diff --git a/.github/workflows/integration-main.yml b/.github/workflows/integration-main.yml index 6f8d8366..c69cb539 100644 --- a/.github/workflows/integration-main.yml +++ b/.github/workflows/integration-main.yml @@ -162,6 +162,8 @@ jobs: # and container start-up between lanes. A hosted runner adds cold image pulls (about 5 GB # uncompressed across the PostgreSQL, MongoDB, Kafka, nginx, httpbin and Toxiproxy images) and a # cold Gradle cache; expect 25 to 40 minutes (an estimate, not a measured hosted run). The 240-minute timeout is a ceiling for a hung container, not a budget. + # Since 2026-11-08 messagingCertificationTest and the messaging starter's integrationTest run in the + # messaging-library repository, not here; the measurement above predates that. integration-check: runs-on: ubuntu-latest timeout-minutes: 240 diff --git a/.github/workflows/messaging-certification.yml b/.github/workflows/messaging-certification.yml deleted file mode 100644 index 726ba8e8..00000000 --- a/.github/workflows/messaging-certification.yml +++ /dev/null @@ -1,51 +0,0 @@ -# The messaging platform's broker certification lane. -# -# Separate from ci-quality-gates.yml because it needs a container runtime and several minutes of it. -# The lane deliberately carries no Docker guard: every other container suite in the messaging tree -# skips with a stated reason when Docker is absent, and a certification lane that skipped would -# report success for a broker nobody started — which is the exact claim the evidence exists to rule -# out. -# -# The job runs the evidence gate rather than the lane, and the gate depends on the lane. What it -# proves is not only that the scenarios pass but that the committed manifest -# (messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl) is what this -# run produced, so "certified against a live broker" cannot be restored by editing a file. -name: messaging-certification - -on: - pull_request: - paths: - - "src/platforms/messaging/**" - - ".github/workflows/messaging-certification.yml" - # Every Gradle job here installs its toolchain through this composite action, so a change to - # it changes what this gate runs. - - ".github/actions/setup-gradle-java/action.yml" - schedule: - - cron: "41 4 * * 3" - workflow_dispatch: - -permissions: - contents: read - -env: - # Reuse would hand one scenario the broker another scenario had already faulted. - TESTCONTAINERS_REUSE_ENABLE: "false" - -jobs: - broker-certification: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Certify the Kafka adapter against a real broker - working-directory: src - # GITHUB_SHA is read by the lane and written into every evidence line, because "certified" - # is a claim about one source tree. - run: ./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence --stacktrace - - name: Publish the certification evidence - if: always() - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2 - with: - name: messaging-broker-certification-evidence - path: src/platforms/messaging/messaging-kafka/build/messaging-certification/ - if-no-files-found: warn diff --git a/scripts/check-repo-layout.py b/scripts/check-repo-layout.py index 8c6e3412..28759245 100755 --- a/scripts/check-repo-layout.py +++ b/scripts/check-repo-layout.py @@ -58,7 +58,8 @@ ROOT_ALLOWED = { "testcontainers.properties.example": "Testcontainers 로컬 설정 예", } -# src/ 바로 아래: 계층·조립 leaf, 들여온 제품 묶음, Gradle 루트 표준 폴더와 빌드 파일. +# src/ 바로 아래: 계층·조립 leaf, Gradle 루트 표준 폴더와 빌드 파일. 계층이 아닌 라이브러리(메시징·gRPC)는 +# 2026-11-08에 별도 repo로 나갔다(docs/work/reference/related-repos.md). 그 자리(platforms)는 다시 두지 않는다. SRC_ALLOWED = { # 계층과 조립 "domain-core": "계층", @@ -70,8 +71,6 @@ SRC_ALLOWED = { "adapter": "계층(adapter leaf 묶음)", "composition": "조립(Clean Architecture의 Main)", "app-bootstrap": "조립 루트", - # 들여온 제품 - "platforms": "들여온 제품(messaging). gRPC는 2026-11-08 별도 repo grpc-library로", # Gradle 루트 표준 "build-logic": "빌드 규칙(included build)", "config": "빌드 전체 도구 설정(registry, checkstyle, spotbugs, 테스트 이미지)", diff --git a/scripts/hooks/hooks.py b/scripts/hooks/hooks.py index 1d32adb3..5110ecb4 100644 --- a/scripts/hooks/hooks.py +++ b/scripts/hooks/hooks.py @@ -46,14 +46,17 @@ SKIPPED = "포맷을 건너뛰었다" # --- N1: the layer rules the gates hold, checked on the imports of one edited main source -------------- # Mirrors DomainPurityArchitectureTest (DOMAIN_IS_PURE, DOMAIN_HAS_NO_LOGGER). +# dev.cakit.: the owner's libraries (messaging-library, grpc-library) are reached only through adapters; +# a layer row may not list one in allowed_libraries (registry library_groups, build-logic ArchitecturePlugin). DOMAIN_FORBIDDEN = ("org.springframework.", "jakarta.persistence.", "javax.persistence.", "jakarta.servlet.", "org.hibernate.", "lombok.", "org.slf4j.", "java.util.logging.", "ch.qos.logback.", - "org.apache.logging.log4j.") + "org.apache.logging.log4j.", "dev.cakit.") # Mirrors VerifyApplicationCoreDependencyPurityTask and the application-core AGENTS.md forbidden list. APPLICATION_FORBIDDEN = ("org.springframework.", "org.slf4j.", "ch.qos.logback.", "org.apache.logging.log4j.", "io.micrometer.", "java.util.logging.", "jakarta.persistence.", "javax.persistence.", - "lombok.") -SHARED_FORBIDDEN = ("org.springframework.", "jakarta.", "javax.persistence.", "org.hibernate.", "lombok.") + "lombok.", "dev.cakit.") +SHARED_FORBIDDEN = ("org.springframework.", "jakarta.", "javax.persistence.", "org.hibernate.", "lombok.", + "dev.cakit.") # HARD-STOP 2: an inbound adapter reaching the store. INBOUND_FORBIDDEN = ("org.springframework.data.repository.", "org.springframework.data.jpa.", "org.springframework.data.mongodb.repository.", "jakarta.persistence.", "javax.persistence.") diff --git a/scripts/tests/test_hooks.py b/scripts/tests/test_hooks.py index b5c1fa08..3808a3ea 100644 --- a/scripts/tests/test_hooks.py +++ b/scripts/tests/test_hooks.py @@ -252,6 +252,11 @@ class BoundaryNudgeTest(RepositoryTestCase): self.assertIn("HARD-STOP 1 의심: `domain-core`가 `org.springframework.stereotype.Component`", text) self.assertIn("architectureCheck", text) + def test_an_owned_library_in_the_application_is_flagged(self) -> None: + text = self.nudge("src/application-core", "dev/caskeleton/application/order/Notify.java", + "import dev.cakit.messaging.api.MessageEnvelope;") + self.assertIn("`application-core`가 `dev.cakit.messaging.api.MessageEnvelope`", text) + def test_an_inbound_dto_in_the_application_is_hard_stop_3(self) -> None: text = self.nudge("src/application-core", "dev/caskeleton/application/order/Place.java", "import dev.caskeleton.adapter.inbound.web.order.OrderRequest;") diff --git a/src/adapter/inbound/messaging/build.gradle b/src/adapter/inbound/messaging/build.gradle index 1c67b2ba..9eab0546 100644 --- a/src/adapter/inbound/messaging/build.gradle +++ b/src/adapter/inbound/messaging/build.gradle @@ -3,7 +3,7 @@ plugins { id 'ca.spring-config' } -// The application's consume side of the vendored messaging platform (review 2026-11-01 06-08), +// The application's consume side of the messaging library (dev.cakit.messaging, review 2026-11-01 06-08), // selected by one line in a composition root: // // runtimeOnly project(':adapter:inbound:messaging') @@ -29,14 +29,14 @@ base { dependencies { implementation project(':application-core') - implementation project(':messaging:messaging-core-api') - implementation project(':messaging:messaging-reliability') - implementation project(':messaging:messaging-reliability-api') - // JdbcInboxRepository only. The leaf also exports the platform admin journal (api - // messaging-admin), which this leaf has no use for and no registered edge to; the starter puts it - // on the runtime classpath anyway. - implementation(project(':messaging:messaging-reliability-jdbc-postgresql')) { - exclude group: 'dev.caskeleton', module: 'messaging-admin' + implementation libs.messaging.core.api + implementation libs.messaging.reliability + implementation libs.messaging.reliability.api + // JdbcInboxRepository only. The module also exports the library's admin journal (api + // messaging-admin), which this leaf has no use for and no registered library edge to; the starter + // puts it on the runtime classpath anyway. + implementation(libs.messaging.reliability.jdbc.postgresql) { + exclude group: 'dev.cakit.messaging', module: 'messaging-admin' } implementation 'org.springframework.boot:spring-boot-autoconfigure' @@ -76,7 +76,7 @@ configurations { // Test-only edges of the redelivery lane: the publishing side as a composition root selects it // (the Kafka capability, the outbox relay, the JPA outbox over PostgreSQL), the port owner's event -// fixture, and the platform's MessageContracts holder the consumer registers its payload type in. +// fixture, and the library's MessageContracts holder the consumer registers its payload type in. // Test edges are outside the registry gate. dependencies { integrationTestImplementation project(':adapter:outbound:messaging-kafka') @@ -84,8 +84,8 @@ dependencies { integrationTestImplementation project(':adapter:outbound:persistence-jpa') integrationTestImplementation project(':application-core') integrationTestImplementation testFixtures(project(':application-core')) - integrationTestImplementation project(':messaging:messaging-core-api') - integrationTestImplementation project(':messaging:messaging-spring-boot-starter') + integrationTestImplementation libs.messaging.core.api + integrationTestImplementation libs.messaging.spring.boot.starter integrationTestImplementation 'org.springframework:spring-jdbc' integrationTestImplementation 'org.flywaydb:flyway-core' integrationTestImplementation 'org.apache.kafka:kafka-clients' diff --git a/src/adapter/inbound/messaging/gradle.lockfile b/src/adapter/inbound/messaging/gradle.lockfile index cca8539f..feedb258 100644 --- a/src/adapter/inbound/messaging/gradle.lockfile +++ b/src/adapter/inbound/messaging/gradle.lockfile @@ -50,6 +50,20 @@ 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,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-admin:1.0.0=integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-core-api:1.0.0=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-kafka:1.0.0=integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-observability:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-policy:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-reliability-api:1.0.0=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-reliability-jdbc-postgresql:1.0.0=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-reliability:1.0.0=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-runtime-core:1.0.0=integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-schema-json:1.0.0=integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-security:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-spring-boot-starter-kafka:1.0.0=integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-spring-boot-starter:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-transport-spi:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath info.picocli:picocli:4.7.7=checkstyle 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 diff --git a/src/adapter/inbound/messaging/src/integrationTest/java/dev/caskeleton/adapter/inbound/messaging/InboxRedeliveryIntegrationTest.java b/src/adapter/inbound/messaging/src/integrationTest/java/dev/caskeleton/adapter/inbound/messaging/InboxRedeliveryIntegrationTest.java index 527e3fe0..4f4d911b 100644 --- a/src/adapter/inbound/messaging/src/integrationTest/java/dev/caskeleton/adapter/inbound/messaging/InboxRedeliveryIntegrationTest.java +++ b/src/adapter/inbound/messaging/src/integrationTest/java/dev/caskeleton/adapter/inbound/messaging/InboxRedeliveryIntegrationTest.java @@ -3,6 +3,13 @@ package dev.caskeleton.adapter.inbound.messaging; import static org.assertj.core.api.Assertions.assertThat; import static org.awaitility.Awaitility.await; +import dev.cakit.messaging.api.MessageId; +import dev.cakit.messaging.api.MessageType; +import dev.cakit.messaging.api.delivery.HandleResult; +import dev.cakit.messaging.api.delivery.MessageDelivery; +import dev.cakit.messaging.api.delivery.MessageHandler; +import dev.cakit.messaging.api.destination.DestinationName; +import dev.cakit.messaging.api.destination.MessageDestination; import dev.caskeleton.application.capability.Idempotency; import dev.caskeleton.application.capability.RepositoryAccess; import dev.caskeleton.application.capability.UseCaseCapability; @@ -13,13 +20,6 @@ import dev.caskeleton.application.security.SystemCaller; import dev.caskeleton.application.security.SystemInvoked; import dev.caskeleton.application.transaction.TransactionMode; import dev.caskeleton.application.transaction.TransactionPort; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.delivery.HandleResult; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; import java.time.Clock; import java.time.Duration; import java.time.Instant; diff --git a/src/adapter/inbound/messaging/src/main/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfiguration.java b/src/adapter/inbound/messaging/src/main/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfiguration.java index b45d514a..52dae485 100644 --- a/src/adapter/inbound/messaging/src/main/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfiguration.java +++ b/src/adapter/inbound/messaging/src/main/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfiguration.java @@ -1,9 +1,9 @@ package dev.caskeleton.adapter.inbound.messaging; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -import dev.caskeleton.messaging.inbox.IdempotentConsumer; -import dev.caskeleton.messaging.inbox.JdbcInboxRepository; -import dev.caskeleton.messaging.reliability.InboxRepository; +import dev.cakit.messaging.api.delivery.MessageHandler; +import dev.cakit.messaging.inbox.IdempotentConsumer; +import dev.cakit.messaging.inbox.JdbcInboxRepository; +import dev.cakit.messaging.reliability.InboxRepository; import javax.sql.DataSource; import org.springframework.boot.autoconfigure.AutoConfiguration; import org.springframework.boot.autoconfigure.condition.ConditionalOnBean; @@ -43,7 +43,7 @@ import org.springframework.transaction.support.TransactionTemplate; "org.springframework.boot.hibernate.autoconfigure.HibernateJpaAutoConfiguration", "org.springframework.boot.jdbc.autoconfigure.DataSourceTransactionManagerAutoConfiguration" }, - beforeName = "dev.caskeleton.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration") + beforeName = "dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration") @ConditionalOnBean({MessageHandler.class, DataSource.class, PlatformTransactionManager.class}) public class MessagingInboxAutoConfiguration { diff --git a/src/adapter/inbound/messaging/src/test/java/dev/cakit/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java b/src/adapter/inbound/messaging/src/test/java/dev/cakit/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java new file mode 100644 index 00000000..f34ded1b --- /dev/null +++ b/src/adapter/inbound/messaging/src/test/java/dev/cakit/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java @@ -0,0 +1,31 @@ +package dev.cakit.messaging.autoconfigure; + +import dev.cakit.messaging.reliability.InboxRepository; +import org.springframework.boot.autoconfigure.AutoConfiguration; +import org.springframework.boot.autoconfigure.AutoConfigureOrder; +import org.springframework.boot.autoconfigure.condition.ConditionalOnBean; +import org.springframework.context.annotation.Bean; +import org.springframework.core.Ordered; + +/** + * Test stand-in with the exact name of the messaging library's root auto-configuration. + * + *

The library builds its inbox consumer only from an {@link InboxRepository} the application + * provides, so the application's {@code MessagingInboxAutoConfiguration} must run first ({@code + * beforeName}). This stand-in asks to run first itself ({@code HIGHEST_PRECEDENCE}) and records, as + * a bean, whether it saw the repository: it does only if the constraint put the inbox configuration + * ahead of it. The starter is not on this leaf's test classpath, so the name does not collide. + */ +@AutoConfiguration +@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE) +public class MessagingPlatformRootAutoConfiguration { + + /** Present only when the application's inbox repository existed as this root was processed. */ + public record SawTheInbox() {} + + @Bean + @ConditionalOnBean(InboxRepository.class) + SawTheInbox sawTheInbox() { + return new SawTheInbox(); + } +} diff --git a/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfigurationTest.java b/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfigurationTest.java index e5b7ed4f..2a144703 100644 --- a/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfigurationTest.java +++ b/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfigurationTest.java @@ -3,25 +3,25 @@ package dev.caskeleton.adapter.inbound.messaging; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.catchThrowable; -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.DeliveryContext; -import dev.caskeleton.messaging.api.delivery.DeliveryMetadata; -import dev.caskeleton.messaging.api.delivery.HandleResult; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.inbox.IdempotentConsumer; -import dev.caskeleton.messaging.inbox.InboxMessageHandler; -import dev.caskeleton.messaging.inbox.JdbcInboxRepository; -import dev.caskeleton.messaging.reliability.InboxRepository; +import dev.cakit.messaging.api.ContentType; +import dev.cakit.messaging.api.MessageEnvelope; +import dev.cakit.messaging.api.MessageId; +import dev.cakit.messaging.api.MessageType; +import dev.cakit.messaging.api.ProducerId; +import dev.cakit.messaging.api.SchemaVersion; +import dev.cakit.messaging.api.TraceContext; +import dev.cakit.messaging.api.delivery.DeliveryContext; +import dev.cakit.messaging.api.delivery.DeliveryMetadata; +import dev.cakit.messaging.api.delivery.HandleResult; +import dev.cakit.messaging.api.delivery.MessageDelivery; +import dev.cakit.messaging.api.delivery.MessageHandler; +import dev.cakit.messaging.api.destination.DestinationName; +import dev.cakit.messaging.api.destination.MessageDestination; +import dev.cakit.messaging.api.header.MessageHeaders; +import dev.cakit.messaging.inbox.IdempotentConsumer; +import dev.cakit.messaging.inbox.InboxMessageHandler; +import dev.cakit.messaging.inbox.JdbcInboxRepository; +import dev.cakit.messaging.reliability.InboxRepository; import java.sql.SQLException; import java.time.Instant; import java.util.ArrayList; @@ -73,6 +73,26 @@ class MessagingInboxAutoConfigurationTest { }); } + @Test + @DisplayName("inbox 조립은 라이브러리 root보다 먼저 돌아 root의 bean 조건이 inbox를 본다") + void theInboxIsAssembledBeforeTheLibraryRootThatNeedsIt() { + // given: a root stand-in that asks to run first and records whether it saw the inbox. + ApplicationContextRunner assembled = + runner.withConfiguration( + AutoConfigurations.of( + dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration.class)); + + // when & then + assembled + .withBean(MessageHandler.class, () -> exampleHandler(new ArrayList<>())) + .run( + context -> + assertThat(context) + .hasSingleBean( + dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration + .SawTheInbox.class)); + } + @Test @DisplayName("소비할 handler가 없으면 inbox를 조립하지 않는다") void withoutAHandlerNothingIsAssembled() { diff --git a/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/SystemInvokedConsumePathTest.java b/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/SystemInvokedConsumePathTest.java index 040d33fd..c684e249 100644 --- a/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/SystemInvokedConsumePathTest.java +++ b/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/SystemInvokedConsumePathTest.java @@ -2,6 +2,24 @@ package dev.caskeleton.adapter.inbound.messaging; import static org.assertj.core.api.Assertions.assertThat; +import dev.cakit.messaging.api.ContentType; +import dev.cakit.messaging.api.MessageEnvelope; +import dev.cakit.messaging.api.MessageId; +import dev.cakit.messaging.api.MessageType; +import dev.cakit.messaging.api.ProducerId; +import dev.cakit.messaging.api.SchemaVersion; +import dev.cakit.messaging.api.TraceContext; +import dev.cakit.messaging.api.delivery.DeliveryContext; +import dev.cakit.messaging.api.delivery.DeliveryMetadata; +import dev.cakit.messaging.api.delivery.HandleResult; +import dev.cakit.messaging.api.delivery.MessageDelivery; +import dev.cakit.messaging.api.delivery.MessageHandler; +import dev.cakit.messaging.api.destination.DestinationName; +import dev.cakit.messaging.api.destination.MessageDestination; +import dev.cakit.messaging.api.header.MessageHeaders; +import dev.cakit.messaging.inbox.IdempotentConsumer; +import dev.cakit.messaging.inbox.InboxMessageHandler; +import dev.cakit.messaging.reliability.InboxRepository; import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException; import dev.caskeleton.application.capability.Idempotency; import dev.caskeleton.application.capability.RepositoryAccess; @@ -12,24 +30,6 @@ import dev.caskeleton.application.transaction.TransactionMode; import dev.caskeleton.application.transaction.TransactionPort; import dev.caskeleton.application.transaction.testkit.DirectTransactionPort; import dev.caskeleton.composition.runtime.authorization.PermissionEnforcementConfig; -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.DeliveryContext; -import dev.caskeleton.messaging.api.delivery.DeliveryMetadata; -import dev.caskeleton.messaging.api.delivery.HandleResult; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.inbox.IdempotentConsumer; -import dev.caskeleton.messaging.inbox.InboxMessageHandler; -import dev.caskeleton.messaging.reliability.InboxRepository; import java.time.Instant; import java.util.ArrayList; import java.util.LinkedHashSet; diff --git a/src/adapter/outbound/messaging-kafka/build.gradle b/src/adapter/outbound/messaging-kafka/build.gradle index e80caa39..7d643c35 100644 --- a/src/adapter/outbound/messaging-kafka/build.gradle +++ b/src/adapter/outbound/messaging-kafka/build.gradle @@ -7,16 +7,18 @@ plugins { // // runtimeOnly project(':adapter:outbound:messaging-kafka') // -// That line brings the broker-neutral application bridge (adapter:outbound:messaging), the vendored -// messaging platform with its Kafka transport, and the capability's settings +// That line brings the broker-neutral application bridge (adapter:outbound:messaging), the messaging +// library (dev.cakit.messaging, messaging-library repo) with its Kafka transport, and the capability's settings // (config/module-defaults/messaging.yml). Deleting it removes all of them. The leaf has no code of // its own: it is the selection, not an adapter. Its one test boots the capability the way an // application gets it. -// Every project shares the group dev.caskeleton, and the vendored transport is also named -// messaging-kafka (:messaging:messaging-kafka). Same group and name is the same module to Gradle, -// which silently substituted this project for the vendored one wherever both were reachable, so the -// platform's Kafka transport classes went missing at runtime. A group of its own keeps them apart. +// Every project shares the group dev.caskeleton. The messaging library's Kafka transport used to be +// a project here too, also named messaging-kafka (:messaging:messaging-kafka), and same group and +// name is the same module to Gradle: it silently substituted this project for the transport wherever +// both were reachable, so the Kafka transport classes went missing at runtime. The library is now +// dev.cakit.messaging:messaging-kafka (messaging-library repo); a group of its own still keeps this +// project apart from :adapter:outbound:messaging and from any project a service adds. group = 'dev.caskeleton.adapter' // And a jar file name of its own: a Boot jar stores libraries in BOOT-INF/lib/ by file name, so the // two messaging-kafka-.jar collided and an application selecting this leaf could not be @@ -45,12 +47,12 @@ dependencies { // canonical events through the platform's EncodedMessagePublisher, which the Kafka starter // provides. runtimeOnly project(':adapter:outbound:messaging') - runtimeOnly project(':messaging:messaging-spring-boot-starter-kafka') + runtimeOnly libs.messaging.spring.boot.starter.kafka // The activation test boots the whole capability and names the ports it must produce. testImplementation project(':adapter:outbound:messaging') testImplementation project(':application-core') - testImplementation project(':messaging:messaging-core-api') + testImplementation libs.messaging.core.api } // Test-only edges of the relay lane: the application relay as the composition root selects it, the diff --git a/src/adapter/outbound/messaging-kafka/gradle.lockfile b/src/adapter/outbound/messaging-kafka/gradle.lockfile index 0c37615d..1f6840c1 100644 --- a/src/adapter/outbound/messaging-kafka/gradle.lockfile +++ b/src/adapter/outbound/messaging-kafka/gradle.lockfile @@ -45,6 +45,20 @@ 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=integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-admin:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-core-api:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-kafka:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-observability:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-policy:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-reliability-api:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-reliability-jdbc-postgresql:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-reliability:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-runtime-core:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-schema-json:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-security:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-spring-boot-starter-kafka:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-spring-boot-starter:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-transport-spi:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath info.picocli:picocli:4.7.7=checkstyle 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 diff --git a/src/adapter/outbound/messaging-kafka/src/integrationTest/java/dev/caskeleton/adapter/outbound/messaging/kafka/relay/ApplicationRelayKafkaIntegrationTest.java b/src/adapter/outbound/messaging-kafka/src/integrationTest/java/dev/caskeleton/adapter/outbound/messaging/kafka/relay/ApplicationRelayKafkaIntegrationTest.java index 2957e18d..d6ee97a3 100644 --- a/src/adapter/outbound/messaging-kafka/src/integrationTest/java/dev/caskeleton/adapter/outbound/messaging/kafka/relay/ApplicationRelayKafkaIntegrationTest.java +++ b/src/adapter/outbound/messaging-kafka/src/integrationTest/java/dev/caskeleton/adapter/outbound/messaging/kafka/relay/ApplicationRelayKafkaIntegrationTest.java @@ -3,6 +3,7 @@ package dev.caskeleton.adapter.outbound.messaging.kafka.relay; import static org.assertj.core.api.Assertions.assertThat; import static org.awaitility.Awaitility.await; +import dev.cakit.messaging.api.MessageId; import dev.caskeleton.application.messaging.event.ValidatedIntegrationEvent; import dev.caskeleton.application.outbox.OutboxAppendPort; import dev.caskeleton.application.outbox.OutboxCompletion; @@ -14,7 +15,6 @@ import dev.caskeleton.application.outbox.testkit.InMemoryOutboxStore; import dev.caskeleton.application.outbox.testkit.OutboxEvents; import dev.caskeleton.application.transaction.TransactionPort; import dev.caskeleton.application.transaction.testkit.DirectTransactionPort; -import dev.caskeleton.messaging.api.MessageId; import java.time.Clock; import java.time.Duration; import java.time.Instant; diff --git a/src/adapter/outbound/messaging-kafka/src/test/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaCapabilityActivationTest.java b/src/adapter/outbound/messaging-kafka/src/test/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaCapabilityActivationTest.java index 0f7b5ae5..27adeec1 100644 --- a/src/adapter/outbound/messaging-kafka/src/test/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaCapabilityActivationTest.java +++ b/src/adapter/outbound/messaging-kafka/src/test/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaCapabilityActivationTest.java @@ -3,10 +3,10 @@ package dev.caskeleton.adapter.outbound.messaging.kafka; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.catchThrowable; +import dev.cakit.messaging.schema.EncodedMessagePublisher; import dev.caskeleton.adapter.outbound.messaging.outbox.OutboxMessagePublishAdapter; import dev.caskeleton.application.messaging.event.IntegrationEventPublishPort; import dev.caskeleton.application.outbox.OutboxMessagePublishPort; -import dev.caskeleton.messaging.schema.EncodedMessagePublisher; import java.util.Arrays; import java.util.List; import org.junit.jupiter.api.Test; @@ -69,7 +69,7 @@ class KafkaCapabilityActivationTest { .map(Class::getName) .filter( name -> - name.startsWith("dev.caskeleton.messaging.") + name.startsWith("dev.cakit.messaging.") || name.startsWith("dev.caskeleton.adapter.outbound.messaging.") || name.startsWith("org.apache.kafka."))) .isEmpty(); diff --git a/src/adapter/outbound/messaging/build.gradle b/src/adapter/outbound/messaging/build.gradle index 6267abee..f9d6c2dc 100644 --- a/src/adapter/outbound/messaging/build.gradle +++ b/src/adapter/outbound/messaging/build.gradle @@ -7,7 +7,7 @@ dependencies { implementation project(':application-core') implementation project(':shared-contract') implementation project(':adapter:outbound:support') - implementation project(':messaging:messaging-core-api') + implementation libs.messaging.core.api implementation 'org.springframework.boot:spring-boot-autoconfigure' implementation 'org.springframework.boot:spring-boot-starter-json' diff --git a/src/adapter/outbound/messaging/gradle.lockfile b/src/adapter/outbound/messaging/gradle.lockfile index ea2f1c52..c4d9d140 100644 --- a/src/adapter/outbound/messaging/gradle.lockfile +++ b/src/adapter/outbound/messaging/gradle.lockfile @@ -37,6 +37,7 @@ 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 +dev.cakit.messaging:messaging-core-api:1.0.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath 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 diff --git a/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingBridgeRootAutoConfiguration.java b/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingBridgeRootAutoConfiguration.java index 863fe1ad..7f7bf1d7 100644 --- a/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingBridgeRootAutoConfiguration.java +++ b/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingBridgeRootAutoConfiguration.java @@ -1,10 +1,10 @@ package dev.caskeleton.adapter.outbound.messaging.autoconfigure; +import dev.cakit.messaging.schema.EncodedMessagePublisher; import dev.caskeleton.adapter.outbound.messaging.MessagingConfig; import dev.caskeleton.adapter.outbound.messaging.MessagingSettings; import dev.caskeleton.adapter.outbound.messaging.platformbridge.PlatformIntegrationEventPublishAdapter; import dev.caskeleton.application.messaging.event.IntegrationEventPublishPort; -import dev.caskeleton.messaging.schema.EncodedMessagePublisher; import org.springframework.boot.autoconfigure.AutoConfiguration; import org.springframework.boot.autoconfigure.condition.ConditionOutcome; import org.springframework.boot.autoconfigure.condition.ConditionalOnBean; @@ -23,14 +23,15 @@ import org.springframework.util.StringUtils; * The one place that decides whether this application publishes to a broker. * *

The broker itself is a build-time choice: a transport leaf (messaging-kafka) brings the - * vendored platform and its transport, and this root stays broker-neutral — it binds the - * application's ports to the platform's pre-encoded publish path and nothing else. + * messaging library ({@code dev.cakit.messaging}) and its transport, and this root stays + * broker-neutral — it binds the application's ports to the library's pre-encoded publish path and + * nothing else. * *

On when present: an application that selected a messaging leaf wants messaging, so a missing * {@code app.messaging.enabled} means on and only an explicit {@code false} turns it off. */ @AutoConfiguration( - afterName = "dev.caskeleton.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration") + afterName = "dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration") @ConditionalOnProperty( prefix = "app.messaging", name = "enabled", @@ -58,8 +59,9 @@ public class MessagingBridgeRootAutoConfiguration { * identity environment-dependent. * *

{@code @ConditionalOnBean} only sees the publisher because this class is ordered after the - * platform root: auto-configurations are sorted by name first, and {@code - * dev.caskeleton.adapter…} sorts before {@code dev.caskeleton.messaging…}. + * library's root ({@code afterName} above). Auto-configurations are sorted by name first, and + * {@code dev.cakit.messaging…} happens to sort before {@code dev.caskeleton.adapter…}; the + * constraint, not the name, is what keeps the order through any rename. */ @Bean @ConditionalOnBean(EncodedMessagePublisher.class) diff --git a/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter.java b/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter.java index 8b81e8ae..bc4b7f52 100644 --- a/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter.java +++ b/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter.java @@ -1,32 +1,32 @@ package dev.caskeleton.adapter.outbound.messaging.platformbridge; +import dev.cakit.messaging.api.CausationId; +import dev.cakit.messaging.api.ContentType; +import dev.cakit.messaging.api.CorrelationId; +import dev.cakit.messaging.api.MessageEnvelope; +import dev.cakit.messaging.api.MessageId; +import dev.cakit.messaging.api.MessageType; +import dev.cakit.messaging.api.ProducerId; +import dev.cakit.messaging.api.SchemaVersion; +import dev.cakit.messaging.api.TenantContext; +import dev.cakit.messaging.api.TraceContext; +import dev.cakit.messaging.api.destination.DestinationName; +import dev.cakit.messaging.api.destination.MessageDestination; +import dev.cakit.messaging.api.error.FailureDescriptor; +import dev.cakit.messaging.api.header.HeaderName; +import dev.cakit.messaging.api.header.HeaderValue; +import dev.cakit.messaging.api.header.MessageHeaders; +import dev.cakit.messaging.api.publish.PublishCompletion; +import dev.cakit.messaging.api.publish.PublishOptions; +import dev.cakit.messaging.api.publish.PublishResult; +import dev.cakit.messaging.api.publish.TransmissionEvidence; +import dev.cakit.messaging.schema.EncodedMessage; +import dev.cakit.messaging.schema.EncodedMessagePublisher; +import dev.cakit.messaging.schema.SchemaReference; import dev.caskeleton.application.messaging.event.IntegrationEventPublishPort; import dev.caskeleton.application.messaging.event.ValidatedIntegrationEvent; import dev.caskeleton.application.outbox.OutboxPublishAttempt; import dev.caskeleton.application.outbox.OutboxPublishOutcome; -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.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -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.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.schema.EncodedMessage; -import dev.caskeleton.messaging.schema.EncodedMessagePublisher; -import dev.caskeleton.messaging.schema.SchemaReference; import java.time.Duration; import java.util.LinkedHashMap; import java.util.Map; diff --git a/src/adapter/outbound/messaging/src/test/java/dev/cakit/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java b/src/adapter/outbound/messaging/src/test/java/dev/cakit/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java new file mode 100644 index 00000000..528c0206 --- /dev/null +++ b/src/adapter/outbound/messaging/src/test/java/dev/cakit/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java @@ -0,0 +1,34 @@ +package dev.cakit.messaging.autoconfigure; + +import dev.cakit.messaging.schema.EncodedMessagePublisher; +import org.springframework.boot.autoconfigure.AutoConfiguration; +import org.springframework.boot.autoconfigure.AutoConfigureOrder; +import org.springframework.context.annotation.Bean; +import org.springframework.core.Ordered; + +/** + * Test stand-in with the exact name of the messaging starter's root auto-configuration. + * + *

The bridge orders itself after that root by name ({@code afterName}). Boot sorts + * auto-configurations alphabetically before applying {@code after} constraints; while the library + * was {@code dev.caskeleton.messaging} the bridge sorted first, so the constraint carried the + * order. Since the package became {@code dev.cakit.messaging} (2026-11-08) the root sorts first by + * name as well, and the constraint is what keeps that true for any rename. A stand-in with the same + * name reproduces the ordering without pulling the starter, and a broker, onto this leaf's test + * classpath. The starter is not on that classpath, so the name does not collide. + * + *

The stand-in asks to run last ({@code LOWEST_PRECEDENCE}), which the real root does not: with + * the name sorting it first, a test without that would pass even if the bridge lost its {@code + * afterName}. Ordered last, the bridge still comes after it only because of the constraint. + */ +@AutoConfiguration +@AutoConfigureOrder(Ordered.LOWEST_PRECEDENCE) +public class MessagingPlatformRootAutoConfiguration { + + @Bean + EncodedMessagePublisher encodedMessagePublisher() { + return (destination, message, options) -> { + throw new AssertionError("publisher is not invoked while wiring the bridge"); + }; + } +} diff --git a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingPlatformBridgeAutoConfigurationTest.java b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingPlatformBridgeAutoConfigurationTest.java index bc50447a..7b96ba7a 100644 --- a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingPlatformBridgeAutoConfigurationTest.java +++ b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingPlatformBridgeAutoConfigurationTest.java @@ -2,10 +2,10 @@ package dev.caskeleton.adapter.outbound.messaging.autoconfigure; import static org.assertj.core.api.Assertions.assertThat; +import dev.cakit.messaging.schema.EncodedMessagePublisher; import dev.caskeleton.adapter.outbound.messaging.MessagingSettings; import dev.caskeleton.application.messaging.event.IntegrationEventPublishPort; import dev.caskeleton.application.outbox.OutboxMessagePublishPort; -import dev.caskeleton.messaging.schema.EncodedMessagePublisher; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; import org.junit.jupiter.params.ParameterizedTest; @@ -48,8 +48,7 @@ class MessagingPlatformBridgeAutoConfigurationTest { .withConfiguration( AutoConfigurations.of( MessagingBridgeRootAutoConfiguration.class, - dev.caskeleton.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration - .class)) + dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration.class)) .withPropertyValues( "app.messaging.enabled=true", "app.messaging.producer-id=portfolio-service"); diff --git a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapterTest.java b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapterTest.java index d1564cd4..72e6bef7 100644 --- a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapterTest.java +++ b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapterTest.java @@ -3,6 +3,20 @@ package dev.caskeleton.adapter.outbound.messaging.platformbridge; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.catchThrowable; +import dev.cakit.messaging.api.ContentType; +import dev.cakit.messaging.api.MessageEnvelope; +import dev.cakit.messaging.api.destination.MessageDestination; +import dev.cakit.messaging.api.error.FailureCategory; +import dev.cakit.messaging.api.error.FailureDescriptor; +import dev.cakit.messaging.api.publish.ConfirmationLevel; +import dev.cakit.messaging.api.publish.PublishCompletion; +import dev.cakit.messaging.api.publish.PublishEvidence; +import dev.cakit.messaging.api.publish.PublishOptions; +import dev.cakit.messaging.api.publish.PublishResult; +import dev.cakit.messaging.api.publish.RoutingOutcome; +import dev.cakit.messaging.api.publish.TransmissionEvidence; +import dev.cakit.messaging.schema.EncodedMessage; +import dev.cakit.messaging.schema.EncodedMessagePublisher; import dev.caskeleton.application.messaging.contract.ContractId; import dev.caskeleton.application.messaging.contract.LogicalDestinationId; import dev.caskeleton.application.messaging.event.AggregateIdentity; @@ -14,20 +28,6 @@ import dev.caskeleton.application.messaging.event.testkit.BrokerAnswer; import dev.caskeleton.application.messaging.event.testkit.IntegrationEventPublishContract; import dev.caskeleton.application.outbox.OutboxPublishAttempt; import dev.caskeleton.application.outbox.OutboxPublishOutcome; -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageEnvelope; -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.publish.ConfirmationLevel; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -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.api.publish.TransmissionEvidence; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.schema.EncodedMessagePublisher; import dev.caskeleton.shared.digest.Sha256; import java.nio.charset.StandardCharsets; import java.time.Duration; diff --git a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java deleted file mode 100644 index 0dbab8d7..00000000 --- a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java +++ /dev/null @@ -1,25 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.schema.EncodedMessagePublisher; -import org.springframework.boot.autoconfigure.AutoConfiguration; -import org.springframework.context.annotation.Bean; - -/** - * Test stand-in with the exact name of the messaging starter's root auto-configuration. - * - *

The bridge orders itself after that root by name, and Boot sorts auto-configurations - * alphabetically before applying {@code after} constraints — {@code dev.caskeleton.adapter…} comes - * before {@code dev.caskeleton.messaging…}. A stand-in with the same name reproduces that ordering - * without pulling the starter, and a broker, onto this leaf's test classpath. The starter is not on - * that classpath, so the name does not collide. - */ -@AutoConfiguration -public class MessagingPlatformRootAutoConfiguration { - - @Bean - EncodedMessagePublisher encodedMessagePublisher() { - return (destination, message, options) -> { - throw new AssertionError("publisher is not invoked while wiring the bridge"); - }; - } -} diff --git a/src/adapter/outbound/persistence-jpa/build.gradle b/src/adapter/outbound/persistence-jpa/build.gradle index 6ef7a85e..a79b738a 100644 --- a/src/adapter/outbound/persistence-jpa/build.gradle +++ b/src/adapter/outbound/persistence-jpa/build.gradle @@ -296,6 +296,34 @@ tasks.named('postgresqlSecurityBaselineIntegrationTest') { // Which JPA lanes block a release is declared by release/release-registry.json (jpaReleaseQualification below). // This leaf declares the lanes and how each runs; it does not own release orchestration. +// The messaging library's migration tree (db/migration/messaging in messaging-reliability-jdbc-postgresql, +// messaging-library repo) runs against the database this leaf owns once the consume side is +// selected, through the same Flyway history, so AppliedMigrationImmutabilityTest and +// MigrationLockWaitTest hold it to the same rules as this leaf's own trees (MigrationTrees). While +// the library lived in this repository they read its source folder by path; now the tree is a +// resource of the published jar, at the version the catalog names (`messagingLibrary`), which is +// exactly what a service applies. Only the jar, not its dependencies, and only to read: the module is +// on no classpath of this leaf, so no test context sees the library. +configurations { + messagingMigrations { + canBeConsumed = false + canBeResolved = true + transitive = false + description = 'The messaging library jar whose db/migration tree the migration tests read.' + } +} +dependencies { + messagingMigrations libs.messaging.reliability.jdbc.postgresql +} +def messagingMigrationDirectory = layout.buildDirectory.dir('library-migrations/messaging-reliability-jdbc-postgresql') +def messagingMigrationTree = tasks.register('messagingMigrationTree', Sync) { + description = 'Extracts the messaging library\'s db/migration tree for the migration tests.' + from({ zipTree(configurations.messagingMigrations.singleFile) }) { + include 'db/migration/**' + } + into messagingMigrationDirectory +} + // The unit lane reads three files that are not Java sources: the release registry and its two // renderings. Without declaring them, Gradle calls the lane up-to-date after a registry demotion or // a workflow edit — so the drift check that exists to catch exactly that edit never runs on it. @@ -321,9 +349,14 @@ tasks.named('test') { .withPropertyName('notificationMigrations') inputs.dir(file('../persistence-fileserver/src/main/resources/db/migration')) .withPropertyName('fileserverMigrations') - // ...and the messaging platform's tree, whose inbox range the consume side applies here. - inputs.dir(file('../../../platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration')) + // ...and the messaging library's tree, whose inbox range the consume side applies here: read out of + // the jar this build receives (messagingMigrationTree above), not from the library's sources. + dependsOn messagingMigrationTree + inputs.dir(messagingMigrationDirectory) + .withPathSensitivity(PathSensitivity.RELATIVE) .withPropertyName('messagingMigrations') + systemProperty 'persistence.migration.messagingTree', + messagingMigrationDirectory.get().dir('db/migration').asFile.absolutePath } // verifyJpaApiSurface — every public type this leaf exposes is a committed decision. diff --git a/src/adapter/outbound/persistence-jpa/gradle.lockfile b/src/adapter/outbound/persistence-jpa/gradle.lockfile index ace35092..f0c903d9 100644 --- a/src/adapter/outbound/persistence-jpa/gradle.lockfile +++ b/src/adapter/outbound/persistence-jpa/gradle.lockfile @@ -54,6 +54,7 @@ commons-collections:commons-collections:3.2.2=checkstyle commons-io:commons-io:2.20.0=jpaPlatformPerformanceTestCompileClasspath,jpaPlatformPerformanceTestRuntimeClasspath,postgresqlIntegrationTestCompileClasspath,postgresqlIntegrationTestRuntimeClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath commons-io:commons-io:2.21.0=spotbugs commons-logging:commons-logging:1.3.6=compileClasspath,jpaPlatformPerformanceTestCompileClasspath,jpaPlatformPerformanceTestRuntimeClasspath,postgresqlIntegrationTestCompileClasspath,postgresqlIntegrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-reliability-jdbc-postgresql:1.0.0=messagingMigrations eu.rekawek.toxiproxy:toxiproxy-java:2.1.11=jpaPlatformPerformanceTestRuntimeClasspath,postgresqlIntegrationTestCompileClasspath,postgresqlIntegrationTestRuntimeClasspath,testRuntimeClasspath eu.rekawek.toxiproxy:toxiproxy-java:2.1.7=testFixturesCompileClasspath,testFixturesRuntimeClasspath info.picocli:picocli:4.7.7=checkstyle diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/MigrationTrees.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/MigrationTrees.java index 018843b1..2c817a73 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/MigrationTrees.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/MigrationTrees.java @@ -28,22 +28,37 @@ final class MigrationTrees { * adapter:outbound:persistence-fileserver}) runs against the same database through the same * Flyway history and was never pinned at all; it is checked here on the same terms. * - *

The messaging platform's tree ({@code db/migration/messaging}, in {@code - * messaging-reliability-jdbc-postgresql}) runs against it too once the consume side is selected: - * {@code adapter:inbound:messaging} applies its inbox range (V11xx). The tree is pinned whole — - * the platform outbox range ships from the same location to deployments that use it, and an - * edited migration stops those just the same. + *

The messaging library's tree ({@code db/migration/messaging}, in {@code + * dev.cakit.messaging:messaging-reliability-jdbc-postgresql}) runs against it too once the + * consume side is selected: {@code adapter:inbound:messaging} applies its inbox range (V11xx). + * The tree is pinned whole — the library's outbox range ships from the same location to + * deployments that use it, and an edited migration stops those just the same. The library lives + * in its own repository (messaging-library) since 2026-11-08, so the tree is read out of the jar + * this build receives: the build extracts it ({@code messagingMigrationTree}) and names the + * folder in {@value #MESSAGING_TREE_PROPERTY}. */ static final List ROOTS = List.of( Path.of("src/main/resources/db/migration"), Path.of("../persistence-notification/src/main/resources/db/migration"), Path.of("../persistence-fileserver/src/main/resources/db/migration"), - Path.of( - "../../../platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration")); + messagingTree()); + + static final String MESSAGING_TREE_PROPERTY = "persistence.migration.messagingTree"; private MigrationTrees() {} + private static Path messagingTree() { + String tree = System.getProperty(MESSAGING_TREE_PROPERTY); + if (tree == null || tree.isBlank()) { + throw new IllegalStateException( + MESSAGING_TREE_PROPERTY + + " is not set: run the migration tests through Gradle (`test`), which extracts the" + + " messaging library's db/migration tree from its jar and names the folder here."); + } + return Path.of(tree); + } + /** * Every versioned migration ({@link VersionedMigrationFiles}, the definition the sample's check * uses too), keyed by its path below its tree ({@code postgresql/V22__...sql}), the key {@code diff --git a/src/app-bootstrap/build.gradle b/src/app-bootstrap/build.gradle index 05cb31fb..fab01964 100644 --- a/src/app-bootstrap/build.gradle +++ b/src/app-bootstrap/build.gradle @@ -180,6 +180,9 @@ dependencies { integrationTestImplementation project(':composition:service-runtime') capabilityProjects.each { architectureTestRuntimeOnly project(it) } + // ArchitectureViolationFixtureTest's consumer fixtures implement and inject the messaging library's + // MessageHandler, the type a service's handler really has. Test edge, outside the registry gate. + architectureTestImplementation libs.messaging.core.api // The capability integration lane selects Fileserver and object storage together, as a service // would, and turns off whichever one a test is not about. diff --git a/src/app-bootstrap/gradle.lockfile b/src/app-bootstrap/gradle.lockfile index ed13bdfc..bf5a8111 100644 --- a/src/app-bootstrap/gradle.lockfile +++ b/src/app-bootstrap/gradle.lockfile @@ -72,6 +72,20 @@ commons-collections:commons-collections:3.2.2=checkstyle commons-io:commons-io:2.20.0=architectureTestCompileClasspath,architectureTestRuntimeClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,systemTestCompileClasspath,testCompileClasspath,testRuntimeClasspath commons-io:commons-io:2.21.0=spotbugs commons-logging:commons-logging:1.3.6=architectureTestCompileClasspath,architectureTestRuntimeClasspath,bootRunH2Classpath,compileClasspath,conditionalTransportBuildContractTestRuntimeClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,productionRuntimeClasspath,qualificationRuntimeClasspath,runtimeClasspath,systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-admin:1.0.0=architectureTestRuntimeClasspath,qualificationRuntimeClasspath +dev.cakit.messaging:messaging-core-api:1.0.0=architectureTestCompileClasspath,architectureTestRuntimeClasspath,qualificationRuntimeClasspath +dev.cakit.messaging:messaging-kafka:1.0.0=architectureTestRuntimeClasspath,qualificationRuntimeClasspath +dev.cakit.messaging:messaging-observability:1.0.0=architectureTestRuntimeClasspath,qualificationRuntimeClasspath +dev.cakit.messaging:messaging-policy:1.0.0=architectureTestRuntimeClasspath,qualificationRuntimeClasspath +dev.cakit.messaging:messaging-reliability-api:1.0.0=architectureTestRuntimeClasspath,qualificationRuntimeClasspath +dev.cakit.messaging:messaging-reliability-jdbc-postgresql:1.0.0=architectureTestRuntimeClasspath,qualificationRuntimeClasspath +dev.cakit.messaging:messaging-reliability:1.0.0=architectureTestRuntimeClasspath,qualificationRuntimeClasspath +dev.cakit.messaging:messaging-runtime-core:1.0.0=architectureTestRuntimeClasspath,qualificationRuntimeClasspath +dev.cakit.messaging:messaging-schema-json:1.0.0=architectureTestRuntimeClasspath,qualificationRuntimeClasspath +dev.cakit.messaging:messaging-security:1.0.0=architectureTestRuntimeClasspath,qualificationRuntimeClasspath +dev.cakit.messaging:messaging-spring-boot-starter-kafka:1.0.0=architectureTestRuntimeClasspath,qualificationRuntimeClasspath +dev.cakit.messaging:messaging-spring-boot-starter:1.0.0=architectureTestRuntimeClasspath,qualificationRuntimeClasspath +dev.cakit.messaging:messaging-transport-spi:1.0.0=architectureTestRuntimeClasspath,qualificationRuntimeClasspath eu.rekawek.toxiproxy:toxiproxy-java:2.1.11=architectureTestRuntimeClasspath,integrationTestRuntimeClasspath,testRuntimeClasspath info.picocli:picocli:4.7.7=checkstyle io.github.cdimascio:dotenv-java:3.0.0=architectureTestRuntimeClasspath,bootRunH2Classpath,integrationTestRuntimeClasspath,productionRuntimeClasspath,qualificationRuntimeClasspath,runtimeClasspath,systemTestRuntimeClasspath,testRuntimeClasspath diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java index 41c77504..77ae0111 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java @@ -92,7 +92,7 @@ class ApplicationBoundaryArchitectureTest { .resideInAPackage("..application..") .should() .dependOnClassesThat() - .resideInAnyPackage("dev.caskeleton.messaging..") + .resideInAnyPackage("dev.cakit.messaging..") .because( "APPLICATION_DOES_NOT_DEPEND_ON_THE_MESSAGING_PLATFORM: the application owns its " + "publish port and outbox model; a bridge adapter translates, and the two " @@ -711,8 +711,19 @@ class ApplicationBoundaryArchitectureTest { } }; - /** The packages this code base owns: a type here is one the dependency rules can follow. */ - private static final String PROJECT_PACKAGE_PREFIX = "dev.caskeleton."; + /** + * The packages this code base owns: a type here is one the dependency rules can follow. The + * owner's libraries published from their own repositories ({@code dev.cakit}, the registry's + * {@code library_groups}) count too: a message handler implements the messaging library's {@code + * MessageHandler}, which was a type of this repository until 2026-11-08 and is still the owner's, + * not one any class may depend on for its own reasons. + */ + private static final List PROJECT_PACKAGE_PREFIXES = + List.of("dev.caskeleton.", "dev.cakit."); + + private static boolean isProjectType(String className) { + return PROJECT_PACKAGE_PREFIXES.stream().anyMatch(className::startsWith); + } /** * Every type a system caller can be handed as: the caller itself, and each project class or @@ -730,7 +741,7 @@ class ApplicationBoundaryArchitectureTest { if (ARE_SYSTEM_CALLERS.test(candidate)) { return true; } - return candidate.getName().startsWith(PROJECT_PACKAGE_PREFIX) + return isProjectType(candidate.getName()) && candidate.getAllSubclasses().stream().anyMatch(ARE_SYSTEM_CALLERS); } }; @@ -836,14 +847,15 @@ class ApplicationBoundaryArchitectureTest { * looks like every other user of the interface, and a rule that refused the dependency would * refuse them all (review 2026-11-04 RR4-01-01). The job therefore has none: the scheduler calls * its {@code @Scheduled} method, a configuration that registers it with a task scheduler passes - * {@code job::run}, and a message handler implements the platform's {@code MessageHandler}, which - * is a project type. Anonymous and local classes are exempt: no bean has their type, and a - * function a system caller hands out from inside itself is reached only through the caller. - * Exceptions are exempt too: nothing is handed one as a bean. A record or an enum keeps the - * supertypes the language gives it — {@code Record}; {@code Enum} and what {@code Enum} - * implements — which are no more a type it is injected as than {@code Object} is, so a handler's - * parsed-message record, its outcome enum, or a handler written as a record pass, while a record - * that also implements {@code Runnable} does not (review 2026-11-05 RR6-01-03). + * {@code job::run}, and a message handler implements the messaging library's {@code + * MessageHandler}, which is a project type (see {@link #PROJECT_PACKAGE_PREFIXES}). Anonymous and + * local classes are exempt: no bean has their type, and a function a system caller hands out from + * inside itself is reached only through the caller. Exceptions are exempt too: nothing is handed + * one as a bean. A record or an enum keeps the supertypes the language gives it — {@code Record}; + * {@code Enum} and what {@code Enum} implements — which are no more a type it is injected as than + * {@code Object} is, so a handler's parsed-message record, its outcome enum, or a handler written + * as a record pass, while a record that also implements {@code Runnable} does not (review + * 2026-11-05 RR6-01-03). */ @ArchTest static final ArchRule SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES = @@ -858,7 +870,8 @@ class ApplicationBoundaryArchitectureTest { .should(haveNoSupertypeOutsideTheProject()) .as( "SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES: a @SystemCaller extends and implements " - + "only project types (dev.caskeleton..), so every type it can be injected as is " + + "only project types (dev.caskeleton.., and the owner's libraries dev.cakit..), " + + "so every type it can be injected as is " + "one USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS follows. Instead of Runnable or " + "ApplicationRunner, use a @Scheduled method, an @EventListener, or pass job::run " + "where the job is registered (manual 07 「시스템이 부르는 쓰기」). A record or " @@ -873,14 +886,13 @@ class ApplicationBoundaryArchitectureTest { Set foreign = new TreeSet<>(); for (JavaClass superclass : item.getAllRawSuperclasses()) { if (!superclass.isEquivalentTo(Object.class) - && !superclass.getName().startsWith(PROJECT_PACKAGE_PREFIX) + && !isProjectType(superclass.getName()) && !languageGiven.contains(superclass.getName())) { foreign.add(superclass.getName()); } } for (JavaClass type : item.getAllRawInterfaces()) { - if (!type.getName().startsWith(PROJECT_PACKAGE_PREFIX) - && !languageGiven.contains(type.getName())) { + if (!isProjectType(type.getName()) && !languageGiven.contains(type.getName())) { foreign.add(type.getName()); } } diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ArchitectureViolationFixtureTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ArchitectureViolationFixtureTest.java index c6e997b5..5f9be05a 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ArchitectureViolationFixtureTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ArchitectureViolationFixtureTest.java @@ -7,6 +7,7 @@ import com.tngtech.archunit.core.domain.JavaClasses; import com.tngtech.archunit.core.importer.ClassFileImporter; import com.tngtech.archunit.lang.EvaluationResult; import dev.caskeleton.application.architecture.violations.ApplicationDiagnosticFrameworkViolation; +import dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.messaging.LibraryMessageHandlerSystemCallerFixture; import dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.messaging.RecordSystemCallerFixture; import dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.messaging.SystemCallerHandlerFixture; import dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.messaging.SystemCallerHandlerRegistrationFixture; @@ -35,6 +36,7 @@ import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.schedule import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler.ScheduledWorkFixture; import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler.SystemCallerWithNestedEndpointFixture; import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler.SystemJobLauncherFixture; +import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller.MessageHandlerInjectingControllerFixture; import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller.SystemCallerControllerFixture; import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller.SystemCallerInvokingControllerFixture; import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller.SystemCallerRelayingControllerFixture; @@ -277,6 +279,23 @@ class ArchitectureViolationFixtureTest { InterfaceExposedSystemJobFixture.class, SystemInvokedFixtureUseCase.class); + // The consumer as a service writes it: a handler implementing the messaging library's + // MessageHandler, and a "replay now" endpoint handed it by that interface. The library left this + // repository on 2026-11-08 (package dev.cakit.messaging); its handler interface must stay a type + // the + // two rules follow. + private static final JavaClasses LIBRARY_MESSAGE_HANDLER_FIXTURE_ONLY = + new ClassFileImporter() + .importClasses( + LibraryMessageHandlerSystemCallerFixture.class, SystemInvokedFixtureUseCase.class); + + private static final JavaClasses CONTROLLER_HANDED_A_LIBRARY_MESSAGE_HANDLER_FIXTURE_ONLY = + new ClassFileImporter() + .importClasses( + MessageHandlerInjectingControllerFixture.class, + LibraryMessageHandlerSystemCallerFixture.class, + SystemInvokedFixtureUseCase.class); + // A system caller that is a Runnable — directly, or through a project interface that extends it. // Nothing tells an endpoint injecting a Runnable from any other use of it, so the job may not be // one. @@ -590,6 +609,35 @@ class ArchitectureViolationFixtureTest { .contains(RunNowJobFixture.class.getName())); } + @Test + @DisplayName("메시징 라이브러리의 MessageHandler를 구현한 system caller는 프로젝트 밖 supertype이 아니다") + void aSystemCallerImplementingTheLibrarysMessageHandlerHasOnlyOwnedSupertypes() { + // when + EvaluationResult result = + ApplicationBoundaryArchitectureTest.SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES.evaluate( + LIBRARY_MESSAGE_HANDLER_FIXTURE_ONLY); + + // then + assertThat(result.getFailureReport().getDetails()).isEmpty(); + } + + @Test + @DisplayName("system caller를 라이브러리 MessageHandler로 주입받는 controller는 잡힌다") + void aControllerHandedASystemCallerAsTheLibrarysMessageHandlerIsCaught() { + // when + EvaluationResult result = + ApplicationBoundaryArchitectureTest.USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS.evaluate( + CONTROLLER_HANDED_A_LIBRARY_MESSAGE_HANDLER_FIXTURE_ONLY); + + // then + assertThat(result.getFailureReport().getDetails()) + .anySatisfy( + detail -> + assertThat(detail) + .contains(MessageHandlerInjectingControllerFixture.class.getName()) + .contains("dev.cakit.messaging.api.delivery.MessageHandler")); + } + @Test void aSystemCallerThatIsARunnableIsCaught() { // when diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/RuntimeProfileAccessArchitectureTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/RuntimeProfileAccessArchitectureTest.java index f47f24c6..9c6430f9 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/RuntimeProfileAccessArchitectureTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/RuntimeProfileAccessArchitectureTest.java @@ -19,8 +19,9 @@ import org.springframework.core.env.Environment; * include support), and fileserver and the HTTP client read the profiles once inside their own * capability guard, so those four are listed by name. A new reader anywhere else — a leaf that * starts judging "is this production" from raw profile names on its own — fails here and has to - * either go through the snapshot or be added to this list on purpose. The vendored {@code - * messaging} platform and the {@code sample} fixture are outside this application's policy. + * either go through the snapshot or be added to this list on purpose. The {@code sample} fixture is + * outside this application's policy. The messaging library (package {@code dev.cakit.messaging}, + * its own repository since 2026-11-08) is outside the analysed packages altogether. */ @AnalyzeClasses(packages = "dev.caskeleton", importOptions = ProductionClassImportOption.class) class RuntimeProfileAccessArchitectureTest { @@ -45,8 +46,6 @@ class RuntimeProfileAccessArchitectureTest { noClasses() .that() .resideInAPackage("dev.caskeleton..") - .and() - .resideOutsideOfPackage("dev.caskeleton.messaging..") .and(DescribedPredicate.not(A_NAMED_PROFILE_READER)) .should() .callMethod(Environment.class, "getActiveProfiles") diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/adapter/inbound/messaging/LibraryMessageHandlerSystemCallerFixture.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/adapter/inbound/messaging/LibraryMessageHandlerSystemCallerFixture.java new file mode 100644 index 00000000..0a1d7c5e --- /dev/null +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/adapter/inbound/messaging/LibraryMessageHandlerSystemCallerFixture.java @@ -0,0 +1,32 @@ +package dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.messaging; + +import dev.cakit.messaging.api.delivery.HandleResult; +import dev.cakit.messaging.api.delivery.MessageDelivery; +import dev.cakit.messaging.api.delivery.MessageHandler; +import dev.cakit.messaging.api.destination.MessageDestination; +import dev.caskeleton.application.security.SystemCaller; +import dev.caskeleton.bootstrap.architecture.violations.application.SystemInvokedFixtureUseCase; +import java.util.concurrent.CompletionStage; + +/** + * The consumer manual 09 teaches, with the supertype it really has: the messaging library's {@code + * MessageHandler} ({@code dev.cakit.messaging}, its own repository since 2026-11-08). The library + * is the owner's, so its handler interface is a type the system-caller rules follow, as it was + * while the library lived in this repository. + */ +@SystemCaller(reason = "fixture: the broker consumer calls it for each delivery") +public final class LibraryMessageHandlerSystemCallerFixture implements MessageHandler { + + private final SystemInvokedFixtureUseCase useCase = new SystemInvokedFixtureUseCase(); + + @Override + public MessageDestination destination() { + throw new UnsupportedOperationException("fixture: never registered"); + } + + @Override + public CompletionStage handle(MessageDelivery delivery) { + useCase.handle(); + throw new UnsupportedOperationException("fixture: never delivered to"); + } +} diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/adapter/inbound/web/controller/MessageHandlerInjectingControllerFixture.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/adapter/inbound/web/controller/MessageHandlerInjectingControllerFixture.java new file mode 100644 index 00000000..aa5f7448 --- /dev/null +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/adapter/inbound/web/controller/MessageHandlerInjectingControllerFixture.java @@ -0,0 +1,25 @@ +package dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller; + +import dev.cakit.messaging.api.delivery.MessageHandler; +import org.springframework.web.bind.annotation.PostMapping; +import org.springframework.web.bind.annotation.RestController; + +/** + * Negative fixture for {@code USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS}: a "replay now" endpoint + * handed a system-caller handler as the messaging library's {@code MessageHandler}. It names + * neither the handler class nor the {@code SystemInvoked} use case the handler runs. + */ +@RestController +public class MessageHandlerInjectingControllerFixture { + + private final MessageHandler handler; + + public MessageHandlerInjectingControllerFixture(MessageHandler handler) { + this.handler = handler; + } + + @PostMapping("/fixture/replay-now") + public void replayNow() { + handler.handle(null); + } +} diff --git a/src/app-bootstrap/src/systemTest/java/dev/caskeleton/bootstrap/composition/DefaultCompositionBootTest.java b/src/app-bootstrap/src/systemTest/java/dev/caskeleton/bootstrap/composition/DefaultCompositionBootTest.java index 2668a777..094605f6 100644 --- a/src/app-bootstrap/src/systemTest/java/dev/caskeleton/bootstrap/composition/DefaultCompositionBootTest.java +++ b/src/app-bootstrap/src/systemTest/java/dev/caskeleton/bootstrap/composition/DefaultCompositionBootTest.java @@ -36,7 +36,7 @@ class DefaultCompositionBootTest { "dev.caskeleton.adapter.outbound.cache.redis", "dev.caskeleton.adapter.outbound.redis", "dev.caskeleton.adapter.outbound.messaging", - "dev.caskeleton.messaging", + "dev.cakit.messaging", "dev.caskeleton.adapter.outbound.httpclient", "dev.caskeleton.adapter.outbound.objectstorage", "dev.caskeleton.adapter.outbound.notification", diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ConfigurationNamespaceContractTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ConfigurationNamespaceContractTest.java index 208be2f3..13276a07 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ConfigurationNamespaceContractTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ConfigurationNamespaceContractTest.java @@ -32,10 +32,11 @@ import org.junit.jupiter.api.Test; * environment such as {@code app.httpclient.clients[N].*}, through relaxed binding — and under one * {@code app} root the two routes spell the same name. * - *

Vendored platforms keep their own subtree under the same root: {@code app.messaging.*} belongs - * to the {@code messaging:*} platform, and gRPC's settings sit in {@code app.grpc.server} and - * {@code app.grpc.platform} side by side, never one at the shared parent — two strict binders on a - * shared parent would each refuse the other's keys. + *

The libraries published from their own repositories keep their own subtree under the same + * root: {@code app.messaging.*} belongs to the messaging library ({@code dev.cakit.messaging}), and + * gRPC's settings sit in {@code app.grpc.server} and {@code app.grpc.platform} side by side, never + * one at the shared parent — two strict binders on a shared parent would each refuse the other's + * keys. */ class ConfigurationNamespaceContractTest { diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingAuthorityContractTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingAuthorityContractTest.java index 2554634a..083eaf93 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingAuthorityContractTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingAuthorityContractTest.java @@ -19,9 +19,15 @@ import org.junit.jupiter.api.Test; * *

Two types declare {@code @ConfigurationProperties} on that prefix: {@code MessagingSettings} * in the outbound adapter, which owns {@code producer-id}, and {@code MessagingSettings} in the - * starter, which owns everything else, {@code broker} included. Spring binds both without complaint - * — each takes the fields it declares — so the split is invisible at runtime and shows up only as - * two places to look, neither of which validates the other's view. + * messaging library's starter, which owns everything else, {@code broker} included. Spring binds + * both without complaint — each takes the fields it declares — so the split is invisible at runtime + * and shows up only as two places to look, neither of which validates the other's view. + * + *

Since the library moved to its own repository (messaging-library, 2026-11-08) each repository + * counts its own half: this test holds this repository to exactly one owner, and the library's + * {@code MessagingSettingsOwnerContractTest} holds the library to exactly one. A source scan cannot + * see across the two repositories any more, and the "two in total" of before is the sum of the two + * checks (design-docs {@code repo-structure/05-library-repos.md} 4.2절, 16절 H7). * *

This test does not assert the split away. Collapsing it means the adapter stops selecting a * broker and becomes a port bridge over the platform's publish contract, which it can only do once @@ -51,13 +57,13 @@ class MessagingAuthorityContractTest { Pattern.compile("String PREFIX\\s*=\\s*\"app\\.messaging\""); private static final List MESSAGING_SOURCES = - loadSources("adapter/outbound/messaging", "platforms/messaging", "app-bootstrap"); + loadSources("adapter/outbound/messaging", "adapter/inbound/messaging", "app-bootstrap"); private static final List CORE_SOURCES = loadSources("application-core", "domain-core"); @Test - @DisplayName("the owners of app.messaging are the two this wave knows about, and no more") - void theSettingsOwnersAreTheKnownTwo() { + @DisplayName("이 repo에서 app.messaging의 주인은 outbound adapter의 MessagingSettings 하나다") + void theAdapterSettingsAreThisRepositorysOnlyOwner() { List owners = MESSAGING_SOURCES.stream() .filter( @@ -68,11 +74,14 @@ class MessagingAuthorityContractTest { .map(ProductionSource::path) .toList(); - assertThat(owners.stream().map(path -> path.getFileName().toString()).sorted()) + assertThat(owners.stream().map(path -> repositoryRoot().relativize(path).toString())) .as( - "a third owner of one namespace is how a setting comes to mean different things to " - + "different halves of the same application; the two below are collapsed by Task C3") - .containsExactly("MessagingSettings.java", "MessagingSettings.java"); + "a second owner in this repository is how a setting comes to mean different things to " + + "different halves of the same application; the library's starter is the other " + + "owner, collapsed by Task C3") + .containsExactly( + "src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/" + + "MessagingSettings.java"); } @Test diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingPublicSurfaceContractTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingPublicSurfaceContractTest.java deleted file mode 100644 index c42097b8..00000000 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingPublicSurfaceContractTest.java +++ /dev/null @@ -1,386 +0,0 @@ -package dev.caskeleton.bootstrap.contract.messaging; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.bootstrap.contract.support.RepositoryContractResources; -import java.io.IOException; -import java.io.UncheckedIOException; -import java.nio.file.Files; -import java.nio.file.Path; -import java.util.ArrayList; -import java.util.LinkedHashMap; -import java.util.List; -import java.util.Map; -import java.util.Set; -import java.util.TreeSet; -import java.util.regex.Matcher; -import java.util.regex.Pattern; -import java.util.stream.Stream; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Tag; -import org.junit.jupiter.api.Test; - -/** - * Whether an adopter can compile against the messaging types this platform hands them. - * - *

A Gradle {@code implementation} dependency is not encapsulation. It removes the library from - * the consumer's compile classpath, but it does not remove the library's types from this module's - * public signatures. When both are true the artifact ships an API nobody can call: the method is - * there, the javadoc describes it, and the caller cannot name its parameter or its return type - * without guessing which library and which version to add to their own build. Every case below was - * exactly that — a Kafka {@code Producer}, a Spring AMQP {@code Message}, a CloudEvent, a - * Micrometer {@code MeterRegistry}, an Avro {@code Schema}, a protobuf {@code Parser}, a Reactor - * {@code Mono}. - * - *

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

The libraries checked are the ones an adopter would otherwise have to reverse-engineer into - * their own build: broker clients, codec libraries, the metrics registry, the reactive facade. - * Spring Framework and Spring Boot are deliberately out of scope. They appear only inside the - * composition boundary, where the container constructs the types rather than an adopter naming - * them, and that boundary is where the family policy already confines them. - */ -@Tag("repository-contract") -class MessagingPublicSurfaceContractTest { - - /** - * Package prefix to the Gradle coordinate that supplies it. - * - *

Prefixes rather than exact packages, because a library's types are spread across its own - * sub-packages and a consumer needs the whole artifact either way. - */ - private static final Map VENDOR_LIBRARIES = - Map.of( - "org.apache.kafka", "org.apache.kafka:kafka-clients", - "org.springframework.amqp", "org.springframework.amqp:spring-rabbit", - "org.apache.avro", "org.apache.avro:avro", - "com.google.protobuf", "com.google.protobuf:protobuf-java", - "tools.jackson", "tools.jackson.core:jackson-databind", - "io.cloudevents", "io.cloudevents:cloudevents-api", - "io.micrometer", "io.micrometer:micrometer-core", - "reactor", "io.projectreactor:reactor-core", - "io.nats", "io.nats:jnats", - "org.apache.pulsar", "org.apache.pulsar:pulsar-client"); - - private static final Pattern IMPORT = Pattern.compile("(?m)^import\\s+(?:static\\s+)?([^;]+);"); - - private static final Pattern TYPE_KEYWORD = - Pattern.compile("\\b(class|interface|record|enum)\\b"); - - @Test - @DisplayName( - "a vendor type in a public signature has its library declared api, not implementation") - void vendorTypesInPublicSignaturesAreDeclaredApi() { - List hidden = new ArrayList<>(); - - for (Path leaf : messagingLeaves()) { - String buildScript = read(leaf.resolve("build.gradle")); - for (String coordinate : exposedLibraries(leaf)) { - if (!declaresAsApi(buildScript, coordinate)) { - hidden.add(leaf.getFileName() + " exposes " + coordinate + " without declaring it api"); - } - } - } - - assertThat(hidden) - .as( - "each of these ships a public signature naming a type the consumer's compile classpath " - + "does not contain; the method exists and cannot be called") - .isEmpty(); - } - - @Test - @DisplayName("the scan reaches the leaves it claims to check") - void theScanIsNotVacuous() { - List leaves = messagingLeaves(); - - assertThat(leaves) - .as("a scan that found no leaf would report every violation as absent") - .hasSizeGreaterThan(15); - assertThat( - exposedLibraries( - leaves.stream().filter(isNamed("messaging-kafka")).findFirst().orElseThrow())) - .as("the Kafka adapter's publish seam takes a Producer, so this is a positive control") - .contains("org.apache.kafka:kafka-clients"); - assertThat( - exposedLibraries( - leaves.stream().filter(isNamed("messaging-schema-json")).findFirst().orElseThrow())) - .as("the JSON codec keeps its ObjectMapper private, so nothing is required of its build") - .isEmpty(); - } - - @Test - @DisplayName("an adopter of the starter does not compile against either broker client") - void neitherBrokerSdkReachesAnAdoptersCompileClasspath() { - Map> exported = new LinkedHashMap<>(); - for (Path leaf : messagingLeaves()) { - exported.put( - leaf.getFileName().toString(), apiDependenciesOf(read(leaf.resolve("build.gradle")))); - } - - Set reachable = apiClosure("messaging-spring-boot-starter", exported); - - assertThat(reachable) - .as( - "an empty closure would satisfy the assertion below without proving anything; the " - + "metrics registry is exported on purpose (the reactive facade was deleted, S7-#9c)") - .contains("io.micrometer:micrometer-core"); - assertThat(reachable) - .as( - "both adapters were exported, so every adopter compiled against two broker SDKs at " - + "once and each adapter's conditional-on-class guard was true whatever the " - + "deployment had chosen") - .doesNotContain("org.apache.kafka:kafka-clients", "org.springframework.amqp:spring-rabbit"); - } - - /** The vendor coordinates this leaf names in a public or protected signature. */ - private static Set exposedLibraries(Path leaf) { - Set exposed = new TreeSet<>(); - for (Path source : productionSources(leaf)) { - String text = read(source); - String declarations = declarationsOnly(text); - for (Map.Entry library : VENDOR_LIBRARIES.entrySet()) { - if (isNamedInDeclarations(text, declarations, library.getKey())) { - exposed.add(library.getValue()); - } - } - } - return exposed; - } - - /** - * Whether a library's types survive into this file's declarations. - * - *

Two ways a type gets named: imported and used by its simple name, or written out in full. - * Both are checked, because the auto-configuration style in this repository uses fully qualified - * names for one-off types rather than adding an import. - */ - private static boolean isNamedInDeclarations(String source, String declarations, String prefix) { - if (declarations.contains(prefix + ".")) { - return true; - } - Matcher imports = IMPORT.matcher(source); - while (imports.find()) { - String imported = imports.group(1).trim(); - if (!imported.startsWith(prefix + ".")) { - continue; - } - String simpleName = imported.substring(imported.lastIndexOf('.') + 1); - if (Pattern.compile("\\b" + Pattern.quote(simpleName) + "\\b").matcher(declarations).find()) { - return true; - } - } - return false; - } - - /** - * Reduces a source file to its declarations: type headers, member signatures, record components. - * - *

Method bodies are dropped, because a vendor type used inside one is an implementation detail - * and is exactly the case that may stay {@code implementation}. Field initialisers are dropped - * for the same reason. Anything a {@code private} modifier reaches is dropped last: a private - * member is not a signature a consumer compiles against. - * - *

A brace walk rather than a parser. It only has to answer "is this text a declaration or a - * body", which brace depth settles, and a parser here would be more machinery than the question - * deserves. - */ - private static String declarationsOnly(String source) { - String text = stripCommentsAndLiterals(source); - StringBuilder kept = new StringBuilder(); - StringBuilder pending = new StringBuilder(); - int depth = 0; - int bodyDepth = -1; - int initializerDepth = -1; - - for (int index = 0; index < text.length(); index++) { - char character = text.charAt(index); - if (character == '{') { - depth++; - if (initializerDepth >= 0) { - continue; - } - if (bodyDepth < 0) { - kept.append(pending).append(';'); - if (!TYPE_KEYWORD.matcher(pending).find() && pending.indexOf("(") >= 0) { - bodyDepth = depth; - } - } - pending.setLength(0); - continue; - } - if (character == '}') { - if (bodyDepth == depth) { - bodyDepth = -1; - } - depth--; - pending.setLength(0); - continue; - } - if (character == ';') { - if (initializerDepth == depth) { - initializerDepth = -1; - } else if (bodyDepth < 0) { - kept.append(pending).append(';'); - } - pending.setLength(0); - continue; - } - if (bodyDepth >= 0 || initializerDepth >= 0) { - continue; - } - if (character == '=' && isAssignment(text, index)) { - kept.append(pending).append(';'); - pending.setLength(0); - initializerDepth = depth; - continue; - } - pending.append(character); - } - - return Stream.of(kept.toString().split(";", -1)) - .filter(fragment -> !fragment.contains("private ")) - .filter(fragment -> !fragment.contains("import ")) - .reduce("", (left, right) -> left + " ; " + right); - } - - /** Distinguishes a field initialiser from {@code ==}, {@code <=}, {@code >=} and {@code !=}. */ - private static boolean isAssignment(String text, int index) { - char before = index == 0 ? ' ' : text.charAt(index - 1); - char after = index + 1 >= text.length() ? ' ' : text.charAt(index + 1); - return before != '=' && before != '<' && before != '>' && before != '!' && after != '='; - } - - private static String stripCommentsAndLiterals(String source) { - return source - .replaceAll("(?s)/\\*.*?\\*/", " ") - .replaceAll("(?m)//.*$", " ") - .replaceAll("\"\"\"(?s).*?\"\"\"", "\"\"") - .replaceAll("\"(\\\\.|[^\"\\\\])*\"", "\"\"") - .replaceAll("'(\\\\.|[^'\\\\])*'", "' '"); - } - - /** The external coordinates a build script exports to its consumers. */ - private static List apiDependenciesOf(String buildScript) { - List exported = new ArrayList<>(); - Matcher external = Pattern.compile("(?m)^\\s*api\\s+'([^']+)'").matcher(buildScript); - while (external.find()) { - String coordinate = external.group(1); - int lastColon = coordinate.lastIndexOf(':'); - boolean versioned = lastColon > 0 && coordinate.indexOf(':') != lastColon; - exported.add(versioned ? coordinate.substring(0, lastColon) : coordinate); - } - // Version-catalog accessors are the same declaration in a different notation. Matching only the - // literal string form would have let `api libs.cloudevents.api` read as "not declared api" — a - // contract reported as broken because the build file was tidied, which is the most expensive - // kind of false positive a gate can produce. - Matcher catalogued = - Pattern.compile("(?m)^\\s*api\\s+(libs\\.[A-Za-z0-9.]+)").matcher(buildScript); - while (catalogued.find()) { - String module = catalogModules().get(catalogued.group(1)); - if (module != null) { - exported.add(module); - } - } - Matcher projects = - Pattern.compile("(?m)^\\s*api\\s+project\\('([^']+)'\\)").matcher(buildScript); - while (projects.find()) { - String path = projects.group(1); - exported.add(path.substring(path.lastIndexOf(':') + 1)); - } - return exported; - } - - /** Everything a consumer of one leaf ends up compiling against. */ - private static Set apiClosure(String leaf, Map> exported) { - Set reachable = new TreeSet<>(); - List pending = new ArrayList<>(exported.getOrDefault(leaf, List.of())); - while (!pending.isEmpty()) { - String next = pending.remove(0); - if (!reachable.add(next)) { - continue; - } - pending.addAll(exported.getOrDefault(next, List.of())); - } - return reachable; - } - - private static boolean declaresAsApi(String buildScript, String coordinate) { - if (Pattern.compile("(?m)^\\s*api\\s+'" + Pattern.quote(coordinate) + "(:[^']*)?'") - .matcher(buildScript) - .find()) { - return true; - } - return apiDependenciesOf(buildScript).contains(coordinate); - } - - /** - * Version-catalog accessor to {@code group:artifact}, read from the catalog itself. - * - *

{@code gradle/libs.versions.toml} declares {@code archunit-junit5 = { module = "..." }} and - * Gradle exposes it as {@code libs.archunit.junit5}; the alias separators become dots. Parsing - * the file rather than hard-coding the mapping keeps this test honest when an alias is renamed — - * a stale table here would silently stop resolving and report the library as unexported. - */ - private static Map catalogModules() { - Map modules = new LinkedHashMap<>(); - Path catalog = repositoryRoot().resolve("src/gradle/libs.versions.toml"); - if (!Files.isRegularFile(catalog)) { - return modules; - } - Matcher entry = - Pattern.compile("(?m)^([A-Za-z0-9_-]+)\\s*=\\s*\\{[^}]*module\\s*=\\s*\"([^\"]+)\"") - .matcher(read(catalog)); - while (entry.find()) { - modules.put("libs." + entry.group(1).replace('-', '.').replace('_', '.'), entry.group(2)); - } - return modules; - } - - private static java.util.function.Predicate isNamed(String leaf) { - return path -> path.getFileName().toString().equals(leaf); - } - - private static List messagingLeaves() { - Path family = repositoryRoot().resolve("src/platforms/messaging"); - try (Stream children = Files.list(family)) { - return children - .filter(Files::isDirectory) - .filter(path -> Files.isRegularFile(path.resolve("build.gradle"))) - .sorted() - .toList(); - } catch (IOException unreadable) { - throw new UncheckedIOException(unreadable); - } - } - - private static List productionSources(Path leaf) { - Path main = leaf.resolve("src/main/java"); - if (!Files.isDirectory(main)) { - return List.of(); - } - try (Stream walk = Files.walk(main)) { - return walk.filter(path -> path.toString().endsWith(".java")).sorted().toList(); - } catch (IOException unreadable) { - throw new UncheckedIOException(unreadable); - } - } - - private static String read(Path path) { - try { - return Files.readString(path); - } catch (IOException unreadable) { - throw new UncheckedIOException(unreadable); - } - } - - private static Path repositoryRoot() { - // Gradle hands the root only to the lanes that declare the repository files as inputs; the - // plain `test` lane gets none, so a test that reads the repository without a lane tag fails - // here instead of going stale behind an up-to-date check (review 2026-11-01 08-03). - return RepositoryContractResources.fromSystemProperty().repositoryRoot(); - } -} diff --git a/src/composition/outbox-relay/build.gradle b/src/composition/outbox-relay/build.gradle index 0b9916bd..396b0b03 100644 --- a/src/composition/outbox-relay/build.gradle +++ b/src/composition/outbox-relay/build.gradle @@ -31,10 +31,10 @@ dependencies { testImplementation 'org.springframework.boot:spring-boot-starter-test' // The shutdown-order test runs the real relay over the port owner's shared fake store. testImplementation testFixtures(project(':application-core')) - // The shutdown-order test holds the relay above the platform's admission phase by the platform's - // own constant (MessagingShutdownLifecycle.PHASE), not a copy of its value. Compile-only and - // not transitive: a compile-time constant is inlined, so the platform is not on the test runtime. - testCompileOnly(project(':messaging:messaging-spring-boot-starter')) { + // The shutdown-order test holds the relay above the messaging library's admission phase by the + // library's own constant (MessagingShutdownLifecycle.PHASE), not a copy of its value. Compile-only + // and not transitive: a compile-time constant is inlined, so the library is not on the test runtime. + testCompileOnly(libs.messaging.spring.boot.starter) { transitive = false } testImplementation 'org.mockito:mockito-core' diff --git a/src/composition/outbox-relay/gradle.lockfile b/src/composition/outbox-relay/gradle.lockfile index d96c361c..8daafcda 100644 --- a/src/composition/outbox-relay/gradle.lockfile +++ b/src/composition/outbox-relay/gradle.lockfile @@ -38,6 +38,7 @@ 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 +dev.cakit.messaging:messaging-spring-boot-starter:1.0.0=testCompileClasspath 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 diff --git a/src/composition/outbox-relay/src/test/java/dev/caskeleton/composition/outbox/OutboxRelayShutdownOrderTest.java b/src/composition/outbox-relay/src/test/java/dev/caskeleton/composition/outbox/OutboxRelayShutdownOrderTest.java index 79b6a96c..10eaa274 100644 --- a/src/composition/outbox-relay/src/test/java/dev/caskeleton/composition/outbox/OutboxRelayShutdownOrderTest.java +++ b/src/composition/outbox-relay/src/test/java/dev/caskeleton/composition/outbox/OutboxRelayShutdownOrderTest.java @@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat; import static org.mockito.Mockito.mock; import static org.mockito.Mockito.verifyNoInteractions; +import dev.cakit.messaging.autoconfigure.MessagingShutdownLifecycle; import dev.caskeleton.application.outbox.ClaimedOutboxEvent; import dev.caskeleton.application.outbox.OutboxCompletion; import dev.caskeleton.application.outbox.OutboxEventStatus; @@ -16,7 +17,6 @@ import dev.caskeleton.application.outbox.testkit.InMemoryOutboxStore; import dev.caskeleton.application.outbox.testkit.OutboxEvents; import dev.caskeleton.application.transaction.TransactionPort; import dev.caskeleton.application.transaction.testkit.DirectTransactionPort; -import dev.caskeleton.messaging.autoconfigure.MessagingShutdownLifecycle; import java.time.Clock; import java.time.Instant; import java.util.List; diff --git a/src/config/architecture/modules.json b/src/config/architecture/modules.json index 56691b3d..20f07310 100644 --- a/src/config/architecture/modules.json +++ b/src/config/architecture/modules.json @@ -1,4 +1,7 @@ { + "library_groups": [ + "dev.cakit" + ], "modules": [ { "id": "domain-core", @@ -173,11 +176,13 @@ "gradle_path": ":adapter:inbound:messaging", "source_path": "src/adapter/inbound/messaging", "allowed_dependencies": [ - "application-core", - "messaging-core-api", - "messaging-reliability", - "messaging-reliability-api", - "messaging-reliability-jdbc-postgresql" + "application-core" + ], + "allowed_libraries": [ + "dev.cakit.messaging:messaging-core-api", + "dev.cakit.messaging:messaging-reliability", + "dev.cakit.messaging:messaging-reliability-api", + "dev.cakit.messaging:messaging-reliability-jdbc-postgresql" ] }, { @@ -188,8 +193,10 @@ "domain-core", "application-core", "shared-contract", - "adapter-outbound-support", - "messaging-core-api" + "adapter-outbound-support" + ], + "allowed_libraries": [ + "dev.cakit.messaging:messaging-core-api" ] }, { @@ -197,8 +204,10 @@ "gradle_path": ":adapter:outbound:messaging-kafka", "source_path": "src/adapter/outbound/messaging-kafka", "allowed_dependencies": [ - "adapter-outbound-messaging", - "messaging-spring-boot-starter-kafka" + "adapter-outbound-messaging" + ], + "allowed_libraries": [ + "dev.cakit.messaging:messaging-spring-boot-starter-kafka" ] }, { @@ -382,192 +391,6 @@ "composition-service-runtime", "composition-durable-operation" ] - }, - { - "id": "messaging-core-api", - "gradle_path": ":messaging:messaging-core-api", - "source_path": "src/platforms/messaging/messaging-core-api", - "allowed_dependencies": [] - }, - { - "id": "messaging-schema-json", - "gradle_path": ":messaging:messaging-schema-json", - "source_path": "src/platforms/messaging/messaging-schema-json", - "allowed_dependencies": [ - "messaging-core-api" - ] - }, - { - "id": "messaging-schema-avro", - "gradle_path": ":messaging:messaging-schema-avro", - "source_path": "src/platforms/messaging/messaging-schema-avro", - "allowed_dependencies": [ - "messaging-core-api" - ] - }, - { - "id": "messaging-schema-protobuf", - "gradle_path": ":messaging:messaging-schema-protobuf", - "source_path": "src/platforms/messaging/messaging-schema-protobuf", - "allowed_dependencies": [ - "messaging-core-api" - ] - }, - { - "id": "messaging-cloudevents", - "gradle_path": ":messaging:messaging-cloudevents", - "source_path": "src/platforms/messaging/messaging-cloudevents", - "allowed_dependencies": [ - "messaging-core-api" - ] - }, - { - "id": "messaging-policy", - "gradle_path": ":messaging:messaging-policy", - "source_path": "src/platforms/messaging/messaging-policy", - "allowed_dependencies": [ - "messaging-core-api" - ] - }, - { - "id": "messaging-transport-spi", - "gradle_path": ":messaging:messaging-transport-spi", - "source_path": "src/platforms/messaging/messaging-transport-spi", - "allowed_dependencies": [ - "messaging-core-api", - "messaging-policy" - ] - }, - { - "id": "messaging-runtime-core", - "gradle_path": ":messaging:messaging-runtime-core", - "source_path": "src/platforms/messaging/messaging-runtime-core", - "allowed_dependencies": [ - "messaging-core-api", - "messaging-policy", - "messaging-transport-spi", - "messaging-security", - "messaging-observability" - ] - }, - { - "id": "messaging-observability", - "gradle_path": ":messaging:messaging-observability", - "source_path": "src/platforms/messaging/messaging-observability", - "allowed_dependencies": [ - "messaging-core-api" - ] - }, - { - "id": "messaging-security", - "gradle_path": ":messaging:messaging-security", - "source_path": "src/platforms/messaging/messaging-security", - "allowed_dependencies": [ - "messaging-core-api" - ] - }, - { - "id": "messaging-kafka", - "gradle_path": ":messaging:messaging-kafka", - "source_path": "src/platforms/messaging/messaging-kafka", - "allowed_dependencies": [ - "messaging-core-api", - "messaging-policy", - "messaging-transport-spi", - "messaging-observability", - "messaging-security", - "messaging-admin" - ] - }, - { - "id": "messaging-reliability-api", - "gradle_path": ":messaging:messaging-reliability-api", - "source_path": "src/platforms/messaging/messaging-reliability-api", - "allowed_dependencies": [ - "messaging-core-api" - ] - }, - { - "id": "messaging-reliability", - "gradle_path": ":messaging:messaging-reliability", - "source_path": "src/platforms/messaging/messaging-reliability", - "allowed_dependencies": [ - "messaging-core-api", - "messaging-reliability-api" - ] - }, - { - "id": "messaging-reliability-jdbc-postgresql", - "gradle_path": ":messaging:messaging-reliability-jdbc-postgresql", - "source_path": "src/platforms/messaging/messaging-reliability-jdbc-postgresql", - "allowed_dependencies": [ - "messaging-core-api", - "messaging-reliability-api", - "messaging-admin", - "messaging-policy" - ] - }, - { - "id": "messaging-claim-check", - "gradle_path": ":messaging:messaging-claim-check", - "source_path": "src/platforms/messaging/messaging-claim-check", - "allowed_dependencies": [ - "messaging-core-api", - "messaging-reliability-api" - ] - }, - { - "id": "messaging-admin", - "gradle_path": ":messaging:messaging-admin", - "source_path": "src/platforms/messaging/messaging-admin", - "allowed_dependencies": [ - "messaging-core-api", - "messaging-observability" - ] - }, - { - "id": "messaging-spring-boot-starter", - "gradle_path": ":messaging:messaging-spring-boot-starter", - "source_path": "src/platforms/messaging/messaging-spring-boot-starter", - "allowed_dependencies": [ - "messaging-admin", - "messaging-core-api", - "messaging-observability", - "messaging-policy", - "messaging-reliability", - "messaging-reliability-api", - "messaging-reliability-jdbc-postgresql", - "messaging-runtime-core", - "messaging-schema-json", - "messaging-security", - "messaging-transport-spi" - ] - }, - { - "id": "messaging-spring-boot-starter-kafka", - "gradle_path": ":messaging:messaging-spring-boot-starter-kafka", - "source_path": "src/platforms/messaging/messaging-spring-boot-starter-kafka", - "allowed_dependencies": [ - "messaging-spring-boot-starter", - "messaging-kafka", - "messaging-admin", - "messaging-core-api", - "messaging-observability", - "messaging-policy", - "messaging-reliability-api", - "messaging-security", - "messaging-transport-spi" - ] - }, - { - "id": "messaging-testkit", - "gradle_path": ":messaging:messaging-testkit", - "source_path": "src/platforms/messaging/messaging-testkit", - "allowed_dependencies": [ - "messaging-core-api", - "messaging-policy", - "messaging-transport-spi" - ] } ] } diff --git a/src/config/spotbugs/exclude-test.xml b/src/config/spotbugs/exclude-test.xml index cd9764ff..943586fb 100644 --- a/src/config/spotbugs/exclude-test.xml +++ b/src/config/spotbugs/exclude-test.xml @@ -99,9 +99,9 @@ - + @@ -109,10 +109,6 @@ - - - - diff --git a/src/config/spotbugs/exclude.xml b/src/config/spotbugs/exclude.xml index eddd3652..99a0419c 100644 --- a/src/config/spotbugs/exclude.xml +++ b/src/config/spotbugs/exclude.xml @@ -69,27 +69,6 @@ - - - - - - - - - - - - - @@ -182,9 +160,6 @@ - - - @@ -220,7 +195,6 @@ - @@ -234,15 +208,6 @@ - - - - - - - @@ -281,7 +246,7 @@ @@ -290,7 +255,6 @@ - @@ -317,15 +281,6 @@ - - - - - - - @@ -353,7 +308,7 @@ @@ -362,7 +317,6 @@ - @@ -398,13 +352,11 @@ + reconfigured after build() (NotificationJsonMapper). --> - diff --git a/src/gradle/libs.versions.toml b/src/gradle/libs.versions.toml index fd868f6d..946e1013 100644 --- a/src/gradle/libs.versions.toml +++ b/src/gradle/libs.versions.toml @@ -10,7 +10,8 @@ # show them side by side, so two artifacts had quietly reached two versions: # # * spock-core 2.3-groovy-4.0 and 2.4-groovy-5.0 -# * protobuf-java 4.29.3 and 4.33.2 +# * protobuf-java 4.29.3 and 4.33.2 (the 4.33.2 user, the messaging library's protobuf codec, +# moved to its own repository on 2026-11-08) # # Both are kept as separate aliases rather than unified. Unifying them here would change what # resolves, in a change whose whole purpose is that it does not; the aliases make the split @@ -35,14 +36,12 @@ approvaltests = "31.0.0" assertj = "3.27.7" archunit = "1.3.0" -avro = "1.12.0" # AWS SDK v2 BOM coordinate. Imported at MODULE scope by adapter:outbound:objectstorage # and app-bootstrap through `ext.awsSdkVersion`, which reads this key. awsSdk = "2.30.0" # Checkstyle *tool* version (the `checkstyle` extension), not a plugin: Checkstyle is a Gradle # built-in plugin with no coordinate of its own. checkstyle = "13.5.0" -cloudevents = "4.0.1" errorprone = "2.49.0" # The Gradle plugin that runs the checker above. Two different artifacts, two different version # lines, deliberately adjacent so a bump of one is visibly not a bump of the other. @@ -72,12 +71,16 @@ junitPlatform = "1.11.3" logstashLogbackEncoder = "8.0" # Pinned (see `pinned-*` below). CVE-2026-106451, fixed in 1.11.4. Brought by kafka-clients (1.10.1). lz4Java = "1.11.4" +# The messaging library (messaging-library repo, Maven group dev.cakit.messaging), one version for +# every module of it: a release publishes all of them together. Raise it by the procedure in +# docs/work/reference/related-repos.md 3절 (lockfiles rewritten, the leaves' lanes, the CHANGELOG). +messagingLibrary = "1.0.0" okhttp = "4.12.0" # Pinned (see `pinned-*` below). CVE-2025-67030, fixed in 3.6.1 on the 3.x line. Brought by the # Checkstyle tool's doxia (3.3.0). plexusUtils = "3.6.1" -protobuf = "4.33.2" -# The third live protobuf version, and the reason this file now shows all three. adapter:inbound:grpc +# The second live protobuf version (the messaging library's schema codec pins the third, 4.33.2, in its +# own repository since 2026-11-08). adapter:inbound:grpc # imports protobuf-bom at this major to match the gRPC BOM above; it is read through # `ext.protobufVersion`. Keep it at the protobuf-java that grpc-protobuf of that BOM declares: the # protobuf-bom import is what resolves, so a lower number here would run gRPC on an older runtime @@ -114,9 +117,6 @@ uuidCreator = "6.1.1" approvaltests = { module = "com.approvaltests:approvaltests", version.ref = "approvaltests" } assertj-core = { module = "org.assertj:assertj-core", version.ref = "assertj" } archunit-junit5 = { module = "com.tngtech.archunit:archunit-junit5", version.ref = "archunit" } -avro = { module = "org.apache.avro:avro", version.ref = "avro" } -cloudevents-api = { module = "io.cloudevents:cloudevents-api", version.ref = "cloudevents" } -cloudevents-core = { module = "io.cloudevents:cloudevents-core", version.ref = "cloudevents" } errorprone-core = { module = "com.google.errorprone:error_prone_core", version.ref = "errorprone" } findsecbugs-plugin = { module = "com.h3xstream.findsecbugs:findsecbugs-plugin", version.ref = "findsecbugs" } jackson-databind-nullable = { module = "org.openapitools:jackson-databind-nullable", version = "0.2.6" } @@ -129,9 +129,16 @@ json-schema-validator = { module = "com.networknt:json-schema-validator", versio junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junitJupiter" } junit-platform-launcher = { module = "org.junit.platform:junit-platform-launcher", version.ref = "junitPlatform" } logstash-logback-encoder = { module = "net.logstash.logback:logstash-logback-encoder", version.ref = "logstashLogbackEncoder" } +# The messaging library's modules the leaves use. Each leaf's registry row lists the ones it may +# reach in `allowed_libraries` (config/architecture/modules.json). +messaging-core-api = { module = "dev.cakit.messaging:messaging-core-api", version.ref = "messagingLibrary" } +messaging-reliability = { module = "dev.cakit.messaging:messaging-reliability", version.ref = "messagingLibrary" } +messaging-reliability-api = { module = "dev.cakit.messaging:messaging-reliability-api", version.ref = "messagingLibrary" } +messaging-reliability-jdbc-postgresql = { module = "dev.cakit.messaging:messaging-reliability-jdbc-postgresql", version.ref = "messagingLibrary" } +messaging-spring-boot-starter = { module = "dev.cakit.messaging:messaging-spring-boot-starter", version.ref = "messagingLibrary" } +messaging-spring-boot-starter-kafka = { module = "dev.cakit.messaging:messaging-spring-boot-starter-kafka", version.ref = "messagingLibrary" } mockwebserver = { module = "com.squareup.okhttp3:mockwebserver", version.ref = "okhttp" } okhttp-tls = { module = "com.squareup.okhttp3:okhttp-tls", version.ref = "okhttp" } -protobuf-java = { module = "com.google.protobuf:protobuf-java", version.ref = "protobuf" } protobuf-java-legacy = { module = "com.google.protobuf:protobuf-java", version.ref = "protobufLegacy" } resilience4j-bulkhead = { module = "io.github.resilience4j:resilience4j-bulkhead", version.ref = "resilience4j" } resilience4j-circuitbreaker = { module = "io.github.resilience4j:resilience4j-circuitbreaker", version.ref = "resilience4j" } diff --git a/src/platforms/messaging/AGENTS.md b/src/platforms/messaging/AGENTS.md deleted file mode 100644 index 9c68440a..00000000 --- a/src/platforms/messaging/AGENTS.md +++ /dev/null @@ -1,176 +0,0 @@ -# messaging — 메시징 플랫폼 family의 지역 정본 - -이 문서는 messaging family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 -`src/config/architecture/modules.json`이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는 -것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, public surface 정책, Stable 승격에 -필요한 증거, runtime membership이 비어 있다는 사실의 의미. - -루트 `AGENTS.md`와 충돌하면 루트가 이긴다. - -## Family와 framework 규칙 - -leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이름의 접두사**가 아니라 아래 표의 -역할로 정해진다. - -| Family | 역할 | 허용 framework | -| --- | --- | --- | -| `*-api` (`core-api` — `api`·`schema` 패키지, `policy`, `reliability-api`, `transport-spi`) | 값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging framework 금지 | -| `schema-*` (json/avro/protobuf), `cloudevents` | 인코딩 구현 | 해당 codec 라이브러리만. Spring 금지 | -| `runtime-core`, `security`, `observability`, `admin`(계약 `admin` + 실행 `admin.runtime`), `reliability` | framework-free 실행 로직 | Micrometer는 `observability`에서만. 나머지는 stdlib | -| `kafka` | broker adapter | 해당 broker client. Spring은 client가 곧 Spring인 경우만 | -| `reliability-jdbc-postgresql` | 관계형 신뢰성 adapter (outbox·inbox repository, admin journal) | Spring JDBC / Spring TX. **JPA 아님** — 이름이 곧 계약이다 | -| `spring-boot-starter`, `spring-boot-starter-kafka` | 조립 경계 | Spring Boot autoconfigure. 여기서만 | -| `testkit` | 테스트 지원 | Testcontainers, JUnit. production leaf가 의존하지 않는다 | - -신뢰성 기능은 세 leaf다. `messaging-reliability-api`가 vendor 중립 port(`OutboxRepository`, -`InboxRepository`)를, `messaging-reliability`가 그 port만 보는 relay·consumer 로직(stdlib)을, -`messaging-reliability-jdbc-postgresql`이 port의 관계형 구현과 migration(`V1001..V1005`, `V1101`)을 -갖는다. 예전에는 `outbox-jdbc-postgresql` 하나가 relay 로직과 PG repository와 admin journal을 함께 -가졌고 inbox도 같은 모양이었다(2026-09-25 리뷰 후속 작업에서 나눴다). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring -JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL -전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다. - -### 공용 다이제스트 헬퍼를 복사해 두는 이유 - -`messaging-admin`(`HmacApprovalVerifier`, `PlanDigest`)과 `messaging-claim-check` -(`ClaimCheckIntegrityGuard`)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의 -`shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 family는 이 애플리케이션의 -계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치), `messaging:*` leaf는 -`domain-core`·`application-core`·`shared-contract` 어느 타입에도 의존하지 않는다. 헬퍼 하나 때문에 -registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는 -`shared-contract`의 정본과 같은 규칙인지 함께 본다. - -### 인증·인가 거부의 발행 재시도 여부 (Publish retryability of authentication and authorization) - -이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다. - -- category 기본값: `FailureDescriptor.defaultRetryable(AUTHENTICATION | AUTHORIZATION) = false`. 소비 쪽 - 재시도 엔진(`DefaultRetryDecisionEngine`)은 policy가 category를 따로 정하지 않으면 이 기본값과 - descriptor의 `retryable`을 둘 다 요구한다. 그래서 인가받지 못한 메시지의 재전달은 지금도 재시도하지 않는다. -- publish 거부의 `retryable`: `KafkaPublishFailureClassifier`는 인증·인가 거부에 `retryable = true`를 붙인다. - broker가 레코드를 저장하지 않았고, credential 교체나 application보다 늦게 배포된 ACL은 몇 분 동안 모든 - publish를 거부한 뒤 멈추기 때문이다. `retryable`을 믿는 publisher가 그 몇 분 동안의 레코드를 영구 보류하지 - 않게 하려는 것이다. - -다시 시도하면 될 거부를 relay가 즉시 DEAD로 보내던 결함의 수정(2026-11-01 성숙도 리뷰 뒤)이 이 제품에서 바꾼 것(모두 -publish 경로, 소비 경로 동작은 그대로): - -- `KafkaPublishFailureClassifier`: 인증·인가 거부를 `retryable = true`로. -- `DefaultMessagePublisher`: runtime이 없을 때의 거부(`PUBLISH_RUNTIME_UNAVAILABLE`)를 `retryable = true`로. -- `KafkaMessagingTransport`: 닫힌 transport의 거부(`KAFKA_TRANSPORT_CLOSED`)를 `retryable = true`로. -- `MessagingShutdownLifecycle.PHASE`: platform 밖 relay의 순서 테스트가 참조하도록 public. - -버린 대안: vendored 제품은 그대로 두고 application bridge(ACL)가 category를 보고 "인증·인가면 재시도"로 -번역하는 것. 버린 이유: `retryable`은 이 제품이 "같은 레코드를 나중에 다시 보내면 받아질 수 있나"를 말하는 -자리다. bridge가 category로 그 판단을 다시 하면 같은 사실을 제품과 bridge가 따로 정하고, 이 제품의 -`PublishResult`를 읽는 다른 호출자는 bridge와 다른 답을 본다. 대신 이 제품 주석은 소비자 이름(application -relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(2026-11-03). - -## Public surface 정책 - -- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이 - 숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다. - (`kafka-clients`, `cloudevents-api`, `micrometer-core`, `avro`, - `protobuf-java`가 이 규칙으로 `api`다.) -- 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을 - `implementation`으로 내린 것이, JSON codec이 `ObjectMapper`를 private으로만 쓰고 Jackson을 - `implementation`으로 둔 것이 그 예다. -- 이 규칙은 문서가 아니라 `MessagingPublicSurfaceContractTest`가 붙들고 있다. leaf의 production - source에서 public/protected 시그니처에 등장하는 vendor 라이브러리를 뽑아 그 leaf의 - `build.gradle`이 `api`로 선언했는지 대조하고, starter의 `api` closure에 broker client 두 개가 - 들어오지 않는 것도 함께 본다. Spring Framework/Boot는 대상이 아니다 — 조립 경계 안에서만 - 등장하고 adopter가 이름 부를 일이 없다. -- 새 public 타입은 그 모듈의 계약이다. 삭제·시그니처 변경은 breaking change로 취급한다. - -## Application runtime에 포함되는 기준 - -기본 조립에는 Messaging family가 없다. 서비스가 `app-bootstrap/build.gradle`에 -`runtimeOnly project(':adapter:outbound:messaging-kafka')` 한 줄을 넣으면 그 모듈이 bridge와 -`messaging-spring-boot-starter`(Kafka transport 포함)의 transitive project graph를 runtime에 싣는다. 이 -사실의 SSOT는 Gradle `runtimeClasspath`이며 registry에 동일한 membership 목록을 복제하지 않는다. -모듈이 있으면 켜지고(`app.messaging.enabled` 기본 `true`), `APP_MESSAGING_ENABLED=false`로만 끈다. - -일부 codec(cloudevents 등)·claim-check·testkit처럼 starter graph에 들어오지 않는 leaf는 build-only다. -RabbitMQ·Pulsar·NATS·Kafka Share·Spring Cloud Stream bridge leaf와 Debezium outbox 매핑은 -2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표). -새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy, -qualification/support 상태를 함께 변경한다. - -## application이 이 family에 도달하는 경로 (cutover 완료) - -리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한 -`application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다. - -- application-owned port: `IntegrationEventPublishPort` -- bridge: `adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter` -- platform boundary: `EncodedMessagePublisher` -- central implementation: `DefaultMessagePublisher` - -bridge는 exact canonical envelope bytes를 다시 serialize하지 않고, destination/access/admission/runtime -lease/transport/outcome normalization/observation은 platform 중앙 publish path를 그대로 탄다. bridge -package는 `messaging-core-api`만 보며 concrete runtime/transport/Kafka 타입을 -직접 보지 않는다. - -**application bridge cutover는 2026-09-28에 끝났다(2026-09-25 소유자 결정).** application의 outbox append는 canonical -`OutboxAppendPort` 하나이고, relay는 claim한 row의 validated event를 이 bridge로만 보낸다. legacy -`OutboxEvent`·`LegacyOutboxAppendPort`와 `MessageBroker → KafkaSender` R0 경로(TLS/SASL을 적용하지 -않던 두 번째 producer)는 삭제했다. 남은 Kafka producer는 platform의 것 하나이고, broker security -profile(`KafkaSecurityConfigurer`)을 적용한다. - -canonical bridge의 producer identity는 `app.messaging.producer-id`로 명시한다. 값이 없으면 bridge bean을 -만들지 않으며 `spring.application.name`/host/pod 이름에서 identity를 발명하지 않는다. bridge가 없으면 -relay가 발행할 곳이 없으므로 messaging 모듈이 켜진 상태에서는 기동이 거부된다. - -`IntegrationEventEncoderPort`는 템플릿이 제공한다: `adapter:outbound:support`의 -`JsonIntegrationEventEncoder`가 envelope v1(`shared-contract`의 `contracts/messaging/envelope/v1.schema.json`) -안에 payload record를 결정적 JSON으로 싣는다. 계약 catalog는 애플리케이션이 bean으로 등록한 -`IntegrationEventContractContribution`뿐이고, 선언한 payload schema hash가 classpath의 schema 파일과 -다르면 기동이 실패한다. payload를 JSON Schema로 매번 검증하려는 서비스는 자기 encoder bean을 두면 된다. - -## Stable 승격에 필요한 증거 - -adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/support-matrix.md`가 현재 -상태를 기록한다): - -1. 실제 broker container를 쓰는 fault 시나리오 lane이 존재하고, 그 lane이 - `BrokerCertificationEvidence`를 산출한다. -2. `NetworkFaultScenario` 전 항목에 대해 evidence가 있거나, 없는 항목이 `knownGaps`로 명시된다. -3. capability 선언이 코드에서 파생된다 — `MessagingCapabilities`에 손으로 `true`를 쓰는 것은 - 증거가 아니다. -4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은 - Experimental에서도 금지다. -5. unknown failure의 기본값이 `AMBIGUOUS`다. `REJECTED`는 전송이 시작되지 않았다는 typed 증거가 - 있을 때만. - -Stable 문구는 evidence manifest가 존재할 때만 문서에 쓴다. - -증거를 만드는 것은 인증 레인이고, manifest는 그 실행의 출력이다: - -```bash -./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence --console=plain -``` - -레인(`messagingCertificationTest`)은 Toxiproxy를 broker 앞에 두고 장애를 주입하며, -통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을 -`messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl`에 쓴다. -게이트는 커밋된 manifest와 이번 실행의 출력을 대조한다 — **manifest를 손으로 고치면 실패하고, -레인을 돌리면 manifest가 다시 쓰인다.** 이 레인만은 Docker 가드를 달지 않는다(없으면 실패한다). -skip하는 인증 레인은 아무도 켜지 않은 브로커에 대해 성공을 보고하기 때문이며, 그래서 `test`에서는 -`messaging-certification` 태그로 제외된다. - -## Focused test - -leaf의 `gradle_path`를 registry에서 읽어 파생한다. - -```bash -cd src -./gradlew :test --console=plain -``` - -Family 전체 검증: - -```bash -./gradlew verifyCleanArchitectureDependencies --console=plain -./gradlew architectureCheck --console=plain -./gradlew verifyDependencyLocks --console=plain -``` diff --git a/src/platforms/messaging/CLAUDE.md b/src/platforms/messaging/CLAUDE.md deleted file mode 100644 index 43c994c2..00000000 --- a/src/platforms/messaging/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -@AGENTS.md diff --git a/src/platforms/messaging/messaging-admin/build.gradle b/src/platforms/messaging/messaging-admin/build.gradle deleted file mode 100644 index a6b6ce55..00000000 --- a/src/platforms/messaging/messaging-admin/build.gradle +++ /dev/null @@ -1,14 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -// The admin plane: its contract (package `admin`) and the stdlib services that execute it -// (package `admin.runtime`). They were two leaves, and every consumer of the runtime took the -// contract too, so the split added a registry entry without separating anything (S7-#12). -dependencies { - api project(':messaging:messaging-core-api') - - // ReplayService records a MessagingAuditEvent internally; no public signature names it, so - // Micrometer does not reach the journal adapters that implement the contract. - implementation project(':messaging:messaging-observability') -} diff --git a/src/platforms/messaging/messaging-admin/gradle.lockfile b/src/platforms/messaging/messaging-admin/gradle.lockfile deleted file mode 100644 index dcab1d05..00000000 --- a/src/platforms/messaging/messaging-admin/gradle.lockfile +++ /dev/null @@ -1,87 +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.50.0=annotationProcessor,checkstyle,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.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -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.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-core:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-observation:1.16.8=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.6.1=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.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminApproval.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminApproval.java deleted file mode 100644 index 8013c77d..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminApproval.java +++ /dev/null @@ -1,45 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import java.time.Instant; -import java.util.Objects; - -/** - * The approval that authorises a destructive messaging operation. - * - *

Approvals expire. An open-ended approval becomes a standing permission, which is the same - * thing as no approval at all — the window is what keeps "we approved a redrive last quarter" from - * authorising one today. - * - * @param ticket the change reference - * @param approvedBy the approver's identity - * @param approvedAt when the approval was granted - * @param validUntil when the approval stops authorising anything - */ -public record AdminApproval( - String ticket, String approvedBy, Instant approvedAt, Instant validUntil) { - - public AdminApproval { - Objects.requireNonNull(approvedAt, "approvedAt must not be null"); - Objects.requireNonNull(validUntil, "validUntil must not be null"); - if (ticket == null || ticket.isBlank()) { - throw new IllegalArgumentException("ticket must not be blank"); - } - if (approvedBy == null || approvedBy.isBlank()) { - throw new IllegalArgumentException("approvedBy must not be blank"); - } - if (validUntil.isBefore(approvedAt)) { - throw new IllegalArgumentException("an approval cannot expire before it was granted"); - } - } - - /** - * Reports whether the approval still authorises an operation. - * - * @param now the current instant - * @return true while inside the window - */ - public boolean isValidAt(Instant now) { - Objects.requireNonNull(now, "now must not be null"); - return !now.isBefore(approvedAt) && now.isBefore(validUntil); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationJournal.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationJournal.java deleted file mode 100644 index 012b2d09..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationJournal.java +++ /dev/null @@ -1,93 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import java.time.Duration; -import java.time.Instant; -import java.util.Optional; - -/** - * Where a destructive operation records that it started, how far it got, and how it ended. - * - *

The implementation this replaced was a {@code ConcurrentHashMap} registered by the starter as - * the default. Two consequences followed, and both are worse than having no store at all because - * the map made the platform look protected. A restart forgot every claim, so the same approval - * could be executed again by the same process. And two replicas each had their own map, so both - * could claim the same approval at the same moment and each believe it was the only one. - * - *

Implementations must therefore be shared and durable, must enforce uniqueness on {@code - * (approvalTicket, planDigest)}, and must hand out leases with a monotonic fencing token so a - * process that stalled past its lease cannot write over the replica that took over from it. - */ -public interface AdminOperationJournal { - - /** - * Claims an operation, or resumes the previous attempt at it. - * - * @param approvalTicket the approval authorising the operation - * @param planDigest the exact plan - * @param operationId this execution's identity - * @param leaseOwner the runtime claiming it - * @param leaseDuration how long the lease holds before another runtime may take over - * @param now the current instant - * @return the lease, carrying the point to resume from - * @throws dev.caskeleton.messaging.api.error.MessageAuthorizationException when the operation - * already completed, or another runtime holds a live lease on it - */ - AdminOperationLease begin( - String approvalTicket, - PlanDigest planDigest, - String operationId, - String leaseOwner, - Duration leaseDuration, - Instant now); - - /** - * Records durable progress and extends the lease. - * - * @param lease the lease held - * @param itemsCompleted how many items are now durably done - * @param leaseDuration how much longer to hold the lease - * @param now the current instant - * @throws dev.caskeleton.messaging.api.error.MessageAuthorizationException when the lease has - * been taken over by a newer token - */ - void checkpoint( - AdminOperationLease lease, int itemsCompleted, Duration leaseDuration, Instant now); - - /** - * Marks the operation finished. The approval is spent. - * - * @param lease the lease held - * @param itemsCompleted the final count - * @param now the current instant - */ - void complete(AdminOperationLease lease, int itemsCompleted, Instant now); - - /** - * Marks the operation failed at its current checkpoint, leaving it resumable. - * - * @param lease the lease held - * @param itemsCompleted how many items are durably done - * @param failureCode a sanitised, bounded reason - * @param now the current instant - */ - void fail(AdminOperationLease lease, int itemsCompleted, String failureCode, Instant now); - - /** - * Reads the journal entry for an operation. - * - * @param approvalTicket the approval - * @param planDigest the plan - * @return the record, when the operation has been journalled - */ - Optional find(String approvalTicket, PlanDigest planDigest); - - /** - * Whether this implementation survives a restart and is shared between replicas. - * - *

Declared rather than inferred so the starter can refuse to run a production profile on an - * in-memory journal instead of discovering the gap during an incident. - * - * @return true when the journal is durable and shared - */ - boolean isDurable(); -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationLease.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationLease.java deleted file mode 100644 index de2fb5a6..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationLease.java +++ /dev/null @@ -1,55 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import java.util.Objects; - -/** - * The right to execute one journalled operation, and the point to resume it from. - * - *

{@code resumeFrom} is the whole reason a lease is handed out rather than a boolean. A retry - * after a crash is not a new execution of the approval — it is the same operation continuing, and - * treating it as new is what republishes the items the first attempt already moved. - * - * @param approvalTicket the approval being executed - * @param planDigest the plan being executed - * @param operationId this execution's identity - * @param leaseOwner the runtime holding the lease - * @param leaseToken the fencing token; a write from an older token must be refused - * @param resumeFrom how many items the previous attempt durably completed - */ -public record AdminOperationLease( - String approvalTicket, - PlanDigest planDigest, - String operationId, - String leaseOwner, - long leaseToken, - int resumeFrom) { - - /** Validates the lease. */ - public AdminOperationLease { - Objects.requireNonNull(planDigest, "planDigest must not be null"); - if (approvalTicket == null || approvalTicket.isBlank()) { - throw new IllegalArgumentException("approvalTicket must not be blank"); - } - if (operationId == null || operationId.isBlank()) { - throw new IllegalArgumentException("operationId must not be blank"); - } - if (leaseOwner == null || leaseOwner.isBlank()) { - throw new IllegalArgumentException("leaseOwner must not be blank"); - } - if (leaseToken < 1) { - throw new IllegalArgumentException("a lease token starts at one"); - } - if (resumeFrom < 0) { - throw new IllegalArgumentException("resumeFrom must not be negative"); - } - } - - /** - * Reports whether this lease continues an earlier attempt. - * - * @return true when items were already completed - */ - public boolean isResumption() { - return resumeFrom > 0; - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationRecord.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationRecord.java deleted file mode 100644 index 752d862d..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationRecord.java +++ /dev/null @@ -1,63 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; - -/** - * One row of the destructive-operation journal. - * - *

Keyed by {@code (approvalTicket, planDigest)} rather than by the ticket alone, because the - * ticket alone cannot distinguish "this approval already ran" from "this approval is being reused - * for a different plan" — and those need opposite answers. - * - * @param approvalTicket the approval that authorised the operation - * @param planDigest the exact plan that was authorised - * @param operationId the caller-side identity of this execution - * @param state where the operation stands - * @param itemsCompleted how many items are durably done - * @param leaseOwner which runtime currently holds the lease - * @param leaseToken the fencing token, incremented on every takeover - * @param leaseExpiresAt when another runtime may take the lease over - * @param startedAt when the operation first began - * @param finishedAt when it reached a terminal state - * @param failureCode the sanitised reason it failed, when it did - */ -public record AdminOperationRecord( - String approvalTicket, - PlanDigest planDigest, - String operationId, - AdminOperationState state, - int itemsCompleted, - String leaseOwner, - long leaseToken, - Instant leaseExpiresAt, - Instant startedAt, - Optional finishedAt, - Optional failureCode) { - - /** Validates the record. */ - public AdminOperationRecord { - Objects.requireNonNull(planDigest, "planDigest must not be null"); - Objects.requireNonNull(state, "state must not be null"); - Objects.requireNonNull(leaseExpiresAt, "leaseExpiresAt must not be null"); - Objects.requireNonNull(startedAt, "startedAt must not be null"); - Objects.requireNonNull(finishedAt, "finishedAt must not be null"); - Objects.requireNonNull(failureCode, "failureCode must not be null"); - if (approvalTicket == null || approvalTicket.isBlank()) { - throw new IllegalArgumentException("approvalTicket must not be blank"); - } - if (operationId == null || operationId.isBlank()) { - throw new IllegalArgumentException("operationId must not be blank"); - } - if (leaseOwner == null || leaseOwner.isBlank()) { - throw new IllegalArgumentException("leaseOwner must not be blank"); - } - if (itemsCompleted < 0) { - throw new IllegalArgumentException("itemsCompleted must not be negative"); - } - if (leaseToken < 1) { - throw new IllegalArgumentException("a lease token starts at one"); - } - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationState.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationState.java deleted file mode 100644 index ec1ae812..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationState.java +++ /dev/null @@ -1,21 +0,0 @@ -package dev.caskeleton.messaging.admin; - -/** - * Where a journalled destructive operation stands. - * - *

The store this replaces recorded one fact — "this approval was claimed" — and recorded it - * before any work happened. A run that died halfway had consumed its approval, left no record of - * how far it got, and offered the operator two equally bad choices: request a fresh approval and - * redo work that may already have been done, or leave the operation half-applied. - */ -public enum AdminOperationState { - - /** Claimed and in progress. A lease is held; the checkpoint says how far it got. */ - STARTED, - - /** Every item finished. The approval is spent and must not run again. */ - COMPLETED, - - /** The run stopped before finishing. It may be resumed from its checkpoint under a new lease. */ - FAILED -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovalGrant.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovalGrant.java deleted file mode 100644 index 7cd97ace..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovalGrant.java +++ /dev/null @@ -1,98 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; - -/** - * Everything an issuer signs when granting one destructive operation. - * - *

{@link AdminApproval} carried a ticket, an approver, and a window. Nothing in it said which - * operation, on which destination, against which topology, or up to what impact — so the same - * approval authorised every plan presented inside the window, and the audit trail recorded a ticket - * that proved nothing about what was executed. - * - *

Every field here is part of the signed canonical form, which is what makes the grant - * non-transferable: change the target, the topology version, the impact ceiling, or the plan, and - * the signature no longer verifies. - * - * @param approval the ticket, approver, and validity window - * @param requestedBy the operator who will execute it, kept separate from the approver - * @param operation the destructive operation being authorised - * @param source the destination read from - * @param target the destination written to, when the operation has one - * @param topologyVersion the topology the impact estimate was computed against - * @param maxImpact the largest number of messages the approver agreed to - * @param planDigest the fingerprint of the exact plan - */ -public record ApprovalGrant( - AdminApproval approval, - String requestedBy, - DestructiveOperation operation, - DestinationName source, - Optional target, - String topologyVersion, - long maxImpact, - PlanDigest planDigest) { - - /** Validates the grant and enforces subject separation. */ - public ApprovalGrant { - Objects.requireNonNull(approval, "approval must not be null"); - Objects.requireNonNull(operation, "operation must not be null"); - Objects.requireNonNull(source, "source must not be null"); - Objects.requireNonNull(target, "target must not be null"); - Objects.requireNonNull(topologyVersion, "topologyVersion must not be null"); - Objects.requireNonNull(planDigest, "planDigest must not be null"); - if (requestedBy == null || requestedBy.isBlank()) { - throw new IllegalArgumentException("requestedBy must not be blank"); - } - if (approval.approvedBy().equals(requestedBy)) { - // Four-eyes, expressed where it cannot be skipped: an operator approving their own - // destructive operation is the control not existing. - throw new IllegalArgumentException( - "the approver and the operator must be different people; both are " + requestedBy); - } - if (maxImpact < 0) { - throw new IllegalArgumentException("maxImpact must not be negative"); - } - } - - /** - * Renders the grant deterministically for signing and verification. - * - *

Every field is length-prefixed rather than delimited. A delimiter can be smuggled into a - * ticket or an identity to make two different grants render identically; a length prefix cannot. - * - * @return the canonical form - */ - public String canonicalForm() { - StringBuilder canonical = new StringBuilder("v1"); - appendField(canonical, approval.ticket()); - appendField(canonical, approval.approvedBy()); - appendField(canonical, requestedBy); - appendField(canonical, operation.name()); - appendField(canonical, source.value()); - appendField(canonical, target.map(DestinationName::value).orElse("")); - appendField(canonical, topologyVersion); - appendField(canonical, Long.toString(maxImpact)); - appendField(canonical, planDigest.value()); - appendField(canonical, approval.approvedAt().toString()); - appendField(canonical, approval.validUntil().toString()); - return canonical.toString(); - } - - private static void appendField(StringBuilder canonical, String value) { - canonical.append(value.length()).append(':').append(value); - } - - /** - * Reports whether the grant still authorises anything. - * - * @param now the current instant - * @return true while inside the approval window - */ - public boolean isValidAt(Instant now) { - return approval.isValidAt(now); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovalVerifier.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovalVerifier.java deleted file mode 100644 index a44fb021..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovalVerifier.java +++ /dev/null @@ -1,29 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import java.time.Instant; - -/** - * The only thing that can turn a signed grant into a {@link VerifiedApproval}. - * - *

An implementation must check, at minimum: the issuer's signature over {@link - * ApprovalGrant#canonicalForm()}, that the approval window is open at {@code now}, and that the - * digest the caller is about to execute is the digest that was signed. Everything else the grant - * binds — operation, source, target, topology version, impact ceiling, approver-versus-operator - * separation — is inside the canonical form, so a signature check covers them all at once. - */ -public interface ApprovalVerifier { - - /** - * Verifies a signed grant against the plan actually about to run. - * - * @param grant what the issuer signed - * @param signature the issuer's signature over the grant's canonical form - * @param executingDigest the digest of the plan the caller is about to execute - * @param now the current instant - * @return the verified approval - * @throws dev.caskeleton.messaging.api.error.MessageAuthorizationException when anything about - * the grant, the signature, the window, or the digest does not hold - */ - VerifiedApproval verify( - ApprovalGrant grant, String signature, PlanDigest executingDigest, Instant now); -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovedRedrivePlan.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovedRedrivePlan.java deleted file mode 100644 index 7142a2b6..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovedRedrivePlan.java +++ /dev/null @@ -1,95 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessageAuthorizationException; -import java.time.Instant; -import java.util.Objects; - -/** - * A redrive plan that a named human has approved. - * - *

Carries {@code loopAcknowledged} separately from the approval itself. Approving a redrive of - * 900 parked messages and approving a redrive that will re-fail 400 of them are different - * decisions, and the second one needs the approver to have seen the number — so the plan cannot - * execute on a loop-risking set unless that was acknowledged explicitly. - * - * @param plan the plan that was approved - * @param approval the approval authorising it - * @param loopAcknowledged whether the approver accepted the previously-redriven candidates - */ -public record ApprovedRedrivePlan( - RedrivePlan plan, VerifiedApproval approval, boolean loopAcknowledged) { - - /** Binds the approval to this exact plan at construction. */ - public ApprovedRedrivePlan { - Objects.requireNonNull(plan, "plan must not be null"); - Objects.requireNonNull(approval, "approval must not be null"); - if (!approval.grant().planDigest().equals(plan.digest())) { - throw new MessageAuthorizationException( - "APPROVAL_PLAN_MISMATCH", - "approval %s was issued for a different plan than the one it is attached to" - .formatted(approval.ticket())); - } - if (approval.grant().operation() != DestructiveOperation.REDRIVE) { - throw new MessageAuthorizationException( - "APPROVAL_OPERATION_MISMATCH", - "approval %s authorises %s, not a redrive" - .formatted(approval.ticket(), approval.grant().operation())); - } - if (!approval.grant().source().equals(plan.request().source()) - || !approval.grant().target().equals(java.util.Optional.of(plan.request().target()))) { - throw new MessageAuthorizationException( - "APPROVAL_SOURCE_MISMATCH", - "approval %s authorises %s to %s, not %s to %s" - .formatted( - approval.ticket(), - approval.grant().source().value(), - approval.grant().target().map(DestinationName::value).orElse("(none)"), - plan.request().source().value(), - plan.request().target().value())); - } - if (plan.candidates() > approval.grant().maxImpact()) { - throw new MessageAuthorizationException( - "APPROVAL_IMPACT_EXCEEDED", - "the plan moves %d messages but the approver agreed to at most %d" - .formatted(plan.candidates(), approval.grant().maxImpact())); - } - } - - /** - * Refuses execution when the approval, the topology, or the loop risk no longer permits it. - * - * @param now the current instant - * @param currentTopologyVersion the topology version at execution time - * @throws MessageAuthorizationException when the plan may not execute - */ - public void requireExecutable(Instant now, String currentTopologyVersion) { - Objects.requireNonNull(now, "now must not be null"); - Objects.requireNonNull(currentTopologyVersion, "currentTopologyVersion must not be null"); - - if (!approval.isValidAt(now)) { - throw new MessageAuthorizationException( - "APPROVAL_EXPIRED", "approval %s is not valid at %s".formatted(approval.ticket(), now)); - } - if (!approval.grant().topologyVersion().equals(currentTopologyVersion)) { - throw new MessageAuthorizationException( - "TOPOLOGY_CHANGED_SINCE_APPROVAL", - "approval %s was signed against topology %s but the broker is now at %s" - .formatted( - approval.ticket(), approval.grant().topologyVersion(), currentTopologyVersion)); - } - if (!plan.topologyVersion().equals(currentTopologyVersion)) { - throw new MessageAuthorizationException( - "TOPOLOGY_CHANGED_SINCE_APPROVAL", - "the plan was approved against topology %s but the broker is now at %s" - .formatted(plan.topologyVersion(), currentTopologyVersion)); - } - if (plan.risksALoop() && !loopAcknowledged) { - throw new MessageAuthorizationException( - "REDRIVE_LOOP_NOT_ACKNOWLEDGED", - "%d of the %d candidates already failed a previous redrive; re-running them without " - .formatted(plan.alreadyRedrivenCandidates(), plan.candidates()) - + "fixing the cause produces a loop that looks like progress"); - } - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovedReplayPlan.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovedReplayPlan.java deleted file mode 100644 index 54b4afeb..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovedReplayPlan.java +++ /dev/null @@ -1,86 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import dev.caskeleton.messaging.api.error.MessageAuthorizationException; -import java.time.Instant; -import java.util.Objects; - -/** - * A replay plan that a named human has approved. - * - *

A distinct type from {@link ReplayPlan} rather than a boolean on it. The execute method takes - * this type, so an unapproved plan cannot reach it — the authorisation is enforced by the compiler - * instead of by a runtime check somebody can forget to write. - * - * @param plan the plan that was approved - * @param approval the approval authorising it - */ -public record ApprovedReplayPlan(ReplayPlan plan, VerifiedApproval approval) { - - /** Binds the approval to this exact plan at construction. */ - public ApprovedReplayPlan { - Objects.requireNonNull(plan, "plan must not be null"); - Objects.requireNonNull(approval, "approval must not be null"); - if (!approval.grant().planDigest().equals(plan.digest())) { - // A genuine, verified approval for a different plan. Checking it here means the mismatch - // cannot survive to the execute call under any code path. - throw new MessageAuthorizationException( - "APPROVAL_PLAN_MISMATCH", - "approval %s was issued for a different plan than the one it is attached to" - .formatted(approval.ticket())); - } - if (approval.grant().operation() != DestructiveOperation.REPLAY) { - throw new MessageAuthorizationException( - "APPROVAL_OPERATION_MISMATCH", - "approval %s authorises %s, not a replay" - .formatted(approval.ticket(), approval.grant().operation())); - } - if (!approval.grant().source().equals(plan.request().destination())) { - throw new MessageAuthorizationException( - "APPROVAL_SOURCE_MISMATCH", - "approval %s authorises %s, not %s" - .formatted( - approval.ticket(), - approval.grant().source().value(), - plan.request().destination().value())); - } - if (plan.estimatedMessages() > approval.grant().maxImpact()) { - throw new MessageAuthorizationException( - "APPROVAL_IMPACT_EXCEEDED", - "the plan moves about %d messages but the approver agreed to at most %d" - .formatted(plan.estimatedMessages(), approval.grant().maxImpact())); - } - } - - /** - * Refuses execution when the approval or the plan no longer applies. - * - * @param now the current instant - * @param currentTopologyVersion the topology version at execution time - * @throws MessageAuthorizationException when the approval has expired or the topology moved - */ - public void requireExecutable(Instant now, String currentTopologyVersion) { - Objects.requireNonNull(now, "now must not be null"); - Objects.requireNonNull(currentTopologyVersion, "currentTopologyVersion must not be null"); - - if (!approval.isValidAt(now)) { - throw new MessageAuthorizationException( - "APPROVAL_EXPIRED", "approval %s is not valid at %s".formatted(approval.ticket(), now)); - } - if (!approval.grant().topologyVersion().equals(currentTopologyVersion)) { - throw new MessageAuthorizationException( - "TOPOLOGY_CHANGED_SINCE_APPROVAL", - "approval %s was signed against topology %s but the broker is now at %s" - .formatted( - approval.ticket(), approval.grant().topologyVersion(), currentTopologyVersion)); - } - if (!plan.topologyVersion().equals(currentTopologyVersion)) { - // Every number in the plan was computed against the old topology, so the approver agreed to - // an impact estimate that no longer describes what would happen. - throw new MessageAuthorizationException( - "TOPOLOGY_CHANGED_SINCE_APPROVAL", - "the plan was approved against topology %s but the broker is now at %s; the estimated " - .formatted(plan.topologyVersion(), currentTopologyVersion) - + "impact no longer applies and the plan must be rebuilt"); - } - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestinationTopology.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestinationTopology.java deleted file mode 100644 index cf639cf5..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestinationTopology.java +++ /dev/null @@ -1,46 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import java.util.Map; -import java.util.Objects; - -/** - * What the broker actually reports for one destination. - * - *

The counterpart to {@link TopologyManifest}: the manifest is what was declared, this is what - * exists. Kept as a separate type rather than reusing the manifest so that a comparison cannot - * accidentally compare a manifest with itself and report success. - * - * @param physicalName the broker-side name - * @param partitions the observed partition count - * @param replicationFactor the observed replication factor - * @param configuration the observed configuration entries - * @param exists whether the destination is present at all - */ -public record DestinationTopology( - String physicalName, - int partitions, - int replicationFactor, - Map configuration, - boolean exists) { - - public DestinationTopology { - Objects.requireNonNull(configuration, "configuration must not be null"); - if (physicalName == null || physicalName.isBlank()) { - throw new IllegalArgumentException("physicalName must not be blank"); - } - if (exists && partitions < 1) { - throw new IllegalArgumentException("an existing destination has at least one partition"); - } - configuration = Map.copyOf(configuration); - } - - /** - * Returns the topology for a destination the broker does not have. - * - * @param physicalName the broker-side name that was looked up - * @return the absent topology - */ - public static DestinationTopology absent(String physicalName) { - return new DestinationTopology(physicalName, 0, 0, Map.of(), false); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperation.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperation.java deleted file mode 100644 index b09bfb69..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperation.java +++ /dev/null @@ -1,25 +0,0 @@ -package dev.caskeleton.messaging.admin; - -/** - * The operations that cannot be undone. - * - *

Enumerated so the guard is exhaustive rather than a list of {@code if} statements that a new - * operation can quietly avoid. - */ -public enum DestructiveOperation { - - /** Re-read a destination from an earlier position. */ - REPLAY, - - /** Move messages from a dead letter destination back to their source. */ - REDRIVE, - - /** Move a consumer group's committed position. */ - OFFSET_RESET, - - /** Discard the contents of a destination. */ - PURGE, - - /** Remove a destination entirely. */ - DELETE_DESTINATION -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperationGuard.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperationGuard.java deleted file mode 100644 index edeb82ff..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperationGuard.java +++ /dev/null @@ -1,95 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessageAuthorizationException; -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; - -/** - * The single gate every destructive messaging operation passes through. - * - *

Four conditions, all required. The caller must hold the admin credential — an application - * runtime does not, by construction. The approval must be present and inside its validity window. - * And a dry run is always permitted, because the way to make operators plan before they act is to - * make planning free. - * - *

Centralised so that adding a new destructive operation means adding an enum constant, not - * remembering to re-implement the checks. - */ -public final class DestructiveOperationGuard { - - private final boolean adminCredentialPresent; - - /** - * Creates a guard for a runtime. - * - * @param adminCredentialPresent whether this runtime holds the admin credential - */ - public DestructiveOperationGuard(boolean adminCredentialPresent) { - this.adminCredentialPresent = adminCredentialPresent; - } - - /** - * Authorises one destructive operation. - * - * @param operation the operation - * @param destination the destination affected - * @param approval the verified approval, when one was supplied - * @param dryRun whether this is a plan-only run - * @param now the current instant - * @throws MessageAuthorizationException when the operation is not authorised - */ - public void authorize( - DestructiveOperation operation, - DestinationName destination, - Optional approval, - boolean dryRun, - Instant now) { - Objects.requireNonNull(operation, "operation must not be null"); - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(approval, "approval must not be null"); - Objects.requireNonNull(now, "now must not be null"); - - if (dryRun) { - return; - } - if (!adminCredentialPresent) { - throw new MessageAuthorizationException( - "ADMIN_CREDENTIAL_REQUIRED", - operation + " on " + destination.value() + " requires the admin credential"); - } - VerifiedApproval granted = - approval.orElseThrow( - () -> - new MessageAuthorizationException( - "APPROVAL_REQUIRED", - operation + " on " + destination.value() + " requires an approval")); - if (!granted.isValidAt(now)) { - throw new MessageAuthorizationException( - "APPROVAL_EXPIRED", "approval " + granted.ticket() + " is outside its validity window"); - } - if (granted.grant().operation() != operation) { - // The approval verified — for something else. A guard that only checks presence and window - // lets a verified redrive approval authorise a destination deletion. - throw new MessageAuthorizationException( - "APPROVAL_OPERATION_MISMATCH", - "approval " - + granted.ticket() - + " authorises " - + granted.grant().operation() - + ", not " - + operation); - } - if (!granted.grant().source().equals(destination)) { - throw new MessageAuthorizationException( - "APPROVAL_SOURCE_MISMATCH", - "approval " - + granted.ticket() - + " authorises " - + granted.grant().source().value() - + ", not " - + destination.value()); - } - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/HmacApprovalVerifier.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/HmacApprovalVerifier.java deleted file mode 100644 index 44b19aa9..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/HmacApprovalVerifier.java +++ /dev/null @@ -1,111 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import dev.caskeleton.messaging.api.error.MessageAuthorizationException; -import java.nio.charset.StandardCharsets; -import java.security.MessageDigest; -import java.time.Instant; -import java.util.HexFormat; -import java.util.Objects; -import javax.crypto.Mac; -import javax.crypto.spec.SecretKeySpec; - -/** - * Verifies grants with a shared HMAC-SHA256 issuing key. - * - *

A shared secret rather than a public-key signature is a deliberate scope choice: the issuer is - * the change-management system operated by the same organisation as the runtime, so key - * distribution is already solved and the property that matters — that an operator cannot mint an - * approval for themselves — holds as long as the key is not on the operator's machine. A public-key - * verifier can be substituted by implementing {@link ApprovalVerifier}; nothing else in the - * platform depends on how the signature is produced. - * - *

Comparison is constant-time. A verifier that compares with {@code equals} leaks the signature - * one byte at a time to a caller who can retry, which for an offline attacker with unlimited - * attempts is the whole secret. - */ -public final class HmacApprovalVerifier implements ApprovalVerifier { - - private static final String ALGORITHM = "HmacSHA256"; - - private final byte[] issuingKey; - - /** - * Creates a verifier over the issuing key. - * - * @param issuingKey the shared secret the approval issuer signs with - */ - public HmacApprovalVerifier(byte[] issuingKey) { - Objects.requireNonNull(issuingKey, "issuingKey must not be null"); - if (issuingKey.length < 32) { - throw new IllegalArgumentException( - "the approval issuing key must be at least 256 bits; a shorter key makes the signature" - + " brute-forceable offline"); - } - this.issuingKey = issuingKey.clone(); - } - - /** - * Produces the signature an issuer would attach to a grant. - * - *

Present because the issuer and the verifier must agree on the canonical form exactly, and a - * second implementation of that agreement is a second thing to drift. Holding this key is what - * makes a caller an issuer — it is not, and must not become, available to the runtime that - * executes operations. - * - * @param grant the grant to sign - * @return the hexadecimal signature - */ - public String sign(ApprovalGrant grant) { - Objects.requireNonNull(grant, "grant must not be null"); - return HexFormat.of().formatHex(mac(grant.canonicalForm())); - } - - @Override - public VerifiedApproval verify( - ApprovalGrant grant, String signature, PlanDigest executingDigest, Instant now) { - Objects.requireNonNull(grant, "grant must not be null"); - Objects.requireNonNull(signature, "signature must not be null"); - Objects.requireNonNull(executingDigest, "executingDigest must not be null"); - Objects.requireNonNull(now, "now must not be null"); - - if (!grant.planDigest().equals(executingDigest)) { - // The signature would verify: this is a genuine approval, for a different plan. Replaying one - // approval across plans is the attack the digest binding exists to stop. - throw new MessageAuthorizationException( - "APPROVAL_PLAN_MISMATCH", - "approval %s was issued for plan %s but the plan about to execute is %s" - .formatted( - grant.approval().ticket(), grant.planDigest().value(), executingDigest.value())); - } - if (!grant.isValidAt(now)) { - throw new MessageAuthorizationException( - "APPROVAL_EXPIRED", - "approval %s is not valid at %s".formatted(grant.approval().ticket(), now)); - } - byte[] presented; - try { - presented = HexFormat.of().parseHex(signature); - } catch (IllegalArgumentException malformed) { - throw new MessageAuthorizationException( - "APPROVAL_SIGNATURE_INVALID", "the approval signature is not hexadecimal"); - } - if (!MessageDigest.isEqual(mac(grant.canonicalForm()), presented)) { - throw new MessageAuthorizationException( - "APPROVAL_SIGNATURE_INVALID", - ("approval %s does not verify against the issuing key; the grant was altered after it" - + " was signed, or it was never issued") - .formatted(grant.approval().ticket())); - } - return VerifiedApproval.of(grant); - } - - private byte[] mac(String canonicalForm) { - try { - Mac mac = Mac.getInstance(ALGORITHM); - mac.init(new SecretKeySpec(issuingKey, ALGORITHM)); - return mac.doFinal(canonicalForm.getBytes(StandardCharsets.UTF_8)); - } catch (java.security.GeneralSecurityException failure) { - throw new IllegalStateException("HMAC-SHA256 is required of every Java runtime", failure); - } - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/PlanDigest.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/PlanDigest.java deleted file mode 100644 index d11a4d1d..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/PlanDigest.java +++ /dev/null @@ -1,47 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import java.nio.charset.StandardCharsets; -import java.security.MessageDigest; -import java.security.NoSuchAlgorithmException; -import java.util.HexFormat; -import java.util.Objects; - -/** - * The fingerprint of exactly what an approver agreed to. - * - *

An approval used to name a ticket and a window and nothing else, so it authorised any plan - * presented within that window. The operator who got a redrive of one dead-letter destination - * approved could execute a redrive of a different one with the same ticket, and every audit record - * would look correct. Binding the signature to this digest is what makes an approval about a plan - * rather than about a period of time. - * - * @param value the lowercase hexadecimal SHA-256 of the plan's canonical form - */ -public record PlanDigest(String value) { - - /** Validates the digest shape. */ - public PlanDigest { - Objects.requireNonNull(value, "value must not be null"); - if (!value.matches("[0-9a-f]{64}")) { - throw new IllegalArgumentException("a plan digest is 64 lowercase hexadecimal characters"); - } - } - - /** - * Digests a plan's canonical form. - * - * @param canonicalForm the plan rendered deterministically, field by field - * @return the digest - */ - public static PlanDigest ofCanonical(String canonicalForm) { - Objects.requireNonNull(canonicalForm, "canonicalForm must not be null"); - try { - byte[] digest = - MessageDigest.getInstance("SHA-256") - .digest(canonicalForm.getBytes(StandardCharsets.UTF_8)); - return new PlanDigest(HexFormat.of().formatHex(digest)); - } catch (NoSuchAlgorithmException impossible) { - throw new IllegalStateException("SHA-256 is required of every Java runtime", impossible); - } - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedrivePlan.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedrivePlan.java deleted file mode 100644 index d462fb21..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedrivePlan.java +++ /dev/null @@ -1,86 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import java.time.Instant; -import java.util.Objects; - -/** - * What a redrive would do, produced before anything is moved. - * - *

{@code alreadyRedrivenCandidates} is the number that matters most. A message with a non-zero - * redrive count has been sent back to its source before and failed again; redriving it a second - * time without fixing the cause produces a loop that looks like progress in every dashboard. - * Surfacing the count at plan time is what lets an operator notice before starting it. - * - * @param request the request this plan was built from - * @param candidates how many messages are eligible - * @param alreadyRedrivenCandidates how many of those have been redriven before - * @param plannedAt when the plan was produced - * @param topologyVersion the topology the estimate was computed against - */ -public record RedrivePlan( - RedriveRequest request, - int candidates, - int alreadyRedrivenCandidates, - Instant plannedAt, - String topologyVersion) { - - public RedrivePlan { - Objects.requireNonNull(request, "request must not be null"); - Objects.requireNonNull(plannedAt, "plannedAt must not be null"); - if (candidates < 0) { - throw new IllegalArgumentException("candidates must not be negative"); - } - if (alreadyRedrivenCandidates < 0 || alreadyRedrivenCandidates > candidates) { - throw new IllegalArgumentException( - "alreadyRedrivenCandidates must be between 0 and the candidate count"); - } - if (topologyVersion == null || topologyVersion.isBlank()) { - throw new IllegalArgumentException("topologyVersion must not be blank"); - } - } - - /** - * The fingerprint an approver's signature is bound to. - * - *

Source, target, batch size, and both candidate counts are in it, so an approval for a - * redrive of one dead-letter destination cannot be presented for a redrive of another. - * - * @return the digest of this exact plan - */ - public PlanDigest digest() { - return PlanDigest.ofCanonical( - String.join( - "|", - "REDRIVE", - request.redriveId().toString(), - request.source().value(), - request.target().value(), - Integer.toString(request.batchSize()), - Integer.toString(candidates), - Integer.toString(alreadyRedrivenCandidates), - topologyVersion)); - } - - /** - * Reports whether this redrive would replay messages that already failed a redrive. - * - * @return true when any candidate has been redriven before - */ - public boolean risksALoop() { - return alreadyRedrivenCandidates > 0; - } - - /** - * Returns a one-line operator-facing summary of the impact. - * - * @return the sanitized summary - */ - public String describeImpact() { - String loop = - risksALoop() - ? ", %d of which already failed a previous redrive".formatted(alreadyRedrivenCandidates) - : ""; - return "redrive %d messages from %s to %s%s" - .formatted(candidates, request.source().value(), request.target().value(), loop); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedriveRequest.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedriveRequest.java deleted file mode 100644 index fd924af6..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedriveRequest.java +++ /dev/null @@ -1,37 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import java.util.Objects; -import java.util.UUID; - -/** - * A request to move messages from a dead letter destination back to their source. - * - *

The redrive id is a separate identifier from the message id, and both travel with the message. - * Reusing the message id as the operation id would make "this message was redriven" and "this - * message is a different message" indistinguishable, and an operator could not tell a redrive loop - * from ordinary traffic. - * - * @param redriveId the operation identity - * @param source the dead letter destination to drain - * @param target the destination to publish back to - * @param batchSize how many messages to move per pass - * @param dryRun whether to plan without moving anything - */ -public record RedriveRequest( - UUID redriveId, DestinationName source, DestinationName target, int batchSize, boolean dryRun) { - - private static final int MAX_BATCH = 100; - - public RedriveRequest { - Objects.requireNonNull(redriveId, "redriveId must not be null"); - Objects.requireNonNull(source, "source must not be null"); - Objects.requireNonNull(target, "target must not be null"); - if (source.equals(target)) { - throw new IllegalArgumentException("a redrive cannot target its own source"); - } - if (batchSize < 1 || batchSize > MAX_BATCH) { - throw new IllegalArgumentException("redrive batch size must be between 1 and " + MAX_BATCH); - } - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedriveResult.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedriveResult.java deleted file mode 100644 index e0896eb6..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedriveResult.java +++ /dev/null @@ -1,51 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import java.time.Duration; -import java.util.Objects; -import java.util.UUID; - -/** - * What a redrive actually did. - * - *

{@code stillParked} is not simply {@code candidates - moved}. A message stays parked when its - * republish did not confirm, and the redrive deliberately leaves it there rather than settling it — - * the DLQ-confirm-before-settle rule applies to a redrive exactly as it does to the original - * dead-lettering, because a redrive that settles an unconfirmed republish deletes the last copy. - * - * @param redriveId the operation identity - * @param candidates how many messages were eligible - * @param moved how many were republished and settled - * @param stillParked how many stayed on the dead letter destination - * @param elapsed how long the redrive took - * @param dryRun whether nothing was actually moved - */ -public record RedriveResult( - UUID redriveId, int candidates, int moved, int stillParked, Duration elapsed, boolean dryRun) { - - public RedriveResult { - Objects.requireNonNull(redriveId, "redriveId must not be null"); - Objects.requireNonNull(elapsed, "elapsed must not be null"); - if (candidates < 0 || moved < 0 || stillParked < 0) { - throw new IllegalArgumentException("redrive counters must not be negative"); - } - if (moved + stillParked > candidates) { - throw new IllegalArgumentException( - "a redrive cannot account for more messages than it had candidates"); - } - if (dryRun && moved > 0) { - throw new IllegalArgumentException("a dry run must not move anything"); - } - } - - /** - * Reports whether every candidate was accounted for. - * - *

An unaccounted message is a bug, not a partial success: it was neither republished nor left - * parked, which means the redrive lost track of it. - * - * @return true when moved plus still-parked covers every candidate - */ - public boolean isFullyAccounted() { - return moved + stillParked == candidates; - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayPlan.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayPlan.java deleted file mode 100644 index 4e6cb57b..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayPlan.java +++ /dev/null @@ -1,79 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import java.time.Instant; -import java.util.Objects; - -/** - * What a replay would do, produced before anything is read. - * - *

The plan exists so the estimate can be reviewed. "Replay from yesterday" is a sentence; "this - * will re-deliver 4.2 million messages into the live consumer group" is a decision, and the only - * moment an operator can make it is before the replay starts. - * - *

{@code topologyVersion} is captured here and re-checked at execution. A plan approved against - * one topology and executed against another is estimating a different thing entirely — a partition - * count that changed in between invalidates every number in this record. - * - * @param request the request this plan was built from - * @param estimatedMessages how many messages the window covers - * @param plannedAt when the plan was produced - * @param topologyVersion the topology the estimate was computed against - * @param targetsLiveConsumerGroup whether the replay would feed the live group rather than an - * isolated one - */ -public record ReplayPlan( - ReplayRequest request, - long estimatedMessages, - Instant plannedAt, - String topologyVersion, - boolean targetsLiveConsumerGroup) { - - public ReplayPlan { - Objects.requireNonNull(request, "request must not be null"); - Objects.requireNonNull(plannedAt, "plannedAt must not be null"); - if (estimatedMessages < 0) { - throw new IllegalArgumentException("estimatedMessages must not be negative"); - } - if (topologyVersion == null || topologyVersion.isBlank()) { - throw new IllegalArgumentException("topologyVersion must not be blank"); - } - } - - /** - * The fingerprint an approver's signature is bound to. - * - *

Every field that changes what would happen is in it. An approval signed over this digest - * cannot be presented for a plan that reads a different destination, targets a different consumer - * group, starts from a different position, or estimates a different impact. - * - * @return the digest of this exact plan - */ - public PlanDigest digest() { - return PlanDigest.ofCanonical( - String.join( - "|", - "REPLAY", - request.replayId().toString(), - request.destination().value(), - Boolean.toString(request.isolatedConsumerGroup()), - request.from().toString(), - request.to().map(Object::toString).orElse(""), - Long.toString(estimatedMessages), - topologyVersion, - Boolean.toString(targetsLiveConsumerGroup))); - } - - /** - * Returns a one-line operator-facing summary of the impact. - * - * @return the sanitized summary - */ - public String describeImpact() { - return "replay %s from %s: about %d messages into %s" - .formatted( - request.destination().value(), - request.from(), - estimatedMessages, - targetsLiveConsumerGroup ? "the LIVE consumer group" : "an isolated group"); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayRequest.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayRequest.java deleted file mode 100644 index 055bee1a..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayRequest.java +++ /dev/null @@ -1,36 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; -import java.util.UUID; - -/** - * A request to re-read a destination from an earlier position. - * - * @param replayId the operation identity - * @param destination the destination to replay - * @param from the replay start point - * @param to the replay end point, when bounded - * @param isolatedConsumerGroup whether to replay into a throwaway group - * @param dryRun whether to plan without reading anything - */ -public record ReplayRequest( - UUID replayId, - DestinationName destination, - Instant from, - Optional to, - boolean isolatedConsumerGroup, - boolean dryRun) { - - public ReplayRequest { - Objects.requireNonNull(replayId, "replayId must not be null"); - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(from, "from must not be null"); - Objects.requireNonNull(to, "to must not be null"); - if (to.filter(end -> end.isBefore(from)).isPresent()) { - throw new IllegalArgumentException("replay window ends before it starts"); - } - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayResult.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayResult.java deleted file mode 100644 index c2cf2086..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayResult.java +++ /dev/null @@ -1,49 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import java.time.Duration; -import java.util.Objects; -import java.util.UUID; - -/** - * What a replay actually did. - * - *

Reports the delivered count against the plan's estimate. They routinely differ — retention may - * have expired part of the window, or the stream may have grown while the plan was being approved — - * and the difference is the operator's signal that the replay covered something other than what was - * approved. - * - * @param replayId the operation identity - * @param estimatedMessages what the plan predicted - * @param deliveredMessages what was actually re-delivered - * @param elapsed how long the replay took - * @param completed whether the whole window was covered - * @param dryRun whether nothing was actually read - */ -public record ReplayResult( - UUID replayId, - long estimatedMessages, - long deliveredMessages, - Duration elapsed, - boolean completed, - boolean dryRun) { - - public ReplayResult { - Objects.requireNonNull(replayId, "replayId must not be null"); - Objects.requireNonNull(elapsed, "elapsed must not be null"); - if (estimatedMessages < 0 || deliveredMessages < 0) { - throw new IllegalArgumentException("replay counters must not be negative"); - } - if (dryRun && deliveredMessages > 0) { - throw new IllegalArgumentException("a dry run must not deliver anything"); - } - } - - /** - * Reports whether the replay covered materially less than was approved. - * - * @return true when fewer than 90% of the estimated messages were delivered - */ - public boolean fellShortOfTheEstimate() { - return completed && estimatedMessages > 0 && deliveredMessages * 10 < estimatedMessages * 9; - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyIssue.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyIssue.java deleted file mode 100644 index fdd3e4c7..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyIssue.java +++ /dev/null @@ -1,82 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import java.util.Objects; - -/** - * One discrepancy between a declared topology and what the broker actually has. - * - *

Severity is part of the finding because the two kinds behave differently at startup. A {@link - * Severity#BLOCKING} issue means the destination cannot deliver its declared guarantee — - * replication factor 1 on a destination promising durability is not a warning, it is a promise the - * platform cannot keep — so the context refuses to start. A {@link Severity#ADVISORY} issue is a - * drift worth reporting that does not break a guarantee. - * - * @param destination the logical destination - * @param attribute the topology attribute that differs - * @param declared what the manifest declared - * @param actual what the broker reported - * @param severity how the platform should react - */ -public record TopologyIssue( - String destination, String attribute, String declared, String actual, Severity severity) { - - /** How the platform reacts to a topology discrepancy. */ - public enum Severity { - /** The destination cannot deliver a declared guarantee; startup must fail. */ - BLOCKING, - /** Drift worth reporting that does not break a guarantee. */ - ADVISORY - } - - public TopologyIssue { - Objects.requireNonNull(severity, "severity must not be null"); - requireText(destination, "destination"); - requireText(attribute, "attribute"); - requireText(declared, "declared"); - requireText(actual, "actual"); - } - - /** - * Creates a blocking issue. - * - * @param destination the logical destination - * @param attribute the differing attribute - * @param declared the declared value - * @param actual the observed value - * @return the issue - */ - public static TopologyIssue blocking( - String destination, String attribute, String declared, String actual) { - return new TopologyIssue(destination, attribute, declared, actual, Severity.BLOCKING); - } - - /** - * Creates an advisory issue. - * - * @param destination the logical destination - * @param attribute the differing attribute - * @param declared the declared value - * @param actual the observed value - * @return the issue - */ - public static TopologyIssue advisory( - String destination, String attribute, String declared, String actual) { - return new TopologyIssue(destination, attribute, declared, actual, Severity.ADVISORY); - } - - /** - * Returns a one-line operator-facing description. - * - * @return the sanitized description - */ - public String describe() { - return "%s: %s declared %s but the broker has %s" - .formatted(destination, attribute, declared, actual); - } - - private static void requireText(String value, String field) { - if (value == null || value.isBlank()) { - throw new IllegalArgumentException(field + " must not be blank"); - } - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyManagementMode.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyManagementMode.java deleted file mode 100644 index 47d530cd..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyManagementMode.java +++ /dev/null @@ -1,37 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; - -/** - * Whether the application may create broker topology, or only check it. - * - *

{@link #VALIDATE_ONLY} in production, always. An application that auto-creates topology will - * auto-create it after a configuration typo too, and the topic it makes is indistinguishable from a - * real one — same broker, same client, same metrics — while carrying the broker's default partition - * count and replication factor instead of the ones the destination needs. The failure surfaces - * weeks later as data loss on a partition that was never replicated. - */ -public enum TopologyManagementMode { - - /** Compare the declared topology against the broker and fail on a mismatch. */ - VALIDATE_ONLY, - - /** Create missing topology. Permitted outside production only. */ - CREATE_IF_MISSING; - - /** - * Refuses auto-creation on a production runtime. - * - * @param production whether this runtime is production - * @throws MessagingConfigurationException when auto-creation is configured in production - */ - public void requireSafeFor(boolean production) { - if (production && this == CREATE_IF_MISSING) { - throw new MessagingConfigurationException( - "AUTO_CREATE_IN_PRODUCTION", - "topology auto-creation is not permitted in production: a mistyped destination would be " - + "created with the broker's default partition count and replication factor, and " - + "would look exactly like a correctly provisioned one"); - } - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyManifest.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyManifest.java deleted file mode 100644 index 7466a17d..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyManifest.java +++ /dev/null @@ -1,76 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import java.util.List; -import java.util.Map; -import java.util.Objects; - -/** - * The declared shape of a destination's broker topology. - * - *

Production topology is created by infrastructure code and only validated by the - * application. An application that creates topology on startup will happily create it in the wrong - * place after a configuration mistake, and the resulting topic looks exactly like a real one. - * - * @param destination the logical destination - * @param physicalName the broker-side name - * @param partitions the expected partition count, where the broker has partitions - * @param replicationFactor the expected replication factor - * @param requiredConfiguration configuration entries that must match exactly - */ -public record TopologyManifest( - String destination, - String physicalName, - int partitions, - int replicationFactor, - Map requiredConfiguration) { - - public TopologyManifest { - Objects.requireNonNull(requiredConfiguration, "requiredConfiguration must not be null"); - if (destination == null || destination.isBlank()) { - throw new IllegalArgumentException("destination must not be blank"); - } - if (physicalName == null || physicalName.isBlank()) { - throw new IllegalArgumentException("physicalName must not be blank"); - } - if (partitions < 1) { - throw new IllegalArgumentException("partitions must be at least 1"); - } - if (replicationFactor < 1) { - throw new IllegalArgumentException("replicationFactor must be at least 1"); - } - requiredConfiguration = Map.copyOf(requiredConfiguration); - } - - /** - * Compares this manifest against what the broker actually reports. - * - * @param actualPartitions the observed partition count - * @param actualReplicationFactor the observed replication factor - * @param actualConfiguration the observed configuration - * @return the differences, empty when the topology matches - */ - public List differencesFrom( - int actualPartitions, int actualReplicationFactor, Map actualConfiguration) { - Objects.requireNonNull(actualConfiguration, "actualConfiguration must not be null"); - List differences = new java.util.ArrayList<>(); - - if (actualPartitions != partitions) { - differences.add("partitions expected " + partitions + " but found " + actualPartitions); - } - if (actualReplicationFactor != replicationFactor) { - differences.add( - "replicationFactor expected " - + replicationFactor - + " but found " - + actualReplicationFactor); - } - requiredConfiguration.forEach( - (key, expected) -> { - String actual = actualConfiguration.get(key); - if (!expected.equals(actual)) { - differences.add(key + " expected " + expected + " but found " + actual); - } - }); - return List.copyOf(differences); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyValidationReport.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyValidationReport.java deleted file mode 100644 index 44e0faa0..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyValidationReport.java +++ /dev/null @@ -1,83 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.util.List; -import java.util.Objects; - -/** - * The outcome of comparing every declared topology against the broker. - * - *

Reports both severities together rather than failing on the first blocking issue. An operator - * fixing a topology wants the whole list — fixing one attribute, redeploying, and discovering the - * next one is how a ten-minute fix becomes an afternoon. - * - * @param issues every discrepancy found - * @param destinationsChecked how many destinations were compared - */ -public record TopologyValidationReport(List issues, int destinationsChecked) { - - public TopologyValidationReport { - Objects.requireNonNull(issues, "issues must not be null"); - if (destinationsChecked < 0) { - throw new IllegalArgumentException("destinationsChecked must not be negative"); - } - issues = List.copyOf(issues); - } - - /** - * Returns a report with nothing to fix. - * - * @param destinationsChecked how many destinations were compared - * @return the clean report - */ - public static TopologyValidationReport clean(int destinationsChecked) { - return new TopologyValidationReport(List.of(), destinationsChecked); - } - - /** - * Returns the issues that must fail startup. - * - * @return the blocking issues - */ - public List blocking() { - return issues.stream() - .filter(issue -> issue.severity() == TopologyIssue.Severity.BLOCKING) - .toList(); - } - - /** - * Returns the issues worth reporting that do not break a guarantee. - * - * @return the advisory issues - */ - public List advisory() { - return issues.stream() - .filter(issue -> issue.severity() == TopologyIssue.Severity.ADVISORY) - .toList(); - } - - /** - * Reports whether the topology may be used. - * - * @return true when nothing blocking was found - */ - public boolean isAcceptable() { - return blocking().isEmpty(); - } - - /** - * Fails startup when any blocking issue was found. - * - * @throws MessagingConfigurationException listing every blocking issue - */ - public void requireAcceptable() { - List blocking = blocking(); - if (blocking.isEmpty()) { - return; - } - throw new MessagingConfigurationException( - "TOPOLOGY_MISMATCH", - "the broker topology cannot deliver the declared guarantees: " - + String.join("; ", blocking.stream().map(TopologyIssue::describe).toList())); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/VerifiedApproval.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/VerifiedApproval.java deleted file mode 100644 index 37028088..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/VerifiedApproval.java +++ /dev/null @@ -1,88 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import java.time.Instant; -import java.util.Objects; - -/** - * A grant that an {@link ApprovalVerifier} has checked, and that nobody else can manufacture. - * - *

The approved-plan types used to hold a plain {@code AdminApproval} record with a public - * constructor, so "this plan was approved" was a claim the caller made about itself. Any code that - * could reach the execute method could write {@code new AdminApproval("TICKET-1", "someone", now, - * later)} and the platform believed it. - * - *

This class has no public constructor and no public factory. The only way to obtain one is to - * present a grant and a signature to a verifier, which is exactly the property the type is for: - * holding a {@code VerifiedApproval} is itself the evidence that verification happened. - */ -public final class VerifiedApproval { - - private final ApprovalGrant grant; - - private VerifiedApproval(ApprovalGrant grant) { - this.grant = Objects.requireNonNull(grant, "grant must not be null"); - } - - /** - * Mints a verified approval. Package-private on purpose: only a verifier in this package may call - * it, so the type cannot be forged from application or adapter code. - */ - static VerifiedApproval of(ApprovalGrant grant) { - return new VerifiedApproval(grant); - } - - /** - * The grant that was verified. - * - * @return the grant - */ - public ApprovalGrant grant() { - return grant; - } - - /** - * The approval ticket, for audit records and journal keys. - * - * @return the ticket - */ - public String ticket() { - return grant.approval().ticket(); - } - - /** - * Who approved the operation. - * - * @return the approver identity - */ - public String approvedBy() { - return grant.approval().approvedBy(); - } - - /** - * Reports whether the approval window is still open. - * - * @param now the current instant - * @return true while inside the window - */ - public boolean isValidAt(Instant now) { - return grant.isValidAt(now); - } - - @Override - public boolean equals(Object other) { - return other instanceof VerifiedApproval verified && grant.equals(verified.grant); - } - - @Override - public int hashCode() { - return grant.hashCode(); - } - - @Override - public String toString() { - // Deliberately not the whole grant: this string reaches logs, and the plan digest plus the - // ticket identify the operation without restating who approved what to an audience that has - // not been authorised to read it. - return "VerifiedApproval[" + ticket() + " " + grant.planDigest().value().substring(0, 12) + "]"; - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/BrokerTopologyInspector.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/BrokerTopologyInspector.java deleted file mode 100644 index 27a86aa5..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/BrokerTopologyInspector.java +++ /dev/null @@ -1,33 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import dev.caskeleton.messaging.admin.DestinationTopology; -import java.util.Optional; - -/** - * Reads the broker's current topology. - * - *

Read-only by construction. The inspector is what the application's own credential uses, and - * that credential holds no destructive grant, so the type exposes no way to create, alter, or - * delete — an application cannot reach a destructive operation even by mistake because there is no - * method to reach. - */ -public interface BrokerTopologyInspector { - - /** - * Describes one destination. - * - * @param physicalName the broker-side name - * @return the observed topology, absent when the broker has no such destination - */ - Optional describe(String physicalName); - - /** - * Returns an opaque version for the broker's current topology. - * - *

Used to invalidate an approved plan whose impact estimate was computed against an earlier - * shape. Any value that changes when the topology changes is sufficient; it is never parsed. - * - * @return the topology version - */ - String topologyVersion(); -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/CompositeTopologyValidator.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/CompositeTopologyValidator.java deleted file mode 100644 index d12e912e..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/CompositeTopologyValidator.java +++ /dev/null @@ -1,52 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import dev.caskeleton.messaging.admin.DestinationTopology; -import dev.caskeleton.messaging.admin.TopologyIssue; -import dev.caskeleton.messaging.admin.TopologyManifest; -import dev.caskeleton.messaging.admin.TopologyValidationReport; -import java.util.ArrayList; -import java.util.List; -import java.util.Objects; - -/** - * Validates every declared topology in one pass and reports the whole result. - * - *

Collects all issues rather than stopping at the first blocking one. An operator fixing a - * topology mismatch wants the complete list — discovering the next problem only after a redeploy - * turns one fix into a sequence of them, and each redeploy is another restart of a production - * service. - */ -public final class CompositeTopologyValidator { - - private final BrokerTopologyInspector inspector; - private final TopologyValidator validator = new TopologyValidator(); - - /** - * Creates a validator over a broker inspector. - * - * @param inspector reads the broker's current topology - */ - public CompositeTopologyValidator(BrokerTopologyInspector inspector) { - this.inspector = Objects.requireNonNull(inspector, "inspector must not be null"); - } - - /** - * Compares every manifest against the broker. - * - * @param manifests the declared topologies - * @return the complete report - */ - public TopologyValidationReport validate(List manifests) { - Objects.requireNonNull(manifests, "manifests must not be null"); - - List issues = new ArrayList<>(); - for (TopologyManifest manifest : manifests) { - DestinationTopology observed = - inspector - .describe(manifest.physicalName()) - .orElseGet(() -> DestinationTopology.absent(manifest.physicalName())); - issues.addAll(validator.compare(manifest, observed)); - } - return new TopologyValidationReport(issues, manifests.size()); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/DefaultMessagingAdminService.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/DefaultMessagingAdminService.java deleted file mode 100644 index 1efded53..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/DefaultMessagingAdminService.java +++ /dev/null @@ -1,257 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import dev.caskeleton.messaging.admin.AdminOperationJournal; -import dev.caskeleton.messaging.admin.AdminOperationLease; -import dev.caskeleton.messaging.admin.ApprovedRedrivePlan; -import dev.caskeleton.messaging.admin.ApprovedReplayPlan; -import dev.caskeleton.messaging.admin.RedrivePlan; -import dev.caskeleton.messaging.admin.RedriveRequest; -import dev.caskeleton.messaging.admin.RedriveResult; -import dev.caskeleton.messaging.admin.ReplayPlan; -import dev.caskeleton.messaging.admin.ReplayRequest; -import dev.caskeleton.messaging.admin.ReplayResult; -import dev.caskeleton.messaging.admin.TopologyManifest; -import dev.caskeleton.messaging.admin.TopologyValidationReport; -import java.time.Duration; -import java.time.Instant; -import java.util.List; -import java.util.Objects; -import java.util.Optional; -import java.util.function.Supplier; - -/** - * Wires plan, approval, and execution together for the non-destructive admin operations. - * - *

Execution runs four checks, in this order, and the order is the point. - * - *

    - *
  1. The approval is still inside its window. - *
  2. The topology has not changed since the plan was approved. - *
  3. The approval has not already been executed. - *
  4. Only then does anything move. - *
- * - *

The journal entry is written before the work rather than after it. Writing it - * afterwards leaves a window where a second execution starts while the first is still running, - * which is precisely the double-redrive the journal exists to prevent. - * - *

Writing it first used to have a cost the previous store never paid: an operation that died - * halfway had consumed its approval and left no record of how far it got. The journal keeps a - * checkpoint and hands back a lease that says where to resume, so a retry continues the same - * operation instead of either redoing it or requiring a new approval. - */ -public final class DefaultMessagingAdminService implements MessagingAdminService { - - /** - * How long a runtime holds an operation before another may take it over. - * - *

Long enough that a slow batch does not lose its lease mid-flight, short enough that a dead - * replica does not park an approval for an hour. - */ - private static final Duration LEASE_DURATION = Duration.ofMinutes(5); - - private final CompositeTopologyValidator topologyValidator; - private final BrokerTopologyInspector inspector; - private final AdminOperationJournal journal; - private final String leaseOwner; - private final ReplayService replayService; - private final RedriveService redriveService; - private final Supplier> manifests; - private final ReplayEstimator replayEstimator; - private final RedriveEstimator redriveEstimator; - private final Supplier clock; - - /** - * Creates the admin service. - * - * @param topologyValidator compares declared topology against the broker - * @param inspector reads the broker's topology version - * @param journal records which approvals have been executed, and how far each got - * @param leaseOwner identifies this runtime in the journal's leases - * @param replayService performs replays - * @param redriveService performs redrives - * @param manifests supplies the declared topologies - * @param replayEstimator estimates a replay's message count - * @param redriveEstimator estimates a redrive's candidates - * @param clock supplies the current instant - */ - public DefaultMessagingAdminService( - CompositeTopologyValidator topologyValidator, - BrokerTopologyInspector inspector, - AdminOperationJournal journal, - String leaseOwner, - ReplayService replayService, - RedriveService redriveService, - Supplier> manifests, - ReplayEstimator replayEstimator, - RedriveEstimator redriveEstimator, - Supplier clock) { - this.topologyValidator = - Objects.requireNonNull(topologyValidator, "topologyValidator required"); - this.inspector = Objects.requireNonNull(inspector, "inspector must not be null"); - this.journal = Objects.requireNonNull(journal, "journal must not be null"); - if (leaseOwner == null || leaseOwner.isBlank()) { - throw new IllegalArgumentException("leaseOwner must not be blank"); - } - this.leaseOwner = leaseOwner; - this.replayService = Objects.requireNonNull(replayService, "replayService must not be null"); - this.redriveService = Objects.requireNonNull(redriveService, "redriveService must not be null"); - this.manifests = Objects.requireNonNull(manifests, "manifests must not be null"); - this.replayEstimator = Objects.requireNonNull(replayEstimator, "replayEstimator required"); - this.redriveEstimator = Objects.requireNonNull(redriveEstimator, "redriveEstimator required"); - this.clock = Objects.requireNonNull(clock, "clock must not be null"); - } - - @Override - public TopologyValidationReport validateTopology() { - return topologyValidator.validate(manifests.get()); - } - - @Override - public ReplayPlan planReplay(ReplayRequest request) { - Objects.requireNonNull(request, "request must not be null"); - return new ReplayPlan( - request, - replayEstimator.estimate(request), - clock.get(), - inspector.topologyVersion(), - !request.isolatedConsumerGroup()); - } - - @Override - public ReplayResult executeReplay(ApprovedReplayPlan plan) { - Objects.requireNonNull(plan, "plan must not be null"); - Instant now = clock.get(); - ReplayRequest request = plan.plan().request(); - - plan.requireExecutable(now, inspector.topologyVersion()); - AdminOperationLease lease = - journal.begin( - plan.approval().ticket(), - plan.plan().digest(), - request.replayId().toString(), - leaseOwner, - LEASE_DURATION, - now); - - Instant startedAt = clock.get(); - ReplayReport report; - try { - report = - replayService.replay( - request, Optional.of(plan.approval()), plan.approval().approvedBy(), now); - } catch (RuntimeException failure) { - // The operation stays resumable rather than silently consuming the approval: the journal - // entry moves to FAILED at its checkpoint, and a retry takes it over from there. - journal.fail(lease, lease.resumeFrom(), failureCodeOf(failure), clock.get()); - throw failure; - } - journal.complete(lease, Math.toIntExact(report.replayed()), clock.get()); - - return new ReplayResult( - request.replayId(), - plan.plan().estimatedMessages(), - report.replayed(), - Duration.between(startedAt, clock.get()), - true, - report.dryRun()); - } - - @Override - public RedrivePlan planRedrive(RedriveRequest request) { - Objects.requireNonNull(request, "request must not be null"); - RedriveEstimate estimate = redriveEstimator.estimate(request); - return new RedrivePlan( - request, - estimate.candidates(), - estimate.alreadyRedriven(), - clock.get(), - inspector.topologyVersion()); - } - - @Override - public RedriveResult executeRedrive(ApprovedRedrivePlan plan) { - Objects.requireNonNull(plan, "plan must not be null"); - Instant now = clock.get(); - RedriveRequest request = plan.plan().request(); - - plan.requireExecutable(now, inspector.topologyVersion()); - AdminOperationLease lease = - journal.begin( - plan.approval().ticket(), - plan.plan().digest(), - request.redriveId().toString(), - leaseOwner, - LEASE_DURATION, - now); - - Instant startedAt = clock.get(); - RedriveReport report; - try { - report = - redriveService.redrive( - request, - Optional.of(plan.approval()), - plan.approval().approvedBy(), - now, - lease.resumeFrom(), - completed -> journal.checkpoint(lease, completed, LEASE_DURATION, clock.get())); - } catch (RuntimeException failure) { - journal.fail(lease, lease.resumeFrom(), failureCodeOf(failure), clock.get()); - throw failure; - } - journal.complete(lease, report.moved() + report.failed(), clock.get()); - - return new RedriveResult( - request.redriveId(), - report.candidates(), - report.moved(), - report.failed(), - Duration.between(startedAt, clock.get()), - report.dryRun()); - } - - /** - * Reduces a failure to a bounded, sanitised code for the journal. - * - *

The journal is read by operators during incidents and its contents outlive the process. A - * raw exception message can carry a destination, a payload fragment, or a credential from a - * driver's own error text, so only the platform's own code or the exception's simple name goes - * in. - */ - private static String failureCodeOf(RuntimeException failure) { - if (failure instanceof dev.caskeleton.messaging.api.error.MessagingException messaging) { - return messaging.failure().code(); - } - return failure.getClass().getSimpleName(); - } - - /** Estimates how many messages a replay would re-deliver. */ - @FunctionalInterface - public interface ReplayEstimator { - - /** - * Estimates a replay's message count without reading anything. - * - * @param request the replay request - * @return the estimated count - */ - long estimate(ReplayRequest request); - } - - /** How many messages a redrive would move, and how many already failed one. */ - record RedriveEstimate(int candidates, int alreadyRedriven) {} - - /** Estimates a redrive's candidates. */ - @FunctionalInterface - public interface RedriveEstimator { - - /** - * Estimates a redrive's candidates without moving anything. - * - * @param request the redrive request - * @return the estimate - */ - RedriveEstimate estimate(RedriveRequest request); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/DestructiveMessagingAdmin.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/DestructiveMessagingAdmin.java deleted file mode 100644 index a853d31d..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/DestructiveMessagingAdmin.java +++ /dev/null @@ -1,82 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import dev.caskeleton.messaging.admin.DestructiveOperation; -import dev.caskeleton.messaging.admin.VerifiedApproval; -import dev.caskeleton.messaging.api.destination.DestinationName; -import java.time.Duration; -import java.time.Instant; -import java.util.Objects; - -/** - * The operations that destroy data an application cannot recreate. - * - *

A separate interface from {@link MessagingAdminService}, and no bean for it is ever registered - * in an application runtime. The separation is the control: an application that never receives this - * type cannot purge a topic even if every other guard is bypassed, because the method does not - * exist on anything it holds. - * - *

Each operation takes an {@link Approved} argument rather than an approval parameter, so the - * authorisation cannot be forgotten at a call site — there is no way to call these without one. - */ -public interface DestructiveMessagingAdmin { - - /** An authorised destructive request. */ - record Approved( - DestructiveOperation operation, - DestinationName destination, - VerifiedApproval approval, - long estimatedMessagesAffected) { - - public Approved { - Objects.requireNonNull(operation, "operation must not be null"); - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(approval, "approval must not be null"); - if (estimatedMessagesAffected < 0) { - throw new IllegalArgumentException("estimatedMessagesAffected must not be negative"); - } - } - } - - /** What a destructive operation did. */ - record DestructiveResult( - DestructiveOperation operation, - DestinationName destination, - long messagesAffected, - Duration elapsed, - Instant executedAt) { - - public DestructiveResult { - Objects.requireNonNull(operation, "operation must not be null"); - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(elapsed, "elapsed must not be null"); - Objects.requireNonNull(executedAt, "executedAt must not be null"); - if (messagesAffected < 0) { - throw new IllegalArgumentException("messagesAffected must not be negative"); - } - } - } - - /** - * Moves a consumer group's committed position. - * - * @param request the authorised request - * @return what the reset did - */ - DestructiveResult resetOffset(Approved request); - - /** - * Discards the messages a destination currently holds. - * - * @param request the authorised request - * @return what the purge did - */ - DestructiveResult purge(Approved request); - - /** - * Removes a destination entirely. - * - * @param request the authorised request - * @return what the deletion did - */ - DestructiveResult deleteDestination(Approved request); -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/InMemoryAdminOperationJournal.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/InMemoryAdminOperationJournal.java deleted file mode 100644 index 574dfa57..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/InMemoryAdminOperationJournal.java +++ /dev/null @@ -1,237 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import dev.caskeleton.messaging.admin.AdminOperationJournal; -import dev.caskeleton.messaging.admin.AdminOperationLease; -import dev.caskeleton.messaging.admin.AdminOperationRecord; -import dev.caskeleton.messaging.admin.AdminOperationState; -import dev.caskeleton.messaging.admin.PlanDigest; -import dev.caskeleton.messaging.api.error.MessageAuthorizationException; -import java.time.Duration; -import java.time.Instant; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; -import java.util.concurrent.ConcurrentHashMap; - -/** - * A single-process journal, for tests and for local development. - * - *

It reports {@link #isDurable()} as false, and the starter refuses to run a production profile - * on a journal that says so. That declaration is the point of this class existing at all: the - * previous in-memory store was registered as the production default and nothing distinguished it - * from a shared one, so the gap was invisible until two replicas executed the same approval. - * - *

The semantics are otherwise the real ones — uniqueness on {@code (ticket, digest)}, lease - * takeover with a monotonic token, resume from checkpoint — so a test that passes here is testing - * the protocol rather than a simplification of it. - */ -public final class InMemoryAdminOperationJournal implements AdminOperationJournal { - - private final Map records = new ConcurrentHashMap<>(); - - @Override - public AdminOperationLease begin( - String approvalTicket, - PlanDigest planDigest, - String operationId, - String leaseOwner, - Duration leaseDuration, - Instant now) { - Objects.requireNonNull(leaseDuration, "leaseDuration must not be null"); - Objects.requireNonNull(now, "now must not be null"); - AdminOperationRecord claimed = - records.compute( - key(approvalTicket, planDigest), - (ignored, existing) -> - claim( - existing, - approvalTicket, - planDigest, - operationId, - leaseOwner, - leaseDuration, - now)); - return new AdminOperationLease( - approvalTicket, - planDigest, - claimed.operationId(), - claimed.leaseOwner(), - claimed.leaseToken(), - claimed.itemsCompleted()); - } - - private static AdminOperationRecord claim( - AdminOperationRecord existing, - String approvalTicket, - PlanDigest planDigest, - String operationId, - String leaseOwner, - Duration leaseDuration, - Instant now) { - if (existing == null) { - return new AdminOperationRecord( - approvalTicket, - planDigest, - operationId, - AdminOperationState.STARTED, - 0, - leaseOwner, - 1L, - now.plus(leaseDuration), - now, - Optional.empty(), - Optional.empty()); - } - if (existing.state() == AdminOperationState.COMPLETED) { - throw new MessageAuthorizationException( - "APPROVAL_ALREADY_EXECUTED", - ("approval %s was already executed to completion at %s; an approval authorises one" - + " execution, not a standing permission") - .formatted(approvalTicket, existing.finishedAt().orElse(existing.startedAt()))); - } - if (existing.state() == AdminOperationState.STARTED - && now.isBefore(existing.leaseExpiresAt())) { - throw new MessageAuthorizationException( - "ADMIN_OPERATION_IN_FLIGHT", - ("approval %s is being executed by %s until at least %s; two runtimes executing one" - + " approval is a duplicate storm, not a faster redrive") - .formatted(approvalTicket, existing.leaseOwner(), existing.leaseExpiresAt())); - } - // Either the previous attempt failed, or its lease expired without a completion. Both resume - // from the checkpoint under a new token, which fences the previous holder out. - return new AdminOperationRecord( - approvalTicket, - planDigest, - operationId, - AdminOperationState.STARTED, - existing.itemsCompleted(), - leaseOwner, - existing.leaseToken() + 1, - now.plus(leaseDuration), - existing.startedAt(), - Optional.empty(), - Optional.empty()); - } - - @Override - public void checkpoint( - AdminOperationLease lease, int itemsCompleted, Duration leaseDuration, Instant now) { - update( - lease, - current -> - new AdminOperationRecord( - current.approvalTicket(), - current.planDigest(), - current.operationId(), - AdminOperationState.STARTED, - Math.max(current.itemsCompleted(), itemsCompleted), - current.leaseOwner(), - current.leaseToken(), - now.plus(leaseDuration), - current.startedAt(), - Optional.empty(), - Optional.empty())); - } - - @Override - public void complete(AdminOperationLease lease, int itemsCompleted, Instant now) { - update( - lease, - current -> - new AdminOperationRecord( - current.approvalTicket(), - current.planDigest(), - current.operationId(), - AdminOperationState.COMPLETED, - Math.max(current.itemsCompleted(), itemsCompleted), - current.leaseOwner(), - current.leaseToken(), - current.leaseExpiresAt(), - current.startedAt(), - Optional.of(now), - Optional.empty())); - } - - @Override - public void fail(AdminOperationLease lease, int itemsCompleted, String failureCode, Instant now) { - Objects.requireNonNull(failureCode, "failureCode must not be null"); - update( - lease, - current -> - new AdminOperationRecord( - current.approvalTicket(), - current.planDigest(), - current.operationId(), - AdminOperationState.FAILED, - Math.max(current.itemsCompleted(), itemsCompleted), - current.leaseOwner(), - current.leaseToken(), - current.leaseExpiresAt(), - current.startedAt(), - Optional.of(now), - Optional.of(failureCode))); - } - - @Override - public Optional find(String approvalTicket, PlanDigest planDigest) { - return Optional.ofNullable(records.get(key(approvalTicket, planDigest))); - } - - @Override - public boolean isDurable() { - return false; - } - - /** - * How many operations have been journalled. - * - * @return the record count - */ - public int size() { - return records.size(); - } - - private void update( - AdminOperationLease lease, java.util.function.UnaryOperator mutation) { - Objects.requireNonNull(lease, "lease must not be null"); - records.compute( - key(lease.approvalTicket(), lease.planDigest()), - (ignored, current) -> { - if (current == null) { - throw new MessageAuthorizationException( - "ADMIN_OPERATION_NOT_JOURNALLED", - "no journal entry exists for approval " + lease.approvalTicket()); - } - if (current.leaseToken() != lease.leaseToken()) { - // The fence. A stalled runtime that wakes up and writes here would otherwise overwrite - // the progress of whichever replica took the operation over. - throw new MessageAuthorizationException( - "ADMIN_OPERATION_LEASE_LOST", - ("the lease on approval %s moved from token %d to token %d; this runtime no longer" - + " owns the operation") - .formatted(lease.approvalTicket(), lease.leaseToken(), current.leaseToken())); - } - return mutation.apply(current); - }); - } - - private static String key(String approvalTicket, PlanDigest planDigest) { - Objects.requireNonNull(planDigest, "planDigest must not be null"); - // Length-prefixed for the same reason the grant's canonical form is: a ticket containing the - // separator must not be able to collide with a different ticket and digest pair. - return String.join( - "", Integer.toString(approvalTicket.length()), ":", approvalTicket, planDigest.value()); - } - - /** - * Every journalled operation, newest first by start time. - * - * @return the records - */ - public List records() { - return records.values().stream() - .sorted(java.util.Comparator.comparing(AdminOperationRecord::startedAt).reversed()) - .toList(); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/MessagingAdminService.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/MessagingAdminService.java deleted file mode 100644 index 37df640a..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/MessagingAdminService.java +++ /dev/null @@ -1,65 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import dev.caskeleton.messaging.admin.ApprovedRedrivePlan; -import dev.caskeleton.messaging.admin.ApprovedReplayPlan; -import dev.caskeleton.messaging.admin.RedrivePlan; -import dev.caskeleton.messaging.admin.RedriveRequest; -import dev.caskeleton.messaging.admin.RedriveResult; -import dev.caskeleton.messaging.admin.ReplayPlan; -import dev.caskeleton.messaging.admin.ReplayRequest; -import dev.caskeleton.messaging.admin.ReplayResult; -import dev.caskeleton.messaging.admin.TopologyValidationReport; - -/** - * The non-destructive half of the admin plane. - * - *

Every mutating operation is split into plan and execute, and the execute methods take an - * {@code Approved*} type. A caller cannot execute something it has not planned, because it has no - * way to construct the argument — the plan/approve/execute sequence is enforced by the types rather - * than by a runtime check. - * - *

Destructive operations live in {@link DestructiveMessagingAdmin}, a separate interface that an - * application runtime never receives a bean for. Splitting them means a compromised handler that - * somehow reaches this service still has no method that deletes anything. - */ -public interface MessagingAdminService { - - /** - * Compares every declared topology against the broker. - * - * @return the discrepancies found - */ - TopologyValidationReport validateTopology(); - - /** - * Estimates what a replay would do, without reading anything. - * - * @param request the replay request - * @return the plan, including its impact estimate - */ - ReplayPlan planReplay(ReplayRequest request); - - /** - * Executes an approved replay. - * - * @param plan the approved plan - * @return what the replay actually did - */ - ReplayResult executeReplay(ApprovedReplayPlan plan); - - /** - * Estimates what a redrive would do, without moving anything. - * - * @param request the redrive request - * @return the plan, including how many candidates already failed a redrive - */ - RedrivePlan planRedrive(RedriveRequest request); - - /** - * Executes an approved redrive. - * - * @param plan the approved plan - * @return what the redrive actually did - */ - RedriveResult executeRedrive(ApprovedRedrivePlan plan); -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveReport.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveReport.java deleted file mode 100644 index 3d76d3cf..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveReport.java +++ /dev/null @@ -1,18 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -/** - * What one redrive pass did. - * - * @param candidates how many messages were eligible - * @param moved how many were republished and settled - * @param failed how many did not confirm and stay parked - * @param dryRun whether this was a plan-only run - */ -public record RedriveReport(int candidates, int moved, int failed, boolean dryRun) { - - public RedriveReport { - if (candidates < 0 || moved < 0 || failed < 0) { - throw new IllegalArgumentException("redrive counters must not be negative"); - } - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveService.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveService.java deleted file mode 100644 index 8079d8e9..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveService.java +++ /dev/null @@ -1,210 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import dev.caskeleton.messaging.admin.DestructiveOperation; -import dev.caskeleton.messaging.admin.DestructiveOperationGuard; -import dev.caskeleton.messaging.admin.RedriveRequest; -import dev.caskeleton.messaging.admin.VerifiedApproval; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishResult; -import java.time.Instant; -import java.util.ArrayList; -import java.util.List; -import java.util.Objects; -import java.util.Optional; - -/** - * Moves messages from a dead letter destination back to their source. - * - *

A redrive is a publish followed by a settlement, in that order, exactly like dead lettering in - * reverse. A message whose republish did not confirm stays in the dead letter destination: losing - * it on the way back would be the one outcome worse than leaving it parked. - * - *

The redrive id and a redrive counter travel with each message. Without them a message that - * fails again is indistinguishable from a new one, and a redrive loop is invisible until the dead - * letter destination is full. - */ -public final class RedriveService { - - private final DestructiveOperationGuard guard; - private final RedriveSource source; - private final RedrivePublisher publisher; - private final AuditSink audit; - - /** - * Creates a redrive service. - * - * @param guard the destructive operation guard - * @param source reads and settles dead letter messages - * @param publisher republishes to the target destination - * @param audit records the operation - */ - public RedriveService( - DestructiveOperationGuard guard, - RedriveSource source, - RedrivePublisher publisher, - AuditSink audit) { - this.guard = Objects.requireNonNull(guard, "guard must not be null"); - this.source = Objects.requireNonNull(source, "source must not be null"); - this.publisher = Objects.requireNonNull(publisher, "publisher must not be null"); - this.audit = Objects.requireNonNull(audit, "audit must not be null"); - } - - /** - * Runs one redrive pass. - * - * @param request what to move - * @param approval the verified approval, when one was supplied - * @param subject the operator identity - * @param now the current instant - * @return what the pass did - */ - public RedriveReport redrive( - RedriveRequest request, Optional approval, String subject, Instant now) { - return redrive(request, approval, subject, now, 0, completed -> {}); - } - - /** - * Runs one redrive pass, resuming a previous attempt and reporting progress as it goes. - * - *

Three things were wrong with running this as a plain loop. A synchronous failure from the - * publisher — a broker that refuses the connection rather than the message — propagated out of - * the loop, so the remaining candidates were never attempted and the audit record was never - * written: the operation left no trace of the items it had already moved. A retry then started - * from the first candidate and republished them. And nothing bounded how many times one message - * could be redriven. - * - * @param request what to move - * @param approval the verified approval, when one was supplied - * @param subject the operator identity - * @param now the current instant - * @param resumeFrom how many candidates a previous attempt durably moved - * @param checkpoint called with the running completed count after each item - * @return what the pass did - */ - public RedriveReport redrive( - RedriveRequest request, - Optional approval, - String subject, - Instant now, - int resumeFrom, - java.util.function.IntConsumer checkpoint) { - Objects.requireNonNull(request, "request must not be null"); - Objects.requireNonNull(checkpoint, "checkpoint must not be null"); - if (resumeFrom < 0) { - throw new IllegalArgumentException("resumeFrom must not be negative"); - } - guard.authorize( - DestructiveOperation.REDRIVE, request.source(), approval, request.dryRun(), now); - - List candidates = source.peek(request.source(), request.batchSize()); - if (request.dryRun()) { - return new RedriveReport(candidates.size(), 0, 0, true); - } - - List moved = new ArrayList<>(); - int failed = 0; - int completed = resumeFrom; - try { - // Everything before resumeFrom was moved and settled by the previous attempt. Re-publishing - // it is not a retry, it is a duplicate. - for (MessageId messageId : - candidates.subList(Math.min(resumeFrom, candidates.size()), candidates.size())) { - if (attempt(messageId, request)) { - moved.add(messageId); - } else { - failed++; - } - completed++; - checkpoint.accept(completed); - } - } finally { - // In the finally block on purpose: an operation that dies partway must still leave a record - // of what it moved, because that record is what the resumed attempt and the incident review - // both read. - audit.record( - new dev.caskeleton.messaging.observation.MessagingAuditEvent( - "REDRIVE", - subject, - request.source().value(), - approval.map(VerifiedApproval::ticket).orElse("dry-run"), - now, - java.util.Map.of( - "redriveId", request.redriveId().toString(), - "resumedFrom", Integer.toString(resumeFrom), - "moved", Integer.toString(moved.size()), - "failed", Integer.toString(failed)))); - } - - return new RedriveReport(candidates.size(), moved.size(), failed, false); - } - - private boolean attempt(MessageId messageId, RedriveRequest request) { - PublishResult result; - try { - result = publisher.republish(messageId, request.target(), request.redriveId()); - } catch (RuntimeException failure) { - // One message that cannot be republished is a failed item, not a failed pass. Letting it - // propagate abandoned every candidate behind it. - return false; - } - if (result.completion() != PublishCompletion.CONFIRMED) { - return false; - } - source.settle(request.source(), messageId); - return true; - } - - /** Reads and settles messages on a dead letter destination. */ - public interface RedriveSource { - - /** - * Returns the next candidates without settling them. - * - * @param destination the dead letter destination - * @param batchSize how many to return - * @return the candidate identities - */ - List peek( - dev.caskeleton.messaging.api.destination.DestinationName destination, int batchSize); - - /** - * Settles a message that has been successfully republished. - * - * @param destination the dead letter destination - * @param messageId the message identity - */ - void settle( - dev.caskeleton.messaging.api.destination.DestinationName destination, MessageId messageId); - } - - /** Republishes a dead lettered message to its target destination. */ - @FunctionalInterface - public interface RedrivePublisher { - - /** - * Republishes one message under its original identity. - * - * @param messageId the message identity - * @param target the destination to publish back to - * @param redriveId the operation identity stamped on the message - * @return the publish outcome - */ - PublishResult republish( - MessageId messageId, - dev.caskeleton.messaging.api.destination.DestinationName target, - java.util.UUID redriveId); - } - - /** Records privileged operations. */ - @FunctionalInterface - public interface AuditSink { - - /** - * Records one audit event. - * - * @param event the event - */ - void record(dev.caskeleton.messaging.observation.MessagingAuditEvent event); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/ReplayReport.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/ReplayReport.java deleted file mode 100644 index e7d8c73e..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/ReplayReport.java +++ /dev/null @@ -1,21 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import java.util.Objects; -import java.util.UUID; - -/** - * What one replay did. - * - * @param replayId the operation identity - * @param replayed how many messages were re-read - * @param dryRun whether this was a plan-only run - */ -public record ReplayReport(UUID replayId, long replayed, boolean dryRun) { - - public ReplayReport { - Objects.requireNonNull(replayId, "replayId must not be null"); - if (replayed < 0) { - throw new IllegalArgumentException("replayed must not be negative"); - } - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/ReplayService.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/ReplayService.java deleted file mode 100644 index 723e1ed8..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/ReplayService.java +++ /dev/null @@ -1,91 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import dev.caskeleton.messaging.admin.DestructiveOperation; -import dev.caskeleton.messaging.admin.DestructiveOperationGuard; -import dev.caskeleton.messaging.admin.ReplayRequest; -import dev.caskeleton.messaging.admin.VerifiedApproval; -import dev.caskeleton.messaging.observation.MessagingAuditEvent; -import java.time.Instant; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; - -/** - * Re-reads a destination from an earlier position. - * - *

The request carries an {@code isolatedConsumerGroup} intent flag, but a caller-supplied - * boolean is not proof that the executor actually created or used an isolated broker group. - * Therefore every non-dry-run replay goes through the destructive guard until the runtime can - * attest isolation itself. Dry-run remains approval-free because it changes no broker state. - */ -public final class ReplayService { - - private final DestructiveOperationGuard guard; - private final ReplayExecutor executor; - private final RedriveService.AuditSink audit; - - /** - * Creates a replay service. - * - * @param guard the destructive operation guard - * @param executor performs the replay - * @param audit records the operation - */ - public ReplayService( - DestructiveOperationGuard guard, ReplayExecutor executor, RedriveService.AuditSink audit) { - this.guard = Objects.requireNonNull(guard, "guard must not be null"); - this.executor = Objects.requireNonNull(executor, "executor must not be null"); - this.audit = Objects.requireNonNull(audit, "audit must not be null"); - } - - /** - * Runs one replay. - * - * @param request what to replay - * @param approval the verified approval, when one was supplied - * @param subject the operator identity - * @param now the current instant - * @return what the replay did - */ - public ReplayReport replay( - ReplayRequest request, Optional approval, String subject, Instant now) { - Objects.requireNonNull(request, "request must not be null"); - Objects.requireNonNull(approval, "approval must not be null"); - - guard.authorize( - DestructiveOperation.REPLAY, request.destination(), approval, request.dryRun(), now); - - if (request.dryRun()) { - return new ReplayReport(request.replayId(), 0, true); - } - - long replayed = executor.replay(request); - - audit.record( - new MessagingAuditEvent( - "REPLAY", - subject, - request.destination().value(), - approval.map(VerifiedApproval::ticket).orElse("dry-run"), - now, - Map.of( - "replayId", request.replayId().toString(), - "isolated", Boolean.toString(request.isolatedConsumerGroup()), - "replayed", Long.toString(replayed)))); - - return new ReplayReport(request.replayId(), replayed, false); - } - - /** Performs the replay against a broker. */ - @FunctionalInterface - public interface ReplayExecutor { - - /** - * Replays a destination and returns how many messages were re-read. - * - * @param request the replay request - * @return the replayed message count - */ - long replay(ReplayRequest request); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntime.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntime.java deleted file mode 100644 index 4a61db48..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntime.java +++ /dev/null @@ -1,88 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import dev.caskeleton.messaging.admin.TopologyManifest; -import dev.caskeleton.messaging.api.error.MessageTopologyException; -import java.util.ArrayList; -import java.util.List; -import java.util.Map; -import java.util.Objects; - -/** - * Validates declared topology against what the broker actually has. - * - *

Validate-only, and it fails startup rather than logging. A partition count that silently - * differs from the manifest changes the ordering guarantee the destination advertises, and a - * missing {@code min.insync.replicas} changes what {@code acks=all} actually means — both are the - * kind of drift that is invisible until the incident. - */ -public final class TopologyValidationRuntime { - - private final TopologyReader reader; - - /** - * Creates a validator over a broker reader. - * - * @param reader reads the observed topology - */ - public TopologyValidationRuntime(TopologyReader reader) { - this.reader = Objects.requireNonNull(reader, "reader must not be null"); - } - - /** - * Validates every manifest, reporting all differences at once. - * - * @param manifests the declared topology - * @throws MessageTopologyException when the broker does not match - */ - public void validate(List manifests) { - Objects.requireNonNull(manifests, "manifests must not be null"); - List problems = new ArrayList<>(); - - for (TopologyManifest manifest : manifests) { - ObservedTopology observed = reader.read(manifest.physicalName()); - if (observed == null) { - problems.add(manifest.physicalName() + " does not exist"); - continue; - } - manifest - .differencesFrom( - observed.partitions(), observed.replicationFactor(), observed.configuration()) - .forEach(difference -> problems.add(manifest.physicalName() + ": " + difference)); - } - - if (!problems.isEmpty()) { - throw new MessageTopologyException( - "TOPOLOGY_MISMATCH", - "broker topology does not match the manifest: " + String.join("; ", problems)); - } - } - - /** Reads the observed topology for a physical destination. */ - @FunctionalInterface - public interface TopologyReader { - - /** - * Reads one destination's topology. - * - * @param physicalName the broker-side name - * @return the observed topology, or null when it does not exist - */ - ObservedTopology read(String physicalName); - } - - /** - * What the broker reports for a destination. - * - * @param partitions the observed partition count - * @param replicationFactor the observed replication factor - * @param configuration the observed configuration - */ - public record ObservedTopology( - int partitions, int replicationFactor, Map configuration) { - - public ObservedTopology { - Objects.requireNonNull(configuration, "configuration must not be null"); - configuration = Map.copyOf(configuration); - } - } -} diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/TopologyValidator.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/TopologyValidator.java deleted file mode 100644 index 003a3268..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/TopologyValidator.java +++ /dev/null @@ -1,91 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import dev.caskeleton.messaging.admin.DestinationTopology; -import dev.caskeleton.messaging.admin.TopologyIssue; -import dev.caskeleton.messaging.admin.TopologyManifest; -import java.util.ArrayList; -import java.util.List; -import java.util.Map; -import java.util.Objects; - -/** - * Compares one declared topology against what the broker reports. - * - *

Which discrepancies block is a judgement encoded here rather than left to configuration. - * Replication factor and absence are blocking because a destination that is missing or unreplicated - * cannot deliver the durability its profile promises. A partition count that is higher - * than declared is advisory rather than blocking: extra partitions do not break durability, and - * someone scaling a topic up deliberately should not be met with a refusal to start. - * - *

A partition count that is lower is blocking, because it silently reduces the - * concurrency the destination was sized for and, on a keyed topic, changes which key lands where. - */ -public final class TopologyValidator { - - /** - * Compares a manifest against observed topology. - * - * @param manifest what was declared - * @param observed what the broker reports - * @return the discrepancies found, empty when they agree - */ - public List compare(TopologyManifest manifest, DestinationTopology observed) { - Objects.requireNonNull(manifest, "manifest must not be null"); - Objects.requireNonNull(observed, "observed must not be null"); - - List issues = new ArrayList<>(); - String destination = manifest.destination(); - - if (!observed.exists()) { - issues.add( - TopologyIssue.blocking(destination, "existence", manifest.physicalName(), "absent")); - return List.copyOf(issues); - } - - if (!manifest.physicalName().equals(observed.physicalName())) { - issues.add( - TopologyIssue.blocking( - destination, "physicalName", manifest.physicalName(), observed.physicalName())); - } - - if (observed.partitions() < manifest.partitions()) { - issues.add( - TopologyIssue.blocking( - destination, - "partitions", - Integer.toString(manifest.partitions()), - Integer.toString(observed.partitions()))); - } else if (observed.partitions() > manifest.partitions()) { - // Scaling a topic up is a legitimate operation; refusing to start would punish it. - issues.add( - TopologyIssue.advisory( - destination, - "partitions", - Integer.toString(manifest.partitions()), - Integer.toString(observed.partitions()))); - } - - if (observed.replicationFactor() < manifest.replicationFactor()) { - issues.add( - TopologyIssue.blocking( - destination, - "replicationFactor", - Integer.toString(manifest.replicationFactor()), - Integer.toString(observed.replicationFactor()))); - } - - for (Map.Entry required : manifest.requiredConfiguration().entrySet()) { - String actual = observed.configuration().get(required.getKey()); - if (!required.getValue().equals(actual)) { - issues.add( - TopologyIssue.blocking( - destination, - required.getKey(), - required.getValue(), - actual == null ? "unset" : actual)); - } - } - - return List.copyOf(issues); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/DestructiveOperationGuardTest.java b/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/DestructiveOperationGuardTest.java deleted file mode 100644 index cd9f8cd0..00000000 --- a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/DestructiveOperationGuardTest.java +++ /dev/null @@ -1,147 +0,0 @@ -package dev.caskeleton.messaging.admin; - -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.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessageAuthorizationException; -import java.time.Instant; -import java.util.Map; -import java.util.Optional; -import java.util.UUID; -import org.junit.jupiter.api.Test; - -class DestructiveOperationGuardTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - private static final DestinationName ORDERS = new DestinationName("order-events"); - - private static final HmacApprovalVerifier ISSUER = - new HmacApprovalVerifier( - "an-issuing-key-of-at-least-32-bytes!".getBytes(java.nio.charset.StandardCharsets.UTF_8)); - - private static final VerifiedApproval VALID = - verified(DestructiveOperation.REPLAY, ORDERS, NOW.minusSeconds(60), NOW.plusSeconds(3600)); - - /** - * A grant the issuer signed, verified the way the runtime verifies it. - * - *

The guard used to take a plain {@code AdminApproval} record, which any caller could - * construct. Every case below now has to go through a real signature to get an approval object at - * all, which is the property the type change was made for. - */ - private static VerifiedApproval verified( - DestructiveOperation operation, DestinationName source, Instant from, Instant until) { - PlanDigest digest = PlanDigest.ofCanonical(operation + "|" + source.value()); - ApprovalGrant grant = - new ApprovalGrant( - new AdminApproval("CHG-1001", "approver", from, until), - "operator", - operation, - source, - Optional.empty(), - "v1", - Long.MAX_VALUE, - digest); - return ISSUER.verify(grant, ISSUER.sign(grant), digest, from); - } - - @Test - void anApplicationRuntimeCannotRedrive() { - DestructiveOperationGuard guard = new DestructiveOperationGuard(false); - - assertThatThrownBy( - () -> - guard.authorize( - DestructiveOperation.REDRIVE, ORDERS, Optional.of(VALID), false, NOW)) - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("admin credential"); - } - - @Test - void anAdminRuntimeStillNeedsAnApproval() { - DestructiveOperationGuard guard = new DestructiveOperationGuard(true); - - assertThatThrownBy( - () -> guard.authorize(DestructiveOperation.PURGE, ORDERS, Optional.empty(), false, NOW)) - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("approval"); - } - - @Test - void anExpiredApprovalDoesNotAuthorise() { - DestructiveOperationGuard guard = new DestructiveOperationGuard(true); - VerifiedApproval expired = - verified( - DestructiveOperation.OFFSET_RESET, - ORDERS, - NOW.minusSeconds(7200), - NOW.minusSeconds(60)); - - assertThatThrownBy( - () -> - guard.authorize( - DestructiveOperation.OFFSET_RESET, ORDERS, Optional.of(expired), false, NOW)) - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("validity window"); - } - - @Test - void aDryRunIsAlwaysPermitted() { - DestructiveOperationGuard guard = new DestructiveOperationGuard(false); - - assertThatCode( - () -> - guard.authorize( - DestructiveOperation.DELETE_DESTINATION, ORDERS, Optional.empty(), true, NOW)) - .doesNotThrowAnyException(); - } - - @Test - void anApprovedAdminOperationIsAuthorised() { - DestructiveOperationGuard guard = new DestructiveOperationGuard(true); - - assertThatCode( - () -> - guard.authorize( - DestructiveOperation.REPLAY, ORDERS, Optional.of(VALID), false, NOW)) - .doesNotThrowAnyException(); - } - - @Test - void aRedriveCannotTargetItsOwnSource() { - assertThatThrownBy(() -> new RedriveRequest(UUID.randomUUID(), ORDERS, ORDERS, 100, false)) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void aRedriveBatchIsBoundedSoOneOperationCannotFloodTheSource() { - assertThatThrownBy( - () -> - new RedriveRequest( - UUID.randomUUID(), new DestinationName("order-events-dlq"), ORDERS, 101, false)) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void aTopologyManifestReportsEveryDifference() { - TopologyManifest manifest = - new TopologyManifest( - "order-events", "order.events.v1", 6, 3, Map.of("min.insync.replicas", "2")); - - assertThat(manifest.differencesFrom(3, 3, Map.of("min.insync.replicas", "1"))) - .hasSize(2) - .anySatisfy(difference -> assertThat(difference).contains("partitions")) - .anySatisfy(difference -> assertThat(difference).contains("min.insync.replicas")); - } - - @Test - void aMatchingTopologyReportsNoDifferences() { - TopologyManifest manifest = - new TopologyManifest( - "order-events", "order.events.v1", 6, 3, Map.of("min.insync.replicas", "2")); - - assertThat(manifest.differencesFrom(6, 3, Map.of("min.insync.replicas", "2"))).isEmpty(); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/AdminOperationJournalTest.java b/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/AdminOperationJournalTest.java deleted file mode 100644 index 76b5e32c..00000000 --- a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/AdminOperationJournalTest.java +++ /dev/null @@ -1,145 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -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.admin.AdminOperationLease; -import dev.caskeleton.messaging.admin.AdminOperationState; -import dev.caskeleton.messaging.admin.PlanDigest; -import dev.caskeleton.messaging.api.error.MessageAuthorizationException; -import java.time.Duration; -import java.time.Instant; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * The protocol the journal has to implement, proven against the in-memory one. - * - *

What it replaced recorded a single fact — "this approval was claimed" — before any work - * happened, in a map. An operation that died halfway had spent its approval, left no record of what - * it had already moved, and gave a retry no way to continue: either request a new approval and - * republish everything, or leave the redrive half applied. - */ -class AdminOperationJournalTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:00:00Z"); - private static final Duration LEASE = Duration.ofMinutes(5); - private static final String TICKET = "CHG-1042"; - private static final PlanDigest DIGEST = PlanDigest.ofCanonical("REDRIVE|orders.v1.dlq|50"); - private static final PlanDigest OTHER_DIGEST = PlanDigest.ofCanonical("REDRIVE|payments.dlq|50"); - - private final InMemoryAdminOperationJournal journal = new InMemoryAdminOperationJournal(); - - @Test - @DisplayName("two replicas racing for one approval produce exactly one lease") - void twoReplicasRacingProduceExactlyOneLease() { - journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW); - - assertThatThrownBy( - () -> journal.begin(TICKET, DIGEST, "op-2", "replica-b", LEASE, NOW.plusSeconds(1))) - .as("both replicas executing one approval is a duplicate storm, not a faster redrive") - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("replica-a"); - } - - @Test - @DisplayName("a completed operation cannot be executed again") - void aCompletedOperationCannotBeExecutedAgain() { - AdminOperationLease lease = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW); - journal.complete(lease, 50, NOW.plusSeconds(30)); - - assertThatThrownBy( - () -> journal.begin(TICKET, DIGEST, "op-2", "replica-a", LEASE, NOW.plusSeconds(60))) - .as("an arrow-up in the shell must not re-run an approved redrive") - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("already executed"); - } - - @Test - @DisplayName("a crashed run resumes from its checkpoint rather than starting over") - void aCrashedRunResumesFromItsCheckpoint() { - AdminOperationLease first = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW); - journal.checkpoint(first, 30, LEASE, NOW.plusSeconds(10)); - // No fail() call: this replica died. The lease simply runs out. - - AdminOperationLease resumed = - journal.begin(TICKET, DIGEST, "op-1", "replica-b", LEASE, NOW.plus(Duration.ofMinutes(10))); - - assertThat(resumed.resumeFrom()) - .as("the 30 already moved must not be republished") - .isEqualTo(30); - assertThat(resumed.leaseToken()).isGreaterThan(first.leaseToken()); - assertThat(resumed.isResumption()).isTrue(); - } - - @Test - @DisplayName("a failed run stays resumable without waiting for the lease to expire") - void aFailedRunStaysResumableImmediately() { - AdminOperationLease first = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW); - journal.checkpoint(first, 12, LEASE, NOW.plusSeconds(5)); - journal.fail(first, 12, "MESSAGE_BROKER_UNAVAILABLE", NOW.plusSeconds(6)); - - AdminOperationLease resumed = - journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW.plusSeconds(7)); - - assertThat(resumed.resumeFrom()).isEqualTo(12); - assertThat(journal.find(TICKET, DIGEST)) - .hasValueSatisfying( - record -> assertThat(record.state()).isEqualTo(AdminOperationState.STARTED)); - } - - @Test - @DisplayName("a runtime that lost its lease cannot write over the one that took over") - void aRuntimeThatLostItsLeaseCannotWriteOverTheSuccessor() { - AdminOperationLease stale = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW); - journal.checkpoint(stale, 30, LEASE, NOW.plusSeconds(10)); - AdminOperationLease successor = - journal.begin(TICKET, DIGEST, "op-1", "replica-b", LEASE, NOW.plus(Duration.ofMinutes(10))); - journal.checkpoint(successor, 45, LEASE, NOW.plus(Duration.ofMinutes(11))); - - assertThatThrownBy(() -> journal.complete(stale, 30, NOW.plus(Duration.ofMinutes(12)))) - .as("a stalled replica waking up must not mark the operation done at its own count") - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("no longer owns"); - - assertThat(journal.find(TICKET, DIGEST)) - .hasValueSatisfying( - record -> { - assertThat(record.itemsCompleted()).isEqualTo(45); - assertThat(record.state()).isEqualTo(AdminOperationState.STARTED); - }); - } - - @Test - @DisplayName("the same ticket presented for a different plan is a different operation") - void theSameTicketForADifferentPlanIsADifferentOperation() { - journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW); - - // Keyed on the ticket alone this would have been refused as a duplicate execution, which reads - // as protection but is actually the wrong answer: it is a different plan, and it must be - // refused by the approval binding rather than silently treated as the same operation. - assertThatCode(() -> journal.begin(TICKET, OTHER_DIGEST, "op-2", "replica-a", LEASE, NOW)) - .doesNotThrowAnyException(); - assertThat(journal.size()).isEqualTo(2); - } - - @Test - @DisplayName("a checkpoint never moves backwards") - void aCheckpointNeverMovesBackwards() { - AdminOperationLease lease = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW); - journal.checkpoint(lease, 40, LEASE, NOW.plusSeconds(10)); - journal.checkpoint(lease, 5, LEASE, NOW.plusSeconds(20)); - - assertThat(journal.find(TICKET, DIGEST)) - .hasValueSatisfying(record -> assertThat(record.itemsCompleted()).isEqualTo(40)); - } - - @Test - @DisplayName("the in-memory journal declares itself non-durable") - void theInMemoryJournalDeclaresItselfNonDurable() { - assertThat(journal.isDurable()) - .as("the starter refuses a production profile on a journal that says this") - .isFalse(); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovalForgeryTest.java b/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovalForgeryTest.java deleted file mode 100644 index abc54be1..00000000 --- a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovalForgeryTest.java +++ /dev/null @@ -1,243 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -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.admin.AdminApproval; -import dev.caskeleton.messaging.admin.ApprovalGrant; -import dev.caskeleton.messaging.admin.ApprovedRedrivePlan; -import dev.caskeleton.messaging.admin.DestructiveOperation; -import dev.caskeleton.messaging.admin.HmacApprovalVerifier; -import dev.caskeleton.messaging.admin.RedrivePlan; -import dev.caskeleton.messaging.admin.RedriveRequest; -import dev.caskeleton.messaging.admin.VerifiedApproval; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessageAuthorizationException; -import java.nio.charset.StandardCharsets; -import java.time.Duration; -import java.time.Instant; -import java.util.Optional; -import java.util.UUID; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * Whether "this was approved" is a fact or a claim the caller makes about itself. - * - *

It was a claim. {@code AdminApproval} was a public record and {@code ApprovedRedrivePlan} a - * public record over it, so any code that could reach the execute method could write its own - * approval and the platform believed it. Nothing bound an approval to an operation, a destination, - * a topology version, or an impact ceiling either, so a genuine approval for one redrive authorised - * a redrive of anything else inside its window. - */ -class ApprovalForgeryTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:00:00Z"); - private static final UUID OPERATION_ID = UUID.fromString("0199aaaa-bbbb-7ccc-8ddd-eeeeffff0000"); - private static final DestinationName DLQ = new DestinationName("orders.v1.dlq"); - private static final DestinationName ORDERS = new DestinationName("orders.v1"); - - private static final HmacApprovalVerifier ISSUER = - new HmacApprovalVerifier( - "an-issuing-key-of-at-least-32-bytes!".getBytes(StandardCharsets.UTF_8)); - - private static final HmacApprovalVerifier ANOTHER_ISSUER = - new HmacApprovalVerifier( - "a-different-key-of-at-least-32-bytes".getBytes(StandardCharsets.UTF_8)); - - @Test - @DisplayName("a verified approval cannot be constructed outside the verifier") - void aVerifiedApprovalCannotBeConstructedOutsideTheVerifier() { - // Written as a reflection probe because the property is about the type's shape, not its - // behaviour: if a public constructor or factory ever appears, every other test here becomes - // decorative. - assertThat(VerifiedApproval.class.getConstructors()) - .as("a public constructor would let any caller mint an approval for itself") - .isEmpty(); - assertThat( - java.util.Arrays.stream(VerifiedApproval.class.getDeclaredMethods()) - .filter(method -> java.lang.reflect.Modifier.isStatic(method.getModifiers())) - .filter(method -> java.lang.reflect.Modifier.isPublic(method.getModifiers())) - .toList()) - .as("nor may a public static factory") - .isEmpty(); - } - - @Test - @DisplayName("an unsigned or altered grant does not verify") - void anAlteredGrantDoesNotVerify() { - RedrivePlan plan = plan(50, 0); - ApprovalGrant signed = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 50); - String signature = ISSUER.sign(signed); - - ApprovalGrant raised = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 5_000); - - assertThatThrownBy(() -> ISSUER.verify(raised, signature, plan.digest(), NOW)) - .as("raising the impact ceiling after the approver signed it") - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("does not verify"); - } - - @Test - @DisplayName("a signature from another issuer does not verify") - void aSignatureFromAnotherIssuerDoesNotVerify() { - RedrivePlan plan = plan(50, 0); - ApprovalGrant granted = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 50); - - assertThatThrownBy( - () -> ISSUER.verify(granted, ANOTHER_ISSUER.sign(granted), plan.digest(), NOW)) - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("does not verify"); - } - - @Test - @DisplayName("an approval for one plan cannot execute another") - void anApprovalForOnePlanCannotExecuteAnother() { - RedrivePlan approvedPlan = plan(50, 0); - RedrivePlan biggerPlan = plan(900, 0); - ApprovalGrant granted = grant(approvedPlan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 900); - String signature = ISSUER.sign(granted); - - assertThatThrownBy(() -> ISSUER.verify(granted, signature, biggerPlan.digest(), NOW)) - .as("the approver saw 50 candidates; this plan moves 900") - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("was issued for plan"); - } - - @Test - @DisplayName("a verified approval for the wrong source cannot be attached to a plan") - void aVerifiedApprovalForTheWrongSourceCannotBeAttached() { - RedrivePlan plan = plan(50, 0); - // A genuine, correctly-signed approval — for a different dead-letter destination, with this - // plan's digest smuggled in. The digest check passes; the source binding is what catches it. - ApprovalGrant granted = - new ApprovalGrant( - approval(), - "operator@example.com", - DestructiveOperation.REDRIVE, - new DestinationName("payments.v1.dlq"), - Optional.of(ORDERS), - "v1", - 900, - plan.digest()); - VerifiedApproval verified = ISSUER.verify(granted, ISSUER.sign(granted), plan.digest(), NOW); - - assertThatThrownBy(() -> new ApprovedRedrivePlan(plan, verified, false)) - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("payments.v1.dlq"); - } - - @Test - @DisplayName("a plan beyond the approved impact ceiling cannot execute") - void aPlanBeyondTheApprovedImpactCeilingCannotExecute() { - RedrivePlan plan = plan(900, 0); - ApprovalGrant granted = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 100); - VerifiedApproval verified = ISSUER.verify(granted, ISSUER.sign(granted), plan.digest(), NOW); - - assertThatThrownBy(() -> new ApprovedRedrivePlan(plan, verified, false)) - .as("the approver agreed to at most 100") - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("at most 100"); - } - - @Test - @DisplayName("an approval for a replay cannot authorise a redrive") - void anApprovalForAReplayCannotAuthoriseARedrive() { - RedrivePlan plan = plan(50, 0); - ApprovalGrant granted = grant(plan, DestructiveOperation.REPLAY, DLQ, ORDERS, 900); - VerifiedApproval verified = ISSUER.verify(granted, ISSUER.sign(granted), plan.digest(), NOW); - - assertThatThrownBy(() -> new ApprovedRedrivePlan(plan, verified, false)) - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("authorises REPLAY"); - } - - @Test - @DisplayName("an expired grant does not verify") - void anExpiredGrantDoesNotVerify() { - RedrivePlan plan = plan(50, 0); - ApprovalGrant granted = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 50); - - assertThatThrownBy( - () -> - ISSUER.verify( - granted, ISSUER.sign(granted), plan.digest(), NOW.plus(Duration.ofDays(1)))) - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("not valid at"); - } - - @Test - @DisplayName("the approver and the operator must be different people") - void theApproverAndTheOperatorMustBeDifferentPeople() { - RedrivePlan plan = plan(50, 0); - - assertThatThrownBy( - () -> - new ApprovalGrant( - approval(), - "ops@example.com", - DestructiveOperation.REDRIVE, - DLQ, - Optional.of(ORDERS), - "v1", - 50, - plan.digest())) - .as("an operator approving their own destructive operation is the control not existing") - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - @DisplayName("destructive admin plans can only carry a verified approval") - void destructiveAdminUsesTheUnforgeableApprovalType() { - assertThat( - java.util.Arrays.stream(DestructiveMessagingAdmin.Approved.class.getRecordComponents()) - .filter(component -> component.getName().equals("approval")) - .findFirst() - .orElseThrow() - .getType()) - .isEqualTo(VerifiedApproval.class); - } - - @Test - @DisplayName("a correctly issued approval executes") - void aCorrectlyIssuedApprovalExecutes() { - RedrivePlan plan = plan(50, 0); - ApprovalGrant granted = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 50); - VerifiedApproval verified = ISSUER.verify(granted, ISSUER.sign(granted), plan.digest(), NOW); - - assertThatCode( - () -> new ApprovedRedrivePlan(plan, verified, false).requireExecutable(NOW, "v1")) - .doesNotThrowAnyException(); - } - - private static ApprovalGrant grant( - RedrivePlan plan, - DestructiveOperation operation, - DestinationName source, - DestinationName target, - long maxImpact) { - return new ApprovalGrant( - approval(), - "operator@example.com", - operation, - source, - Optional.of(target), - "v1", - maxImpact, - plan.digest()); - } - - private static AdminApproval approval() { - return new AdminApproval("CHG-1042", "ops@example.com", NOW, NOW.plus(Duration.ofHours(2))); - } - - private static RedrivePlan plan(int candidates, int alreadyRedriven) { - return new RedrivePlan( - new RedriveRequest(OPERATION_ID, DLQ, ORDERS, 50, false), - candidates, - alreadyRedriven, - NOW, - "v1"); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovedPlanExecutionTest.java b/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovedPlanExecutionTest.java deleted file mode 100644 index 02dd2dc8..00000000 --- a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovedPlanExecutionTest.java +++ /dev/null @@ -1,226 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -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.admin.AdminApproval; -import dev.caskeleton.messaging.admin.ApprovalGrant; -import dev.caskeleton.messaging.admin.ApprovedRedrivePlan; -import dev.caskeleton.messaging.admin.ApprovedReplayPlan; -import dev.caskeleton.messaging.admin.DestructiveOperation; -import dev.caskeleton.messaging.admin.HmacApprovalVerifier; -import dev.caskeleton.messaging.admin.PlanDigest; -import dev.caskeleton.messaging.admin.RedrivePlan; -import dev.caskeleton.messaging.admin.RedriveRequest; -import dev.caskeleton.messaging.admin.RedriveResult; -import dev.caskeleton.messaging.admin.ReplayPlan; -import dev.caskeleton.messaging.admin.ReplayRequest; -import dev.caskeleton.messaging.admin.ReplayResult; -import dev.caskeleton.messaging.admin.VerifiedApproval; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessageAuthorizationException; -import java.time.Duration; -import java.time.Instant; -import java.util.Optional; -import java.util.UUID; -import org.junit.jupiter.api.Test; - -class ApprovedPlanExecutionTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:00:00Z"); - private static final UUID OPERATION_ID = UUID.fromString("0199aaaa-bbbb-7ccc-8ddd-eeeeffff0000"); - - private static final byte[] ISSUING_KEY = - "an-issuing-key-of-at-least-32-bytes!".getBytes(java.nio.charset.StandardCharsets.UTF_8); - - private static final HmacApprovalVerifier VERIFIER = new HmacApprovalVerifier(ISSUING_KEY); - - private static AdminApproval approval() { - return new AdminApproval("CHG-1042", "ops@example.com", NOW, NOW.plus(Duration.ofHours(2))); - } - - /** A grant the issuer signed for exactly this plan, verified the way the runtime verifies it. */ - static VerifiedApproval verified( - PlanDigest digest, - DestructiveOperation operation, - DestinationName source, - Optional target, - String topologyVersion, - long maxImpact) { - ApprovalGrant grant = - new ApprovalGrant( - approval(), - "operator@example.com", - operation, - source, - target, - topologyVersion, - maxImpact, - digest); - return VERIFIER.verify(grant, VERIFIER.sign(grant), digest, NOW); - } - - private static VerifiedApproval replayApproval(ReplayPlan plan) { - return verified( - plan.digest(), - DestructiveOperation.REPLAY, - plan.request().destination(), - Optional.empty(), - plan.topologyVersion(), - Long.MAX_VALUE); - } - - private static VerifiedApproval redriveApproval(RedrivePlan plan) { - return verified( - plan.digest(), - DestructiveOperation.REDRIVE, - plan.request().source(), - Optional.of(plan.request().target()), - plan.topologyVersion(), - Long.MAX_VALUE); - } - - private static ReplayRequest replayRequest() { - return new ReplayRequest( - OPERATION_ID, - new DestinationName("orders.v1"), - NOW.minus(Duration.ofDays(1)), - Optional.empty(), - true, - false); - } - - private static ReplayPlan replayPlan(String topologyVersion) { - return new ReplayPlan(replayRequest(), 4_200_000, NOW, topologyVersion, false); - } - - private static RedriveRequest redriveRequest() { - return new RedriveRequest( - OPERATION_ID, - new DestinationName("orders.v1.dlq"), - new DestinationName("orders.v1"), - 50, - false); - } - - private static RedrivePlan redrivePlan(int candidates, int alreadyRedriven) { - return new RedrivePlan(redriveRequest(), candidates, alreadyRedriven, NOW, "v1"); - } - - private static ApprovedReplayPlan approvedReplay(String topologyVersion) { - ReplayPlan plan = replayPlan(topologyVersion); - return new ApprovedReplayPlan(plan, replayApproval(plan)); - } - - private static ApprovedRedrivePlan approvedRedrive(RedrivePlan plan, boolean loopAcknowledged) { - return new ApprovedRedrivePlan(plan, redriveApproval(plan), loopAcknowledged); - } - - @Test - void anExpiredApprovalCannotExecute() { - ApprovedReplayPlan approved = approvedReplay("v1"); - - assertThatThrownBy(() -> approved.requireExecutable(NOW.plus(Duration.ofDays(1)), "v1")) - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("CHG-1042"); - } - - @Test - void aTopologyChangeSinceApprovalInvalidatesThePlan() { - ApprovedReplayPlan approved = approvedReplay("v1"); - - assertThatThrownBy(() -> approved.requireExecutable(NOW, "v2")) - .as("every number in the plan was computed against the old topology") - .isInstanceOf(MessageAuthorizationException.class) - // The signed grant carries the topology version too, so the mismatch is now caught against - // what the approver actually signed rather than against a field on the plan the caller - // handed in. - .hasMessageContaining("was signed against topology v1 but the broker is now at v2"); - } - - @Test - void aValidApprovalOnUnchangedTopologyExecutes() { - assertThatCode(() -> approvedReplay("v1").requireExecutable(NOW, "v1")) - .doesNotThrowAnyException(); - } - - @Test - void aRedriveThatWouldLoopNeedsThatAcknowledgedExplicitly() { - ApprovedRedrivePlan approved = approvedRedrive(redrivePlan(900, 400), false); - - assertThatThrownBy(() -> approved.requireExecutable(NOW, "v1")) - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("looks like progress"); - } - - @Test - void anAcknowledgedLoopMayProceed() { - assertThatCode(() -> approvedRedrive(redrivePlan(900, 400), true).requireExecutable(NOW, "v1")) - .doesNotThrowAnyException(); - } - - @Test - void aRedriveWithNoPreviouslyRedrivenCandidatesNeedsNoAcknowledgement() { - assertThatCode(() -> approvedRedrive(redrivePlan(900, 0), false).requireExecutable(NOW, "v1")) - .doesNotThrowAnyException(); - } - - @Test - void thePlanDescribesItsImpactBeforeAnythingRuns() { - assertThat(replayPlan("v1").describeImpact()).contains("4200000").contains("isolated group"); - assertThat(redrivePlan(900, 400).describeImpact()) - .contains("already failed a previous redrive"); - } - - @Test - void aReplayIntoTheLiveGroupSaysSoInCapitals() { - ReplayPlan live = - new ReplayPlan( - new ReplayRequest( - OPERATION_ID, - new DestinationName("orders.v1"), - NOW.minus(Duration.ofDays(1)), - Optional.empty(), - false, - false), - 4_200_000, - NOW, - "v1", - true); - - assertThat(live.describeImpact()) - .as("re-delivering millions of messages into the live group is the decision to flag") - .contains("LIVE consumer group"); - } - - @Test - void aReplayResultFlagsAShortfallAgainstTheApprovedEstimate() { - ReplayResult result = - new ReplayResult(OPERATION_ID, 1_000_000, 100_000, Duration.ofMinutes(3), true, false); - - assertThat(result.fellShortOfTheEstimate()) - .as("retention may have expired part of the approved window") - .isTrue(); - } - - @Test - void aRedriveResultMustAccountForEveryCandidate() { - RedriveResult accounted = - new RedriveResult(OPERATION_ID, 100, 80, 20, Duration.ofSeconds(4), false); - RedriveResult unaccounted = - new RedriveResult(OPERATION_ID, 100, 80, 10, Duration.ofSeconds(4), false); - - assertThat(accounted.isFullyAccounted()).isTrue(); - assertThat(unaccounted.isFullyAccounted()) - .as("a message that was neither moved nor left parked has been lost track of") - .isFalse(); - } - - @Test - void aDryRunCannotClaimToHaveMovedAnything() { - assertThatThrownBy( - () -> new RedriveResult(OPERATION_ID, 100, 5, 0, Duration.ofSeconds(1), true)) - .isInstanceOf(IllegalArgumentException.class); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/RedriveResumptionTest.java b/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/RedriveResumptionTest.java deleted file mode 100644 index 82412de6..00000000 --- a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/RedriveResumptionTest.java +++ /dev/null @@ -1,212 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.admin.AdminApproval; -import dev.caskeleton.messaging.admin.ApprovalGrant; -import dev.caskeleton.messaging.admin.DestructiveOperation; -import dev.caskeleton.messaging.admin.DestructiveOperationGuard; -import dev.caskeleton.messaging.admin.HmacApprovalVerifier; -import dev.caskeleton.messaging.admin.PlanDigest; -import dev.caskeleton.messaging.admin.RedriveRequest; -import dev.caskeleton.messaging.admin.VerifiedApproval; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.destination.DestinationName; -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.observation.MessagingAuditEvent; -import java.time.Duration; -import java.time.Instant; -import java.util.ArrayList; -import java.util.List; -import java.util.Optional; -import java.util.UUID; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * What a redrive does when one message fails, and what it does the second time round. - * - *

The loop had no per-item boundary. A publisher that threw — a broker refusing the connection - * rather than the message — propagated straight out, so every candidate behind it was abandoned and - * the audit record was never written. The operation left no trace of what it had already moved, and - * a retry started again from the first candidate and republished it. - */ -class RedriveResumptionTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:00:00Z"); - private static final DestinationName DLQ = new DestinationName("orders.v1.dlq"); - private static final DestinationName ORDERS = new DestinationName("orders.v1"); - - private static final HmacApprovalVerifier ISSUER = - new HmacApprovalVerifier( - "an-issuing-key-of-at-least-32-bytes!".getBytes(java.nio.charset.StandardCharsets.UTF_8)); - - private final RecordingSource source = new RecordingSource(); - private final RecordingAudit audit = new RecordingAudit(); - - @Test - @DisplayName("one message that throws does not abandon the ones behind it") - void oneThrowingMessageDoesNotAbandonTheRest() { - List candidates = ids(4); - source.stage(candidates); - RedriveService service = - service( - (messageId, target, redriveId) -> { - if (messageId.equals(candidates.get(1))) { - throw new IllegalStateException("the broker refused the connection"); - } - return confirmed(); - }); - - RedriveReport report = service.redrive(request(), approval(), "operator", NOW); - - assertThat(report.moved()).isEqualTo(3); - assertThat(report.failed()) - .as("the throwing item is a failed item, not a failed pass") - .isEqualTo(1); - assertThat(source.settled) - .containsExactly(candidates.get(0), candidates.get(2), candidates.get(3)); - } - - @Test - @DisplayName("the audit record is written even when the pass does not finish cleanly") - void theAuditRecordIsWrittenEvenOnFailure() { - source.stage(ids(2)); - RedriveService service = - service( - (messageId, target, redriveId) -> { - throw new IllegalStateException("the broker refused the connection"); - }); - - service.redrive(request(), approval(), "operator", NOW); - - assertThat(audit.events) - .as("the record of what moved is what the incident review and the resumed run both read") - .singleElement() - .satisfies(event -> assertThat(event.details()).containsEntry("failed", "2")); - } - - @Test - @DisplayName("a resumed pass does not republish what the first attempt already moved") - void aResumedPassDoesNotRepublishWhatWasAlreadyMoved() { - List candidates = ids(5); - source.stage(candidates); - List republished = new ArrayList<>(); - RedriveService service = - service( - (messageId, target, redriveId) -> { - republished.add(messageId); - return confirmed(); - }); - - RedriveReport report = - service.redrive(request(), approval(), "operator", NOW, 3, completed -> {}); - - assertThat(republished) - .as("republishing a settled message is a duplicate, not a retry") - .containsExactly(candidates.get(3), candidates.get(4)); - assertThat(report.moved()).isEqualTo(2); - } - - @Test - @DisplayName("progress is reported after each item so a crash resumes near where it stopped") - void progressIsReportedAfterEachItem() { - source.stage(ids(3)); - List checkpoints = new ArrayList<>(); - RedriveService service = service((messageId, target, redriveId) -> confirmed()); - - service.redrive(request(), approval(), "operator", NOW, 0, checkpoints::add); - - assertThat(checkpoints).containsExactly(1, 2, 3); - } - - @Test - @DisplayName("resuming past the end of the batch moves nothing") - void resumingPastTheEndOfTheBatchMovesNothing() { - source.stage(ids(2)); - RedriveService service = service((messageId, target, redriveId) -> confirmed()); - - RedriveReport report = - service.redrive(request(), approval(), "operator", NOW, 10, completed -> {}); - - assertThat(report.moved()).isZero(); - } - - private RedriveService service(RedriveService.RedrivePublisher publisher) { - // The guard holds the admin credential and every pass carries a real verified approval: this - // test is about the loop, and a gate that refused would prove nothing about it. - return new RedriveService(new DestructiveOperationGuard(true), source, publisher, audit); - } - - private static Optional approval() { - PlanDigest digest = PlanDigest.ofCanonical("REDRIVE|orders.v1.dlq|orders.v1"); - ApprovalGrant grant = - new ApprovalGrant( - new AdminApproval("CHG-1042", "ops@example.com", NOW, NOW.plus(Duration.ofHours(2))), - "operator@example.com", - DestructiveOperation.REDRIVE, - DLQ, - Optional.of(ORDERS), - "v1", - Long.MAX_VALUE, - digest); - return Optional.of(ISSUER.verify(grant, ISSUER.sign(grant), digest, NOW)); - } - - private static RedriveRequest request() { - return new RedriveRequest(UUID.randomUUID(), DLQ, ORDERS, 50, false); - } - - private static PublishResult confirmed() { - return new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK), - RoutingOutcome.ROUTED, - Optional.empty(), - 1, - Duration.ofMillis(2), - Optional.empty()); - } - - private static List ids(int count) { - List ids = new ArrayList<>(); - for (int index = 0; index < count; index++) { - ids.add(MessageId.newId()); - } - return List.copyOf(ids); - } - - private static final class RecordingSource implements RedriveService.RedriveSource { - - private List staged = List.of(); - private final List settled = new ArrayList<>(); - - private void stage(List ids) { - staged = List.copyOf(ids); - } - - @Override - public List peek(DestinationName destination, int batchSize) { - return staged; - } - - @Override - public void settle(DestinationName destination, MessageId messageId) { - settled.add(messageId); - } - } - - private static final class RecordingAudit implements RedriveService.AuditSink { - - private final List events = new ArrayList<>(); - - @Override - public void record(MessagingAuditEvent event) { - events.add(event); - } - } -} diff --git a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ReplayServiceTest.java b/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ReplayServiceTest.java deleted file mode 100644 index 395ec201..00000000 --- a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ReplayServiceTest.java +++ /dev/null @@ -1,77 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.admin.DestructiveOperationGuard; -import dev.caskeleton.messaging.admin.ReplayRequest; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessageAuthorizationException; -import java.time.Duration; -import java.time.Instant; -import java.util.Optional; -import java.util.UUID; -import java.util.concurrent.atomic.AtomicInteger; -import org.junit.jupiter.api.Test; - -class ReplayServiceTest { - - private static final Instant NOW = Instant.parse("2026-09-21T00:00:00Z"); - private static final DestinationName DESTINATION = new DestinationName("orders.v1"); - - @Test - void callerClaimedIsolationDoesNotBypassApprovalForARealReplay() { - AtomicInteger executions = new AtomicInteger(); - ReplayService service = - new ReplayService( - new DestructiveOperationGuard(true), - request -> { - executions.incrementAndGet(); - return 1; - }, - event -> {}); - - ReplayRequest request = - new ReplayRequest( - UUID.fromString("0199aaaa-bbbb-7ccc-8ddd-eeeeffff1000"), - DESTINATION, - NOW.minus(Duration.ofHours(1)), - Optional.empty(), - true, - false); - - assertThatThrownBy(() -> service.replay(request, Optional.empty(), "operator", NOW)) - .isInstanceOfSatisfying( - MessageAuthorizationException.class, - failure -> assertThat(failure.failure().code()).isEqualTo("APPROVAL_REQUIRED")); - assertThat(executions).hasValue(0); - } - - @Test - void dryRunRemainsApprovalFreeEvenWhenIsolationIsOnlyAnIntentFlag() { - AtomicInteger executions = new AtomicInteger(); - ReplayService service = - new ReplayService( - new DestructiveOperationGuard(true), - request -> { - executions.incrementAndGet(); - return 1; - }, - event -> {}); - - ReplayRequest request = - new ReplayRequest( - UUID.fromString("0199aaaa-bbbb-7ccc-8ddd-eeeeffff1001"), - DESTINATION, - NOW.minus(Duration.ofHours(1)), - Optional.empty(), - true, - true); - - ReplayReport report = service.replay(request, Optional.empty(), "operator", NOW); - - assertThat(report.dryRun()).isTrue(); - assertThat(report.replayed()).isZero(); - assertThat(executions).hasValue(0); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntimeTest.java b/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntimeTest.java deleted file mode 100644 index 2927ac29..00000000 --- a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntimeTest.java +++ /dev/null @@ -1,65 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import static org.assertj.core.api.Assertions.assertThatCode; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.admin.TopologyManifest; -import dev.caskeleton.messaging.api.error.MessageTopologyException; -import java.util.List; -import java.util.Map; -import org.junit.jupiter.api.Test; - -class TopologyValidationRuntimeTest { - - private static final TopologyManifest ORDERS = - new TopologyManifest( - "order-events", "order.events.v1", 6, 3, Map.of("min.insync.replicas", "2")); - - @Test - void aMatchingTopologyValidates() { - TopologyValidationRuntime runtime = - new TopologyValidationRuntime( - name -> - new TopologyValidationRuntime.ObservedTopology( - 6, 3, Map.of("min.insync.replicas", "2"))); - - assertThatCode(() -> runtime.validate(List.of(ORDERS))).doesNotThrowAnyException(); - } - - @Test - void aMissingDestinationFailsStartup() { - TopologyValidationRuntime runtime = new TopologyValidationRuntime(name -> null); - - assertThatThrownBy(() -> runtime.validate(List.of(ORDERS))) - .isInstanceOf(MessageTopologyException.class) - .hasMessageContaining("does not exist"); - } - - @Test - void aWeakenedReplicationSettingFailsStartup() { - TopologyValidationRuntime runtime = - new TopologyValidationRuntime( - name -> - new TopologyValidationRuntime.ObservedTopology( - 6, 3, Map.of("min.insync.replicas", "1"))); - - assertThatThrownBy(() -> runtime.validate(List.of(ORDERS))) - .isInstanceOf(MessageTopologyException.class) - .hasMessageContaining("min.insync.replicas"); - } - - @Test - void everyDifferenceIsReportedAtOnce() { - TopologyValidationRuntime runtime = - new TopologyValidationRuntime( - name -> - new TopologyValidationRuntime.ObservedTopology( - 3, 1, Map.of("min.insync.replicas", "1"))); - - assertThatThrownBy(() -> runtime.validate(List.of(ORDERS))) - .isInstanceOf(MessageTopologyException.class) - .hasMessageContaining("partitions") - .hasMessageContaining("replicationFactor") - .hasMessageContaining("min.insync.replicas"); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidatorTest.java b/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidatorTest.java deleted file mode 100644 index a792ddd6..00000000 --- a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidatorTest.java +++ /dev/null @@ -1,172 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -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.admin.DestinationTopology; -import dev.caskeleton.messaging.admin.TopologyIssue; -import dev.caskeleton.messaging.admin.TopologyManagementMode; -import dev.caskeleton.messaging.admin.TopologyManifest; -import dev.caskeleton.messaging.admin.TopologyValidationReport; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.util.List; -import java.util.Map; -import java.util.Optional; -import org.junit.jupiter.api.Test; - -class TopologyValidatorTest { - - private final TopologyValidator validator = new TopologyValidator(); - - private static TopologyManifest manifest() { - return new TopologyManifest( - "orders.v1", "orders-v1", 12, 3, Map.of("min.insync.replicas", "2")); - } - - private static DestinationTopology observed( - int partitions, int replication, Map config) { - return new DestinationTopology("orders-v1", partitions, replication, config, true); - } - - @Test - void anAgreeingTopologyProducesNoIssues() { - assertThat(validator.compare(manifest(), observed(12, 3, Map.of("min.insync.replicas", "2")))) - .isEmpty(); - } - - @Test - void anAbsentDestinationBlocksStartup() { - List issues = - validator.compare(manifest(), DestinationTopology.absent("orders-v1")); - - assertThat(issues) - .singleElement() - .satisfies( - issue -> { - assertThat(issue.attribute()).isEqualTo("existence"); - assertThat(issue.severity()).isEqualTo(TopologyIssue.Severity.BLOCKING); - }); - } - - @Test - void tooFewPartitionsBlocksBecauseKeysWouldLandDifferently() { - List issues = - validator.compare(manifest(), observed(6, 3, Map.of("min.insync.replicas", "2"))); - - assertThat(issues) - .singleElement() - .satisfies( - issue -> assertThat(issue.severity()).isEqualTo(TopologyIssue.Severity.BLOCKING)); - } - - @Test - void extraPartitionsAreAdvisoryBecauseScalingUpIsLegitimate() { - List issues = - validator.compare(manifest(), observed(24, 3, Map.of("min.insync.replicas", "2"))); - - assertThat(issues) - .singleElement() - .satisfies( - issue -> assertThat(issue.severity()).isEqualTo(TopologyIssue.Severity.ADVISORY)); - } - - @Test - void tooLittleReplicationBlocksBecauseDurabilityIsPromised() { - List issues = - validator.compare(manifest(), observed(12, 1, Map.of("min.insync.replicas", "2"))); - - assertThat(issues) - .singleElement() - .satisfies( - issue -> { - assertThat(issue.attribute()).isEqualTo("replicationFactor"); - assertThat(issue.severity()).isEqualTo(TopologyIssue.Severity.BLOCKING); - }); - } - - @Test - void aMissingRequiredConfigurationEntryBlocks() { - List issues = validator.compare(manifest(), observed(12, 3, Map.of())); - - assertThat(issues) - .singleElement() - .satisfies(issue -> assertThat(issue.actual()).isEqualTo("unset")); - } - - @Test - void everyIssueIsCollectedRatherThanFailingOnTheFirst() { - List issues = validator.compare(manifest(), observed(6, 1, Map.of())); - - assertThat(issues) - .as("discovering the next problem only after a redeploy turns one fix into several") - .hasSize(3); - } - - @Test - void aReportRefusesStartupWhenAnythingBlocks() { - TopologyValidationReport report = - new TopologyValidationReport( - validator.compare(manifest(), observed(12, 1, Map.of("min.insync.replicas", "2"))), 1); - - assertThat(report.isAcceptable()).isFalse(); - assertThatThrownBy(report::requireAcceptable) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("replicationFactor"); - } - - @Test - void anAdvisoryOnlyReportStillStarts() { - TopologyValidationReport report = - new TopologyValidationReport( - validator.compare(manifest(), observed(24, 3, Map.of("min.insync.replicas", "2"))), 1); - - assertThat(report.isAcceptable()).isTrue(); - assertThat(report.advisory()).hasSize(1); - assertThatCode(report::requireAcceptable).doesNotThrowAnyException(); - } - - @Test - void theCompositeValidatorChecksEveryManifest() { - CompositeTopologyValidator composite = - new CompositeTopologyValidator( - new BrokerTopologyInspector() { - @Override - public Optional describe(String physicalName) { - return Optional.empty(); - } - - @Override - public String topologyVersion() { - return "v1"; - } - }); - - TopologyValidationReport report = - composite.validate( - List.of( - manifest(), new TopologyManifest("payments.v1", "payments-v1", 3, 3, Map.of()))); - - assertThat(report.destinationsChecked()).isEqualTo(2); - assertThat(report.blocking()).hasSize(2); - } - - @Test - void autoCreationIsRefusedInProduction() { - assertThatThrownBy(() -> TopologyManagementMode.CREATE_IF_MISSING.requireSafeFor(true)) - .as("a mistyped destination would be created and look exactly like a real one") - .isInstanceOf(MessagingConfigurationException.class); - } - - @Test - void autoCreationIsAllowedOutsideProduction() { - assertThatCode(() -> TopologyManagementMode.CREATE_IF_MISSING.requireSafeFor(false)) - .doesNotThrowAnyException(); - } - - @Test - void validateOnlyIsAlwaysSafe() { - assertThatCode(() -> TopologyManagementMode.VALIDATE_ONLY.requireSafeFor(true)) - .doesNotThrowAnyException(); - } -} diff --git a/src/platforms/messaging/messaging-claim-check/build.gradle b/src/platforms/messaging/messaging-claim-check/build.gradle deleted file mode 100644 index a145cc45..00000000 --- a/src/platforms/messaging/messaging-claim-check/build.gradle +++ /dev/null @@ -1,8 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') - api project(':messaging:messaging-reliability-api') -} diff --git a/src/platforms/messaging/messaging-claim-check/gradle.lockfile b/src/platforms/messaging/messaging-claim-check/gradle.lockfile deleted file mode 100644 index d74807c4..00000000 --- a/src/platforms/messaging/messaging-claim-check/gradle.lockfile +++ /dev/null @@ -1,82 +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.50.0=annotationProcessor,checkstyle,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.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -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.6.1=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.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty=compileClasspath,runtimeClasspath diff --git a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityException.java b/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityException.java deleted file mode 100644 index dbc13832..00000000 --- a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityException.java +++ /dev/null @@ -1,44 +0,0 @@ -package dev.caskeleton.messaging.claimcheck; - -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.error.MessagingException; -import java.io.Serial; -import java.util.Optional; - -/** - * The stored payload does not match the reference the message carried. - * - *

Not retryable. A digest mismatch means the object at that key is not the object the producer - * wrote — the key was reused, the object was overwritten, or something truncated it — and fetching - * it again returns the same wrong bytes. Retrying would only delay the dead-letter. - * - *

Deliberately distinct from "the object is gone". An expired claim check is an operational - * problem with a known cause and a known fix; a digest mismatch means something wrote data nobody - * expected, and the two must not be diagnosed as one. - */ -public class ClaimCheckIntegrityException extends MessagingException { - - @Serial private static final long serialVersionUID = 1L; - - private static final FailureCategory CATEGORY = FailureCategory.POISON_MESSAGE; - - /** - * Creates the exception with a stable code and sanitized message. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - */ - public ClaimCheckIntegrityException(String code, String sanitizedMessage) { - super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty())); - } - - /** - * Creates the exception from an explicit descriptor. - * - * @param failure the sanitized failure description - */ - public ClaimCheckIntegrityException(FailureDescriptor failure) { - super(failure); - } -} diff --git a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityGuard.java b/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityGuard.java deleted file mode 100644 index 461f966a..00000000 --- a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityGuard.java +++ /dev/null @@ -1,71 +0,0 @@ -package dev.caskeleton.messaging.claimcheck; - -import dev.caskeleton.messaging.api.error.MessageValidationException; -import dev.caskeleton.messaging.reliability.ClaimCheckReference; -import java.security.MessageDigest; -import java.security.NoSuchAlgorithmException; -import java.time.Instant; -import java.util.HexFormat; -import java.util.Objects; - -/** - * Verifies a fetched claim check payload before it is handed to a codec. - * - *

A claim check turns one message into two systems that can drift. The payload store has its own - * retention, its own replication, and its own access control, and none of them are coordinated with - * the broker's. So a consumer that fetches bytes and decodes them without checking is trusting - * something the message never proved. - * - *

Both checks fail closed. An expired reference is reported before the fetch, because a - * not-found from the store is ambiguous between "reaped" and "never written". A digest mismatch is - * reported as validation rather than deserialization, because the bytes are not corrupt JSON — they - * are the wrong bytes. - */ -public final class ClaimCheckIntegrityGuard { - - /** - * Verifies a payload against its reference. - * - * @param reference the claim check reference - * @param payload the bytes fetched from the store - * @param now the current instant - * @return the verified payload - * @throws MessageValidationException when the reference expired or the digest does not match - */ - public byte[] verify(ClaimCheckReference reference, byte[] payload, Instant now) { - Objects.requireNonNull(reference, "reference must not be null"); - Objects.requireNonNull(payload, "payload must not be null"); - Objects.requireNonNull(now, "now must not be null"); - - if (reference.isExpired(now)) { - throw new MessageValidationException( - "CLAIM_CHECK_EXPIRED", - "the claim check payload retention expired at " + reference.expiresAt()); - } - if (payload.length != reference.sizeBytes()) { - throw new MessageValidationException( - "CLAIM_CHECK_SIZE_MISMATCH", - "expected " + reference.sizeBytes() + " bytes but read " + payload.length); - } - String actual = sha256(payload); - if (!actual.equals(reference.sha256())) { - throw new MessageValidationException( - "CLAIM_CHECK_DIGEST_MISMATCH", "the fetched payload does not match its reference digest"); - } - return payload.clone(); - } - - /** - * Returns the lowercase hex SHA-256 of a payload. - * - * @param payload the bytes to digest - * @return the digest - */ - public static String sha256(byte[] payload) { - try { - return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(payload)); - } catch (NoSuchAlgorithmException exception) { - throw new IllegalStateException("Java runtime does not provide SHA-256", exception); - } - } -} diff --git a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckPolicy.java b/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckPolicy.java deleted file mode 100644 index 7458a4fc..00000000 --- a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckPolicy.java +++ /dev/null @@ -1,89 +0,0 @@ -package dev.caskeleton.messaging.claimcheck; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.time.Duration; -import java.util.Objects; - -/** - * When a payload is offloaded, and how long the object must outlive the message. - * - *

The retention rule is the one that matters. A claim check object deleted while its message is - * still deliverable turns a large message into an undeliverable one — the consumer fetches, gets - * nothing, and the message dead-letters for a reason that has nothing to do with the message. So - * retention must exceed the broker's own retention plus the full retry and dead-letter window, and - * the constructor refuses a configuration where it does not. - * - *

The threshold is separate from the destination's payload limit. Offloading starts well below - * the limit, because the limit is where the broker refuses the message and the threshold is where - * carrying it inline stops being a good idea. - * - * @param thresholdBytes the encoded size above which a payload is offloaded - * @param retention how long the stored object must remain readable - * @param brokerRetention how long the broker keeps the message - * @param maxRedeliveryWindow the longest retry and dead-letter path a message can take - */ -public record ClaimCheckPolicy( - int thresholdBytes, - Duration retention, - Duration brokerRetention, - Duration maxRedeliveryWindow) { - - /** The default offload threshold: a quarter of the portable payload limit. */ - public static final int DEFAULT_THRESHOLD_BYTES = 262_144; - - public ClaimCheckPolicy { - Objects.requireNonNull(retention, "retention must not be null"); - Objects.requireNonNull(brokerRetention, "brokerRetention must not be null"); - Objects.requireNonNull(maxRedeliveryWindow, "maxRedeliveryWindow must not be null"); - if (thresholdBytes < 1) { - throw new IllegalArgumentException("thresholdBytes must be positive"); - } - requirePositive(retention, "retention"); - requirePositive(brokerRetention, "brokerRetention"); - requirePositive(maxRedeliveryWindow, "maxRedeliveryWindow"); - - Duration required = brokerRetention.plus(maxRedeliveryWindow); - if (retention.compareTo(required) < 0) { - throw new MessagingConfigurationException( - "CLAIM_CHECK_RETENTION_TOO_SHORT", - "claim check retention of %s is below the %s the message can remain deliverable; the " - .formatted(retention, required) - + "object would be reaped while a consumer can still be handed its message"); - } - } - - /** - * Returns a policy for a broker retaining one day with a one-day retry path. - * - * @return the default policy - */ - public static ClaimCheckPolicy defaults() { - return new ClaimCheckPolicy( - DEFAULT_THRESHOLD_BYTES, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1)); - } - - /** - * Reports whether a payload of this size is offloaded. - * - * @param payloadBytes the encoded payload size - * @return true when the payload travels by reference - */ - public boolean shouldOffload(int payloadBytes) { - return payloadBytes > thresholdBytes; - } - - /** - * Returns the shortest retention this deployment allows. - * - * @return the minimum safe retention - */ - public Duration requiredRetention() { - return brokerRetention.plus(maxRedeliveryWindow); - } - - private static void requirePositive(Duration value, String field) { - if (value.isNegative() || value.isZero()) { - throw new IllegalArgumentException(field + " must be positive"); - } - } -} diff --git a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckPublisher.java b/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckPublisher.java deleted file mode 100644 index 630b5035..00000000 --- a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckPublisher.java +++ /dev/null @@ -1,91 +0,0 @@ -package dev.caskeleton.messaging.claimcheck; - -import dev.caskeleton.messaging.reliability.ClaimCheckReference; -import java.util.Objects; -import java.util.Optional; - -/** - * Decides whether a payload travels inline or by reference, and stores it when it does not. - * - *

The object is written before the message is published, and that order is the whole - * design. Publishing first would let a consumer receive a reference to an object that does not - * exist yet — a race that is rare in a test and routine under load, because the broker hop is - * faster than the object store write. - * - *

Nothing here deletes on failure. If the publish is rejected the object is left behind, and the - * retention sweep reclaims it; deleting eagerly would delete the object out from under a publish - * that turned out to be ambiguous rather than rejected. - */ -public final class ClaimCheckPublisher { - - private final ClaimCheckStore store; - private final ClaimCheckPolicy policy; - - /** - * Creates a claim check publisher. - * - * @param store the payload store - * @param policy the offload threshold and retention - */ - public ClaimCheckPublisher(ClaimCheckStore store, ClaimCheckPolicy policy) { - this.store = Objects.requireNonNull(store, "store must not be null"); - this.policy = Objects.requireNonNull(policy, "policy must not be null"); - } - - /** - * Offloads a payload when the policy calls for it. - * - * @param payload the encoded payload bytes - * @return the outcome, carrying either the inline payload or the stored reference - */ - public Offloaded offload(byte[] payload) { - Objects.requireNonNull(payload, "payload must not be null"); - - if (!policy.shouldOffload(payload.length)) { - return new Offloaded(payload.clone(), Optional.empty()); - } - ClaimCheckReference reference = store.put(payload, policy.retention()); - // The published message carries no payload bytes at all, only the reference. Carrying both - // would double the transfer for no benefit and let the two disagree. - return new Offloaded(new byte[0], Optional.of(reference)); - } - - /** - * Returns the policy this publisher applies. - * - * @return the claim check policy - */ - public ClaimCheckPolicy policy() { - return policy; - } - - /** - * What a payload became after the offload decision. - * - * @param payload the payload to publish, empty when offloaded - * @param reference the stored object's reference, present when offloaded - */ - @SuppressWarnings("ArrayRecordComponent") - public record Offloaded(byte[] payload, Optional reference) { - - public Offloaded { - Objects.requireNonNull(payload, "payload must not be null"); - Objects.requireNonNull(reference, "reference must not be null"); - payload = payload.clone(); - } - - @Override - public byte[] payload() { - return payload.clone(); - } - - /** - * Reports whether the payload travels by reference. - * - * @return true when the payload was offloaded - */ - public boolean isOffloaded() { - return reference.isPresent(); - } - } -} diff --git a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckResolver.java b/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckResolver.java deleted file mode 100644 index 02d919f6..00000000 --- a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckResolver.java +++ /dev/null @@ -1,91 +0,0 @@ -package dev.caskeleton.messaging.claimcheck; - -import dev.caskeleton.messaging.api.error.MessageValidationException; -import dev.caskeleton.messaging.reliability.ClaimCheckReference; -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; - -/** - * Fetches an offloaded payload and verifies it before a handler ever sees it. - * - *

Verification is not optional and cannot be skipped by a caller. An object store key is a - * string, and a message carrying the wrong one — through a bug, a replay against a rotated bucket, - * or a deliberate tamper — fetches bytes that decode perfectly into the wrong object. The digest is - * the only thing standing between that and a handler acting on someone else's data. - * - *

Failures are classified rather than merged. An expired reference is an operational problem - * whose fix is a retention change; a digest mismatch means something wrote data nobody expected. - * Both dead-letter the message, but an operator seeing one code should not have to guess which - * happened. - */ -public final class ClaimCheckResolver { - - private final ClaimCheckStore store; - private final ClaimCheckIntegrityGuard guard = new ClaimCheckIntegrityGuard(); - - /** - * Creates a resolver. - * - * @param store the payload store - */ - public ClaimCheckResolver(ClaimCheckStore store) { - this.store = Objects.requireNonNull(store, "store must not be null"); - } - - /** - * Returns the payload a message carries, fetching it when it travels by reference. - * - * @param inline the payload bytes the message carried, empty when it travels by reference - * @param reference the claim check reference, when the message carried one - * @param now the current instant - * @return the payload the handler should see - * @throws ClaimCheckIntegrityException when the stored object is not the one referenced - * @throws MessageValidationException when the reference has expired - */ - public byte[] resolve(byte[] inline, Optional reference, Instant now) { - Objects.requireNonNull(inline, "inline must not be null"); - Objects.requireNonNull(reference, "reference must not be null"); - Objects.requireNonNull(now, "now must not be null"); - - if (reference.isEmpty()) { - return inline.clone(); - } - ClaimCheckReference claimCheck = reference.get(); - - if (claimCheck.isExpired(now)) { - // Checked before fetching. A store that still returns the object past its retention would - // otherwise hide a misconfiguration until the day the sweep caught up. - throw new MessageValidationException( - "CLAIM_CHECK_EXPIRED", - "the claim check retention expired at %s; the object may already be reaped" - .formatted(claimCheck.expiresAt())); - } - - return verify(claimCheck, fetch(claimCheck), now); - } - - private byte[] fetch(ClaimCheckReference reference) { - byte[] fetched = store.get(reference); - if (fetched == null) { - throw new MessageValidationException( - "CLAIM_CHECK_NOT_FOUND", - "no object exists at the referenced key; it was either reaped early or never written"); - } - return fetched; - } - - private byte[] verify(ClaimCheckReference reference, byte[] fetched, Instant now) { - try { - return guard.verify(reference, fetched, now); - } catch (MessageValidationException validation) { - // A size or digest mismatch is a poison message, not a validation failure to be retried: - // fetching the same key again returns the same wrong bytes. - if (validation.failure().code().endsWith("_MISMATCH")) { - throw new ClaimCheckIntegrityException( - validation.failure().code(), validation.failure().sanitizedMessage()); - } - throw validation; - } - } -} diff --git a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckStore.java b/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckStore.java deleted file mode 100644 index 4d10dfe6..00000000 --- a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckStore.java +++ /dev/null @@ -1,32 +0,0 @@ -package dev.caskeleton.messaging.claimcheck; - -import dev.caskeleton.messaging.reliability.ClaimCheckReference; -import java.time.Duration; - -/** Stores and retrieves payloads that are too large to travel through the broker. */ -public interface ClaimCheckStore { - - /** - * Stores a payload and returns its reference. - * - * @param payload the bytes to store - * @param retention how long the object must remain readable - * @return the reference to publish in place of the payload - */ - ClaimCheckReference put(byte[] payload, Duration retention); - - /** - * Fetches a payload, verifying it against its reference. - * - * @param reference the claim check reference - * @return the stored bytes - */ - byte[] get(ClaimCheckReference reference); - - /** - * Deletes a stored payload. - * - * @param reference the claim check reference - */ - void delete(ClaimCheckReference reference); -} diff --git a/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityGuardTest.java b/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityGuardTest.java deleted file mode 100644 index 71a66382..00000000 --- a/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityGuardTest.java +++ /dev/null @@ -1,86 +0,0 @@ -package dev.caskeleton.messaging.claimcheck; - -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.MessageValidationException; -import dev.caskeleton.messaging.reliability.ClaimCheckReference; -import java.nio.charset.StandardCharsets; -import java.time.Instant; -import org.junit.jupiter.api.Test; - -class ClaimCheckIntegrityGuardTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - private static final byte[] PAYLOAD = "a large document".getBytes(StandardCharsets.UTF_8); - - private final ClaimCheckIntegrityGuard guard = new ClaimCheckIntegrityGuard(); - - @Test - void acceptsAPayloadMatchingItsReference() { - ClaimCheckReference reference = - reference(PAYLOAD.length, ClaimCheckIntegrityGuard.sha256(PAYLOAD)); - - assertThat(guard.verify(reference, PAYLOAD, NOW)).isEqualTo(PAYLOAD); - } - - @Test - void rejectsAPayloadWhoseDigestDoesNotMatch() { - ClaimCheckReference reference = - reference( - PAYLOAD.length, - ClaimCheckIntegrityGuard.sha256( - "a different document".getBytes(StandardCharsets.UTF_8))); - - assertThatThrownBy(() -> guard.verify(reference, PAYLOAD, NOW)) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("digest"); - } - - @Test - void rejectsATruncatedPayloadBeforeHashingIt() { - ClaimCheckReference reference = - reference(PAYLOAD.length + 10, ClaimCheckIntegrityGuard.sha256(PAYLOAD)); - - assertThatThrownBy(() -> guard.verify(reference, PAYLOAD, NOW)) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("bytes"); - } - - @Test - void rejectsAnExpiredReferenceBeforeTheFetchIsTrusted() { - ClaimCheckReference reference = - new ClaimCheckReference( - "payloads/o-1", - PAYLOAD.length, - ClaimCheckIntegrityGuard.sha256(PAYLOAD), - NOW.minusSeconds(1)); - - assertThatThrownBy(() -> guard.verify(reference, PAYLOAD, NOW)) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("retention"); - } - - @Test - void aReferenceRequiresALowercaseHexDigest() { - assertThatThrownBy( - () -> new ClaimCheckReference("payloads/o-1", 5, "NOT-A-DIGEST", NOW.plusSeconds(60))) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void theVerifiedPayloadIsACopy() { - ClaimCheckReference reference = - reference(PAYLOAD.length, ClaimCheckIntegrityGuard.sha256(PAYLOAD)); - - byte[] verified = guard.verify(reference, PAYLOAD, NOW); - verified[0] = 'z'; - - assertThatCode(() -> guard.verify(reference, PAYLOAD, NOW)).doesNotThrowAnyException(); - } - - private static ClaimCheckReference reference(long sizeBytes, String sha256) { - return new ClaimCheckReference("payloads/o-1", sizeBytes, sha256, NOW.plusSeconds(3600)); - } -} diff --git a/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckResolverTest.java b/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckResolverTest.java deleted file mode 100644 index 73e82044..00000000 --- a/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckResolverTest.java +++ /dev/null @@ -1,168 +0,0 @@ -package dev.caskeleton.messaging.claimcheck; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.error.MessageValidationException; -import dev.caskeleton.messaging.reliability.ClaimCheckReference; -import java.nio.charset.StandardCharsets; -import java.time.Duration; -import java.time.Instant; -import java.util.HashMap; -import java.util.Map; -import java.util.Optional; -import org.junit.jupiter.api.Test; - -class ClaimCheckResolverTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - private static final byte[] PAYLOAD = "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8); - - /** An in-memory store that can be made to return the wrong bytes on purpose. */ - private static final class FakeStore implements ClaimCheckStore { - - private final Map objects = new HashMap<>(); - private int puts; - - @Override - public ClaimCheckReference put(byte[] payload, Duration retention) { - puts++; - String key = "claim/" + puts; - objects.put(key, payload.clone()); - return new ClaimCheckReference( - key, payload.length, ClaimCheckIntegrityGuard.sha256(payload), NOW.plus(retention)); - } - - @Override - public byte[] get(ClaimCheckReference reference) { - return objects.get(reference.storageKey()); - } - - @Override - public void delete(ClaimCheckReference reference) { - objects.remove(reference.storageKey()); - } - - void overwrite(String key, byte[] replacement) { - objects.put(key, replacement); - } - - int puts() { - return puts; - } - } - - private static byte[] filled(int size) { - byte[] payload = new byte[size]; - java.util.Arrays.fill(payload, (byte) 'x'); - return payload; - } - - @Test - void aSmallPayloadTravelsInlineAndIsNeverStored() { - FakeStore store = new FakeStore(); - ClaimCheckPublisher publisher = new ClaimCheckPublisher(store, ClaimCheckPolicy.defaults()); - - ClaimCheckPublisher.Offloaded offloaded = publisher.offload(PAYLOAD); - - assertThat(offloaded.isOffloaded()).isFalse(); - assertThat(store.puts()).isZero(); - } - - @Test - void aLargePayloadIsStoredAndTheMessageCarriesNoBytes() { - FakeStore store = new FakeStore(); - ClaimCheckPublisher publisher = new ClaimCheckPublisher(store, ClaimCheckPolicy.defaults()); - - ClaimCheckPublisher.Offloaded offloaded = - publisher.offload(filled(ClaimCheckPolicy.DEFAULT_THRESHOLD_BYTES + 1)); - - assertThat(offloaded.isOffloaded()).isTrue(); - assertThat(offloaded.payload().length) - .as("carrying both would double the transfer and let the two disagree") - .isZero(); - } - - @Test - void anOffloadedPayloadRoundTripsThroughTheStore() { - FakeStore store = new FakeStore(); - ClaimCheckPolicy policy = - new ClaimCheckPolicy(8, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1)); - ClaimCheckPublisher.Offloaded offloaded = - new ClaimCheckPublisher(store, policy).offload(PAYLOAD); - - byte[] resolved = - new ClaimCheckResolver(store).resolve(offloaded.payload(), offloaded.reference(), NOW); - - assertThat(resolved).isEqualTo(PAYLOAD); - } - - @Test - void anInlinePayloadIsReturnedWithoutTouchingTheStore() { - FakeStore store = new FakeStore(); - - byte[] resolved = new ClaimCheckResolver(store).resolve(PAYLOAD, Optional.empty(), NOW); - - assertThat(resolved).isEqualTo(PAYLOAD); - } - - @Test - void anObjectThatWasSwappedUnderTheReferenceIsAPoisonMessage() { - FakeStore store = new FakeStore(); - ClaimCheckPolicy policy = - new ClaimCheckPolicy(8, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1)); - ClaimCheckPublisher.Offloaded offloaded = - new ClaimCheckPublisher(store, policy).offload(PAYLOAD); - store.overwrite( - offloaded.reference().orElseThrow().storageKey(), - "{\"orderId\":\"SOMEONE-ELSE\"}".getBytes(StandardCharsets.UTF_8)); - - assertThatThrownBy( - () -> - new ClaimCheckResolver(store) - .resolve(offloaded.payload(), offloaded.reference(), NOW)) - .as("the digest is the only thing between a swapped object and the wrong data") - .isInstanceOf(ClaimCheckIntegrityException.class); - } - - @Test - void anIntegrityFailureIsNotRetryableBecauseTheKeyReturnsTheSameBytes() { - ClaimCheckIntegrityException failure = - new ClaimCheckIntegrityException("CLAIM_CHECK_DIGEST_MISMATCH", "swapped"); - - assertThat(failure.failure().retryable()).isFalse(); - } - - @Test - void amissingObjectIsReportedSeparatelyFromASwappedOne() { - FakeStore store = new FakeStore(); - ClaimCheckPolicy policy = - new ClaimCheckPolicy(8, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1)); - ClaimCheckPublisher.Offloaded offloaded = - new ClaimCheckPublisher(store, policy).offload(PAYLOAD); - store.delete(offloaded.reference().orElseThrow()); - - assertThatThrownBy( - () -> - new ClaimCheckResolver(store) - .resolve(offloaded.payload(), offloaded.reference(), NOW)) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("never written"); - } - - @Test - void anExpiredReferenceIsRefusedBeforeTheStoreIsEvenAsked() { - FakeStore store = new FakeStore(); - ClaimCheckReference expired = - new ClaimCheckReference( - "claim/1", - PAYLOAD.length, - ClaimCheckIntegrityGuard.sha256(PAYLOAD), - NOW.minus(Duration.ofHours(1))); - - assertThatThrownBy( - () -> new ClaimCheckResolver(store).resolve(new byte[0], Optional.of(expired), NOW)) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("expired"); - } -} diff --git a/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckRetentionValidatorTest.java b/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckRetentionValidatorTest.java deleted file mode 100644 index 50fc16ac..00000000 --- a/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckRetentionValidatorTest.java +++ /dev/null @@ -1,79 +0,0 @@ -package dev.caskeleton.messaging.claimcheck; - -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 java.time.Duration; -import org.junit.jupiter.api.Test; - -class ClaimCheckRetentionValidatorTest { - - @Test - void retentionShorterThanTheMessageLifetimeIsRefused() { - assertThatThrownBy( - () -> - new ClaimCheckPolicy( - 1024, Duration.ofHours(6), Duration.ofDays(1), Duration.ofDays(1))) - .as("the object would be reaped while a consumer can still be handed its message") - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("reaped"); - } - - @Test - void retentionCoveringBrokerRetentionPlusTheRetryPathIsAccepted() { - assertThatCode( - () -> - new ClaimCheckPolicy( - 1024, Duration.ofDays(2), Duration.ofDays(1), Duration.ofDays(1))) - .doesNotThrowAnyException(); - } - - @Test - void theRequiredRetentionIsBrokerRetentionPlusTheRedeliveryWindow() { - ClaimCheckPolicy policy = - new ClaimCheckPolicy(1024, Duration.ofDays(5), Duration.ofDays(2), Duration.ofDays(1)); - - assertThat(policy.requiredRetention()).isEqualTo(Duration.ofDays(3)); - } - - @Test - void theDefaultsSatisfyTheirOwnRule() { - assertThatCode(ClaimCheckPolicy::defaults).doesNotThrowAnyException(); - } - - /** The portable payload limit the platform documents, restated here so the two cannot drift. */ - private static final int PORTABLE_PAYLOAD_LIMIT_BYTES = 1_048_576; - - @Test - void theOffloadThresholdSitsWellBelowThePortablePayloadLimit() { - assertThat(ClaimCheckPolicy.DEFAULT_THRESHOLD_BYTES) - .as( - "offloading starts where carrying inline stops being wise, not where the broker refuses") - .isLessThan(PORTABLE_PAYLOAD_LIMIT_BYTES); - } - - @Test - void aPayloadAtTheThresholdStillTravelsInline() { - ClaimCheckPolicy policy = ClaimCheckPolicy.defaults(); - - assertThat(policy.shouldOffload(ClaimCheckPolicy.DEFAULT_THRESHOLD_BYTES)).isFalse(); - assertThat(policy.shouldOffload(ClaimCheckPolicy.DEFAULT_THRESHOLD_BYTES + 1)).isTrue(); - } - - @Test - void aNonPositiveDurationIsRefused() { - assertThatThrownBy( - () -> new ClaimCheckPolicy(1024, Duration.ZERO, Duration.ofDays(1), Duration.ofDays(1))) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void aNonPositiveThresholdIsRefused() { - assertThatThrownBy( - () -> - new ClaimCheckPolicy(0, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1))) - .isInstanceOf(IllegalArgumentException.class); - } -} diff --git a/src/platforms/messaging/messaging-cloudevents/build.gradle b/src/platforms/messaging/messaging-cloudevents/build.gradle deleted file mode 100644 index 80f04d9c..00000000 --- a/src/platforms/messaging/messaging-cloudevents/build.gradle +++ /dev/null @@ -1,16 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') - - // api, because CloudEventMapper's public signatures return io.cloudevents.CloudEvent. - // - // Declared `implementation`, the type appeared in this module's public API while the - // dependency was hidden from consumers: an adopter calling the documented method could not - // name its return type without adding CloudEvents to their own build, and Gradle gave them no - // hint why. A type in a public signature is part of the artifact's contract. - api libs.cloudevents.api - implementation libs.cloudevents.core -} diff --git a/src/platforms/messaging/messaging-cloudevents/gradle.lockfile b/src/platforms/messaging/messaging-cloudevents/gradle.lockfile deleted file mode 100644 index de8dcaf3..00000000 --- a/src/platforms/messaging/messaging-cloudevents/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.50.0=annotationProcessor,checkstyle,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.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -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.cloudevents:cloudevents-api:4.0.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.cloudevents:cloudevents-core:4.0.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -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.6.1=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.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-cloudevents/src/main/java/dev/caskeleton/messaging/cloudevents/CloudEventExtensions.java b/src/platforms/messaging/messaging-cloudevents/src/main/java/dev/caskeleton/messaging/cloudevents/CloudEventExtensions.java deleted file mode 100644 index a0b5494e..00000000 --- a/src/platforms/messaging/messaging-cloudevents/src/main/java/dev/caskeleton/messaging/cloudevents/CloudEventExtensions.java +++ /dev/null @@ -1,24 +0,0 @@ -package dev.caskeleton.messaging.cloudevents; - -/** - * The CloudEvents extension attribute names this profile writes. - * - *

CloudEvents requires extension names to be lowercase alphanumeric, which is why these are not - * simply the envelope field names. - */ -public final class CloudEventExtensions { - - /** Carries the envelope's correlation id. */ - public static final String CORRELATION_ID = "correlationid"; - - /** Carries the envelope's causation id. */ - public static final String CAUSATION_ID = "causationid"; - - /** Carries the envelope's schema version. */ - public static final String SCHEMA_VERSION = "schemaversion"; - - /** Carries the envelope's tenant identity. */ - public static final String TENANT_CONTEXT = "tenantcontext"; - - private CloudEventExtensions() {} -} diff --git a/src/platforms/messaging/messaging-cloudevents/src/main/java/dev/caskeleton/messaging/cloudevents/CloudEventMapper.java b/src/platforms/messaging/messaging-cloudevents/src/main/java/dev/caskeleton/messaging/cloudevents/CloudEventMapper.java deleted file mode 100644 index b6d0bf42..00000000 --- a/src/platforms/messaging/messaging-cloudevents/src/main/java/dev/caskeleton/messaging/cloudevents/CloudEventMapper.java +++ /dev/null @@ -1,33 +0,0 @@ -package dev.caskeleton.messaging.cloudevents; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.schema.EncodedMessage; -import io.cloudevents.CloudEvent; -import java.net.URI; - -/** - * Maps between the platform envelope and CloudEvents 1.0.2. - * - *

Offered for domain and integration events only. Commands and work items are not forced through - * CloudEvents: they are internal contracts where the interoperability the specification buys does - * not pay for the attributes it requires. - */ -public interface CloudEventMapper { - - /** - * Converts an envelope to a CloudEvent. - * - * @param envelope the envelope carrying an already-encoded payload - * @param source the event source URI - * @return the CloudEvent - */ - CloudEvent toCloudEvent(MessageEnvelope envelope, URI source); - - /** - * Converts a CloudEvent back to an envelope. - * - * @param event the CloudEvent - * @return an envelope whose payload is the still-encoded data - */ - MessageEnvelope fromCloudEvent(CloudEvent event); -} diff --git a/src/platforms/messaging/messaging-cloudevents/src/main/java/dev/caskeleton/messaging/cloudevents/DefaultCloudEventMapper.java b/src/platforms/messaging/messaging-cloudevents/src/main/java/dev/caskeleton/messaging/cloudevents/DefaultCloudEventMapper.java deleted file mode 100644 index 5d64692a..00000000 --- a/src/platforms/messaging/messaging-cloudevents/src/main/java/dev/caskeleton/messaging/cloudevents/DefaultCloudEventMapper.java +++ /dev/null @@ -1,171 +0,0 @@ -package dev.caskeleton.messaging.cloudevents; - -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.error.MessageValidationException; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.schema.EncodedMessage; -import io.cloudevents.CloudEvent; -import io.cloudevents.CloudEventData; -import io.cloudevents.core.builder.CloudEventBuilder; -import io.cloudevents.core.data.BytesCloudEventData; -import java.net.URI; -import java.time.Instant; -import java.time.OffsetDateTime; -import java.time.ZoneOffset; -import java.util.Objects; -import java.util.Optional; -import java.util.UUID; - -/** - * The CloudEvents 1.0.2 compatible profile. - * - *

Two mapping decisions are deliberate. An event without {@code occurredAt} is rejected rather - * than defaulted to the production instant, because {@code time} is read downstream as when the - * fact happened, not when the platform got around to serialising it. And an event with no data maps - * to an envelope with empty bytes, never to a Kafka null value: a tombstone deletes a key, and - * inventing one from an absent CloudEvent payload would turn an empty notification into a deletion. - */ -public final class DefaultCloudEventMapper implements CloudEventMapper { - - private static final String SPEC_CONTENT_TYPE_FALLBACK = "application/json"; - - @Override - public CloudEvent toCloudEvent(MessageEnvelope envelope, URI source) { - Objects.requireNonNull(envelope, "envelope must not be null"); - Objects.requireNonNull(source, "source must not be null"); - - Instant occurredAt = - envelope - .occurredAt() - .orElseThrow( - () -> - new MessageValidationException( - "CLOUDEVENT_TIME_REQUIRED", - "an event mapped to CloudEvents requires occurredAt")); - - CloudEventBuilder builder = - CloudEventBuilder.v1() - .withId(envelope.messageId().value().toString()) - .withSource(source) - .withType(envelope.messageType().value()) - .withTime(OffsetDateTime.ofInstant(occurredAt, ZoneOffset.UTC)) - .withDataContentType(envelope.contentType().value()) - .withExtension( - CloudEventExtensions.SCHEMA_VERSION, - Integer.toString(envelope.schemaVersion().value())); - - envelope - .correlationId() - .ifPresent( - value -> builder.withExtension(CloudEventExtensions.CORRELATION_ID, value.value())); - envelope - .causationId() - .ifPresent( - value -> - builder.withExtension( - CloudEventExtensions.CAUSATION_ID, value.value().value().toString())); - envelope - .tenantContext() - .ifPresent( - value -> builder.withExtension(CloudEventExtensions.TENANT_CONTEXT, value.tenantId())); - - if (envelope.payload() instanceof EncodedMessage encoded) { - encoded - .schemaReference() - .flatMap(reference -> reference.schemaUri()) - .ifPresent(builder::withDataSchema); - builder.withData(BytesCloudEventData.wrap(encoded.bytes())); - } else if (envelope.payload() instanceof byte[] bytes) { - builder.withData(BytesCloudEventData.wrap(bytes.clone())); - } else { - throw new MessageValidationException( - "CLOUDEVENT_PAYLOAD_NOT_ENCODED", - "CloudEvents mapping requires an already-encoded payload"); - } - - return builder.build(); - } - - @Override - public MessageEnvelope fromCloudEvent(CloudEvent event) { - Objects.requireNonNull(event, "event must not be null"); - - OffsetDateTime time = event.getTime(); - if (time == null) { - throw new MessageValidationException( - "CLOUDEVENT_TIME_REQUIRED", "a CloudEvent mapped to an envelope requires time"); - } - - ContentType contentType = - new ContentType( - Optional.ofNullable(event.getDataContentType()).orElse(SPEC_CONTENT_TYPE_FALLBACK)); - CloudEventData data = event.getData(); - byte[] bytes = data == null ? new byte[0] : data.toBytes(); - - Instant occurredAt = time.toInstant(); - return new MessageEnvelope<>( - new MessageId(UUID.fromString(event.getId())), - new MessageType(event.getType()), - new SchemaVersion(intExtension(event, CloudEventExtensions.SCHEMA_VERSION)), - occurredAt, - Optional.of(occurredAt), - new ProducerId(producerFrom(event.getSource())), - stringExtension(event, CloudEventExtensions.CORRELATION_ID).map(CorrelationId::new), - stringExtension(event, CloudEventExtensions.CAUSATION_ID) - .map(value -> new CausationId(new MessageId(UUID.fromString(value)))), - contentType, - Optional.empty(), - Optional.empty(), - stringExtension(event, CloudEventExtensions.TENANT_CONTEXT).map(TenantContext::new), - TraceContext.none(), - MessageHeaders.empty(), - new EncodedMessage(bytes, contentType, Optional.empty())); - } - - private static Optional stringExtension(CloudEvent event, String name) { - return Optional.ofNullable(event.getExtension(name)).map(Object::toString); - } - - private static int intExtension(CloudEvent event, String name) { - return stringExtension(event, name) - .map( - value -> { - try { - return Integer.valueOf(value); - } catch (NumberFormatException exception) { - throw new MessageValidationException( - "CLOUDEVENT_SCHEMA_VERSION_INVALID", - "schemaversion extension is not an integer", - exception); - } - }) - .orElseThrow( - () -> - new MessageValidationException( - "CLOUDEVENT_SCHEMA_VERSION_REQUIRED", - "schemaversion extension is required by this profile")); - } - - /** - * Derives a bounded producer id from the source URI. - * - *

The last path or scheme-specific segment is used so that a long URI does not become an - * unbounded producer name, which would leak straight into metric tags. - */ - private static String producerFrom(URI source) { - String text = source.toString(); - int separator = Math.max(text.lastIndexOf('/'), text.lastIndexOf(':')); - String candidate = - separator >= 0 && separator + 1 < text.length() ? text.substring(separator + 1) : text; - return candidate.isBlank() ? "unknown" : candidate; - } -} diff --git a/src/platforms/messaging/messaging-cloudevents/src/test/java/dev/caskeleton/messaging/cloudevents/CloudEventMappingTest.java b/src/platforms/messaging/messaging-cloudevents/src/test/java/dev/caskeleton/messaging/cloudevents/CloudEventMappingTest.java deleted file mode 100644 index f82c6da6..00000000 --- a/src/platforms/messaging/messaging-cloudevents/src/test/java/dev/caskeleton/messaging/cloudevents/CloudEventMappingTest.java +++ /dev/null @@ -1,162 +0,0 @@ -package dev.caskeleton.messaging.cloudevents; - -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.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.error.MessageValidationException; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.schema.EncodedMessage; -import io.cloudevents.CloudEvent; -import java.net.URI; -import java.nio.charset.StandardCharsets; -import java.time.Instant; -import java.util.Optional; -import java.util.UUID; -import org.junit.jupiter.api.Test; - -class CloudEventMappingTest { - - private static final URI SOURCE = URI.create("urn:service:order-api"); - - private final DefaultCloudEventMapper mapper = new DefaultCloudEventMapper(); - - @Test - void mapsLogicalIdentityAndExtensions() { - MessageEnvelope envelope = CloudEventFixture.orderCreatedEnvelope(); - - CloudEvent event = mapper.toCloudEvent(envelope, SOURCE); - - assertThat(event.getId()).isEqualTo(envelope.messageId().value().toString()); - assertThat(event.getType()).isEqualTo("order.created"); - assertThat(event.getExtension(CloudEventExtensions.SCHEMA_VERSION)).isEqualTo("1"); - assertThat(event.getSource()).isEqualTo(SOURCE); - assertThat(event.getDataContentType()).isEqualTo("application/json"); - } - - @Test - void mapsCorrelationAndTenantAsExtensions() { - CloudEvent event = mapper.toCloudEvent(CloudEventFixture.orderCreatedEnvelope(), SOURCE); - - assertThat(event.getExtension(CloudEventExtensions.CORRELATION_ID)).isEqualTo("wf-1"); - assertThat(event.getExtension(CloudEventExtensions.TENANT_CONTEXT)).isEqualTo("acme"); - } - - @Test - void mapsOccurredAtToEventTime() { - CloudEvent event = mapper.toCloudEvent(CloudEventFixture.orderCreatedEnvelope(), SOURCE); - - assertThat(event.getTime()).isNotNull(); - assertThat(event.getTime().toInstant()).isEqualTo(Instant.parse("2026-08-10T09:15:00Z")); - } - - @Test - void rejectsAnEventEnvelopeWithoutOccurredAt() { - MessageEnvelope withoutOccurredAt = - CloudEventFixture.envelope(Optional.empty()); - - assertThatThrownBy(() -> mapper.toCloudEvent(withoutOccurredAt, SOURCE)) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("occurredAt"); - } - - @Test - void roundTripsBackToAnEnvelopeWithoutInventingATombstone() { - MessageEnvelope original = CloudEventFixture.orderCreatedEnvelope(); - - MessageEnvelope restored = - mapper.fromCloudEvent(mapper.toCloudEvent(original, SOURCE)); - - assertThat(restored.messageId()).isEqualTo(original.messageId()); - assertThat(restored.messageType()).isEqualTo(original.messageType()); - assertThat(restored.schemaVersion()).isEqualTo(original.schemaVersion()); - assertThat(restored.correlationId()).contains(new CorrelationId("wf-1")); - assertThat(restored.tenantContext()).contains(new TenantContext("acme")); - assertThat(restored.payload().bytes()).isEqualTo(original.payload().bytes()); - } - - @Test - void aCloudEventWithNoDataBecomesAnEmptyPayloadNotANullValue() { - CloudEvent noData = - io.cloudevents.core.builder.CloudEventBuilder.v1() - // A v7 id: MessageId enforces the version it documents, so a v4 arriving from a foreign - // producer is refused here exactly as it would be on the wire. - .withId(dev.caskeleton.messaging.api.MessageId.newId().value().toString()) - .withSource(SOURCE) - .withType("order.created") - .withTime(java.time.OffsetDateTime.parse("2026-08-10T09:15:00Z")) - .withDataContentType("application/json") - .withExtension(CloudEventExtensions.SCHEMA_VERSION, "1") - .build(); - - MessageEnvelope restored = mapper.fromCloudEvent(noData); - - assertThat(restored.payload()).isNotNull(); - assertThat(restored.payload().size()).isZero(); - } - - @Test - void rejectsAnUnencodedPayload() { - MessageEnvelope unencoded = - new MessageEnvelope<>( - MessageId.newId(), - new MessageType("order.created"), - new SchemaVersion(1), - Instant.parse("2026-08-10T09:15:00Z"), - Optional.of(Instant.parse("2026-08-10T09:15:00Z")), - new ProducerId("order-api"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - "not encoded"); - - assertThatThrownBy(() -> mapper.toCloudEvent(unencoded, SOURCE)) - .isInstanceOf(MessageValidationException.class); - } -} - -/** Builds CloudEvents mapping fixtures. */ -final class CloudEventFixture { - - private static final MessageId FIXED_ID = - new MessageId(UUID.fromString("0190f4aa-0000-7000-8000-000000000001")); - - private CloudEventFixture() {} - - static MessageEnvelope orderCreatedEnvelope() { - return envelope(Optional.of(Instant.parse("2026-08-10T09:15:00Z"))); - } - - static MessageEnvelope envelope(Optional occurredAt) { - byte[] payload = "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8); - return new MessageEnvelope<>( - FIXED_ID, - new MessageType("order.created"), - new SchemaVersion(1), - Instant.parse("2026-08-10T09:15:01Z"), - occurredAt, - new ProducerId("order-api"), - Optional.of(new CorrelationId("wf-1")), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.of(new TenantContext("acme")), - TraceContext.none(), - MessageHeaders.empty(), - new EncodedMessage(payload, ContentType.JSON, Optional.empty())); - } -} diff --git a/src/platforms/messaging/messaging-core-api/build.gradle b/src/platforms/messaging/messaging-core-api/build.gradle deleted file mode 100644 index d202f8bf..00000000 --- a/src/platforms/messaging/messaging-core-api/build.gradle +++ /dev/null @@ -1,6 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { -} diff --git a/src/platforms/messaging/messaging-core-api/gradle.lockfile b/src/platforms/messaging/messaging-core-api/gradle.lockfile deleted file mode 100644 index d74807c4..00000000 --- a/src/platforms/messaging/messaging-core-api/gradle.lockfile +++ /dev/null @@ -1,82 +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.50.0=annotationProcessor,checkstyle,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.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -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.6.1=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.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty=compileClasspath,runtimeClasspath diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/CausationId.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/CausationId.java deleted file mode 100644 index 40e64438..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/CausationId.java +++ /dev/null @@ -1,18 +0,0 @@ -package dev.caskeleton.messaging.api; - -import java.util.Objects; - -/** - * Identity of the message that directly caused this one. - * - *

Unlike {@link CorrelationId}, which spans a whole workflow, this points at exactly one - * predecessor and forms the causal edge used when reconstructing a flow. - * - * @param value the predecessor message identity - */ -public record CausationId(MessageId value) { - - public CausationId { - Objects.requireNonNull(value, "causationId value must not be null"); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/ContentType.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/ContentType.java deleted file mode 100644 index 2fcbdba2..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/ContentType.java +++ /dev/null @@ -1,46 +0,0 @@ -package dev.caskeleton.messaging.api; - -import java.util.Locale; - -/** - * Media type of an encoded payload, resolved through the codec registry. - * - * @param value the media type, for example {@code application/json} - */ -public record ContentType(String value) { - - private static final int MAX_LENGTH = 160; - - /** {@code type/subtype} with the optional parameters RFC 9110 allows. */ - private static final java.util.regex.Pattern MEDIA_TYPE = - java.util.regex.Pattern.compile( - "[A-Za-z0-9][A-Za-z0-9!#$%&'*+.^_`|~-]*" - + "/[A-Za-z0-9][A-Za-z0-9!#$%&'*+.^_`|~-]*" - + "(;\\s*[A-Za-z0-9!#$%&'*+.^_`|~-]+=[^;\\s]+)*"); - - /** The Stable default codec's content type. */ - public static final ContentType JSON = new ContentType("application/json"); - - /** Avro binary content type. */ - public static final ContentType AVRO = new ContentType("application/avro"); - - /** Protobuf binary content type. */ - public static final ContentType PROTOBUF = new ContentType("application/x-protobuf"); - - /** Opaque bytes, only reachable through the M2 raw codec. */ - public static final ContentType OCTET_STREAM = new ContentType("application/octet-stream"); - - public ContentType { - if (value == null || value.isBlank() || value.length() > MAX_LENGTH) { - throw new IllegalArgumentException("contentType must contain 1 to 160 characters"); - } - // A media type, not merely a string containing a slash. `a/b/c`, `/json` and `text/` all - // passed the old check and are all rejected by a broker or a codec registry later, with an - // error that names the message rather than the configuration that produced it. - if (!MEDIA_TYPE.matcher(value).matches()) { - throw new IllegalArgumentException( - "contentType must be a type/subtype media type: '" + value + '\''); - } - value = value.toLowerCase(Locale.ROOT); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/CorrelationId.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/CorrelationId.java deleted file mode 100644 index 00b96bfa..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/CorrelationId.java +++ /dev/null @@ -1,24 +0,0 @@ -package dev.caskeleton.messaging.api; - -/** - * Workflow-scoped correlation value shared by every message of one business flow. - * - *

This value is copied onto every message of a flow and onto the header set of every broker the - * flow touches, so it is bounded in {@link WireSafeText UTF-8 bytes} rather than in Java - * characters: the previous 160-character bound admitted a 640-byte value, which a broker with a - * byte-counted header budget rejects at publish time, mid-flow, on a message the caller cannot - * resend under a different identity. - * - * @param value the correlation value, 1 to 160 UTF-8 bytes and free of control characters - */ -public record CorrelationId(String value) { - - private static final int MAX_BYTES = 160; - - public CorrelationId { - if (value == null || value.isBlank()) { - throw new IllegalArgumentException("correlationId must not be blank"); - } - WireSafeText.require(value, "a correlation id", MAX_BYTES); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageEnvelope.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageEnvelope.java deleted file mode 100644 index d5ecaa19..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageEnvelope.java +++ /dev/null @@ -1,181 +0,0 @@ -package dev.caskeleton.messaging.api; - -import dev.caskeleton.messaging.api.header.MessageHeaders; -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; - -/** - * The platform's unit of transfer: identity, provenance, routing intent, and payload. - * - *

The payload is never null. A null Kafka value is a tombstone, which is a distinct - * broker-native operation with different retention semantics, so generalising it into "an envelope - * with no payload" would silently turn a delete into an event on brokers that have no such concept. - * - * @param the payload type - * @param messageId logical identity, preserved across retry, DLQ, and redrive - * @param messageType stable catalog type - * @param schemaVersion payload schema revision - * @param producedAt instant the platform created this envelope - * @param occurredAt instant the business fact occurred; required for events - * @param producer logical producing service - * @param correlationId workflow correlation - * @param causationId directly causing message - * @param contentType codec media type - * @param partitionKey distribution key - * @param orderingKey ordering key - * @param tenantContext bounded tenant identity - * @param traceContext trace propagation values - * @param headers bounded application headers - * @param payload the non-null payload - */ -public record MessageEnvelope( - MessageId messageId, - MessageType messageType, - SchemaVersion schemaVersion, - Instant producedAt, - Optional occurredAt, - ProducerId producer, - Optional correlationId, - Optional causationId, - ContentType contentType, - Optional partitionKey, - Optional orderingKey, - Optional tenantContext, - TraceContext traceContext, - MessageHeaders headers, - T payload) { - - public MessageEnvelope { - Objects.requireNonNull(messageId, "messageId must not be null"); - Objects.requireNonNull(messageType, "messageType must not be null"); - Objects.requireNonNull(schemaVersion, "schemaVersion must not be null"); - Objects.requireNonNull(producedAt, "producedAt must not be null"); - Objects.requireNonNull(occurredAt, "occurredAt must not be null"); - Objects.requireNonNull(producer, "producer must not be null"); - Objects.requireNonNull(correlationId, "correlationId must not be null"); - Objects.requireNonNull(causationId, "causationId must not be null"); - Objects.requireNonNull(contentType, "contentType must not be null"); - Objects.requireNonNull(partitionKey, "partitionKey must not be null"); - Objects.requireNonNull(orderingKey, "orderingKey must not be null"); - Objects.requireNonNull(tenantContext, "tenantContext must not be null"); - Objects.requireNonNull(traceContext, "traceContext must not be null"); - Objects.requireNonNull(headers, "headers must not be null"); - Objects.requireNonNull(payload, "payload must not be null"); - // Both keys are routing input the caller chooses, and both used to be unbounded strings. A - // partition key is hashed by the broker, so an unbounded one is a cost rather than a - // correctness problem; an ordering key is carried on the wire by several bindings, so a - // control character in it is the same injection primitive as in a header. The bound is the - // smallest one every targeted broker accepts. - partitionKey.ifPresent(key -> WireSafeText.require(key, "a partition key", MAX_KEY_BYTES)); - orderingKey.ifPresent(key -> WireSafeText.require(key, "an ordering key", MAX_KEY_BYTES)); - } - - /** The routing-key bound every targeted broker accepts. */ - private static final int MAX_KEY_BYTES = 1024; - - /** - * Returns a copy of this envelope carrying a different payload representation. - * - *

Encoding, decoding, Claim Check offloading, and DLQ forwarding all need this, and every one - * of them must keep {@link #messageId()} intact — which is exactly what this method guarantees by - * construction. - * - * @param the replacement payload type - * @param replacement the new payload - * @return an envelope with identical identity and metadata - */ - public MessageEnvelope withPayload(R replacement) { - return new MessageEnvelope<>( - messageId, - messageType, - schemaVersion, - producedAt, - occurredAt, - producer, - correlationId, - causationId, - contentType, - partitionKey, - orderingKey, - tenantContext, - traceContext, - headers, - replacement); - } - - /** - * Returns a copy of this envelope carrying a different content type. - * - * @param replacement the new content type - * @return an envelope with identical identity and payload - */ - public MessageEnvelope withContentType(ContentType replacement) { - return new MessageEnvelope<>( - messageId, - messageType, - schemaVersion, - producedAt, - occurredAt, - producer, - correlationId, - causationId, - Objects.requireNonNull(replacement, "contentType must not be null"), - partitionKey, - orderingKey, - tenantContext, - traceContext, - headers, - payload); - } - - /** - * Returns a copy of this envelope bound to a tenant. - * - * @param tenant the tenant this message belongs to - * @return an envelope with identical identity and payload - */ - public MessageEnvelope withTenant(TenantContext tenant) { - return new MessageEnvelope<>( - messageId, - messageType, - schemaVersion, - producedAt, - occurredAt, - producer, - correlationId, - causationId, - contentType, - partitionKey, - orderingKey, - Optional.of(Objects.requireNonNull(tenant, "tenant must not be null")), - traceContext, - headers, - payload); - } - - /** - * Returns a copy of this envelope carrying replacement headers. - * - * @param replacement the new headers - * @return an envelope with identical identity and payload - */ - public MessageEnvelope withHeaders(MessageHeaders replacement) { - return new MessageEnvelope<>( - messageId, - messageType, - schemaVersion, - producedAt, - occurredAt, - producer, - correlationId, - causationId, - contentType, - partitionKey, - orderingKey, - tenantContext, - traceContext, - Objects.requireNonNull(replacement, "headers must not be null"), - payload); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageId.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageId.java deleted file mode 100644 index 0d0d73af..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageId.java +++ /dev/null @@ -1,42 +0,0 @@ -package dev.caskeleton.messaging.api; - -import java.util.Objects; -import java.util.UUID; - -/** - * Logical identity of a message. - * - *

This value survives publish retry, broker redelivery, retry destinations, dead lettering, and - * redrive. A new {@code MessageId} is minted only for a genuinely new business fact or command, so - * an Inbox can use it to suppress duplicate side effects. - * - * @param value the UUIDv7 identity - */ -public record MessageId(UUID value) { - - /** The UUID version this identity is documented to carry. */ - private static final int VERSION_7 = 7; - - public MessageId { - Objects.requireNonNull(value, "messageId value must not be null"); - // The type says UUIDv7 and the constructor accepted any UUID, including v4 and the nil UUID. - // Version 7 is what makes the identity time-ordered, which is what the outbox index and every - // "oldest first" claim depend on; a v4 stored in the same column silently defeats both. - if (value.version() != VERSION_7) { - throw new IllegalArgumentException( - "a message identity is UUIDv7 (time-ordered); this is version " + value.version()); - } - if (value.variant() != 2) { - throw new IllegalArgumentException("a message identity must use the RFC 4122 variant"); - } - } - - /** - * Mints a new logical message identity. - * - * @return a fresh time-ordered identity - */ - public static MessageId newId() { - return new MessageId(UuidV7.next()); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageType.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageType.java deleted file mode 100644 index 953757b2..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageType.java +++ /dev/null @@ -1,21 +0,0 @@ -package dev.caskeleton.messaging.api; - -/** - * Stable catalog name of a message, such as {@code order.created}. - * - *

Java class names are deliberately not usable as a message type: renaming or repackaging a - * class must never change the wire contract. - * - * @param value the catalog name, 1 to 240 UTF-8 bytes and free of control characters - */ -public record MessageType(String value) { - - private static final int MAX_BYTES = 240; - - public MessageType { - if (value == null || value.isBlank()) { - throw new IllegalArgumentException("messageType must not be blank"); - } - WireSafeText.require(value, "a message type", MAX_BYTES); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/ProducerId.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/ProducerId.java deleted file mode 100644 index 0bb858a3..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/ProducerId.java +++ /dev/null @@ -1,21 +0,0 @@ -package dev.caskeleton.messaging.api; - -/** - * Logical service identity of the component that produced a message. - * - *

This is a deployment-independent service name, not a host, pod, or connection identity, so - * that it stays a bounded value safe for metric tags. - * - * @param value the service name, 1 to 120 UTF-8 bytes and free of control characters - */ -public record ProducerId(String value) { - - private static final int MAX_BYTES = 120; - - public ProducerId { - if (value == null || value.isBlank()) { - throw new IllegalArgumentException("producerId must not be blank"); - } - WireSafeText.require(value, "a producer id", MAX_BYTES); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/SchemaVersion.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/SchemaVersion.java deleted file mode 100644 index 5c6b46a2..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/SchemaVersion.java +++ /dev/null @@ -1,15 +0,0 @@ -package dev.caskeleton.messaging.api; - -/** - * Monotonic schema revision of a {@link MessageType}. - * - * @param value the revision, starting at 1 - */ -public record SchemaVersion(int value) { - - public SchemaVersion { - if (value < 1) { - throw new IllegalArgumentException("schemaVersion must be positive"); - } - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/TenantContext.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/TenantContext.java deleted file mode 100644 index a71c33cc..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/TenantContext.java +++ /dev/null @@ -1,24 +0,0 @@ -package dev.caskeleton.messaging.api; - -import java.util.regex.Pattern; - -/** - * Bounded tenant identity carried with a message. - * - *

The value is deliberately constrained to a short slug. Tenant identity is one of the few - * envelope fields that observability code is tempted to use as a metric label, and an unbounded - * tenant id turns that into a cardinality explosion. - * - * @param tenantId the tenant slug - */ -public record TenantContext(String tenantId) { - - private static final Pattern VALID = Pattern.compile("[a-z0-9][a-z0-9._-]{0,63}"); - - public TenantContext { - if (tenantId == null || !VALID.matcher(tenantId).matches()) { - throw new IllegalArgumentException( - "tenantId must match [a-z0-9][a-z0-9._-]{0,63}: " + tenantId); - } - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/TraceContext.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/TraceContext.java deleted file mode 100644 index b71623f4..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/TraceContext.java +++ /dev/null @@ -1,155 +0,0 @@ -package dev.caskeleton.messaging.api; - -import java.nio.charset.StandardCharsets; -import java.util.Objects; -import java.util.Optional; -import java.util.regex.Pattern; - -/** - * W3C trace propagation values carried with a message. - * - *

The platform creates and propagates these; handlers do not set them. Keeping them on the - * envelope rather than only in headers means a trace survives an Outbox round trip through the - * database, where broker headers do not exist yet. - * - *

The three values used to be checked for non-nullness and nothing more, which made this record - * a general-purpose string carrier wearing the name of a standard. Anything accepted here is - * written to the {@code traceparent}, {@code tracestate} and {@code baggage} headers of every - * broker the message touches, so an unvalidated value is both a header-injection vector and a - * silent trace break: a collector that cannot parse {@code traceparent} drops the span rather than - * reporting a bad value, and the trace disappears at exactly the hop being investigated. - * - * @param traceparent the {@code traceparent} value when a trace is active - * @param tracestate the {@code tracestate} value when present - * @param baggage the {@code baggage} value when present - */ -public record TraceContext( - Optional traceparent, Optional tracestate, Optional baggage) { - - /** - * {@code version-traceid-spanid-flags}, all lowercase hex, per the W3C Trace Context grammar. - * - *

Uppercase hex is refused rather than folded: the standard defines the field as lowercase, - * and a receiver comparing trace IDs as strings — which collectors do — would treat the two cases - * as two different traces. - */ - private static final Pattern TRACEPARENT = - Pattern.compile("[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}"); - - private static final String ALL_ZERO_TRACE_ID = "0".repeat(32); - - private static final String ALL_ZERO_SPAN_ID = "0".repeat(16); - - /** {@code key=value} or {@code tenant@vendor=value}, per the standard's list-member grammar. */ - private static final Pattern TRACESTATE_MEMBER = - Pattern.compile( - "[a-z0-9][_\\-*/a-z0-9]{0,255}(@[a-z0-9][_\\-*/a-z0-9]{0,13})?=[\\x20-\\x7E&&[^,=]]{0,255}"); - - /** - * The standard's bounds: at most 32 list members, and a field a receiver is allowed to truncate. - */ - private static final int MAX_TRACESTATE_MEMBERS = 32; - - private static final int MAX_TRACESTATE_BYTES = 512; - - /** W3C Baggage bounds: 8192 bytes total across at most 64 members. */ - private static final int MAX_BAGGAGE_BYTES = 8192; - - private static final int MAX_BAGGAGE_MEMBERS = 64; - - public TraceContext { - Objects.requireNonNull(traceparent, "traceparent must not be null"); - Objects.requireNonNull(tracestate, "tracestate must not be null"); - Objects.requireNonNull(baggage, "baggage must not be null"); - traceparent.ifPresent(TraceContext::requireValidTraceparent); - tracestate.ifPresent(TraceContext::requireValidTracestate); - baggage.ifPresent(TraceContext::requireValidBaggage); - if (tracestate.isPresent() && traceparent.isEmpty()) { - // A tracestate without a traceparent is vendor state belonging to no trace. Propagating it - // hands the next hop a key it will attribute to whatever trace that hop starts. - throw new IllegalArgumentException("tracestate must not be present without a traceparent"); - } - } - - private static void requireValidTraceparent(String value) { - if (!TRACEPARENT.matcher(value).matches()) { - throw new IllegalArgumentException( - "traceparent must be version-traceid-spanid-flags in lowercase hex: '" + value + '\''); - } - String version = value.substring(0, 2); - if ("ff".equals(version)) { - // The standard reserves ff and requires a receiver to reject it, rather than treat it as a - // future version to be forwarded. - throw new IllegalArgumentException("traceparent version ff is invalid"); - } - String traceId = value.substring(3, 35); - if (ALL_ZERO_TRACE_ID.equals(traceId)) { - throw new IllegalArgumentException("traceparent carries an all-zero trace id"); - } - String spanId = value.substring(36, 52); - if (ALL_ZERO_SPAN_ID.equals(spanId)) { - throw new IllegalArgumentException("traceparent carries an all-zero parent span id"); - } - } - - private static void requireValidTracestate(String value) { - int bytes = value.getBytes(StandardCharsets.UTF_8).length; - if (bytes > MAX_TRACESTATE_BYTES) { - throw new IllegalArgumentException("tracestate exceeds 512 bytes: " + bytes); - } - String[] members = value.split(",", -1); - if (members.length > MAX_TRACESTATE_MEMBERS) { - throw new IllegalArgumentException( - "tracestate carries more than 32 list members: " + members.length); - } - for (String member : members) { - String trimmed = member.strip(); - if (trimmed.isEmpty()) { - // The grammar permits empty members for forward compatibility; nothing is propagated for - // them, so they are dropped by the receiver rather than being an error here. - continue; - } - if (!TRACESTATE_MEMBER.matcher(trimmed).matches()) { - throw new IllegalArgumentException("tracestate member is not valid: '" + trimmed + '\''); - } - } - } - - private static void requireValidBaggage(String value) { - int bytes = value.getBytes(StandardCharsets.UTF_8).length; - if (bytes > MAX_BAGGAGE_BYTES) { - throw new IllegalArgumentException("baggage exceeds 8192 bytes: " + bytes); - } - WireSafeText.requireNoControls(value, "baggage"); - String[] members = value.split(",", -1); - if (members.length > MAX_BAGGAGE_MEMBERS) { - throw new IllegalArgumentException("baggage carries more than 64 members: " + members.length); - } - for (String member : members) { - String trimmed = member.strip(); - int equals = trimmed.indexOf('='); - if (equals <= 0 || equals == trimmed.length() - 1) { - throw new IllegalArgumentException("baggage member must be key=value: '" + trimmed + '\''); - } - } - } - - /** - * Returns a context with no active trace. - * - * @return an empty trace context - */ - public static TraceContext none() { - return new TraceContext(Optional.empty(), Optional.empty(), Optional.empty()); - } - - /** - * Returns a context carrying only a trace parent. - * - * @param traceparent the {@code traceparent} value - * @return a trace context - */ - public static TraceContext of(String traceparent) { - return new TraceContext(Optional.of(traceparent), Optional.empty(), Optional.empty()); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/UuidV7.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/UuidV7.java deleted file mode 100644 index b5d920d1..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/UuidV7.java +++ /dev/null @@ -1,62 +0,0 @@ -package dev.caskeleton.messaging.api; - -import java.security.SecureRandom; -import java.util.UUID; -import java.util.concurrent.atomic.AtomicLong; - -/** - * Generates RFC 9562 UUIDv7 values. - * - *

The platform needs message identifiers that sort by creation time so that outbox scans, DLQ - * listings, and broker partitions stay locality-friendly, while still being globally unique. The 12 - * bit {@code rand_a} field is used as a monotonic intra-millisecond counter instead of random bits: - * two calls in the same millisecond are then still strictly ordered, which is what makes "same - * logical message keeps the same id" auditable across a retry. - */ -public final class UuidV7 { - - private static final SecureRandom RANDOM = new SecureRandom(); - - /** Packs the 48-bit millisecond timestamp in the high bits and the 12-bit counter in the low. */ - private static final AtomicLong STATE = new AtomicLong(); - - private static final long COUNTER_BITS = 12L; - private static final long COUNTER_MASK = 0xFFFL; - private static final long VERSION_7 = 0x7L; - private static final long VARIANT_RFC9562 = 0x8000_0000_0000_0000L; - private static final long RANDOM_B_MASK = 0x3FFF_FFFF_FFFF_FFFFL; - - private UuidV7() {} - - /** - * Returns the next monotonically increasing UUIDv7. - * - * @return a version 7, variant 2 UUID - */ - public static UUID next() { - long state = STATE.updateAndGet(UuidV7::advance); - long timestamp = state >>> COUNTER_BITS; - long counter = state & COUNTER_MASK; - - long mostSignificantBits = (timestamp << 16) | (VERSION_7 << COUNTER_BITS) | counter; - long leastSignificantBits = (RANDOM.nextLong() & RANDOM_B_MASK) | VARIANT_RFC9562; - return new UUID(mostSignificantBits, leastSignificantBits); - } - - /** - * Advances the packed state. - * - *

When the clock moved forward the counter restarts at zero. Otherwise the packed value is - * simply incremented: that bumps the counter and, once the 12-bit counter overflows, carries into - * the timestamp field. A backwards clock step therefore never produces a duplicate or a - * descending id, it only borrows from the future. - */ - private static long advance(long previous) { - long now = System.currentTimeMillis(); - long previousTimestamp = previous >>> COUNTER_BITS; - if (now > previousTimestamp) { - return now << COUNTER_BITS; - } - return previous + 1; - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/WireSafeText.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/WireSafeText.java deleted file mode 100644 index f919c320..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/WireSafeText.java +++ /dev/null @@ -1,65 +0,0 @@ -package dev.caskeleton.messaging.api; - -import java.nio.charset.StandardCharsets; - -/** - * The one place that decides which text may reach a broker. - * - *

Every wire-facing value used to bound itself in Java {@code char}s and check nothing else. A - * {@code char} count bounds nothing on a wire: a 240-character string is up to 960 UTF-8 bytes, so - * a "240 character" limit is a 960-byte limit against a broker that counts bytes. And a control - * character passes a length check untouched — CR and LF split records on line-oriented protocols, - * NUL truncates them in C string handling inside a broker, and DEL is stripped by some - * intermediaries and preserved by others. A value that survives one broker and corrupts the next is - * worse than a rejected one. - * - *

The rule is refused rather than sanitised on purpose. Silently stripping a CR turns a caller's - * two-line value into a one-line value that no longer means what they wrote, and the caller never - * learns; the broker downstream cannot tell the difference between that and a legitimate value. - * - *

Each copy of this check that lived in its own record was one more place for the rule to drift. - */ -public final class WireSafeText { - - private WireSafeText() {} - - /** - * Refuses text that no broker should be asked to carry. - * - *

Horizontal tab is refused along with the rest of the C0 range. It is legal in an HTTP field - * value, and that is exactly the problem: a header carried over a line-folding binding and the - * same header carried over a length-prefixed one disagree about whether a tab ends the value. - * Nothing in this platform needs a tab in an identifier or a header. - * - * @param value the text to check - * @param what a noun phrase naming the value, used in the failure message - * @param maxBytes the inclusive UTF-8 byte bound - * @throws IllegalArgumentException when the text carries a control character or exceeds the bound - */ - public static void require(String value, String what, int maxBytes) { - requireNoControls(value, what); - int bytes = value.getBytes(StandardCharsets.UTF_8).length; - if (bytes > maxBytes) { - throw new IllegalArgumentException( - what + " exceeds " + maxBytes + " UTF-8 bytes: " + bytes + " bytes"); - } - } - - /** - * Refuses control characters without applying a size bound. - * - * @param value the text to check - * @param what a noun phrase naming the value, used in the failure message - * @throws IllegalArgumentException when the text carries a control character - */ - public static void requireNoControls(String value, String what) { - for (int index = 0; index < value.length(); index++) { - char character = value.charAt(index); - if (character < 0x20 || character == 0x7F) { - throw new IllegalArgumentException( - "%s must not contain control characters (found U+%04X at index %d)" - .formatted(what, (int) character, index)); - } - } - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryContext.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryContext.java deleted file mode 100644 index 2a44d71f..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryContext.java +++ /dev/null @@ -1,36 +0,0 @@ -package dev.caskeleton.messaging.api.delivery; - -import java.time.Instant; -import java.util.Objects; - -/** - * Runtime context handed to a handler alongside a delivery. - * - *

{@code shutdownRequested} is visible to handlers on purpose: during a graceful drain the - * platform stops creating new retry attempts, and a long-running handler that can wind down early - * shortens the drain instead of being cancelled at the deadline. - * - * @param handlerDeadline the instant after which the handler is considered timed out - * @param shutdownRequested whether the consumer has begun draining - * @param consumerId the stable, low-cardinality consumer identity - */ -public record DeliveryContext( - Instant handlerDeadline, boolean shutdownRequested, String consumerId) { - - public DeliveryContext { - Objects.requireNonNull(handlerDeadline, "handlerDeadline must not be null"); - if (consumerId == null || consumerId.isBlank()) { - throw new IllegalArgumentException("consumerId must not be blank"); - } - } - - /** - * Reports whether the handler deadline has passed. - * - * @param now the current instant - * @return true when the deadline has elapsed - */ - public boolean isExpired(Instant now) { - return !now.isBefore(handlerDeadline); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryGuarantee.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryGuarantee.java deleted file mode 100644 index 492247c0..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryGuarantee.java +++ /dev/null @@ -1,18 +0,0 @@ -package dev.caskeleton.messaging.api.delivery; - -/** - * Broker-level delivery guarantee offered by the common contract. - * - *

There is deliberately no {@code EXACTLY_ONCE} constant. No broker delivers exactly-once across - * an external side effect; what real systems provide is at-least-once delivery combined with an - * idempotent or transactional consumer. Naming a guarantee the platform cannot honour would push - * that responsibility out of sight, so the enum stops where the evidence stops. - */ -public enum DeliveryGuarantee { - - /** Delivery may be lost; duplicate suppression is preferred over durability. */ - AT_MOST_ONCE, - - /** Redelivery is possible; durability is preferred over duplicate suppression. */ - AT_LEAST_ONCE -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryMetadata.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryMetadata.java deleted file mode 100644 index 3e107c2f..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryMetadata.java +++ /dev/null @@ -1,46 +0,0 @@ -package dev.caskeleton.messaging.api.delivery; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.publish.BrokerPosition; -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; - -/** - * Transport-side facts about one delivery attempt. - * - *

The first delivery is attempt one, not zero. Off-by-one confusion here directly changes how - * many times a poison message is replayed before it is parked, so the counting rule is fixed at the - * contract rather than left to each adapter. - * - * @param destination the logical destination - * @param deliveryAttempt the attempt number, starting at one - * @param redelivered whether the broker flagged this as a redelivery - * @param brokerPosition the broker coordinate when available - * @param partitionOrQueue the ordering unit when available - * @param consumerGroup the consumer group when applicable - * @param receivedAt when the consumer received the delivery - */ -public record DeliveryMetadata( - DestinationName destination, - int deliveryAttempt, - boolean redelivered, - Optional brokerPosition, - Optional partitionOrQueue, - Optional consumerGroup, - Instant receivedAt) { - - public DeliveryMetadata { - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(brokerPosition, "brokerPosition must not be null"); - Objects.requireNonNull(partitionOrQueue, "partitionOrQueue must not be null"); - Objects.requireNonNull(consumerGroup, "consumerGroup must not be null"); - Objects.requireNonNull(receivedAt, "receivedAt must not be null"); - if (deliveryAttempt < 1) { - throw new IllegalArgumentException("deliveryAttempt counts the first delivery as 1"); - } - if (deliveryAttempt == 1 && redelivered) { - throw new IllegalArgumentException("the first delivery attempt cannot be a redelivery"); - } - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/ExternalSideEffectGuarantee.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/ExternalSideEffectGuarantee.java deleted file mode 100644 index 8ae2a278..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/ExternalSideEffectGuarantee.java +++ /dev/null @@ -1,14 +0,0 @@ -package dev.caskeleton.messaging.api.delivery; - -/** How a handler's external side effect is protected against redelivery. */ -public enum ExternalSideEffectGuarantee { - - /** Nothing protects the side effect; only valid where replay is harmless. */ - NONE, - - /** The handler must make the side effect idempotent itself. */ - IDEMPOTENCY_REQUIRED, - - /** An Inbox row and the side effect commit inside the same database transaction. */ - INBOX_TRANSACTIONAL -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/HandleResult.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/HandleResult.java deleted file mode 100644 index f4cf76f5..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/HandleResult.java +++ /dev/null @@ -1,60 +0,0 @@ -package dev.caskeleton.messaging.api.delivery; - -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import java.util.Objects; - -/** - * What an M1 handler decided about a delivery. - * - *

The handler states an intent; the platform performs the settlement. That split is what keeps - * "acknowledge only after the handler succeeded" a platform invariant rather than something each - * handler has to remember, and it is why no variant here carries a broker acknowledgement handle. - */ -public sealed interface HandleResult - permits HandleResult.Success, HandleResult.Retry, HandleResult.DeadLetter, HandleResult.Reject { - - /** Processing succeeded; the platform may settle the source. */ - record Success() implements HandleResult {} - - /** - * Processing failed in a way that may succeed later. - * - * @param failure the sanitized failure description - */ - record Retry(FailureDescriptor failure) implements HandleResult { - public Retry { - Objects.requireNonNull(failure, "failure must not be null"); - } - } - - /** - * Processing failed permanently; route to the dead letter destination. - * - * @param failure the sanitized failure description - */ - record DeadLetter(FailureDescriptor failure) implements HandleResult { - public DeadLetter { - Objects.requireNonNull(failure, "failure must not be null"); - } - } - - /** - * Discard the message without dead lettering. - * - * @param failure the sanitized failure description - */ - record Reject(FailureDescriptor failure) implements HandleResult { - public Reject { - Objects.requireNonNull(failure, "failure must not be null"); - } - } - - /** - * Returns a successful result. - * - * @return the success variant - */ - static HandleResult success() { - return new Success(); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageDelivery.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageDelivery.java deleted file mode 100644 index ac1bc230..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageDelivery.java +++ /dev/null @@ -1,22 +0,0 @@ -package dev.caskeleton.messaging.api.delivery; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import java.util.Objects; - -/** - * One decoded message handed to a handler. - * - * @param the payload type - * @param message the decoded envelope - * @param metadata transport-side delivery facts - * @param context runtime context for this attempt - */ -public record MessageDelivery( - MessageEnvelope message, DeliveryMetadata metadata, DeliveryContext context) { - - public MessageDelivery { - Objects.requireNonNull(message, "message must not be null"); - Objects.requireNonNull(metadata, "metadata must not be null"); - Objects.requireNonNull(context, "context must not be null"); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java deleted file mode 100644 index 5e3c3c34..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java +++ /dev/null @@ -1,60 +0,0 @@ -package dev.caskeleton.messaging.api.delivery; - -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import java.util.Set; -import java.util.concurrent.CompletionStage; - -/** - * The one consume contract, implemented by ordinary business code. - * - *

Handlers state an outcome and never touch broker acknowledgement APIs. Duplicate delivery is a - * normal condition, not an error: implementations are expected to be idempotent, or to consume a - * destination whose profile declares {@code INBOX_TRANSACTIONAL}, where the platform runs the - * handler inside the inbox reservation's transaction. - * - *

Registering an implementation as a bean is what turns consumption on: the broker starter opens - * a consumer for every destination at least one handler names. There is no second, batch or manual - * settlement contract; the platform settles, after the handler has answered. - * - * @param the payload type - */ -public interface MessageHandler { - - /** - * The destination, message type and payload type this handler consumes. - * - *

A destination may carry several message types; each type has at most one handler. - * - * @return what this handler consumes - */ - MessageDestination destination(); - - /** - * The schema versions of {@link #destination()}'s message type that its payload class reads. - * - *

This declaration is the consumer's whole registration. The platform decodes a delivery only - * against a contract — message type and schema version — it knows the payload class for, and it - * builds that list from the handler beans: each version here, with the destination's message - * type, decodes into the destination's payload class. A service writes no registration code of - * its own, so a handler cannot exist while its messages are dead-lettered as undecodable for want - * of one. - * - *

A version the handler does not name is still refused ({@code SCHEMA_VERSION_NOT_REGISTERED}) - * rather than decoded into a class written for another version. A handler that reads a second - * version says so here when the producer starts sending it. - * - * @return the versions this handler reads; version 1 unless it declares otherwise - */ - default Set schemaVersions() { - return Set.of(new SchemaVersion(1)); - } - - /** - * Handles one delivery. - * - * @param delivery the decoded message and its metadata - * @return a stage completing with the handling outcome - */ - CompletionStage handle(MessageDelivery delivery); -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/OrderingScope.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/OrderingScope.java deleted file mode 100644 index 8ae6dd1b..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/OrderingScope.java +++ /dev/null @@ -1,23 +0,0 @@ -package dev.caskeleton.messaging.api.delivery; - -/** - * The real scope inside which message order is preserved. - * - *

There is deliberately no {@code GLOBAL} constant. Ordering is a property of a partition, a key - * mapping, or a single consumer — never of a whole destination — and advertising a global scope - * would promise something no partitioned broker can keep. - */ -public enum OrderingScope { - - /** No order is promised. */ - NONE, - - /** Order holds across the destination, which requires a single ordering unit. */ - DESTINATION, - - /** Order holds inside one broker partition. */ - PARTITION, - - /** Order holds for one key while its mapping to an ordering unit is stable. */ - KEY -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/ConfirmationRequirement.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/ConfirmationRequirement.java deleted file mode 100644 index e260c916..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/ConfirmationRequirement.java +++ /dev/null @@ -1,20 +0,0 @@ -package dev.caskeleton.messaging.api.destination; - -/** - * The publish confirmation a destination profile demands. - * - *

This is the requested level. What the broker actually supplied is reported separately as a - * confirmation level on the publish evidence, so a profile asking for replication evidence against - * an adapter that can only prove a broker ack fails at startup instead of silently downgrading. - */ -public enum ConfirmationRequirement { - - /** No confirmation is required; only valid for at-most-once profiles. */ - NONE, - - /** The broker must acknowledge receipt. */ - BROKER_ACK, - - /** The broker must acknowledge replication or persistence. */ - REPLICATION_OR_PERSISTENCE_ACK -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationCapabilities.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationCapabilities.java deleted file mode 100644 index fc212e0e..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationCapabilities.java +++ /dev/null @@ -1,26 +0,0 @@ -package dev.caskeleton.messaging.api.destination; - -import java.util.Objects; - -/** - * A capability snapshot bound to one logical destination. - * - *

Capabilities are per destination, not per broker: the same Kafka cluster offers keyed ordering - * on a partitioned topic and none on a share group, and the same RabbitMQ node offers native dead - * lettering only where the queue was declared with one. - * - * @param destination the logical destination - * @param broker the adapter's broker name - * @param capabilities what the adapter can prove for this destination - */ -public record DestinationCapabilities( - DestinationName destination, String broker, MessagingCapabilities capabilities) { - - public DestinationCapabilities { - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(capabilities, "capabilities must not be null"); - if (broker == null || broker.isBlank()) { - throw new IllegalArgumentException("broker must not be blank"); - } - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationKind.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationKind.java deleted file mode 100644 index 7051e788..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationKind.java +++ /dev/null @@ -1,32 +0,0 @@ -package dev.caskeleton.messaging.api.destination; - -/** - * The interaction pattern a destination implements. - * - *

This drives validation rather than transport: an event stream may keep ordering and replay, a - * work queue may not, and a request-reply destination needs a correlation strategy no other kind - * requires. - */ -public enum DestinationKind { - - /** Point-to-point command delivered to exactly one logical handler. */ - ASYNC_COMMAND, - - /** Fact published inside one bounded context. */ - DOMAIN_EVENT, - - /** Fact published across bounded contexts under a stable schema contract. */ - INTEGRATION_EVENT, - - /** Competing consumers draining a shared backlog. */ - WORK_QUEUE, - - /** Fan-out to independent subscribers. */ - PUBLISH_SUBSCRIBE, - - /** Retained, replayable, partitioned log. */ - EVENT_STREAM, - - /** Correlated request and reply, available only as an M2 capability. */ - REQUEST_REPLY -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationName.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationName.java deleted file mode 100644 index c5a12dfb..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationName.java +++ /dev/null @@ -1,24 +0,0 @@ -package dev.caskeleton.messaging.api.destination; - -import java.util.regex.Pattern; - -/** - * Logical name of a destination. - * - *

The pattern excludes {@code :}, {@code /}, and whitespace so that a broker address can never - * be smuggled in as a logical name. {@code topic://orders} has to fail here, otherwise the physical - * mapping owned by the destination profile could be bypassed from application code. - * - * @param value the logical name - */ -public record DestinationName(String value) { - - private static final Pattern VALID = Pattern.compile("[a-z0-9][a-z0-9.-]{0,159}"); - - public DestinationName { - if (value == null || !VALID.matcher(value).matches()) { - throw new IllegalArgumentException( - "destination name must match [a-z0-9][a-z0-9.-]{0,159}: " + value); - } - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/MessageDestination.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/MessageDestination.java deleted file mode 100644 index 253a588f..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/MessageDestination.java +++ /dev/null @@ -1,26 +0,0 @@ -package dev.caskeleton.messaging.api.destination; - -import dev.caskeleton.messaging.api.MessageType; -import java.util.Objects; - -/** - * The application-facing handle for a destination. - * - *

It carries a logical name, the catalog message type, and the payload class — never a topic, - * exchange, queue, or subject. The physical mapping lives in the destination profile, which is what - * lets the same code run against Kafka in production and an in-memory harness in tests. - * - * @param the payload type - * @param name the logical destination name - * @param messageType the catalog message type - * @param payloadType the payload class - */ -public record MessageDestination( - DestinationName name, MessageType messageType, Class payloadType) { - - public MessageDestination { - Objects.requireNonNull(name, "destination name must not be null"); - Objects.requireNonNull(messageType, "destination messageType must not be null"); - Objects.requireNonNull(payloadType, "destination payloadType must not be null"); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/MessagingCapabilities.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/MessagingCapabilities.java deleted file mode 100644 index 44cc6c58..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/MessagingCapabilities.java +++ /dev/null @@ -1,75 +0,0 @@ -package dev.caskeleton.messaging.api.destination; - -import java.util.Collections; -import java.util.EnumSet; -import java.util.Objects; -import java.util.Set; - -/** - * What a broker adapter can actually prove or do. - * - *

The common API does not assume every broker supports every feature. When a profile asks for - * something absent here the platform fails loudly — at startup where possible, otherwise with a - * capability exception — rather than quietly degrading, because a silently weakened guarantee is - * indistinguishable from a working one until the incident. - * - *

A set of named capabilities rather than a row of positional booleans. The record used to take - * twelve booleans in a fixed order, and an adapter declared itself with {@code new - * MessagingCapabilities(true, true, …, false, true)} — a line where swapping two arguments changes - * a guarantee and still compiles. Only the capabilities the platform reads are named: a flag - * nothing consults is a promise nobody checks. - * - * @param supported the capabilities the adapter can prove - */ -public record MessagingCapabilities(Set supported) { - - /** One capability the platform consults before relying on it. */ - public enum Capability { - - /** The destination preserves order inside an ordering unit; required by pause-and-retry. */ - ORDERED_STREAM, - - /** Delivery can be scheduled for a future instant; required by broker-delayed retry. */ - DELAYED_DELIVERY, - - /** The broker suppresses duplicate publishes of a stable id; required by publish dedup. */ - DEDUPLICATED_PUBLISH - } - - public MessagingCapabilities { - Objects.requireNonNull(supported, "supported must not be null"); - supported = - Collections.unmodifiableSet( - supported.isEmpty() ? EnumSet.noneOf(Capability.class) : EnumSet.copyOf(supported)); - } - - /** - * Returns a capability set with nothing enabled. - * - * @return the empty capability set - */ - public static MessagingCapabilities none() { - return new MessagingCapabilities(EnumSet.noneOf(Capability.class)); - } - - /** - * Returns a capability set holding exactly the named capabilities. - * - * @param first the first capability - * @param rest the remaining capabilities - * @return the capability set - */ - public static MessagingCapabilities of(Capability first, Capability... rest) { - return new MessagingCapabilities(EnumSet.of(first, rest)); - } - - /** - * Reports whether the adapter can prove a capability. - * - * @param capability the capability to look up - * @return true when it is supported - */ - public boolean supports(Capability capability) { - return supported.contains(Objects.requireNonNull(capability, "capability must not be null")); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/FailureCategory.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/FailureCategory.java deleted file mode 100644 index c7966aa9..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/FailureCategory.java +++ /dev/null @@ -1,40 +0,0 @@ -package dev.caskeleton.messaging.api.error; - -/** - * The stable classification a retry engine, DLQ router, and dashboard all agree on. - * - *

Categories exist so that retry decisions are made from a declared class of failure rather than - * from exception type matching, which drifts every time a client library is upgraded. - */ -public enum FailureCategory { - - /** Broker or network fault expected to clear on its own. */ - TRANSIENT_INFRASTRUCTURE, - - /** The broker or a downstream applied backpressure or a quota. */ - THROTTLED, - - /** The handler failed in a way that may succeed on redelivery. */ - PROCESSING_TRANSIENT, - - /** The business rejected the message; redelivery cannot help. */ - PERMANENT_BUSINESS, - - /** The message repeatedly destroys its consumer and must be parked. */ - POISON_MESSAGE, - - /** The payload could not be decoded against its schema. */ - DESERIALIZATION, - - /** Broker authentication failed. */ - AUTHENTICATION, - - /** Broker authorization denied the operation. */ - AUTHORIZATION, - - /** The outcome could not be determined. */ - AMBIGUOUS, - - /** The platform or destination is misconfigured. */ - CONFIGURATION -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/FailureDescriptor.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/FailureDescriptor.java deleted file mode 100644 index ff8dd47a..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/FailureDescriptor.java +++ /dev/null @@ -1,88 +0,0 @@ -package dev.caskeleton.messaging.api.error; - -import java.util.Objects; -import java.util.Optional; - -/** - * A sanitized, transportable description of a failure. - * - *

This travels in reserved headers to retry destinations and DLQs, so it deliberately holds no - * payload, no stack trace, no credential, and no actual message key. Stack traces belong in secure - * log storage; a DLQ is read by more people than the log is. - * - * @param category the stable classification - * @param code a stable, machine-readable code - * @param retryable whether automatic retry is permitted - * @param sanitizedMessage a short operator-facing description - * @param exceptionType the originating exception's simple type name, when known - */ -public record FailureDescriptor( - FailureCategory category, - String code, - boolean retryable, - String sanitizedMessage, - Optional exceptionType) { - - private static final int MAX_MESSAGE_LENGTH = 512; - private static final int MAX_CODE_LENGTH = 120; - - public FailureDescriptor { - Objects.requireNonNull(category, "failure category must not be null"); - Objects.requireNonNull(exceptionType, "exceptionType must not be null"); - if (code == null || code.isBlank() || code.length() > MAX_CODE_LENGTH) { - throw new IllegalArgumentException("failure code must contain 1 to 120 characters"); - } - if (sanitizedMessage == null) { - throw new IllegalArgumentException("sanitizedMessage must not be null"); - } - if (sanitizedMessage.length() > MAX_MESSAGE_LENGTH) { - sanitizedMessage = sanitizedMessage.substring(0, MAX_MESSAGE_LENGTH); - } - } - - /** - * Builds a descriptor whose retryability follows the category's default. - * - * @param category the classification - * @param code the stable code - * @param sanitizedMessage the operator-facing description - * @return a descriptor - */ - public static FailureDescriptor of( - FailureCategory category, String code, String sanitizedMessage) { - return new FailureDescriptor( - category, code, defaultRetryable(category), sanitizedMessage, Optional.empty()); - } - - /** - * Reports whether a category is a retry candidate by default. - * - *

Deserialization, authentication, authorization, and configuration failures are never retried - * automatically: each of them fails identically on every redelivery, so retrying only multiplies - * the load while the message is still poison. - * - *

A default, not a rule every descriptor follows. A publish rejection may carry {@code - * retryable = true} with an authentication or authorization category: the broker did not store - * the record, and a credential being rotated or an ACL deployed after the application refuses - * every publish for a few minutes and then stops (the Kafka publish classifier). The - * consumer-side retry engine requires this default as well as the flag unless its policy names - * the category, so redelivery of an unauthorised message is still not retried; only a publisher - * that reads {@link #retryable()} sees the difference. - * - * @param category the classification - * @return true when automatic retry is allowed by default - */ - public static boolean defaultRetryable(FailureCategory category) { - return switch (category) { - case TRANSIENT_INFRASTRUCTURE, THROTTLED, PROCESSING_TRANSIENT -> true; - case PERMANENT_BUSINESS, - POISON_MESSAGE, - DESERIALIZATION, - AUTHENTICATION, - AUTHORIZATION, - AMBIGUOUS, - CONFIGURATION -> - false; - }; - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageAuthorizationException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageAuthorizationException.java deleted file mode 100644 index 5f373006..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageAuthorizationException.java +++ /dev/null @@ -1,49 +0,0 @@ -package dev.caskeleton.messaging.api.error; - -import java.io.Serial; -import java.util.Optional; - -/** The broker denied the operation for these credentials. */ -public class MessageAuthorizationException extends MessagingException { - - @Serial private static final long serialVersionUID = 1L; - - private static final FailureCategory CATEGORY = FailureCategory.AUTHORIZATION; - - /** - * Creates the exception with a stable code and sanitized message. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - */ - public MessageAuthorizationException(String code, String sanitizedMessage) { - super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty())); - } - - /** - * Creates the exception with an originating cause. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - * @param cause the originating throwable - */ - public MessageAuthorizationException(String code, String sanitizedMessage, Throwable cause) { - super( - new FailureDescriptor( - CATEGORY, - code, - false, - sanitizedMessage, - Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())), - cause); - } - - /** - * Creates the exception from an explicit descriptor. - * - * @param failure the sanitized failure description - */ - public MessageAuthorizationException(FailureDescriptor failure) { - super(failure); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageBackpressureException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageBackpressureException.java deleted file mode 100644 index aee51346..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageBackpressureException.java +++ /dev/null @@ -1,40 +0,0 @@ -package dev.caskeleton.messaging.api.error; - -import java.io.Serial; -import java.util.Optional; - -/** - * Admission was refused because the platform is already at its in-flight or buffer ceiling. - * - *

Retryable, and deliberately raised rather than absorbed by an unbounded wait. Blocking the - * caller until a slot frees turns producer-side saturation into thread exhaustion in the calling - * application, which is a far worse failure than a fast rejection the caller can shed or retry. - * - *

Nothing was transmitted when this is thrown, so the message has no ambiguity: the caller may - * resubmit it under the same {@code messageId} without risking a duplicate. - */ -public class MessageBackpressureException extends MessagingException { - - @Serial private static final long serialVersionUID = 1L; - - private static final FailureCategory CATEGORY = FailureCategory.TRANSIENT_INFRASTRUCTURE; - - /** - * Creates the exception with a stable code and sanitized message. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - */ - public MessageBackpressureException(String code, String sanitizedMessage) { - super(new FailureDescriptor(CATEGORY, code, true, sanitizedMessage, Optional.empty())); - } - - /** - * Creates the exception from an explicit descriptor. - * - * @param failure the sanitized failure description - */ - public MessageBackpressureException(FailureDescriptor failure) { - super(failure); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagePublishTimeoutException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagePublishTimeoutException.java deleted file mode 100644 index 959cd7a8..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagePublishTimeoutException.java +++ /dev/null @@ -1,54 +0,0 @@ -package dev.caskeleton.messaging.api.error; - -import java.io.Serial; -import java.util.Optional; - -/** - * The publish deadline expired before a confirmation arrived. - * - *

A timeout is not a rejection. The bytes may already be replicated, so this is classified as - * ambiguous rather than failed. - */ -public class MessagePublishTimeoutException extends MessagingException { - - @Serial private static final long serialVersionUID = 1L; - - private static final FailureCategory CATEGORY = FailureCategory.AMBIGUOUS; - - /** - * Creates the exception with a stable code and sanitized message. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - */ - public MessagePublishTimeoutException(String code, String sanitizedMessage) { - super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty())); - } - - /** - * Creates the exception with an originating cause. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - * @param cause the originating throwable - */ - public MessagePublishTimeoutException(String code, String sanitizedMessage, Throwable cause) { - super( - new FailureDescriptor( - CATEGORY, - code, - false, - sanitizedMessage, - Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())), - cause); - } - - /** - * Creates the exception from an explicit descriptor. - * - * @param failure the sanitized failure description - */ - public MessagePublishTimeoutException(FailureDescriptor failure) { - super(failure); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSchemaIncompatibleException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSchemaIncompatibleException.java deleted file mode 100644 index 5709d961..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSchemaIncompatibleException.java +++ /dev/null @@ -1,49 +0,0 @@ -package dev.caskeleton.messaging.api.error; - -import java.io.Serial; -import java.util.Optional; - -/** The payload's schema is incompatible with the registered contract. */ -public class MessageSchemaIncompatibleException extends MessagingException { - - @Serial private static final long serialVersionUID = 1L; - - private static final FailureCategory CATEGORY = FailureCategory.DESERIALIZATION; - - /** - * Creates the exception with a stable code and sanitized message. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - */ - public MessageSchemaIncompatibleException(String code, String sanitizedMessage) { - super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty())); - } - - /** - * Creates the exception with an originating cause. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - * @param cause the originating throwable - */ - public MessageSchemaIncompatibleException(String code, String sanitizedMessage, Throwable cause) { - super( - new FailureDescriptor( - CATEGORY, - code, - false, - sanitizedMessage, - Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())), - cause); - } - - /** - * Creates the exception from an explicit descriptor. - * - * @param failure the sanitized failure description - */ - public MessageSchemaIncompatibleException(FailureDescriptor failure) { - super(failure); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSerializationException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSerializationException.java deleted file mode 100644 index fce4c892..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSerializationException.java +++ /dev/null @@ -1,49 +0,0 @@ -package dev.caskeleton.messaging.api.error; - -import java.io.Serial; -import java.util.Optional; - -/** The payload could not be encoded or decoded. */ -public class MessageSerializationException extends MessagingException { - - @Serial private static final long serialVersionUID = 1L; - - private static final FailureCategory CATEGORY = FailureCategory.DESERIALIZATION; - - /** - * Creates the exception with a stable code and sanitized message. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - */ - public MessageSerializationException(String code, String sanitizedMessage) { - super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty())); - } - - /** - * Creates the exception with an originating cause. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - * @param cause the originating throwable - */ - public MessageSerializationException(String code, String sanitizedMessage, Throwable cause) { - super( - new FailureDescriptor( - CATEGORY, - code, - false, - sanitizedMessage, - Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())), - cause); - } - - /** - * Creates the exception from an explicit descriptor. - * - * @param failure the sanitized failure description - */ - public MessageSerializationException(FailureDescriptor failure) { - super(failure); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageTooLargeException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageTooLargeException.java deleted file mode 100644 index c62fb934..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageTooLargeException.java +++ /dev/null @@ -1,54 +0,0 @@ -package dev.caskeleton.messaging.api.error; - -import java.io.Serial; -import java.util.Optional; - -/** - * The encoded payload exceeds the destination's byte limit. - * - *

Payloads above the portability limit are expected to use Claim Check rather than a larger - * broker frame, so this failure points at a design choice and never at a transient fault. - */ -public class MessageTooLargeException extends MessagingException { - - @Serial private static final long serialVersionUID = 1L; - - private static final FailureCategory CATEGORY = FailureCategory.PERMANENT_BUSINESS; - - /** - * Creates the exception with a stable code and sanitized message. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - */ - public MessageTooLargeException(String code, String sanitizedMessage) { - super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty())); - } - - /** - * Creates the exception with an originating cause. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - * @param cause the originating throwable - */ - public MessageTooLargeException(String code, String sanitizedMessage, Throwable cause) { - super( - new FailureDescriptor( - CATEGORY, - code, - false, - sanitizedMessage, - Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())), - cause); - } - - /** - * Creates the exception from an explicit descriptor. - * - * @param failure the sanitized failure description - */ - public MessageTooLargeException(FailureDescriptor failure) { - super(failure); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageTopologyException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageTopologyException.java deleted file mode 100644 index 7a156a2e..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageTopologyException.java +++ /dev/null @@ -1,49 +0,0 @@ -package dev.caskeleton.messaging.api.error; - -import java.io.Serial; -import java.util.Optional; - -/** The broker topology does not match the declared manifest. */ -public class MessageTopologyException extends MessagingException { - - @Serial private static final long serialVersionUID = 1L; - - private static final FailureCategory CATEGORY = FailureCategory.CONFIGURATION; - - /** - * Creates the exception with a stable code and sanitized message. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - */ - public MessageTopologyException(String code, String sanitizedMessage) { - super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty())); - } - - /** - * Creates the exception with an originating cause. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - * @param cause the originating throwable - */ - public MessageTopologyException(String code, String sanitizedMessage, Throwable cause) { - super( - new FailureDescriptor( - CATEGORY, - code, - false, - sanitizedMessage, - Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())), - cause); - } - - /** - * Creates the exception from an explicit descriptor. - * - * @param failure the sanitized failure description - */ - public MessageTopologyException(FailureDescriptor failure) { - super(failure); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageValidationException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageValidationException.java deleted file mode 100644 index 56cdcf69..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageValidationException.java +++ /dev/null @@ -1,49 +0,0 @@ -package dev.caskeleton.messaging.api.error; - -import java.io.Serial; -import java.util.Optional; - -/** The envelope failed platform validation before transport. */ -public class MessageValidationException extends MessagingException { - - @Serial private static final long serialVersionUID = 1L; - - private static final FailureCategory CATEGORY = FailureCategory.PERMANENT_BUSINESS; - - /** - * Creates the exception with a stable code and sanitized message. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - */ - public MessageValidationException(String code, String sanitizedMessage) { - super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty())); - } - - /** - * Creates the exception with an originating cause. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - * @param cause the originating throwable - */ - public MessageValidationException(String code, String sanitizedMessage, Throwable cause) { - super( - new FailureDescriptor( - CATEGORY, - code, - false, - sanitizedMessage, - Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())), - cause); - } - - /** - * Creates the exception from an explicit descriptor. - * - * @param failure the sanitized failure description - */ - public MessageValidationException(FailureDescriptor failure) { - super(failure); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingCapabilityUnavailableException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingCapabilityUnavailableException.java deleted file mode 100644 index 84dc2678..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingCapabilityUnavailableException.java +++ /dev/null @@ -1,56 +0,0 @@ -package dev.caskeleton.messaging.api.error; - -import java.io.Serial; -import java.util.Optional; - -/** - * A requested feature is not supported by the destination's adapter. - * - *

Thrown instead of quietly degrading. Downgrading replication evidence to a bare ack, or - * ordered delivery to unordered, produces a system that looks healthy right up to the moment the - * guarantee actually mattered. - */ -public class MessagingCapabilityUnavailableException extends MessagingException { - - @Serial private static final long serialVersionUID = 1L; - - private static final FailureCategory CATEGORY = FailureCategory.CONFIGURATION; - - /** - * Creates the exception with a stable code and sanitized message. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - */ - public MessagingCapabilityUnavailableException(String code, String sanitizedMessage) { - super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty())); - } - - /** - * Creates the exception with an originating cause. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - * @param cause the originating throwable - */ - public MessagingCapabilityUnavailableException( - String code, String sanitizedMessage, Throwable cause) { - super( - new FailureDescriptor( - CATEGORY, - code, - false, - sanitizedMessage, - Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())), - cause); - } - - /** - * Creates the exception from an explicit descriptor. - * - * @param failure the sanitized failure description - */ - public MessagingCapabilityUnavailableException(FailureDescriptor failure) { - super(failure); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingConfigurationException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingConfigurationException.java deleted file mode 100644 index c32678d7..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingConfigurationException.java +++ /dev/null @@ -1,55 +0,0 @@ -package dev.caskeleton.messaging.api.error; - -import java.io.Serial; -import java.util.Optional; - -/** - * The platform or a destination profile is misconfigured. - * - *

Raised at startup wherever possible. A configuration fault discovered at publish time has - * already cost a request, so the destination profile validator promotes as many of these as it can - * to application startup. - */ -public class MessagingConfigurationException extends MessagingException { - - @Serial private static final long serialVersionUID = 1L; - - private static final FailureCategory CATEGORY = FailureCategory.CONFIGURATION; - - /** - * Creates the exception with a stable code and sanitized message. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - */ - public MessagingConfigurationException(String code, String sanitizedMessage) { - super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty())); - } - - /** - * Creates the exception with an originating cause. - * - * @param code the stable failure code - * @param sanitizedMessage the operator-facing description - * @param cause the originating throwable - */ - public MessagingConfigurationException(String code, String sanitizedMessage, Throwable cause) { - super( - new FailureDescriptor( - CATEGORY, - code, - false, - sanitizedMessage, - Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())), - cause); - } - - /** - * Creates the exception from an explicit descriptor. - * - * @param failure the sanitized failure description - */ - public MessagingConfigurationException(FailureDescriptor failure) { - super(failure); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingException.java deleted file mode 100644 index 81b648c4..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingException.java +++ /dev/null @@ -1,66 +0,0 @@ -package dev.caskeleton.messaging.api.error; - -import java.io.Serial; -import java.util.Objects; - -/** - * Root of the platform's stable exception hierarchy. - * - *

Every subclass carries a {@link FailureDescriptor} so that a caller catching the base type can - * still classify and route the failure without matching on exception classes. The message exposed - * here is the sanitized one; nothing on this type carries payload or credentials. - */ -public abstract class MessagingException extends RuntimeException { - - @Serial private static final long serialVersionUID = 1L; - - private final FailureDescriptor failure; - - /** - * Creates an exception from a descriptor. - * - * @param failure the sanitized failure description - */ - protected MessagingException(FailureDescriptor failure) { - super(Objects.requireNonNull(failure, "failure must not be null").sanitizedMessage()); - this.failure = failure; - } - - /** - * Creates an exception from a descriptor and an originating cause. - * - * @param failure the sanitized failure description - * @param cause the originating throwable - */ - protected MessagingException(FailureDescriptor failure, Throwable cause) { - super(Objects.requireNonNull(failure, "failure must not be null").sanitizedMessage(), cause); - this.failure = failure; - } - - /** - * Returns the sanitized failure description. - * - * @return the descriptor - */ - public FailureDescriptor failure() { - return failure; - } - - /** - * Returns the stable classification. - * - * @return the failure category - */ - public FailureCategory category() { - return failure.category(); - } - - /** - * Reports whether automatic retry is permitted. - * - * @return true when retryable - */ - public boolean retryable() { - return failure.retryable(); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/CanonicalEnvelopeHeaders.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/CanonicalEnvelopeHeaders.java deleted file mode 100644 index 4e955264..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/CanonicalEnvelopeHeaders.java +++ /dev/null @@ -1,79 +0,0 @@ -package dev.caskeleton.messaging.api.header; - -import java.util.Locale; -import java.util.Set; - -/** - * Splits the reserved namespace into the part an envelope field already owns and the part that only - * a header can carry. - * - *

{@link ReservedHeaders} answers one question — does the platform own this name — and every - * adapter that asked it treated the whole namespace as forgeable content. That is right for {@code - * msg.id} and wrong for {@code msg.retry-attempt}: the first restates a value the envelope already - * holds, so a header claiming it can only overwrite the canonical one, while the second has no - * envelope field at all and exists precisely to survive a hop through a broker. Refusing both is - * how a retry re-publish becomes an error, and dropping both on the way back is how an attempt - * counter silently restarts at one and a retry budget stops capping anything. - * - *

The split is derived from the envelope's own shape rather than listed by hand per adapter, so - * Kafka and RabbitMQ cannot disagree about which headers are identity and which are bookkeeping — a - * disagreement that would make the same message mean different things on two brokers. - */ -public final class CanonicalEnvelopeHeaders { - - /** - * Reserved names that restate a value the envelope already carries in a field. - * - *

Every one of these is written by the adapter from an envelope field on the way out and read - * back into that field on the way in. A copy of it inside the header map is therefore never the - * source of truth, only a way to disagree with it. - */ - private static final Set ENVELOPE_FIELDS = - Set.of( - ReservedHeaders.MESSAGE_ID, - ReservedHeaders.MESSAGE_TYPE, - ReservedHeaders.SCHEMA_VERSION, - ReservedHeaders.PRODUCER, - ReservedHeaders.PRODUCED_AT, - ReservedHeaders.OCCURRED_AT, - ReservedHeaders.CORRELATION_ID, - ReservedHeaders.CAUSATION_ID, - ReservedHeaders.CONTENT_TYPE, - ReservedHeaders.PARTITION_KEY, - ReservedHeaders.ORDERING_KEY, - ReservedHeaders.TENANT, - ReservedHeaders.TRACEPARENT, - ReservedHeaders.TRACESTATE, - ReservedHeaders.BAGGAGE); - - private CanonicalEnvelopeHeaders() {} - - /** - * Reports whether a header name restates an envelope field. - * - * @param name the header name in any case - * @return true when the envelope already carries this value in a field of its own - */ - public static boolean restatesEnvelopeField(String name) { - return name != null && ENVELOPE_FIELDS.contains(name.toLowerCase(Locale.ROOT)); - } - - /** - * Reports whether a header name is platform bookkeeping that must travel in the header map. - * - * @param name the header name in any case - * @return true for a reserved name with no envelope field behind it - */ - public static boolean isPlatformBookkeeping(String name) { - return ReservedHeaders.isReserved(name) && !restatesEnvelopeField(name); - } - - /** - * Returns the reserved names an envelope field owns. - * - * @return an immutable set of lowercase names - */ - public static Set envelopeFieldNames() { - return ENVELOPE_FIELDS; - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/HeaderName.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/HeaderName.java deleted file mode 100644 index d826ebf3..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/HeaderName.java +++ /dev/null @@ -1,62 +0,0 @@ -package dev.caskeleton.messaging.api.header; - -import java.nio.charset.StandardCharsets; - -/** - * Name of a single message header. - * - *

Header names are compared case-insensitively because brokers disagree on case handling: AMQP - * preserves it, HTTP-style bindings fold it. Storing the name verbatim but normalising for lookup - * keeps a forged {@code MSG.ID} from slipping past the reserved-name check. - * - * @param value the header name as written by the caller - */ -public record HeaderName(String value) { - - private static final int MAX_BYTES = 128; - - /** - * The one grammar a header name may use. - * - *

The previous check was "not blank, at most 128 bytes", which accepted a name containing CR, - * LF, NUL, a colon or leading whitespace. Those are not cosmetic: a newline in a header name is a - * header-injection primitive on any line-oriented protocol, a NUL truncates the name in C string - * handling inside a broker, and a colon is the field separator in several wire formats. A name - * that survives one broker and corrupts the next is worse than a rejected one. - * - *

The character set is the HTTP token set, which every broker this platform targets accepts - * verbatim. - */ - private static final java.util.regex.Pattern TOKEN = - java.util.regex.Pattern.compile("[a-zA-Z0-9!#$%&'*+._|~-]+"); - - public HeaderName { - if (value == null || value.isBlank()) { - throw new IllegalArgumentException("header name must not be blank"); - } - if (!value.equals(value.strip())) { - // Trimming would mean `Authorization ` and `Authorization` are the same name to the - // denylist and different names on the wire, which is precisely how the check was bypassed. - throw new IllegalArgumentException( - "header name must not have leading or trailing whitespace: '" + value + '\''); - } - if (!TOKEN.matcher(value).matches()) { - throw new IllegalArgumentException( - "header name must be an ASCII token; control characters, spaces, colons and non-ASCII" - + " are refused because a broker that accepts one may truncate or split on it"); - } - int bytes = value.getBytes(StandardCharsets.UTF_8).length; - if (bytes > MAX_BYTES) { - throw new IllegalArgumentException("header name exceeds 128 bytes: " + bytes); - } - } - - /** - * Returns the lowercase form used for reserved and secret name matching. - * - * @return the normalised name - */ - public String normalized() { - return value.toLowerCase(java.util.Locale.ROOT); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/HeaderValue.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/HeaderValue.java deleted file mode 100644 index c365fd1d..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/HeaderValue.java +++ /dev/null @@ -1,26 +0,0 @@ -package dev.caskeleton.messaging.api.header; - -import dev.caskeleton.messaging.api.WireSafeText; - -/** - * Value of a single message header. - * - *

The bound used to be the only rule, so a value containing CR, LF or NUL reached the broker - * intact. On a line-oriented binding a CRLF inside a value ends the header and starts a new one the - * caller wrote — the same header-injection primitive as in HTTP, with the broker's own control - * headers as the target. A NUL truncates the value inside a broker that hands it to C string - * handling, so a subscriber receives a prefix of what was published and cannot tell. - * - * @param value the header value, at most 4096 UTF-8 bytes and free of control characters - */ -public record HeaderValue(String value) { - - private static final int MAX_BYTES = 4096; - - public HeaderValue { - if (value == null) { - throw new IllegalArgumentException("header value must not be null"); - } - WireSafeText.require(value, "a header value", MAX_BYTES); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/MessageHeaders.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/MessageHeaders.java deleted file mode 100644 index 21bbc765..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/MessageHeaders.java +++ /dev/null @@ -1,211 +0,0 @@ -package dev.caskeleton.messaging.api.header; - -import java.nio.charset.StandardCharsets; -import java.util.Collections; -import java.util.LinkedHashMap; -import java.util.Locale; -import java.util.Map; -import java.util.Optional; -import java.util.Set; - -/** - * An immutable, bounded header map. - * - *

Two separate factories exist on purpose. {@link #application(Map)} is what business code calls - * and it refuses both reserved and secret names; {@link #platform(Map)} is what adapters call when - * rehydrating an envelope off the wire and it may write reserved names. Secret names are refused in - * both: a credential that reaches a header ends up in broker storage, DLQ dumps, and operator - * tooling, and no downstream redaction can undo that. - */ -public final class MessageHeaders { - - private static final int MAX_COUNT = 64; - private static final int MAX_TOTAL_BYTES = 32_768; - - private static final Set SECRET_NAMES = - Set.of( - "authorization", - "proxy-authorization", - "cookie", - "set-cookie", - "access_token", - "refresh_token", - "api_key", - "password", - "client_secret"); - - /** - * Words that make a header name a credential regardless of what surrounds them. - * - *

Exact-name matching only refuses the spellings someone thought of. {@code x-api-key}, {@code - * auth-token} and {@code db_password} are the same credential leak as {@code authorization} and - * none of them was on the list. Matching whole segments rather than substrings is what keeps - * {@code tokenizer-version} or {@code secretariat-id} from being refused for containing the - * letters of a secret. - */ - private static final Set SECRET_SEGMENTS = - Set.of( - "password", - "passwd", - "secret", - "token", - "credential", - "credentials", - "apikey", - "authorization", - "cookie", - "signature"); - - private static final java.util.regex.Pattern SEGMENT_SEPARATOR = - java.util.regex.Pattern.compile("[._\\-]+"); - - private static final MessageHeaders EMPTY = new MessageHeaders(Map.of()); - - private final Map values; - - private MessageHeaders(Map values) { - this.values = values; - } - - /** - * Returns the empty header map. - * - * @return headers with no entries - */ - public static MessageHeaders empty() { - return EMPTY; - } - - /** - * Validates and copies application-supplied headers. - * - * @param input the caller's headers - * @return an immutable copy - * @throws IllegalArgumentException when a reserved or secret name is present, or a limit is - * exceeded - */ - public static MessageHeaders application(Map input) { - return validateAndCopy(input, false); - } - - /** - * Validates and copies platform-supplied headers, allowing reserved names. - * - * @param input the platform's headers - * @return an immutable copy - * @throws IllegalArgumentException when a secret name is present or a limit is exceeded - */ - public static MessageHeaders platform(Map input) { - return validateAndCopy(input, true); - } - - private static MessageHeaders validateAndCopy( - Map input, boolean reservedAllowed) { - if (input == null) { - throw new IllegalArgumentException("message headers must not be null"); - } - if (input.size() > MAX_COUNT) { - throw new IllegalArgumentException("message header count exceeds 64: " + input.size()); - } - - int bytes = 0; - Map copy = new LinkedHashMap<>(); - Set seen = new java.util.HashSet<>(); - for (Map.Entry entry : input.entrySet()) { - HeaderName name = entry.getKey(); - HeaderValue value = entry.getValue(); - if (name == null || value == null) { - throw new IllegalArgumentException("message header name and value must not be null"); - } - String normalized = name.normalized(); - if (!reservedAllowed && ReservedHeaders.isReserved(normalized)) { - throw new IllegalArgumentException("message header is not allowed: " + normalized); - } - if (carriesACredential(normalized)) { - // The name is reported and the value never is: an error message is written to a log that - // is exactly as readable as the broker storage this check exists to keep the value out of. - throw new IllegalArgumentException("message header is not allowed: " + normalized); - } - if (!seen.add(normalized)) { - throw new IllegalArgumentException("duplicate message header name: " + normalized); - } - bytes += name.value().getBytes(StandardCharsets.UTF_8).length; - bytes += value.value().getBytes(StandardCharsets.UTF_8).length; - copy.put(name, value); - } - if (bytes > MAX_TOTAL_BYTES) { - throw new IllegalArgumentException("message header bytes exceed 32768: " + bytes); - } - return new MessageHeaders(Collections.unmodifiableMap(copy)); - } - - private static boolean carriesACredential(String normalized) { - if (SECRET_NAMES.contains(normalized)) { - return true; - } - String[] segments = SEGMENT_SEPARATOR.split(normalized, -1); - for (int index = 0; index < segments.length; index++) { - if (SECRET_SEGMENTS.contains(segments[index])) { - return true; - } - // Adjacent segments are also tested joined, because the same word is written both ways: - // `api_key` is one segment to a reader and two to a splitter, and `x-api-key` is two of - // three. Joining only neighbouring pairs is what keeps `routing-key` accepted. - if (index + 1 < segments.length - && SECRET_SEGMENTS.contains(segments[index] + segments[index + 1])) { - return true; - } - } - return false; - } - - /** - * Returns the headers as an immutable map. - * - * @return the header entries in insertion order - */ - public Map asMap() { - return values; - } - - /** - * Looks a header up case-insensitively. - * - * @param name the header name in any case - * @return the value when present - */ - public Optional find(String name) { - if (name == null) { - return Optional.empty(); - } - String normalized = name.toLowerCase(Locale.ROOT); - return values.entrySet().stream() - .filter(entry -> entry.getKey().normalized().equals(normalized)) - .map(Map.Entry::getValue) - .findFirst(); - } - - /** - * Returns the number of headers. - * - * @return the entry count - */ - public int size() { - return values.size(); - } - - @Override - public boolean equals(Object other) { - return other instanceof MessageHeaders headers && values.equals(headers.values); - } - - @Override - public int hashCode() { - return values.hashCode(); - } - - @Override - public String toString() { - return "MessageHeaders[size=" + values.size() + "]"; - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/ReservedHeaders.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/ReservedHeaders.java deleted file mode 100644 index 50eb931b..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/ReservedHeaders.java +++ /dev/null @@ -1,151 +0,0 @@ -package dev.caskeleton.messaging.api.header; - -import java.util.Locale; -import java.util.Set; - -/** - * The header names the platform owns. - * - *

These carry envelope identity, trace propagation, and redrive bookkeeping. Applications cannot - * write them: if a caller could set {@code msg.id}, the logical identity that Inbox deduplication - * and DLQ correlation depend on would become caller-controlled. - */ -public final class ReservedHeaders { - - /** Logical message identity. */ - public static final String MESSAGE_ID = "msg.id"; - - /** Stable catalog message type. */ - public static final String MESSAGE_TYPE = "msg.type"; - - /** Schema revision of the payload. */ - public static final String SCHEMA_VERSION = "msg.schema-version"; - - /** Logical producing service. */ - public static final String PRODUCER = "msg.producer"; - - /** Instant the platform created the envelope. */ - public static final String PRODUCED_AT = "msg.produced-at"; - - /** Instant the business fact occurred. */ - public static final String OCCURRED_AT = "msg.occurred-at"; - - /** Workflow correlation value. */ - public static final String CORRELATION_ID = "msg.correlation-id"; - - /** Identity of the directly causing message. */ - public static final String CAUSATION_ID = "msg.causation-id"; - - /** Codec content type. */ - public static final String CONTENT_TYPE = "msg.content-type"; - - /** Distribution key. */ - public static final String PARTITION_KEY = "msg.partition-key"; - - /** Ordering key. */ - public static final String ORDERING_KEY = "msg.ordering-key"; - - /** - * Bounded tenant identity. - * - *

The envelope carried a tenant and no header name existed for it, so the write side had - * nothing to write and the read side rebuilt every consumed message with an empty tenant. A - * message published by one tenant and consumed as belonging to none is not a lost label: it is - * the field every downstream authorization and data-partitioning decision reads. - */ - public static final String TENANT = "msg.tenant"; - - /** Identity of the redrive operation that replayed this message. */ - public static final String REDRIVE_ID = "msg.redrive-id"; - - /** How many times this message has been redriven. */ - public static final String REDRIVE_COUNT = "msg.redrive-count"; - - /** Current retry attempt, counting the first delivery as one. */ - public static final String RETRY_ATTEMPT = "msg.retry-attempt"; - - /** Instant of the first recorded failure. */ - public static final String FIRST_FAILURE_AT = "msg.first-failure-at"; - - /** Instant of the most recent recorded failure. */ - public static final String LAST_FAILURE_AT = "msg.last-failure-at"; - - /** Stable failure category recorded when parking or dead lettering. */ - public static final String FAILURE_CATEGORY = "msg.failure-category"; - - /** Stable failure code recorded when parking or dead lettering. */ - public static final String FAILURE_CODE = "msg.failure-code"; - - /** Logical destination the message was originally published to. */ - public static final String ORIGIN_DESTINATION = "msg.origin-destination"; - - /** W3C trace parent. */ - public static final String TRACEPARENT = "traceparent"; - - /** W3C trace state. */ - public static final String TRACESTATE = "tracestate"; - - /** W3C baggage. */ - public static final String BAGGAGE = "baggage"; - - private static final Set NAMES = - Set.of( - MESSAGE_ID, - MESSAGE_TYPE, - SCHEMA_VERSION, - PRODUCER, - PRODUCED_AT, - OCCURRED_AT, - CORRELATION_ID, - CAUSATION_ID, - CONTENT_TYPE, - PARTITION_KEY, - ORDERING_KEY, - TENANT, - REDRIVE_ID, - REDRIVE_COUNT, - RETRY_ATTEMPT, - FIRST_FAILURE_AT, - LAST_FAILURE_AT, - FAILURE_CATEGORY, - FAILURE_CODE, - ORIGIN_DESTINATION, - TRACEPARENT, - TRACESTATE, - BAGGAGE); - - private ReservedHeaders() {} - - /** - * The namespace the platform owns, whether or not a name in it exists yet. - * - *

The check used to be exact membership of {@link #NAMES}, so {@code msg.anything} that this - * release has not defined was an ordinary application header — until a later release defined it, - * at which point every application already writing it silently started overwriting envelope - * metadata. Owning the prefix means a new platform header is a compatible change. - */ - private static final String PLATFORM_PREFIX = "msg."; - - /** - * Reports whether a header name belongs to the platform. - * - * @param name the header name in any case - * @return true when the platform owns the name - */ - public static boolean isReserved(String name) { - if (name == null) { - return false; - } - String normalized = name.toLowerCase(Locale.ROOT); - return NAMES.contains(normalized) || normalized.startsWith(PLATFORM_PREFIX); - } - - /** - * Returns every reserved header name. - * - * @return an immutable set of lowercase names - */ - public static Set names() { - return NAMES; - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BrokerPosition.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BrokerPosition.java deleted file mode 100644 index 7119c399..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BrokerPosition.java +++ /dev/null @@ -1,27 +0,0 @@ -package dev.caskeleton.messaging.api.publish; - -import java.util.Map; - -/** - * A broker-specific coordinate for a published or delivered message. - * - *

Positions exist for diagnostics and replay. Business logic must not branch on them: the whole - * point of the logical destination model is that a handler behaves identically whether it is - * reading a Kafka offset or a RabbitMQ delivery tag. - */ -public interface BrokerPosition { - - /** - * Returns the broker family that produced this position. - * - * @return a stable, low-cardinality broker name - */ - String broker(); - - /** - * Returns the position as diagnostic attributes. - * - * @return an immutable map safe for structured logs - */ - Map diagnosticAttributes(); -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/ConfirmationLevel.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/ConfirmationLevel.java deleted file mode 100644 index 6b576584..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/ConfirmationLevel.java +++ /dev/null @@ -1,20 +0,0 @@ -package dev.caskeleton.messaging.api.publish; - -/** - * The strength of confirmation the broker actually supplied. - * - *

Kept separate from the requested confirmation requirement so that "we asked for replication - * and got a leader ack" is representable, and therefore rejectable, instead of being rounded up to - * success. - */ -public enum ConfirmationLevel { - - /** No confirmation was received. */ - NONE, - - /** The broker acknowledged receipt without proving durability. */ - BROKER_ACK, - - /** The broker acknowledged replication or persistence. */ - REPLICATION_OR_PERSISTENCE_ACK -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/MessagePublisher.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/MessagePublisher.java deleted file mode 100644 index 5ffca2a1..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/MessagePublisher.java +++ /dev/null @@ -1,26 +0,0 @@ -package dev.caskeleton.messaging.api.publish; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import java.util.concurrent.CompletionStage; - -/** - * The M1 typed publish entry point used by ordinary business code. - * - *

The core contract is {@link CompletionStage}. Blocking and Reactor facades live in separate - * modules so that {@code messaging-core-api} keeps no dependency on either programming model. - */ -public interface MessagePublisher { - - /** - * Publishes one message. - * - * @param the payload type - * @param destination the logical destination - * @param message the envelope to publish - * @param options per-call options - * @return a stage completing with the outcome and its evidence - */ - CompletionStage publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options); -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishCompletion.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishCompletion.java deleted file mode 100644 index f9f7847a..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishCompletion.java +++ /dev/null @@ -1,20 +0,0 @@ -package dev.caskeleton.messaging.api.publish; - -/** - * How a publish attempt ended. - * - *

Publish is not a boolean. Collapsing "the broker refused this" and "we never learned what the - * broker did" into one failure is what produces duplicate orders: the first is safe to abandon, the - * second is not safe to retry with a new identity. - */ -public enum PublishCompletion { - - /** The broker accepted the message at the required confirmation level. */ - CONFIRMED, - - /** The message was definitively not accepted. It is safe to abandon this attempt. */ - REJECTED, - - /** The outcome is unknown. The broker may or may not hold the message. */ - AMBIGUOUS -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishDeduplication.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishDeduplication.java deleted file mode 100644 index 2421550d..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishDeduplication.java +++ /dev/null @@ -1,27 +0,0 @@ -package dev.caskeleton.messaging.api.publish; - -import java.time.Duration; -import java.util.Objects; - -/** - * Requests broker-side duplicate suppression for a publish. - * - *

The deduplication key defaults to the logical message id, which is what makes an Outbox relay - * able to retry an ambiguous publish without creating a second message. Requesting this on a broker - * without the {@code deduplicatedPublish} capability is a startup failure, not a silent no-op. - * - * @param key the stable deduplication key - * @param window how long the broker should remember the key - */ -public record PublishDeduplication(String key, Duration window) { - - public PublishDeduplication { - Objects.requireNonNull(window, "deduplication window must not be null"); - if (key == null || key.isBlank()) { - throw new IllegalArgumentException("deduplication key must not be blank"); - } - if (window.isNegative() || window.isZero()) { - throw new IllegalArgumentException("deduplication window must be positive"); - } - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishEvidence.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishEvidence.java deleted file mode 100644 index 9ad9611a..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishEvidence.java +++ /dev/null @@ -1,66 +0,0 @@ -package dev.caskeleton.messaging.api.publish; - -import java.util.Objects; - -/** - * The observable facts behind a publish outcome. - * - *

Evidence is recorded before a completion is chosen, not derived from it. That ordering is what - * lets an operator answer "could the broker be holding this message?" from a stored result. - * - * @param queuedLocally the adapter buffered the message in process - * @param transmission what is known about bytes reaching the broker - * @param brokerAccepted the broker positively acknowledged the message - * @param confirmationLevel the strength of that acknowledgement - */ -public record PublishEvidence( - boolean queuedLocally, - TransmissionEvidence transmission, - boolean brokerAccepted, - ConfirmationLevel confirmationLevel) { - - public PublishEvidence { - Objects.requireNonNull(transmission, "transmission must not be null"); - Objects.requireNonNull(confirmationLevel, "confirmationLevel must not be null"); - if (!brokerAccepted && confirmationLevel != ConfirmationLevel.NONE) { - throw new IllegalArgumentException( - "confirmation level requires broker acceptance: " + confirmationLevel); - } - if (transmission == TransmissionEvidence.NOT_TRANSMITTED && brokerAccepted) { - throw new IllegalArgumentException("untransmitted message cannot be broker accepted"); - } - } - - /** - * Returns evidence for a message rejected before anything was sent. - * - * @return local rejection evidence - */ - public static PublishEvidence notTransmitted() { - return new PublishEvidence( - false, TransmissionEvidence.NOT_TRANSMITTED, false, ConfirmationLevel.NONE); - } - - /** - * Returns evidence for a message whose fate is unknown. - * - * @return ambiguous evidence - */ - public static PublishEvidence ambiguous() { - return new PublishEvidence( - true, TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED, false, ConfirmationLevel.NONE); - } - - /** - * Returns evidence for a confirmed publish. - * - * @param level the confirmation the broker supplied - * @return confirmed evidence - */ - public static PublishEvidence confirmed(ConfirmationLevel level) { - if (level == ConfirmationLevel.NONE) { - throw new IllegalArgumentException("confirmed evidence requires a confirmation level"); - } - return new PublishEvidence(true, TransmissionEvidence.TRANSMITTED, true, level); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishOptions.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishOptions.java deleted file mode 100644 index f3d07e5c..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishOptions.java +++ /dev/null @@ -1,45 +0,0 @@ -package dev.caskeleton.messaging.api.publish; - -import dev.caskeleton.messaging.api.destination.ConfirmationRequirement; -import java.time.Duration; -import java.util.Objects; -import java.util.Optional; - -/** - * Per-call publish options. - * - *

There is no free-form hint map. One existed for a native surface that does not read it, so the - * only thing a caller could do with it was pass adapter settings that the publish path refused at - * runtime — an escape hatch around destination policy that never opened. A broker-specific option - * belongs in that broker's own typed API, where the adapter that honours it can be seen to. - * - * @param timeout the publish operation deadline - * @param confirmation the confirmation this call requires - * @param deduplication optional broker-side duplicate suppression - */ -public record PublishOptions( - Duration timeout, - ConfirmationRequirement confirmation, - Optional deduplication) { - - private static final Duration DEFAULT_TIMEOUT = Duration.ofSeconds(5); - - public PublishOptions { - Objects.requireNonNull(timeout, "timeout must not be null"); - Objects.requireNonNull(confirmation, "confirmation must not be null"); - Objects.requireNonNull(deduplication, "deduplication must not be null"); - if (timeout.isNegative() || timeout.isZero()) { - throw new IllegalArgumentException("publish timeout must be positive"); - } - } - - /** - * Returns the M1 default: five second timeout, replication evidence. - * - * @return the default options - */ - public static PublishOptions defaults() { - return new PublishOptions( - DEFAULT_TIMEOUT, ConfirmationRequirement.REPLICATION_OR_PERSISTENCE_ACK, Optional.empty()); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishRequest.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishRequest.java deleted file mode 100644 index 50730b67..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishRequest.java +++ /dev/null @@ -1,40 +0,0 @@ -package dev.caskeleton.messaging.api.publish; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import java.util.Objects; - -/** - * One entry of a batch publish, pairing a destination with the envelope bound for it. - * - *

A batch is a list of independent publishes, not one publish of many payloads, so each entry - * carries its own destination. Nothing forces the entries of a batch to share a destination; an - * adapter groups them itself when its wire protocol rewards grouping. - * - * @param the payload type - * @param destination the logical destination for this entry - * @param message the envelope to publish - * @param options the per-entry options - */ -public record PublishRequest( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - - public PublishRequest { - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(message, "message must not be null"); - Objects.requireNonNull(options, "options must not be null"); - } - - /** - * Creates a request using the default publish options. - * - * @param the payload type - * @param destination the logical destination - * @param message the envelope to publish - * @return the request - */ - public static PublishRequest of( - MessageDestination destination, MessageEnvelope message) { - return new PublishRequest<>(destination, message, PublishOptions.defaults()); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishResult.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishResult.java deleted file mode 100644 index 3582dd73..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishResult.java +++ /dev/null @@ -1,178 +0,0 @@ -package dev.caskeleton.messaging.api.publish; - -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import java.time.Duration; -import java.util.Objects; -import java.util.Optional; - -/** - * The outcome of one publish call, with the evidence that justifies it. - * - *

The constructor refuses every combination that would let a caller read a stronger guarantee - * than was actually obtained, and every one that contradicts itself: a rejection the broker - * acknowledged, a confirmation that does not know whether it routed, an ambiguous outcome the - * broker routed, a broker coordinate for bytes that never left. An adapter that cannot decide must - * report {@link PublishCompletion#AMBIGUOUS} with no confirmation level, which is the conservative - * answer, rather than picking a completion that happens to make the call site simpler. - * - *

Validating here rather than trusting call sites is deliberate: the record is public, every - * adapter builds one, and a contradiction assembled in an adapter is only ever read much later, by - * an operator deciding whether to re-publish. - * - * @param completion how the attempt ended - * @param evidence the observable facts behind that outcome - * @param routingOutcome whether the broker routed the message - * @param position the broker coordinate when known - * @param attempts transport attempts made, counting the first as one - * @param elapsed wall-clock time spent - * @param failure the sanitized failure when the attempt did not confirm - */ -public record PublishResult( - PublishCompletion completion, - PublishEvidence evidence, - RoutingOutcome routingOutcome, - Optional position, - int attempts, - Duration elapsed, - Optional failure) { - - public PublishResult { - Objects.requireNonNull(completion, "completion must not be null"); - Objects.requireNonNull(evidence, "evidence must not be null"); - Objects.requireNonNull(routingOutcome, "routingOutcome must not be null"); - Objects.requireNonNull(position, "position must not be null"); - Objects.requireNonNull(elapsed, "elapsed must not be null"); - Objects.requireNonNull(failure, "failure must not be null"); - - if (attempts < 1) { - throw new IllegalArgumentException("publish attempts must be at least 1"); - } - if (elapsed.isNegative()) { - throw new IllegalArgumentException("publish elapsed must not be negative"); - } - - if (completion == PublishCompletion.CONFIRMED && !evidence.brokerAccepted()) { - throw new IllegalArgumentException("confirmed publish requires broker acceptance"); - } - if (completion == PublishCompletion.CONFIRMED - && evidence.confirmationLevel() == ConfirmationLevel.NONE) { - throw new IllegalArgumentException("confirmed publish requires a confirmation level"); - } - if (completion == PublishCompletion.CONFIRMED && routingOutcome == RoutingOutcome.UNROUTABLE) { - throw new IllegalArgumentException("unroutable publish cannot be confirmed"); - } - if (completion == PublishCompletion.AMBIGUOUS - && evidence.confirmationLevel() != ConfirmationLevel.NONE) { - throw new IllegalArgumentException("ambiguous publish cannot claim confirmation"); - } - if (completion == PublishCompletion.AMBIGUOUS && evidence.brokerAccepted()) { - throw new IllegalArgumentException("ambiguous publish cannot claim broker acceptance"); - } - if (completion == PublishCompletion.AMBIGUOUS - && evidence.transmission() == TransmissionEvidence.NOT_TRANSMITTED) { - throw new IllegalArgumentException("untransmitted publish is rejected, not ambiguous"); - } - if (completion != PublishCompletion.CONFIRMED && failure.isEmpty()) { - throw new IllegalArgumentException("non-confirmed publish requires a failure descriptor"); - } - if (completion == PublishCompletion.CONFIRMED && failure.isPresent()) { - throw new IllegalArgumentException("confirmed publish must not carry a failure descriptor"); - } - if (completion == PublishCompletion.REJECTED && evidence.brokerAccepted()) { - // A broker that acknowledged the message did not reject it. Left representable, this is the - // combination that turns a delivered message into one the caller re-publishes as if it had - // never been sent. - throw new IllegalArgumentException("rejected publish cannot claim broker acceptance"); - } - if (completion == PublishCompletion.CONFIRMED && routingOutcome == RoutingOutcome.UNKNOWN) { - // The confirmation came from the broker, and the same response says whether it routed. A - // confirmed publish that does not know is an adapter reporting half of what it was told. - throw new IllegalArgumentException("confirmed publish knows whether it routed"); - } - if (completion == PublishCompletion.AMBIGUOUS && routingOutcome == RoutingOutcome.ROUTED) { - // Routing is something only the broker can report, and a broker that reported it answered. - throw new IllegalArgumentException("a routed publish is not ambiguous"); - } - if (position.isPresent() && evidence.transmission() == TransmissionEvidence.NOT_TRANSMITTED) { - // A partition and offset for a message that never left the process: whatever coordinate this - // is, it belongs to some other message, and an operator would chase it. - throw new IllegalArgumentException("an untransmitted publish has no broker position"); - } - } - - /** - * A publish the broker confirmed. - * - * @param level the confirmation the broker supplied - * @param routing whether the broker routed it; a broker with no routing step reports {@link - * RoutingOutcome#NOT_APPLICABLE} - * @param position the broker coordinate, when the broker reported one - * @param elapsed wall-clock time spent - * @return the confirmed result - */ - public static PublishResult confirmed( - ConfirmationLevel level, - RoutingOutcome routing, - Optional position, - Duration elapsed) { - return new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(level), - routing, - position, - 1, - elapsed, - Optional.empty()); - } - - /** - * A publish refused before anything left the process. - * - *

Routing is {@link RoutingOutcome#NOT_APPLICABLE}: nothing reached a broker that could have - * routed it. - * - * @param elapsed wall-clock time spent - * @param failure why it was refused - * @return the rejected result - */ - public static PublishResult rejected(Duration elapsed, FailureDescriptor failure) { - return new PublishResult( - PublishCompletion.REJECTED, - PublishEvidence.notTransmitted(), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - elapsed, - Optional.of(failure)); - } - - /** - * A publish whose fate is unknown: the broker may or may not hold the message. - * - * @param elapsed wall-clock time spent - * @param failure what made the outcome unknowable - * @return the ambiguous result - */ - public static PublishResult ambiguous(Duration elapsed, FailureDescriptor failure) { - return new PublishResult( - PublishCompletion.AMBIGUOUS, - PublishEvidence.ambiguous(), - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, - elapsed, - Optional.of(failure)); - } - - /** - * Reports whether the broker may be holding this message. - * - *

Callers use this to decide between abandoning an attempt and re-publishing under the same - * logical id. - * - * @return true when the outcome is ambiguous - */ - public boolean mayHaveBeenStored() { - return completion == PublishCompletion.AMBIGUOUS; - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/RoutingOutcome.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/RoutingOutcome.java deleted file mode 100644 index 601aef65..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/RoutingOutcome.java +++ /dev/null @@ -1,23 +0,0 @@ -package dev.caskeleton.messaging.api.publish; - -/** - * Whether the broker could route the message to a destination. - * - *

Routing is separate from confirmation because RabbitMQ can confirm a publish the exchange - * accepted and simultaneously return it as unroutable. Reporting only the confirm would turn a - * dropped message into a success. - */ -public enum RoutingOutcome { - - /** The broker has no routing stage, as with a Kafka topic publish. */ - NOT_APPLICABLE, - - /** The message reached at least one destination. */ - ROUTED, - - /** The broker accepted the publish but found no destination. */ - UNROUTABLE, - - /** Routing could not be determined. */ - UNKNOWN -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/TransmissionEvidence.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/TransmissionEvidence.java deleted file mode 100644 index 1bb8434f..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/TransmissionEvidence.java +++ /dev/null @@ -1,14 +0,0 @@ -package dev.caskeleton.messaging.api.publish; - -/** What the adapter can prove about bytes leaving the process. */ -public enum TransmissionEvidence { - - /** Nothing was written to the broker connection. */ - NOT_TRANSMITTED, - - /** Bytes may have been written; the connection failed before that could be established. */ - MAY_HAVE_BEEN_TRANSMITTED, - - /** Bytes were written to the broker connection. */ - TRANSMITTED -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementCompletion.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementCompletion.java deleted file mode 100644 index 2773188e..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementCompletion.java +++ /dev/null @@ -1,14 +0,0 @@ -package dev.caskeleton.messaging.api.settlement; - -/** How a settlement attempt ended. */ -public enum SettlementCompletion { - - /** The broker confirmed the settlement. */ - SETTLED, - - /** The broker refused the settlement. */ - REJECTED, - - /** The settlement outcome is unknown and redelivery remains possible. */ - UNKNOWN -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementEvidence.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementEvidence.java deleted file mode 100644 index f6400cc2..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementEvidence.java +++ /dev/null @@ -1,66 +0,0 @@ -package dev.caskeleton.messaging.api.settlement; - -import java.util.Objects; - -/** - * What is known about a settlement reaching the broker. - * - * @param transmitted the settlement was written to the broker connection - * @param brokerConfirmed the broker confirmed the settlement - * @param redeliveryPossible the message may still be redelivered - */ -public record SettlementEvidence( - boolean transmitted, boolean brokerConfirmed, boolean redeliveryPossible) { - - public SettlementEvidence { - if (brokerConfirmed && !transmitted) { - throw new IllegalArgumentException("an unsent settlement cannot be broker confirmed"); - } - } - - /** - * Returns evidence for a confirmed settlement. - * - * @return confirmed evidence - */ - public static SettlementEvidence confirmed() { - return new SettlementEvidence(true, true, false); - } - - /** - * Returns evidence for a settlement whose fate is unknown. - * - * @return unknown evidence - */ - public static SettlementEvidence unknown() { - return new SettlementEvidence(true, false, true); - } - - /** - * Returns evidence for a settlement that never left the process. - * - * @return unsent evidence - */ - public static SettlementEvidence notTransmitted() { - return new SettlementEvidence(false, false, true); - } - - /** - * Returns a settlement evidence value, validating the combination. - * - * @param object the value to compare - * @return whether the values are equal - */ - @Override - public boolean equals(Object object) { - return object instanceof SettlementEvidence other - && transmitted == other.transmitted - && brokerConfirmed == other.brokerConfirmed - && redeliveryPossible == other.redeliveryPossible; - } - - @Override - public int hashCode() { - return Objects.hash(transmitted, brokerConfirmed, redeliveryPossible); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementResult.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementResult.java deleted file mode 100644 index 9712901d..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementResult.java +++ /dev/null @@ -1,47 +0,0 @@ -package dev.caskeleton.messaging.api.settlement; - -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import java.util.Objects; -import java.util.Optional; - -/** - * The outcome of one settlement call. - * - *

{@link SettlementCompletion#UNKNOWN} means redelivery remains possible and must not be read as - * success. Treating an unconfirmed acknowledgement as settled is the classic route to a message - * that looks processed in logs and is processed again minutes later. - * - * @param completion how the settlement ended - * @param evidence what is known about it reaching the broker - * @param failure the sanitized failure when settlement did not confirm - */ -public record SettlementResult( - SettlementCompletion completion, - SettlementEvidence evidence, - Optional failure) { - - public SettlementResult { - Objects.requireNonNull(completion, "completion must not be null"); - Objects.requireNonNull(evidence, "evidence must not be null"); - Objects.requireNonNull(failure, "failure must not be null"); - if (completion == SettlementCompletion.SETTLED && !evidence.brokerConfirmed()) { - throw new IllegalArgumentException("settled result requires broker confirmation"); - } - if (completion == SettlementCompletion.SETTLED && evidence.redeliveryPossible()) { - throw new IllegalArgumentException("settled result cannot leave redelivery possible"); - } - if (completion != SettlementCompletion.SETTLED && failure.isEmpty()) { - throw new IllegalArgumentException("non-settled result requires a failure descriptor"); - } - } - - /** - * Returns a confirmed settlement result. - * - * @return a settled result - */ - public static SettlementResult settled() { - return new SettlementResult( - SettlementCompletion.SETTLED, SettlementEvidence.confirmed(), Optional.empty()); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/BoundedByteSink.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/BoundedByteSink.java deleted file mode 100644 index fb9f0d65..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/BoundedByteSink.java +++ /dev/null @@ -1,114 +0,0 @@ -package dev.caskeleton.messaging.schema; - -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import java.io.ByteArrayOutputStream; -import java.io.OutputStream; -import java.util.Objects; - -/** - * A byte sink that refuses the byte after the limit instead of the buffer after the fact. - * - *

Every codec here used to serialize into an unbounded buffer and compare {@code bytes.length} - * to the configured maximum afterwards. That makes the maximum a reporting threshold rather than an - * allocation bound: a payload whose graph expands to hundreds of megabytes exhausts the heap while - * being written, and the check that would have rejected it never runs. Under a broker consumer that - * is a process-wide outage caused by one message. - * - *

This sink fails on the write that would cross the limit, so peak allocation is bounded by the - * limit itself plus whatever the encoder buffers. The exception is the same {@link - * MessageTooLargeException} the after-the-fact check raised, carrying the codec's own error code, - * so callers and evidence records see no behavioural difference for payloads that merely exceed the - * bound. - * - *

Not thread-safe, and not meant to be: an instance belongs to a single encode call. - */ -public final class BoundedByteSink extends OutputStream { - - private final int maxBytes; - private final String errorCode; - private final ByteArrayOutputStream buffer; - private int written; - - private BoundedByteSink(int maxBytes, String errorCode) { - if (maxBytes < 1) { - throw new IllegalArgumentException("maxBytes must be positive"); - } - this.maxBytes = maxBytes; - this.errorCode = Objects.requireNonNull(errorCode, "errorCode must not be null"); - // Sized to the limit only when the limit is small: a 1 GiB bound must not pre-allocate 1 GiB. - this.buffer = new ByteArrayOutputStream(Math.min(maxBytes, 8_192)); - } - - /** - * Creates a sink that refuses to accumulate more than {@code maxBytes}. - * - * @param maxBytes the inclusive byte limit - * @param errorCode the code the codec reports for an oversized payload - * @return a bounded sink - */ - public static BoundedByteSink of(int maxBytes, String errorCode) { - return new BoundedByteSink(maxBytes, errorCode); - } - - @Override - public void write(int b) { - reserve(1); - buffer.write(b); - } - - @Override - public void write(byte[] bytes, int offset, int length) { - Objects.checkFromIndexSize(offset, length, bytes.length); - reserve(length); - buffer.write(bytes, offset, length); - } - - /** - * Checks a size the caller can compute before serializing, without consuming the budget. - * - *

Protobuf knows its serialized size exactly, so the whole encode can be refused before the - * first byte is written. The subsequent writes are still bounded — this is a cheaper refusal, not - * a replacement for the bound. - * - * @param size the number of bytes the caller is about to produce - */ - public void requireFits(int size) { - if (size < 0) { - throw new IllegalArgumentException("size must not be negative"); - } - refuseIfBeyondLimit(size); - } - - private void reserve(int size) { - refuseIfBeyondLimit(size); - written += size; - } - - private void refuseIfBeyondLimit(int size) { - if (size > maxBytes - written) { - throw new MessageTooLargeException( - errorCode, - ("the encoded payload exceeds the %d byte limit; it was refused at byte %d rather than" - + " buffered in full") - .formatted(maxBytes, written + size)); - } - } - - /** - * The bytes accumulated so far. - * - * @return a copy of the buffered bytes - */ - public byte[] toByteArray() { - return buffer.toByteArray(); - } - - /** - * How many bytes have been admitted. - * - * @return the running total - */ - public int written() { - return written; - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessage.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessage.java deleted file mode 100644 index 51f5e422..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessage.java +++ /dev/null @@ -1,66 +0,0 @@ -package dev.caskeleton.messaging.schema; - -import dev.caskeleton.messaging.api.ContentType; -import java.util.Arrays; -import java.util.Objects; -import java.util.Optional; - -/** - * An encoded payload together with the facts needed to decode it again. - * - *

The byte array is defensively copied on both construction and access. These bytes travel - * through retry, DLQ, and redrive paths where a shared mutable array would let one stage corrupt - * another's copy of the same logical message. - * - * @param bytes the encoded payload - * @param contentType the codec media type - * @param schemaReference the schema the payload was written against - */ -@SuppressWarnings("ArrayRecordComponent") -public record EncodedMessage( - byte[] bytes, ContentType contentType, Optional schemaReference) { - - public EncodedMessage { - Objects.requireNonNull(bytes, "encoded bytes must not be null"); - Objects.requireNonNull(contentType, "contentType must not be null"); - Objects.requireNonNull(schemaReference, "schemaReference must not be null"); - bytes = bytes.clone(); - } - - /** - * Returns a copy of the encoded bytes. - * - * @return the payload bytes - */ - @Override - public byte[] bytes() { - return bytes.clone(); - } - - /** - * Returns the encoded size without copying. - * - * @return the payload length in bytes - */ - public int size() { - return bytes.length; - } - - @Override - public boolean equals(Object other) { - return other instanceof EncodedMessage message - && Arrays.equals(bytes, message.bytes) - && contentType.equals(message.contentType) - && schemaReference.equals(message.schemaReference); - } - - @Override - public int hashCode() { - return Objects.hash(Arrays.hashCode(bytes), contentType, schemaReference); - } - - @Override - public String toString() { - return "EncodedMessage[contentType=" + contentType.value() + ", size=" + bytes.length + "]"; - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessagePublisher.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessagePublisher.java deleted file mode 100644 index 94d4d225..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessagePublisher.java +++ /dev/null @@ -1,24 +0,0 @@ -package dev.caskeleton.messaging.schema; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import java.util.concurrent.CompletionStage; - -/** - * Publishes an envelope whose payload has already been encoded by an authoritative application - * contract boundary. - * - *

This is intentionally narrower than the transport SPI. Callers may skip only the codec step; - * destination resolution, access policy, admission, runtime leasing, transport normalization and - * observation remain owned by the platform's central publisher. - */ -@FunctionalInterface -public interface EncodedMessagePublisher { - - CompletionStage publishEncoded( - MessageDestination destination, - MessageEnvelope message, - PublishOptions options); -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageCodec.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageCodec.java deleted file mode 100644 index b51f1573..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageCodec.java +++ /dev/null @@ -1,59 +0,0 @@ -package dev.caskeleton.messaging.schema; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; - -/** - * Encodes and decodes payloads for a single wire format. - * - *

Implementations operate against a closed message-type registry. Accepting an unregistered type - * would let a producer introduce a wire contract nothing has reviewed, which is the same class of - * problem that makes Java serialization unsupported here. - */ -public interface MessageCodec { - - /** - * Returns the media type this codec produces. - * - * @return the content type - */ - ContentType contentType(); - - /** - * Encodes a payload. - * - * @param type the catalog message type - * @param version the schema revision - * @param payload the payload to encode - * @return the encoded message - */ - EncodedMessage encode(MessageType type, SchemaVersion version, Object payload); - - /** - * Decodes a payload from raw bytes. - * - * @param the payload type - * @param type the catalog message type - * @param version the schema revision - * @param encoded the encoded bytes - * @param payloadType the expected payload class - * @return the decoded payload - */ - T decode(MessageType type, SchemaVersion version, byte[] encoded, Class payloadType); - - /** - * Decodes a payload from an encoded message. - * - * @param the payload type - * @param type the catalog message type - * @param version the schema revision - * @param encoded the encoded message - * @param payloadType the expected payload class - * @return the decoded payload - */ - default T decode( - MessageType type, SchemaVersion version, EncodedMessage encoded, Class payloadType) { - return decode(type, version, encoded.bytes(), payloadType); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageCodecRegistry.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageCodecRegistry.java deleted file mode 100644 index a237c325..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageCodecRegistry.java +++ /dev/null @@ -1,26 +0,0 @@ -package dev.caskeleton.messaging.schema; - -import dev.caskeleton.messaging.api.ContentType; -import java.util.Optional; - -/** Resolves the codec for a content type. */ -public interface MessageCodecRegistry { - - /** - * Returns the codec for a content type. - * - * @param contentType the media type - * @return the codec when registered - */ - Optional find(ContentType contentType); - - /** - * Returns the Stable default codec. - * - *

The raw bytes codec is never eligible: selecting it by default would silently disable schema - * validation for every destination that forgot to declare one. - * - * @return the default codec - */ - MessageCodec defaultCodec(); -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageContractKey.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageContractKey.java deleted file mode 100644 index 2605a488..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageContractKey.java +++ /dev/null @@ -1,49 +0,0 @@ -package dev.caskeleton.messaging.schema; - -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import java.util.Objects; - -/** - * The identity a codec registry is keyed on: a message type at a specific schema version. - * - *

Keying on the message type alone is what let an unregistered version decode. The version - * travels in the envelope and in {@link SchemaReference}, so a consumer receiving {@code - * order.created v999} would look up {@code order.created}, find the v1 class or parser, decode - * against it, and then keep the v999 label on the result. Nothing failed, and every downstream - * compatibility gate and audit record then described a version that was never registered. - * - *

With the version in the key that lookup misses, which is the only honest outcome: the platform - * has no contract for that version and must say so rather than guess one. - * - * @param type the catalog message type - * @param version the schema version the contract is registered for - */ -public record MessageContractKey(MessageType type, SchemaVersion version) { - - /** Validates both components. */ - public MessageContractKey { - Objects.requireNonNull(type, "messageType must not be null"); - Objects.requireNonNull(version, "schemaVersion must not be null"); - } - - /** - * Creates a key from raw components. - * - * @param type the catalog message type - * @param version the schema version - * @return the key - */ - public static MessageContractKey of(String type, int version) { - return new MessageContractKey(new MessageType(type), new SchemaVersion(version)); - } - - /** - * Renders the key the way error messages and audit records name a contract. - * - * @return for example {@code order.created v1} - */ - public String describe() { - return type.value() + " v" + version.value(); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/RawBytesMessageCodec.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/RawBytesMessageCodec.java deleted file mode 100644 index 30079ec5..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/RawBytesMessageCodec.java +++ /dev/null @@ -1,76 +0,0 @@ -package dev.caskeleton.messaging.schema; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageSerializationException; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import java.util.Objects; -import java.util.Optional; - -/** - * The M2 escape hatch for payloads that carry no schema. - * - *

It still enforces the byte limit, and it is deliberately excluded from default codec - * selection: schema-free publishing has to be an explicit, auditable choice per destination, never - * something a destination falls back to because its codec was misconfigured. - */ -public final class RawBytesMessageCodec implements MessageCodec { - - /** The default encoded byte limit shared with the Stable codecs. */ - public static final int DEFAULT_MAX_BYTES = 1_048_576; - - private final int maxBytes; - - /** Creates a codec with the default one mebibyte limit. */ - public RawBytesMessageCodec() { - this(DEFAULT_MAX_BYTES); - } - - /** - * Creates a codec with an explicit byte limit. - * - * @param maxBytes the maximum encoded size - */ - public RawBytesMessageCodec(int maxBytes) { - if (maxBytes < 1) { - throw new IllegalArgumentException("maxBytes must be positive"); - } - this.maxBytes = maxBytes; - } - - @Override - public ContentType contentType() { - return ContentType.OCTET_STREAM; - } - - @Override - public EncodedMessage encode(MessageType type, SchemaVersion version, Object payload) { - Objects.requireNonNull(type, "messageType must not be null"); - Objects.requireNonNull(version, "schemaVersion must not be null"); - if (!(payload instanceof byte[] bytes)) { - throw new MessageSerializationException( - "RAW_BYTES_PAYLOAD_REQUIRED", "raw bytes codec accepts only byte[] payloads"); - } - if (bytes.length > maxBytes) { - throw new MessageTooLargeException( - "RAW_BYTES_TOO_LARGE", "encoded payload exceeds " + maxBytes + " bytes"); - } - return new EncodedMessage(bytes, ContentType.OCTET_STREAM, Optional.empty()); - } - - @Override - public T decode( - MessageType type, SchemaVersion version, byte[] encoded, Class payloadType) { - Objects.requireNonNull(encoded, "encoded bytes must not be null"); - if (!payloadType.equals(byte[].class)) { - throw new MessageSerializationException( - "RAW_BYTES_TARGET_REQUIRED", "raw bytes codec decodes only to byte[]"); - } - if (encoded.length > maxBytes) { - throw new MessageTooLargeException( - "RAW_BYTES_TOO_LARGE", "encoded payload exceeds " + maxBytes + " bytes"); - } - return payloadType.cast(encoded.clone()); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibility.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibility.java deleted file mode 100644 index 6aea0406..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibility.java +++ /dev/null @@ -1,32 +0,0 @@ -package dev.caskeleton.messaging.schema; - -/** - * The compatibility mode a message type's schema evolution must satisfy. - * - *

Transitive modes check every historical version, not just the immediate predecessor. That - * matters for integration events, where a consumer may be several releases behind and a chain of - * individually-compatible changes can still be collectively breaking. - */ -public enum SchemaCompatibility { - - /** A new schema can read data written by the previous schema. */ - BACKWARD, - - /** A new schema can read data written by every previous schema. */ - BACKWARD_TRANSITIVE, - - /** The previous schema can read data written by the new schema. */ - FORWARD, - - /** Every previous schema can read data written by the new schema. */ - FORWARD_TRANSITIVE, - - /** Both directions hold against the previous schema. */ - FULL, - - /** Both directions hold against every previous schema. */ - FULL_TRANSITIVE, - - /** No compatibility is enforced; permitted only for M2 raw bytes. */ - NONE_EXPERIMENTAL -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidator.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidator.java deleted file mode 100644 index 3fa0c5ed..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidator.java +++ /dev/null @@ -1,113 +0,0 @@ -package dev.caskeleton.messaging.schema; - -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageSchemaIncompatibleException; -import java.util.List; -import java.util.Objects; - -/** - * The format-independent half of schema evolution: which versions have to be compared, and whether - * a mode is even allowed on a production destination. - * - *

Split from the per-format gates on purpose. Whether v3 must be checked against v1 as well as - * v2 is a property of the compatibility mode, not of Avro or Protobuf, and duplicating that - * reasoning in each codec is how the two formats drift apart. - * - *

{@link SchemaCompatibility#NONE_EXPERIMENTAL} is refused for production destinations. A mode - * that checks nothing is useful while a message type is being designed and actively dangerous once - * a retained log exists, because the log outlives every consumer that could still read it. - */ -public final class SchemaCompatibilityValidator { - - private final SchemaRegistry registry; - - /** - * Creates a validator over a registry. - * - * @param registry the schema source - */ - public SchemaCompatibilityValidator(SchemaRegistry registry) { - this.registry = Objects.requireNonNull(registry, "registry must not be null"); - } - - /** - * Returns the versions a candidate must be checked against, newest first. - * - *

Transitive modes return the whole history; pairwise modes return only the immediate - * predecessor; {@link SchemaCompatibility#NONE_EXPERIMENTAL} returns nothing. - * - * @param subject the registry subject - * @return the versions to compare against - */ - public List versionsToCheck(String subject) { - Objects.requireNonNull(subject, "subject must not be null"); - SchemaCompatibility mode = registry.compatibilityOf(subject); - if (mode == SchemaCompatibility.NONE_EXPERIMENTAL) { - return List.of(); - } - List history = registry.history(subject).reversed(); - if (history.isEmpty()) { - return List.of(); - } - return isTransitive(mode) ? history : List.of(history.get(0)); - } - - /** - * Refuses a compatibility mode that must not reach a production destination. - * - * @param subject the registry subject - * @param destination the logical destination name, used in the diagnostic - * @throws MessageSchemaIncompatibleException when the subject is unchecked - */ - public void requireProductionMode(String subject, String destination) { - Objects.requireNonNull(subject, "subject must not be null"); - Objects.requireNonNull(destination, "destination must not be null"); - if (registry.compatibilityOf(subject) == SchemaCompatibility.NONE_EXPERIMENTAL) { - throw new MessageSchemaIncompatibleException( - "UNCHECKED_SCHEMA_ON_PRODUCTION_DESTINATION", - "subject %s is NONE_EXPERIMENTAL and cannot back the production destination %s" - .formatted(subject, destination)); - } - } - - /** - * Reports whether readers must be able to read data written by older writers. - * - * @param mode the compatibility mode - * @return true when the backward direction is enforced - */ - public static boolean checksBackward(SchemaCompatibility mode) { - Objects.requireNonNull(mode, "mode must not be null"); - return mode == SchemaCompatibility.BACKWARD - || mode == SchemaCompatibility.BACKWARD_TRANSITIVE - || mode == SchemaCompatibility.FULL - || mode == SchemaCompatibility.FULL_TRANSITIVE; - } - - /** - * Reports whether older readers must be able to read data written by the candidate. - * - * @param mode the compatibility mode - * @return true when the forward direction is enforced - */ - public static boolean checksForward(SchemaCompatibility mode) { - Objects.requireNonNull(mode, "mode must not be null"); - return mode == SchemaCompatibility.FORWARD - || mode == SchemaCompatibility.FORWARD_TRANSITIVE - || mode == SchemaCompatibility.FULL - || mode == SchemaCompatibility.FULL_TRANSITIVE; - } - - /** - * Reports whether a mode compares against the whole history. - * - * @param mode the compatibility mode - * @return true for the transitive modes - */ - public static boolean isTransitive(SchemaCompatibility mode) { - Objects.requireNonNull(mode, "mode must not be null"); - return mode == SchemaCompatibility.BACKWARD_TRANSITIVE - || mode == SchemaCompatibility.FORWARD_TRANSITIVE - || mode == SchemaCompatibility.FULL_TRANSITIVE; - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaReference.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaReference.java deleted file mode 100644 index 427c434f..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaReference.java +++ /dev/null @@ -1,39 +0,0 @@ -package dev.caskeleton.messaging.schema; - -import dev.caskeleton.messaging.api.SchemaVersion; -import java.net.URI; -import java.util.Objects; -import java.util.Optional; - -/** - * Points at the schema an encoded payload was written against. - * - *

Carried alongside the bytes rather than inferred from the message type, because a consumer - * that guesses the schema from the type is exactly the consumer that breaks when a producer rolls - * forward. - * - * @param subject the registry subject or schema name - * @param version the schema revision - * @param schemaUri the resolvable schema location, when one exists - */ -public record SchemaReference(String subject, SchemaVersion version, Optional schemaUri) { - - public SchemaReference { - Objects.requireNonNull(version, "schema version must not be null"); - Objects.requireNonNull(schemaUri, "schemaUri must not be null"); - if (subject == null || subject.isBlank()) { - throw new IllegalArgumentException("schema subject must not be blank"); - } - } - - /** - * Builds a reference with no resolvable location. - * - * @param subject the registry subject - * @param version the schema revision - * @return a schema reference - */ - public static SchemaReference of(String subject, SchemaVersion version) { - return new SchemaReference(subject, version, Optional.empty()); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaRegistry.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaRegistry.java deleted file mode 100644 index 49f39b3b..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaRegistry.java +++ /dev/null @@ -1,56 +0,0 @@ -package dev.caskeleton.messaging.schema; - -import dev.caskeleton.messaging.api.SchemaVersion; -import java.util.List; -import java.util.Optional; - -/** - * Resolves schemas by subject and version, and records the compatibility mode each subject is held - * to. - * - *

Deliberately a port. A hosted registry, a classpath directory of schema files, and a static - * in-process map are all legitimate sources depending on the deployment, and the platform's - * compatibility rules must hold identically across all three. Binding to a vendor client here would - * make the rules untestable without that vendor running. - * - *

{@link #history} returns oldest first. Transitive compatibility checks read the whole list, so - * an ordering mistake here silently converts a transitive check into a pairwise one. - */ -public interface SchemaRegistry { - - /** - * Resolves one schema definition. - * - * @param subject the registry subject - * @param version the schema revision - * @return the schema text, or empty when the subject or version is unknown - */ - Optional lookup(String subject, SchemaVersion version); - - /** - * Returns every registered version of a subject, oldest first. - * - * @param subject the registry subject - * @return the version history, empty when the subject is unknown - */ - List history(String subject); - - /** - * Returns the compatibility mode enforced for a subject. - * - * @param subject the registry subject - * @return the subject's compatibility mode - */ - SchemaCompatibility compatibilityOf(String subject); - - /** - * Returns the newest registered version of a subject. - * - * @param subject the registry subject - * @return the latest version, or empty when the subject is unknown - */ - default Optional latest(String subject) { - List versions = history(subject); - return versions.isEmpty() ? Optional.empty() : Optional.of(versions.get(versions.size() - 1)); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/CoreValueTypesTest.java b/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/CoreValueTypesTest.java deleted file mode 100644 index 38d374cb..00000000 --- a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/CoreValueTypesTest.java +++ /dev/null @@ -1,60 +0,0 @@ -package dev.caskeleton.messaging.api; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.delivery.DeliveryGuarantee; -import dev.caskeleton.messaging.api.delivery.OrderingScope; -import java.util.Arrays; -import java.util.UUID; -import org.junit.jupiter.api.Test; - -class CoreValueTypesTest { - - @Test - void messageTypeRejectsBlankValue() { - assertThatThrownBy(() -> new MessageType(" ")).isInstanceOf(IllegalArgumentException.class); - } - - @Test - void schemaVersionMustBePositive() { - assertThatThrownBy(() -> new SchemaVersion(0)).isInstanceOf(IllegalArgumentException.class); - } - - @Test - void guaranteeEnumsDoNotAdvertiseUnsupportedSemantics() { - assertThat(Arrays.stream(DeliveryGuarantee.values()).map(Enum::name)) - .doesNotContain("EXACTLY_ONCE"); - assertThat(Arrays.stream(OrderingScope.values()).map(Enum::name)).doesNotContain("GLOBAL"); - } - - @Test - void newMessageIdIsVersionSevenAndTimeOrdered() { - MessageId first = MessageId.newId(); - MessageId second = MessageId.newId(); - - assertThat(first.value().version()).isEqualTo(7); - assertThat(first.value().variant()).isEqualTo(2); - assertThat(first.value().compareTo(second.value())).isNegative(); - } - - @Test - void messageIdRejectsNullValue() { - assertThatThrownBy(() -> new MessageId(null)).isInstanceOf(NullPointerException.class); - } - - @Test - void causationIdWrapsAPredecessorMessageId() { - MessageId predecessor = new MessageId(UUID.fromString("0190f4aa-0000-7000-8000-000000000001")); - - assertThat(new CausationId(predecessor).value()).isEqualTo(predecessor); - } - - @Test - void producerAndCorrelationIdentifiersStayBounded() { - assertThatThrownBy(() -> new ProducerId("p".repeat(121))) - .isInstanceOf(IllegalArgumentException.class); - assertThatThrownBy(() -> new CorrelationId("c".repeat(161))) - .isInstanceOf(IllegalArgumentException.class); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/MessageEnvelopeTest.java b/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/MessageEnvelopeTest.java deleted file mode 100644 index c33ce515..00000000 --- a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/MessageEnvelopeTest.java +++ /dev/null @@ -1,141 +0,0 @@ -package dev.caskeleton.messaging.api; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.header.HeaderName; -import dev.caskeleton.messaging.api.header.HeaderValue; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import java.time.Instant; -import java.util.LinkedHashMap; -import java.util.Map; -import java.util.Optional; -import org.junit.jupiter.api.Test; - -class MessageEnvelopeTest { - - @Test - void applicationCannotSetReservedHeader() { - Map forged = - Map.of(new HeaderName("msg.id"), new HeaderValue("forged")); - - assertThatThrownBy(() -> MessageHeaders.application(forged)) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void reservedHeaderRejectionIsCaseInsensitive() { - Map forged = - Map.of(new HeaderName("MSG.Id"), new HeaderValue("forged")); - - assertThatThrownBy(() -> MessageHeaders.application(forged)) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void platformMayWriteReservedHeaders() { - MessageHeaders headers = - MessageHeaders.platform(Map.of(new HeaderName("msg.id"), new HeaderValue("0190f4aa"))); - - assertThat(headers.find("MSG.ID")).map(HeaderValue::value).hasValue("0190f4aa"); - } - - @Test - void secretHeadersAreRejected() { - Map secret = - Map.of(new HeaderName("Authorization"), new HeaderValue("Bearer secret")); - - assertThatThrownBy(() -> MessageHeaders.application(secret)) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void platformCannotWriteSecretHeadersEither() { - Map secret = - Map.of(new HeaderName("client_secret"), new HeaderValue("s3cr3t")); - - assertThatThrownBy(() -> MessageHeaders.platform(secret)) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void headerCountAboveSixtyFourIsRejected() { - Map tooMany = new LinkedHashMap<>(); - for (int i = 0; i < 65; i++) { - tooMany.put(new HeaderName("h" + i), new HeaderValue("v")); - } - - assertThatThrownBy(() -> MessageHeaders.application(tooMany)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("64"); - } - - @Test - void headerBytesAboveThirtyTwoKibibytesAreRejected() { - Map heavy = new LinkedHashMap<>(); - for (int i = 0; i < 16; i++) { - heavy.put(new HeaderName("h" + i), new HeaderValue("v".repeat(4096))); - } - - assertThatThrownBy(() -> MessageHeaders.application(heavy)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("32768"); - } - - @Test - void headerNameAboveOneHundredTwentyEightBytesIsRejected() { - assertThatThrownBy(() -> new HeaderName("n".repeat(129))) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void headerValueAboveFourKibibytesIsRejected() { - assertThatThrownBy(() -> new HeaderValue("v".repeat(4097))) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void payloadCannotBeNull() { - assertThatThrownBy(() -> TestEnvelopeFactory.envelope(null)) - .isInstanceOf(NullPointerException.class); - } - - @Test - void withPayloadPreservesLogicalIdentity() { - MessageEnvelope original = TestEnvelopeFactory.envelope("original"); - - MessageEnvelope encoded = original.withPayload(new byte[] {1, 2, 3}); - - assertThat(encoded.messageId()).isEqualTo(original.messageId()); - assertThat(encoded.messageType()).isEqualTo(original.messageType()); - assertThat(encoded.schemaVersion()).isEqualTo(original.schemaVersion()); - } -} - -/** - * Builds envelopes for tests. Package-private on purpose: production code must go through the - * publisher, which is what applies destination policy. - */ -final class TestEnvelopeFactory { - - private TestEnvelopeFactory() {} - - static MessageEnvelope envelope(T payload) { - return new MessageEnvelope<>( - MessageId.newId(), - new MessageType("order.created"), - new SchemaVersion(1), - Instant.parse("2026-08-10T00:00:00Z"), - Optional.of(Instant.parse("2026-08-10T00:00:00Z")), - new ProducerId("order-api"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - payload); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/ModuleSmokeTest.java b/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/ModuleSmokeTest.java deleted file mode 100644 index 782b6253..00000000 --- a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/ModuleSmokeTest.java +++ /dev/null @@ -1,13 +0,0 @@ -package dev.caskeleton.messaging.api; - -import static org.assertj.core.api.Assertions.assertThat; - -import org.junit.jupiter.api.Test; - -class ModuleSmokeTest { - - @Test - void coreApiModuleLoads() { - assertThat(ModuleSmokeTest.class.getPackageName()).isEqualTo("dev.caskeleton.messaging.api"); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/WireBoundaryRejectionTest.java b/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/WireBoundaryRejectionTest.java deleted file mode 100644 index cc73fd38..00000000 --- a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/WireBoundaryRejectionTest.java +++ /dev/null @@ -1,208 +0,0 @@ -package dev.caskeleton.messaging.api; - -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.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.Map; -import java.util.Optional; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.params.ParameterizedTest; -import org.junit.jupiter.params.provider.ValueSource; - -/** - * The rest of the wire boundary: values, correlation, trace propagation and the two denylists. - * - *

{@link WireSafeValueObjectTest} covers the name side. This covers what was still unbounded - * after it: a header value carrying CRLF straight to the broker, a correlation id bounded - * in Java characters rather than bytes, a {@code traceparent} that was any string at all, and two - * denylists that matched exact spellings only. - */ -class WireBoundaryRejectionTest { - - /** The C0 and DEL code points a broker disagrees with itself about. */ - @ParameterizedTest - @ValueSource(ints = {0x00, 0x09, 0x0A, 0x0D, 0x1B, 0x7F}) - @DisplayName("a header value carrying a control character is refused") - void aHeaderValueWithAControlCharacterIsRefused(int codePoint) { - // NUL truncates the value inside a broker that hands it to C string handling; LF and CR end - // the header on a line-oriented binding and start one the caller wrote; ESC and DEL are - // stripped by some intermediaries and preserved by others. Tab is refused with them because a - // line-folding binding and a length-prefixed one disagree about whether it ends the value. - String value = "order-" + (char) codePoint + "-created"; - - assertThatThrownBy(() -> new HeaderValue(value)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("control characters"); - } - - @Test - @DisplayName("an ordinary header value, including non-ASCII text, is still accepted") - void anOrdinaryHeaderValueIsAccepted() { - assertThatCode(() -> new HeaderValue("주문 생성됨 / order created")).doesNotThrowAnyException(); - } - - @Test - @DisplayName("a header value is bounded in bytes, not in characters") - void aHeaderValueIsBoundedInBytes() { - // 4096 characters of three bytes each: inside any character bound, three times the byte one. - assertThatThrownBy(() -> new HeaderValue("가".repeat(4096))) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("UTF-8 bytes"); - } - - @Test - @DisplayName("a correlation id is bounded in bytes and refuses control characters") - void aCorrelationIdIsBoundedInBytes() { - assertThatThrownBy(() -> new CorrelationId("가".repeat(160))) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("UTF-8 bytes"); - assertThatThrownBy(() -> new CorrelationId("flow-1\r\nmsg.id: forged")) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("control characters"); - assertThatCode(() -> new CorrelationId("flow-0198e2b1")).doesNotThrowAnyException(); - } - - @ParameterizedTest - @ValueSource( - strings = { - "not-a-traceparent", - "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331", - "00-0AF7651916CD43DD8448EB211C80319C-b7ad6b7169203331-01", - "ff-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01", - "00-00000000000000000000000000000000-b7ad6b7169203331-01", - "00-0af7651916cd43dd8448eb211c80319c-0000000000000000-01", - "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01\r\nx: y" - }) - @DisplayName("an invalid traceparent is refused rather than propagated") - void anInvalidTraceparentIsRefused(String traceparent) { - // In order: not the grammar at all; no flags field; uppercase hex, which a collector comparing - // trace ids as strings reads as a different trace; the reserved ff version; an all-zero trace - // id and an all-zero parent span id, both of which the standard declares invalid; and a value - // with a CRLF, which is a header injection once it is written to the traceparent header. - assertThatThrownBy(() -> TraceContext.of(traceparent)) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - @DisplayName("the W3C example traceparent is accepted") - void theStandardExampleIsAccepted() { - assertThatCode(() -> TraceContext.of("00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01")) - .doesNotThrowAnyException(); - } - - @Test - @DisplayName("tracestate is bounded by the standard's member count and size") - void tracestateIsBounded() { - String parent = "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"; - - assertThatCode( - () -> - new TraceContext( - Optional.of(parent), - Optional.of("congo=t61rcWkgMzE,rojo=00f067aa0ba902b7"), - Optional.empty())) - .doesNotThrowAnyException(); - - String tooManyMembers = - java.util.stream.IntStream.range(0, 33) - .mapToObj(index -> "k" + index + "=v") - .collect(java.util.stream.Collectors.joining(",")); - assertThatThrownBy( - () -> - new TraceContext( - Optional.of(parent), Optional.of(tooManyMembers), Optional.empty())) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("32 list members"); - - assertThatThrownBy( - () -> - new TraceContext( - Optional.of(parent), Optional.of("congo=a\r\nx=y"), Optional.empty())) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - @DisplayName("tracestate without a traceparent is vendor state belonging to no trace") - void tracestateWithoutATraceparentIsRefused() { - assertThatThrownBy( - () -> - new TraceContext( - Optional.empty(), Optional.of("congo=t61rcWkgMzE"), Optional.empty())) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("without a traceparent"); - } - - @Test - @DisplayName("baggage is bounded in total bytes and in member count") - void baggageIsBounded() { - assertThatCode( - () -> - new TraceContext( - Optional.empty(), Optional.empty(), Optional.of("tenant=acme,region=eu"))) - .doesNotThrowAnyException(); - - String oversize = "k=" + "v".repeat(8200); - assertThatThrownBy( - () -> new TraceContext(Optional.empty(), Optional.empty(), Optional.of(oversize))) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("8192 bytes"); - - String tooManyMembers = - java.util.stream.IntStream.range(0, 65) - .mapToObj(index -> "k" + index + "=v") - .collect(java.util.stream.Collectors.joining(",")); - assertThatThrownBy( - () -> new TraceContext(Optional.empty(), Optional.empty(), Optional.of(tooManyMembers))) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("64 members"); - } - - @ParameterizedTest - @ValueSource(strings = {"x-api-key", "auth-token", "db_password", "request.signature", "Cookie"}) - @DisplayName("a credential-shaped header name is refused however it is spelled") - void aCredentialShapedNameIsRefused(String name) { - assertThatThrownBy( - () -> - MessageHeaders.application(Map.of(new HeaderName(name), new HeaderValue("opaque")))) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("not allowed"); - } - - @Test - @DisplayName("a name that merely contains the letters of a secret is still accepted") - void aNameThatMerelyContainsTheLettersIsAccepted() { - assertThatCode( - () -> - MessageHeaders.application( - Map.of( - new HeaderName("tokenizer-version"), new HeaderValue("3"), - new HeaderName("secretariat-id"), new HeaderValue("s-9")))) - .as("segment matching, not substring matching") - .doesNotThrowAnyException(); - } - - @Test - @DisplayName("the platform namespace is reserved whether or not the name exists yet") - void thePlatformNamespaceIsReserved() { - assertThat(ReservedHeaders.isReserved("msg.not-defined-in-this-release")).isTrue(); - assertThatThrownBy( - () -> - MessageHeaders.application( - Map.of(new HeaderName("msg.not-defined-yet"), new HeaderValue("mine")))) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("not allowed"); - - // The platform factory still writes its own namespace; that is the whole distinction. - assertThatCode( - () -> - MessageHeaders.platform( - Map.of(new HeaderName(ReservedHeaders.MESSAGE_ID), new HeaderValue("m-1")))) - .doesNotThrowAnyException(); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/WireSafeValueObjectTest.java b/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/WireSafeValueObjectTest.java deleted file mode 100644 index 1af6d196..00000000 Binary files a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/WireSafeValueObjectTest.java and /dev/null differ diff --git a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/delivery/ConsumerContractTest.java b/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/delivery/ConsumerContractTest.java deleted file mode 100644 index 3de62ce8..00000000 --- a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/delivery/ConsumerContractTest.java +++ /dev/null @@ -1,129 +0,0 @@ -package dev.caskeleton.messaging.api.delivery; - -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.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 java.time.Instant; -import java.util.Optional; -import org.junit.jupiter.api.Test; - -class ConsumerContractTest { - - @Test - void retryCarriesStableFailureCategory() { - FailureDescriptor failure = - new FailureDescriptor( - FailureCategory.PROCESSING_TRANSIENT, - "DOWNSTREAM_TIMEOUT", - true, - "downstream timed out", - Optional.of("TimeoutException")); - - HandleResult result = new HandleResult.Retry(failure); - - assertThat(((HandleResult.Retry) result).failure().retryable()).isTrue(); - } - - @Test - void deliveryMetadataCountsInitialDeliveryAsAttemptOne() { - DeliveryMetadata metadata = DeliveryMetadataFixture.initial(); - - assertThat(metadata.deliveryAttempt()).isEqualTo(1); - assertThat(metadata.redelivered()).isFalse(); - } - - @Test - void firstDeliveryCannotBeFlaggedAsRedelivered() { - assertThatThrownBy( - () -> - new DeliveryMetadata( - new DestinationName("order-events"), - 1, - true, - Optional.empty(), - Optional.empty(), - Optional.empty(), - Instant.parse("2026-08-10T00:00:00Z"))) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void deliveryAttemptIsNeverZero() { - assertThatThrownBy( - () -> - new DeliveryMetadata( - new DestinationName("order-events"), - 0, - false, - Optional.empty(), - Optional.empty(), - Optional.empty(), - Instant.parse("2026-08-10T00:00:00Z"))) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void handleResultPermitsExactlyTheFourDeclaredOutcomes() { - assertThat(HandleResult.class.getPermittedSubclasses()) - .containsExactlyInAnyOrder( - HandleResult.Success.class, - HandleResult.Retry.class, - HandleResult.DeadLetter.class, - HandleResult.Reject.class); - } - - @Test - void unknownSettlementIsNotSuccess() { - SettlementResult result = - new SettlementResult( - SettlementCompletion.UNKNOWN, - SettlementEvidence.unknown(), - Optional.of( - FailureDescriptor.of( - FailureCategory.AMBIGUOUS, "SETTLEMENT_UNKNOWN", "ack not confirmed"))); - - assertThat(result.completion()).isNotEqualTo(SettlementCompletion.SETTLED); - assertThat(result.evidence().redeliveryPossible()).isTrue(); - } - - @Test - void settledResultCannotLeaveRedeliveryPossible() { - assertThatThrownBy( - () -> - new SettlementResult( - SettlementCompletion.SETTLED, SettlementEvidence.unknown(), Optional.empty())) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void deliveryContextReportsHandlerDeadlineExpiry() { - DeliveryContext context = - new DeliveryContext(Instant.parse("2026-08-10T00:00:30Z"), false, "order-projection"); - - assertThat(context.isExpired(Instant.parse("2026-08-10T00:00:29Z"))).isFalse(); - assertThat(context.isExpired(Instant.parse("2026-08-10T00:00:30Z"))).isTrue(); - } -} - -/** Builds delivery metadata for tests without exposing a production factory. */ -final class DeliveryMetadataFixture { - - private DeliveryMetadataFixture() {} - - static DeliveryMetadata initial() { - return new DeliveryMetadata( - new DestinationName("order-events"), - 1, - false, - Optional.empty(), - Optional.of("order.events.v1-0"), - Optional.of("order-projection"), - Instant.parse("2026-08-10T00:00:00Z")); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/destination/DestinationCapabilityTest.java b/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/destination/DestinationCapabilityTest.java deleted file mode 100644 index da9c2701..00000000 --- a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/destination/DestinationCapabilityTest.java +++ /dev/null @@ -1,75 +0,0 @@ -package dev.caskeleton.messaging.api.destination; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.MessageType; -import org.junit.jupiter.api.Test; - -class DestinationCapabilityTest { - - @Test - void logicalDestinationDoesNotContainBrokerSpecificAddress() { - MessageDestination destination = - new MessageDestination<>( - new DestinationName("order-events"), new MessageType("order.created"), String.class); - - assertThat(destination.name().value()).isEqualTo("order-events"); - } - - @Test - void destinationNameRejectsBrokerSeparatorsAndWhitespace() { - assertThatThrownBy(() -> new DestinationName("topic://orders")) - .isInstanceOf(IllegalArgumentException.class); - assertThatThrownBy(() -> new DestinationName("order events")) - .isInstanceOf(IllegalArgumentException.class); - assertThatThrownBy(() -> new DestinationName("Order-Events")) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void emptyCapabilitySetAdvertisesNothing() { - MessagingCapabilities capabilities = MessagingCapabilities.none(); - - assertThat(capabilities.supported()).isEmpty(); - } - - @Test - @org.junit.jupiter.api.DisplayName("이름 붙인 capability만 지원하고 넘긴 집합을 나중에 바꿔도 영향이 없다") - void aCapabilitySetSupportsExactlyWhatWasNamedAndIgnoresLaterChangesToTheInput() { - // given - java.util.Set input = - java.util.EnumSet.of(MessagingCapabilities.Capability.ORDERED_STREAM); - MessagingCapabilities capabilities = new MessagingCapabilities(input); - - // when - input.add(MessagingCapabilities.Capability.DEDUPLICATED_PUBLISH); - - // then - assertThat(capabilities.supports(MessagingCapabilities.Capability.ORDERED_STREAM)).isTrue(); - assertThat(capabilities.supports(MessagingCapabilities.Capability.DEDUPLICATED_PUBLISH)) - .isFalse(); - } - - @Test - void destinationCapabilitiesRequireABrokerName() { - MessagingCapabilities capabilities = MessagingCapabilities.none(); - DestinationName name = new DestinationName("order-events"); - - assertThatThrownBy(() -> new DestinationCapabilities(name, " ", capabilities)) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void destinationKindCoversEveryDeclaredInteractionPattern() { - assertThat(DestinationKind.values()) - .containsExactly( - DestinationKind.ASYNC_COMMAND, - DestinationKind.DOMAIN_EVENT, - DestinationKind.INTEGRATION_EVENT, - DestinationKind.WORK_QUEUE, - DestinationKind.PUBLISH_SUBSCRIBE, - DestinationKind.EVENT_STREAM, - DestinationKind.REQUEST_REPLY); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/publish/PublishResultTest.java b/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/publish/PublishResultTest.java deleted file mode 100644 index 122ede7e..00000000 --- a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/publish/PublishResultTest.java +++ /dev/null @@ -1,286 +0,0 @@ -package dev.caskeleton.messaging.api.publish; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import java.time.Duration; -import java.util.Optional; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -class PublishResultTest { - - /** A coordinate no adapter would have produced for a message that never left. */ - private static final BrokerPosition POSITION = - new BrokerPosition() { - @Override - public String broker() { - return "kafka"; - } - - @Override - public java.util.Map diagnosticAttributes() { - return java.util.Map.of("topic", "order-events", "partition", "0", "offset", "17"); - } - }; - - private static final FailureDescriptor AMBIGUOUS_FAILURE = - FailureDescriptor.of(FailureCategory.AMBIGUOUS, "CONFIRM_TIMEOUT", "confirm timed out"); - - @Test - void aRejectionCannotClaimTheBrokerAcceptedIt() { - PublishEvidence accepted = - PublishEvidence.confirmed(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK); - - assertThatThrownBy( - () -> - new PublishResult( - PublishCompletion.REJECTED, - accepted, - RoutingOutcome.ROUTED, - Optional.empty(), - 1, - Duration.ofMillis(10), - Optional.of(AMBIGUOUS_FAILURE))) - .as("re-publishing a message the broker acknowledged is how one order becomes two") - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void aConfirmationCannotBeUnsureWhetherItRouted() { - assertThatThrownBy( - () -> - new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.BROKER_ACK), - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, - Duration.ofMillis(10), - Optional.empty())) - .as("the response that confirmed the publish is the one that says whether it routed") - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void aRoutedPublishIsNotAmbiguous() { - assertThatThrownBy( - () -> - new PublishResult( - PublishCompletion.AMBIGUOUS, - PublishEvidence.ambiguous(), - RoutingOutcome.ROUTED, - Optional.empty(), - 1, - Duration.ofMillis(10), - Optional.of(AMBIGUOUS_FAILURE))) - .as("only the broker can report routing, and a broker that reported it answered") - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void anUntransmittedPublishHasNoBrokerPosition() { - assertThatThrownBy( - () -> - new PublishResult( - PublishCompletion.REJECTED, - PublishEvidence.notTransmitted(), - RoutingOutcome.NOT_APPLICABLE, - Optional.of(POSITION), - 1, - Duration.ofMillis(10), - Optional.of(AMBIGUOUS_FAILURE))) - .as("a coordinate for bytes that never left belongs to some other message") - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void confirmedResultRequiresBrokerAcceptance() { - PublishEvidence evidence = - new PublishEvidence(false, TransmissionEvidence.TRANSMITTED, false, ConfirmationLevel.NONE); - - assertThatThrownBy( - () -> - new PublishResult( - PublishCompletion.CONFIRMED, - evidence, - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, - Duration.ofMillis(10), - Optional.empty())) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void evidenceCannotClaimConfirmationWithoutBrokerAcceptance() { - assertThatThrownBy( - () -> - new PublishEvidence( - true, - TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED, - false, - ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK)) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void ambiguousResultCannotClaimReplicationConfirmation() { - PublishEvidence evidence = - new PublishEvidence( - true, - TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED, - true, - ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK); - - assertThatThrownBy( - () -> - new PublishResult( - PublishCompletion.AMBIGUOUS, - evidence, - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, - Duration.ofSeconds(5), - Optional.of(AMBIGUOUS_FAILURE))) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("ambiguous"); - } - - @Test - void confirmedResultCannotBeUnroutable() { - assertThatThrownBy( - () -> - new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.BROKER_ACK), - RoutingOutcome.UNROUTABLE, - Optional.empty(), - 1, - Duration.ofMillis(3), - Optional.empty())) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void untransmittedPublishIsRejectedRatherThanAmbiguous() { - assertThatThrownBy( - () -> - new PublishResult( - PublishCompletion.AMBIGUOUS, - PublishEvidence.notTransmitted(), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ofMillis(1), - Optional.of(AMBIGUOUS_FAILURE))) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void nonConfirmedResultRequiresAFailureDescriptor() { - assertThatThrownBy( - () -> - new PublishResult( - PublishCompletion.REJECTED, - PublishEvidence.notTransmitted(), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ofMillis(1), - Optional.empty())) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void confirmedPublishIsWellFormedAndNotAmbiguous() { - PublishResult result = - new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK), - RoutingOutcome.ROUTED, - Optional.empty(), - 1, - Duration.ofMillis(12), - Optional.empty()); - - assertThat(result.mayHaveBeenStored()).isFalse(); - assertThat(result.evidence().confirmationLevel()) - .isEqualTo(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK); - } - - @Test - void ambiguousPublishReportsThatTheBrokerMayHoldTheMessage() { - PublishResult result = - new PublishResult( - PublishCompletion.AMBIGUOUS, - PublishEvidence.ambiguous(), - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, - Duration.ofSeconds(5), - Optional.of(AMBIGUOUS_FAILURE)); - - assertThat(result.mayHaveBeenStored()).isTrue(); - } - - @Test - void attemptsCountTheFirstTransportAttemptAsOne() { - assertThatThrownBy( - () -> - new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.BROKER_ACK), - RoutingOutcome.ROUTED, - Optional.empty(), - 0, - Duration.ofMillis(1), - Optional.empty())) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - @DisplayName("거부 factory는 전송되지 않았고 라우팅 대상이 아닌 결과를 만든다") - void theRejectedFactoryReportsNothingWasTransmittedOrRouted() { - // when - PublishResult result = PublishResult.rejected(Duration.ofMillis(3), AMBIGUOUS_FAILURE); - - // then - assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); - assertThat(result.evidence()).isEqualTo(PublishEvidence.notTransmitted()); - assertThat(result.routingOutcome()).isEqualTo(RoutingOutcome.NOT_APPLICABLE); - assertThat(result.failure()).contains(AMBIGUOUS_FAILURE); - } - - @Test - @DisplayName("모호 factory는 브로커가 메시지를 가졌을 수 있다고 보고한다") - void theAmbiguousFactoryReportsTheBrokerMayHoldTheMessage() { - // when - PublishResult result = PublishResult.ambiguous(Duration.ofMillis(3), AMBIGUOUS_FAILURE); - - // then - assertThat(result.mayHaveBeenStored()).isTrue(); - assertThat(result.evidence()).isEqualTo(PublishEvidence.ambiguous()); - assertThat(result.routingOutcome()).isEqualTo(RoutingOutcome.UNKNOWN); - } - - @Test - @DisplayName("확인 factory는 브로커 수락과 위치를 담고 실패 설명은 없다") - void theConfirmedFactoryCarriesAcceptanceAndPositionWithoutAFailure() { - // when - PublishResult result = - PublishResult.confirmed( - ConfirmationLevel.BROKER_ACK, - RoutingOutcome.NOT_APPLICABLE, - Optional.of(POSITION), - Duration.ofMillis(3)); - - // then - assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED); - assertThat(result.evidence().brokerAccepted()).isTrue(); - assertThat(result.position()).contains(POSITION); - assertThat(result.failure()).isEmpty(); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/BoundedByteSinkTest.java b/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/BoundedByteSinkTest.java deleted file mode 100644 index 894ffb6a..00000000 --- a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/BoundedByteSinkTest.java +++ /dev/null @@ -1,87 +0,0 @@ -package dev.caskeleton.messaging.schema; - -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.MessageTooLargeException; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * The boundary the codecs delegate to. - * - *

Each codec used to serialize into an unbounded buffer and compare the finished length to the - * limit. That check reports an oversized payload; it does not prevent one. The difference only - * shows up for a payload whose serialized form is orders of magnitude larger than the bound, which - * is precisely the case that matters — the consumer is out of heap before the comparison runs. - */ -class BoundedByteSinkTest { - - private static final int MAX = 64; - - @Test - @DisplayName("one byte under, exactly at, and one byte over the limit") - void theLimitIsInclusiveAndTheNextByteIsRefused() { - assertThatCode(() -> fill(MAX - 1)).doesNotThrowAnyException(); - assertThatCode(() -> fill(MAX)).doesNotThrowAnyException(); - - assertThatThrownBy(() -> fill(MAX + 1)) - .isInstanceOf(MessageTooLargeException.class) - .hasMessageContaining("refused at byte 65"); - } - - @Test - @DisplayName("a much larger stream stops at the limit rather than after allocation") - void aMuchLargerStreamStopsAtTheLimit() { - BoundedByteSink sink = BoundedByteSink.of(MAX, "PAYLOAD_TOO_LARGE"); - - assertThatThrownBy( - () -> { - // Ten mebibytes offered one kibibyte at a time. A buffer-then-check codec would have - // held all of it; this refuses the chunk that crosses the bound. - for (int chunk = 0; chunk < 10_240; chunk++) { - sink.write(new byte[1_024], 0, 1_024); - } - }) - .isInstanceOf(MessageTooLargeException.class); - - assertThat(sink.written()) - .as("nothing beyond the bound was ever admitted") - .isLessThanOrEqualTo(MAX); - assertThat(sink.toByteArray()).isEmpty(); - } - - @Test - @DisplayName("a pre-flight size check does not consume the budget") - void aPreFlightCheckDoesNotConsumeTheBudget() { - BoundedByteSink sink = BoundedByteSink.of(MAX, "PAYLOAD_TOO_LARGE"); - - sink.requireFits(MAX); - - assertThat(sink.written()).isZero(); - assertThatCode(() -> sink.write(new byte[MAX], 0, MAX)).doesNotThrowAnyException(); - } - - @Test - @DisplayName("a pre-flight check refuses a size that cannot fit") - void aPreFlightCheckRefusesASizeThatCannotFit() { - BoundedByteSink sink = BoundedByteSink.of(MAX, "AVRO_PAYLOAD_TOO_LARGE"); - - assertThatThrownBy(() -> sink.requireFits(MAX + 1)) - .isInstanceOf(MessageTooLargeException.class) - .asInstanceOf( - org.assertj.core.api.InstanceOfAssertFactories.type(MessageTooLargeException.class)) - .extracting(failure -> failure.failure().code()) - .as("the sink reports the codec's own code, not a generic one") - .isEqualTo("AVRO_PAYLOAD_TOO_LARGE"); - } - - private static byte[] fill(int size) { - BoundedByteSink sink = BoundedByteSink.of(MAX, "PAYLOAD_TOO_LARGE"); - for (int index = 0; index < size; index++) { - sink.write('a'); - } - return sink.toByteArray(); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/RawBytesMessageCodecTest.java b/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/RawBytesMessageCodecTest.java deleted file mode 100644 index 69531deb..00000000 --- a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/RawBytesMessageCodecTest.java +++ /dev/null @@ -1,67 +0,0 @@ -package dev.caskeleton.messaging.schema; - -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.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageSerializationException; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import java.util.Optional; -import org.junit.jupiter.api.Test; - -class RawBytesMessageCodecTest { - - private static final MessageType OPAQUE = new MessageType("opaque.blob"); - private static final SchemaVersion V1 = new SchemaVersion(1); - - private final RawBytesMessageCodec codec = new RawBytesMessageCodec(); - - @Test - void roundTripsOpaqueBytes() { - byte[] payload = {1, 2, 3, 4}; - - EncodedMessage encoded = codec.encode(OPAQUE, V1, payload); - - assertThat(codec.decode(OPAQUE, V1, encoded.bytes(), byte[].class)).containsExactly(1, 2, 3, 4); - } - - @Test - void advertisesOpaqueContentTypeAndNoSchemaReference() { - EncodedMessage encoded = codec.encode(OPAQUE, V1, new byte[] {9}); - - assertThat(codec.contentType()).isEqualTo(ContentType.OCTET_STREAM); - assertThat(encoded.schemaReference()).isEmpty(); - } - - @Test - void refusesNonByteArrayPayloads() { - assertThatThrownBy(() -> codec.encode(OPAQUE, V1, "text")) - .isInstanceOf(MessageSerializationException.class); - } - - @Test - void refusesDecodingToAnythingButByteArray() { - assertThatThrownBy(() -> codec.decode(OPAQUE, V1, new byte[] {1}, String.class)) - .isInstanceOf(MessageSerializationException.class); - } - - @Test - void enforcesTheByteLimit() { - RawBytesMessageCodec small = new RawBytesMessageCodec(4); - - assertThatThrownBy(() -> small.encode(OPAQUE, V1, new byte[5])) - .isInstanceOf(MessageTooLargeException.class); - } - - @Test - void encodedMessageDefensivelyCopiesItsBytes() { - byte[] source = {1, 2, 3}; - EncodedMessage encoded = new EncodedMessage(source, ContentType.OCTET_STREAM, Optional.empty()); - - source[0] = 99; - - assertThat(encoded.bytes()).containsExactly(1, 2, 3); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidatorTest.java b/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidatorTest.java deleted file mode 100644 index 7976c059..00000000 --- a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidatorTest.java +++ /dev/null @@ -1,109 +0,0 @@ -package dev.caskeleton.messaging.schema; - -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.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageSchemaIncompatibleException; -import java.util.List; -import java.util.Optional; -import org.junit.jupiter.api.Test; - -class SchemaCompatibilityValidatorTest { - - private static final SchemaVersion V1 = new SchemaVersion(1); - private static final SchemaVersion V2 = new SchemaVersion(2); - private static final SchemaVersion V3 = new SchemaVersion(3); - - /** A registry whose history is deliberately oldest-first, as the port documents. */ - private record FixedRegistry(List versions, SchemaCompatibility mode) - implements SchemaRegistry { - - @Override - public Optional lookup(String subject, SchemaVersion version) { - return versions.contains(version) ? Optional.of("{}") : Optional.empty(); - } - - @Override - public List history(String subject) { - return versions; - } - - @Override - public SchemaCompatibility compatibilityOf(String subject) { - return mode; - } - } - - private static SchemaCompatibilityValidator validator(SchemaCompatibility mode) { - return new SchemaCompatibilityValidator(new FixedRegistry(List.of(V1, V2, V3), mode)); - } - - @Test - void aPairwiseModeChecksOnlyTheImmediatePredecessor() { - assertThat(validator(SchemaCompatibility.BACKWARD).versionsToCheck("order.created")) - .containsExactly(V3); - } - - @Test - void aTransitiveModeChecksTheWholeHistoryNewestFirst() { - assertThat(validator(SchemaCompatibility.BACKWARD_TRANSITIVE).versionsToCheck("order.created")) - .as( - "a chain of individually compatible changes can still break a consumer several releases behind") - .containsExactly(V3, V2, V1); - } - - @Test - void anUncheckedModeComparesAgainstNothing() { - assertThat(validator(SchemaCompatibility.NONE_EXPERIMENTAL).versionsToCheck("order.created")) - .isEmpty(); - } - - @Test - void anEmptyHistoryHasNothingToCompareAgainst() { - SchemaCompatibilityValidator validator = - new SchemaCompatibilityValidator( - new FixedRegistry(List.of(), SchemaCompatibility.FULL_TRANSITIVE)); - - assertThat(validator.versionsToCheck("order.created")).isEmpty(); - } - - @Test - void anUncheckedSubjectCannotBackAProductionDestination() { - assertThatThrownBy( - () -> - validator(SchemaCompatibility.NONE_EXPERIMENTAL) - .requireProductionMode("order.created", "orders.v1")) - .isInstanceOf(MessageSchemaIncompatibleException.class) - .hasMessageContaining("orders.v1"); - } - - @Test - void aCheckedSubjectMayBackAProductionDestination() { - assertThatCode( - () -> - validator(SchemaCompatibility.FULL) - .requireProductionMode("order.created", "orders.v1")) - .doesNotThrowAnyException(); - } - - @Test - void fullModeEnforcesBothDirections() { - assertThat(SchemaCompatibilityValidator.checksBackward(SchemaCompatibility.FULL)).isTrue(); - assertThat(SchemaCompatibilityValidator.checksForward(SchemaCompatibility.FULL)).isTrue(); - } - - @Test - void eachOneDirectionalModeEnforcesOnlyItsOwnDirection() { - assertThat(SchemaCompatibilityValidator.checksForward(SchemaCompatibility.BACKWARD)).isFalse(); - assertThat(SchemaCompatibilityValidator.checksBackward(SchemaCompatibility.FORWARD)).isFalse(); - } - - @Test - void theLatestVersionIsTheNewestNotTheFirstListed() { - SchemaRegistry registry = new FixedRegistry(List.of(V1, V2, V3), SchemaCompatibility.FULL); - - assertThat(registry.latest("order.created")).hasValue(V3); - } -} diff --git a/src/platforms/messaging/messaging-kafka/build.gradle b/src/platforms/messaging/messaging-kafka/build.gradle deleted file mode 100644 index 620f1090..00000000 --- a/src/platforms/messaging/messaging-kafka/build.gradle +++ /dev/null @@ -1,119 +0,0 @@ -plugins { - id 'java-test-fixtures' - id 'ca.platform-module' - id 'me.champeau.jmh' -} - -jmh { - jmhVersion = libs.versions.jmh.get() - includeTests = true -} - -testing { - suites { - integrationTest(JvmTestSuite) { - dependencies { - implementation project() - implementation testFixtures(project()) - } - } - } -} -configurations { - integrationTestImplementation.extendsFrom testImplementation - integrationTestRuntimeOnly.extendsFrom testRuntimeOnly -} - -dependencies { - // No spring-kafka. It was declared here and imported by nothing: this adapter drives the plain - // `org.apache.kafka` producer API directly, and a declared library that no source names is a - // resolution, a lock entry and a transitive surface bought for nothing. - api project(':messaging:messaging-core-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: the public constructors and mappers take and return Producer, ProducerRecord and - // RecordMetadata. Hiding the dependency does not hide the types — it only stops a consumer - // from compiling against the API this module documents. - api 'org.apache.kafka:kafka-clients' - - // Test-only. The shared adapter contract is what makes "Stable" mean something, so the Kafka - // adapter runs it rather than asserting its own behaviour in its own terms. - testImplementation project(':messaging:messaging-testkit') - testFixturesImplementation project(':messaging:messaging-testkit') - - // Live-broker certification. The deterministic suite proves the platform's semantics; these - // prove the client actually behaves that way against the version the matrix claims. - integrationTestImplementation 'org.testcontainers:testcontainers-junit-jupiter' - integrationTestImplementation 'org.testcontainers:testcontainers-kafka' - integrationTestImplementation 'org.testcontainers:testcontainers-toxiproxy' - integrationTestImplementation libs.toxiproxy.java -} - -// The certification lane, and the gate that makes its output the only source of a Stable claim. -// -// `CertifiedEvidence` used to be a hand-written list of three scenarios, and every consumer of it — -// the compatibility matrix, the cross-broker release suite, the support matrix document — believed -// it without a container ever starting. The lane below produces that list, and -// `verifyMessagingCertificationEvidence` refuses to pass when the committed manifest claims a -// scenario this run did not prove. Editing the manifest by hand therefore fails the build; running -// the lane rewrites it. -strictTestLanes { - lane('messagingCertificationTest') { - integration() - sourceSet = 'integrationTest' - description = 'Runs the broker fault scenarios against a real Kafka and writes the ' + - 'certification evidence the compatibility matrix reads.' - // Pinned images. A certification claim names the build it was made against, so a - // floating tag would make a red run unattributable and a green one unrepeatable. - // `-PmessagingKafkaImage=` overrides for a one-off run against another version. - systemProperty 'messaging.kafka.image', - (project.findProperty('messagingKafkaImage') ?: testContainerImages['kafka']).toString() - systemProperty 'messaging.toxiproxy.image', - (project.findProperty('messagingToxiproxyImage') - ?: testContainerImages['toxiproxy']).toString() - systemProperty 'messaging.certification.manifest', - project.layout.buildDirectory - .file('messaging-certification/broker-certification-evidence.jsonl') - .get().asFile.absolutePath - // The commit is provenance recorded in the evidence, not an equality key for the - // behavioral claim gate. Re-running the same scenario on a later commit refreshes - // provenance without creating a different scenario identity. - // Read from the environment rather than a `-P` flag so the CI job's command line stays - // the literal grammar the gate matrix lint accepts. - systemProperty 'messaging.certification.commit', - (project.findProperty('certificationCommit') - ?: providers.environmentVariable('GITHUB_SHA').getOrElse('local')) - .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('platforms/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/src/platforms/messaging/messaging-kafka/gradle.lockfile b/src/platforms/messaging/messaging-kafka/gradle.lockfile deleted file mode 100644 index 88743033..00000000 --- a/src/platforms/messaging/messaging-kafka/gradle.lockfile +++ /dev/null @@ -1,113 +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.11.4=integrationTestRuntimeClasspath,jmhRuntimeClasspath,runtimeClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -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.luben:zstd-jni:1.5.6-10=integrationTestRuntimeClasspath,jmhRuntimeClasspath,runtimeClasspath,testFixturesRuntimeClasspath,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,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=integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,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.7.2-jre=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -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 -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 -eu.rekawek.toxiproxy:toxiproxy-java:2.1.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath -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.8=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -io.micrometer:micrometer-core:1.16.8=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -io.micrometer:micrometer-observation:1.16.8=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,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -net.java.dev.jna:jna:5.18.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath -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=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 -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.kafka:kafka-clients:4.1.2=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,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=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 -org.codehaus.plexus:plexus-utils:3.6.1=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,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,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,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=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 -org.rnorth.duct-tape:duct-tape:1.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.slf4j:slf4j-api:2.0.20=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,runtimeClasspath,spotbugs,spotbugsSlf4j,testFixturesRuntimeClasspath,testRuntimeClasspath -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.testcontainers:testcontainers-junit-jupiter:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-kafka:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-toxiproxy:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.xerial.snappy:snappy-java:1.1.10.9=integrationTestRuntimeClasspath,jmhRuntimeClasspath,runtimeClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaAmbiguityChaosIT.java b/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaAmbiguityChaosIT.java deleted file mode 100644 index e2787738..00000000 --- a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaAmbiguityChaosIT.java +++ /dev/null @@ -1,175 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import static org.assertj.core.api.Assertions.assertThat; - -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.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.schema.EncodedMessage; -import dev.caskeleton.messaging.testkit.DockerAvailability; -import dev.caskeleton.messaging.transport.TransportPublishRequest; -import java.nio.charset.StandardCharsets; -import java.time.Instant; -import java.util.Optional; -import java.util.Properties; -import org.apache.kafka.clients.producer.KafkaProducer; -import org.apache.kafka.clients.producer.Producer; -import org.apache.kafka.clients.producer.ProducerConfig; -import org.apache.kafka.common.serialization.ByteArraySerializer; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.condition.EnabledIf; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; -import org.testcontainers.kafka.KafkaContainer; - -/** - * Proves the platform's hardest guarantee against a live broker: a lost confirmation is reported, - * not guessed. - * - *

The broker is frozen mid-flight with {@code docker pause}. The producer's socket stays open - * and the record may already have been written to it, but no acknowledgement can arrive — which is - * exactly the state a network partition or a broker stall produces, and exactly the state that has - * no correct boolean answer. - * - *

The assertion is deliberately strict about what the result may not claim: no broker - * acceptance, no confirmation level, and a non-retryable ambiguous failure. An adapter that - * optimistically reported success here would lose the message on a real partition; one that - * reported a plain failure would invite a retry under a new identity and duplicate the order. - * - *

Pausing the container is used rather than a proxy because it needs no rewiring of the broker's - * advertised listeners, which would otherwise change the very connection path under test. - */ -@Testcontainers -@EnabledIf("dockerAvailable") -class KafkaAmbiguityChaosIT { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - @Container - private static final KafkaContainer KAFKA = - new KafkaContainer(System.getProperty("ca.test.image.kafka")); - - static boolean dockerAvailable() { - return DockerAvailability.isAvailable(); - } - - @Test - void aLostConfirmationIsReportedAsAmbiguousRatherThanGuessed() { - try (Producer producer = new KafkaProducer<>(producerConfig())) { - try (KafkaMessagingTransport transport = - new KafkaMessagingTransport("kafka-primary", 1, producer)) { - - pauseBroker(); - PublishResult result; - try { - result = - transport - .publish( - new TransportPublishRequest( - KafkaContractHarness.profile(), envelope(), PublishOptions.defaults())) - .toCompletableFuture() - .join() - .result(); - } finally { - resumeBroker(); - } - - assertThat(result.completion()).isEqualTo(PublishCompletion.AMBIGUOUS); - assertThat(result.evidence().transmission()) - .isEqualTo(TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED); - assertThat(result.evidence().brokerAccepted()) - .as("nothing proves the broker took it") - .isFalse(); - assertThat(result.evidence().confirmationLevel()).isEqualTo(ConfirmationLevel.NONE); - assertThat(result.mayHaveBeenStored()).isTrue(); - - assertThat(result.failure().orElseThrow().category()).isEqualTo(FailureCategory.AMBIGUOUS); - assertThat(result.failure().orElseThrow().retryable()) - .as( - "an ambiguous publish is not silently retried; the caller decides, under the same id") - .isFalse(); - } - } - } - - @Test - void theBrokerRecoversAndPublishingConfirmsAgain() { - try (Producer producer = new KafkaProducer<>(producerConfig())) { - try (KafkaMessagingTransport transport = - new KafkaMessagingTransport("kafka-primary", 1, producer)) { - - PublishResult result = - transport - .publish( - new TransportPublishRequest( - KafkaContractHarness.profile(), envelope(), PublishOptions.defaults())) - .toCompletableFuture() - .join() - .result(); - - assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED); - } - } - } - - private static void pauseBroker() { - KAFKA.getDockerClient().pauseContainerCmd(KAFKA.getContainerId()).exec(); - } - - private static void resumeBroker() { - try { - KAFKA.getDockerClient().unpauseContainerCmd(KAFKA.getContainerId()).exec(); - } catch (RuntimeException exception) { - // Already running; nothing to undo. - } - } - - private static Properties producerConfig() { - Properties properties = new Properties(); - properties.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, KAFKA.getBootstrapServers()); - properties.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, ByteArraySerializer.class.getName()); - properties.put( - ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, ByteArraySerializer.class.getName()); - properties.put(ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true); - properties.put(ProducerConfig.ACKS_CONFIG, "all"); - properties.put(ProducerConfig.MAX_IN_FLIGHT_REQUESTS_PER_CONNECTION, 5); - // Short deadlines so the stall resolves inside the test rather than the suite timeout. - properties.put(ProducerConfig.DELIVERY_TIMEOUT_MS_CONFIG, 4_000); - properties.put(ProducerConfig.REQUEST_TIMEOUT_MS_CONFIG, 2_000); - properties.put(ProducerConfig.MAX_BLOCK_MS_CONFIG, 4_000); - return properties; - } - - 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.of("acct-1"), - Optional.of("acct-1"), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - new EncodedMessage( - "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), - ContentType.JSON, - Optional.empty())); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaBrokerCertificationIT.java b/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaBrokerCertificationIT.java deleted file mode 100644 index beec17d2..00000000 --- a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaBrokerCertificationIT.java +++ /dev/null @@ -1,467 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import static org.assertj.core.api.Assertions.assertThat; - -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.testkit.BrokerCertificationEvidence; -import dev.caskeleton.messaging.testkit.NetworkFaultScenario; -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 eu.rekawek.toxiproxy.Proxy; -import eu.rekawek.toxiproxy.ToxiproxyClient; -import eu.rekawek.toxiproxy.model.Toxic; -import eu.rekawek.toxiproxy.model.ToxicDirection; -import java.io.IOException; -import java.nio.charset.StandardCharsets; -import java.nio.file.Files; -import java.nio.file.Path; -import java.time.Duration; -import java.time.Instant; -import java.util.ArrayList; -import java.util.List; -import java.util.Map; -import java.util.Properties; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CopyOnWriteArrayList; -import java.util.concurrent.TimeUnit; -import org.apache.kafka.clients.admin.Admin; -import org.apache.kafka.clients.admin.AdminClientConfig; -import org.apache.kafka.clients.admin.NewTopic; -import org.apache.kafka.clients.consumer.Consumer; -import org.apache.kafka.clients.consumer.ConsumerConfig; -import org.apache.kafka.clients.consumer.KafkaConsumer; -import org.apache.kafka.clients.producer.KafkaProducer; -import org.apache.kafka.clients.producer.Producer; -import org.apache.kafka.clients.producer.ProducerConfig; -import org.apache.kafka.common.serialization.ByteArrayDeserializer; -import org.apache.kafka.common.serialization.ByteArraySerializer; -import org.junit.jupiter.api.AfterAll; -import org.junit.jupiter.api.AfterEach; -import org.junit.jupiter.api.BeforeAll; -import org.junit.jupiter.api.Tag; -import org.junit.jupiter.api.Test; -import org.testcontainers.containers.Network; -import org.testcontainers.kafka.KafkaContainer; -import org.testcontainers.toxiproxy.ToxiproxyContainer; - -/** - * The certification lane: every fault scenario this adapter claims, run against a real broker, with - * the run's own output as the evidence. - * - *

The claim used to be a list. {@code CertifiedEvidence} named three scenarios as - * live-broker-covered, the compatibility matrix derived "Stable" from that list, and the support - * matrix repeated it — none of which required a container to have started. This suite is where the - * list comes from now: each test proves one scenario and appends one {@link - * BrokerCertificationEvidence} line, and the manifest the release gate compares is what these tests - * wrote. - * - *

No {@code @EnabledIf} on Docker, deliberately, and that is the difference between this suite - * and the other integration suites in this module. A developer's {@code test} run may skip a - * container suite with a stated reason; a certification lane that skips reports success for a - * broker nobody started, which is the exact failure the evidence exists to rule out. The tag keeps - * it out of {@code test} so that skipping is never necessary. - * - *

Faults are injected with Toxiproxy in front of the broker rather than by pausing the - * container. A pause stalls every scenario the same way; the distinction the scenarios draw — a cut - * connection, a response that never arrives, a response that arrives too late — only exists at the - * socket. The broker's advertised listener points at the proxy, so the client's data path really - * does run through it instead of reconnecting straight to the container. - * - *

{@code connection-refused} is absent, and its absence is the honest answer rather than an - * oversight: a Kafka producer buffers a record before it learns whether a connection exists, so a - * refused connection surfaces as a delivery timeout that proves nothing about transmission. - * Reporting it as {@code REJECTED} would be the guess this platform refuses to make, so the - * scenario stays an uncovered gap that {@code CertifiedEvidence.knownGaps} names. - */ -@Tag("messaging-certification") -class KafkaBrokerCertificationIT { - - private static final String ADAPTER = "messaging-kafka"; - - /** - * The certified image, pinned rather than floating. - * - *

A mutable tag makes a red run unattributable and a green one unrepeatable: the evidence - * records the image it ran against, so the image has to be a fact and not "whatever {@code - * latest} resolved to that morning". - */ - private static final String IMAGE = - System.getProperty("messaging.kafka.image", System.getProperty("ca.test.image.kafka")); - - private static final String TOXIPROXY_IMAGE = - System.getProperty( - "messaging.toxiproxy.image", System.getProperty("ca.test.image.toxiproxy")); - - /** The in-network listener the proxy forwards to. */ - private static final int BROKER_PORT = 19092; - - /** - * The first port the Toxiproxy container publishes, used for the single proxy this lane needs. - */ - private static final int PROXY_PORT = 8666; - - /** - * The publish deadline every fault is measured against. - * - *

Short on purpose: each scenario resolves inside its own test rather than inside the suite - * timeout, and the injected latency below only has to exceed this rather than a production - * default. - */ - private static final Duration DELIVERY_TIMEOUT = Duration.ofSeconds(4); - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - private static final List OBSERVED = new CopyOnWriteArrayList<>(); - - private static Network network; - private static ToxiproxyContainer toxiproxy; - private static KafkaContainer kafka; - private static Proxy brokerProxy; - private static String bootstrapServers; - - // Scope-based leak analysis cannot see the owner: the containers are static fields this class - // stops in its @AfterAll. - @SuppressWarnings("resource") - @BeforeAll - static void startBrokerBehindAProxy() throws IOException { - network = Network.newNetwork(); - toxiproxy = new ToxiproxyContainer(TOXIPROXY_IMAGE).withNetwork(network); - toxiproxy.start(); - - ToxiproxyClient toxiproxyClient = - new ToxiproxyClient(toxiproxy.getHost(), toxiproxy.getControlPort()); - brokerProxy = - toxiproxyClient.createProxy( - "messaging-kafka", "0.0.0.0:" + PROXY_PORT, "kafka:" + BROKER_PORT); - bootstrapServers = toxiproxy.getHost() + ":" + toxiproxy.getMappedPort(PROXY_PORT); - - kafka = - new KafkaContainer(IMAGE) - .withNetwork(network) - .withNetworkAliases("kafka") - // The advertised listener is the proxy, so a client that follows the broker's own - // metadata still arrives through the fault injector. Advertising the container instead - // would let every connection after the bootstrap bypass the proxy, and the suite would - // certify a data path it never faulted. - .withListener("kafka:" + BROKER_PORT, () -> bootstrapServers); - kafka.start(); - } - - @AfterEach - void clearInjectedFaults() throws IOException { - for (Toxic toxic : brokerProxy.toxics().getAll()) { - toxic.remove(); - } - brokerProxy.enable(); - } - - @AfterAll - static void writeEvidence() throws IOException { - Path manifest = - Path.of( - System.getProperty( - "messaging.certification.manifest", - "build/messaging-certification/broker-certification-evidence.jsonl")); - Files.createDirectories(manifest.toAbsolutePath().getParent()); - List lines = - OBSERVED.stream() - .sorted(java.util.Comparator.comparing(evidence -> evidence.scenario().name())) - .map(BrokerCertificationEvidence::toJson) - .toList(); - Files.write(manifest, lines, StandardCharsets.UTF_8); - - if (kafka != null) { - kafka.stop(); - } - if (toxiproxy != null) { - toxiproxy.stop(); - } - if (network != null) { - network.close(); - } - } - - @Test - void aConnectionCutAfterTheWriteIsReportedAsAmbiguous() throws IOException { - String topic = createTopic("certification.cut"); - try (Producer producer = producer()) { - KafkaMessagingTransport transport = new KafkaMessagingTransport("kafka-primary", 1, producer); - // A warm-up publish so metadata and the broker connection already exist. Without it the - // failure under test would be a metadata lookup that never started, which is a different - // scenario with a different honest answer. - assertThat(publish(transport, topic, "warm-up").completion()) - .isEqualTo(PublishCompletion.CONFIRMED); - - brokerProxy.disable(); - PublishResult result = publish(transport, topic, "cut"); - - assertAmbiguous(result); - record( - NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE, - "KafkaBrokerCertificationIT#aConnectionCutAfterTheWriteIsReportedAsAmbiguous", - result); - } - } - - @Test - void aConfirmThatNeverArrivesIsReportedAsAmbiguousAndTheRecordIsThere() throws IOException { - String topic = createTopic("certification.confirm"); - try (Producer producer = producer()) { - KafkaMessagingTransport transport = new KafkaMessagingTransport("kafka-primary", 1, producer); - assertThat(publish(transport, topic, "warm-up").completion()) - .isEqualTo(PublishCompletion.CONFIRMED); - - // Only the broker's answers are stopped. The produce request still lands, so this is the - // case where the record really is stored and only the acknowledgement is missing — the exact - // state in which reporting a rejection would lose a message the broker is holding. - brokerProxy.toxics().timeout("confirm-lost", ToxicDirection.DOWNSTREAM, 0); - PublishResult result = publish(transport, topic, "confirm-lost"); - assertAmbiguous(result); - - clearInjectedFaults(); - assertThat(recordCount(topic)) - .as("the broker kept both records, so AMBIGUOUS was the true answer and REJECTED a lie") - .isEqualTo(2); - - record( - NetworkFaultScenario.CONFIRM_TIMEOUT, - "KafkaBrokerCertificationIT#aConfirmThatNeverArrivesIsReportedAsAmbiguousAndTheRecordIsThere", - result); - } - } - - @Test - void latencyBeyondThePublishDeadlineIsReportedAsAmbiguous() throws IOException { - String topic = createTopic("certification.latency"); - try (Producer producer = producer()) { - KafkaMessagingTransport transport = new KafkaMessagingTransport("kafka-primary", 1, producer); - assertThat(publish(transport, topic, "warm-up").completion()) - .isEqualTo(PublishCompletion.CONFIRMED); - - // Slow, not broken: nothing is dropped and no connection closes. At the moment the deadline - // expires the caller cannot tell this apart from a lost confirm, and the platform's answer - // must be the same for both. - brokerProxy - .toxics() - .latency("high-latency", ToxicDirection.DOWNSTREAM, DELIVERY_TIMEOUT.toMillis() * 2); - PublishResult result = publish(transport, topic, "slow"); - - assertAmbiguous(result); - record( - NetworkFaultScenario.HIGH_LATENCY, - "KafkaBrokerCertificationIT#latencyBeyondThePublishDeadlineIsReportedAsAmbiguous", - result); - } - } - - @Test - void aDeliveryLostBeforeSettlementIsRedelivered() throws IOException { - String topic = createTopic("certification.settlement"); - String group = "certification-" + System.nanoTime(); - try (Producer producer = producer()) { - KafkaMessagingTransport transport = new KafkaMessagingTransport("kafka-primary", 1, producer); - assertThat(publish(transport, topic, "settle-me").completion()) - .isEqualTo(PublishCompletion.CONFIRMED); - } - - List firstAttempt = new ArrayList<>(); - try (Consumer first = consumer(group)) { - KafkaConsumerRegistrar registrar = registrar(topic, first, firstAttempt, false); - registrar.subscribe(topic); - drain(registrar, firstAttempt); - // The broker disappears while the delivery is unsettled. That is what makes the settlement - // lost rather than merely withheld: the consumer had the record and no acknowledgement could - // reach the broker even if the handler had produced one. - brokerProxy.disable(); - registrar.pollOnce(NOW); - brokerProxy.enable(); - - assertThat(registrar.committedOffset(new org.apache.kafka.common.TopicPartition(topic, 0))) - .as("nothing was committed, so the record is still owed to this group") - .isEmpty(); - registrar.close(); - } - - assertThat(firstAttempt).as("the first consumer received the record").hasSize(1); - - List secondAttempt = new ArrayList<>(); - try (Consumer second = consumer(group)) { - KafkaConsumerRegistrar registrar = registrar(topic, second, secondAttempt, true); - registrar.subscribe(topic); - // Longer than the other drains: this consumer is joining a group whose previous member left - // under a network fault, so the first poll may sit through a rebalance rather than a fetch. - drain(registrar, secondAttempt, 80); - registrar.close(); - } - - assertThat(secondAttempt) - .as("an unsettled delivery is redelivered; the handler is idempotent, not the platform") - .hasSize(1); - record( - NetworkFaultScenario.SETTLEMENT_LOST, - "KafkaBrokerCertificationIT#aDeliveryLostBeforeSettlementIsRedelivered", - NetworkFaultScenario.Expectation.REDELIVERED); - } - - private static void assertAmbiguous(PublishResult result) { - assertThat(result.completion()).isEqualTo(PublishCompletion.AMBIGUOUS); - assertThat(result.evidence().transmission()) - .isEqualTo(TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED); - assertThat(result.evidence().brokerAccepted()) - .as("nothing proves the broker took it") - .isFalse(); - assertThat(result.evidence().confirmationLevel()).isEqualTo(ConfirmationLevel.NONE); - assertThat(result.mayHaveBeenStored()).isTrue(); - assertThat(result.failure().orElseThrow().retryable()) - .as("an ambiguous publish is not silently retried; the caller decides, under the same id") - .isFalse(); - } - - /** - * Records what the run observed, translated from the platform's own reported completion. - * - *

Translated rather than asserted equal to the scenario's expectation, because the two are - * compared later by {@code BrokerFailureMatrix.from}: evidence whose outcome contradicts the - * scenario it claims is refused there, and hard-coding the expected value here would remove the - * only place that check has anything to check. - */ - private static void record(NetworkFaultScenario scenario, String testId, PublishResult result) { - NetworkFaultScenario.Expectation observed = - switch (result.completion()) { - case AMBIGUOUS -> NetworkFaultScenario.Expectation.AMBIGUOUS; - case REJECTED -> NetworkFaultScenario.Expectation.REJECTED; - case CONFIRMED -> - throw new AssertionError( - "a confirmed publish is not evidence of a fault scenario: " + scenario.name()); - }; - record(scenario, testId, observed); - } - - private static void record( - NetworkFaultScenario scenario, String testId, NetworkFaultScenario.Expectation observed) { - OBSERVED.add( - new BrokerCertificationEvidence( - ADAPTER, - IMAGE, - scenario, - testId, - observed.name(), - System.getProperty("messaging.certification.commit", "local"), - Instant.now())); - } - - private static PublishResult publish( - KafkaMessagingTransport transport, String topic, String key) { - return transport - .publish( - new TransportPublishRequest( - KafkaFixtureProfiles.withTopic(topic), - KafkaTransactionFixtures.delivery(topic, key).outputs().get(0).envelope(), - PublishOptions.defaults())) - .toCompletableFuture() - .join() - .result(); - } - - private static String createTopic(String prefix) { - String topic = prefix + '.' + System.nanoTime(); - try (Admin admin = - Admin.create(Map.of(AdminClientConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers))) { - admin - .createTopics(List.of(new NewTopic(topic, 1, (short) 1))) - .all() - .get(30, TimeUnit.SECONDS); - } catch (InterruptedException interrupted) { - Thread.currentThread().interrupt(); - throw new IllegalStateException("interrupted creating " + topic, interrupted); - } catch (java.util.concurrent.ExecutionException | java.util.concurrent.TimeoutException e) { - throw new IllegalStateException("could not create " + topic, e); - } - return topic; - } - - private static int recordCount(String topic) { - try (Consumer consumer = consumer("count-" + System.nanoTime())) { - consumer.subscribe(List.of(topic)); - int seen = 0; - for (int attempt = 0; attempt < 10; attempt++) { - seen += consumer.poll(Duration.ofMillis(500)).count(); - } - return seen; - } - } - - private static Producer producer() { - Properties config = new Properties(); - config.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers); - config.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, ByteArraySerializer.class.getName()); - config.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, ByteArraySerializer.class.getName()); - // The Stable profile's durability. A lane that quietly weakened these would certify a - // configuration the platform refuses to run. - config.put(ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true); - config.put(ProducerConfig.ACKS_CONFIG, "all"); - config.put(ProducerConfig.DELIVERY_TIMEOUT_MS_CONFIG, (int) DELIVERY_TIMEOUT.toMillis()); - config.put(ProducerConfig.REQUEST_TIMEOUT_MS_CONFIG, 2_000); - config.put(ProducerConfig.MAX_BLOCK_MS_CONFIG, (int) DELIVERY_TIMEOUT.toMillis()); - return new KafkaProducer<>(config); - } - - private static Consumer consumer(String group) { - Properties config = new Properties(); - config.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers); - config.put(ConsumerConfig.GROUP_ID_CONFIG, group); - config.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, ByteArrayDeserializer.class.getName()); - config.put( - ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, ByteArrayDeserializer.class.getName()); - config.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest"); - config.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, false); - // Short group timeouts. The settlement scenario kills the connection under a live member, so - // its departure may reach the broker as a session expiry rather than as a clean leave; with the - // defaults the replacement consumer would then wait three quarters of a minute for the group to - // rebalance and the suite would time out before the redelivery it is certifying ever happened. - config.put(ConsumerConfig.SESSION_TIMEOUT_MS_CONFIG, 6_000); - config.put(ConsumerConfig.HEARTBEAT_INTERVAL_MS_CONFIG, 2_000); - config.put(ConsumerConfig.MAX_POLL_INTERVAL_MS_CONFIG, 20_000); - return new KafkaConsumer<>(config); - } - - private static KafkaConsumerRegistrar registrar( - String topic, - Consumer consumer, - List handled, - boolean settle) { - return new KafkaConsumerRegistrar( - new TransportConsumerSpec( - KafkaFixtureProfiles.withTopic(topic), - delivery -> { - handled.add(delivery); - if (settle) { - delivery.settlement().acknowledge().toCompletableFuture().join(); - } - return CompletableFuture.completedFuture(null); - }), - consumer, - Runnable::run, - new GracefulShutdownCoordinator(Duration.ofSeconds(30)), - Duration.ofMillis(500)); - } - - private static void drain(KafkaConsumerRegistrar registrar, List handled) { - drain(registrar, handled, 20); - } - - private static void drain( - KafkaConsumerRegistrar registrar, List handled, int attempts) { - for (int attempt = 0; attempt < attempts && handled.isEmpty(); attempt++) { - registrar.pollOnce(NOW); - } - // One more cycle so the settlements the handler queued are applied and committed. - registrar.pollOnce(NOW); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaBrokerIT.java b/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaBrokerIT.java deleted file mode 100644 index ac3cec45..00000000 --- a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaBrokerIT.java +++ /dev/null @@ -1,294 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import static org.assertj.core.api.Assertions.assertThat; - -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.TransmissionEvidence; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.testkit.DockerAvailability; -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 java.nio.charset.StandardCharsets; -import java.time.Duration; -import java.time.Instant; -import java.util.ArrayList; -import java.util.List; -import java.util.Map; -import java.util.Optional; -import java.util.Properties; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.TimeUnit; -import org.apache.kafka.clients.admin.Admin; -import org.apache.kafka.clients.admin.AdminClientConfig; -import org.apache.kafka.clients.admin.NewTopic; -import org.apache.kafka.clients.consumer.Consumer; -import org.apache.kafka.clients.consumer.ConsumerConfig; -import org.apache.kafka.clients.consumer.KafkaConsumer; -import org.apache.kafka.clients.producer.KafkaProducer; -import org.apache.kafka.clients.producer.Producer; -import org.apache.kafka.clients.producer.ProducerConfig; -import org.apache.kafka.common.TopicPartition; -import org.apache.kafka.common.serialization.ByteArrayDeserializer; -import org.apache.kafka.common.serialization.ByteArraySerializer; -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.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; -import org.testcontainers.kafka.KafkaContainer; - -/** - * Certifies the Kafka adapter against a live broker. - * - *

The deterministic suite proves the platform's semantics; this proves the client actually - * behaves that way against the broker version the compatibility matrix claims. Both are needed: a - * mock cannot tell you that {@code acks=all} produced a real replication acknowledgement, and a - * live broker cannot be made to lose a confirmation on demand. - * - *

Topics are created through {@code Admin} rather than by auto-creation, because production - * topology is created by infrastructure and only validated by the application. A test that relies - * on auto-creation is testing a configuration the platform forbids. - */ -@Testcontainers -@EnabledIf("dockerAvailable") -class KafkaBrokerIT { - - private static final String TOPIC = "order.events.v1"; - private static final String DEAD_LETTER_TOPIC = "order.events.v1.dlt"; - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - @Container - private static final KafkaContainer KAFKA = - new KafkaContainer(System.getProperty("ca.test.image.kafka")); - - private Producer producer; - private Consumer consumer; - - static boolean dockerAvailable() { - return DockerAvailability.isAvailable(); - } - - @BeforeEach - void createTopology() throws Exception { - try (Admin admin = - Admin.create( - Map.of(AdminClientConfig.BOOTSTRAP_SERVERS_CONFIG, KAFKA.getBootstrapServers()))) { - admin - .createTopics( - List.of( - new NewTopic(TOPIC, 1, (short) 1), new NewTopic(DEAD_LETTER_TOPIC, 1, (short) 1))) - .all() - .get(30, TimeUnit.SECONDS); - } catch (java.util.concurrent.ExecutionException exception) { - if (!(exception.getCause() instanceof org.apache.kafka.common.errors.TopicExistsException)) { - throw exception; - } - } - producer = new KafkaProducer<>(producerConfig()); - consumer = new KafkaConsumer<>(consumerConfig()); - } - - @AfterEach - void closeClients() { - if (producer != null) { - producer.close(Duration.ofSeconds(5)); - } - if (consumer != null) { - consumer.close(); - } - } - - @Test - void aStableProfilePublishConfirmsWithReplicationEvidence() { - try (KafkaMessagingTransport transport = - new KafkaMessagingTransport("kafka-primary", 1, producer)) { - - PublishResult result = - transport - .publish( - new TransportPublishRequest( - KafkaContractHarness.profile(), envelope(), PublishOptions.defaults())) - .toCompletableFuture() - .join() - .result(); - - assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED); - assertThat(result.evidence().transmission()).isEqualTo(TransmissionEvidence.TRANSMITTED); - assertThat(result.evidence().confirmationLevel()) - .isEqualTo(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK); - assertThat(result.position()).isPresent(); - } - } - - @Test - void anInvalidTopicIsRejectedRatherThanReportedAmbiguous() { - try (KafkaMessagingTransport transport = - new KafkaMessagingTransport("kafka-primary", 1, producer)) { - - PublishResult result = - transport - .publish( - new TransportPublishRequest( - KafkaFixtureProfiles.withTopic("not a legal topic name!"), - envelope(), - PublishOptions.defaults())) - .toCompletableFuture() - .join() - .result(); - - assertThat(result.completion()) - .as("an invalid topic is definitive: the record was never stored") - .isEqualTo(PublishCompletion.REJECTED); - assertThat(result.evidence().transmission()).isEqualTo(TransmissionEvidence.NOT_TRANSMITTED); - assertThat(result.failure().orElseThrow().retryable()).isFalse(); - } - } - - /** - * Demonstrates why the platform forbids topology auto-creation in production. - * - *

This broker has auto-creation enabled, so publishing to a topic nobody declared silently - * succeeds and creates it. Nothing about the publish result reveals the mistake: the evidence is - * a genuine replication acknowledgement for a topic that should not exist. - * - *

That is the whole argument for {@code topologyAutoCreate=false} on production profiles and - * for validate-only startup checks — the failure this test pins is invisible at publish time and - * only shows up later as a topic with the wrong partition count and no retention policy. - */ - @Test - void autoCreationMakesAnUndeclaredTopicIndistinguishableFromADeclaredOne() { - try (KafkaMessagingTransport transport = - new KafkaMessagingTransport("kafka-primary", 1, producer)) { - - PublishResult result = - transport - .publish( - new TransportPublishRequest( - KafkaFixtureProfiles.withTopic("undeclared.topic.v1"), - envelope(), - PublishOptions.defaults())) - .toCompletableFuture() - .join() - .result(); - - assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED); - assertThat(KafkaContractHarness.profile().topologyAutoCreate()) - .as("production profiles must never permit this") - .isFalse(); - } - } - - @Test - void aPublishedMessageIsConsumedWithItsIdentityIntactAndCommitted() { - try (KafkaMessagingTransport transport = - new KafkaMessagingTransport("kafka-primary", 1, producer)) { - MessageEnvelope published = envelope(); - - transport - .publish( - new TransportPublishRequest( - KafkaContractHarness.profile(), published, PublishOptions.defaults())) - .toCompletableFuture() - .join(); - - List handled = new ArrayList<>(); - KafkaConsumerRegistrar registrar = - new KafkaConsumerRegistrar( - new TransportConsumerSpec( - KafkaContractHarness.profile(), - delivery -> { - handled.add(delivery); - delivery.settlement().acknowledge().toCompletableFuture().join(); - return CompletableFuture.completedFuture(null); - }), - consumer, - Runnable::run, - new GracefulShutdownCoordinator(Duration.ofSeconds(30)), - Duration.ofMillis(500)); - registrar.subscribe(TOPIC); - - for (int attempt = 0; attempt < 20 && handled.isEmpty(); attempt++) { - registrar.pollOnce(NOW); - } - registrar.pollOnce(NOW); - - assertThat(handled) - .singleElement() - .satisfies( - delivery -> { - assertThat(delivery.envelope().messageId()).isEqualTo(published.messageId()); - assertThat(delivery.envelope().messageType()).isEqualTo(published.messageType()); - assertThat(delivery.envelope().payload().bytes()) - .isEqualTo(published.payload().bytes()); - }); - assertThat(registrar.committedOffset(new TopicPartition(TOPIC, 0))).isPresent(); - - registrar.close(); - } - } - - private Properties producerConfig() { - Properties properties = new Properties(); - properties.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, KAFKA.getBootstrapServers()); - properties.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, ByteArraySerializer.class.getName()); - properties.put( - ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, ByteArraySerializer.class.getName()); - // The Stable profile the guard enforces. - properties.put(ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true); - properties.put(ProducerConfig.ACKS_CONFIG, "all"); - properties.put(ProducerConfig.MAX_IN_FLIGHT_REQUESTS_PER_CONNECTION, 5); - properties.put(ProducerConfig.DELIVERY_TIMEOUT_MS_CONFIG, 10_000); - properties.put(ProducerConfig.REQUEST_TIMEOUT_MS_CONFIG, 5_000); - return properties; - } - - private Properties consumerConfig() { - Properties properties = new Properties(); - properties.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, KAFKA.getBootstrapServers()); - properties.put( - ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, ByteArrayDeserializer.class.getName()); - properties.put( - ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, ByteArrayDeserializer.class.getName()); - properties.put(ConsumerConfig.GROUP_ID_CONFIG, "order-projection-" + System.nanoTime()); - properties.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest"); - // Auto commit is forbidden: the platform commits after handler success. - properties.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, false); - return properties; - } - - 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.of("acct-1"), - Optional.of("acct-1"), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - new EncodedMessage( - "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), - ContentType.JSON, - Optional.empty())); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaConsumerSettlementIT.java b/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaConsumerSettlementIT.java deleted file mode 100644 index ec0b8eb8..00000000 --- a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaConsumerSettlementIT.java +++ /dev/null @@ -1,218 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.publish.PublishOptions; -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 java.time.Duration; -import java.time.Instant; -import java.util.ArrayList; -import java.util.List; -import java.util.OptionalLong; -import java.util.concurrent.CompletableFuture; -import org.apache.kafka.clients.consumer.Consumer; -import org.apache.kafka.clients.producer.Producer; -import org.apache.kafka.common.TopicPartition; -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; - -/** - * Certifies that offsets advance only for work that actually finished, on a live broker. - * - *

The deterministic suite proves the tracker's arithmetic. This proves the arithmetic reaches - * the broker: that an unacknowledged record leaves the committed offset behind it, and that a - * restarted consumer therefore reads it again. - * - *

Redelivery after an unsettled handler is the whole at-least-once guarantee. If it did not hold - * here, every downstream inbox would be protecting against a duplicate that could never happen - * while the real risk — silent loss — went unnoticed. - */ -@EnabledIf("dockerAvailable") -class KafkaConsumerSettlementIT { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - /** - * A topic per test, because the broker is shared across suites and across tests in this class. - * - *

A fresh consumer group reads from the earliest offset, so a topic carrying records another - * test published would make this suite's assertions count someone else's messages. - */ - private String topic; - - private TopicPartition partition; - private Producer producer; - private String group; - - static boolean dockerAvailable() { - return KafkaContainerFixture.dockerAvailable(); - } - - @BeforeEach - void createTopology() { - long unique = System.nanoTime(); - topic = "settlement.events." + unique; - partition = new TopicPartition(topic, 0); - KafkaContainerFixture.createTopics(1, topic); - producer = KafkaContainerFixture.producer(); - group = "settlement-it-" + unique; - } - - @AfterEach - void closeProducer() { - if (producer != null) { - producer.close(Duration.ofSeconds(5)); - } - } - - @Test - void anAcknowledgedRecordAdvancesTheCommittedOffset() { - publish(1); - - try (Consumer consumer = KafkaContainerFixture.consumer(group)) { - List handled = new ArrayList<>(); - KafkaConsumerRegistrar registrar = registrarThatAcknowledges(consumer, handled); - registrar.subscribe(topic); - drain(registrar, handled, 1); - - assertThat(registrar.committedOffset(partition)) - .as("the next offset to read, not the one just handled") - .isEqualTo(OptionalLong.of(1)); - registrar.close(); - } - } - - @Test - void anUnsettledRecordLeavesTheCommittedOffsetBehindIt() { - publish(1); - - try (Consumer consumer = KafkaContainerFixture.consumer(group)) { - List handled = new ArrayList<>(); - KafkaConsumerRegistrar registrar = registrarThatNeverSettles(consumer, handled); - registrar.subscribe(topic); - drain(registrar, handled, 1); - - assertThat(registrar.committedOffset(partition)) - .as("committing a record whose handler never finished is how a message is lost") - .isEmpty(); - registrar.close(); - } - } - - @Test - void anUnsettledRecordIsRedeliveredToAFreshConsumerInTheSameGroup() { - publish(1); - - try (Consumer first = KafkaContainerFixture.consumer(group)) { - List handled = new ArrayList<>(); - KafkaConsumerRegistrar registrar = registrarThatNeverSettles(first, handled); - registrar.subscribe(topic); - drain(registrar, handled, 1); - registrar.close(); - } - - try (Consumer second = KafkaContainerFixture.consumer(group)) { - List handled = new ArrayList<>(); - KafkaConsumerRegistrar registrar = registrarThatAcknowledges(second, handled); - registrar.subscribe(topic); - drain(registrar, handled, 1); - - assertThat(handled) - .as("redelivery after an unsettled handler is the at-least-once guarantee itself") - .hasSize(1); - registrar.close(); - } - } - - @Test - void anAcknowledgedRecordIsNotRedeliveredToAFreshConsumer() { - publish(1); - - try (Consumer first = KafkaContainerFixture.consumer(group)) { - List handled = new ArrayList<>(); - KafkaConsumerRegistrar registrar = registrarThatAcknowledges(first, handled); - registrar.subscribe(topic); - drain(registrar, handled, 1); - registrar.close(); - } - - try (Consumer second = KafkaContainerFixture.consumer(group)) { - List handled = new ArrayList<>(); - KafkaConsumerRegistrar registrar = registrarThatAcknowledges(second, handled); - registrar.subscribe(topic); - for (int attempt = 0; attempt < 6; attempt++) { - registrar.pollOnce(NOW); - } - - assertThat(handled).isEmpty(); - registrar.close(); - } - } - - private void publish(int count) { - try (KafkaMessagingTransport transport = - new KafkaMessagingTransport("kafka-primary", 1, producer)) { - for (int index = 0; index < count; index++) { - transport - .publish( - new TransportPublishRequest( - KafkaFixtureProfiles.withTopic(topic), - KafkaTransactionFixtures.delivery(topic, "settle-" + index) - .outputs() - .get(0) - .envelope(), - PublishOptions.defaults())) - .toCompletableFuture() - .join(); - } - } - } - - private KafkaConsumerRegistrar registrarThatAcknowledges( - Consumer consumer, List handled) { - return registrar( - consumer, - delivery -> { - handled.add(delivery); - delivery.settlement().acknowledge().toCompletableFuture().join(); - return CompletableFuture.completedFuture(null); - }); - } - - private KafkaConsumerRegistrar registrarThatNeverSettles( - Consumer consumer, List handled) { - return registrar( - consumer, - delivery -> { - handled.add(delivery); - // No settlement at all: the handler "died" mid-work. - return CompletableFuture.completedFuture(null); - }); - } - - private KafkaConsumerRegistrar registrar( - Consumer consumer, - java.util.function.Function> - sink) { - return new KafkaConsumerRegistrar( - new TransportConsumerSpec(KafkaFixtureProfiles.withTopic(topic), sink), - consumer, - Runnable::run, - new GracefulShutdownCoordinator(Duration.ofSeconds(30)), - KafkaContainerFixture.pollTimeout()); - } - - private static void drain( - KafkaConsumerRegistrar registrar, List handled, int expected) { - for (int attempt = 0; attempt < 20 && handled.size() < expected; attempt++) { - registrar.pollOnce(NOW); - } - // One more cycle so the settlements queued by the handlers are applied and committed. - registrar.pollOnce(NOW); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaContainerFixture.java b/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaContainerFixture.java deleted file mode 100644 index 9d6b1a4c..00000000 --- a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaContainerFixture.java +++ /dev/null @@ -1,193 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.testkit.DockerAvailability; -import java.time.Duration; -import java.util.List; -import java.util.Map; -import java.util.Properties; -import java.util.concurrent.TimeUnit; -import org.apache.kafka.clients.admin.Admin; -import org.apache.kafka.clients.admin.AdminClientConfig; -import org.apache.kafka.clients.admin.NewTopic; -import org.apache.kafka.clients.consumer.Consumer; -import org.apache.kafka.clients.consumer.ConsumerConfig; -import org.apache.kafka.clients.consumer.KafkaConsumer; -import org.apache.kafka.clients.producer.KafkaProducer; -import org.apache.kafka.clients.producer.Producer; -import org.apache.kafka.clients.producer.ProducerConfig; -import org.apache.kafka.common.serialization.ByteArrayDeserializer; -import org.apache.kafka.common.serialization.ByteArraySerializer; -import org.testcontainers.kafka.KafkaContainer; - -/** - * One Kafka broker shared by every Kafka integration suite in this module. - * - *

A singleton container rather than one per class. Kafka takes several seconds to become usable, - * and a dozen suites each starting their own would dominate the build; the container is started - * once on first use and reaped by Ryuk when the JVM exits. - * - *

Isolation comes from topic names instead. Every suite creates its own topics, so sharing a - * broker never means sharing state — which is also closer to how a real cluster is used than a - * private broker per service would be. - * - *

Producer defaults here are the Stable profile's: idempotence on, {@code acks=all}. A test that - * quietly used weaker settings would certify a configuration the platform refuses. - */ -final class KafkaContainerFixture { - - private static final String IMAGE = System.getProperty("ca.test.image.kafka"); - - private static KafkaContainer container; - - private KafkaContainerFixture() {} - - /** - * Reports whether the container suites can run at all. - * - * @return true when a Docker daemon is reachable - */ - static boolean dockerAvailable() { - return DockerAvailability.isAvailable(); - } - - /** - * Returns the shared broker, starting it on first use. - * - * @return the running container - */ - static synchronized KafkaContainer broker() { - if (container == null) { - container = new KafkaContainer(IMAGE); - container.start(); - } - return container; - } - - /** - * Returns the bootstrap servers of the shared broker. - * - * @return the bootstrap servers - */ - static String bootstrapServers() { - return broker().getBootstrapServers(); - } - - /** - * Creates topics, tolerating ones a previous suite already made. - * - * @param partitions how many partitions each topic gets - * @param topics the topic names - */ - static void createTopics(int partitions, String... topics) { - try (Admin admin = - Admin.create(Map.of(AdminClientConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers()))) { - admin - .createTopics( - List.of(topics).stream() - .map(topic -> new NewTopic(topic, partitions, (short) 1)) - .toList()) - .all() - .get(30, TimeUnit.SECONDS); - } catch (java.util.concurrent.ExecutionException exception) { - if (!(exception.getCause() instanceof org.apache.kafka.common.errors.TopicExistsException)) { - throw new IllegalStateException("could not create topics", exception); - } - } catch (InterruptedException interrupted) { - Thread.currentThread().interrupt(); - throw new IllegalStateException("interrupted creating topics", interrupted); - } catch (java.util.concurrent.TimeoutException timeout) { - throw new IllegalStateException("timed out creating topics", timeout); - } - } - - /** - * Returns an admin client against the shared broker. - * - * @return a new admin client, which the caller closes - */ - static Admin admin() { - return Admin.create(Map.of(AdminClientConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers())); - } - - /** - * Returns a producer configured as the Stable profile requires. - * - * @return a new producer, which the caller closes - */ - static Producer producer() { - return new KafkaProducer<>(producerConfig()); - } - - /** - * Returns a transactional producer. - * - * @param transactionalId the producer's transactional id - * @return a new producer, which the caller closes - */ - static Producer transactionalProducer(String transactionalId) { - Properties config = producerConfig(); - config.put(ProducerConfig.TRANSACTIONAL_ID_CONFIG, transactionalId); - return new KafkaProducer<>(config); - } - - /** - * Returns a consumer for a group, reading from the beginning. - * - * @param group the consumer group - * @return a new consumer, which the caller closes - */ - static Consumer consumer(String group) { - return new KafkaConsumer<>(consumerConfig(group, "read_uncommitted")); - } - - /** - * Returns a consumer that only sees committed records. - * - * @param group the consumer group - * @return a new consumer, which the caller closes - */ - static Consumer readCommittedConsumer(String group) { - return new KafkaConsumer<>(consumerConfig(group, "read_committed")); - } - - /** - * Returns the Stable producer configuration. - * - * @return the producer properties - */ - static Properties producerConfig() { - Properties config = new Properties(); - config.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers()); - config.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, ByteArraySerializer.class.getName()); - config.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, ByteArraySerializer.class.getName()); - config.put(ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true); - config.put(ProducerConfig.ACKS_CONFIG, "all"); - config.put(ProducerConfig.DELIVERY_TIMEOUT_MS_CONFIG, 15_000); - config.put(ProducerConfig.REQUEST_TIMEOUT_MS_CONFIG, 5_000); - return config; - } - - private static Properties consumerConfig(String group, String isolationLevel) { - Properties config = new Properties(); - config.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers()); - config.put(ConsumerConfig.GROUP_ID_CONFIG, group); - config.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, ByteArrayDeserializer.class.getName()); - config.put( - ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, ByteArrayDeserializer.class.getName()); - config.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest"); - // The platform commits contiguously from the poll thread; auto-commit would race it and - // acknowledge records whose handlers are still running. - config.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, false); - config.put(ConsumerConfig.ISOLATION_LEVEL_CONFIG, isolationLevel); - return config; - } - - /** - * Returns a poll timeout short enough to keep suites fast but long enough to avoid empty polls. - * - * @return the poll timeout - */ - static Duration pollTimeout() { - return Duration.ofMillis(500); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaContainerSmokeTest.java b/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaContainerSmokeTest.java deleted file mode 100644 index e32fce79..00000000 --- a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaContainerSmokeTest.java +++ /dev/null @@ -1,66 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import static org.assertj.core.api.Assertions.assertThat; - -import java.util.Set; -import java.util.concurrent.TimeUnit; -import org.apache.kafka.clients.admin.Admin; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.condition.EnabledIf; - -/** - * Proves the shared fixture actually produces a usable broker. - * - *

Worth its own suite because every other Kafka integration test depends on it. When the broker - * image changes or Testcontainers changes how it exposes a port, this fails with one clear reason - * instead of a dozen suites failing with timeouts that each look like a different bug. - */ -@EnabledIf("dockerAvailable") -class KafkaContainerSmokeTest { - - static boolean dockerAvailable() { - return KafkaContainerFixture.dockerAvailable(); - } - - @Test - void theSharedBrokerIsReachable() { - assertThat(KafkaContainerFixture.broker().isRunning()).isTrue(); - assertThat(KafkaContainerFixture.bootstrapServers()).isNotBlank(); - } - - @Test - void theSameBrokerIsReusedRatherThanStartedPerSuite() { - assertThat(KafkaContainerFixture.broker()) - .as("a container per suite would dominate the build") - .isSameAs(KafkaContainerFixture.broker()); - } - - @Test - void aCreatedTopicIsVisibleToTheAdminClient() throws Exception { - KafkaContainerFixture.createTopics(1, "smoke.topic.v1"); - - try (Admin admin = KafkaContainerFixture.admin()) { - Set topics = admin.listTopics().names().get(30, TimeUnit.SECONDS); - assertThat(topics).contains("smoke.topic.v1"); - } - } - - @Test - void creatingAnExistingTopicIsTolerated() { - KafkaContainerFixture.createTopics(1, "smoke.topic.v1"); - - assertThat(KafkaContainerFixture.broker().isRunning()) - .as("suites share a broker, so a topic another suite already made must not fail this one") - .isTrue(); - } - - @Test - void theProducerDefaultsMatchTheStableProfile() { - var config = KafkaContainerFixture.producerConfig(); - - assertThat(config.get("enable.idempotence")).isEqualTo(true); - assertThat(config.get("acks")) - .as("a weaker acks setting would certify a configuration the platform refuses") - .isEqualTo("all"); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaReadCommittedIT.java b/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaReadCommittedIT.java deleted file mode 100644 index 67a91bdb..00000000 --- a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaReadCommittedIT.java +++ /dev/null @@ -1,155 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import static org.assertj.core.api.Assertions.assertThat; - -import java.nio.charset.StandardCharsets; -import java.time.Duration; -import java.util.ArrayList; -import java.util.List; -import java.util.Map; -import org.apache.kafka.clients.consumer.Consumer; -import org.apache.kafka.clients.consumer.ConsumerRecords; -import org.apache.kafka.clients.consumer.OffsetAndMetadata; -import org.apache.kafka.clients.producer.Producer; -import org.apache.kafka.clients.producer.ProducerRecord; -import org.apache.kafka.common.TopicPartition; -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; - -/** - * Pins the difference between the two isolation levels, on a live broker. - * - *

This is the test that makes {@code isolation.level} a correctness setting rather than a tuning - * knob. An aborted transaction's records are physically present in the log — the abort is a marker, - * not a deletion — so a {@code read_uncommitted} consumer reads them and cannot tell them apart - * from committed ones. - * - *

A service that uses transactions for correctness and reads with the Kafka client's default is - * therefore not protected at all. The default is {@code read_uncommitted}, which is why the - * platform sets it explicitly rather than inheriting it. - */ -@EnabledIf("dockerAvailable") -class KafkaReadCommittedIT { - - private static final String INPUT_TOPIC = "isolation.input.v1"; - - /** A topic per test: a sibling test's record must not be able to satisfy this one's assertion. */ - private String topic; - - private TopicPartition partition; - private Producer producer; - - static boolean dockerAvailable() { - return KafkaContainerFixture.dockerAvailable(); - } - - @BeforeEach - void createTopology() { - long unique = System.nanoTime(); - topic = "isolation.output." + unique; - partition = new TopicPartition(topic, 0); - KafkaContainerFixture.createTopics(1, topic, INPUT_TOPIC); - producer = KafkaContainerFixture.transactionalProducer("isolation-it-" + unique); - } - - @AfterEach - void closeProducer() { - if (producer != null) { - producer.close(Duration.ofSeconds(5)); - } - } - - @Test - void anAbortedRecordIsInvisibleToAReadCommittedConsumer() { - abortATransactionCarrying("aborted-payload"); - - try (Consumer reader = - KafkaContainerFixture.readCommittedConsumer("rc-" + System.nanoTime())) { - assertThat(readAll(reader)).doesNotContain("aborted-payload"); - } - } - - @Test - void theSameAbortedRecordIsVisibleToAReadUncommittedConsumer() { - abortATransactionCarrying("uncommitted-visible"); - - try (Consumer reader = - KafkaContainerFixture.consumer("ru-" + System.nanoTime())) { - assertThat(readAll(reader)) - .as("the abort is a marker, not a deletion; the bytes are still in the log") - .contains("uncommitted-visible"); - } - } - - @Test - void aCommittedRecordIsVisibleToBothIsolationLevels() { - commitATransactionCarrying("committed-both"); - - try (Consumer committedReader = - KafkaContainerFixture.readCommittedConsumer("rc2-" + System.nanoTime()); - Consumer uncommittedReader = - KafkaContainerFixture.consumer("ru2-" + System.nanoTime())) { - assertThat(readAll(committedReader)).contains("committed-both"); - assertThat(readAll(uncommittedReader)).contains("committed-both"); - } - } - - @Test - void thePlatformSetsIsolationLevelExplicitlyRatherThanInheritingTheDefault() { - assertThat(KafkaContainerFixture.readCommittedConsumer("probe-" + System.nanoTime())) - .as("the client default is read_uncommitted, which silently defeats transactions") - .isNotNull(); - // Reading the configured value back through a consumer is not possible, so the guarantee is - // pinned by the two tests above: the same record is visible to one reader and not the other. - assertThat(true).isTrue(); - } - - /** - * Aborts a transaction whose record has definitely reached the broker. - * - *

The flush is load-bearing and was not obvious. Inside a transaction {@code send} only - * buffers, so aborting discards the record client-side and nothing ever reaches the log — an - * abort test written without the flush passes vacuously against an empty topic. - * - *

The raw producer is used rather than the platform publisher because the platform has no - * reason to expose "flush, then fail": this is a broker-semantics test, and what it needs is a - * record that is physically in the log and marked aborted. - */ - @SuppressWarnings("FutureReturnValueIgnored") - private void abortATransactionCarrying(String payload) { - producer.initTransactions(); - producer.beginTransaction(); - // The send Future is not inspected because the flush below is the barrier: it blocks until the - // record is acknowledged, and a send failure surfaces from it rather than from the Future. - producer.send(new ProducerRecord<>(topic, payload.getBytes(StandardCharsets.UTF_8))); - producer.flush(); - producer.abortTransaction(); - } - - private void commitATransactionCarrying(String payload) { - KafkaTransactionalPublisher publisher = - KafkaTransactionalPublisher.forStaticGroup(producer, "isolation-it-group"); - publisher.initialise(); - publisher.sendInTransaction( - KafkaTransactionFixtures.delivery(topic, payload), - Map.of(topic, KafkaFixtureProfiles.withTopic(topic)), - Map.of(new TopicPartition(INPUT_TOPIC, 0), new OffsetAndMetadata(1))); - } - - private List readAll(Consumer reader) { - reader.assign(List.of(partition)); - reader.seekToBeginning(List.of(partition)); - - List payloads = new ArrayList<>(); - for (int attempt = 0; attempt < 10; attempt++) { - ConsumerRecords records = reader.poll(Duration.ofMillis(500)); - records.forEach(record -> payloads.add(new String(record.value(), StandardCharsets.UTF_8))); - if (!payloads.isEmpty() && records.isEmpty()) { - break; - } - } - return payloads; - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaTopologyValidationIT.java b/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaTopologyValidationIT.java deleted file mode 100644 index c8355027..00000000 --- a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaTopologyValidationIT.java +++ /dev/null @@ -1,144 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -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.admin.DestinationTopology; -import dev.caskeleton.messaging.admin.TopologyIssue; -import dev.caskeleton.messaging.admin.TopologyManifest; -import dev.caskeleton.messaging.admin.TopologyValidationReport; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.util.List; -import java.util.Map; -import java.util.Optional; -import java.util.concurrent.TimeUnit; -import org.apache.kafka.clients.admin.Admin; -import org.apache.kafka.clients.admin.TopicDescription; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.condition.EnabledIf; - -/** - * Validates a declared topology against what a live broker actually reports. - * - *

The unit test proves the comparison logic against hand-built inputs. This proves the inputs - * themselves are right — that what the admin client returns for a real topic maps onto the - * manifest's fields the way the validator assumes. A partition count read from the wrong place - * would make every validation vacuously pass. - * - *

The absent-topic case is the one that matters operationally. A destination whose topic does - * not exist must fail startup, because the alternative is a service that starts cleanly and then - * auto-creates the topic with the broker's defaults on first publish. - */ -@EnabledIf("dockerAvailable") -class KafkaTopologyValidationIT { - - private static final String TOPIC = "topology.validated.v1"; - - static boolean dockerAvailable() { - return KafkaContainerFixture.dockerAvailable(); - } - - private static DestinationTopology describe(String topic) { - try (Admin admin = KafkaContainerFixture.admin()) { - Map described = - admin.describeTopics(List.of(topic)).allTopicNames().get(30, TimeUnit.SECONDS); - TopicDescription description = described.get(topic); - if (description == null) { - return DestinationTopology.absent(topic); - } - int replication = description.partitions().get(0).replicas().size(); - return new DestinationTopology( - topic, description.partitions().size(), replication, Map.of(), true); - } catch (java.util.concurrent.ExecutionException absent) { - return DestinationTopology.absent(topic); - } catch (InterruptedException interrupted) { - Thread.currentThread().interrupt(); - throw new IllegalStateException("interrupted describing " + topic, interrupted); - } catch (java.util.concurrent.TimeoutException timeout) { - throw new IllegalStateException("timed out describing " + topic, timeout); - } - } - - @Test - void aTopicMatchingItsManifestProducesNoIssues() { - KafkaContainerFixture.createTopics(3, TOPIC); - - List issues = - new dev.caskeleton.messaging.admin.runtime.TopologyValidator() - .compare(new TopologyManifest("orders.v1", TOPIC, 3, 1, Map.of()), describe(TOPIC)); - - assertThat(issues).isEmpty(); - } - - @Test - void theBrokerReportsThePartitionCountTheManifestIsComparedAgainst() { - KafkaContainerFixture.createTopics(3, TOPIC); - - assertThat(describe(TOPIC).partitions()) - .as("reading this from the wrong place would make every validation vacuously pass") - .isEqualTo(3); - } - - @Test - void aTopicWithFewerPartitionsThanDeclaredBlocksStartup() { - KafkaContainerFixture.createTopics(3, TOPIC); - - TopologyValidationReport report = - new TopologyValidationReport( - new dev.caskeleton.messaging.admin.runtime.TopologyValidator() - .compare( - new TopologyManifest("orders.v1", TOPIC, 12, 1, Map.of()), describe(TOPIC)), - 1); - - assertThat(report.isAcceptable()).isFalse(); - assertThatThrownBy(report::requireAcceptable) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("partitions"); - } - - @Test - void aTopicWithMorePartitionsThanDeclaredIsAdvisoryAndStillStarts() { - KafkaContainerFixture.createTopics(3, TOPIC); - - TopologyValidationReport report = - new TopologyValidationReport( - new dev.caskeleton.messaging.admin.runtime.TopologyValidator() - .compare(new TopologyManifest("orders.v1", TOPIC, 1, 1, Map.of()), describe(TOPIC)), - 1); - - assertThat(report.advisory()).hasSize(1); - assertThatCode(report::requireAcceptable) - .as("scaling a topic up is legitimate and must not refuse to start") - .doesNotThrowAnyException(); - } - - @Test - void aDestinationWhoseTopicDoesNotExistBlocksStartup() { - TopologyValidationReport report = - new TopologyValidationReport( - new dev.caskeleton.messaging.admin.runtime.TopologyValidator() - .compare( - new TopologyManifest("orders.v1", "topology.never.created.v1", 1, 1, Map.of()), - describe("topology.never.created.v1")), - 1); - - assertThat(report.blocking()) - .as("starting cleanly here means auto-creating the topic on first publish") - .isNotEmpty(); - assertThat(Optional.of(report.blocking().get(0).attribute())).hasValue("existence"); - } - - @Test - void aTopicWithTooLittleReplicationBlocksStartup() { - KafkaContainerFixture.createTopics(1, TOPIC); - - List issues = - new dev.caskeleton.messaging.admin.runtime.TopologyValidator() - .compare(new TopologyManifest("orders.v1", TOPIC, 1, 3, Map.of()), describe(TOPIC)); - - assertThat(issues) - .as("a single-replica topic cannot deliver the durability the profile promises") - .anySatisfy(issue -> assertThat(issue.attribute()).isEqualTo("replicationFactor")); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaTransactionFencingIT.java b/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaTransactionFencingIT.java deleted file mode 100644 index 8335de90..00000000 --- a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaTransactionFencingIT.java +++ /dev/null @@ -1,150 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -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 java.time.Duration; -import java.util.Map; -import org.apache.kafka.clients.consumer.OffsetAndMetadata; -import org.apache.kafka.clients.producer.Producer; -import org.apache.kafka.common.TopicPartition; -import org.apache.kafka.common.errors.ProducerFencedException; -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; - -/** - * Certifies that a stale transactional producer is fenced by a newer one. - * - *

This is what makes a transactional service safe to redeploy. When a new instance starts with - * the same {@code transactional.id}, its {@code initTransactions} bumps the producer epoch, and the - * old instance — which may still be alive, mid-transaction, and unaware it has been replaced — is - * refused by the broker rather than allowed to commit. - * - *

Without fencing, a partitioned-off old instance and a healthy new one would both be writing - * under the same identity, and the offsets each committed would overwrite the other's. Fencing - * turns that split brain into a loud failure on the instance that lost. - */ -@EnabledIf("dockerAvailable") -class KafkaTransactionFencingIT { - - private static final String INPUT_TOPIC = "fencing.input.v1"; - private static final String OUTPUT_TOPIC = "fencing.output.v1"; - private static final String TRANSACTIONAL_ID = "fencing-it-producer"; - private static final String GROUP = "fencing-it-group"; - - private Producer first; - private Producer second; - - static boolean dockerAvailable() { - return KafkaContainerFixture.dockerAvailable(); - } - - @BeforeEach - void createTopology() { - KafkaContainerFixture.createTopics(1, INPUT_TOPIC, OUTPUT_TOPIC); - } - - @AfterEach - void closeProducers() { - closeQuietly(first); - closeQuietly(second); - } - - @Test - void aNewerProducerFencesTheOlderOneSharingItsTransactionalId() { - first = KafkaContainerFixture.transactionalProducer(TRANSACTIONAL_ID); - KafkaTransactionalPublisher older = KafkaTransactionalPublisher.forStaticGroup(first, GROUP); - older.initialise(); - - // The replacement instance starting up is what bumps the epoch. - second = KafkaContainerFixture.transactionalProducer(TRANSACTIONAL_ID); - KafkaTransactionalPublisher newer = KafkaTransactionalPublisher.forStaticGroup(second, GROUP); - newer.initialise(); - - assertThatThrownBy( - () -> older.sendInTransaction(delivery("from-older"), profiles(), offsets(1))) - .as("the old instance may still be alive and unaware it was replaced") - .isInstanceOf(ProducerFencedException.class); - } - - @Test - void theFencingProducerItselfKeepsWorking() { - first = KafkaContainerFixture.transactionalProducer(TRANSACTIONAL_ID); - KafkaTransactionalPublisher.forStaticGroup(first, GROUP).initialise(); - - second = KafkaContainerFixture.transactionalProducer(TRANSACTIONAL_ID); - KafkaTransactionalPublisher newer = KafkaTransactionalPublisher.forStaticGroup(second, GROUP); - newer.initialise(); - - assertThatCode(() -> newer.sendInTransaction(delivery("from-newer"), profiles(), offsets(2))) - .doesNotThrowAnyException(); - } - - @Test - void aDistinctTransactionalIdIsNotFenced() { - first = KafkaContainerFixture.transactionalProducer(TRANSACTIONAL_ID + "-a"); - KafkaTransactionalPublisher one = KafkaTransactionalPublisher.forStaticGroup(first, GROUP); - one.initialise(); - - second = KafkaContainerFixture.transactionalProducer(TRANSACTIONAL_ID + "-b"); - KafkaTransactionalPublisher two = KafkaTransactionalPublisher.forStaticGroup(second, GROUP); - two.initialise(); - - assertThatCode(() -> one.sendInTransaction(delivery("independent"), profiles(), offsets(3))) - .as("fencing is scoped to the transactional id, not to the broker") - .doesNotThrowAnyException(); - } - - @Test - void aFencedProducerCannotBeRecoveredByRetrying() { - first = KafkaContainerFixture.transactionalProducer(TRANSACTIONAL_ID); - KafkaTransactionalPublisher older = KafkaTransactionalPublisher.forStaticGroup(first, GROUP); - older.initialise(); - - second = KafkaContainerFixture.transactionalProducer(TRANSACTIONAL_ID); - KafkaTransactionalPublisher.forStaticGroup(second, GROUP).initialise(); - - assertThatThrownBy(() -> older.sendInTransaction(delivery("attempt-1"), profiles(), offsets(4))) - .isInstanceOf(ProducerFencedException.class); - assertThat( - catchFencing( - () -> older.sendInTransaction(delivery("attempt-2"), profiles(), offsets(5)))) - .as("fencing is terminal: the instance must exit rather than retry") - .isTrue(); - } - - private static boolean catchFencing(Runnable action) { - try { - action.run(); - return false; - } catch (RuntimeException expected) { - return true; - } - } - - private static KafkaTransactionalDelivery delivery(String marker) { - return KafkaTransactionFixtures.delivery(OUTPUT_TOPIC, marker); - } - - private static Map profiles() { - return Map.of(OUTPUT_TOPIC, KafkaFixtureProfiles.withTopic(OUTPUT_TOPIC)); - } - - private static Map offsets(long offset) { - return Map.of(new TopicPartition(INPUT_TOPIC, 0), new OffsetAndMetadata(offset)); - } - - private static void closeQuietly(Producer producer) { - if (producer == null) { - return; - } - try { - producer.close(Duration.ofSeconds(5)); - } catch (RuntimeException ignored) { - // A fenced producer throws on close; the test has already made its point by then. - } - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaTransactionFixtures.java b/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaTransactionFixtures.java deleted file mode 100644 index 7b1481ef..00000000 --- a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaTransactionFixtures.java +++ /dev/null @@ -1,78 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -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.DestinationName; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.schema.EncodedMessage; -import java.nio.charset.StandardCharsets; -import java.time.Instant; -import java.util.List; -import java.util.Optional; - -/** Builds transactional deliveries whose payloads are identifiable in a consumed record. */ -final class KafkaTransactionFixtures { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - private KafkaTransactionFixtures() {} - - /** - * Returns a delivery producing one output whose payload is the given marker. - * - * @param outputTopic the output destination name - * @param marker the payload text, used to recognise the record when reading back - * @return the delivery - */ - static KafkaTransactionalDelivery delivery(String outputTopic, String marker) { - return new KafkaTransactionalDelivery( - envelope("input"), - List.of(new KafkaTransactionalOutput(new DestinationName(outputTopic), envelope(marker)))); - } - - /** - * Returns a delivery whose second output names a destination nobody registered. - * - *

The first output is sent before the failure is discovered, which is what makes this a real - * abort test rather than a validation test: something is already on the wire when the transaction - * is rolled back. - * - * @param outputTopic the registered output destination - * @param marker the payload text for the first output - * @return the delivery - */ - static KafkaTransactionalDelivery deliveryWithUnregisteredSecondOutput( - String outputTopic, String marker) { - return new KafkaTransactionalDelivery( - envelope("input"), - List.of( - new KafkaTransactionalOutput(new DestinationName(outputTopic), envelope(marker)), - new KafkaTransactionalOutput( - new DestinationName("nobody.registered.this.v1"), envelope("unreachable")))); - } - - private static MessageEnvelope envelope(String payload) { - 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.getBytes(StandardCharsets.UTF_8), ContentType.JSON, Optional.empty())); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaTransactionIT.java b/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaTransactionIT.java deleted file mode 100644 index 0bb7924f..00000000 --- a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaTransactionIT.java +++ /dev/null @@ -1,168 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.policy.DestinationProfile; -import java.time.Duration; -import java.util.List; -import java.util.Map; -import org.apache.kafka.clients.consumer.Consumer; -import org.apache.kafka.clients.consumer.ConsumerRecords; -import org.apache.kafka.clients.consumer.OffsetAndMetadata; -import org.apache.kafka.clients.producer.Producer; -import org.apache.kafka.common.TopicPartition; -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; - -/** - * Certifies Kafka's read-process-write transaction against a live broker. - * - *

A transaction here binds two things that are otherwise independent: the records this process - * produces, and the offset of the record it consumed. Committing them separately is the classic - * duplicate: the outputs land, the process dies before committing the offset, and the input is - * reprocessed — producing the outputs a second time. - * - *

Every assertion reads through a {@code read_committed} consumer, because that is the only view - * in which an aborted transaction is actually invisible. A {@code read_uncommitted} reader sees - * aborted records too, which is exactly the distinction {@link KafkaReadCommittedIT} pins. - */ -@EnabledIf("dockerAvailable") -class KafkaTransactionIT { - - private static final String INPUT_TOPIC = "tx.input.v1"; - private static final String OUTPUT_TOPIC = "tx.output.v1"; - private static final String TRANSACTIONAL_ID = "tx-it-producer"; - private static final String CONSUMER_GROUP = "tx-it-group"; - - private Producer producer; - private Consumer reader; - - static boolean dockerAvailable() { - return KafkaContainerFixture.dockerAvailable(); - } - - @BeforeEach - void createTopology() { - KafkaContainerFixture.createTopics(1, INPUT_TOPIC, OUTPUT_TOPIC); - producer = KafkaContainerFixture.transactionalProducer(TRANSACTIONAL_ID); - reader = KafkaContainerFixture.readCommittedConsumer("tx-it-reader-" + System.nanoTime()); - } - - @AfterEach - void closeClients() { - if (producer != null) { - producer.close(Duration.ofSeconds(5)); - } - if (reader != null) { - reader.close(); - } - } - - @Test - void aCommittedTransactionMakesItsOutputVisible() { - KafkaTransactionalPublisher publisher = - KafkaTransactionalPublisher.forStaticGroup(producer, CONSUMER_GROUP); - publisher.initialise(); - - publisher.sendInTransaction( - KafkaTransactionFixtures.delivery(OUTPUT_TOPIC, "committed-1"), - profiles(), - Map.of(new TopicPartition(INPUT_TOPIC, 0), new OffsetAndMetadata(1))); - - assertThat(readOutputPayloads()).contains("committed-1"); - } - - @Test - void anAbortedTransactionLeavesNothingVisible() { - KafkaTransactionalPublisher publisher = - KafkaTransactionalPublisher.forStaticGroup(producer, CONSUMER_GROUP); - publisher.initialise(); - - // An unregistered destination fails inside the transaction, which aborts it. The output that - // was already sent before the failure must not survive. - assertThatThrownBy( - () -> - publisher.sendInTransaction( - KafkaTransactionFixtures.deliveryWithUnregisteredSecondOutput( - OUTPUT_TOPIC, "aborted-1"), - profiles(), - Map.of(new TopicPartition(INPUT_TOPIC, 0), new OffsetAndMetadata(1)))) - .isInstanceOf(RuntimeException.class); - - assertThat(readOutputPayloads()) - .as("the record was sent before the failure; the abort is what makes it invisible") - .doesNotContain("aborted-1"); - } - - @Test - void theProducerRecoversAfterAnAbortAndCanCommitAgain() { - KafkaTransactionalPublisher publisher = - KafkaTransactionalPublisher.forStaticGroup(producer, CONSUMER_GROUP); - publisher.initialise(); - - assertThatThrownBy( - () -> - publisher.sendInTransaction( - KafkaTransactionFixtures.deliveryWithUnregisteredSecondOutput( - OUTPUT_TOPIC, "aborted-2"), - profiles(), - Map.of(new TopicPartition(INPUT_TOPIC, 0), new OffsetAndMetadata(1)))) - .isInstanceOf(RuntimeException.class); - - publisher.sendInTransaction( - KafkaTransactionFixtures.delivery(OUTPUT_TOPIC, "recovered-1"), - profiles(), - Map.of(new TopicPartition(INPUT_TOPIC, 0), new OffsetAndMetadata(2))); - - assertThat(readOutputPayloads()) - .as("aborting rather than leaving the transaction open is what makes recovery possible") - .contains("recovered-1") - .doesNotContain("aborted-2"); - } - - @Test - void theInputOffsetIsCommittedWithTheOutputsNotSeparately() { - KafkaTransactionalPublisher publisher = - KafkaTransactionalPublisher.forStaticGroup(producer, CONSUMER_GROUP); - publisher.initialise(); - - publisher.sendInTransaction( - KafkaTransactionFixtures.delivery(OUTPUT_TOPIC, "offset-bound-1"), - profiles(), - Map.of(new TopicPartition(INPUT_TOPIC, 0), new OffsetAndMetadata(7))); - - try (Consumer groupReader = KafkaContainerFixture.consumer(CONSUMER_GROUP)) { - Map committed = - groupReader.committed(java.util.Set.of(new TopicPartition(INPUT_TOPIC, 0))); - - assertThat(committed.get(new TopicPartition(INPUT_TOPIC, 0))) - .as("the offset landing with the outputs is what removes the duplicate window") - .isNotNull() - .satisfies(offset -> assertThat(offset.offset()).isEqualTo(7)); - } - } - - private static Map profiles() { - return Map.of(OUTPUT_TOPIC, KafkaFixtureProfiles.withTopic(OUTPUT_TOPIC)); - } - - private List readOutputPayloads() { - reader.assign(List.of(new TopicPartition(OUTPUT_TOPIC, 0))); - reader.seekToBeginning(List.of(new TopicPartition(OUTPUT_TOPIC, 0))); - - List payloads = new java.util.ArrayList<>(); - for (int attempt = 0; attempt < 10; attempt++) { - ConsumerRecords records = reader.poll(Duration.ofMillis(500)); - records.forEach( - record -> - payloads.add(new String(record.value(), java.nio.charset.StandardCharsets.UTF_8))); - if (!payloads.isEmpty() && records.isEmpty()) { - break; - } - } - return payloads; - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/jmh/java/dev/caskeleton/messaging/kafka/KafkaPublishBenchmark.java b/src/platforms/messaging/messaging-kafka/src/jmh/java/dev/caskeleton/messaging/kafka/KafkaPublishBenchmark.java deleted file mode 100644 index be43caf4..00000000 --- a/src/platforms/messaging/messaging-kafka/src/jmh/java/dev/caskeleton/messaging/kafka/KafkaPublishBenchmark.java +++ /dev/null @@ -1,155 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -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.schema.EncodedMessage; -import java.nio.charset.StandardCharsets; -import java.time.Duration; -import java.time.Instant; -import java.util.Optional; -import java.util.concurrent.TimeUnit; -import org.apache.kafka.common.TopicPartition; -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 Kafka adapter's own cost per publish, with no broker in the loop. - * - *

Deliberately no producer and no network. A benchmark that talked to a broker would report the - * broker's latency and the agent's network, both of which vary far more than the code being - * measured — and the resulting number could not be compared across runs, which is the only thing a - * benchmark is for. - * - *

What is measured is what the adapter does on the calling thread: header mapping, payload - * framing, and the offset bookkeeping that runs per settlement. Those are the costs that scale with - * message rate and that a change to this module can regress. - */ -@BenchmarkMode(Mode.AverageTime) -@OutputTimeUnit(TimeUnit.NANOSECONDS) -@Warmup(iterations = 3, time = 1) -@Measurement(iterations = 5, time = 1) -@Fork(1) -@State(Scope.Benchmark) -public class KafkaPublishBenchmark { - - /** 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 TopicPartition PARTITION = new TopicPartition("orders.v1", 0); - - private KafkaHeaderMapper headerMapper; - private KafkaPublishFailureClassifier classifier; - private MessageEnvelope envelope; - private ContiguousPartitionOffsetTracker tracker; - - /** Builds the fixtures once so the measured methods allocate only what a publish allocates. */ - @Setup(Level.Trial) - public void setUp() { - headerMapper = new KafkaHeaderMapper(); - classifier = new KafkaPublishFailureClassifier(); - byte[] payload = new byte[payloadBytes]; - java.util.Arrays.fill(payload, (byte) 'x'); - envelope = - 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())); - } - - /** Resets the offset tracker per iteration so its cost does not drift with accumulated state. */ - @Setup(Level.Iteration) - public void resetTracker() { - tracker = new ContiguousPartitionOffsetTracker(); - } - - /** - * Measures mapping an envelope's reserved headers onto Kafka headers. - * - * @param blackhole consumes the result - */ - @Benchmark - public void mapHeaders(Blackhole blackhole) { - blackhole.consume(headerMapper.toKafkaHeaders(envelope)); - } - - /** - * Measures classifying a producer timeout, which runs on every ambiguous publish. - * - * @param blackhole consumes the result - */ - @Benchmark - public void classifyTimeout(Blackhole blackhole) { - blackhole.consume( - classifier.classify( - new org.apache.kafka.common.errors.TimeoutException("expired"), Duration.ofMillis(5))); - } - - /** - * Measures the contiguous-offset bookkeeping that runs on every settlement. - * - *

Out of order on purpose: the in-order path is a single comparison, while the out-of-order - * path is the one that has to hold pending offsets and is where a regression would show. - * - * @param blackhole consumes the result - */ - @Benchmark - public void trackOutOfOrderSettlements(Blackhole blackhole) { - tracker.delivered(PARTITION, 0); - tracker.delivered(PARTITION, 1); - tracker.delivered(PARTITION, 2); - tracker.completed(PARTITION, 2); - tracker.completed(PARTITION, 0); - blackhole.consume(tracker.commitOffset(PARTITION)); - } - - /** - * Measures reading the payload bytes, which every publish copies once. - * - * @param blackhole consumes the result - */ - @Benchmark - public void readPayload(Blackhole blackhole) { - blackhole.consume(envelope.payload().bytes()); - } - - /** - * Returns the fixture payload as text, so the setup cannot be optimised away entirely. - * - * @return the payload length - */ - @Benchmark - public int payloadLength() { - return new String(envelope.payload().bytes(), StandardCharsets.UTF_8).length(); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/ContiguousPartitionOffsetTracker.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/ContiguousPartitionOffsetTracker.java deleted file mode 100644 index 82e7ee19..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/ContiguousPartitionOffsetTracker.java +++ /dev/null @@ -1,119 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import java.util.Iterator; -import java.util.Map; -import java.util.NavigableSet; -import java.util.Optional; -import java.util.OptionalLong; -import java.util.concurrent.ConcurrentHashMap; -import java.util.concurrent.ConcurrentSkipListSet; -import org.apache.kafka.common.TopicPartition; - -/** - * Commits only through the highest contiguous completed offset. - * - *

A Kafka offset commit is a watermark, not a set: committing offset 13 declares that everything - * below it is done. With concurrent handlers, offsets finish out of order — 10 and 12 may complete - * while 11 is still running — and committing 13 at that moment would silently discard 11 if the - * consumer then died. So the tracker advances only while each successive delivered offset is - * complete, and stops at the first gap. - * - *

The cost is that one slow message holds back the watermark for its partition. That is the - * correct trade: the alternative loses messages, and the delay is visible as consumer lag rather - * than as missing data. - */ -public final class ContiguousPartitionOffsetTracker implements PartitionOffsetTracker { - - private final Map> delivered = new ConcurrentHashMap<>(); - private final Map> completed = new ConcurrentHashMap<>(); - - @Override - public void delivered(TopicPartition partition, long offset) { - delivered.computeIfAbsent(partition, key -> new ConcurrentSkipListSet<>()).add(offset); - } - - /** - * Undoes a delivery registration for a record that was never submitted. - * - *

Needed because the executor can refuse the work after the offset has been registered. A - * delivered offset with no worker behind it holds the contiguous watermark back forever: nothing - * will ever complete it, so the partition stops committing while continuing to consume. - */ - public void forgetDelivered(TopicPartition partition, long offset) { - NavigableSet inFlight = delivered.get(partition); - if (inFlight != null) { - inFlight.remove(offset); - } - } - - @Override - public void completed(TopicPartition partition, long offset) { - completed.computeIfAbsent(partition, key -> new ConcurrentSkipListSet<>()).add(offset); - } - - @Override - public Optional highestContiguousCompleted(TopicPartition partition) { - NavigableSet inFlight = delivered.get(partition); - NavigableSet done = completed.get(partition); - if (inFlight == null || done == null) { - return Optional.empty(); - } - Long highest = null; - for (Iterator iterator = inFlight.iterator(); iterator.hasNext(); ) { - Long offset = iterator.next(); - if (!done.contains(offset)) { - break; - } - highest = offset; - } - return Optional.ofNullable(highest); - } - - @Override - public OptionalLong commitOffset(TopicPartition partition) { - return highestContiguousCompleted(partition) - .map(offset -> OptionalLong.of(offset + 1)) - .orElseGet(OptionalLong::empty); - } - - /** - * Discards the fully-committed prefix so the tracker does not grow without bound. - * - * @param partition the partition - * @param committedThrough the highest offset now committed - */ - public void pruneThrough(TopicPartition partition, long committedThrough) { - NavigableSet inFlight = delivered.get(partition); - NavigableSet done = completed.get(partition); - if (inFlight != null) { - inFlight.headSet(committedThrough, true).clear(); - } - if (done != null) { - done.headSet(committedThrough, true).clear(); - } - } - - @Override - public void forget(TopicPartition partition) { - delivered.remove(partition); - completed.remove(partition); - } - - /** - * Returns how many offsets are still in flight for a partition. - * - * @param partition the partition - * @return the in-flight count - */ - public int inFlight(TopicPartition partition) { - NavigableSet inFlight = delivered.get(partition); - NavigableSet done = completed.get(partition); - if (inFlight == null) { - return 0; - } - if (done == null) { - return inFlight.size(); - } - return (int) inFlight.stream().filter(offset -> !done.contains(offset)).count(); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaBrokerProfile.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaBrokerProfile.java deleted file mode 100644 index d6976855..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaBrokerProfile.java +++ /dev/null @@ -1,56 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import java.time.Duration; -import java.util.List; -import java.util.Objects; - -/** - * The Kafka client settings the platform is willing to run with. - * - *

Held as a validated record rather than a raw property map so that the Stable guarantees are - * checkable at startup. A Kafka producer configured with {@code acks=1} still works, still - * confirms, and still loses messages on a leader failover — the only place to catch that is before - * the client is built. - * - * @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 bootstrapServers the broker addresses - * @param enableIdempotence whether the producer suppresses duplicates on internal retry - * @param acks the required acknowledgement level - * @param maxInFlightRequestsPerConnection the in-flight request ceiling - * @param deliveryTimeout the producer delivery deadline - * @param enableAutoCommit whether the consumer commits offsets on a timer - * @param consumerGroup the consumer group - * @param tlsEnabled whether transport encryption is on - * @param authenticationEnabled whether broker authentication is on - */ -public record KafkaBrokerProfile( - String broker, - boolean stable, - boolean production, - List bootstrapServers, - boolean enableIdempotence, - String acks, - int maxInFlightRequestsPerConnection, - Duration deliveryTimeout, - boolean enableAutoCommit, - String consumerGroup, - boolean tlsEnabled, - boolean authenticationEnabled) { - - public KafkaBrokerProfile { - Objects.requireNonNull(bootstrapServers, "bootstrapServers must not be null"); - Objects.requireNonNull(deliveryTimeout, "deliveryTimeout must not be null"); - if (broker == null || broker.isBlank()) { - throw new IllegalArgumentException("broker must not be blank"); - } - if (acks == null || acks.isBlank()) { - throw new IllegalArgumentException("acks must not be blank"); - } - if (bootstrapServers.isEmpty()) { - throw new IllegalArgumentException("bootstrapServers must not be empty"); - } - bootstrapServers = List.copyOf(bootstrapServers); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java deleted file mode 100644 index 4e96018c..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java +++ /dev/null @@ -1,819 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.policy.DestinationProfile; -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 java.time.Duration; -import java.time.Instant; -import java.util.ArrayList; -import java.util.Collection; -import java.util.LinkedHashMap; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.OptionalLong; -import java.util.Set; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import java.util.concurrent.ConcurrentHashMap; -import java.util.concurrent.Executor; -import java.util.concurrent.atomic.AtomicBoolean; -import org.apache.kafka.clients.consumer.Consumer; -import org.apache.kafka.clients.consumer.ConsumerRebalanceListener; -import org.apache.kafka.clients.consumer.ConsumerRecord; -import org.apache.kafka.clients.consumer.ConsumerRecords; -import org.apache.kafka.clients.consumer.OffsetAndMetadata; -import org.apache.kafka.common.TopicPartition; - -/** - * The Kafka consumer runtime: one poll thread, many handler workers. - * - *

Every call into {@code Consumer} — poll, pause, resume, seek, commit — happens on the poll - * thread and nowhere else. {@code KafkaConsumer} is documented as not thread-safe, and a worker - * that committed directly would corrupt the client's internal state under concurrency in ways that - * surface much later as skipped offsets. Workers therefore enqueue a {@link KafkaSettlementCommand} - * and the poll thread applies it at the top of the next cycle. - * - *

Offsets advance only through the contiguous watermark. With concurrent handlers, offset 12 can - * finish while 11 is still running; committing 12 at that moment would discard 11 if the consumer - * then died. The tracker stops at the first gap, which trades a little consumer lag for not losing - * messages. - * - *

Backpressure is applied by pausing the partition rather than buffering. A partition at its - * in-flight ceiling stops being fetched, so unprocessed records stay in the broker instead of in - * the heap. - * - *

{@link #pollOnce(Instant)} is one full cycle and is public so the whole loop — commit - * ordering, pause, seek, rebalance — is testable against {@code MockConsumer} without threads or - * sleeps. - */ -public final class KafkaConsumerRegistrar implements TransportConsumerRegistration { - - private final TransportConsumerSpec spec; - private final Consumer consumer; - private final Executor handlerPool; - private final KafkaDeliveryMapper deliveryMapper; - private final KafkaRetryMetadataMapper retryMetadataMapper; - private final ContiguousPartitionOffsetTracker offsets; - private final PartitionWorkCoordinator coordinator; - private final KafkaSettlementQueue settlements; - private final KafkaPartitionRetryScheduler retries; - private final GracefulShutdownCoordinator shutdown; - private final Duration pollTimeout; - - private final KafkaQuarantinePublisher quarantine; - - private final java.time.InstantSource clock; - - /** The shortest wait before a failed delivery is read again, whatever the policy computes. */ - private static final Duration MIN_RETRY_DELAY = Duration.ofSeconds(1); - - private static final dev.caskeleton.messaging.policy.BackoffCalculator BACKOFF = - new dev.caskeleton.messaging.policy.BackoffCalculator(); - - /** A delivery that failed, by where it sits in the log. */ - private record FailedOffset(TopicPartition partition, long offset) {} - - /** - * How many times each offset has failed without being settled. - * - *

Pause-and-seek re-reads the same record, so the envelope's own attempt header never moves; - * the count has to live here. Without it a poison message was retried with no delay and no limit, - * and its partition never advanced again. - */ - private final Map failures = new ConcurrentHashMap<>(); - - /** - * Partitions paused because a record could not be dispatched — the ceiling was reached, the - * runtime was draining, or the pool refused. Poll thread only. - * - *

They were paused and never resumed: an ordered partition handed two records by one poll ran - * the first and then stopped reading for good. - */ - private final Set saturated = new java.util.HashSet<>(); - - private final Map committed = new ConcurrentHashMap<>(); - - /** - * The assignment generation of each owned partition. - * - *

A settlement carries the epoch it was created under. Without one, a handler that finished - * after its partition was revoked and reassigned applied its outcome to the new assignment: the - * old epoch's acknowledgement advanced a watermark over offsets the new owner had not processed. - */ - private final Map epochs = new ConcurrentHashMap<>(); - - private final java.util.concurrent.atomic.AtomicLong epochSequence = - new java.util.concurrent.atomic.AtomicLong(); - - private final java.util.concurrent.atomic.AtomicInteger staleSettlements = - new java.util.concurrent.atomic.AtomicInteger(); - - /** - * Work that must run on the poll thread, queued by any other thread. - * - *

{@code pause}, {@code resume} and {@code close} are public API and were called on the - * caller's thread, touching the {@code Consumer} directly — the one object this class documents - * as poll-thread-only. The Kafka consumer is not thread-safe, and a concurrent call is a {@code - * ConcurrentModificationException} at best and a corrupted subscription at worst. - */ - private final java.util.Queue control = - new java.util.concurrent.ConcurrentLinkedQueue<>(); - - private final AtomicBoolean active = new AtomicBoolean(true); - - /** - * Creates a consumer runtime. - * - * @param spec what to consume and where to deliver it - * @param consumer the Kafka consumer, owned by this runtime - * @param handlerPool where handler work runs - * @param shutdown the drain coordinator - * @param pollTimeout how long each poll blocks - */ - public KafkaConsumerRegistrar( - TransportConsumerSpec spec, - Consumer consumer, - Executor handlerPool, - GracefulShutdownCoordinator shutdown, - Duration pollTimeout) { - this( - spec, consumer, handlerPool, shutdown, pollTimeout, KafkaQuarantinePublisher.unavailable()); - } - - /** - * A consumer runtime with a quarantine destination for undecodable records. - * - * @param quarantine where a record that cannot be decoded is written before its offset commits - */ - public KafkaConsumerRegistrar( - TransportConsumerSpec spec, - Consumer consumer, - Executor handlerPool, - GracefulShutdownCoordinator shutdown, - Duration pollTimeout, - KafkaQuarantinePublisher quarantine) { - this( - spec, - consumer, - handlerPool, - shutdown, - pollTimeout, - quarantine, - java.time.InstantSource.system()); - } - - /** A consumer runtime with the clock retry delays are measured on, for tests. */ - KafkaConsumerRegistrar( - TransportConsumerSpec spec, - Consumer consumer, - Executor handlerPool, - GracefulShutdownCoordinator shutdown, - Duration pollTimeout, - KafkaQuarantinePublisher quarantine, - java.time.InstantSource clock) { - this.clock = Objects.requireNonNull(clock, "clock must not be null"); - this.quarantine = Objects.requireNonNull(quarantine, "quarantine must not be null"); - this.spec = Objects.requireNonNull(spec, "spec must not be null"); - if (spec.profile().production() && quarantine == KafkaQuarantinePublisher.unavailable()) { - // Without somewhere to park a message that keeps failing, its partition retries it forever - // and nothing behind it is ever read. - throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException( - "KAFKA_QUARANTINE_REQUIRED", - "production destination " - + spec.profile().name().value() - + " needs a KafkaQuarantinePublisher; without one a message that exhausts its" - + " attempts stops its partition for good"); - } - this.consumer = Objects.requireNonNull(consumer, "consumer must not be null"); - this.handlerPool = Objects.requireNonNull(handlerPool, "handlerPool must not be null"); - this.shutdown = Objects.requireNonNull(shutdown, "shutdown must not be null"); - this.pollTimeout = Objects.requireNonNull(pollTimeout, "pollTimeout must not be null"); - this.deliveryMapper = new KafkaDeliveryMapper(); - this.retryMetadataMapper = new KafkaRetryMetadataMapper(); - this.offsets = new ContiguousPartitionOffsetTracker(); - this.coordinator = - new PartitionWorkCoordinator(spec.profile().consumer().maxInFlightPerOrderingUnit()); - this.settlements = new KafkaSettlementQueue(); - this.retries = new KafkaPartitionRetryScheduler(); - } - - /** - * Subscribes to the destination's topic and installs the rebalance listener. - * - *

On revocation the runtime commits what is safely committable and forgets the partition's - * state. Keeping stale in-flight state across a rebalance would let the watermark for a partition - * this consumer no longer owns be committed by the next poll. - * - * @param topic the physical topic - */ - public void subscribe(String topic) { - Objects.requireNonNull(topic, "topic must not be null"); - consumer.subscribe( - List.of(topic), - new ConsumerRebalanceListener() { - @Override - public void onPartitionsRevoked(Collection partitions) { - // Drop the epoch first. Any settlement still in flight for these partitions now - // carries a number no live assignment has, so applySettlements refuses it instead of - // moving a watermark this consumer no longer owns. - partitions.forEach(epochs::remove); - commitContiguous(); - partitions.forEach( - partition -> { - offsets.forget(partition); - coordinator.forget(partition); - retries.forget(partition); - committed.remove(partition); - saturated.remove(partition); - failures.keySet().removeIf(failed -> failed.partition().equals(partition)); - }); - } - - @Override - public void onPartitionsAssigned(Collection partitions) { - // A fresh epoch per assignment. The broker's committed offset is still the source of - // truth for where to read; the epoch decides whose settlements may be applied. - partitions.forEach(partition -> epochs.put(partition, epochSequence.incrementAndGet())); - } - }); - } - - /** - * Runs one complete poll cycle. - * - *

The order matters. Settlement commands are applied before committing so a handler that just - * finished is reflected in this cycle's watermark; resumes are applied before polling so a - * partition whose retry delay elapsed is fetched immediately; and dispatch happens last so a - * record is only handed to a worker after the partition's ceiling has been checked. - * - * @param now the current instant - * @return how many records were dispatched to handlers - */ - public int pollOnce(Instant now) { - Objects.requireNonNull(now, "now must not be null"); - - drainControl(); - syncEpochs(); - applySettlements(); - applyDueResumes(now); - resumeSaturated(); - commitContiguous(); - - if (!shutdown.isAcceptingWork()) { - return 0; - } - - ConsumerRecords records = consumer.poll(pollTimeout); - int dispatched = 0; - // Per partition, and never a global break. - // - // The loop used to iterate the whole batch and `break` on the first record it could not - // submit — which abandoned every record the same poll had returned for *other* partitions. - // The consumer's position had already advanced past them, so those offsets were not read - // again until a rebalance or a restart: a processing gap that nothing reported. - for (TopicPartition partition : records.partitions()) { - Long epoch = epochs.get(partition); - if (epoch == null) { - // Not ours: revoked between the poll and now. - continue; - } - java.util.List> partitionRecords = records.records(partition); - long seekBackTo = -1L; - for (ConsumerRecord record : partitionRecords) { - if (seekBackTo >= 0) { - // Already stopped for this partition; the seek below covers this record too. - continue; - } - if (!coordinator.tryAcquire(partition)) { - seekBackTo = record.offset(); - continue; - } - if (!shutdown.tryBeginWork()) { - coordinator.release(partition); - seekBackTo = record.offset(); - continue; - } - offsets.delivered(partition, record.offset()); - if (!dispatch(record, partition, now, epoch)) { - // The pool refused the work. Undo everything this iteration took so the in-flight count - // and the delivered set do not drift, and re-read the record next cycle. - offsets.forgetDelivered(partition, record.offset()); - coordinator.release(partition); - shutdown.endWork(); - seekBackTo = record.offset(); - continue; - } - dispatched++; - } - if (seekBackTo >= 0) { - // Only this partition pauses. Its earliest unsubmitted offset is where it resumes. - consumer.pause(Set.of(partition)); - consumer.seek(partition, seekBackTo); - saturated.add(partition); - } - } - return dispatched; - } - - /** - * Hands one record to the pool. - * - * @return false when the pool refused the work, so the caller can undo what it took - */ - private boolean dispatch( - ConsumerRecord record, TopicPartition partition, Instant now, long epoch) { - DestinationProfile profile = spec.profile(); - DestinationName destination = profile.name(); - Duration handlerTimeout = profile.consumer().handlerTimeout(); - - try { - handlerPool.execute( - () -> { - QueuedSettlement settlement = - new QueuedSettlement(partition, record, record.offset(), epoch); - dev.caskeleton.messaging.api.MessageEnvelope< - dev.caskeleton.messaging.schema.EncodedMessage> - envelope; - try { - envelope = deliveryMapper.toEnvelope(record); - } catch (RuntimeException undecodable) { - // A decode failure is not a handler failure and must not be retried forever. The - // offset may only advance once the record exists somewhere else, so an unavailable - // quarantine leaves it uncommitted rather than dropping the message. - // It will never decode, however often it is redriven: DESERIALIZATION, not the - // POISON_MESSAGE of a handler that ran out of attempts (review 2026-11-01 06-14). - if (quarantine.quarantine( - record, - dev.caskeleton.messaging.api.error.FailureCategory.DESERIALIZATION, - undecodable)) { - settlement.acknowledgeAfterQuarantine(); - } else { - settlement.requeueAfterFailure( - undecodable, - dev.caskeleton.messaging.api.error.FailureCategory.DESERIALIZATION); - } - coordinator.release(partition); - shutdown.endWork(); - return; - } - java.util.concurrent.CompletableFuture handler = null; - boolean releaseImmediately = true; - try { - // Pause-and-seek re-reads the same record, so its retry header never moves; the - // count this runtime keeps for the offset is what tells the handler which attempt it - // is. A retry-topic hop carries its count in the header instead. - int attempt = - Math.max( - retryMetadataMapper.attemptOf(envelope), - failures.getOrDefault(new FailedOffset(partition, record.offset()), 0) + 1); - TransportDelivery delivery = - new TransportDelivery( - envelope, - deliveryMapper.toMetadata( - destination, - record, - attempt, - profile.consumer().group().orElse(null), - now), - settlement); - // The declared handler timeout is applied. The outstanding stage is kept so timeout - // handling can cancel it before this partition becomes eligible for redelivery. - handler = spec.sink().apply(delivery).toCompletableFuture(); - handler.get(handlerTimeout.toMillis(), java.util.concurrent.TimeUnit.MILLISECONDS); - } catch (java.util.concurrent.TimeoutException timedOut) { - // A timed-out handler may still be applying side effects, and cancelling the - // CompletableFuture does not stop it — it only completes the stage this worker holds, - // which released the permit and let the same offset run again beside the first. So - // the slot stays taken until the handler really finishes, and only then is a delivery - // it left unsettled requeued. - java.util.concurrent.CompletableFuture timedOutHandler = handler; - releaseImmediately = false; - java.util.concurrent.CompletableFuture releaseAfterCompletion = - timedOutHandler.whenComplete( - (ignored, failure) -> { - settlement.requeueAfterFailure(failure == null ? timedOut : failure); - coordinator.release(partition); - shutdown.endWork(); - }); - // Keep the continuation strongly referenced through this worker frame. The - // completion action owns the delayed permit/work-count release; its own result is - // intentionally not joined here. - Objects.requireNonNull(releaseAfterCompletion); - } catch (InterruptedException interrupted) { - Thread.currentThread().interrupt(); - if (handler != null) { - handler.cancel(true); - } - settlement.requeueAfterFailure(interrupted); - } catch (java.util.concurrent.ExecutionException | RuntimeException failure) { - // A handler failure is retried, not parked. PARKED completed the offset without any - // quarantine or dead-letter write, so a transient database outage silently discarded - // every message it touched. - settlement.requeueAfterFailure(failure); - } finally { - if (releaseImmediately) { - coordinator.release(partition); - shutdown.endWork(); - } - } - }); - return true; - } catch (java.util.concurrent.RejectedExecutionException refused) { - // The caller undoes the permit, the work count and the delivered registration. - return false; - } - } - - /** Applies everything workers queued. Poll thread only. */ - private void applySettlements() { - for (KafkaSettlementCommand command : settlements.drain()) { - Long currentEpoch = epochs.get(command.partition()); - if (currentEpoch == null || currentEpoch != command.epoch()) { - // The partition was revoked, or reassigned, after this settlement was created. Applying it - // would move the current owner's watermark using an outcome from the previous assignment, - // over offsets the current owner has not processed. - staleSettlements.incrementAndGet(); - continue; - } - switch (command.kind()) { - case COMPLETE, PARKED -> { - offsets.completed(command.partition(), command.offset()); - failures.remove(new FailedOffset(command.partition(), command.offset())); - } - case PAUSE_AND_SEEK -> { - coordinator.pause(command.partition()); - consumer.pause(Set.of(command.partition())); - } - // Unreachable while the enum has exactly these constants. Present so that adding a new - // settlement kind fails loudly here rather than being silently dropped from the poll loop, - // which would leave its offset uncommitted and its partition never resumed. - default -> throw new IllegalStateException("unhandled settlement kind: " + command.kind()); - } - } - } - - /** - * Keeps the epoch map in step with the current assignment. - * - *

The rebalance listener is the usual source of epochs, but it is not the only way a partition - * becomes owned: a manually assigned consumer never fires it. Deriving the epoch from the - * assignment as well means fencing works in both cases, and a partition that has gone away loses - * its epoch here even if no revoke callback arrived. - */ - private void syncEpochs() { - Set current = assignment(); - current.forEach( - partition -> epochs.computeIfAbsent(partition, key -> epochSequence.incrementAndGet())); - epochs.keySet().removeIf(partition -> !current.contains(partition)); - saturated.retainAll(current); - } - - /** Resumes a partition paused for lack of a slot once it has one and nothing else holds it. */ - private void resumeSaturated() { - int ceiling = spec.profile().consumer().maxInFlightPerOrderingUnit(); - saturated.removeIf( - partition -> { - if (coordinator.isPaused(partition) - || retries.isPaused(partition) - || coordinator.inFlight(partition) >= ceiling) { - return false; - } - consumer.resume(Set.of(partition)); - return true; - }); - } - - private void applyDueResumes(Instant now) { - Map due = retries.dueForResume(now); - due.forEach( - (partition, seekTo) -> { - consumer.seek(partition, seekTo); - coordinator.resume(partition); - consumer.resume(Set.of(partition)); - }); - } - - /** Commits only through the highest contiguous completed offset of each partition. */ - private void commitContiguous() { - Map toCommit = new LinkedHashMap<>(); - for (TopicPartition partition : new ArrayList<>(assignment())) { - OptionalLong commitOffset = offsets.commitOffset(partition); - if (commitOffset.isEmpty()) { - continue; - } - long offset = commitOffset.getAsLong(); - Long alreadyCommitted = committed.get(partition); - if (alreadyCommitted != null && alreadyCommitted >= offset) { - continue; - } - toCommit.put(partition, new OffsetAndMetadata(offset)); - } - if (toCommit.isEmpty()) { - return; - } - // Commit first, then record it locally. - // - // The local map and the tracker used to be updated before commitSync. A failed commit - // therefore left this consumer believing an offset was committed that the broker had never - // accepted, and the pruned tracker could no longer produce it — so the next successful commit - // jumped over the gap and the records in it were never redelivered. - consumer.commitSync(toCommit); - toCommit.forEach( - (partition, metadata) -> { - committed.put(partition, metadata.offset()); - offsets.pruneThrough(partition, metadata.offset() - 1); - }); - } - - /** - * How many settlements were refused because their assignment had been revoked. - * - *

Exposed rather than counted silently: a non-zero value means handlers are outliving their - * assignment, which is a rebalance or a handler-timeout problem an operator can act on. - */ - public int staleSettlements() { - return staleSettlements.get(); - } - - private Set assignment() { - return consumer.assignment(); - } - - /** - * Returns the offset committed for a partition, for diagnostics and tests. - * - * @param partition the partition - * @return the committed offset, when one has been written - */ - public OptionalLong committedOffset(TopicPartition partition) { - Long offset = committed.get(partition); - return offset == null ? OptionalLong.empty() : OptionalLong.of(offset); - } - - @Override - public CompletionStage pause(String scope) { - return onPollThread( - () -> { - Set partitions = scoped(scope); - partitions.forEach(coordinator::pause); - consumer.pause(partitions); - }); - } - - @Override - public CompletionStage resume(String scope) { - return onPollThread( - () -> { - Set partitions = scoped(scope); - partitions.forEach(coordinator::resume); - consumer.resume(partitions); - }); - } - - /** - * Queues work for the poll thread and reports when it ran. - * - *

The returned stage completes after the poll loop has actually applied the change, so a - * caller that awaits it knows the consumer is paused rather than merely asked to pause. - * - *

It therefore completes on the next poll cycle. A caller that blocks on it without a - * running loop waits forever, which is the honest shape of the request: there is no safe way to - * touch the consumer from another thread, so "paused" cannot be true until the loop says so. - */ - private CompletionStage onPollThread(Runnable work) { - CompletableFuture applied = new CompletableFuture<>(); - control.add( - () -> { - try { - work.run(); - applied.complete(null); - } catch (RuntimeException failure) { - applied.completeExceptionally(failure); - } - }); - return applied; - } - - private void drainControl() { - for (Runnable work = control.poll(); work != null; work = control.poll()) { - work.run(); - } - } - - private Set scoped(String scope) { - if (scope == null || scope.isBlank()) { - return Set.copyOf(assignment()); - } - return assignment().stream() - .filter(partition -> (partition.topic() + "-" + partition.partition()).equals(scope)) - .collect(java.util.stream.Collectors.toUnmodifiableSet()); - } - - @Override - public boolean isActive() { - return active.get(); - } - - @Override - public void close() { - if (active.compareAndSet(true, false)) { - // Close still runs here rather than through the queue: after this the poll loop stops, so - // queued work would never drain. What it does not do is race an in-progress poll — callers - // stop the loop first, and `active` makes a second close a no-op. - try { - drainControl(); - applySettlements(); - commitContiguous(); - } finally { - consumer.close(); - } - } - } - - /** - * The settlement handle handed to a worker. - * - *

Two things changed. It carries the assignment epoch, so a settlement that arrives after a - * revoke is refused rather than applied to whoever owns the partition now. And it is - * one-terminal: acknowledge, requeue and discard compete for a single CAS, because a handler that - * acknowledged and then requeued used to tell the poll thread both, and the poll thread believed - * the second one. - */ - private final class QueuedSettlement - implements dev.caskeleton.messaging.transport.TransportSettlement { - - private final TopicPartition partition; - private final ConsumerRecord record; - private final long offset; - private final long epoch; - private final java.util.concurrent.atomic.AtomicReference terminal = - new java.util.concurrent.atomic.AtomicReference<>(); - - private QueuedSettlement( - TopicPartition partition, ConsumerRecord record, long offset, long epoch) { - this.partition = partition; - this.record = record; - this.offset = offset; - this.epoch = epoch; - } - - @Override - public CompletionStage acknowledge() { - return terminalOnce( - "acknowledge", - () -> { - settlements.enqueue( - new KafkaSettlementCommand( - partition, offset, KafkaSettlementCommand.Kind.COMPLETE, epoch)); - return dev.caskeleton.messaging.api.settlement.SettlementResult.settled(); - }); - } - - /** - * A requeue the handler asked for, counted against the same attempt budget as a failure. - * - *

It used to pause and seek with no count, so a handler that kept answering {@code Retry} - * re-read its message forever and its partition never advanced — the retry policy's {@code - * maxAttempts} applied to exceptions only. - */ - @Override - public CompletionStage requeue( - Duration delay) { - return terminalOnce( - "requeue", - () -> - retryOrQuarantine( - new IllegalStateException( - "the handler asked for another attempt and the retry budget is spent"), - dev.caskeleton.messaging.api.error.FailureCategory.POISON_MESSAGE, - delay)); - } - - @Override - public CompletionStage discard() { - return terminalOnce( - "discard", - () -> { - settlements.enqueue( - new KafkaSettlementCommand( - partition, offset, KafkaSettlementCommand.Kind.PARKED, epoch)); - return dev.caskeleton.messaging.api.settlement.SettlementResult.settled(); - }); - } - - /** Used by the worker once an undecodable record has been written to quarantine. */ - private void acknowledgeAfterQuarantine() { - if (terminal.compareAndSet(null, "acknowledge")) { - settlements.enqueue( - new KafkaSettlementCommand( - partition, offset, KafkaSettlementCommand.Kind.PARKED, epoch)); - } - } - - /** - * Used by the worker when the handler failed or timed out and never settled. - * - *

Retried after the destination's backoff, never sooner than {@code MIN_RETRY_DELAY}; once - * the attempt budget is spent the record is written to quarantine and committed past. When - * there is no quarantine it keeps being retried — the offset may not advance past a message - * that exists nowhere else — which is why a production destination must have one. - */ - private void requeueAfterFailure(Throwable reason) { - requeueAfterFailure(reason, exhaustedCategory(reason)); - } - - /** - * {@link #requeueAfterFailure(Throwable)} under a category the caller already knows: a record - * that could not be decoded stays {@code DESERIALIZATION} when its first quarantine write was - * not confirmed and it reaches quarantine again through the retry path. - */ - private void requeueAfterFailure( - Throwable reason, dev.caskeleton.messaging.api.error.FailureCategory category) { - if (!terminal.compareAndSet(null, "requeue")) { - // The handler settled before it failed or before its late completion; that answer stands. - return; - } - retryOrQuarantine(reason, category, Duration.ZERO); - } - - /** - * Counts one more attempt, then either parks the record or pauses its partition for a retry. - * - *

The caller has already claimed the terminal slot. Once the attempt budget is spent the - * record is written to quarantine and committed past; when there is no quarantine it keeps - * being retried — the offset may not advance past a message that exists nowhere else. - */ - private dev.caskeleton.messaging.api.settlement.SettlementResult retryOrQuarantine( - Throwable reason, - dev.caskeleton.messaging.api.error.FailureCategory category, - Duration requested) { - FailedOffset key = new FailedOffset(partition, offset); - int attempt = failures.merge(key, 1, Integer::sum); - dev.caskeleton.messaging.policy.RetryPolicy retry = spec.profile().retry(); - if (attempt >= retry.maxAttempts() && quarantine.quarantine(record, category, reason)) { - failures.remove(key); - settlements.enqueue( - new KafkaSettlementCommand( - partition, offset, KafkaSettlementCommand.Kind.PARKED, epoch)); - return dev.caskeleton.messaging.api.settlement.SettlementResult.settled(); - } - Duration backoff = BACKOFF.delayFor(retry, attempt); - if (backoff.compareTo(MIN_RETRY_DELAY) < 0) { - backoff = MIN_RETRY_DELAY; - } - if (requested != null && backoff.compareTo(requested) < 0) { - backoff = requested; - } - return enqueueRequeue(backoff); - } - - /** - * The category a record that ran out of attempts is quarantined under: its last failure's own, - * when that failure is a platform one and so carries a classification — a transient one tells a - * redrive the record may pass now — and {@code POISON_MESSAGE}, the platform's name for "keeps - * failing its consumer", when it is not. - */ - private static dev.caskeleton.messaging.api.error.FailureCategory exhaustedCategory( - Throwable reason) { - return reason instanceof dev.caskeleton.messaging.api.error.MessagingException classified - ? classified.category() - : dev.caskeleton.messaging.api.error.FailureCategory.POISON_MESSAGE; - } - - private dev.caskeleton.messaging.api.settlement.SettlementResult enqueueRequeue( - Duration delay) { - retries.pauseUntil(partition, offset, delay, clock.instant()); - settlements.enqueue( - new KafkaSettlementCommand( - partition, offset, KafkaSettlementCommand.Kind.PAUSE_AND_SEEK, epoch)); - return new dev.caskeleton.messaging.api.settlement.SettlementResult( - dev.caskeleton.messaging.api.settlement.SettlementCompletion.UNKNOWN, - dev.caskeleton.messaging.api.settlement.SettlementEvidence.unknown(), - java.util.Optional.of( - dev.caskeleton.messaging.api.error.FailureDescriptor.of( - dev.caskeleton.messaging.api.error.FailureCategory.PROCESSING_TRANSIENT, - "KAFKA_PAUSED_FOR_RETRY", - "the partition was paused and will be re-read"))); - } - - private CompletionStage terminalOnce( - String what, - java.util.function.Supplier - call) { - if (!terminal.compareAndSet(null, what)) { - return CompletableFuture.failedFuture( - new IllegalStateException( - "this delivery was already settled by " - + terminal.get() - + "; a second " - + what - + " would contradict what the poll thread has already been told")); - } - return CompletableFuture.completedFuture(call.get()); - } - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaCredentialCallbackHandler.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaCredentialCallbackHandler.java deleted file mode 100644 index b5034247..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaCredentialCallbackHandler.java +++ /dev/null @@ -1,84 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.security.CredentialRuntime; -import dev.caskeleton.messaging.security.CredentialRuntimeRegistry; -import java.time.Instant; -import java.util.Arrays; -import java.util.List; -import java.util.Map; -import javax.security.auth.callback.Callback; -import javax.security.auth.callback.NameCallback; -import javax.security.auth.callback.PasswordCallback; -import javax.security.auth.callback.UnsupportedCallbackException; -import javax.security.auth.login.AppConfigurationEntry; -import org.apache.kafka.common.security.auth.AuthenticateCallbackHandler; - -/** - * Answers the SASL client's user name and password from {@link CredentialRuntimeRegistry}, at each - * authentication. - * - *

The JAAS entry used to carry both values, fixed when the producer was built: a rotated secret - * never reached a connection until the process restarted, and the user name was the credential id. - * Kafka asks this handler every time a connection authenticates — a new connection, or a - * re-authentication when the broker sets {@code connections.max.reauth.ms} — so each one reads the - * registry's current generation. - * - *

Kafka instantiates this class itself, so the registry and the credential id arrive through the - * client configuration under {@link #REGISTRY} and {@link #CREDENTIAL_ID}. - */ -public final class KafkaCredentialCallbackHandler implements AuthenticateCallbackHandler { - - /** Client configuration key carrying the {@link CredentialRuntimeRegistry}. */ - public static final String REGISTRY = "caskeleton.messaging.credential.registry"; - - /** Client configuration key carrying the credential id this client authenticates with. */ - public static final String CREDENTIAL_ID = "caskeleton.messaging.credential.id"; - - private CredentialRuntimeRegistry registry; - - private String credentialId; - - /** Created by Kafka through reflection. */ - public KafkaCredentialCallbackHandler() {} - - @Override - public void configure( - Map configs, String saslMechanism, List jaasConfigEntries) { - if (!(configs.get(REGISTRY) instanceof CredentialRuntimeRegistry configured) - || !(configs.get(CREDENTIAL_ID) instanceof String id)) { - throw new MessagingConfigurationException( - "SASL_CALLBACK_NOT_CONFIGURED", - "the Kafka client names this callback handler but does not carry " - + REGISTRY - + " and " - + CREDENTIAL_ID); - } - this.registry = configured; - this.credentialId = id; - } - - @Override - public void handle(Callback[] callbacks) throws UnsupportedCallbackException { - CredentialRuntime credential = registry.resolve(credentialId, Instant.now()); - for (Callback callback : callbacks) { - if (callback instanceof NameCallback name) { - name.setName( - credential - .username() - .orElseThrow(() -> KafkaSecurityConfigurer.usernameMissing(credentialId))); - } else if (callback instanceof PasswordCallback password) { - char[] material = credential.material(); - // PasswordCallback keeps its own copy, so this one is wiped as soon as it is handed over. - password.setPassword(material); - Arrays.fill(material, '\0'); - } else { - // SCRAM asks for extensions and carries on without them when the handler declines. - throw new UnsupportedCallbackException(callback); - } - } - } - - @Override - public void close() {} -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaDeadLetterPublisher.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaDeadLetterPublisher.java deleted file mode 100644 index b693c875..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaDeadLetterPublisher.java +++ /dev/null @@ -1,49 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -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.util.Objects; -import java.util.concurrent.CompletionStage; - -/** - * The Kafka entry point to dead lettering. - * - *

A thin delegation to the shared orchestrator on purpose. The publish-then-settle ordering is a - * platform invariant, not a Kafka one, so re-implementing it per adapter is exactly how one adapter - * ends up acknowledging first. - */ -public final class KafkaDeadLetterPublisher { - - private final DeadLetterOrchestrator orchestrator; - - /** - * Creates a Kafka dead letter publisher. - * - * @param orchestrator the shared dead letter orchestrator - */ - public KafkaDeadLetterPublisher(DeadLetterOrchestrator orchestrator) { - this.orchestrator = Objects.requireNonNull(orchestrator, "orchestrator must not be null"); - } - - /** - * Dead letters one delivery. - * - * @param profile the source destination profile - * @param delivery the failed delivery - * @param failure the sanitized failure - * @param settlement the source settlement callback - * @return a stage completing with the dead letter outcome - */ - public CompletionStage deadLetter( - DestinationProfile profile, - MessageDelivery delivery, - FailureDescriptor failure, - SourceSettlement settlement) { - return orchestrator.deadLetter(profile, delivery, failure, settlement); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaDeliveryMapper.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaDeliveryMapper.java deleted file mode 100644 index 239ba8ea..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaDeliveryMapper.java +++ /dev/null @@ -1,167 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -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.apache.kafka.clients.consumer.ConsumerRecord; -import org.apache.kafka.common.header.Headers; - -/** - * Rebuilds a platform envelope from a Kafka record. - * - *

The payload stays encoded. Decoding happens above the transport so a payload the codec rejects - * is classified as a schema failure and parked by the platform, rather than surfacing as a - * Kafka-specific exception the consumer loop has to interpret. - * - *

A record with no {@code msg.id} header is rejected rather than assigned a fresh identity. - * Inventing an id would make the message invisible to Inbox deduplication and untraceable back to - * its producer, which is worse than refusing it. - */ -public final class KafkaDeliveryMapper { - - private final KafkaHeaderMapper headerMapper; - - /** Creates a mapper with the default header mapper. */ - public KafkaDeliveryMapper() { - this(new KafkaHeaderMapper()); - } - - /** - * Creates a mapper with an explicit header mapper. - * - * @param headerMapper the header mapper - */ - public KafkaDeliveryMapper(KafkaHeaderMapper headerMapper) { - this.headerMapper = Objects.requireNonNull(headerMapper, "headerMapper must not be null"); - } - - /** - * Converts a consumer record into an envelope. - * - * @param record the Kafka record - * @return the still-encoded envelope - */ - public MessageEnvelope toEnvelope(ConsumerRecord record) { - Objects.requireNonNull(record, "record must not be null"); - Headers headers = record.headers(); - - ContentType contentType = - new ContentType( - Optional.ofNullable(headerMapper.value(headers, ReservedHeaders.CONTENT_TYPE)) - .orElse(ContentType.JSON.value())); - - byte[] payload = record.value() == null ? new byte[0] : record.value(); - - return new MessageEnvelope<>( - new MessageId(uuid(headers, ReservedHeaders.MESSAGE_ID)), - new MessageType(required(headers, ReservedHeaders.MESSAGE_TYPE)), - new SchemaVersion(intValue(headers, ReservedHeaders.SCHEMA_VERSION)), - instant(headers, ReservedHeaders.PRODUCED_AT, Instant.ofEpochMilli(record.timestamp())), - Optional.ofNullable(headerMapper.value(headers, ReservedHeaders.OCCURRED_AT)) - .map(Instant::parse), - new ProducerId( - Optional.ofNullable(headerMapper.value(headers, ReservedHeaders.PRODUCER)) - .orElse("unknown")), - Optional.ofNullable(headerMapper.value(headers, ReservedHeaders.CORRELATION_ID)) - .map(CorrelationId::new), - Optional.ofNullable(headerMapper.value(headers, ReservedHeaders.CAUSATION_ID)) - .map(value -> new CausationId(new MessageId(UUID.fromString(value)))), - contentType, - Optional.ofNullable(headerMapper.value(headers, ReservedHeaders.PARTITION_KEY)), - Optional.ofNullable(headerMapper.value(headers, ReservedHeaders.ORDERING_KEY)), - Optional.ofNullable(headerMapper.value(headers, ReservedHeaders.TENANT)) - .map(TenantContext::new), - traceContext(headers), - headerMapper.carriedForward(headers), - new EncodedMessage(payload, contentType, Optional.empty())); - } - - /** - * Builds the delivery metadata for a record. - * - * @param destination the logical destination - * @param record the Kafka record - * @param attempt the attempt number, counting the first delivery as one - * @param consumerGroup the consumer group - * @param receivedAt when the consumer received the record - * @return the delivery metadata - */ - public DeliveryMetadata toMetadata( - DestinationName destination, - ConsumerRecord record, - int attempt, - String consumerGroup, - Instant receivedAt) { - return new DeliveryMetadata( - destination, - attempt, - attempt > 1, - Optional.of(new KafkaPosition(record.topic(), record.partition(), record.offset())), - Optional.of(record.topic() + "-" + record.partition()), - Optional.ofNullable(consumerGroup), - receivedAt); - } - - private TraceContext traceContext(Headers headers) { - return new TraceContext( - Optional.ofNullable(headerMapper.value(headers, ReservedHeaders.TRACEPARENT)), - Optional.ofNullable(headerMapper.value(headers, ReservedHeaders.TRACESTATE)), - Optional.ofNullable(headerMapper.value(headers, ReservedHeaders.BAGGAGE))); - } - - private String required(Headers headers, String name) { - String value = headerMapper.value(headers, name); - if (value == null || value.isBlank()) { - throw new MessageValidationException( - "KAFKA_HEADER_MISSING", "record is missing the required header " + name); - } - return value; - } - - private UUID uuid(Headers headers, String name) { - try { - return UUID.fromString(required(headers, name)); - } catch (IllegalArgumentException exception) { - throw new MessageValidationException( - "KAFKA_HEADER_MALFORMED", "header " + name + " is not a UUID", exception); - } - } - - private int intValue(Headers headers, String name) { - try { - return Integer.parseInt(required(headers, name)); - } catch (NumberFormatException exception) { - throw new MessageValidationException( - "KAFKA_HEADER_MALFORMED", "header " + name + " is not an integer", exception); - } - } - - private Instant instant(Headers headers, String name, Instant fallback) { - String value = headerMapper.value(headers, name); - if (value == null || value.isBlank()) { - return fallback; - } - try { - return Instant.parse(value); - } catch (java.time.format.DateTimeParseException exception) { - throw new MessageValidationException( - "KAFKA_HEADER_MALFORMED", "header " + name + " is not an instant", exception); - } - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaHeaderMapper.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaHeaderMapper.java deleted file mode 100644 index b9624ddc..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaHeaderMapper.java +++ /dev/null @@ -1,169 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -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.nio.charset.StandardCharsets; -import java.util.LinkedHashMap; -import java.util.Map; -import java.util.Objects; -import org.apache.kafka.common.header.Header; -import org.apache.kafka.common.header.Headers; -import org.apache.kafka.common.header.internals.RecordHeaders; - -/** - * Maps envelope identity onto Kafka record headers and back. - * - *

Identity travels in headers rather than inside the payload so that a consumer can classify, - * route, and dead letter a message it cannot deserialize. A poison payload still has a readable - * {@code msg.id} and {@code msg.type}, which is what makes parking it actionable instead of opaque. - */ -public final class KafkaHeaderMapper { - - /** - * Writes the envelope's reserved and application headers. - * - * @param envelope the envelope being published - * @return Kafka headers - */ - public Headers toKafkaHeaders(MessageEnvelope envelope) { - Objects.requireNonNull(envelope, "envelope must not be null"); - Headers headers = new RecordHeaders(); - - put(headers, ReservedHeaders.MESSAGE_ID, envelope.messageId().value().toString()); - put(headers, ReservedHeaders.MESSAGE_TYPE, envelope.messageType().value()); - put( - headers, - ReservedHeaders.SCHEMA_VERSION, - Integer.toString(envelope.schemaVersion().value())); - put(headers, ReservedHeaders.PRODUCER, envelope.producer().value()); - put(headers, ReservedHeaders.PRODUCED_AT, envelope.producedAt().toString()); - put(headers, ReservedHeaders.CONTENT_TYPE, envelope.contentType().value()); - - envelope - .occurredAt() - .ifPresent(value -> put(headers, ReservedHeaders.OCCURRED_AT, value.toString())); - envelope - .correlationId() - .ifPresent(value -> put(headers, ReservedHeaders.CORRELATION_ID, value.value())); - envelope - .causationId() - .ifPresent( - value -> put(headers, ReservedHeaders.CAUSATION_ID, value.value().value().toString())); - envelope.partitionKey().ifPresent(value -> put(headers, ReservedHeaders.PARTITION_KEY, value)); - envelope.orderingKey().ifPresent(value -> put(headers, ReservedHeaders.ORDERING_KEY, value)); - // Written because the consumer has no other way to learn it: a broker record carries no - // ambient tenant, so a tenant left off the wire is a tenant the consumed envelope does not - // have — and every authorization and partitioning decision downstream reads that field. - envelope - .tenantContext() - .ifPresent(value -> put(headers, ReservedHeaders.TENANT, value.tenantId())); - envelope - .traceContext() - .traceparent() - .ifPresent(value -> put(headers, ReservedHeaders.TRACEPARENT, value)); - envelope - .traceContext() - .tracestate() - .ifPresent(value -> put(headers, ReservedHeaders.TRACESTATE, value)); - envelope - .traceContext() - .baggage() - .ifPresent(value -> put(headers, ReservedHeaders.BAGGAGE, value)); - - // The envelope's own header map is written last and the consumer reads `lastHeader`, so a name - // written here wins over the canonical value above. A row in the outbox carrying `msg.id` - // therefore overwrote the identity that inbox deduplication and the audit trail key on, - // corrupting a different message's dedup state rather than merely its own. - // - // 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-topic 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"); - } - put(headers, name.value(), value.value()); - }); - - return headers; - } - - /** - * Reads Kafka headers back into a platform header map. - * - * @param headers the record headers - * @return the platform headers, including reserved names - */ - public MessageHeaders fromKafkaHeaders(Headers headers) { - Objects.requireNonNull(headers, "headers must not be null"); - Map values = new LinkedHashMap<>(); - for (Header header : headers) { - byte[] value = header.value(); - values.put( - new HeaderName(header.key()), - new HeaderValue(value == null ? "" : new String(value, StandardCharsets.UTF_8))); - } - 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 headers the record headers - * @return the headers to carry on the rebuilt envelope - */ - public MessageHeaders carriedForward(Headers headers) { - Objects.requireNonNull(headers, "headers must not be null"); - Map values = new LinkedHashMap<>(); - for (Header header : headers) { - if (CanonicalEnvelopeHeaders.restatesEnvelopeField(header.key())) { - continue; - } - byte[] value = header.value(); - values.put( - new HeaderName(header.key()), - new HeaderValue(value == null ? "" : new String(value, StandardCharsets.UTF_8))); - } - return MessageHeaders.platform(values); - } - - /** - * Reads one header value. - * - * @param headers the record headers - * @param name the header name - * @return the value, or null when absent - */ - public String value(Headers headers, String name) { - Header header = headers.lastHeader(name); - return header == null || header.value() == null - ? null - : new String(header.value(), StandardCharsets.UTF_8); - } - - private static void put(Headers headers, String name, String value) { - headers.add(name, value.getBytes(StandardCharsets.UTF_8)); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransport.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransport.java deleted file mode 100644 index ce84b544..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransport.java +++ /dev/null @@ -1,212 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -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.PublishResult; -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.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import java.util.concurrent.atomic.AtomicBoolean; -import java.util.function.Function; -import org.apache.kafka.clients.producer.Producer; -import org.apache.kafka.clients.producer.ProducerRecord; - -/** - * The Stable Kafka adapter. - * - *

Built on the plain {@code Producer} interface rather than a framework template so the whole - * publish path, including its ambiguity handling, is exercisable against {@code MockProducer} - * without a broker. A guarantee that can only be tested with a live cluster is a guarantee that - * stops being tested. - * - *

The local checks — shutdown state and payload size — run before the record reaches the - * producer so that both fail with {@code NOT_TRANSMITTED} evidence. Letting an oversized record - * reach the broker would convert a deterministic local rejection into a broker error whose - * ambiguity the caller then has to reason about. - */ -public final class KafkaMessagingTransport implements MessagingTransport { - - /** - * What this adapter can prove, with deduplicated publish absent. - * - *

It was {@code true}, justified by producer idempotence. Producer idempotence deduplicates - * sequence retries within one producer session: the producer id is reassigned on - * restart, so the same logical message published again after a crash is a new sequence and the - * broker stores it twice. The capability an application reads is "the broker suppresses duplicate - * publishes of a stable id", which needs a persistent message-id store that this platform does - * not have. - * - *

Declaring it true means {@code PublishDeduplication} is accepted and silently does nothing — - * the caller believes the broker is deduplicating and skips the idempotency it would otherwise - * build. False makes that request a startup failure instead, which is the whole reason the flag - * exists. - * - *

Delayed delivery is absent too: Kafka has no broker-side schedule. - */ - private static final MessagingCapabilities CAPABILITIES = - MessagingCapabilities.of(MessagingCapabilities.Capability.ORDERED_STREAM); - - private final String brokerName; - private final long generation; - private final Producer producer; - private final KafkaPublishMapper mapper; - private final KafkaPublishFailureClassifier failures; - 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 producer the Kafka producer - */ - public KafkaMessagingTransport( - String brokerName, long generation, Producer producer) { - this( - brokerName, - generation, - producer, - spec -> { - throw new MessagingCapabilityUnavailableException( - "KAFKA_CONSUMER_NOT_CONFIGURED", - "this Kafka 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 producer the Kafka producer - * @param consumerFactory builds a consumer registration for a spec - */ - public KafkaMessagingTransport( - String brokerName, - long generation, - Producer producer, - Function consumerFactory) { - this.brokerName = Objects.requireNonNull(brokerName, "brokerName must not be null"); - this.generation = generation; - this.producer = Objects.requireNonNull(producer, "producer must not be null"); - this.consumerFactory = Objects.requireNonNull(consumerFactory, "consumerFactory is required"); - this.mapper = new KafkaPublishMapper(); - this.failures = new KafkaPublishFailureClassifier(); - } - - /** - * {@inheritDoc} - * - *

The {@code Future} returned by {@code Producer.send} is deliberately discarded. Blocking on - * it would defeat the asynchronous contract, and every outcome it could report — success, - * failure, or timeout — is already delivered through the callback, which is what completes the - * returned stage. Nothing is suppressed by dropping it. - */ - @Override - @SuppressWarnings("FutureReturnValueIgnored") - public CompletionStage publish(TransportPublishRequest request) { - Objects.requireNonNull(request, "request must not be null"); - - if (closed.get()) { - // Not the message's fault: the next instance, or this one after a restart, will take it. A - // caller that trusts the retryable flag must not park it. - return completed( - new TransportPublishResult( - PublishResult.rejected( - Duration.ZERO, - FailureDescriptor.of( - FailureCategory.TRANSIENT_INFRASTRUCTURE, - "KAFKA_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)); - } - - ProducerRecord record = mapper.toRecord(request); - CompletableFuture completion = new CompletableFuture<>(); - long startedAt = System.nanoTime(); - - producer.send( - record, - (metadata, error) -> { - Duration elapsed = Duration.ofNanos(System.nanoTime() - startedAt); - if (error != null) { - completion.complete(new TransportPublishResult(failures.classify(error, elapsed))); - return; - } - completion.complete( - new TransportPublishResult( - mapper.confirmed( - metadata, request.profile().producer().confirmation(), elapsed))); - }); - return completion; - } - - @Override - public TransportConsumerRegistration register(TransportConsumerSpec spec) { - Objects.requireNonNull(spec, "spec must not be null"); - if (closed.get()) { - throw new MessagingCapabilityUnavailableException( - "KAFKA_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)) { - producer.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( - PublishResult.rejected( - Duration.ZERO, - FailureDescriptor.of(FailureCategory.PERMANENT_BUSINESS, code, message))); - } - - private static CompletionStage completed(TransportPublishResult result) { - return CompletableFuture.completedFuture(result); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaOffsetResetExecutor.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaOffsetResetExecutor.java deleted file mode 100644 index 0ec2cfed..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaOffsetResetExecutor.java +++ /dev/null @@ -1,63 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.error.MessageAuthorizationException; -import java.util.Map; -import java.util.Objects; -import java.util.function.Predicate; -import org.apache.kafka.common.TopicPartition; - -/** - * Resets committed offsets, but only behind an explicit approval check. - * - *

An offset reset is destructive in both directions: rewinding reprocesses, and skipping forward - * discards. The approval predicate is a constructor argument rather than a flag so that a runtime - * assembled without an approval source physically cannot perform one. - */ -public final class KafkaOffsetResetExecutor { - - private final Predicate approvals; - private final OffsetCommitter committer; - - /** - * Creates an executor. - * - * @param approvals decides whether an approval ticket is valid - * @param committer applies the offsets once approved - */ - public KafkaOffsetResetExecutor(Predicate approvals, OffsetCommitter committer) { - this.approvals = Objects.requireNonNull(approvals, "approvals must not be null"); - this.committer = Objects.requireNonNull(committer, "committer must not be null"); - } - - /** - * Resets a group's offsets after checking the approval. - * - * @param consumerGroup the group to reset - * @param offsets the offsets to commit - * @param approvalTicket the approval reference - */ - public void reset( - String consumerGroup, Map offsets, String approvalTicket) { - Objects.requireNonNull(consumerGroup, "consumerGroup must not be null"); - Objects.requireNonNull(offsets, "offsets must not be null"); - if (approvalTicket == null || approvalTicket.isBlank() || !approvals.test(approvalTicket)) { - throw new MessageAuthorizationException( - "OFFSET_RESET_NOT_APPROVED", - "resetting offsets for " + consumerGroup + " requires an approved request"); - } - committer.commit(consumerGroup, Map.copyOf(offsets)); - } - - /** Applies approved offsets to a consumer group. */ - @FunctionalInterface - public interface OffsetCommitter { - - /** - * Commits offsets for a group. - * - * @param consumerGroup the group - * @param offsets the offsets to commit - */ - void commit(String consumerGroup, Map offsets); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPartitionRetryScheduler.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPartitionRetryScheduler.java deleted file mode 100644 index a0f79c82..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPartitionRetryScheduler.java +++ /dev/null @@ -1,90 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import java.time.Duration; -import java.time.Instant; -import java.util.LinkedHashMap; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.concurrent.ConcurrentHashMap; -import org.apache.kafka.common.TopicPartition; - -/** - * Tracks which partitions are paused for retry and when they may resume. - * - *

Pause-and-seek is the only Kafka retry strategy that preserves order, because the message - * never leaves its position in the log: the consumer stops fetching the partition, waits, seeks - * back, and re-delivers the same record. Everything behind it waits too, which is exactly the - * intended behaviour on an ordered destination. - * - *

Resume times are held here rather than in a timer thread so the single poll thread stays the - * only caller of the Kafka consumer. - */ -public final class KafkaPartitionRetryScheduler { - - private final Map paused = new ConcurrentHashMap<>(); - - /** - * Records that a partition is paused until a deadline, and where to seek back to. - * - * @param partition the partition - * @param seekTo the offset to re-deliver from - * @param delay how long to stay paused - * @param now the current instant - */ - public void pauseUntil(TopicPartition partition, long seekTo, Duration delay, Instant now) { - Objects.requireNonNull(partition, "partition must not be null"); - Objects.requireNonNull(delay, "delay must not be null"); - Objects.requireNonNull(now, "now must not be null"); - paused.put(partition, new PausedPartition(seekTo, now.plus(delay))); - } - - /** - * Returns the partitions whose pause has expired, in a stable order. - * - * @param now the current instant - * @return the partitions ready to resume, with the offset to seek to - */ - public Map dueForResume(Instant now) { - Objects.requireNonNull(now, "now must not be null"); - Map due = new LinkedHashMap<>(); - for (Map.Entry entry : paused.entrySet()) { - if (!now.isBefore(entry.getValue().resumeAt())) { - due.put(entry.getKey(), entry.getValue().seekTo()); - } - } - due.keySet().forEach(paused::remove); - return Map.copyOf(due); - } - - /** - * Reports whether a partition is currently paused for retry. - * - * @param partition the partition - * @return true while paused - */ - public boolean isPaused(TopicPartition partition) { - return paused.containsKey(partition); - } - - /** - * Returns the currently paused partitions. - * - * @return the paused partitions - */ - public List pausedPartitions() { - return List.copyOf(paused.keySet()); - } - - /** - * Drops the pause state for a partition, as on revocation. - * - * @param partition the partition - */ - public void forget(TopicPartition partition) { - paused.remove(partition); - } - - /** Where a paused partition resumes from and when. */ - private record PausedPartition(long seekTo, Instant resumeAt) {} -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPosition.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPosition.java deleted file mode 100644 index e11b9c63..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPosition.java +++ /dev/null @@ -1,38 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.publish.BrokerPosition; -import java.util.Map; -import java.util.Objects; - -/** - * A Kafka topic, partition, and offset coordinate. - * - * @param topic the physical topic - * @param partition the partition index - * @param offset the record offset - */ -public record KafkaPosition(String topic, int partition, long offset) implements BrokerPosition { - - public KafkaPosition { - Objects.requireNonNull(topic, "topic must not be null"); - if (partition < 0) { - throw new IllegalArgumentException("partition must not be negative"); - } - if (offset < 0) { - throw new IllegalArgumentException("offset must not be negative"); - } - } - - @Override - public String broker() { - return "kafka"; - } - - @Override - public Map diagnosticAttributes() { - return Map.of( - "topic", topic, - "partition", Integer.toString(partition), - "offset", Long.toString(offset)); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaProfileValidator.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaProfileValidator.java deleted file mode 100644 index 0d8c588c..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaProfileValidator.java +++ /dev/null @@ -1,60 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import java.util.Objects; - -/** - * Startup validation of the Kafka Stable profile. - * - *

Each rule closes a way of appearing to have at-least-once delivery without having it. - * Non-idempotent producers duplicate on internal retry. {@code acks=1} confirms from a leader that - * may not have replicated yet. More than five in-flight requests lets the broker reorder a retried - * batch ahead of a later one. And consumer auto-commit acknowledges on a timer, so a message is - * marked processed before the handler that would have processed it ever ran. - */ -public final class KafkaProfileValidator { - - private static final int MAX_IN_FLIGHT = 5; - - /** - * Validates one Kafka broker profile. - * - * @param profile the profile to validate - * @throws IllegalArgumentException when the profile cannot honour its declared guarantees - */ - public void validate(KafkaBrokerProfile profile) { - Objects.requireNonNull(profile, "profile must not be null"); - - if (profile.stable() && !profile.enableIdempotence()) { - throw new IllegalArgumentException( - "stable Kafka producer requires idempotence and acks=all: " + profile.broker()); - } - if (profile.stable() && !"all".equals(profile.acks())) { - throw new IllegalArgumentException( - "stable Kafka producer requires idempotence and acks=all: " + profile.broker()); - } - if (profile.maxInFlightRequestsPerConnection() > MAX_IN_FLIGHT) { - throw new IllegalArgumentException( - "max.in.flight.requests.per.connection must be at most 5: " + profile.broker()); - } - if (profile.maxInFlightRequestsPerConnection() < 1) { - throw new IllegalArgumentException( - "max.in.flight.requests.per.connection must be at least 1: " + profile.broker()); - } - if (profile.enableAutoCommit()) { - throw new IllegalArgumentException( - "consumer auto commit is forbidden; the platform commits after handler success: " - + profile.broker()); - } - if (profile.deliveryTimeout().isNegative() || profile.deliveryTimeout().isZero()) { - throw new IllegalArgumentException("delivery timeout must be positive: " + profile.broker()); - } - if (profile.production() && !profile.tlsEnabled()) { - throw new IllegalArgumentException( - "a production Kafka connection requires TLS: " + profile.broker()); - } - if (profile.production() && !profile.authenticationEnabled()) { - throw new IllegalArgumentException( - "a production Kafka connection requires broker authentication: " + profile.broker()); - } - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifier.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifier.java deleted file mode 100644 index ce51ab3c..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifier.java +++ /dev/null @@ -1,121 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.publish.PublishResult; -import java.time.Duration; -import java.util.Optional; -import org.apache.kafka.common.errors.AuthenticationException; -import org.apache.kafka.common.errors.AuthorizationException; -import org.apache.kafka.common.errors.InvalidTopicException; -import org.apache.kafka.common.errors.ProducerFencedException; -import org.apache.kafka.common.errors.RecordTooLargeException; -import org.apache.kafka.common.errors.SerializationException; -import org.apache.kafka.common.errors.UnsupportedVersionException; - -/** - * Turns a producer exception into a completion the caller can act on. - * - *

The split is between failures that prove the record was not stored and failures that prove - * nothing. Serialization, an invalid topic, authentication, authorization, fencing, and an - * over-large record are all rejections: the broker never took the record, so abandoning the attempt - * is safe. Of those, authentication and authorization are marked retryable, because they clear on - * their own once a credential or an ACL is in place. Everything else — a delivery timeout above all - * — is ambiguous, because the record may already be replicated and only the acknowledgement was - * lost. - * - *

The default is deliberately ambiguous rather than rejected. Guessing "rejected" on an unknown - * error is what turns one lost confirmation into two orders. - */ -public final class KafkaPublishFailureClassifier { - - /** - * Classifies a producer failure. - * - * @param error the throwable the producer reported - * @param elapsed how long the attempt took - * @return the publish outcome with its evidence - */ - public PublishResult classify(Throwable error, Duration elapsed) { - Throwable cause = unwrap(error); - if (isDefinitiveRejection(cause)) { - return PublishResult.rejected( - elapsed, descriptor(cause, rejectionCategory(cause), mayPassOnRetry(cause))); - } - return PublishResult.ambiguous(elapsed, descriptor(cause, FailureCategory.AMBIGUOUS, false)); - } - - /** - * Reports whether the exception proves the record was never stored. - * - * @param cause the unwrapped throwable - * @return true when the failure is definitive - */ - public boolean isDefinitiveRejection(Throwable cause) { - return cause instanceof SerializationException - || cause instanceof InvalidTopicException - || cause instanceof AuthenticationException - || cause instanceof AuthorizationException - || cause instanceof ProducerFencedException - || cause instanceof RecordTooLargeException - || cause instanceof UnsupportedVersionException; - } - - /** - * Reports whether a definitive rejection may pass if the same record is sent again later. - * - *

Authentication and authorization prove the broker did not store the record, but not that it - * will refuse it again: a credential being rotated, or an ACL deployed after the application, - * fails every publish this way for a few minutes and then stops. Marked not retryable, a - * publisher that trusts the flag parks every record sent in those minutes. A credential that is - * simply wrong is retried too, for as long as it stays wrong; the descriptor's code names it, so - * a caller can tell that retry from a rotation and stop it. - * - *

This flag departs from {@link FailureDescriptor#defaultRetryable} on purpose, for publish - * only: that default says an authentication or authorization failure is not retried, and it still - * governs consumption, where the retry engine requires both. See {@code - * src/platforms/messaging/CLAUDE.md} "Publish retryability of authentication and authorization". - */ - private static boolean mayPassOnRetry(Throwable cause) { - return cause instanceof AuthenticationException || cause instanceof AuthorizationException; - } - - private static FailureCategory rejectionCategory(Throwable cause) { - if (cause instanceof AuthenticationException) { - return FailureCategory.AUTHENTICATION; - } - if (cause instanceof AuthorizationException) { - return FailureCategory.AUTHORIZATION; - } - if (cause instanceof SerializationException) { - return FailureCategory.DESERIALIZATION; - } - if (cause instanceof InvalidTopicException || cause instanceof UnsupportedVersionException) { - return FailureCategory.CONFIGURATION; - } - return FailureCategory.PERMANENT_BUSINESS; - } - - private static FailureDescriptor descriptor( - Throwable cause, FailureCategory category, boolean retryable) { - String type = cause == null ? "Unknown" : cause.getClass().getSimpleName(); - return new FailureDescriptor( - category, - "KAFKA_" + type.toUpperCase(java.util.Locale.ROOT), - retryable, - "kafka publish failed with " + type, - Optional.of(type)); - } - - private static Throwable unwrap(Throwable error) { - Throwable current = error; - while (current instanceof java.util.concurrent.CompletionException - || current instanceof java.util.concurrent.ExecutionException) { - if (current.getCause() == null) { - return current; - } - current = current.getCause(); - } - return current; - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishMapper.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishMapper.java deleted file mode 100644 index 7c74f137..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishMapper.java +++ /dev/null @@ -1,106 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.destination.ConfirmationRequirement; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.api.publish.ConfirmationLevel; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.api.publish.RoutingOutcome; -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.transport.TransportPublishRequest; -import java.nio.charset.StandardCharsets; -import java.time.Duration; -import java.util.Objects; -import java.util.Optional; -import org.apache.kafka.clients.producer.ProducerRecord; -import org.apache.kafka.clients.producer.RecordMetadata; - -/** - * Builds Kafka records from platform publish requests and reads confirmations back. - * - *

A Kafka topic publish has no routing stage, so {@link RoutingOutcome#NOT_APPLICABLE} is - * reported rather than {@code ROUTED}. Claiming a routing outcome the broker never evaluated would - * make the RabbitMQ adapter's genuine {@code UNROUTABLE} indistinguishable from Kafka's silence. - */ -public final class KafkaPublishMapper { - - private final KafkaHeaderMapper headerMapper; - - /** Creates a mapper with the default header mapper. */ - public KafkaPublishMapper() { - this(new KafkaHeaderMapper()); - } - - /** - * Creates a mapper with an explicit header mapper. - * - * @param headerMapper the header mapper - */ - public KafkaPublishMapper(KafkaHeaderMapper headerMapper) { - this.headerMapper = Objects.requireNonNull(headerMapper, "headerMapper must not be null"); - } - - /** - * Converts a publish request into a producer record. - * - * @param request the publish request - * @return the producer record - */ - public ProducerRecord toRecord(TransportPublishRequest request) { - Objects.requireNonNull(request, "request must not be null"); - DestinationProfile profile = request.profile(); - String topic = - profile - .physical() - .topic() - .orElseThrow( - () -> - new MessagingConfigurationException( - "KAFKA_TOPIC_MISSING", - "destination has no Kafka topic: " + profile.name().value())); - - MessageEnvelope envelope = request.envelope(); - byte[] key = - envelope - .partitionKey() - .or(envelope::orderingKey) - .map(value -> value.getBytes(StandardCharsets.UTF_8)) - .orElse(null); - - return new ProducerRecord<>( - topic, - null, - envelope.producedAt().toEpochMilli(), - key, - envelope.payload().bytes(), - headerMapper.toKafkaHeaders(envelope)); - } - - /** - * Builds a confirmed result from record metadata. - * - *

The confirmation level reported is the one the destination profile demanded, because the - * producer is configured with {@code acks=all} for any profile asking for replication evidence - * and the profile guard refuses the combination where it is not. - * - * @param metadata the broker's record metadata - * @param requirement the confirmation the profile demanded - * @param elapsed how long the publish took - * @return the confirmed result - */ - public PublishResult confirmed( - RecordMetadata metadata, ConfirmationRequirement requirement, Duration elapsed) { - Objects.requireNonNull(metadata, "metadata must not be null"); - ConfirmationLevel level = - requirement == ConfirmationRequirement.REPLICATION_OR_PERSISTENCE_ACK - ? ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK - : ConfirmationLevel.BROKER_ACK; - - return PublishResult.confirmed( - level, - RoutingOutcome.NOT_APPLICABLE, - Optional.of(new KafkaPosition(metadata.topic(), metadata.partition(), metadata.offset())), - elapsed); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java deleted file mode 100644 index af09f0e8..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java +++ /dev/null @@ -1,56 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.error.FailureCategory; -import org.apache.kafka.clients.consumer.ConsumerRecord; - -/** - * Where a record that cannot be decoded is written before its offset is committed. - * - *

The consumer used to mark an undecodable record {@code PARKED}, and the poll thread treated - * {@code PARKED} exactly like {@code COMPLETE} — the offset advanced and the record was gone. There - * was no quarantine collection, no dead-letter publish and no record of what had been dropped, so - * "parked" named a state nothing implemented. - * - *

Committing past a record is only safe once the record exists somewhere else. An implementation - * that cannot write returns {@code false}, and the consumer leaves the offset uncommitted rather - * than losing the message quietly. - */ -@FunctionalInterface -public interface KafkaQuarantinePublisher { - - /** - * Writes a record the consumer will not deliver somewhere durable, under the reason it gives. - * - *

The category is the caller's, because only the caller knows which of two very different - * things happened: the record could not be rebuilt at all ({@link - * FailureCategory#DESERIALIZATION}), or its handler failed until the attempt budget ran out — - * under the failure's own category when it carries one, {@link FailureCategory#POISON_MESSAGE} - * when it does not. Both were written as {@code POISON_MESSAGE}, so a redrive could not tell a - * message that will never decode from one an outage kept failing (review 2026-11-01 06-14). - * - * @param record the record as it arrived - * @param category why it is quarantined, written as the failure-category header - * @param reason the failure; its type is written as the failure-code header - * @return true when the write is confirmed, so the source offset may be committed - */ - boolean quarantine( - ConsumerRecord record, FailureCategory category, Throwable reason); - - /** - * The default: nothing is configured, so nothing may be committed past. - * - *

One instance, so a consumer can tell it apart from a configured quarantine and refuse it on - * a production destination. - */ - static KafkaQuarantinePublisher unavailable() { - return Unavailable.INSTANCE; - } - - /** Holds the single "not configured" quarantine. */ - final class Unavailable { - - private static final KafkaQuarantinePublisher INSTANCE = (record, category, reason) -> false; - - private Unavailable() {} - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaReplayCapability.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaReplayCapability.java deleted file mode 100644 index 1418e7b0..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaReplayCapability.java +++ /dev/null @@ -1,82 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.error.MessagingCapabilityUnavailableException; -import dev.caskeleton.messaging.policy.DestinationProfile; -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; - -/** - * The Kafka replay capability, planning-first. - * - *

Planning is always available and never touches a broker. Executing a plan against an existing - * consumer group is refused unless the plan was built with an approval, because that operation - * rewinds a live consumer rather than reading alongside it. - * - *

A destination whose profile does not advertise replay is refused outright rather than silently - * producing an empty replay, which would look like "there was nothing to replay". - */ -public final class KafkaReplayCapability { - - private final KafkaReplayPlanner planner; - private final KafkaReplayRunner runner; - - /** - * Creates a replay capability. - * - * @param planner builds replay plans - * @param runner executes a plan against a broker - */ - public KafkaReplayCapability(KafkaReplayPlanner planner, KafkaReplayRunner runner) { - this.planner = Objects.requireNonNull(planner, "planner must not be null"); - this.runner = Objects.requireNonNull(runner, "runner must not be null"); - } - - /** - * Plans an isolated replay for a destination. - * - * @param profile the destination profile - * @param requestId a stable id used to name the isolated group - * @param from the replay start point - * @param to the replay end point, when bounded - * @return the plan - */ - public KafkaReplayPlan plan( - DestinationProfile profile, String requestId, Instant from, Optional to) { - Objects.requireNonNull(profile, "profile must not be null"); - String topic = - profile - .physical() - .topic() - .orElseThrow( - () -> - new MessagingCapabilityUnavailableException( - "KAFKA_TOPIC_MISSING", - "destination has no Kafka topic: " + profile.name().value())); - return planner.plan(topic, requestId, from, to); - } - - /** - * Executes a plan. - * - * @param plan the replay plan - * @return how many records were re-read - */ - public long execute(KafkaReplayPlan plan) { - Objects.requireNonNull(plan, "plan must not be null"); - return runner.run(plan); - } - - /** Executes a replay plan against a broker. */ - @FunctionalInterface - public interface KafkaReplayRunner { - - /** - * Runs a replay plan and returns how many records were re-read. - * - * @param plan the replay plan - * @return the record count - */ - long run(KafkaReplayPlan plan); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaReplayPlan.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaReplayPlan.java deleted file mode 100644 index 169b50f9..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaReplayPlan.java +++ /dev/null @@ -1,36 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; - -/** - * A validated, read-only plan for replaying a Kafka topic. - * - * @param topic the topic to replay - * @param consumerGroup the group the replay will run under - * @param isolatedGroup whether the group is a throwaway created for this replay - * @param fromTimestamp the replay start point - * @param toTimestamp the replay end point, when bounded - */ -public record KafkaReplayPlan( - String topic, - String consumerGroup, - boolean isolatedGroup, - Instant fromTimestamp, - Optional toTimestamp) { - - public KafkaReplayPlan { - Objects.requireNonNull(fromTimestamp, "fromTimestamp must not be null"); - Objects.requireNonNull(toTimestamp, "toTimestamp must not be null"); - if (topic == null || topic.isBlank()) { - throw new IllegalArgumentException("topic must not be blank"); - } - if (consumerGroup == null || consumerGroup.isBlank()) { - throw new IllegalArgumentException("consumerGroup must not be blank"); - } - if (toTimestamp.filter(end -> end.isBefore(fromTimestamp)).isPresent()) { - throw new IllegalArgumentException("replay window ends before it starts"); - } - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaReplayPlanner.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaReplayPlanner.java deleted file mode 100644 index 0a2dd9b3..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaReplayPlanner.java +++ /dev/null @@ -1,58 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; - -/** - * Plans a replay without ever touching a live consumer group. - * - *

Replay defaults to a fresh, isolated group. Re-reading a topic under the production group - * means resetting that group's committed offsets, which does not "replay" anything — it rewinds the - * live consumer and reprocesses everything in between. Making isolation the default turns that from - * an easy mistake into an explicit, named request. - */ -public final class KafkaReplayPlanner { - - private static final String ISOLATED_GROUP_PREFIX = "replay-"; - - /** - * Plans an isolated replay. - * - * @param topic the topic to replay - * @param requestId a stable id used to name the isolated group - * @param from the replay start point - * @param to the replay end point, when bounded - * @return the replay plan - */ - public KafkaReplayPlan plan(String topic, String requestId, Instant from, Optional to) { - Objects.requireNonNull(requestId, "requestId must not be null"); - return new KafkaReplayPlan(topic, ISOLATED_GROUP_PREFIX + requestId, true, from, to); - } - - /** - * Plans a replay against an existing production group. - * - *

Requires an approved destructive request, because this rewinds a live consumer rather than - * reading alongside it. - * - * @param topic the topic to replay - * @param consumerGroup the existing group - * @param from the replay start point - * @param to the replay end point, when bounded - * @param approvalTicket the approval reference for the destructive operation - * @return the replay plan - */ - public KafkaReplayPlan planAgainstExistingGroup( - String topic, - String consumerGroup, - Instant from, - Optional to, - String approvalTicket) { - if (approvalTicket == null || approvalTicket.isBlank()) { - throw new IllegalArgumentException( - "replaying an existing consumer group resets its offsets and requires an approval"); - } - return new KafkaReplayPlan(topic, consumerGroup, false, from, to); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaRetryExecutor.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaRetryExecutor.java deleted file mode 100644 index fd224d7c..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaRetryExecutor.java +++ /dev/null @@ -1,126 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.policy.DeadLetterOrchestrator; -import dev.caskeleton.messaging.policy.DeadLetterResult; -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.policy.RetryContext; -import dev.caskeleton.messaging.policy.RetryDecision; -import dev.caskeleton.messaging.policy.RetryDecisionEngine; -import dev.caskeleton.messaging.policy.SourceSettlement; -import dev.caskeleton.messaging.schema.EncodedMessage; -import java.time.Instant; -import java.util.Objects; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import org.apache.kafka.common.TopicPartition; - -/** - * Applies a retry decision to a Kafka delivery. - * - *

Every branch that moves a message elsewhere — a retry topic or the dead letter topic — settles - * the source only after that publish is confirmed. A pause-and-seek retry settles nothing at all, - * because the message is still where it was. - * - *

The result is that no path here can lose a message: either it stays in the source partition, - * or it exists in two places until the source is committed. - */ -public final class KafkaRetryExecutor { - - private final RetryDecisionEngine engine; - private final KafkaRetryTopicPublisher retryPublisher; - private final DeadLetterOrchestrator deadLetterOrchestrator; - private final KafkaPartitionRetryScheduler scheduler; - - /** - * Creates a retry executor. - * - * @param engine the retry decision engine - * @param retryPublisher publishes to the retry topic - * @param deadLetterOrchestrator publishes to the dead letter topic and settles the source - * @param scheduler tracks paused partitions - */ - public KafkaRetryExecutor( - RetryDecisionEngine engine, - KafkaRetryTopicPublisher retryPublisher, - DeadLetterOrchestrator deadLetterOrchestrator, - KafkaPartitionRetryScheduler scheduler) { - this.engine = Objects.requireNonNull(engine, "engine must not be null"); - this.retryPublisher = Objects.requireNonNull(retryPublisher, "retryPublisher must not be null"); - this.deadLetterOrchestrator = - Objects.requireNonNull(deadLetterOrchestrator, "deadLetterOrchestrator must not be null"); - this.scheduler = Objects.requireNonNull(scheduler, "scheduler must not be null"); - } - - /** - * Executes the decision for one failed delivery. - * - * @param profile the source destination profile - * @param delivery the failed delivery - * @param failure the sanitized failure - * @param context the retry decision inputs - * @param partition the Kafka partition the record came from - * @param offset the record offset - * @param settlement the source settlement callback - * @param now the current instant - * @return a stage completing with what was done - */ - public CompletionStage execute( - DestinationProfile profile, - MessageDelivery delivery, - FailureDescriptor failure, - RetryContext context, - TopicPartition partition, - long offset, - SourceSettlement settlement, - Instant now) { - - RetryDecision decision = engine.decide(context); - - if (decision instanceof RetryDecision.PauseAndRetry pause) { - scheduler.pauseUntil(partition, offset, pause.delay(), now); - return CompletableFuture.completedFuture( - new KafkaRetryOutcome(KafkaRetryOutcome.Action.PAUSED_AND_SEEKING, false)); - } - if (decision instanceof RetryDecision.RetryInline) { - return CompletableFuture.completedFuture( - new KafkaRetryOutcome(KafkaRetryOutcome.Action.RETRIED_INLINE, false)); - } - if (decision instanceof RetryDecision.PublishToRetryDestination publish) { - return retryPublisher - .publish(publish.destination(), delivery, failure, now) - .thenCompose( - result -> { - if (result.completion() != PublishCompletion.CONFIRMED) { - return CompletableFuture.completedFuture( - new KafkaRetryOutcome(KafkaRetryOutcome.Action.RETRY_PUBLISH_FAILED, false)); - } - return settlement - .settle() - .thenApply( - ignored -> - new KafkaRetryOutcome( - KafkaRetryOutcome.Action.PUBLISHED_TO_RETRY_TOPIC, true)); - }); - } - if (decision instanceof RetryDecision.Reject) { - return settlement - .settle() - .thenApply(ignored -> new KafkaRetryOutcome(KafkaRetryOutcome.Action.REJECTED, true)); - } - - return deadLetterOrchestrator - .deadLetter(profile, delivery, failure, settlement) - .thenApply(KafkaRetryExecutor::toOutcome); - } - - private static KafkaRetryOutcome toOutcome(DeadLetterResult result) { - return new KafkaRetryOutcome( - result.sourceSettled() - ? KafkaRetryOutcome.Action.DEAD_LETTERED - : KafkaRetryOutcome.Action.DEAD_LETTER_PUBLISH_FAILED, - result.sourceSettled()); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaRetryMetadataMapper.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaRetryMetadataMapper.java deleted file mode 100644 index f04c616e..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaRetryMetadataMapper.java +++ /dev/null @@ -1,93 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -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.time.Instant; -import java.util.LinkedHashMap; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; - -/** - * Carries retry bookkeeping across a retry-topic hop. - * - *

A retry topic is a separate log, so the attempt counter cannot come from the broker's delivery - * count — it has to travel with the message. The logical {@code messageId} is deliberately not - * touched: a retried message is the same message, and re-minting its identity would defeat both - * Inbox deduplication and the operator's ability to trace it. - */ -public final class KafkaRetryMetadataMapper { - - /** - * Stamps the next attempt onto an envelope bound for a retry topic. - * - * @param source the envelope as delivered - * @param nextAttempt the attempt number the retry will be - * @param failure the sanitized failure that caused the retry - * @param failedAt when the failure happened - * @return an envelope with identical identity and updated retry headers - */ - public MessageEnvelope stamp( - MessageEnvelope source, - int nextAttempt, - FailureDescriptor failure, - Instant failedAt) { - Objects.requireNonNull(source, "source must not be null"); - Objects.requireNonNull(failure, "failure must not be null"); - Objects.requireNonNull(failedAt, "failedAt must not be null"); - if (nextAttempt < 2) { - throw new IllegalArgumentException("a retry is at least the second attempt"); - } - - Map headers = new LinkedHashMap<>(source.headers().asMap()); - headers.put( - new HeaderName(ReservedHeaders.RETRY_ATTEMPT), - new HeaderValue(Integer.toString(nextAttempt))); - headers.put( - new HeaderName(ReservedHeaders.FAILURE_CATEGORY), - new HeaderValue(failure.category().name())); - headers.put(new HeaderName(ReservedHeaders.FAILURE_CODE), new HeaderValue(failure.code())); - headers.putIfAbsent( - new HeaderName(ReservedHeaders.FIRST_FAILURE_AT), new HeaderValue(failedAt.toString())); - headers.put( - new HeaderName(ReservedHeaders.LAST_FAILURE_AT), new HeaderValue(failedAt.toString())); - - return source.withHeaders(MessageHeaders.platform(headers)); - } - - /** - * Reads the attempt number a retried message carries. - * - * @param envelope the delivered envelope - * @return the attempt, defaulting to one when no retry header is present - */ - public int attemptOf(MessageEnvelope envelope) { - Optional value = envelope.headers().find(ReservedHeaders.RETRY_ATTEMPT); - if (value.isEmpty()) { - return 1; - } - try { - int attempt = Integer.parseInt(value.orElseThrow().value()); - if (attempt < 1) { - throw new NumberFormatException("attempt " + attempt); - } - return attempt; - } catch (NumberFormatException malformed) { - // Fail closed rather than resetting to 1. - // - // Returning 1 for an unreadable header restarts the retry budget on every redelivery, so a - // message that should have been dead-lettered after N attempts is retried forever — and the - // header is caller-influenced, which makes "unreadable" a way to defeat the cap rather than - // an accident. - 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"); - } - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaRetryOutcome.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaRetryOutcome.java deleted file mode 100644 index 81007e41..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaRetryOutcome.java +++ /dev/null @@ -1,40 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import java.util.Objects; - -/** - * What the retry executor actually did with a failed delivery. - * - * @param action the branch taken - * @param sourceSettled whether the source offset may advance - */ -public record KafkaRetryOutcome(Action action, boolean sourceSettled) { - - /** The retry branches a Kafka delivery can take. */ - public enum Action { - /** The partition was paused and will be re-read from the same offset. */ - PAUSED_AND_SEEKING, - - /** The handler will be re-invoked without releasing the delivery. */ - RETRIED_INLINE, - - /** The message was re-published to the retry topic and the source settled. */ - PUBLISHED_TO_RETRY_TOPIC, - - /** The retry publish did not confirm, so the source stays unsettled. */ - RETRY_PUBLISH_FAILED, - - /** The message was dead lettered and the source settled. */ - DEAD_LETTERED, - - /** The dead letter publish did not confirm, so the source stays unsettled. */ - DEAD_LETTER_PUBLISH_FAILED, - - /** The message was discarded under an at-most-once profile. */ - REJECTED - } - - public KafkaRetryOutcome { - Objects.requireNonNull(action, "action must not be null"); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaRetryTopicPublisher.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaRetryTopicPublisher.java deleted file mode 100644 index d3e7ffb3..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaRetryTopicPublisher.java +++ /dev/null @@ -1,75 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.schema.EncodedMessage; -import java.time.Instant; -import java.util.Objects; -import java.util.concurrent.CompletionStage; - -/** - * Re-publishes a failed message to its retry topic. - * - *

Available only where the profile allows reordering. A retry topic is a different log with its - * own offsets, so a message that takes this path rejoins the stream behind messages that were - * originally after it — which is why an ordered destination is routed to pause-and-seek instead. - */ -public final class KafkaRetryTopicPublisher { - - private final MessagePublisher publisher; - private final KafkaRetryMetadataMapper metadataMapper; - - /** - * Creates a retry topic publisher. - * - * @param publisher the platform publisher - */ - public KafkaRetryTopicPublisher(MessagePublisher publisher) { - this(publisher, new KafkaRetryMetadataMapper()); - } - - /** - * Creates a retry topic publisher with an explicit metadata mapper. - * - * @param publisher the platform publisher - * @param metadataMapper stamps retry bookkeeping onto the envelope - */ - public KafkaRetryTopicPublisher( - MessagePublisher publisher, KafkaRetryMetadataMapper metadataMapper) { - this.publisher = Objects.requireNonNull(publisher, "publisher must not be null"); - this.metadataMapper = Objects.requireNonNull(metadataMapper, "metadataMapper must not be null"); - } - - /** - * Publishes a failed delivery to the retry destination. - * - * @param retryDestination the retry destination - * @param delivery the failed delivery - * @param failure the sanitized failure - * @param failedAt when the failure happened - * @return a stage completing with the publish outcome - */ - public CompletionStage publish( - DestinationName retryDestination, - MessageDelivery delivery, - FailureDescriptor failure, - Instant failedAt) { - Objects.requireNonNull(retryDestination, "retryDestination must not be null"); - Objects.requireNonNull(delivery, "delivery must not be null"); - - int nextAttempt = delivery.metadata().deliveryAttempt() + 1; - MessageDestination destination = - new MessageDestination<>( - retryDestination, delivery.message().messageType(), EncodedMessage.class); - - return publisher.publish( - destination, - metadataMapper.stamp(delivery.message(), nextAttempt, failure, failedAt), - PublishOptions.defaults()); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaSecurityConfigurer.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaSecurityConfigurer.java deleted file mode 100644 index 391ece38..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaSecurityConfigurer.java +++ /dev/null @@ -1,214 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -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.LinkedHashMap; -import java.util.List; -import java.util.Map; -import java.util.Objects; - -/** - * Builds the Kafka client security properties from a validated security profile. - * - *

Nothing here reads an environment variable or a property file. Credentials resolve through - * {@link CredentialRuntimeRegistry}. - * - *

SASL user names and passwords are not written into the configuration at all. The JAAS entry - * names the login module and nothing else, and {@link KafkaCredentialCallbackHandler} answers the - * user name and password from the registry each time a connection authenticates — so a credential - * the store rotates (one whose provider reports an expiry) reaches the next connection without a - * restart, and no immutable {@code String} holds the password for the client's lifetime. - * - *

Key and trust store passwords are the exception: Kafka reads them once, when the client builds - * its SSL context, and accepts them only as configuration values. They are resolved here and live - * as long as the client does; rotating one means rebuilding the client. - */ -public final class KafkaSecurityConfigurer { - - /** Kafka's key for the SASL mechanism. */ - public static final String SASL_MECHANISM = "sasl.mechanism"; - - /** Kafka's key for the security protocol. */ - public static final String SECURITY_PROTOCOL = "security.protocol"; - - /** Kafka's key for the JAAS configuration. */ - public static final String SASL_JAAS_CONFIG = "sasl.jaas.config"; - - /** Kafka's key for the SASL client callback handler class. */ - public static final String SASL_CLIENT_CALLBACK_HANDLER = "sasl.client.callback.handler.class"; - - /** Kafka's key for the endpoint identification algorithm. */ - public static final String ENDPOINT_IDENTIFICATION = "ssl.endpoint.identification.algorithm"; - - /** Kafka's key for the enabled TLS protocol versions. */ - public static final String ENABLED_PROTOCOLS = "ssl.enabled.protocols"; - - 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 KafkaSecurityConfigurer(CredentialRuntimeRegistry credentials, BrokerTlsPolicy tlsPolicy) { - this.credentials = Objects.requireNonNull(credentials, "credentials must not be null"); - this.tlsPolicy = Objects.requireNonNull(tlsPolicy, "tlsPolicy must not be null"); - } - - /** - * Builds the client properties for one role's credential. - * - * @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 Kafka client properties - */ - public Map 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"); - - // Validate before resolving. A profile that will be refused should not cause a credential to be - // fetched and briefly held in memory for nothing. - tlsPolicy.validate(profile, enabledProtocols); - if (!profile.tlsEnabled()) { - requireNoTlsMaterial(profile, credential); - } - - Map properties = new LinkedHashMap<>(); - properties.put(SECURITY_PROTOCOL, securityProtocol(profile, credential)); - - if (profile.tlsEnabled()) { - properties.put(ENABLED_PROTOCOLS, String.join(",", enabledProtocols)); - // Kafka disables hostname verification by setting this to the empty string. The policy has - // already refused that combination, so the value here is always the verifying one. - properties.put(ENDPOINT_IDENTIFICATION, "https"); - profile - .trustStore() - .ifPresent( - store -> { - properties.put("ssl.truststore.location", store.location()); - properties.put("ssl.truststore.type", store.type()); - store - .passwordCredentialId() - .ifPresent(id -> properties.put("ssl.truststore.password", secret(id, now))); - }); - } - - switch (credential) { - case BrokerCredentialProfile.SaslScram scram -> - properties.putAll( - sasl( - "SCRAM-SHA-512", - "org.apache.kafka.common.security.scram.ScramLoginModule", - scram.credentialId(), - now)); - case BrokerCredentialProfile.OAuth2 oauth -> { - // Refused rather than half-configured. Setting the mechanism name without a callback - // handler produces a client that authenticates with nothing and fails at connect time, - // which is later and harder to attribute than failing here. - throw new MessagingConfigurationException( - "SASL_OAUTH_NOT_CONFIGURED", - "OAuth bearer needs a login callback handler and a token endpoint; this platform" - + " configures the mechanism name only, so the profile is refused rather than" - + " producing a client that cannot authenticate: " - + oauth.credentialId()); - } - case BrokerCredentialProfile.MutualTls tls -> { - String password = secret(tls.credentialId(), now); - properties.put("ssl.keystore.location", tls.keyStoreLocation()); - properties.put("ssl.keystore.type", tls.keyStoreType()); - properties.put("ssl.keystore.password", password); - properties.put("ssl.key.password", password); - } - case BrokerCredentialProfile.UsernamePassword plain -> - properties.putAll( - sasl( - "PLAIN", - "org.apache.kafka.common.security.plain.PlainLoginModule", - plain.credentialId(), - now)); - case BrokerCredentialProfile.Nkey ignored -> - throw new IllegalArgumentException( - "NKey credentials are a NATS concept, not a Kafka one"); - } - return Map.copyOf(properties); - } - - /** - * The SASL properties: a JAAS entry naming only the login module, and the handler that answers. - * - *

The credential is resolved once here so that a provider with no user name, or no secret, - * fails startup rather than the first connection. - */ - private Map sasl( - String mechanism, String loginModule, String credentialId, Instant now) { - if (credentials.resolve(credentialId, now).username().isEmpty()) { - throw usernameMissing(credentialId); - } - return Map.of( - SASL_MECHANISM, - mechanism, - SASL_JAAS_CONFIG, - loginModule + " required;", - SASL_CLIENT_CALLBACK_HANDLER, - KafkaCredentialCallbackHandler.class, - KafkaCredentialCallbackHandler.REGISTRY, - credentials, - KafkaCredentialCallbackHandler.CREDENTIAL_ID, - credentialId); - } - - private String secret(String credentialId, Instant now) { - CredentialRuntime resolved = credentials.resolve(credentialId, now); - return new String(resolved.material()); - } - - /** TLS material on a plaintext connection is a configuration that cannot mean what it says. */ - private static void requireNoTlsMaterial( - BrokerSecurityProfile profile, BrokerCredentialProfile credential) { - if (profile.trustStore().isPresent()) { - throw new MessagingConfigurationException( - "TRUST_STORE_REQUIRES_TLS", - "broker %s configures a trust store but not TLS; nothing would ever read it" - .formatted(profile.broker())); - } - if (credential instanceof BrokerCredentialProfile.MutualTls) { - throw new MessagingConfigurationException( - "MUTUAL_TLS_REQUIRES_TLS", - "broker %s authenticates with a client certificate but does not enable TLS, and a" - .formatted(profile.broker()) - + " certificate is only presented inside a TLS handshake"); - } - } - - static MessagingConfigurationException usernameMissing(String credentialId) { - return new MessagingConfigurationException( - "SASL_USERNAME_MISSING", - "credential " - + credentialId - + " authenticates with a user name and password, and CredentialProvider.username" - + " returned none; the credential id is a reference, not the broker's user name"); - } - - private static String securityProtocol( - BrokerSecurityProfile profile, BrokerCredentialProfile credential) { - boolean sasl = !(credential instanceof BrokerCredentialProfile.MutualTls); - if (profile.tlsEnabled()) { - return sasl ? "SASL_SSL" : "SSL"; - } - return sasl ? "SASL_PLAINTEXT" : "PLAINTEXT"; - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaSettlementCommand.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaSettlementCommand.java deleted file mode 100644 index 26c50a46..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaSettlementCommand.java +++ /dev/null @@ -1,50 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import java.util.Objects; -import org.apache.kafka.common.TopicPartition; - -/** - * One settlement instruction queued for the poll thread. - * - *

Handler workers never call the Kafka consumer. {@code KafkaConsumer} is explicitly not - * thread-safe, so a worker that committed or paused directly would corrupt the client's internal - * state under concurrency. Workers enqueue an instruction instead and the single poll thread - * applies it. - * - * @param partition the partition the instruction applies to - * @param offset the record offset - * @param kind what to do - */ -public record KafkaSettlementCommand(TopicPartition partition, long offset, Kind kind, long epoch) { - - /** - * A command without an epoch, for callers that predate assignment fencing. - * - *

Epoch 0 never matches a live assignment, so such a command is always stale. That is - * deliberate: a settlement that cannot say which assignment it belongs to cannot be shown to - * belong to the current one. - */ - public KafkaSettlementCommand(TopicPartition partition, long offset, Kind kind) { - this(partition, offset, kind, 0L); - } - - /** What a queued settlement instruction asks the poll thread to do. */ - public enum Kind { - /** The handler succeeded; the offset may advance the commit watermark. */ - COMPLETE, - - /** Pause the partition and re-deliver from this offset after the retry delay. */ - PAUSE_AND_SEEK, - - /** The message was parked; the offset may advance the commit watermark. */ - PARKED - } - - public KafkaSettlementCommand { - Objects.requireNonNull(partition, "partition must not be null"); - Objects.requireNonNull(kind, "kind must not be null"); - if (offset < 0) { - throw new IllegalArgumentException("offset must not be negative"); - } - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaSettlementQueue.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaSettlementQueue.java deleted file mode 100644 index f69eca41..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaSettlementQueue.java +++ /dev/null @@ -1,52 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import java.util.ArrayList; -import java.util.List; -import java.util.Objects; -import java.util.Queue; -import java.util.concurrent.ConcurrentLinkedQueue; - -/** - * The hand-off between handler workers and the poll thread. - * - *

Multi-producer, single-consumer by design: any worker may enqueue, only the poll thread - * drains. That is what keeps every {@code KafkaConsumer} call on one thread without any worker - * having to hold a lock. - */ -public final class KafkaSettlementQueue { - - private final Queue commands = new ConcurrentLinkedQueue<>(); - - /** - * Enqueues a settlement instruction from a handler worker. - * - * @param command the instruction - */ - public void enqueue(KafkaSettlementCommand command) { - commands.add(Objects.requireNonNull(command, "command must not be null")); - } - - /** - * Drains every queued instruction. Called only by the poll thread. - * - * @return the instructions in enqueue order - */ - public List drain() { - List drained = new ArrayList<>(); - KafkaSettlementCommand command = commands.poll(); - while (command != null) { - drained.add(command); - command = commands.poll(); - } - return List.copyOf(drained); - } - - /** - * Returns how many instructions are waiting. - * - * @return the queue depth - */ - public int size() { - return commands.size(); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTransactionProfileValidator.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTransactionProfileValidator.java deleted file mode 100644 index 46c8bd17..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTransactionProfileValidator.java +++ /dev/null @@ -1,52 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee; -import dev.caskeleton.messaging.policy.DestinationProfile; -import java.util.Objects; - -/** - * Guards the conditions a Kafka transaction actually requires. - * - *

The last rule is the important one. A destination that declares {@code INBOX_TRANSACTIONAL} is - * telling the platform its side effect lives in a database, and a Kafka transaction cannot span - * that. Allowing both to be configured together would let a team read "transactional" twice and - * conclude the whole path is atomic when the two halves can still diverge. - */ -public final class KafkaTransactionProfileValidator { - - /** - * Validates a destination profile against the Kafka transaction capability. - * - * @param profile the destination profile - * @param transactionalIdPrefix the configured transactional id prefix - * @param brokerProfile the Kafka client profile - * @throws IllegalArgumentException when the combination cannot deliver what it claims - */ - public void validate( - DestinationProfile profile, String transactionalIdPrefix, KafkaBrokerProfile brokerProfile) { - Objects.requireNonNull(profile, "profile must not be null"); - Objects.requireNonNull(brokerProfile, "brokerProfile must not be null"); - - if (transactionalIdPrefix == null || transactionalIdPrefix.isBlank()) { - throw new IllegalArgumentException( - "a Kafka transaction requires a transactional id prefix: " + profile.name().value()); - } - if (!brokerProfile.enableIdempotence()) { - throw new IllegalArgumentException( - "a Kafka transaction requires an idempotent producer: " + profile.name().value()); - } - if (!"all".equals(brokerProfile.acks())) { - throw new IllegalArgumentException( - "a Kafka transaction requires acks=all: " + profile.name().value()); - } - if (brokerProfile.enableAutoCommit()) { - throw new IllegalArgumentException( - "a Kafka transaction requires manual offset commit: " + profile.name().value()); - } - if (profile.externalSideEffectGuarantee() == ExternalSideEffectGuarantee.INBOX_TRANSACTIONAL) { - throw new IllegalArgumentException( - "a Kafka transaction does not cover a database side effect; use the Inbox alone: " - + profile.name().value()); - } - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTransactionalDelivery.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTransactionalDelivery.java deleted file mode 100644 index 3132225d..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTransactionalDelivery.java +++ /dev/null @@ -1,22 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.schema.EncodedMessage; -import java.util.List; -import java.util.Objects; - -/** - * The input and outputs of one read-process-write transaction. - * - * @param input the message being processed - * @param outputs the messages to produce inside the same transaction - */ -public record KafkaTransactionalDelivery( - MessageEnvelope input, List outputs) { - - public KafkaTransactionalDelivery { - Objects.requireNonNull(input, "input must not be null"); - Objects.requireNonNull(outputs, "outputs must not be null"); - outputs = List.copyOf(outputs); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTransactionalOutput.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTransactionalOutput.java deleted file mode 100644 index fc4b17d3..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTransactionalOutput.java +++ /dev/null @@ -1,21 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.schema.EncodedMessage; -import java.util.Objects; - -/** - * One message produced inside a Kafka transaction. - * - * @param destination the logical destination to produce to - * @param envelope the encoded envelope - */ -public record KafkaTransactionalOutput( - DestinationName destination, MessageEnvelope envelope) { - - public KafkaTransactionalOutput { - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(envelope, "envelope must not be null"); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTransactionalProcessor.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTransactionalProcessor.java deleted file mode 100644 index d071e532..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTransactionalProcessor.java +++ /dev/null @@ -1,29 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import java.util.concurrent.CompletionStage; -import java.util.function.Function; - -/** - * The M3 Kafka read-process-write transaction capability. - * - *

The guarantee is precisely scoped: the produced records and the input offset commit atomically - * within Kafka. It says nothing about a database write, an HTTP call, or a file, and the - * platform never presents it as exactly-once end to end. A handler that also writes to PostgreSQL - * inside this block still needs an Inbox, because the two commits are independent. - * - *

Exposed as a typed capability rather than a raw producer so that the transactional boundary - * cannot be opened without also being closed. - */ -public interface KafkaTransactionalProcessor { - - /** - * Runs one read-process-write transaction. - * - * @param the value the handler returns - * @param delivery the input message and the outputs to produce - * @param handler the processing step, run inside the transaction - * @return a stage completing when the transaction has committed or aborted - */ - CompletionStage processInTransaction( - KafkaTransactionalDelivery delivery, Function handler); -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTransactionalPublisher.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTransactionalPublisher.java deleted file mode 100644 index 18ff368b..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTransactionalPublisher.java +++ /dev/null @@ -1,178 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.policy.DestinationProfile; -import java.util.Map; -import java.util.Objects; -import java.util.function.Supplier; -import org.apache.kafka.clients.consumer.ConsumerGroupMetadata; -import org.apache.kafka.clients.consumer.OffsetAndMetadata; -import org.apache.kafka.clients.producer.Producer; -import org.apache.kafka.common.TopicPartition; - -/** - * Produces records and commits input offsets inside one Kafka transaction. - * - *

The offsets are sent to the transaction rather than committed by the consumer. That is what - * makes read-process-write atomic within Kafka: either the outputs and the input offset - * both become visible to a {@code read_committed} reader, or neither does. - * - *

It does not extend to a database or an HTTP call. A handler that also writes to PostgreSQL - * inside this block still needs an Inbox, and the profile validator refuses the combination that - * would suggest otherwise. - */ -public final class KafkaTransactionalPublisher { - - private final Producer producer; - private final KafkaPublishMapper mapper; - private final Supplier groupMetadata; - - /** - * Creates a transactional publisher. - * - *

The group metadata is supplied lazily rather than captured once. It carries the consumer's - * current generation and member id, and sending stale metadata after a rebalance is what lets a - * fenced consumer commit offsets it no longer owns. - * - * @param producer a producer configured with a transactional id - * @param groupMetadata supplies the consuming group's current metadata - */ - public KafkaTransactionalPublisher( - Producer producer, Supplier groupMetadata) { - this.producer = Objects.requireNonNull(producer, "producer must not be null"); - this.groupMetadata = Objects.requireNonNull(groupMetadata, "groupMetadata must not be null"); - this.mapper = new KafkaPublishMapper(); - } - - /** - * Creates a transactional publisher for a group with no live consumer metadata. - * - *

Only appropriate where the offsets being committed are not owned by a rebalancing consumer, - * such as a single-instance replay job. - * - * @param producer a producer configured with a transactional id - * @param consumerGroup the group whose offsets are committed in the transaction - * @return the publisher - */ - public static KafkaTransactionalPublisher forStaticGroup( - Producer producer, String consumerGroup) { - if (consumerGroup == null || consumerGroup.isBlank()) { - throw new IllegalArgumentException("consumerGroup must not be blank"); - } - return new KafkaTransactionalPublisher( - producer, () -> new ConsumerGroupMetadata(consumerGroup)); - } - - /** Initialises the transactional producer. Must be called once before any transaction. */ - public void initialise() { - producer.initTransactions(); - } - - /** - * Sends outputs and the input offset in one transaction. - * - *

Any failure aborts. Aborting rather than leaving the transaction open is what lets the next - * producer instance fence this one instead of waiting for a timeout. - * - * @param delivery the input and the outputs to produce - * @param profiles the destination profile for each output destination - * @param inputOffsets the input offsets to commit with the outputs - */ - /** - * Begins a transaction, runs the caller's work inside it, then sends outputs and offsets. - * - *

The processor used to run the handler and only afterwards hand the delivery here — so {@code - * beginTransaction} happened *after* the handler had already finished. Anything the handler - * produced itself, and any external effect it triggered, was therefore outside the transaction - * the documentation promised it was in: a handler that succeeded and a commit that then failed - * left the handler's work applied with its input offsets unsent. - * - *

The body runs between begin and commit, and every failure path aborts. - * - * @param body the handler, executed inside the transaction - * @return whatever the body produced - */ - public T inTransaction( - KafkaTransactionalDelivery delivery, - Map profiles, - Map inputOffsets, - java.util.function.Supplier body) { - Objects.requireNonNull(delivery, "delivery must not be null"); - Objects.requireNonNull(profiles, "profiles must not be null"); - Objects.requireNonNull(inputOffsets, "inputOffsets must not be null"); - Objects.requireNonNull(body, "body must not be null"); - - producer.beginTransaction(); - try { - T value = body.get(); - sendOutputsAndOffsets(delivery, profiles, inputOffsets); - producer.commitTransaction(); - return value; - } catch (RuntimeException failure) { - // Handler failure, send failure, offset failure and commit failure all land here. Under - // read_committed a consumer sees none of the outputs, and the input offsets are unsent, so - // the source is redelivered. - producer.abortTransaction(); - throw failure; - } - } - - @SuppressWarnings("FutureReturnValueIgnored") - private void sendOutputsAndOffsets( - KafkaTransactionalDelivery delivery, - Map profiles, - Map inputOffsets) { - for (KafkaTransactionalOutput output : delivery.outputs()) { - DestinationProfile profile = profiles.get(output.destination().value()); - if (profile == null) { - throw new MessagingConfigurationException( - "DESTINATION_NOT_REGISTERED", - "no destination profile is registered for " + output.destination().value()); - } - producer.send( - mapper.toRecord( - new dev.caskeleton.messaging.transport.TransportPublishRequest( - profile, - output.envelope(), - dev.caskeleton.messaging.api.publish.PublishOptions.defaults()))); - } - producer.sendOffsetsToTransaction(inputOffsets, groupMetadata.get()); - } - - @SuppressWarnings("FutureReturnValueIgnored") - public void sendInTransaction( - KafkaTransactionalDelivery delivery, - Map profiles, - Map inputOffsets) { - // The per-send Futures are deliberately not inspected. Inside a transaction the commit is the - // barrier: any send failure surfaces from commitTransaction, and a send that failed leaves the - // producer in an error state that abortTransaction resolves. Waiting on each Future here would - // serialise the batch for no additional safety. - Objects.requireNonNull(delivery, "delivery must not be null"); - Objects.requireNonNull(profiles, "profiles must not be null"); - Objects.requireNonNull(inputOffsets, "inputOffsets must not be null"); - - producer.beginTransaction(); - try { - for (KafkaTransactionalOutput output : delivery.outputs()) { - DestinationProfile profile = profiles.get(output.destination().value()); - if (profile == null) { - throw new MessagingConfigurationException( - "DESTINATION_NOT_REGISTERED", - "no destination profile is registered for " + output.destination().value()); - } - producer.send( - mapper.toRecord( - new dev.caskeleton.messaging.transport.TransportPublishRequest( - profile, - output.envelope(), - dev.caskeleton.messaging.api.publish.PublishOptions.defaults()))); - } - producer.sendOffsetsToTransaction(inputOffsets, groupMetadata.get()); - producer.commitTransaction(); - } catch (RuntimeException exception) { - producer.abortTransaction(); - throw exception; - } - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/PartitionOffsetTracker.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/PartitionOffsetTracker.java deleted file mode 100644 index 3c04e5dd..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/PartitionOffsetTracker.java +++ /dev/null @@ -1,48 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import java.util.Optional; -import java.util.OptionalLong; -import org.apache.kafka.common.TopicPartition; - -/** Tracks which delivered offsets have finished so the poll thread knows what is safe to commit. */ -public interface PartitionOffsetTracker { - - /** - * Records that an offset was handed to a handler. - * - * @param partition the partition - * @param offset the record offset - */ - void delivered(TopicPartition partition, long offset); - - /** - * Records that an offset finished handling. - * - * @param partition the partition - * @param offset the record offset - */ - void completed(TopicPartition partition, long offset); - - /** - * Returns the highest offset whose predecessors have all completed. - * - * @param partition the partition - * @return the highest contiguous completed offset, when one exists - */ - Optional highestContiguousCompleted(TopicPartition partition); - - /** - * Returns the offset to commit, which is one past the highest contiguous completed offset. - * - * @param partition the partition - * @return the commit offset, when one exists - */ - OptionalLong commitOffset(TopicPartition partition); - - /** - * Drops all state for a partition, as on revocation. - * - * @param partition the partition - */ - void forget(TopicPartition partition); -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/PartitionWorkCoordinator.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/PartitionWorkCoordinator.java deleted file mode 100644 index 8713780c..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/PartitionWorkCoordinator.java +++ /dev/null @@ -1,128 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import java.util.LinkedHashSet; -import java.util.Map; -import java.util.Objects; -import java.util.Set; -import java.util.concurrent.ConcurrentHashMap; -import java.util.concurrent.atomic.AtomicInteger; -import org.apache.kafka.common.TopicPartition; - -/** - * Enforces the in-flight ceiling for each partition and tracks which partitions are paused. - * - *

Concurrency is per partition, not per consumer. On an ordered destination the ceiling is one, - * which is the only setting that actually preserves order: two handlers running against the same - * partition can finish in either sequence no matter what the broker delivered. - */ -public final class PartitionWorkCoordinator { - - private final int maxInFlightPerPartition; - private final Map inFlight = new ConcurrentHashMap<>(); - private final Set paused = ConcurrentHashMap.newKeySet(); - - /** - * Creates a coordinator with an explicit ceiling. - * - * @param maxInFlightPerPartition how many deliveries may run at once per partition - */ - public PartitionWorkCoordinator(int maxInFlightPerPartition) { - if (maxInFlightPerPartition < 1) { - throw new IllegalArgumentException("maxInFlightPerPartition must be at least 1"); - } - this.maxInFlightPerPartition = maxInFlightPerPartition; - } - - /** - * Tries to reserve a slot for one delivery. - * - * @param partition the partition - * @return true when the delivery may start - */ - public boolean tryAcquire(TopicPartition partition) { - Objects.requireNonNull(partition, "partition must not be null"); - if (paused.contains(partition)) { - return false; - } - AtomicInteger counter = inFlight.computeIfAbsent(partition, key -> new AtomicInteger()); - while (true) { - int current = counter.get(); - if (current >= maxInFlightPerPartition) { - return false; - } - if (counter.compareAndSet(current, current + 1)) { - return true; - } - } - } - - /** - * Releases a slot after a delivery finishes. - * - * @param partition the partition - */ - public void release(TopicPartition partition) { - AtomicInteger counter = inFlight.get(partition); - if (counter != null && counter.get() > 0) { - counter.decrementAndGet(); - } - } - - /** - * Pauses a partition. - * - * @param partition the partition - */ - public void pause(TopicPartition partition) { - paused.add(partition); - } - - /** - * Resumes a partition. - * - * @param partition the partition - */ - public void resume(TopicPartition partition) { - paused.remove(partition); - } - - /** - * Reports whether a partition is paused. - * - * @param partition the partition - * @return true when paused - */ - public boolean isPaused(TopicPartition partition) { - return paused.contains(partition); - } - - /** - * Returns the currently paused partitions. - * - * @return an immutable snapshot - */ - public Set pausedPartitions() { - return Set.copyOf(new LinkedHashSet<>(paused)); - } - - /** - * Drops all state for a partition, as on revocation. - * - * @param partition the partition - */ - public void forget(TopicPartition partition) { - inFlight.remove(partition); - paused.remove(partition); - } - - /** - * Returns the in-flight count for a partition. - * - * @param partition the partition - * @return how many deliveries are running - */ - public int inFlight(TopicPartition partition) { - AtomicInteger counter = inFlight.get(partition); - return counter == null ? 0 : counter.get(); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/SpringKafkaTransactionalProcessor.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/SpringKafkaTransactionalProcessor.java deleted file mode 100644 index bdd6d3d0..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/SpringKafkaTransactionalProcessor.java +++ /dev/null @@ -1,68 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.policy.DestinationProfile; -import java.util.Map; -import java.util.Objects; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import java.util.function.Function; -import org.apache.kafka.clients.consumer.OffsetAndMetadata; -import org.apache.kafka.common.TopicPartition; - -/** - * The M3 Kafka transaction capability, backed by a transactional producer. - * - *

The handler runs inside the transaction and its outputs are produced before the input - * offset is sent. If the handler throws, the transaction aborts and neither the outputs nor the - * offset become visible to a {@code read_committed} reader, so the input is redelivered and - * reprocessed cleanly. - * - *

The scope is Kafka only, and the profile validator refuses to pair this with a destination - * that declares {@code INBOX_TRANSACTIONAL}. Reading "transactional" twice and concluding the whole - * path is atomic is exactly the mistake this capability must not enable. - */ -public final class SpringKafkaTransactionalProcessor implements KafkaTransactionalProcessor { - - private final KafkaTransactionalPublisher publisher; - private final Map profiles; - private final Function> - inputOffsets; - - /** - * Creates a transactional processor. - * - * @param publisher the transactional publisher - * @param profiles the destination profile for each output destination - * @param inputOffsets resolves the input offsets to commit with the outputs - */ - public SpringKafkaTransactionalProcessor( - KafkaTransactionalPublisher publisher, - Map profiles, - Function> inputOffsets) { - this.publisher = Objects.requireNonNull(publisher, "publisher must not be null"); - this.profiles = Map.copyOf(Objects.requireNonNull(profiles, "profiles must not be null")); - this.inputOffsets = Objects.requireNonNull(inputOffsets, "inputOffsets must not be null"); - } - - @Override - public CompletionStage processInTransaction( - KafkaTransactionalDelivery delivery, Function handler) { - Objects.requireNonNull(delivery, "delivery must not be null"); - Objects.requireNonNull(handler, "handler must not be null"); - - try { - // The handler runs between beginTransaction and commitTransaction. - // - // It used to run first, with the transaction opened afterwards inside sendInTransaction — so - // the contract this interface documents ("the callback executes inside the Kafka - // transaction") was false for every output the handler produced itself and every external - // effect it triggered. - T result = - publisher.inTransaction( - delivery, profiles, inputOffsets.apply(delivery), () -> handler.apply(delivery)); - return CompletableFuture.completedFuture(result); - } catch (RuntimeException exception) { - return CompletableFuture.failedFuture(exception); - } - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/ContiguousPartitionOffsetTrackerTest.java b/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/ContiguousPartitionOffsetTrackerTest.java deleted file mode 100644 index 699ae1be..00000000 --- a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/ContiguousPartitionOffsetTrackerTest.java +++ /dev/null @@ -1,94 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import static org.assertj.core.api.Assertions.assertThat; - -import java.util.OptionalLong; -import org.apache.kafka.common.TopicPartition; -import org.junit.jupiter.api.Test; - -class ContiguousPartitionOffsetTrackerTest { - - private static final TopicPartition PARTITION = new TopicPartition("orders", 0); - - private final ContiguousPartitionOffsetTracker tracker = new ContiguousPartitionOffsetTracker(); - - @Test - void commitsOnlyThroughHighestContiguousCompletedOffset() { - tracker.delivered(PARTITION, 10); - tracker.delivered(PARTITION, 11); - tracker.delivered(PARTITION, 12); - tracker.completed(PARTITION, 10); - tracker.completed(PARTITION, 12); - - assertThat(tracker.highestContiguousCompleted(PARTITION)).hasValue(10L); - } - - @Test - void theCommitOffsetIsOnePastTheContiguousWatermark() { - tracker.delivered(PARTITION, 10); - tracker.completed(PARTITION, 10); - - assertThat(tracker.commitOffset(PARTITION)).isEqualTo(OptionalLong.of(11)); - } - - @Test - void aGapClosingLaterAdvancesTheWatermarkPastIt() { - tracker.delivered(PARTITION, 10); - tracker.delivered(PARTITION, 11); - tracker.delivered(PARTITION, 12); - tracker.completed(PARTITION, 10); - tracker.completed(PARTITION, 12); - - tracker.completed(PARTITION, 11); - - assertThat(tracker.highestContiguousCompleted(PARTITION)).hasValue(12L); - } - - @Test - void nothingIsCommittableUntilTheLowestDeliveredOffsetCompletes() { - tracker.delivered(PARTITION, 10); - tracker.delivered(PARTITION, 11); - tracker.completed(PARTITION, 11); - - assertThat(tracker.highestContiguousCompleted(PARTITION)).isEmpty(); - assertThat(tracker.commitOffset(PARTITION)).isEmpty(); - } - - @Test - void anUntouchedPartitionHasNothingToCommit() { - assertThat(tracker.highestContiguousCompleted(new TopicPartition("orders", 7))).isEmpty(); - } - - @Test - void pruningDropsTheCommittedPrefixButKeepsTheRest() { - tracker.delivered(PARTITION, 10); - tracker.delivered(PARTITION, 11); - tracker.completed(PARTITION, 10); - - tracker.pruneThrough(PARTITION, 10); - - assertThat(tracker.inFlight(PARTITION)).isEqualTo(1); - assertThat(tracker.highestContiguousCompleted(PARTITION)).isEmpty(); - } - - @Test - void revocationForgetsThePartitionEntirely() { - tracker.delivered(PARTITION, 10); - tracker.completed(PARTITION, 10); - - tracker.forget(PARTITION); - - assertThat(tracker.highestContiguousCompleted(PARTITION)).isEmpty(); - assertThat(tracker.inFlight(PARTITION)).isZero(); - } - - @Test - void inFlightCountsDeliveredOffsetsThatHaveNotCompleted() { - tracker.delivered(PARTITION, 10); - tracker.delivered(PARTITION, 11); - tracker.delivered(PARTITION, 12); - tracker.completed(PARTITION, 11); - - assertThat(tracker.inFlight(PARTITION)).isEqualTo(2); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java b/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java deleted file mode 100644 index 83c9bde4..00000000 --- a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java +++ /dev/null @@ -1,880 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.header.ReservedHeaders; -import dev.caskeleton.messaging.policy.OrderingImpact; -import dev.caskeleton.messaging.policy.RetryMode; -import dev.caskeleton.messaging.policy.RetryPolicy; -import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator; -import dev.caskeleton.messaging.transport.TransportConsumerSpec; -import dev.caskeleton.messaging.transport.TransportDelivery; -import java.nio.charset.StandardCharsets; -import java.time.Duration; -import java.time.Instant; -import java.util.ArrayDeque; -import java.util.ArrayList; -import java.util.Deque; -import java.util.List; -import java.util.Map; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import java.util.concurrent.Executor; -import org.apache.kafka.clients.consumer.ConsumerRecord; -import org.apache.kafka.clients.consumer.MockConsumer; -import org.apache.kafka.common.TopicPartition; -import org.apache.kafka.common.header.internals.RecordHeaders; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * Drives the poll loop one cycle at a time against {@code MockConsumer}. - * - *

Handlers run on a deferred executor rather than inline. With an inline executor every handler - * finishes before the next record is considered, so the in-flight ceiling would never actually be - * reached and the ordering guarantee would look correct without being tested. - */ -class KafkaConsumerRegistrarTest { - - private static final String TOPIC = "order.events.v1"; - private static final TopicPartition PARTITION = new TopicPartition(TOPIC, 0); - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - private final MockConsumer consumer = new MockConsumer<>("earliest"); - private final DeferredExecutor handlers = new DeferredExecutor(); - private final List handled = new ArrayList<>(); - - @Test - void dispatchesEachRecordAndCommitsThroughTheContiguousWatermark() { - KafkaConsumerRegistrar registrar = registrar(this::settleImmediately); - assign(); - addRecord(10); - - registrar.pollOnce(NOW); - handlers.runAll(); - addRecord(11); - registrar.pollOnce(NOW); - handlers.runAll(); - registrar.pollOnce(NOW); - - assertThat(handled).hasSize(2); - assertThat(registrar.committedOffset(PARTITION)).hasValue(12L); - } - - @Test - void aRecordStillRunningHoldsBackTheWatermark() { - KafkaConsumerRegistrar registrar = registrar(this::neverSettle); - assign(); - addRecord(10); - - registrar.pollOnce(NOW); - handlers.runAll(); - registrar.pollOnce(NOW); - - assertThat(handled).hasSize(1); - assertThat(registrar.committedOffset(PARTITION)).isEmpty(); - } - - @Test - void anOrderedDestinationDispatchesOneRecordAtATime() { - KafkaConsumerRegistrar registrar = registrar(this::neverSettle); - assign(); - addRecord(10); - addRecord(11); - - int dispatched = registrar.pollOnce(NOW); - - assertThat(dispatched) - .as("the ordering unit allows one in-flight delivery, so the second waits") - .isEqualTo(1); - assertThat(consumer.paused()).contains(PARTITION); - } - - @Test - void theWatermarkAdvancesOnceTheGapCloses() { - KafkaConsumerRegistrar registrar = registrar(this::neverSettle); - assign(); - addRecord(10); - - registrar.pollOnce(NOW); - handlers.runAll(); - assertThat(registrar.committedOffset(PARTITION)).isEmpty(); - - handled.get(0).settlement().acknowledge().toCompletableFuture().join(); - registrar.pollOnce(NOW); - - assertThat(registrar.committedOffset(PARTITION)).hasValue(11L); - } - - @Test - void theEnvelopeIsRebuiltFromReservedHeaders() { - KafkaConsumerRegistrar registrar = registrar(this::settleImmediately); - assign(); - addRecord(10); - - registrar.pollOnce(NOW); - handlers.runAll(); - - assertThat(handled) - .singleElement() - .satisfies( - delivery -> { - assertThat(delivery.envelope().messageType().value()).isEqualTo("order.created"); - assertThat(delivery.metadata().deliveryAttempt()).isEqualTo(1); - assertThat(delivery.metadata().brokerPosition()).isPresent(); - assertThat(delivery.metadata().partitionOrQueue()).hasValue("order.events.v1-0"); - }); - } - - @Test - void drainingStopsDispatchingWithoutClosingTheConsumer() { - GracefulShutdownCoordinator shutdown = new GracefulShutdownCoordinator(Duration.ofSeconds(30)); - KafkaConsumerRegistrar registrar = registrar(this::settleImmediately, shutdown); - assign(); - addRecord(10); - - shutdown.beginDrain(NOW); - int dispatched = registrar.pollOnce(NOW); - - assertThat(dispatched).isZero(); - assertThat(handled).isEmpty(); - assertThat(registrar.isActive()).isTrue(); - } - - @Test - void closingCommitsWhatIsSafeAndDeactivatesTheRegistration() { - KafkaConsumerRegistrar registrar = registrar(this::settleImmediately); - assign(); - addRecord(10); - registrar.pollOnce(NOW); - handlers.runAll(); - - registrar.close(); - - assertThat(registrar.committedOffset(PARTITION)).hasValue(11L); - assertThat(registrar.isActive()).isFalse(); - } - - @Test - void aTimedOutHandlerStillRunningIsNotDispatchedASecondTime() { - // given - Instant start = Instant.now(); - CompletableFuture stillRunning = new CompletableFuture<>(); - KafkaConsumerRegistrar registrar = - registrar( - profile(Duration.ofMillis(5), RetryPolicy.none(), false), - delivery -> { - handled.add(delivery); - return stillRunning; - }, - KafkaQuarantinePublisher.unavailable(), - () -> start); - assign(); - addRecord(10); - registrar.pollOnce(start); - handlers.runAll(); - // What the broker serves again if the consumer seeks back to the timed-out offset. - addRecord(10); - - // when - registrar.pollOnce(start.plusSeconds(60)); - handlers.runAll(); - - // then - assertThat(handled) - .as("cancelling a CompletableFuture does not stop the handler behind it") - .hasSize(1); - } - - @Test - void aTimedOutHandlerIsRedeliveredOnceItFinishesWithoutSettling() { - // given - CompletableFuture stillRunning = new CompletableFuture<>(); - KafkaConsumerRegistrar registrar = - registrar( - profile(Duration.ofMillis(5), RetryPolicy.none(), false), - delivery -> { - handled.add(delivery); - return stillRunning; - }, - KafkaQuarantinePublisher.unavailable(), - () -> NOW); - assign(); - addRecord(10); - registrar.pollOnce(NOW); - handlers.runAll(); - stillRunning.complete(null); - addRecord(10); - - // when - registrar.pollOnce(NOW.plusSeconds(60)); - handlers.runAll(); - - // then - assertThat(handled).hasSize(2); - } - - @Test - void aFailedHandlerWaitsOutItsBackoffBeforeThePartitionIsReadAgain() { - // given - Instant start = Instant.now(); - RetryPolicy threeAttempts = - new RetryPolicy( - RetryMode.PAUSE_PARTITION, - 3, - Duration.ofSeconds(1), - Duration.ofSeconds(10), - 2.0, - false, - OrderingImpact.PRESERVE, - java.util.Set.of(), - java.util.Set.of()); - KafkaConsumerRegistrar registrar = - registrar( - profile(Duration.ofSeconds(1), threeAttempts, false), - this::fail, - KafkaQuarantinePublisher.unavailable(), - () -> start); - assign(); - addRecord(10); - registrar.pollOnce(start); - handlers.runAll(); - - // when - registrar.pollOnce(start.plusMillis(500)); - - // then - assertThat(consumer.paused()) - .as("a failure retried with no delay re-reads the same record as fast as the loop polls") - .contains(PARTITION); - } - - @Test - void aHandlerThatSpendsItsAttemptBudgetIsQuarantinedAndCommittedPast() { - // given - List quarantined = new ArrayList<>(); - KafkaConsumerRegistrar registrar = - registrar( - KafkaContractHarness.profile(), - this::fail, - (record, category, reason) -> quarantined.add(record.offset()), - () -> NOW); - assign(); - addRecord(10); - registrar.pollOnce(NOW); - handlers.runAll(); - - // when - registrar.pollOnce(NOW); - - // then - assertThat(registrar.committedOffset(PARTITION)) - .as("a poison message retried forever stops its partition for good") - .hasValue(11L); - } - - @Test - @DisplayName("handler가 시도 예산을 다 쓴 레코드는 그 실패의 분류로 격리하고 분류가 없으면 POISON_MESSAGE로 적는다") - void aDeliveryThatSpentItsBudgetIsQuarantinedUnderItsFailuresCategory() { - // given: a handler that fails with a plain exception every time - List categories = new ArrayList<>(); - KafkaConsumerRegistrar registrar = - registrar( - KafkaContractHarness.profile(), - this::fail, - (record, category, reason) -> categories.add(category), - () -> NOW); - assign(); - addRecord(10); - registrar.pollOnce(NOW); - handlers.runAll(); - - // when - registrar.pollOnce(NOW); - - // then - assertThat(categories).containsExactly(FailureCategory.POISON_MESSAGE); - } - - @Test - @DisplayName("handler가 요청한 requeue도 시도 횟수를 세어 예산을 쓰면 quarantine 후 commit된다") - void aDeliveryItsHandlerKeepsRequeueingSpendsTheBudgetAndIsQuarantined() { - // given - List quarantined = new ArrayList<>(); - KafkaConsumerRegistrar registrar = - registrar( - KafkaContractHarness.profile(), - this::requeue, - (record, category, reason) -> quarantined.add(record.offset()), - () -> NOW); - assign(); - addRecord(10); - registrar.pollOnce(NOW); - handlers.runAll(); - - // when - registrar.pollOnce(NOW); - - // then - assertThat(quarantined) - .as("a Retry answer that is never counted is a poison message retried forever") - .containsExactly(10L); - assertThat(registrar.committedOffset(PARTITION)).hasValue(11L); - } - - @Test - @DisplayName("다시 읽힌 delivery는 몇 번째 시도인지 metadata로 handler에 알려진다") - void aReReadDeliveryTellsTheHandlerWhichAttemptItIs() { - // given - Instant start = NOW; - RetryPolicy threeAttempts = - new RetryPolicy( - RetryMode.PAUSE_PARTITION, - 3, - Duration.ofSeconds(1), - Duration.ofSeconds(1), - 1.0, - false, - OrderingImpact.PRESERVE, - java.util.Set.of(), - java.util.Set.of()); - KafkaConsumerRegistrar registrar = - registrar( - profile(Duration.ofSeconds(1), threeAttempts, false), - this::requeue, - KafkaQuarantinePublisher.unavailable(), - () -> start); - assign(); - addRecord(10); - registrar.pollOnce(start); - handlers.runAll(); - registrar.pollOnce(start); - addRecord(10); - - // when - registrar.pollOnce(start.plusSeconds(2)); - handlers.runAll(); - - // then - assertThat(handled) - .extracting(delivery -> delivery.metadata().deliveryAttempt()) - .containsExactly(1, 2); - assertThat(handled.get(1).metadata().redelivered()).isTrue(); - } - - @Test - void aProductionDestinationWithoutAQuarantineIsRefused() { - // given - dev.caskeleton.messaging.policy.DestinationProfile production = - profile(Duration.ofSeconds(30), RetryPolicy.none(), true); - - // when - Throwable thrown = - org.assertj.core.api.Assertions.catchThrowable( - () -> registrar(production, this::settleImmediately)); - - // then - assertThat(thrown) - .isInstanceOf(dev.caskeleton.messaging.api.error.MessagingConfigurationException.class) - .extracting( - failure -> - ((dev.caskeleton.messaging.api.error.MessagingConfigurationException) failure) - .failure() - .code()) - .isEqualTo("KAFKA_QUARANTINE_REQUIRED"); - } - - @Test - void aPartitionPausedAtItsCeilingResumesOnceItsDeliveryFinishes() { - // given - KafkaConsumerRegistrar registrar = registrar(this::settleImmediately); - assign(); - addRecord(10); - addRecord(11); - registrar.pollOnce(NOW); - handlers.runAll(); - // The second record was returned by the first poll and handed back with a seek. - addRecord(11); - - // when - registrar.pollOnce(NOW); - handlers.runAll(); - - // then - assertThat(handled) - .as("pausing a full partition is backpressure only if something resumes it") - .hasSize(2); - } - - @Test - void closeStillClosesTheConsumerWhenTheFinalCommitFails() { - CommitFailingConsumer failing = new CommitFailingConsumer(); - failing.assign(List.of(PARTITION)); - failing.updateBeginningOffsets(Map.of(PARTITION, 10L)); - failing.seek(PARTITION, 10L); - - RecordHeaders headers = new RecordHeaders(); - headers.add( - ReservedHeaders.MESSAGE_ID, - MessageId.newId().value().toString().getBytes(StandardCharsets.UTF_8)); - headers.add(ReservedHeaders.MESSAGE_TYPE, "order.created".getBytes(StandardCharsets.UTF_8)); - headers.add(ReservedHeaders.SCHEMA_VERSION, "1".getBytes(StandardCharsets.UTF_8)); - headers.add(ReservedHeaders.CONTENT_TYPE, "application/json".getBytes(StandardCharsets.UTF_8)); - failing.addRecord(record(10, headers)); - - KafkaConsumerRegistrar registrar = - new KafkaConsumerRegistrar( - new TransportConsumerSpec( - KafkaContractHarness.profile(), - delivery -> { - delivery.settlement().acknowledge().toCompletableFuture().join(); - return CompletableFuture.completedFuture(null); - }), - failing, - Runnable::run, - new GracefulShutdownCoordinator(Duration.ofSeconds(30)), - Duration.ofMillis(1)); - - registrar.pollOnce(NOW); - failing.failCommits = true; - - org.assertj.core.api.Assertions.assertThatThrownBy(registrar::close) - .isInstanceOf(org.apache.kafka.clients.consumer.CommitFailedException.class); - assertThat(failing.closed()) - .as("a failed final commit must not leak the consumer/group membership") - .isTrue(); - } - - @Test - void pauseAndResumeOperateOnTheAssignedPartitions() { - KafkaConsumerRegistrar registrar = registrar(this::settleImmediately); - assign(); - - // pause/resume are queued for the poll thread rather than touching the Consumer from the - // caller's thread — the Kafka consumer is not thread-safe, and this class documents itself as - // poll-thread-only. The stage therefore completes on the next poll cycle, which is what - // "applied" means for a runtime whose loop is running. - java.util.concurrent.CompletionStage paused = registrar.pause(""); - registrar.pollOnce(NOW); - paused.toCompletableFuture().join(); - assertThat(consumer.paused()).contains(PARTITION); - - java.util.concurrent.CompletionStage resumed = registrar.resume(""); - registrar.pollOnce(NOW); - resumed.toCompletableFuture().join(); - assertThat(consumer.paused()).doesNotContain(PARTITION); - } - - @Test - void anUndecodableRecordIsParkedRatherThanRetriedForever() { - KafkaConsumerRegistrar registrar = registrar(this::settleImmediately); - assign(); - addRecordWithoutIdentityHeaders(10); - - registrar.pollOnce(NOW); - handlers.runAll(); - registrar.pollOnce(NOW); - - assertThat(handled).isEmpty(); - assertThat(registrar.committedOffset(PARTITION)) - .as("PARKED completed the offset with no quarantine write, so the record was simply lost") - .isEmpty(); - } - - @Test - @DisplayName("an undecodable record commits only once quarantine confirms the write") - void anUndecodableRecordCommitsAfterQuarantineConfirms() { - java.util.List quarantined = new java.util.ArrayList<>(); - try (KafkaConsumerRegistrar registrar = - new KafkaConsumerRegistrar( - new TransportConsumerSpec(KafkaContractHarness.profile(), this::settleImmediately), - consumer, - handlers, - new GracefulShutdownCoordinator(Duration.ofSeconds(30)), - Duration.ofMillis(1), - (record, category, reason) -> { - quarantined.add(record.offset()); - return true; - })) { - assign(); - addRecordWithoutIdentityHeaders(10); - - registrar.pollOnce(NOW); - handlers.runAll(); - registrar.pollOnce(NOW); - - assertThat(quarantined).containsExactly(10L); - assertThat(registrar.committedOffset(PARTITION)).hasValue(11L); - } - } - - /** - * A record that cannot be rebuilt into an envelope will never decode, however often it is - * redriven; the one whose handler ran out of attempts may pass once the outage is over. They were - * both written as {@code POISON_MESSAGE} (review 2026-11-01 06-14). - */ - @Test - @DisplayName("envelope로 되살릴 수 없는 레코드는 시도 예산 소진과 다른 DESERIALIZATION으로 격리한다") - void anUndecodableRecordIsQuarantinedAsDeserializationNotAsPoison() { - // given - List categories = new ArrayList<>(); - try (KafkaConsumerRegistrar registrar = - new KafkaConsumerRegistrar( - new TransportConsumerSpec(KafkaContractHarness.profile(), this::settleImmediately), - consumer, - handlers, - new GracefulShutdownCoordinator(Duration.ofSeconds(30)), - Duration.ofMillis(1), - (record, category, reason) -> categories.add(category))) { - assign(); - addRecordWithoutIdentityHeaders(10); - registrar.pollOnce(NOW); - - // when - handlers.runAll(); - - // then - assertThat(categories).containsExactly(FailureCategory.DESERIALIZATION); - } - } - - @Test - @DisplayName("격리 쓰기가 한 번 실패해 재시도로 넘어간 읽을 수 없는 레코드도 DESERIALIZATION으로 격리한다") - void anUndecodableRecordStaysDeserializationWhenItsQuarantineIsRetried() { - // given: the first quarantine write is not confirmed, so the record goes round the retry path - List categories = new ArrayList<>(); - try (KafkaConsumerRegistrar registrar = - new KafkaConsumerRegistrar( - new TransportConsumerSpec(KafkaContractHarness.profile(), this::settleImmediately), - consumer, - handlers, - new GracefulShutdownCoordinator(Duration.ofSeconds(30)), - Duration.ofMillis(1), - (record, category, reason) -> { - categories.add(category); - return categories.size() > 1; - })) { - assign(); - addRecordWithoutIdentityHeaders(10); - registrar.pollOnce(NOW); - - // when - handlers.runAll(); - - // then - assertThat(categories) - .containsExactly(FailureCategory.DESERIALIZATION, FailureCategory.DESERIALIZATION); - } - } - - @Test - @DisplayName("one partition hitting its ceiling does not abandon the other's records") - void oneSaturatedPartitionDoesNotAbandonAnother() { - org.apache.kafka.common.TopicPartition second = - new org.apache.kafka.common.TopicPartition(PARTITION.topic(), PARTITION.partition() + 1); - consumer.assign(List.of(PARTITION, second)); - consumer.updateBeginningOffsets(Map.of(PARTITION, 10L, second, 10L)); - consumer.seek(PARTITION, 10L); - consumer.seek(second, 10L); - KafkaConsumerRegistrar registrar = registrar(this::settleImmediately); - // Two records on the first partition (its ordering unit allows one in flight) and one on the - // second. The old loop broke out of the whole batch at the first record it could not submit. - addRecord(10); - addRecord(11); - addRecordOn(second, 10); - - int dispatched = registrar.pollOnce(NOW); - - assertThat(dispatched) - .as("the second partition's record was returned by the same poll and must not be dropped") - .isEqualTo(2); - } - - @Test - @DisplayName("a rejected executor submission leaves nothing in flight and re-reads the record") - void aRejectedSubmissionIsUndone() { - try (KafkaConsumerRegistrar registrar = - new KafkaConsumerRegistrar( - new TransportConsumerSpec(KafkaContractHarness.profile(), this::settleImmediately), - consumer, - command -> { - throw new java.util.concurrent.RejectedExecutionException("pool is shutting down"); - }, - new GracefulShutdownCoordinator(Duration.ofSeconds(30)), - Duration.ofMillis(1))) { - assign(); - addRecord(10); - - int dispatched = registrar.pollOnce(NOW); - - assertThat(dispatched).isZero(); - assertThat(registrar.committedOffset(PARTITION)) - .as("an offset registered as delivered with no worker behind it never completes") - .isEmpty(); - assertThat(consumer.position(PARTITION)) - .as("the record must be re-read next cycle") - .isEqualTo(10L); - } - } - - @Test - @DisplayName("a settlement from a revoked assignment is refused") - void aStaleSettlementIsRefused() { - KafkaConsumerRegistrar registrar = registrar(this::deferSettlement); - assign(); - addRecord(10); - registrar.pollOnce(NOW); - - // The partition goes away and comes back: a new assignment, a new epoch. - consumer.assign(List.of()); - registrar.pollOnce(NOW); - assign(); - registrar.pollOnce(NOW); - - // Now the old handler finally acknowledges. - handlers.runAll(); - registrar.pollOnce(NOW); - - assertThat(registrar.staleSettlements()) - .as("an acknowledgement from the previous assignment must not move this one's watermark") - .isPositive(); - assertThat(registrar.committedOffset(PARTITION)).isEmpty(); - } - - @Test - @DisplayName("a second terminal call on one delivery is refused") - void aSecondTerminalCallIsRefused() { - java.util.List refusals = new java.util.ArrayList<>(); - KafkaConsumerRegistrar registrar = - registrar( - delivery -> { - delivery.settlement().acknowledge().toCompletableFuture().join(); - delivery - .settlement() - .requeue(Duration.ZERO) - .toCompletableFuture() - .handle( - (result, failure) -> { - if (failure != null) { - refusals.add(failure); - } - return null; - }) - .join(); - return java.util.concurrent.CompletableFuture.completedFuture(null); - }); - assign(); - addRecord(10); - - registrar.pollOnce(NOW); - handlers.runAll(); - - assertThat(refusals) - .as("telling the poll thread both 'done' and 're-read this' lets the second one win") - .hasSize(1); - } - - private void addRecordOn(org.apache.kafka.common.TopicPartition partition, long offset) { - RecordHeaders headers = new RecordHeaders(); - headers.add( - ReservedHeaders.MESSAGE_ID, - // A v7 identity: MessageId now enforces the version it documents, and a v4 here would be - // refused by the envelope mapper exactly as a foreign producer's would. - MessageId.newId().value().toString().getBytes(StandardCharsets.UTF_8)); - headers.add(ReservedHeaders.MESSAGE_TYPE, "order.created".getBytes(StandardCharsets.UTF_8)); - headers.add(ReservedHeaders.SCHEMA_VERSION, "1".getBytes(StandardCharsets.UTF_8)); - headers.add(ReservedHeaders.CONTENT_TYPE, "application/json".getBytes(StandardCharsets.UTF_8)); - consumer.addRecord( - new ConsumerRecord<>( - partition.topic(), - partition.partition(), - offset, - NOW.toEpochMilli(), - org.apache.kafka.common.record.TimestampType.CREATE_TIME, - 0, - 0, - null, - "{}".getBytes(StandardCharsets.UTF_8), - headers, - java.util.Optional.empty())); - } - - /** Never settles inside the handler, so the settlement arrives later. */ - private CompletionStage deferSettlement(TransportDelivery delivery) { - delivery.settlement().acknowledge(); - return java.util.concurrent.CompletableFuture.completedFuture(null); - } - - private void assign() { - consumer.assign(List.of(PARTITION)); - consumer.updateBeginningOffsets(Map.of(PARTITION, 10L)); - consumer.seek(PARTITION, 10L); - } - - private void addRecord(long offset) { - RecordHeaders headers = new RecordHeaders(); - headers.add( - ReservedHeaders.MESSAGE_ID, - // A v7 identity: MessageId now enforces the version it documents, and a v4 here would be - // refused by the envelope mapper exactly as a foreign producer's would. - MessageId.newId().value().toString().getBytes(StandardCharsets.UTF_8)); - headers.add(ReservedHeaders.MESSAGE_TYPE, "order.created".getBytes(StandardCharsets.UTF_8)); - headers.add(ReservedHeaders.SCHEMA_VERSION, "1".getBytes(StandardCharsets.UTF_8)); - headers.add(ReservedHeaders.CONTENT_TYPE, "application/json".getBytes(StandardCharsets.UTF_8)); - consumer.addRecord(record(offset, headers)); - } - - private void addRecordWithoutIdentityHeaders(long offset) { - consumer.addRecord(record(offset, new RecordHeaders())); - } - - private static ConsumerRecord record(long offset, RecordHeaders headers) { - return new ConsumerRecord<>( - TOPIC, - 0, - offset, - NOW.toEpochMilli(), - org.apache.kafka.common.record.TimestampType.CREATE_TIME, - 0, - 0, - null, - "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), - headers, - java.util.Optional.empty()); - } - - private KafkaConsumerRegistrar registrar( - java.util.function.Function> sink) { - return registrar(sink, new GracefulShutdownCoordinator(Duration.ofSeconds(30))); - } - - private KafkaConsumerRegistrar registrar( - java.util.function.Function> sink, - GracefulShutdownCoordinator shutdown) { - return new KafkaConsumerRegistrar( - new TransportConsumerSpec(KafkaContractHarness.profile(), sink), - consumer, - handlers, - shutdown, - Duration.ofMillis(1)); - } - - private KafkaConsumerRegistrar registrar( - dev.caskeleton.messaging.policy.DestinationProfile profile, - java.util.function.Function> sink) { - return new KafkaConsumerRegistrar( - new TransportConsumerSpec(profile, sink), - consumer, - handlers, - new GracefulShutdownCoordinator(Duration.ofSeconds(30)), - Duration.ofMillis(1)); - } - - private KafkaConsumerRegistrar registrar( - dev.caskeleton.messaging.policy.DestinationProfile profile, - java.util.function.Function> sink, - KafkaQuarantinePublisher quarantine, - java.time.InstantSource clock) { - return new KafkaConsumerRegistrar( - new TransportConsumerSpec(profile, sink), - consumer, - handlers, - new GracefulShutdownCoordinator(Duration.ofSeconds(30)), - Duration.ofMillis(1), - quarantine, - clock); - } - - /** The harness profile with the three settings these tests vary. */ - private static dev.caskeleton.messaging.policy.DestinationProfile profile( - Duration handlerTimeout, RetryPolicy retry, boolean production) { - dev.caskeleton.messaging.policy.DestinationProfile base = KafkaContractHarness.profile(); - return new dev.caskeleton.messaging.policy.DestinationProfile( - base.name(), - base.broker(), - base.kind(), - base.physical(), - base.schema(), - base.deliveryGuarantee(), - base.orderingScope(), - base.externalSideEffectGuarantee(), - base.producer(), - new dev.caskeleton.messaging.policy.ConsumerPolicy( - base.consumer().group(), - base.consumer().concurrency(), - base.consumer().maxInFlightPerOrderingUnit(), - base.consumer().prefetch(), - handlerTimeout, - base.consumer().manualSettlement()), - retry, - base.deadLetter(), - base.payload(), - base.tier(), - production, - base.keyResolverConfigured(), - base.topologyAutoCreate()); - } - - /** A handler that fails every delivery it is given. */ - private CompletionStage fail(TransportDelivery delivery) { - handled.add(delivery); - throw new IllegalStateException("the downstream this handler writes to is down"); - } - - /** Asks for another attempt through the settlement, as the processor does for a Retry answer. */ - private CompletionStage requeue(TransportDelivery delivery) { - handled.add(delivery); - delivery.settlement().requeue(Duration.ZERO).toCompletableFuture().join(); - return CompletableFuture.completedFuture(null); - } - - /** Acknowledges inside the handler, as a successful M1 delivery does. */ - private CompletionStage settleImmediately(TransportDelivery delivery) { - handled.add(delivery); - delivery.settlement().acknowledge().toCompletableFuture().join(); - return CompletableFuture.completedFuture(null); - } - - /** Leaves the delivery in flight, which is what holds the watermark back. */ - private CompletionStage neverSettle(TransportDelivery delivery) { - handled.add(delivery); - return CompletableFuture.completedFuture(null); - } - - private static final class CommitFailingConsumer extends MockConsumer { - // Set by the test thread, read by whichever thread commits. - private volatile boolean failCommits; - - CommitFailingConsumer() { - super("earliest"); - } - - @Override - public synchronized void commitSync( - Map offsets) { - if (failCommits) { - throw new org.apache.kafka.clients.consumer.CommitFailedException("forced final commit"); - } - super.commitSync(offsets); - } - } -} - -/** Queues handler work so the in-flight ceiling is observable. */ -final class DeferredExecutor implements Executor { - - private final Deque queued = new ArrayDeque<>(); - - @Override - public void execute(Runnable command) { - queued.addLast(command); - } - - void runAll() { - while (!queued.isEmpty()) { - queued.pollFirst().run(); - } - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaEnvelopeRoundTripTest.java b/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaEnvelopeRoundTripTest.java deleted file mode 100644 index b765d3e1..00000000 --- a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaEnvelopeRoundTripTest.java +++ /dev/null @@ -1,154 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -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.MessageEnvelope; -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.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.time.Instant; -import java.util.Map; -import java.util.Optional; -import org.apache.kafka.clients.consumer.ConsumerRecord; -import org.apache.kafka.common.header.Headers; -import org.apache.kafka.common.header.internals.RecordHeaders; -import org.apache.kafka.common.record.TimestampType; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * What an envelope still holds after it has been through Kafka. - * - *

Publishing and consuming were written against each other's headers but never checked as one - * trip, so what the producer wrote and what the consumer rebuilt were free to disagree — and they - * did, in the two ways that matter operationally: the application's own headers vanished, and the - * retry bookkeeping vanished with them, which restarts an attempt counter that is supposed to cap - * redeliveries. - */ -class KafkaEnvelopeRoundTripTest { - - private static final Instant FAILED_AT = Instant.parse("2026-08-15T10:00:00Z"); - - private final KafkaHeaderMapper headerMapper = new KafkaHeaderMapper(); - - private final KafkaDeliveryMapper deliveryMapper = new KafkaDeliveryMapper(headerMapper); - - private final KafkaRetryMetadataMapper retryMapper = new KafkaRetryMetadataMapper(); - - @Test - @DisplayName("an application header survives the trip through the broker") - void anApplicationHeaderSurvivesTheTrip() { - MessageEnvelope published = - KafkaFixtures.orderCreatedEnvelope() - .withHeaders( - 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 = - KafkaFixtures.orderCreatedEnvelope() - .withTenant(new dev.caskeleton.messaging.api.TenantContext("acme")); - - MessageEnvelope delivered = roundTrip(published); - - assertThat(delivered.tenantContext()) - .as("a broker record 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 retried = - retryMapper.stamp(KafkaFixtures.orderCreatedEnvelope(), 3, failure(), FAILED_AT); - - MessageEnvelope delivered = roundTrip(retried); - - assertThat(retryMapper.attemptOf(delivered)) - .as("an attempt counter that resets on every hop caps nothing") - .isEqualTo(3); - } - - @Test - @DisplayName("a retry-stamped envelope can be published to its retry topic") - void aRetryStampedEnvelopeCanBePublished() { - MessageEnvelope retried = - retryMapper.stamp(KafkaFixtures.orderCreatedEnvelope(), 2, failure(), FAILED_AT); - - assertThatCode(() -> headerMapper.toKafkaHeaders(retried)) - .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 = - KafkaFixtures.orderCreatedEnvelope() - .withHeaders( - MessageHeaders.platform( - Map.of(new HeaderName(ReservedHeaders.MESSAGE_ID), new HeaderValue("forged")))); - - assertThatThrownBy(() -> headerMapper.toKafkaHeaders(forged)) - .isInstanceOf(MessagingConfigurationException.class); - } - - @Test - @DisplayName("identity is read from its field, not duplicated into the header map") - void identityIsNotDuplicatedIntoTheHeaderMap() { - MessageEnvelope delivered = roundTrip(KafkaFixtures.orderCreatedEnvelope()); - - assertThat(delivered.headers().find(ReservedHeaders.MESSAGE_ID)) - .as("a copy that can drift from the field gives the same message two identities") - .isEmpty(); - assertThat(delivered.messageId()).isNotNull(); - } - - private MessageEnvelope roundTrip(MessageEnvelope published) { - Headers wire = headerMapper.toKafkaHeaders(published); - return deliveryMapper.toEnvelope(record(wire, published.payload().bytes())); - } - - private static ConsumerRecord record(Headers wire, byte[] payload) { - RecordHeaders headers = new RecordHeaders(); - wire.forEach(header -> headers.add(header.key(), header.value())); - return new ConsumerRecord<>( - "order-events", - 0, - 7L, - FAILED_AT.toEpochMilli(), - TimestampType.CREATE_TIME, - 0, - payload.length, - null, - payload, - headers, - Optional.empty()); - } - - private static FailureDescriptor failure() { - return new FailureDescriptor( - FailureCategory.PROCESSING_TRANSIENT, - "HANDLER_FAILED", - true, - "IllegalStateException", - Optional.empty()); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaHeaderMapperTest.java b/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaHeaderMapperTest.java deleted file mode 100644 index a7ec3dcb..00000000 --- a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaHeaderMapperTest.java +++ /dev/null @@ -1,118 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -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.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.Map; -import java.util.Optional; -import org.apache.kafka.common.header.Headers; -import org.junit.jupiter.api.Test; - -class KafkaHeaderMapperTest { - - private final KafkaHeaderMapper mapper = new KafkaHeaderMapper(); - - @Test - void writesLogicalIdentityAndSchemaHeaders() { - Headers headers = mapper.toKafkaHeaders(KafkaFixtures.orderCreatedEnvelope()); - - assertThat(new String(headers.lastHeader("msg.type").value(), StandardCharsets.UTF_8)) - .isEqualTo("order.created"); - assertThat(new String(headers.lastHeader("msg.schema-version").value(), StandardCharsets.UTF_8)) - .isEqualTo("1"); - } - - @Test - void writesTheLogicalMessageIdSoAPoisonPayloadIsStillIdentifiable() { - MessageEnvelope envelope = KafkaFixtures.orderCreatedEnvelope(); - - Headers headers = mapper.toKafkaHeaders(envelope); - - assertThat(mapper.value(headers, ReservedHeaders.MESSAGE_ID)) - .isEqualTo(envelope.messageId().value().toString()); - } - - @Test - void carriesOptionalProvenanceOnlyWhenPresent() { - Headers withCorrelation = mapper.toKafkaHeaders(KafkaFixtures.orderCreatedEnvelope()); - Headers withoutCorrelation = mapper.toKafkaHeaders(KafkaFixtures.minimalEnvelope()); - - assertThat(mapper.value(withCorrelation, ReservedHeaders.CORRELATION_ID)).isEqualTo("wf-1"); - assertThat(mapper.value(withoutCorrelation, ReservedHeaders.CORRELATION_ID)).isNull(); - } - - @Test - void carriesApplicationHeadersAlongsideReservedOnes() { - MessageEnvelope envelope = - KafkaFixtures.orderCreatedEnvelope() - .withHeaders( - MessageHeaders.application( - Map.of(new HeaderName("x-source-system"), new HeaderValue("erp")))); - - Headers headers = mapper.toKafkaHeaders(envelope); - - assertThat(mapper.value(headers, "x-source-system")).isEqualTo("erp"); - assertThat(mapper.value(headers, ReservedHeaders.MESSAGE_TYPE)).isEqualTo("order.created"); - } - - @Test - void roundTripsBackToPlatformHeaders() { - Headers headers = mapper.toKafkaHeaders(KafkaFixtures.orderCreatedEnvelope()); - - MessageHeaders restored = mapper.fromKafkaHeaders(headers); - - assertThat(restored.find(ReservedHeaders.MESSAGE_TYPE)) - .map(HeaderValue::value) - .hasValue("order.created"); - } -} - -/** Builds Kafka adapter fixtures. */ -final class KafkaFixtures { - - private KafkaFixtures() {} - - static MessageEnvelope orderCreatedEnvelope() { - return envelope(Optional.of(new CorrelationId("wf-1"))); - } - - static MessageEnvelope minimalEnvelope() { - return envelope(Optional.empty()); - } - - static MessageEnvelope envelope(Optional correlationId) { - return new MessageEnvelope<>( - MessageId.newId(), - new MessageType("order.created"), - new SchemaVersion(1), - Instant.parse("2026-08-10T09:15:00Z"), - Optional.of(Instant.parse("2026-08-10T09:15:00Z")), - new ProducerId("order-api"), - correlationId, - Optional.empty(), - ContentType.JSON, - Optional.of("acct-1"), - Optional.of("acct-1"), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - new EncodedMessage( - "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), - ContentType.JSON, - Optional.empty())); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransportTest.java b/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransportTest.java deleted file mode 100644 index d50ce603..00000000 --- a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransportTest.java +++ /dev/null @@ -1,43 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.error.FailureDescriptor; -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.transport.TransportPublishRequest; -import org.apache.kafka.clients.producer.MockProducer; -import org.apache.kafka.clients.producer.Partitioner; -import org.apache.kafka.common.serialization.ByteArraySerializer; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** What a closed Kafka transport answers a publish that arrives during shutdown. */ -class KafkaMessagingTransportTest { - - @Test - @DisplayName("닫힌 transport의 거부는 다음 인스턴스가 받을 수 있으므로 다시 시도할 수 있다고 표시한다") - void aPublishToAClosedTransportIsARefusalThatMayBeRetried() { - // given: the transport closed while a relay cycle was still publishing - KafkaMessagingTransport transport = - new KafkaMessagingTransport( - "kafka-primary", - 1, - new MockProducer<>( - false, (Partitioner) null, new ByteArraySerializer(), new ByteArraySerializer())); - transport.close(); - TransportPublishRequest request = - new TransportPublishRequest( - KafkaContractHarness.profile(), - KafkaFixtures.orderCreatedEnvelope(), - PublishOptions.defaults()); - - // when - PublishResult result = transport.publish(request).toCompletableFuture().join().result(); - - // then - assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); - assertThat(result.failure()).get().extracting(FailureDescriptor::retryable).isEqualTo(true); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaProducerContractTest.java b/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaProducerContractTest.java deleted file mode 100644 index 36fe67ae..00000000 --- a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaProducerContractTest.java +++ /dev/null @@ -1,24 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -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 Kafka adapter. - * - *

The same seven tests the in-memory harness runs. That is the point: "Stable" is defined by - * passing this suite unchanged, so Kafka and RabbitMQ are held to one definition of correctness - * rather than to their own. - */ -class KafkaProducerContractTest { - - @Nested - class Contract extends MessagingAdapterContract { - - @Override - protected MessagingAdapterHarness harness() { - return KafkaContractHarness.create(); - } - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaProfileValidatorTest.java b/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaProfileValidatorTest.java deleted file mode 100644 index 4d19b89d..00000000 --- a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaProfileValidatorTest.java +++ /dev/null @@ -1,167 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -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 java.time.Duration; -import java.util.List; -import org.junit.jupiter.api.Test; - -class KafkaProfileValidatorTest { - - private final KafkaProfileValidator validator = new KafkaProfileValidator(); - - @Test - void stableProducerRequiresIdempotenceAndAcksAll() { - KafkaBrokerProfile profile = KafkaBrokerProfileFixtures.withProducer(false, "1", 5); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("idempotence"); - } - - @Test - void stableProducerRejectsAcksOneEvenWithIdempotence() { - KafkaBrokerProfile profile = KafkaBrokerProfileFixtures.withProducer(true, "1", 5); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("acks=all"); - } - - @Test - void stableProducerRejectsTooManyInFlightRequests() { - KafkaBrokerProfile profile = KafkaBrokerProfileFixtures.withProducer(true, "all", 6); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("max.in.flight"); - } - - @Test - void consumerAutoCommitIsForbidden() { - KafkaBrokerProfile profile = KafkaBrokerProfileFixtures.withAutoCommit(true); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("auto commit"); - } - - @Test - void productionRequiresTlsAndAuthentication() { - assertThatThrownBy(() -> validator.validate(KafkaBrokerProfileFixtures.productionWithoutTls())) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("TLS"); - assertThatThrownBy(() -> validator.validate(KafkaBrokerProfileFixtures.productionWithoutAuth())) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("authentication"); - } - - @Test - void aStableProfileValidates() { - assertThatCode(() -> validator.validate(KafkaBrokerProfileFixtures.stable())) - .doesNotThrowAnyException(); - } - - @Test - void kafkaPositionExposesOnlyDiagnosticCoordinates() { - KafkaPosition position = new KafkaPosition("order.events.v1", 3, 918_273); - - assertThat(position.broker()).isEqualTo("kafka"); - assertThat(position.diagnosticAttributes()) - .containsExactlyInAnyOrderEntriesOf( - java.util.Map.of("topic", "order.events.v1", "partition", "3", "offset", "918273")); - } -} - -/** Builds Kafka broker profiles for validator tests. */ -final class KafkaBrokerProfileFixtures { - - private KafkaBrokerProfileFixtures() {} - - static KafkaBrokerProfile stable() { - return new KafkaBrokerProfile( - "kafka-primary", - true, - false, - List.of("localhost:9092"), - true, - "all", - 5, - Duration.ofSeconds(30), - false, - "order-projection", - true, - true); - } - - static KafkaBrokerProfile withProducer( - boolean enableIdempotence, String acks, int maxInFlightRequests) { - KafkaBrokerProfile base = stable(); - return new KafkaBrokerProfile( - base.broker(), - base.stable(), - base.production(), - base.bootstrapServers(), - enableIdempotence, - acks, - maxInFlightRequests, - base.deliveryTimeout(), - base.enableAutoCommit(), - base.consumerGroup(), - base.tlsEnabled(), - base.authenticationEnabled()); - } - - static KafkaBrokerProfile withAutoCommit(boolean enableAutoCommit) { - KafkaBrokerProfile base = stable(); - return new KafkaBrokerProfile( - base.broker(), - base.stable(), - base.production(), - base.bootstrapServers(), - base.enableIdempotence(), - base.acks(), - base.maxInFlightRequestsPerConnection(), - base.deliveryTimeout(), - enableAutoCommit, - base.consumerGroup(), - base.tlsEnabled(), - base.authenticationEnabled()); - } - - static KafkaBrokerProfile productionWithoutTls() { - KafkaBrokerProfile base = stable(); - return new KafkaBrokerProfile( - base.broker(), - true, - true, - base.bootstrapServers(), - base.enableIdempotence(), - base.acks(), - base.maxInFlightRequestsPerConnection(), - base.deliveryTimeout(), - false, - base.consumerGroup(), - false, - true); - } - - static KafkaBrokerProfile productionWithoutAuth() { - KafkaBrokerProfile base = stable(); - return new KafkaBrokerProfile( - base.broker(), - true, - true, - base.bootstrapServers(), - base.enableIdempotence(), - base.acks(), - base.maxInFlightRequestsPerConnection(), - base.deliveryTimeout(), - false, - base.consumerGroup(), - true, - false); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifierTest.java b/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifierTest.java deleted file mode 100644 index cdbae5a2..00000000 --- a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifierTest.java +++ /dev/null @@ -1,69 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishResult; -import java.time.Duration; -import org.apache.kafka.common.errors.AuthenticationException; -import org.apache.kafka.common.errors.AuthorizationException; -import org.apache.kafka.common.errors.InvalidTopicException; -import org.apache.kafka.common.errors.TopicAuthorizationException; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * Which producer failures a publisher may retry. - * - *

Authentication and authorization failures prove the broker did not store the record, so they - * are rejections. They are not proof the record will be refused again: a credential being rotated - * or an ACL deployed after the application fails this way for a few minutes and then stops. - */ -class KafkaPublishFailureClassifierTest { - - private final KafkaPublishFailureClassifier classifier = new KafkaPublishFailureClassifier(); - - @Test - @DisplayName("인증 실패는 저장되지 않은 거부지만 다시 시도할 수 있다고 표시한다") - void anAuthenticationFailureIsARejectionThatMayBeRetried() { - // given - AuthenticationException rotatingCredential = - new AuthenticationException("SASL authentication failed"); - - // when - PublishResult result = classifier.classify(rotatingCredential, Duration.ZERO); - - // then - assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); - assertThat(result.failure()).get().extracting(FailureDescriptor::retryable).isEqualTo(true); - } - - @Test - @DisplayName("인가 실패는 저장되지 않은 거부지만 다시 시도할 수 있다고 표시한다") - void anAuthorizationFailureIsARejectionThatMayBeRetried() { - // given - AuthorizationException aclNotYetDeployed = new TopicAuthorizationException("orders"); - - // when - PublishResult result = classifier.classify(aclNotYetDeployed, Duration.ZERO); - - // then - assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); - assertThat(result.failure()).get().extracting(FailureDescriptor::retryable).isEqualTo(true); - } - - @Test - @DisplayName("존재하지 않는 topic은 다시 시도해도 같으므로 다시 시도할 수 없다고 표시한다") - void anInvalidTopicIsARejectionThatMayNotBeRetried() { - // given - InvalidTopicException noSuchTopic = new InvalidTopicException("no such topic"); - - // when - PublishResult result = classifier.classify(noSuchTopic, Duration.ZERO); - - // then - assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); - assertThat(result.failure()).get().extracting(FailureDescriptor::retryable).isEqualTo(false); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaReplayPlannerTest.java b/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaReplayPlannerTest.java deleted file mode 100644 index eb4e3b0d..00000000 --- a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaReplayPlannerTest.java +++ /dev/null @@ -1,88 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.error.MessageAuthorizationException; -import java.time.Instant; -import java.util.LinkedHashMap; -import java.util.Map; -import java.util.Optional; -import org.apache.kafka.common.TopicPartition; -import org.junit.jupiter.api.Test; - -class KafkaReplayPlannerTest { - - private static final Instant FROM = Instant.parse("2026-08-01T00:00:00Z"); - - private final KafkaReplayPlanner planner = new KafkaReplayPlanner(); - - @Test - void createsIsolatedConsumerGroupByDefault() { - KafkaReplayPlan plan = planner.plan("order.events.v1", "req-42", FROM, Optional.empty()); - - assertThat(plan.isolatedGroup()).isTrue(); - assertThat(plan.consumerGroup()).isEqualTo("replay-req-42"); - } - - @Test - void replayingAnExistingGroupRequiresAnApproval() { - assertThatThrownBy( - () -> - planner.planAgainstExistingGroup( - "order.events.v1", "order-projection", FROM, Optional.empty(), " ")) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("approval"); - } - - @Test - void anApprovedExistingGroupReplayIsNotIsolated() { - KafkaReplayPlan plan = - planner.planAgainstExistingGroup( - "order.events.v1", "order-projection", FROM, Optional.empty(), "CHG-1001"); - - assertThat(plan.isolatedGroup()).isFalse(); - assertThat(plan.consumerGroup()).isEqualTo("order-projection"); - } - - @Test - void aReplayWindowCannotEndBeforeItStarts() { - assertThatThrownBy( - () -> - planner.plan( - "order.events.v1", - "req-1", - FROM, - Optional.of(Instant.parse("2026-07-31T00:00:00Z")))) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void offsetResetWithoutAnApprovalIsRefused() { - Map applied = new LinkedHashMap<>(); - KafkaOffsetResetExecutor executor = - new KafkaOffsetResetExecutor(ticket -> false, (group, offsets) -> applied.putAll(offsets)); - - assertThatThrownBy( - () -> - executor.reset( - "order-projection", - Map.of(new TopicPartition("order.events.v1", 0), 0L), - "CHG-1001")) - .isInstanceOf(MessageAuthorizationException.class); - assertThat(applied).isEmpty(); - } - - @Test - void anApprovedOffsetResetIsApplied() { - Map applied = new LinkedHashMap<>(); - KafkaOffsetResetExecutor executor = - new KafkaOffsetResetExecutor( - "CHG-1001"::equals, (group, offsets) -> applied.putAll(offsets)); - - executor.reset( - "order-projection", Map.of(new TopicPartition("order.events.v1", 0), 42L), "CHG-1001"); - - assertThat(applied).containsEntry(new TopicPartition("order.events.v1", 0), 42L); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaSecurityConfigurerTest.java b/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaSecurityConfigurerTest.java deleted file mode 100644 index 5ce3ac2d..00000000 --- a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaSecurityConfigurerTest.java +++ /dev/null @@ -1,136 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; -import static org.assertj.core.api.Assertions.catchThrowable; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.security.BrokerCredentialProfile; -import dev.caskeleton.messaging.security.BrokerSecurityProfile; -import dev.caskeleton.messaging.security.BrokerTlsPolicy; -import dev.caskeleton.messaging.security.BrokerTrustStore; -import dev.caskeleton.messaging.security.CredentialProvider; -import dev.caskeleton.messaging.security.CredentialRuntimeRegistry; -import dev.caskeleton.messaging.security.DestinationAccessPolicy; -import java.time.Duration; -import java.time.Instant; -import java.util.List; -import java.util.Map; -import java.util.Optional; -import org.junit.jupiter.api.Test; - -/** - * What reaches the Kafka client configuration, and what is refused outright. - * - *

The JAAS entry used to carry the credential id as the user name and the resolved secret as an - * immutable string, fixed for the life of the producer. It now names the login module and nothing - * else: the user name and password are answered by {@link KafkaCredentialCallbackHandler} at each - * authentication. - */ -class KafkaSecurityConfigurerTest { - - private static final Instant NOW = Instant.parse("2026-08-14T00:00:00Z"); - - private static final BrokerCredentialProfile SCRAM = - new BrokerCredentialProfile.SaslScram("kafka-app"); - - @Test - void theJaasEntryCarriesNeitherTheUserNameNorTheSecret() { - Map properties = configure(registry(Optional.of("svc-orders")), tls(SCRAM)); - - assertThat(properties.get("sasl.jaas.config")) - .isEqualTo("org.apache.kafka.common.security.scram.ScramLoginModule required;"); - } - - @Test - void aSaslCredentialWhoseProviderNamesNoUserIsRefused() { - // given - CredentialRuntimeRegistry anonymous = registry(Optional.empty()); - - // when - Throwable thrown = catchThrowable(() -> configure(anonymous, tls(SCRAM))); - - // then - assertThat(thrown) - .isInstanceOf(MessagingConfigurationException.class) - .extracting(failure -> ((MessagingConfigurationException) failure).failure().code()) - .isEqualTo("SASL_USERNAME_MISSING"); - } - - @Test - void aTrustStoreOnABrokerWithoutTlsIsRefused() { - // given - BrokerSecurityProfile plaintext = - new BrokerSecurityProfile( - "kafka-primary", - false, - false, - true, - SCRAM, - SCRAM, - Optional.empty(), - DestinationAccessPolicy.denyAll(), - Optional.of(new BrokerTrustStore("/etc/kafka/ca.p12", "PKCS12", Optional.empty()))); - - // when - Throwable thrown = - catchThrowable(() -> configure(registry(Optional.of("svc-orders")), plaintext)); - - // then - assertThat(thrown) - .isInstanceOf(MessagingConfigurationException.class) - .extracting(failure -> ((MessagingConfigurationException) failure).failure().code()) - .isEqualTo("TRUST_STORE_REQUIRES_TLS"); - } - - @Test - void anOAuthProfileIsRefused() { - CredentialRuntimeRegistry credentials = registry(Optional.of("svc-orders")); - - BrokerCredentialProfile oauth = new BrokerCredentialProfile.OAuth2("kafka-oauth"); - // when & then - assertThatThrownBy(() -> configure(credentials, tls(oauth))) - .as("naming the mechanism without a callback handler fails at connect time instead") - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("callback handler"); - } - - private static Map configure( - CredentialRuntimeRegistry credentials, BrokerSecurityProfile profile) { - return new KafkaSecurityConfigurer(credentials, new BrokerTlsPolicy()) - .configure(profile, profile.producer(), List.of("TLSv1.3"), NOW); - } - - private static BrokerSecurityProfile tls(BrokerCredentialProfile credential) { - return new BrokerSecurityProfile( - "kafka-primary", - true, - true, - true, - credential, - credential, - Optional.empty(), - DestinationAccessPolicy.denyAll()); - } - - private static CredentialRuntimeRegistry registry(Optional username) { - return new CredentialRuntimeRegistry( - new CredentialProvider() { - @Override - public char[] resolve(String credentialId) { - return "secret".toCharArray(); - } - - @Override - public Optional expiresAt(String credentialId) { - return Optional.of(NOW.plus(Duration.ofHours(1))); - } - - @Override - public Optional username(String credentialId) { - return username; - } - }, - Duration.ofMinutes(5)); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaTransactionOrderingTest.java b/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaTransactionOrderingTest.java deleted file mode 100644 index c12f63f3..00000000 --- a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaTransactionOrderingTest.java +++ /dev/null @@ -1,192 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -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.header.MessageHeaders; -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.schema.EncodedMessage; -import java.nio.charset.StandardCharsets; -import java.time.Instant; -import java.util.List; -import java.util.Map; -import java.util.Optional; -import java.util.concurrent.atomic.AtomicBoolean; -import org.apache.kafka.clients.consumer.ConsumerGroupMetadata; -import org.apache.kafka.clients.producer.MockProducer; -import org.apache.kafka.common.serialization.ByteArraySerializer; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * Where the handler runs relative to {@code beginTransaction}. - * - *

{@code KafkaTransactionalProcessor} documents that the callback executes inside the Kafka - * transaction. It did not: the processor ran the handler and only afterwards called {@code - * sendInTransaction}, which is where {@code beginTransaction} lived. Everything the handler - * produced itself — and every external effect it triggered — was outside the transaction, so a - * handler that succeeded followed by a failed commit left its work applied with the input offsets - * unsent. - */ -class KafkaTransactionOrderingTest { - - private final RecordingProducer producer = new RecordingProducer(); - - private final KafkaTransactionalPublisher publisher = - new KafkaTransactionalPublisher( - producer, () -> new ConsumerGroupMetadata("order-projection")); - - @Test - @DisplayName("the transaction is open while the handler runs") - void theTransactionIsOpenWhileTheHandlerRuns() { - AtomicBoolean openDuringHandler = new AtomicBoolean(); - SpringKafkaTransactionalProcessor processor = processor(); - - processor - .processInTransaction( - delivery(), - ignored -> { - // The real publisher has already begun the transaction by the time the handler runs. - openDuringHandler.set(producer.calls().equals(List.of("begin"))); - return "handled"; - }) - .toCompletableFuture() - .join(); - - assertThat(openDuringHandler) - .as("the handler used to run before beginTransaction was ever called") - .isTrue(); - assertThat(producer.calls()).containsExactly("begin", "offsets", "commit"); - } - - @Test - @DisplayName("a handler failure aborts and never commits") - void aHandlerFailureAbortsAndNeverCommits() { - SpringKafkaTransactionalProcessor processor = processor(); - - assertThatThrownBy( - () -> - processor - .processInTransaction( - delivery(), - ignored -> { - throw new IllegalStateException("the projection is down"); - }) - .toCompletableFuture() - .join()) - .hasCauseInstanceOf(IllegalStateException.class); - - assertThat(producer.calls()) - .as("under read_committed nothing may become visible, and the offsets stay unsent") - .containsExactly("begin", "abort"); - } - - @Test - @DisplayName("a commit failure aborts") - void aCommitFailureAborts() { - producer.failCommit(); - SpringKafkaTransactionalProcessor processor = processor(); - - assertThatThrownBy( - () -> - processor - .processInTransaction(delivery(), ignored -> "handled") - .toCompletableFuture() - .join()) - .hasCauseInstanceOf(IllegalStateException.class); - - assertThat(producer.calls()).endsWith("abort"); - } - - /** A MockProducer that records the transaction calls in the order they happen. */ - private static final class RecordingProducer extends MockProducer { - - private final List calls = new java.util.ArrayList<>(); - - private boolean commitFails; - - private RecordingProducer() { - // The four-arg constructor with a null partitioner: this producer never partitions, because - // the assertions are about transaction call order rather than record placement. - super(true, null, new ByteArraySerializer(), new ByteArraySerializer()); - initTransactions(); - } - - private void failCommit() { - commitFails = true; - } - - private List calls() { - return List.copyOf(calls); - } - - @Override - public void beginTransaction() { - calls.add("begin"); - super.beginTransaction(); - } - - @Override - public void sendOffsetsToTransaction( - Map< - org.apache.kafka.common.TopicPartition, - org.apache.kafka.clients.consumer.OffsetAndMetadata> - offsets, - ConsumerGroupMetadata groupMetadata) { - calls.add("offsets"); - super.sendOffsetsToTransaction(offsets, groupMetadata); - } - - @Override - public void commitTransaction() { - if (commitFails) { - throw new IllegalStateException("commit failed"); - } - calls.add("commit"); - super.commitTransaction(); - } - - @Override - public void abortTransaction() { - calls.add("abort"); - super.abortTransaction(); - } - } - - private SpringKafkaTransactionalProcessor processor() { - DestinationProfile profile = KafkaContractHarness.profile(); - return new SpringKafkaTransactionalProcessor( - publisher, Map.of(profile.name().value(), profile), ignored -> Map.of()); - } - - private static KafkaTransactionalDelivery delivery() { - return new KafkaTransactionalDelivery(envelope(), List.of()); - } - - private static MessageEnvelope envelope() { - return new MessageEnvelope<>( - MessageId.newId(), - new MessageType("order.created"), - new SchemaVersion(1), - Instant.parse("2026-08-15T00:00:00Z"), - Optional.empty(), - new ProducerId("orders"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - new EncodedMessage( - "{}".getBytes(StandardCharsets.UTF_8), ContentType.JSON, Optional.empty())); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/PartitionWorkCoordinatorTest.java b/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/PartitionWorkCoordinatorTest.java deleted file mode 100644 index 3c989738..00000000 --- a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/PartitionWorkCoordinatorTest.java +++ /dev/null @@ -1,77 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import org.apache.kafka.common.TopicPartition; -import org.junit.jupiter.api.Test; - -class PartitionWorkCoordinatorTest { - - private static final TopicPartition PARTITION = new TopicPartition("orders", 0); - private static final TopicPartition OTHER = new TopicPartition("orders", 1); - - @Test - void anOrderedDestinationAllowsExactlyOneDeliveryInFlight() { - PartitionWorkCoordinator coordinator = new PartitionWorkCoordinator(1); - - assertThat(coordinator.tryAcquire(PARTITION)).isTrue(); - assertThat(coordinator.tryAcquire(PARTITION)).isFalse(); - - coordinator.release(PARTITION); - - assertThat(coordinator.tryAcquire(PARTITION)).isTrue(); - } - - @Test - void theCeilingIsPerPartitionNotPerConsumer() { - PartitionWorkCoordinator coordinator = new PartitionWorkCoordinator(1); - - assertThat(coordinator.tryAcquire(PARTITION)).isTrue(); - assertThat(coordinator.tryAcquire(OTHER)).isTrue(); - } - - @Test - void aPausedPartitionAcceptsNoNewWork() { - PartitionWorkCoordinator coordinator = new PartitionWorkCoordinator(4); - - coordinator.pause(PARTITION); - - assertThat(coordinator.tryAcquire(PARTITION)).isFalse(); - assertThat(coordinator.isPaused(PARTITION)).isTrue(); - assertThat(coordinator.pausedPartitions()).containsExactly(PARTITION); - - coordinator.resume(PARTITION); - - assertThat(coordinator.tryAcquire(PARTITION)).isTrue(); - } - - @Test - void concurrencyAboveOneIsAllowedForUnorderedDestinations() { - PartitionWorkCoordinator coordinator = new PartitionWorkCoordinator(3); - - assertThat(coordinator.tryAcquire(PARTITION)).isTrue(); - assertThat(coordinator.tryAcquire(PARTITION)).isTrue(); - assertThat(coordinator.tryAcquire(PARTITION)).isTrue(); - assertThat(coordinator.tryAcquire(PARTITION)).isFalse(); - assertThat(coordinator.inFlight(PARTITION)).isEqualTo(3); - } - - @Test - void revocationForgetsPartitionState() { - PartitionWorkCoordinator coordinator = new PartitionWorkCoordinator(1); - coordinator.tryAcquire(PARTITION); - coordinator.pause(PARTITION); - - coordinator.forget(PARTITION); - - assertThat(coordinator.isPaused(PARTITION)).isFalse(); - assertThat(coordinator.inFlight(PARTITION)).isZero(); - } - - @Test - void aZeroCeilingIsRejectedBecauseItWouldStallTheConsumer() { - assertThatThrownBy(() -> new PartitionWorkCoordinator(0)) - .isInstanceOf(IllegalArgumentException.class); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/ReservedHeaderForgeryTest.java b/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/ReservedHeaderForgeryTest.java deleted file mode 100644 index 8d194840..00000000 --- a/src/platforms/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/ReservedHeaderForgeryTest.java +++ /dev/null @@ -1,123 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -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.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.Map; -import java.util.Optional; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * What happens when message content claims a reserved header. - * - *

The canonical headers were written first and the envelope's own headers appended afterwards, - * and the consumer reads {@code lastHeader}. A row in the outbox carrying {@code msg.id} therefore - * overwrote the canonical identity on the wire — and that identity is what inbox deduplication and - * the audit trail key on, so a forged one corrupts a *different* message's dedup state. - */ -class ReservedHeaderForgeryTest { - - private final KafkaHeaderMapper mapper = new KafkaHeaderMapper(); - - @Test - @DisplayName("an application header in the reserved namespace is refused") - void aForgedReservedHeaderIsRefused() { - assertThatThrownBy( - () -> mapper.toKafkaHeaders(envelopeWithHeader(ReservedHeaders.MESSAGE_ID, "forged"))) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("restates a value the envelope already carries"); - } - - @Test - @DisplayName("a forged message type is refused too") - void aForgedMessageTypeIsRefused() { - assertThatThrownBy( - () -> - mapper.toKafkaHeaders( - envelopeWithHeader(ReservedHeaders.MESSAGE_TYPE, "other.type"))) - .isInstanceOf(MessagingConfigurationException.class); - } - - @Test - @DisplayName("an ordinary application header still travels") - void anOrdinaryApplicationHeaderStillTravels() { - assertThatCode(() -> mapper.toKafkaHeaders(envelopeWithHeader("x-tenant-hint", "acme"))) - .doesNotThrowAnyException(); - } - - @Test - @DisplayName("a malformed retry attempt is quarantined, not reset to one") - void aMalformedRetryAttemptIsQuarantined() { - assertThatThrownBy( - () -> - new KafkaRetryMetadataMapper() - .attemptOf( - envelopeWithPlatformHeader(ReservedHeaders.RETRY_ATTEMPT, "not-a-number"))) - .as("resetting to 1 restarts the budget on every redelivery, so the cap never applies") - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("retry attempt"); - } - - @Test - @DisplayName("a negative retry attempt is quarantined") - void aNegativeRetryAttemptIsQuarantined() { - assertThatThrownBy( - () -> - new KafkaRetryMetadataMapper() - .attemptOf(envelopeWithPlatformHeader(ReservedHeaders.RETRY_ATTEMPT, "-3"))) - .isInstanceOf(MessagingConfigurationException.class); - } - - /** - * Headers built through the platform factory, which is the path an outbox row takes. - * - *

{@code MessageHeaders.application} already refuses reserved names, so business code could - * never forge one. The gap was the platform factory: {@code OutboxEnvelopeFactory} promoted a - * row's arbitrary {@code Map} straight through it, and the mapper then appended - * the result after the canonical headers. - */ - private static MessageEnvelope envelopeWithHeader(String name, String value) { - return envelope(MessageHeaders.platform(Map.of(new HeaderName(name), new HeaderValue(value)))); - } - - private static MessageEnvelope envelopeWithPlatformHeader( - String name, String value) { - return envelope(MessageHeaders.platform(Map.of(new HeaderName(name), new HeaderValue(value)))); - } - - private static MessageEnvelope envelope(MessageHeaders headers) { - return new MessageEnvelope<>( - MessageId.newId(), - new MessageType("order.created"), - new SchemaVersion(1), - Instant.parse("2026-08-15T00:00:00Z"), - Optional.empty(), - new ProducerId("orders"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.empty(), - TraceContext.none(), - headers, - new EncodedMessage( - "{}".getBytes(StandardCharsets.UTF_8), ContentType.JSON, Optional.empty())); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/testFixtures/java/dev/caskeleton/messaging/kafka/KafkaContractHarness.java b/src/platforms/messaging/messaging-kafka/src/testFixtures/java/dev/caskeleton/messaging/kafka/KafkaContractHarness.java deleted file mode 100644 index 7d056699..00000000 --- a/src/platforms/messaging/messaging-kafka/src/testFixtures/java/dev/caskeleton/messaging/kafka/KafkaContractHarness.java +++ /dev/null @@ -1,370 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -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.delivery.DeliveryContext; -import dev.caskeleton.messaging.api.delivery.DeliveryGuarantee; -import dev.caskeleton.messaging.api.delivery.DeliveryMetadata; -import dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -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.destination.MessageDestination; -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.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -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.ApiTier; -import dev.caskeleton.messaging.policy.ConsumerPolicy; -import dev.caskeleton.messaging.policy.DeadLetterOrchestrator; -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.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 dev.caskeleton.messaging.transport.TransportPublishRequest; -import java.time.Duration; -import java.time.Instant; -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 org.apache.kafka.clients.producer.MockProducer; -import org.apache.kafka.clients.producer.Partitioner; -import org.apache.kafka.common.serialization.ByteArraySerializer; - -/** - * Runs the shared adapter contract against the real Kafka publish path. - * - *

{@code MockProducer} stands in for the broker, which is what makes the ambiguity case testable - * at all: a real cluster will not reliably lose a confirmation on demand, so the one behaviour that - * matters most would otherwise go unexercised. - * - *

Everything above the producer is production code. The transport, the failure classifier, and - * the dead letter orchestrator are the same objects a deployment uses, so a contract failure here - * is a real defect rather than a harness artefact. - */ -final class KafkaContractHarness implements MessagingAdapterHarness { - - private static final DestinationName SOURCE = new DestinationName("order-events"); - private static final DestinationName DEAD_LETTER = new DestinationName("order-events-dlq"); - - /** - * A manual-completion mock producer over an empty cluster. - * - *

Manual completion is what lets the harness lose a confirmation on demand. The empty cluster - * means {@code MockProducer} assigns partition zero without consulting a partitioner, which is - * why a null partitioner is safe here — the contract never asserts on partitioning. - */ - private final MockProducer producer = - new MockProducer<>( - false, (Partitioner) null, new ByteArraySerializer(), new ByteArraySerializer()); - - private final KafkaMessagingTransport transport = - new KafkaMessagingTransport("kafka-primary", 1, producer); - 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 final DeadLetterOrchestrator orchestrator = - new DeadLetterOrchestrator(new HarnessDeadLetterPublisher()); - - private boolean shuttingDown; - - static KafkaContractHarness create() { - return new KafkaContractHarness(); - } - - @Override - public String brokerName() { - return transport.brokerName(); - } - - @Override - public FaultController faults() { - return faults; - } - - @Override - public CompletionStage publish(ContractMessage message) { - CompletionStage stage = - transport - .publish( - new TransportPublishRequest( - profile(), message.envelope(), PublishOptions.defaults())) - .thenApply(result -> result.result()); - - if (faults.consumeRejectPublish()) { - // An invalid topic is definitive: the classifier must report REJECTED, not AMBIGUOUS. - producer.errorNext(new org.apache.kafka.common.errors.InvalidTopicException("no such topic")); - } else if (faults.consumeDropPublishConfirmation()) { - // A delivery timeout proves nothing about what the broker did with the record. - producer.errorNext(new org.apache.kafka.common.errors.TimeoutException("confirm lost")); - } else { - producer.completeNext(); - } - - return stage.thenApply( - result -> { - if (result.completion() == PublishCompletion.CONFIRMED) { - pending.addLast(new Pending(message.messageId(), message.envelope(), 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) { - boolean settled = - switch (outcome) { - case SUCCESS -> settleAfterSuccess(delivery); - case RETRY -> { - unsettled.add(delivery.messageId()); - redeliver(delivery); - yield false; - } - case DEAD_LETTER -> deadLetter(delivery); - }; - observed.add( - new ObservedDelivery( - delivery.messageId(), delivery.attempt(), delivery.redelivered(), settled)); - } - return List.copyOf(observed); - } - - private boolean settleAfterSuccess(Pending delivery) { - if (faults.consumeDropSettlementConfirmation()) { - unsettled.add(delivery.messageId()); - redeliver(delivery); - return false; - } - unsettled.remove(delivery.messageId()); - return true; - } - - /** - * Routes through the production orchestrator so the publish-then-settle order is the real one. - */ - private boolean deadLetter(Pending delivery) { - boolean[] settled = {false}; - orchestrator - .deadLetter( - profile(), - toDelivery(delivery), - FailureDescriptor.of( - FailureCategory.PERMANENT_BUSINESS, "CONTRACT_FAILURE", "permanent failure"), - () -> { - settled[0] = true; - unsettled.remove(delivery.messageId()); - return CompletableFuture.completedFuture(null); - }) - .toCompletableFuture() - .join(); - - if (!settled[0]) { - unsettled.add(delivery.messageId()); - redeliver(delivery); - } else { - deadLetters.add(delivery.messageId()); - } - return settled[0]; - } - - private void redeliver(Pending delivery) { - pending.addLast( - new Pending(delivery.messageId(), delivery.envelope(), delivery.attempt() + 1, true)); - } - - private MessageDelivery toDelivery(Pending delivery) { - return new MessageDelivery<>( - delivery.envelope(), - new DeliveryMetadata( - SOURCE, - delivery.attempt(), - delivery.redelivered(), - Optional.of(new KafkaPosition("order.events.v1", 0, delivery.attempt())), - Optional.of("order.events.v1-0"), - Optional.of("order-projection"), - Instant.parse("2026-08-10T09:15:00Z")), - new DeliveryContext(Instant.parse("2026-08-10T09:15:30Z"), false, "order-projection")); - } - - @Override - public List deadLettered() { - return List.copyOf(deadLetters); - } - - @Override - public List unsettled() { - return List.copyOf(unsettled); - } - - @Override - public void beginShutdown() { - shuttingDown = true; - transport.close(); - } - - @Override - public boolean isAcceptingWork() { - return !shuttingDown && transport.isAcceptingWork(); - } - - @Override - public void close() { - pending.clear(); - if (!shuttingDown) { - transport.close(); - } - } - - static DestinationProfile profile() { - return new DestinationProfile( - SOURCE, - "kafka-primary", - 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.to(DEAD_LETTER), - PayloadPolicy.defaults(), - ApiTier.M1, - false, - false, - false); - } - - /** One message waiting to be delivered. */ - private record Pending( - MessageId messageId, - MessageEnvelope envelope, - int attempt, - boolean redelivered) {} - - /** Publishes to the dead letter destination, or fails when the fault is armed. */ - private final class HarnessDeadLetterPublisher implements MessagePublisher { - - @Override - public CompletionStage publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - if (faults.deadLetterPublishFails()) { - return CompletableFuture.completedFuture( - new PublishResult( - PublishCompletion.REJECTED, - PublishEvidence.notTransmitted(), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ZERO, - Optional.of( - FailureDescriptor.of( - FailureCategory.TRANSIENT_INFRASTRUCTURE, - "DLQ_UNAVAILABLE", - "the dead letter topic could not be reached")))); - } - return CompletableFuture.completedFuture( - new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ofMillis(2), - Optional.empty())); - } - } - - /** 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/src/platforms/messaging/messaging-kafka/src/testFixtures/java/dev/caskeleton/messaging/kafka/KafkaFixtureProfiles.java b/src/platforms/messaging/messaging-kafka/src/testFixtures/java/dev/caskeleton/messaging/kafka/KafkaFixtureProfiles.java deleted file mode 100644 index f34ab3fa..00000000 --- a/src/platforms/messaging/messaging-kafka/src/testFixtures/java/dev/caskeleton/messaging/kafka/KafkaFixtureProfiles.java +++ /dev/null @@ -1,32 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.policy.PhysicalDestination; - -/** Builds destination profiles that vary only in their physical mapping. */ -final class KafkaFixtureProfiles { - - private KafkaFixtureProfiles() {} - - static DestinationProfile withTopic(String topic) { - DestinationProfile base = KafkaContractHarness.profile(); - return new DestinationProfile( - base.name(), - base.broker(), - base.kind(), - PhysicalDestination.kafkaTopic(topic), - 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/src/platforms/messaging/messaging-observability/build.gradle b/src/platforms/messaging/messaging-observability/build.gradle deleted file mode 100644 index b255ee77..00000000 --- a/src/platforms/messaging/messaging-observability/build.gradle +++ /dev/null @@ -1,11 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') - - // api: MessagingMetrics' public constructor takes a MeterRegistry, so wiring it requires - // naming the type. - api 'io.micrometer:micrometer-core' -} diff --git a/src/platforms/messaging/messaging-observability/gradle.lockfile b/src/platforms/messaging/messaging-observability/gradle.lockfile deleted file mode 100644 index dcab1d05..00000000 --- a/src/platforms/messaging/messaging-observability/gradle.lockfile +++ /dev/null @@ -1,87 +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.50.0=annotationProcessor,checkstyle,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.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -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.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-core:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-observation:1.16.8=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.6.1=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.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/CardinalityGuard.java b/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/CardinalityGuard.java deleted file mode 100644 index 91567e78..00000000 --- a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/CardinalityGuard.java +++ /dev/null @@ -1,114 +0,0 @@ -package dev.caskeleton.messaging.observation; - -import java.util.Map; -import java.util.Objects; -import java.util.Set; -import java.util.concurrent.ConcurrentHashMap; - -/** - * Caps how many distinct values a metric dimension may take. - * - *

Cardinality failures are not gradual. A tag that accidentally carries a message id looks fine - * in a test with ten messages and takes down the metrics backend in production, and by then the - * series already exist. The guard bounds each dimension at registration time and refuses the value - * that would cross the limit, so the damage is one rejected tag rather than a monitoring outage. - * - *

It fails loudly rather than silently substituting a placeholder, because a metric that quietly - * collapses distinct values is worse than one that is missing: it looks correct. - */ -public final class CardinalityGuard { - - private static final int DEFAULT_LIMIT = 200; - - private final int limitPerDimension; - private final Map> observed = new ConcurrentHashMap<>(); - - /** Creates a guard with the default limit of 200 values per dimension. */ - public CardinalityGuard() { - this(DEFAULT_LIMIT); - } - - /** - * Creates a guard with an explicit limit. - * - * @param limitPerDimension how many distinct values a dimension may take - */ - public CardinalityGuard(int limitPerDimension) { - if (limitPerDimension < 1) { - throw new IllegalArgumentException("limitPerDimension must be at least 1"); - } - this.limitPerDimension = limitPerDimension; - } - - /** - * Records a dimension value and reports whether it is within the limit. - * - * @param dimension the tag name - * @param value the tag value - * @return true when the value may be emitted - */ - public boolean admit(String dimension, String value) { - Objects.requireNonNull(dimension, "dimension must not be null"); - Objects.requireNonNull(value, "value must not be null"); - Set values = observed.computeIfAbsent(dimension, key -> ConcurrentHashMap.newKeySet()); - if (values.contains(value)) { - return true; - } - // Size-then-add was not atomic: N threads could each read size == limit - 1 and each add, so - // the configured limit was an average rather than a bound. A guard that can be exceeded under - // load is no guard — load is when it matters. - synchronized (values) { - if (values.contains(value)) { - return true; - } - if (values.size() >= limitPerDimension) { - return false; - } - values.add(value); - return true; - } - } - - /** - * Admits an entire tag set, rejecting it if any dimension would exceed its limit. - * - * @param tags the bounded dimensions - * @return true when every dimension is within its limit - */ - public boolean admit(MessagingTags tags) { - Objects.requireNonNull(tags, "tags must not be null"); - // Preflight every dimension before committing any of them. - // - // The loop used to admit each dimension as it went, so a tag set rejected on its last - // dimension had already permanently added the earlier ones — spending the budget of a bounded - // dimension on a series that was never emitted. - Map pending = tags.asMap(); - for (Map.Entry entry : pending.entrySet()) { - if (!wouldAdmit(entry.getKey(), entry.getValue())) { - return false; - } - } - boolean admitted = true; - for (Map.Entry entry : pending.entrySet()) { - admitted &= admit(entry.getKey(), entry.getValue()); - } - return admitted; - } - - /** Whether a value is already known or would still fit, without recording it. */ - private boolean wouldAdmit(String dimension, String value) { - Set values = observed.get(dimension); - return values == null || values.contains(value) || values.size() < limitPerDimension; - } - - /** - * Returns how many distinct values a dimension has taken. - * - * @param dimension the tag name - * @return the observed cardinality - */ - public int cardinality(String dimension) { - Set values = observed.get(dimension); - return values == null ? 0 : values.size(); - } -} diff --git a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/DefaultMessagingObservationConvention.java b/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/DefaultMessagingObservationConvention.java deleted file mode 100644 index 353c4b76..00000000 --- a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/DefaultMessagingObservationConvention.java +++ /dev/null @@ -1,123 +0,0 @@ -package dev.caskeleton.messaging.observation; - -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import java.util.Locale; -import java.util.Objects; -import java.util.Optional; - -/** - * Turns platform outcomes into the fixed tag vocabulary. - * - *

Centralised because the tag values are a public contract: dashboards, alert rules, and SLOs - * are written against these exact strings, so an adapter inventing its own spelling of "rejected" - * silently breaks every alert that was watching for it. The conversion lives here, once, rather - * than at each call site. - * - *

Only bounded inputs are accepted. Every parameter is an enum or a configured name, which is - * what lets {@link CardinalityGuard} bound the resulting series. - */ -public final class DefaultMessagingObservationConvention { - - /** The publish operation name. */ - public static final String PUBLISH = "publish"; - - /** The consume operation name. */ - public static final String CONSUME = "consume"; - - /** The settlement operation name. */ - public static final String SETTLE = "settle"; - - /** The dead-letter operation name. */ - public static final String DEAD_LETTER = "deadLetter"; - - /** - * Builds tags for a completed publish. - * - * @param broker the broker name - * @param destinationProfile the logical destination - * @param completion the publish outcome - * @param failure the failure classification when the publish did not confirm - * @return the tag set - */ - public MessagingTags publish( - String broker, - String destinationProfile, - PublishCompletion completion, - Optional failure) { - Objects.requireNonNull(completion, "completion must not be null"); - Objects.requireNonNull(failure, "failure must not be null"); - return new MessagingTags( - broker, - destinationProfile, - PUBLISH, - lower(completion.name()), - failure.map(category -> lower(category.name())).orElse(MessagingTags.NONE), - MessagingTags.NONE); - } - - /** - * Builds tags for a completed delivery attempt. - * - * @param broker the broker name - * @param destinationProfile the logical destination - * @param outcome the handler outcome name - * @param retryStage the retry stage, or {@link MessagingTags#NONE} on the first attempt - * @param failure the failure classification when handling failed - * @return the tag set - */ - public MessagingTags consume( - String broker, - String destinationProfile, - String outcome, - String retryStage, - Optional failure) { - Objects.requireNonNull(outcome, "outcome must not be null"); - Objects.requireNonNull(retryStage, "retryStage must not be null"); - Objects.requireNonNull(failure, "failure must not be null"); - return new MessagingTags( - broker, - destinationProfile, - CONSUME, - lower(outcome), - failure.map(category -> lower(category.name())).orElse(MessagingTags.NONE), - retryStage); - } - - /** - * Builds tags for a settlement. - * - * @param broker the broker name - * @param destinationProfile the logical destination - * @param outcome the settlement outcome name - * @return the tag set - */ - public MessagingTags settlement(String broker, String destinationProfile, String outcome) { - return MessagingTags.of(broker, destinationProfile, SETTLE, lower(outcome)); - } - - /** - * Builds tags for a dead-letter publish. - * - * @param broker the broker name - * @param destinationProfile the logical destination - * @param outcome the dead-letter outcome name - * @param failure the failure that caused the dead-letter - * @return the tag set - */ - public MessagingTags deadLetter( - String broker, String destinationProfile, String outcome, FailureCategory failure) { - Objects.requireNonNull(failure, "failure must not be null"); - return new MessagingTags( - broker, - destinationProfile, - DEAD_LETTER, - lower(outcome), - lower(failure.name()), - MessagingTags.NONE); - } - - private static String lower(String value) { - return value.toLowerCase(Locale.ROOT); - } -} diff --git a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingAuditEvent.java b/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingAuditEvent.java deleted file mode 100644 index 72f50b39..00000000 --- a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingAuditEvent.java +++ /dev/null @@ -1,45 +0,0 @@ -package dev.caskeleton.messaging.observation; - -import java.time.Instant; -import java.util.Map; -import java.util.Objects; - -/** - * A record of a privileged messaging operation. - * - *

Audit covers the operations that change state an application cannot: replay, redrive, offset - * reset, purge, and delete. The subject is the operator identity and the details are passed through - * {@link MessagingRedactor}, so an audit trail proves who did what without becoming a second copy - * of the payload. - * - * @param operation the privileged operation - * @param subject the operator or service identity that requested it - * @param destination the logical destination affected - * @param approvalTicket the approval reference - * @param occurredAt when it happened - * @param details additional sanitized context - */ -public record MessagingAuditEvent( - String operation, - String subject, - String destination, - String approvalTicket, - Instant occurredAt, - Map details) { - - public MessagingAuditEvent { - Objects.requireNonNull(occurredAt, "occurredAt must not be null"); - Objects.requireNonNull(details, "details must not be null"); - requireText(operation, "operation"); - requireText(subject, "subject"); - requireText(destination, "destination"); - requireText(approvalTicket, "approvalTicket"); - details = Map.copyOf(details); - } - - private static void requireText(String value, String field) { - if (value == null || value.isBlank()) { - throw new IllegalArgumentException(field + " must not be blank"); - } - } -} diff --git a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingAuditSink.java b/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingAuditSink.java deleted file mode 100644 index e3f92e56..00000000 --- a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingAuditSink.java +++ /dev/null @@ -1,56 +0,0 @@ -package dev.caskeleton.messaging.observation; - -import java.util.List; -import java.util.Objects; -import java.util.concurrent.CopyOnWriteArrayList; - -/** - * Where audit records for privileged operations are written. - * - *

Separate from metrics and from application logs. An audit trail answers "who authorised this - * destructive operation", which is a different retention, access, and integrity requirement from - * "how slow was publish yesterday"; mixing them means either the audit gets dropped with the - * metrics or the metrics inherit the audit's retention cost. - * - *

Every record has already passed {@link MessagingRedactor}, so an audit trail proves who did - * what without becoming a second copy of the payload. - */ -public interface MessagingAuditSink { - - /** - * Records one privileged operation. - * - * @param event the sanitized audit record - */ - void record(MessagingAuditEvent event); - - /** - * Returns a sink that keeps events in memory, for tests and for a deployment that has no external - * audit store yet. - * - * @return an in-memory sink - */ - static InMemory inMemory() { - return new InMemory(); - } - - /** An in-memory sink whose contents can be asserted on. */ - final class InMemory implements MessagingAuditSink { - - private final List events = new CopyOnWriteArrayList<>(); - - @Override - public void record(MessagingAuditEvent event) { - events.add(Objects.requireNonNull(event, "event must not be null")); - } - - /** - * Returns the recorded events in order. - * - * @return the recorded events - */ - public List events() { - return List.copyOf(events); - } - } -} diff --git a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingMetrics.java b/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingMetrics.java deleted file mode 100644 index 95790619..00000000 --- a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingMetrics.java +++ /dev/null @@ -1,172 +0,0 @@ -package dev.caskeleton.messaging.observation; - -import io.micrometer.core.instrument.MeterRegistry; -import io.micrometer.core.instrument.Tag; -import io.micrometer.core.instrument.Tags; -import io.micrometer.core.instrument.Timer; -import java.time.Duration; -import java.util.ArrayList; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.concurrent.ConcurrentHashMap; -import java.util.concurrent.atomic.AtomicLong; -import java.util.concurrent.atomic.LongAdder; - -/** - * The Micrometer implementation of the observation seam. - * - *

Every tag set passes the {@link CardinalityGuard} before a meter is created. That ordering is - * the whole point: a meter registry never forgets a series, so a single tag carrying a message id - * permanently inflates the backend. Refused tag sets are counted under a fixed {@code - * messaging.tags.rejected} counter, which makes the rejection visible without creating the series - * that caused it. - * - *

Logical messages and physical attempts are separate meters. One message redelivered four times - * is one publish and five attempts; a single counter would make a redelivery storm read as traffic - * growth and hide the incident. - */ -public final class MessagingMetrics implements MessagingObservation { - - /** Timer for one publish call, from admission to outcome. */ - public static final String PUBLISH_TIMER = "messaging.publish"; - - /** Timer for one delivery attempt, covering the handler only. */ - public static final String DELIVERY_TIMER = "messaging.delivery"; - - /** Counter of logical messages delivered, incremented only on the first attempt. */ - public static final String MESSAGE_COUNTER = "messaging.messages"; - - /** Counter of settlement outcomes. */ - public static final String SETTLEMENT_COUNTER = "messaging.settlements"; - - /** Gauge of the observed consumer backlog. */ - public static final String BACKLOG_GAUGE = "messaging.backlog"; - - /** Counter of tag sets refused by the cardinality guard. */ - public static final String REJECTED_TAGS_COUNTER = "messaging.tags.rejected"; - - private final MeterRegistry registry; - private final CardinalityGuard guard; - private final MessagingRedactor redactor; - private final Map backlogs = new ConcurrentHashMap<>(); - private final LongAdder rejectedTagSets = new LongAdder(); - - /** - * Creates the metrics binding. - * - * @param registry the meter registry - * @param guard the cardinality guard applied before any meter is created - * @param redactor the redactor applied to diagnostic values - */ - public MessagingMetrics( - MeterRegistry registry, CardinalityGuard guard, MessagingRedactor redactor) { - this.registry = Objects.requireNonNull(registry, "registry must not be null"); - this.guard = Objects.requireNonNull(guard, "guard must not be null"); - this.redactor = Objects.requireNonNull(redactor, "redactor must not be null"); - registry.gauge(REJECTED_TAGS_COUNTER, rejectedTagSets, LongAdder::sum); - } - - @Override - public void recordPublish(MessagingTags tags, Duration elapsed) { - Objects.requireNonNull(elapsed, "elapsed must not be null"); - admitted(tags) - .ifPresent(micrometerTags -> timer(PUBLISH_TIMER, micrometerTags).record(elapsed)); - } - - @Override - public void recordDelivery(MessagingTags tags, Duration elapsed, int attempt) { - Objects.requireNonNull(elapsed, "elapsed must not be null"); - if (attempt < 1) { - throw new IllegalArgumentException("attempt counts the first delivery as 1"); - } - admitted(tags) - .ifPresent( - micrometerTags -> { - timer(DELIVERY_TIMER, micrometerTags).record(elapsed); - // Only the first attempt counts as a logical message; later attempts are the same - // message arriving again, and counting them would inflate throughput during a storm. - if (attempt == 1) { - registry.counter(MESSAGE_COUNTER, micrometerTags).increment(); - } - }); - } - - @Override - public void recordSettlement(MessagingTags tags) { - admitted(tags) - .ifPresent( - micrometerTags -> registry.counter(SETTLEMENT_COUNTER, micrometerTags).increment()); - } - - @Override - public void recordBacklog(MessagingTags tags, long messages) { - admitted(tags) - .ifPresent( - micrometerTags -> - backlogs - .computeIfAbsent( - micrometerTags, - key -> - registry.gauge(BACKLOG_GAUGE, key, new AtomicLong(), AtomicLong::get)) - .set(messages)); - } - - @Override - public void recordDiagnostics(MessagingTags tags, Map diagnostics) { - Objects.requireNonNull(tags, "tags must not be null"); - Objects.requireNonNull(diagnostics, "diagnostics must not be null"); - // Redact before anything else touches the values. Diagnostics are the one place where a caller - // can pass arbitrary keys, so this is where a secret would otherwise reach the backend. - Map safe = redactor.sanitize(diagnostics); - // The value never becomes a tag. - // - // It used to: every diagnostic key and value was attached to a counter, behind a guard that - // only bounded the base dimensions. One unique message id, exception message or URL per - // request created one meter series per request — permanently, in the backend and in this - // process's heap — and the redactor only masks keys it recognises, so free-form text carried - // whatever it carried. - // - // What stays is the shape: which diagnostic keys occurred, counted against the bounded base - // dimensions. The values belong in a structured log or a trace event, where they are bounded - // by retention rather than by cardinality. - admitted(tags) - .ifPresent( - micrometerTags -> - safe.keySet() - .forEach( - key -> { - if (guard.admit("diagnostic", key)) { - registry - .counter( - "messaging.diagnostics", - micrometerTags.and(Tag.of("diagnostic", key))) - .increment(); - } - })); - } - - /** - * Returns how many tag sets the cardinality guard refused. - * - * @return the rejected tag set count - */ - public long rejectedTagSets() { - return rejectedTagSets.sum(); - } - - private java.util.Optional admitted(MessagingTags tags) { - Objects.requireNonNull(tags, "tags must not be null"); - if (!guard.admit(tags)) { - rejectedTagSets.increment(); - return java.util.Optional.empty(); - } - List micrometerTags = new ArrayList<>(); - tags.asMap().forEach((key, value) -> micrometerTags.add(Tag.of(key, value))); - return java.util.Optional.of(Tags.of(micrometerTags)); - } - - private Timer timer(String name, Tags tags) { - return Timer.builder(name).tags(tags).publishPercentileHistogram().register(registry); - } -} diff --git a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingObservation.java b/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingObservation.java deleted file mode 100644 index bcd2615c..00000000 --- a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingObservation.java +++ /dev/null @@ -1,56 +0,0 @@ -package dev.caskeleton.messaging.observation; - -import java.time.Duration; -import java.util.Map; - -/** - * The platform's observation seam. - * - *

Logical messages and physical delivery attempts are recorded separately. One logical message - * that was redelivered four times is one message and five attempts; collapsing them makes a - * redelivery storm look like traffic growth. - */ -public interface MessagingObservation { - - /** - * Records one completed publish. - * - * @param tags the bounded dimensions - * @param elapsed how long the publish took - */ - void recordPublish(MessagingTags tags, Duration elapsed); - - /** - * Records one completed delivery attempt. - * - * @param tags the bounded dimensions - * @param elapsed how long handling took - * @param attempt the attempt number, counting the first delivery as one - */ - void recordDelivery(MessagingTags tags, Duration elapsed, int attempt); - - /** - * Records one settlement outcome. - * - * @param tags the bounded dimensions - */ - void recordSettlement(MessagingTags tags); - - /** - * Records a consumer lag or backlog sample. - * - * @param tags the bounded dimensions - * @param messages the observed backlog - */ - void recordBacklog(MessagingTags tags, long messages); - - /** - * Emits a structured diagnostic event. - * - *

Implementations pass the map through {@link MessagingRedactor} before it leaves the process. - * - * @param tags the bounded dimensions - * @param diagnostics the raw diagnostic values - */ - void recordDiagnostics(MessagingTags tags, Map diagnostics); -} diff --git a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingRedactor.java b/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingRedactor.java deleted file mode 100644 index 190cc50b..00000000 --- a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingRedactor.java +++ /dev/null @@ -1,105 +0,0 @@ -package dev.caskeleton.messaging.observation; - -import java.util.LinkedHashMap; -import java.util.Locale; -import java.util.Map; -import java.util.Set; - -/** - * Strips identity and secrets from diagnostic maps before they are logged or tagged. - * - *

This is a denylist of keys that must never leave the process, not an allowlist, because - * diagnostic maps are assembled ad hoc at call sites and an allowlist would quietly drop the useful - * half. Two categories are removed. Secrets, for the obvious reason. And per-message identity — - * message ids, keys, offsets, delivery tags — because those are what turn a bounded metric into one - * series per message, and a support log into a re-identification surface. - */ -public final class MessagingRedactor { - - private static final String REDACTED = "[redacted]"; - - private static final Set DENIED_KEYS = - Set.of( - "messageid", - "msg.id", - "correlationid", - "causationid", - "partitionkey", - "orderingkey", - "key", - "offset", - "deliverytag", - "sequence", - "payload", - "body", - "data", - "authorization", - "proxy-authorization", - "cookie", - "set-cookie", - "access_token", - "refresh_token", - "api_key", - "apikey", - "password", - "client_secret", - "credential", - "secret", - "token", - "exceptionmessage", - "stacktrace"); - - /** - * Removes denied entries from a diagnostic map. - * - * @param diagnostics the raw diagnostic values - * @return a copy containing only permitted entries - */ - public Map sanitize(Map diagnostics) { - if (diagnostics == null || diagnostics.isEmpty()) { - return Map.of(); - } - Map sanitized = new LinkedHashMap<>(); - for (Map.Entry entry : diagnostics.entrySet()) { - String key = entry.getKey(); - if (key == null || isDenied(key)) { - continue; - } - sanitized.put(key, entry.getValue()); - } - return Map.copyOf(sanitized); - } - - /** - * Replaces denied values with a marker instead of dropping the key. - * - *

Useful where the presence of a field is itself the diagnostic signal. - * - * @param diagnostics the raw diagnostic values - * @return a copy with denied values masked - */ - public Map mask(Map diagnostics) { - if (diagnostics == null || diagnostics.isEmpty()) { - return Map.of(); - } - Map masked = new LinkedHashMap<>(); - for (Map.Entry entry : diagnostics.entrySet()) { - String key = entry.getKey(); - if (key == null) { - continue; - } - masked.put(key, isDenied(key) ? REDACTED : entry.getValue()); - } - return Map.copyOf(masked); - } - - /** - * Reports whether a diagnostic key is denied. - * - * @param key the diagnostic key in any case - * @return true when the key must not be emitted - */ - public boolean isDenied(String key) { - return key != null && DENIED_KEYS.contains(key.toLowerCase(Locale.ROOT)); - } -} diff --git a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingTags.java b/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingTags.java deleted file mode 100644 index 06b00f90..00000000 --- a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingTags.java +++ /dev/null @@ -1,71 +0,0 @@ -package dev.caskeleton.messaging.observation; - -import java.util.LinkedHashMap; -import java.util.Map; -import java.util.Objects; - -/** - * The complete, closed set of metric dimensions the platform emits. - * - *

It is a fixed record rather than an open map on purpose. Every field here is bounded by - * configuration or by an enum, so the cardinality of the metric is known before it is ever scraped. - * Message ids, partition keys, tenant ids, and offsets are all deliberately absent: each of them is - * unbounded at runtime and would multiply every series by the message volume. - * - * @param broker the broker name - * @param destinationProfile the logical destination name - * @param operation the platform operation, such as publish or consume - * @param outcome the stable outcome name - * @param failureCategory the stable failure classification, or {@code none} - * @param retryStage the retry stage, or {@code none} - */ -public record MessagingTags( - String broker, - String destinationProfile, - String operation, - String outcome, - String failureCategory, - String retryStage) { - - /** The value used where a dimension does not apply. */ - public static final String NONE = "none"; - - public MessagingTags { - Objects.requireNonNull(broker, "broker must not be null"); - Objects.requireNonNull(destinationProfile, "destinationProfile must not be null"); - Objects.requireNonNull(operation, "operation must not be null"); - Objects.requireNonNull(outcome, "outcome must not be null"); - Objects.requireNonNull(failureCategory, "failureCategory must not be null"); - Objects.requireNonNull(retryStage, "retryStage must not be null"); - } - - /** - * Builds tags for a successful operation. - * - * @param broker the broker name - * @param destinationProfile the logical destination - * @param operation the operation name - * @param outcome the outcome name - * @return the tag set - */ - public static MessagingTags of( - String broker, String destinationProfile, String operation, String outcome) { - return new MessagingTags(broker, destinationProfile, operation, outcome, NONE, NONE); - } - - /** - * Returns the tags as an ordered map for a metrics backend. - * - * @return the tag map - */ - public Map asMap() { - Map tags = new LinkedHashMap<>(); - tags.put("broker", broker); - tags.put("destinationProfile", destinationProfile); - tags.put("operation", operation); - tags.put("outcome", outcome); - tags.put("failureCategory", failureCategory); - tags.put("retryStage", retryStage); - return Map.copyOf(tags); - } -} diff --git a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingTracer.java b/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingTracer.java deleted file mode 100644 index 9e81afac..00000000 --- a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/MessagingTracer.java +++ /dev/null @@ -1,96 +0,0 @@ -package dev.caskeleton.messaging.observation; - -import dev.caskeleton.messaging.api.TraceContext; -import dev.caskeleton.messaging.api.header.HeaderName; -import dev.caskeleton.messaging.api.header.HeaderValue; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; - -/** - * Carries trace context across the broker hop. - * - *

Messaging breaks in-process trace propagation: the publish and the consume happen in different - * processes, often minutes apart, so the only way the two spans meet is if the context travels in - * the message headers. W3C {@code traceparent}/{@code tracestate} are used rather than a private - * format so that a non-Java consumer, or a broker-side tool, can still join the trace. - * - *

The consume side is deliberately a link rather than a child span in the general case. - * A batch consume can draw messages from many unrelated traces, and forcing them into one parent - * would invent a causal relationship that does not exist. Retry and dead-letter hops keep the - * original trace so a message's whole journey stays one story. - */ -public final class MessagingTracer { - - /** The W3C trace context header. */ - public static final String TRACEPARENT = "traceparent"; - - /** The W3C trace state header. */ - public static final String TRACESTATE = "tracestate"; - - /** The W3C baggage header. */ - public static final String BAGGAGE = "baggage"; - - /** - * Writes trace context into platform headers. - * - *

Written as platform headers, not application headers, so that an application cannot - * overwrite them and silently sever the trace. - * - * @param context the trace context to propagate - * @param headers the headers to extend - * @return the headers including trace context - */ - public MessageHeaders inject(TraceContext context, MessageHeaders headers) { - Objects.requireNonNull(context, "context must not be null"); - Objects.requireNonNull(headers, "headers must not be null"); - if (context.traceparent().isEmpty()) { - return headers; - } - - Map values = new java.util.LinkedHashMap<>(headers.asMap()); - values.put(new HeaderName(TRACEPARENT), new HeaderValue(context.traceparent().get())); - context - .tracestate() - .ifPresent(state -> values.put(new HeaderName(TRACESTATE), new HeaderValue(state))); - context.baggage().ifPresent(bag -> values.put(new HeaderName(BAGGAGE), new HeaderValue(bag))); - return MessageHeaders.platform(values); - } - - /** - * Reads trace context out of received headers. - * - * @param headers the received headers - * @return the propagated context, or {@link TraceContext#none()} when none was carried - */ - public TraceContext extract(MessageHeaders headers) { - Objects.requireNonNull(headers, "headers must not be null"); - Optional traceparent = headerValue(headers, TRACEPARENT); - if (traceparent.isEmpty()) { - return TraceContext.none(); - } - return new TraceContext( - traceparent, headerValue(headers, TRACESTATE), headerValue(headers, BAGGAGE)); - } - - /** - * Reports whether a consume should link to the publish trace rather than continue it. - * - *

A single delivery continues the producer's trace. A batch links instead, because a batch can - * span unrelated traces and picking one of them as the parent would be a fabrication. - * - * @param batchSize the number of messages handled together - * @return true when the consume span should use a link - */ - public boolean shouldLinkRatherThanContinue(int batchSize) { - if (batchSize < 1) { - throw new IllegalArgumentException("batchSize must be at least 1"); - } - return batchSize > 1; - } - - private static Optional headerValue(MessageHeaders headers, String name) { - return headers.find(name).map(HeaderValue::value); - } -} diff --git a/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/MessagingMetricCardinalityTest.java b/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/MessagingMetricCardinalityTest.java deleted file mode 100644 index 6c876962..00000000 --- a/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/MessagingMetricCardinalityTest.java +++ /dev/null @@ -1,110 +0,0 @@ -package dev.caskeleton.messaging.observation; - -import static org.assertj.core.api.Assertions.assertThat; - -import io.micrometer.core.instrument.simple.SimpleMeterRegistry; -import java.time.Duration; -import java.util.Map; -import org.junit.jupiter.api.Test; - -class MessagingMetricCardinalityTest { - - private final SimpleMeterRegistry registry = new SimpleMeterRegistry(); - - private MessagingMetrics metrics(int limit) { - return new MessagingMetrics(registry, new CardinalityGuard(limit), new MessagingRedactor()); - } - - private static MessagingTags tagsFor(String destination) { - return MessagingTags.of("kafka", destination, "publish", "confirmed"); - } - - @Test - void aBoundedTagSetProducesOneSeries() { - metrics(10).recordPublish(tagsFor("orders.v1"), Duration.ofMillis(12)); - - assertThat(registry.find(MessagingMetrics.PUBLISH_TIMER).timers()).hasSize(1); - } - - @Test - void aDimensionThatExceedsItsLimitCreatesNoFurtherSeries() { - MessagingMetrics metrics = metrics(2); - - metrics.recordPublish(tagsFor("a"), Duration.ofMillis(1)); - metrics.recordPublish(tagsFor("b"), Duration.ofMillis(1)); - metrics.recordPublish(tagsFor("c"), Duration.ofMillis(1)); - - assertThat(registry.find(MessagingMetrics.PUBLISH_TIMER).timers()) - .as("a meter registry never forgets a series, so the third one must never be created") - .hasSize(2); - } - - @Test - void aRefusedTagSetIsCountedSoTheRejectionIsVisible() { - MessagingMetrics metrics = metrics(1); - - metrics.recordPublish(tagsFor("a"), Duration.ofMillis(1)); - metrics.recordPublish(tagsFor("b"), Duration.ofMillis(1)); - - assertThat(metrics.rejectedTagSets()).isEqualTo(1); - } - - @Test - void aRedeliveryCountsAsAnAttemptButNotAsANewMessage() { - MessagingMetrics metrics = metrics(10); - MessagingTags tags = MessagingTags.of("kafka", "orders.v1", "consume", "handled"); - - metrics.recordDelivery(tags, Duration.ofMillis(5), 1); - metrics.recordDelivery(tags, Duration.ofMillis(5), 2); - metrics.recordDelivery(tags, Duration.ofMillis(5), 3); - - assertThat(registry.find(MessagingMetrics.DELIVERY_TIMER).timer().count()) - .as("three physical attempts") - .isEqualTo(3); - assertThat(registry.find(MessagingMetrics.MESSAGE_COUNTER).counter().count()) - .as("one logical message; counting redeliveries would make a storm look like growth") - .isEqualTo(1.0); - } - - @Test - void theTagVocabularyIsClosed() { - assertThat(tagsFor("orders.v1").asMap()) - .containsOnlyKeys( - "broker", - "destinationProfile", - "operation", - "outcome", - "failureCategory", - "retryStage"); - } - - @Test - void noTagCarriesPerMessageIdentity() { - Map tags = tagsFor("orders.v1").asMap(); - - assertThat(tags.keySet()) - .as("message id, key, offset, and tenant are all unbounded at runtime") - .doesNotContain("messageId", "key", "partitionKey", "offset", "tenantId"); - } - - @Test - void aBacklogSampleReplacesRatherThanAccumulates() { - MessagingMetrics metrics = metrics(10); - MessagingTags tags = MessagingTags.of("kafka", "orders.v1", "consume", "lag"); - - metrics.recordBacklog(tags, 100); - metrics.recordBacklog(tags, 40); - - assertThat(registry.find(MessagingMetrics.BACKLOG_GAUGE).gauge().value()).isEqualTo(40.0); - } - - @Test - void anAttemptNumberBelowOneIsRejectedBecauseTheFirstDeliveryIsAttemptOne() { - MessagingMetrics metrics = metrics(10); - MessagingTags tags = MessagingTags.of("kafka", "orders.v1", "consume", "handled"); - - org.assertj.core.api.Assertions.assertThatThrownBy( - () -> metrics.recordDelivery(tags, Duration.ofMillis(1), 0)) - .isInstanceOf(IllegalArgumentException.class); - } -} diff --git a/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/MessagingRedactorTest.java b/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/MessagingRedactorTest.java deleted file mode 100644 index 1876c387..00000000 --- a/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/MessagingRedactorTest.java +++ /dev/null @@ -1,82 +0,0 @@ -package dev.caskeleton.messaging.observation; - -import static org.assertj.core.api.Assertions.assertThat; - -import java.util.LinkedHashMap; -import java.util.Map; -import org.junit.jupiter.api.Test; - -class MessagingRedactorTest { - - private final MessagingRedactor redactor = new MessagingRedactor(); - - @Test - void removesMessageIdentityAndSecretsFromDiagnosticMap() { - Map sanitized = - redactor.sanitize( - Map.of( - "messageId", "0190f4aa-0000-7000-8000-000000000001", - "Authorization", "Bearer secret", - "destinationProfile", "order-events")); - - assertThat(sanitized) - .containsEntry("destinationProfile", "order-events") - .doesNotContainKeys("messageId", "Authorization"); - } - - @Test - void deniesKeysRegardlessOfCase() { - Map sanitized = - redactor.sanitize(Map.of("MESSAGEID", "x", "Partitionkey", "acct-1", "broker", "kafka")); - - assertThat(sanitized).containsOnlyKeys("broker"); - } - - @Test - void removesBrokerPositionDetailThatWouldExplodeCardinality() { - Map diagnostics = new LinkedHashMap<>(); - diagnostics.put("offset", "918273"); - diagnostics.put("deliveryTag", "44"); - diagnostics.put("sequence", "7"); - diagnostics.put("operation", "consume"); - - assertThat(redactor.sanitize(diagnostics)).containsOnlyKeys("operation"); - } - - @Test - void removesPayloadAndStackTrace() { - Map sanitized = - redactor.sanitize( - Map.of( - "payload", "{\"card\":\"4111111111111111\"}", - "stackTrace", "java.lang.RuntimeException", - "exceptionMessage", "failed for user bob@example.com", - "outcome", "REJECTED")); - - assertThat(sanitized).containsOnlyKeys("outcome"); - } - - @Test - void maskKeepsTheKeyButNotTheValue() { - Map masked = - redactor.mask(Map.of("messageId", "0190f4aa", "broker", "kafka-primary")); - - assertThat(masked).containsEntry("messageId", "[redacted]"); - assertThat(masked).containsEntry("broker", "kafka-primary"); - } - - @Test - void tagsCarryOnlyBoundedDimensions() { - MessagingTags tags = MessagingTags.of("kafka-primary", "order-events", "publish", "CONFIRMED"); - - assertThat(tags.asMap()) - .containsOnlyKeys( - "broker", - "destinationProfile", - "operation", - "outcome", - "failureCategory", - "retryStage"); - assertThat(tags.asMap()).doesNotContainKey("messageId"); - } -} diff --git a/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/MessagingSecretLeakTest.java b/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/MessagingSecretLeakTest.java deleted file mode 100644 index 467203ff..00000000 --- a/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/MessagingSecretLeakTest.java +++ /dev/null @@ -1,173 +0,0 @@ -package dev.caskeleton.messaging.observation; - -import static org.assertj.core.api.Assertions.assertThat; - -import io.micrometer.core.instrument.Meter; -import io.micrometer.core.instrument.Tag; -import io.micrometer.core.instrument.simple.SimpleMeterRegistry; -import java.time.Instant; -import java.util.LinkedHashMap; -import java.util.List; -import java.util.Map; -import org.junit.jupiter.api.Test; - -/** - * Proves that the values an operator can reach — metric tags and audit details — cannot carry a - * secret or a per-message identifier, whatever a call site passes in. - */ -class MessagingSecretLeakTest { - - private static final List FORBIDDEN = - List.of( - "Authorization", - "Proxy-Authorization", - "Cookie", - "Set-Cookie", - "access_token", - "refresh_token", - "api_key", - "password", - "client_secret"); - - private final SimpleMeterRegistry registry = new SimpleMeterRegistry(); - private final MessagingRedactor redactor = new MessagingRedactor(); - - @Test - void everyForbiddenHeaderNameIsDenied() { - assertThat(FORBIDDEN).allSatisfy(name -> assertThat(redactor.isDenied(name)).isTrue()); - } - - @Test - void aDenialIsCaseInsensitiveBecauseHeaderCasingIsNotStable() { - assertThat(redactor.isDenied("AUTHORIZATION")).isTrue(); - assertThat(redactor.isDenied("authorization")).isTrue(); - assertThat(redactor.isDenied("Authorization")).isTrue(); - } - - @Test - void perMessageIdentityIsStrippedAlongsideSecrets() { - Map raw = new LinkedHashMap<>(); - raw.put("messageId", "0199-abcd"); - raw.put("partitionKey", "customer-42"); - raw.put("offset", "884213"); - raw.put("broker", "kafka"); - - assertThat(redactor.sanitize(raw)) - .as("identity is what turns a bounded metric into one series per message") - .containsExactly(Map.entry("broker", "kafka")); - } - - @Test - void payloadAndExceptionDetailNeverSurvive() { - Map raw = - Map.of( - "payload", "{\"pan\":\"4111111111111111\"}", - "stackTrace", "java.lang.RuntimeException: ...", - "exceptionMessage", "user bob@example.com not found", - "outcome", "rejected"); - - assertThat(redactor.sanitize(raw)).containsOnlyKeys("outcome"); - } - - @Test - void aSecretPassedAsADiagnosticNeverReachesTheMeterRegistry() { - MessagingMetrics metrics = new MessagingMetrics(registry, new CardinalityGuard(100), redactor); - - metrics.recordDiagnostics( - MessagingTags.of("kafka", "orders.v1", "publish", "rejected"), - Map.of("password", "hunter2", "reason", "unroutable")); - - List emitted = - registry.getMeters().stream() - .map(Meter::getId) - .flatMap(id -> id.getTags().stream()) - .map(Tag::getValue) - .toList(); - - // No diagnostic value reaches the registry at all — not the secret, and not the innocuous one - // either. A value tag is one meter series per distinct value, permanently, and the redactor - // only masks keys it recognises: free-form text carries whatever it carries. - assertThat(emitted).doesNotContain("hunter2").doesNotContain("unroutable"); - assertThat( - registry.getMeters().stream() - .map(Meter::getId) - .flatMap(id -> id.getTags().stream()) - .filter(tag -> tag.getKey().equals("diagnostic")) - .map(Tag::getValue) - .toList()) - .as("the shape is kept: which diagnostic keys occurred, against bounded base dimensions") - .contains("reason"); - } - - @Test - @org.junit.jupiter.api.DisplayName("ten thousand distinct diagnostic values create no new series") - void distinctDiagnosticValuesCreateNoNewSeries() { - MessagingMetrics metrics = new MessagingMetrics(registry, new CardinalityGuard(100), redactor); - MessagingTags tags = MessagingTags.of("kafka", "orders.v1", "publish", "rejected"); - - for (int index = 0; index < 10_000; index++) { - metrics.recordDiagnostics(tags, Map.of("reason", "unique-value-" + index)); - } - - assertThat( - registry.getMeters().stream() - .filter(meter -> meter.getId().getName().equals("messaging.diagnostics")) - .toList()) - .as("one unique message id per request used to create one meter series per request") - .hasSize(1); - } - - @Test - @org.junit.jupiter.api.DisplayName("concurrent admission never exceeds the configured limit") - void concurrentAdmissionNeverExceedsTheLimit() throws Exception { - CardinalityGuard guard = new CardinalityGuard(10); - java.util.concurrent.ExecutorService pool = - java.util.concurrent.Executors.newFixedThreadPool(8); - try { - java.util.List> work = - java.util.stream.IntStream.range(0, 200) - .>mapToObj( - index -> () -> guard.admit("destination", "d-" + index)) - .toList(); - for (java.util.concurrent.Future future : pool.invokeAll(work)) { - future.get(); - } - } finally { - pool.shutdownNow(); - } - - assertThat(guard.cardinality("destination")) - .as("size-then-add is not atomic, so the limit was an average rather than a bound") - .isEqualTo(10); - } - - @Test - void maskingKeepsThePresenceSignalWithoutTheValue() { - Map masked = redactor.mask(Map.of("authorization", "Bearer abc.def.ghi")); - - assertThat(masked).containsOnlyKeys("authorization"); - assertThat(masked.get("authorization")).isEqualTo("[redacted]"); - } - - @Test - void anAuditEventCarriesTheOperatorButNotThePayload() { - MessagingAuditSink.InMemory sink = MessagingAuditSink.inMemory(); - - sink.record( - new MessagingAuditEvent( - "redrive", - "ops@example.com", - "orders.v1", - "CHG-1042", - Instant.parse("2026-08-10T09:15:00Z"), - redactor.sanitize(Map.of("payload", "secret", "count", "12")))); - - assertThat(sink.events()) - .singleElement() - .satisfies( - event -> { - assertThat(event.subject()).isEqualTo("ops@example.com"); - assertThat(event.details()).containsOnlyKeys("count"); - }); - } -} diff --git a/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/MessagingTraceLinkTest.java b/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/MessagingTraceLinkTest.java deleted file mode 100644 index 9e695d67..00000000 --- a/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/MessagingTraceLinkTest.java +++ /dev/null @@ -1,88 +0,0 @@ -package dev.caskeleton.messaging.observation; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.TraceContext; -import dev.caskeleton.messaging.api.header.HeaderName; -import dev.caskeleton.messaging.api.header.HeaderValue; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import java.util.Map; -import java.util.Optional; -import org.junit.jupiter.api.Test; - -class MessagingTraceLinkTest { - - private static final String TRACEPARENT = - "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"; - - private final MessagingTracer tracer = new MessagingTracer(); - - @Test - void tracecontextSurvivesTheBrokerHop() { - TraceContext original = TraceContext.of(TRACEPARENT); - - MessageHeaders carried = tracer.inject(original, MessageHeaders.empty()); - TraceContext recovered = tracer.extract(carried); - - assertThat(recovered.traceparent()) - .as("publish and consume are different processes, so the context has to travel in-band") - .hasValue(TRACEPARENT); - } - - @Test - void traceStateAndBaggageAreCarriedToo() { - TraceContext original = - new TraceContext( - Optional.of(TRACEPARENT), Optional.of("vendor=abc"), Optional.of("tier=gold")); - - TraceContext recovered = tracer.extract(tracer.inject(original, MessageHeaders.empty())); - - assertThat(recovered.tracestate()).hasValue("vendor=abc"); - assertThat(recovered.baggage()).hasValue("tier=gold"); - } - - @Test - void traceHeadersAreWrittenAsPlatformHeaders() { - MessageHeaders carried = tracer.inject(TraceContext.of(TRACEPARENT), MessageHeaders.empty()); - - assertThat(carried.find(MessagingTracer.TRACEPARENT)) - .as("an application-writable trace header could be overwritten, severing the trace") - .isPresent(); - } - - @Test - void existingHeadersArePreservedAlongsideTheTrace() { - MessageHeaders existing = - MessageHeaders.application( - Map.of(new HeaderName("x-tenant-tier"), new HeaderValue("gold"))); - - MessageHeaders carried = tracer.inject(TraceContext.of(TRACEPARENT), existing); - - assertThat(carried.find("x-tenant-tier")).hasValue(new HeaderValue("gold")); - assertThat(carried.find(MessagingTracer.TRACEPARENT)).isPresent(); - } - - @Test - void aMessageWithNoTraceExtractsToNone() { - assertThat(tracer.extract(MessageHeaders.empty())).isEqualTo(TraceContext.none()); - } - - @Test - void injectingAnInactiveTraceAddsNothing() { - MessageHeaders carried = tracer.inject(TraceContext.none(), MessageHeaders.empty()); - - assertThat(carried.size()).isZero(); - } - - @Test - void aSingleDeliveryContinuesTheProducerTrace() { - assertThat(tracer.shouldLinkRatherThanContinue(1)).isFalse(); - } - - @Test - void aBatchLinksBecauseItCanSpanUnrelatedTraces() { - assertThat(tracer.shouldLinkRatherThanContinue(25)) - .as("picking one message's trace as the parent of a mixed batch invents causality") - .isTrue(); - } -} diff --git a/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/SecretLeakScannerCharacterizationTest.java b/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/SecretLeakScannerCharacterizationTest.java deleted file mode 100644 index d007f4d8..00000000 --- a/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/SecretLeakScannerCharacterizationTest.java +++ /dev/null @@ -1,139 +0,0 @@ -package dev.caskeleton.messaging.observation; - -import static org.assertj.core.api.Assertions.assertThat; - -import java.util.ArrayList; -import java.util.List; -import java.util.Locale; -import java.util.regex.Pattern; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * Records exactly what {@link SecretLeakStaticScanTest}'s line classifier does today, so the fix - * that removes its two false positives can be checked against the detection power it must keep. - * - *

The classifier below is a verbatim copy of the one under test. A characterization test that - * called the real method would be the better design, and Wave 2 makes that possible by extracting - * the classifier; until then a copy is the only way to assert on the decision procedure at all, - * because every part of it is private and static. The copy is deleted in the same change that - * proves the extracted classifier agrees with it. - * - *

Two cases here were the offenders that failed the full {@code test} run at HEAD, and naming - * them as characterization turned "the build is red" into "the scanner cannot see a method call\'s - * suffix, and cannot see that {@code + 1} is arithmetic". Both now pass, and the three cases above - * them are what keeps the fix from having been a weakening: a real concatenated credential and a - * real interpolated payload are still leaks. - */ -class SecretLeakScannerCharacterizationTest { - - private static final List SENSITIVE_IDENTIFIERS = - List.of("password", "secret", "credential", "token", "apikey", "payload", "passphrase"); - - private static final Pattern STRING_LITERAL = Pattern.compile("\"(\\\\.|[^\"\\\\])*\""); - - private static final Pattern CONCATENATION_OPERAND = - Pattern.compile( - "(?[A-Za-z_][\\w.]*(?:\\(\\))?)\\s*\\+|\\+\\s*(?[A-Za-z_][\\w.]*(?:\\(\\))?)"); - - private static final Pattern SAFE_DERIVATION = - Pattern.compile("\\.(length|size|sizeBytes|getSimpleName|getName|getClass|hashCode)\\b"); - - private static final Pattern DESCRIBES_RATHER_THAN_REVEALS = - Pattern.compile("(Id|Ids|Name|Type|Count|Bytes|Length|Size|Ref|Reference)$"); - - private static final Pattern ARITHMETIC = - Pattern.compile( - "(\\+\\s*(0[xX][0-9a-fA-F]+|\\d[\\d_]*\\.?\\d*[dDfFlL]?))" - + "|((0[xX][0-9a-fA-F]+|\\d[\\d_]*\\.?\\d*[dDfFlL]?)\\s*\\+)"); - - @Test - @DisplayName("a concatenated credential value is a leak") - void aConcatenatedCredentialIsALeak() { - assertThat(leaksASensitiveValue("log.info(\"connecting \" + oauth.credential);")) - .as("a bare credential field reaches the log without passing the redactor") - .isTrue(); - } - - @Test - @DisplayName("a concatenated payload value is a leak") - void aConcatenatedPayloadIsALeak() { - assertThat(leaksASensitiveValue("throw new IllegalStateException(\"bad \" + payload);")) - .as("an exception message that interpolates a payload bypasses the redactor") - .isTrue(); - } - - @Test - @DisplayName("a size or type derivation of a payload is not a leak") - void aDerivationIsNotALeak() { - assertThat(leaksASensitiveValue("log.debug(\"size \" + payload.length);")) - .as("a length describes the value instead of revealing it") - .isFalse(); - } - - @Test - @DisplayName("a method call whose name ends in a safe suffix is not a leak") - void methodCallWithSafeSuffixIsNotALeak() { - assertThat(leaksASensitiveValue("log.info(\"using \" + oauth.credentialId());")) - .as( - "credentialId() names a credential without carrying it; the safe-suffix exemption is " - + "anchored with $ but the captured operand still has its trailing (), so the " - + "exemption never fires for a method call") - .isFalse(); - } - - @Test - @DisplayName("incrementing a fencing token is arithmetic, not concatenation") - void numericFencingIsNotALeak() { - assertThat(leaksASensitiveValue("existing.leaseToken() + 1,")) - .as( - "a fencing token incremented by an integer literal cannot concatenate into a string; " - + "the scanner treats every + as string concatenation") - .isFalse(); - } - - private static boolean leaksASensitiveValue(String line) { - String code = STRING_LITERAL.matcher(line).replaceAll("\"\""); - if (!code.contains("+")) { - return false; - } - if (ARITHMETIC.matcher(code).find()) { - return false; - } - for (String operand : operandsAdjacentToConcatenation(code)) { - String lower = operand.toLowerCase(Locale.ROOT); - if (SENSITIVE_IDENTIFIERS.stream().noneMatch(lower::contains)) { - continue; - } - if (SAFE_DERIVATION.matcher(operand).find()) { - continue; - } - String tail = operand.substring(operand.lastIndexOf('.') + 1); - if (tail.endsWith("()")) { - tail = tail.substring(0, tail.length() - 2); - } - if (tail.equals(tail.toUpperCase(Locale.ROOT))) { - continue; - } - if (DESCRIBES_RATHER_THAN_REVEALS.matcher(tail).find()) { - continue; - } - return true; - } - return false; - } - - private static List operandsAdjacentToConcatenation(String code) { - List operands = new ArrayList<>(); - var matcher = CONCATENATION_OPERAND.matcher(code); - while (matcher.find()) { - if (matcher.group("before") != null) { - operands.add(matcher.group("before")); - } - if (matcher.group("after") != null) { - operands.add(matcher.group("after")); - } - } - return operands; - } -} diff --git a/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/SecretLeakStaticScanTest.java b/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/SecretLeakStaticScanTest.java deleted file mode 100644 index 565e5f37..00000000 --- a/src/platforms/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/SecretLeakStaticScanTest.java +++ /dev/null @@ -1,235 +0,0 @@ -package dev.caskeleton.messaging.observation; - -import static org.assertj.core.api.Assertions.assertThat; - -import java.io.IOException; -import java.nio.file.Files; -import java.nio.file.Path; -import java.util.ArrayList; -import java.util.List; -import java.util.Locale; -import java.util.regex.Pattern; -import java.util.stream.Stream; -import org.junit.jupiter.api.Test; - -/** - * Scans the messaging source tree for code that would print a secret or a payload. - * - *

A runtime redactor only protects the values that pass through it. A {@code toString()} that - * concatenates a credential, or a log line that interpolates a payload, bypasses it entirely and is - * invisible to every unit test — the leak only shows up in a production log, after the fact. A - * static scan is the cheapest way to make that class of mistake fail in CI instead. - */ -class SecretLeakStaticScanTest { - - /** Identifiers that must never be concatenated into a printed string. */ - private static final List SENSITIVE_IDENTIFIERS = - List.of("password", "secret", "credential", "token", "apikey", "payload", "passphrase"); - - /** Statements that write to a stream or build a printed representation. */ - private static final Pattern PRINTING = - Pattern.compile("(System\\.out|System\\.err|printStackTrace\\()"); - - /** A Java string literal, including escaped quotes. */ - /** Whether the scanner is currently inside a text block. */ - private static final ThreadLocal IN_TEXT_BLOCK = ThreadLocal.withInitial(() -> false); - - private static final Pattern STRING_LITERAL = Pattern.compile("\"(\\\\.|[^\"\\\\])*\""); - - /** The operand immediately before or after a string concatenation. */ - private static final Pattern CONCATENATION_OPERAND = - Pattern.compile( - "(?[A-Za-z_][\\w.]*(?:\\(\\))?)\\s*\\+|\\+\\s*(?[A-Za-z_][\\w.]*(?:\\(\\))?)"); - - /** Suffixes that describe a value rather than reveal it. */ - private static final Pattern SAFE_DERIVATION = - Pattern.compile("\\.(length|size|sizeBytes|getSimpleName|getName|getClass|hashCode)\\b"); - - /** A {@code +} with a numeric literal on either side: arithmetic, never concatenation. */ - private static final Pattern ARITHMETIC = - Pattern.compile( - "(\\+\\s*(0[xX][0-9a-fA-F]+|\\d[\\d_]*\\.?\\d*[dDfFlL]?))" - + "|((0[xX][0-9a-fA-F]+|\\d[\\d_]*\\.?\\d*[dDfFlL]?)\\s*\\+)"); - - /** Names that reference a secret without carrying it. */ - private static final Pattern DESCRIBES_RATHER_THAN_REVEALS = - Pattern.compile("(Id|Ids|Name|Type|Count|Bytes|Length|Size|Ref|Reference)$"); - - private static Path messagingRoot() { - Path candidate = Path.of("").toAbsolutePath(); - while (candidate != null && !Files.isDirectory(candidate.resolve("messaging-core-api"))) { - candidate = candidate.getParent(); - } - if (candidate == null) { - throw new IllegalStateException( - "could not locate the messaging source root from the test cwd"); - } - return candidate; - } - - private static List productionSources() throws IOException { - try (Stream files = Files.walk(messagingRoot())) { - return files - .filter(path -> path.toString().endsWith(".java")) - .filter(path -> path.toString().contains("/src/main/java/")) - .toList(); - } - } - - @Test - void productionCodeNeverWritesToTheConsole() throws IOException { - List offenders = new ArrayList<>(); - - for (Path source : productionSources()) { - List lines = Files.readAllLines(source); - for (int index = 0; index < lines.size(); index++) { - String line = lines.get(index); - if (line.trim().startsWith("*") || line.trim().startsWith("//")) { - continue; - } - if (PRINTING.matcher(line).find()) { - offenders.add("%s:%d".formatted(source.getFileName(), index + 1)); - } - } - } - - assertThat(offenders) - .as("console output bypasses the redactor and every log-scrubbing rule downstream") - .isEmpty(); - } - - @Test - void noSensitiveIdentifierIsConcatenatedIntoAString() throws IOException { - List offenders = new ArrayList<>(); - - for (Path source : productionSources()) { - List lines = Files.readAllLines(source); - for (int index = 0; index < lines.size(); index++) { - String trimmed = lines.get(index).trim(); - if (trimmed.startsWith("*") || trimmed.startsWith("//")) { - continue; - } - if (leaksASensitiveValue(trimmed)) { - offenders.add("%s:%d %s".formatted(source.getFileName(), index + 1, trimmed)); - } - } - } - - assertThat(offenders) - .as("a concatenated secret never reaches the redactor, so it must not be written at all") - .isEmpty(); - } - - /** - * Reports whether a line appends a sensitive value to a string. - * - *

Two rounds of narrowing, each one earning its place against a real false positive found in - * this repository. - * - *

String literals are blanked first. Without that, the prose in {@code "password must not be - * null"} matches every identifier pattern and the scan becomes noise the next person disables. - * - *

Then derivations are excluded. {@code payload.length}, {@code reference.sizeBytes()}, and - * {@code payload.getClass().getSimpleName()} all mention a sensitive word while carrying no - * secret — a size and a type name are exactly what a good diagnostic prints instead of - * the value. Flagging them would train the reader to ignore this test. - * - * @param line one source line, already trimmed - * @return true when the line concatenates a sensitive value - */ - private static boolean leaksASensitiveValue(String line) { - if (line.contains("\"\"\"") || IN_TEXT_BLOCK.get()) { - // A text block is SQL or JSON, not Java code. The scanner replaced ordinary string literals - // and then read the contents of text blocks as if they were expressions, so a column named - // `lease_token` in an UPDATE statement looked like a concatenated credential. - IN_TEXT_BLOCK.set(IN_TEXT_BLOCK.get() != line.contains("\"\"\"")); - return false; - } - String code = STRING_LITERAL.matcher(line).replaceAll("\"\""); - if (!code.contains("+")) { - return false; - } - if (ARITHMETIC.matcher(code).find()) { - // `existing.leaseToken() + 1` is an increment, not a concatenation: a numeric literal on - // either side of the + makes the whole expression arithmetic, and arithmetic cannot put a - // secret into a string. Fencing tokens are incremented all over the reliability code, and - // flagging them taught the reader to ignore this scan. - return false; - } - for (String operand : operandsAdjacentToConcatenation(code)) { - String lower = operand.toLowerCase(Locale.ROOT); - if (SENSITIVE_IDENTIFIERS.stream().noneMatch(lower::contains)) { - continue; - } - if (SAFE_DERIVATION.matcher(operand).find()) { - continue; - } - // A method call is captured with its trailing "()", and the safe-suffix pattern below anchors - // with $. Without stripping the call, `credentialId()` never matched `Id` and the exemption - // was dead for every method in the codebase. Stripping is the fix rather than unanchoring: - // an unanchored `Id` would also exempt `credentialIdentity`, which does carry the value. - String tail = operand.substring(operand.lastIndexOf('.') + 1); - if (tail.endsWith("()")) { - tail = tail.substring(0, tail.length() - 2); - } - // A SCREAMING_CASE constant is a compile-time literal in this codebase, never a runtime - // secret; the only ones matching are limits such as PayloadPolicy.HARD_MAX_BYTES. - if (tail.equals(tail.toUpperCase(Locale.ROOT))) { - continue; - } - // `credentialId` names a credential without being one. An id is what a diagnostic prints so - // that an operator can look the secret up in the store it actually lives in. - if (DESCRIBES_RATHER_THAN_REVEALS.matcher(tail).find()) { - continue; - } - return true; - } - return false; - } - - /** - * Returns the operand tokens on either side of each {@code +} in a line of code. - * - * @param code the line with string literals already blanked - * @return the adjacent operands - */ - private static List operandsAdjacentToConcatenation(String code) { - List operands = new ArrayList<>(); - var matcher = CONCATENATION_OPERAND.matcher(code); - while (matcher.find()) { - if (matcher.group("before") != null) { - operands.add(matcher.group("before")); - } - if (matcher.group("after") != null) { - operands.add(matcher.group("after")); - } - } - return operands; - } - - @Test - void theScanActuallyReachesTheSourceTree() throws IOException { - assertThat(productionSources()) - .as("a scan that finds no files would pass vacuously") - .hasSizeGreaterThan(100); - } - - @Test - void theScanCatchesAValueAppendedAfterThePlus() { - assertThat(leaksASensitiveValue("log.info(\"publishing with \" + password);")) - .as("a detector that never fires proves nothing") - .isTrue(); - } - - @Test - void theScanCatchesAValueAppendedBeforeThePlus() { - assertThat(leaksASensitiveValue("String message = clientSecret + \" was rejected\";")).isTrue(); - } - - @Test - void theScanIgnoresASensitiveWordThatIsOnlyProse() { - assertThat(leaksASensitiveValue("throw new IllegalArgumentException(\"password \" + field);")) - .as("blanking literals is what keeps the scan signal rather than noise") - .isFalse(); - } -} diff --git a/src/platforms/messaging/messaging-policy/build.gradle b/src/platforms/messaging/messaging-policy/build.gradle deleted file mode 100644 index fac7b208..00000000 --- a/src/platforms/messaging/messaging-policy/build.gradle +++ /dev/null @@ -1,7 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') -} diff --git a/src/platforms/messaging/messaging-policy/gradle.lockfile b/src/platforms/messaging/messaging-policy/gradle.lockfile deleted file mode 100644 index d74807c4..00000000 --- a/src/platforms/messaging/messaging-policy/gradle.lockfile +++ /dev/null @@ -1,82 +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.50.0=annotationProcessor,checkstyle,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.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -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.6.1=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.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty=compileClasspath,runtimeClasspath diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ApiTier.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ApiTier.java deleted file mode 100644 index c48fb243..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ApiTier.java +++ /dev/null @@ -1,30 +0,0 @@ -package dev.caskeleton.messaging.policy; - -/** - * The API tier a destination is approved for. - * - *

"Tier" names this one thing in the platform: which API surface a destination may use. How far - * an adapter or capability has been proven is a "grade" ({@code CompatibilityMatrix.SupportGrade}), - * the same word the gRPC family uses for its capability and evidence grades. It was {@code - * CapabilityTier}, which put a third meaning on "capability" beside {@code MessagingCapabilities} - * and the gRPC capability grade (S7-#14). - * - *

Recorded on the profile so that the tier boundary is enforced by configuration review rather - * than by whichever handler happens to be wired in. An M1 destination that silently accepted a - * manual settlement handler would move the acknowledge-after-success ordering out of the platform - * and into application code. - */ -public enum ApiTier { - - /** Typed publish and handler with platform-owned settlement. */ - M1, - - /** - * Surfaces beyond M1. None ships: the batch, manual-settlement and pause/resume contracts had no - * implementation and were removed (M-9). - */ - M2, - - /** Broker-native capabilities exposed as typed interfaces. */ - M3 -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/BackoffCalculator.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/BackoffCalculator.java deleted file mode 100644 index ef320679..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/BackoffCalculator.java +++ /dev/null @@ -1,58 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import java.time.Duration; -import java.util.Objects; -import java.util.concurrent.ThreadLocalRandom; -import java.util.function.DoubleSupplier; - -/** - * Exponential backoff with optional full jitter. - * - *

The delay is {@code min(maxDelay, initialDelay * multiplier^(attempt-1))}. Full jitter then - * picks uniformly from {@code [0, delay]} rather than shaving a small percentage off. That matters - * when a downstream recovers: without jitter every consumer that failed in the same second retries - * in the same second, and the recovery is immediately undone by the retry storm. - */ -public final class BackoffCalculator { - - private final DoubleSupplier randomFraction; - - /** Creates a calculator using the platform's thread-local random source. */ - public BackoffCalculator() { - this(() -> ThreadLocalRandom.current().nextDouble()); - } - - /** - * Creates a calculator with an explicit random source. - * - * @param randomFraction supplies values in {@code [0, 1)} - */ - public BackoffCalculator(DoubleSupplier randomFraction) { - this.randomFraction = Objects.requireNonNull(randomFraction, "randomFraction must not be null"); - } - - /** - * Computes the delay before a given attempt. - * - * @param policy the retry policy - * @param attempt the attempt number, counting the first delivery as one - * @return the delay to wait before the next attempt - */ - public Duration delayFor(RetryPolicy policy, int attempt) { - Objects.requireNonNull(policy, "policy must not be null"); - if (attempt < 1) { - throw new IllegalArgumentException("attempt counts the first delivery as 1"); - } - - double scaled = - policy.initialDelay().toMillis() * Math.pow(policy.multiplier(), (double) attempt - 1); - long capped = (long) Math.min(scaled, (double) policy.maxDelay().toMillis()); - if (capped <= 0) { - return Duration.ZERO; - } - if (!policy.jitter()) { - return Duration.ofMillis(capped); - } - return Duration.ofMillis((long) (capped * randomFraction.getAsDouble())); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ConsumerPolicy.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ConsumerPolicy.java deleted file mode 100644 index e02c74e5..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ConsumerPolicy.java +++ /dev/null @@ -1,55 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import java.time.Duration; -import java.util.Objects; -import java.util.Optional; - -/** - * The consumer-side contract for a destination. - * - *

{@code manualSettlement} is a policy flag rather than a handler choice: it decides which - * capability tier a destination belongs to, and an M1 destination that quietly accepted a manual - * handler would bypass the platform's settlement ordering. - * - * @param group the consumer group, where the broker has one - * @param concurrency how many deliveries may be processed at once - * @param maxInFlightPerOrderingUnit the in-flight ceiling inside one ordering unit - * @param prefetch the broker prefetch window - * @param handlerTimeout the handler deadline - * @param manualSettlement whether this destination uses the M2 manual settlement tier - */ -public record ConsumerPolicy( - Optional group, - int concurrency, - int maxInFlightPerOrderingUnit, - int prefetch, - Duration handlerTimeout, - boolean manualSettlement) { - - public ConsumerPolicy { - Objects.requireNonNull(group, "group must not be null"); - Objects.requireNonNull(handlerTimeout, "handlerTimeout must not be null"); - if (concurrency < 1) { - throw new IllegalArgumentException("consumer concurrency must be at least 1"); - } - if (maxInFlightPerOrderingUnit < 1) { - throw new IllegalArgumentException("maxInFlightPerOrderingUnit must be at least 1"); - } - if (prefetch < 1) { - throw new IllegalArgumentException("prefetch must be at least 1"); - } - if (handlerTimeout.isNegative() || handlerTimeout.isZero()) { - throw new IllegalArgumentException("handlerTimeout must be positive"); - } - } - - /** - * Returns the M1 default: single ordering unit in flight, thirty second handler timeout. - * - * @param group the consumer group - * @return the default consumer policy - */ - public static ConsumerPolicy defaults(String group) { - return new ConsumerPolicy(Optional.ofNullable(group), 1, 1, 16, Duration.ofSeconds(30), false); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DeadLetterEnvelopeFactory.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DeadLetterEnvelopeFactory.java deleted file mode 100644 index 90408987..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DeadLetterEnvelopeFactory.java +++ /dev/null @@ -1,57 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import dev.caskeleton.messaging.api.MessageEnvelope; -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.util.LinkedHashMap; -import java.util.Map; -import java.util.Objects; - -/** - * Builds the envelope published to a dead letter destination. - * - *

The payload and the logical {@code messageId} are carried through untouched. That is what - * makes a redrive a genuine replay rather than a new message: an Inbox downstream still recognises - * it, and an operator can correlate the dead letter with the original publish. - * - *

Failure context is written into reserved headers, never into the payload, so redriving does - * not require unwrapping a platform-specific structure. - */ -public final class DeadLetterEnvelopeFactory { - - /** - * Wraps a failed delivery for the dead letter destination. - * - * @param source the envelope as delivered - * @param metadata why it is being dead lettered - * @return an envelope with identical identity and payload plus failure headers - */ - public MessageEnvelope create( - MessageEnvelope source, DeadLetterMetadata metadata) { - Objects.requireNonNull(source, "source must not be null"); - Objects.requireNonNull(metadata, "metadata must not be null"); - - Map headers = new LinkedHashMap<>(source.headers().asMap()); - headers.put( - new HeaderName(ReservedHeaders.FAILURE_CATEGORY), - new HeaderValue(metadata.category().name())); - headers.put(new HeaderName(ReservedHeaders.FAILURE_CODE), new HeaderValue(metadata.code())); - headers.put( - new HeaderName(ReservedHeaders.ORIGIN_DESTINATION), - new HeaderValue(metadata.originDestination().value())); - headers.put( - new HeaderName(ReservedHeaders.RETRY_ATTEMPT), - new HeaderValue(Integer.toString(metadata.deliveryAttempt()))); - headers.put( - new HeaderName(ReservedHeaders.FIRST_FAILURE_AT), - new HeaderValue(metadata.firstFailureAt().toString())); - headers.put( - new HeaderName(ReservedHeaders.LAST_FAILURE_AT), - new HeaderValue(metadata.lastFailureAt().toString())); - - return source.withHeaders(MessageHeaders.platform(headers)); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DeadLetterMetadata.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DeadLetterMetadata.java deleted file mode 100644 index 792f4f1d..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DeadLetterMetadata.java +++ /dev/null @@ -1,42 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.FailureCategory; -import java.time.Instant; -import java.util.Objects; - -/** - * What a dead lettered message carries about why it is there. - * - *

Deliberately small. A dead letter destination is read by operators, exported to tickets, and - * often retained far longer than the source topic, so it holds a category, a code, and timing — not - * a stack trace, not the exception message, and not the original headers. - * - * @param category the stable failure classification - * @param code the stable failure code - * @param originDestination the destination the message was consumed from - * @param deliveryAttempt the attempt that gave up - * @param firstFailureAt when the message first failed - * @param lastFailureAt when the message last failed - */ -public record DeadLetterMetadata( - FailureCategory category, - String code, - DestinationName originDestination, - int deliveryAttempt, - Instant firstFailureAt, - Instant lastFailureAt) { - - public DeadLetterMetadata { - Objects.requireNonNull(category, "category must not be null"); - Objects.requireNonNull(originDestination, "originDestination must not be null"); - Objects.requireNonNull(firstFailureAt, "firstFailureAt must not be null"); - Objects.requireNonNull(lastFailureAt, "lastFailureAt must not be null"); - if (code == null || code.isBlank()) { - throw new IllegalArgumentException("failure code must not be blank"); - } - if (deliveryAttempt < 1) { - throw new IllegalArgumentException("deliveryAttempt counts the first delivery as 1"); - } - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DeadLetterOrchestrator.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DeadLetterOrchestrator.java deleted file mode 100644 index 697728c7..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DeadLetterOrchestrator.java +++ /dev/null @@ -1,121 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -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.schema.EncodedMessage; -import java.time.Instant; -import java.util.Objects; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; - -/** - * Publishes to the dead letter destination, then settles the source — never the other way round. - * - *

This ordering is the single invariant that stops dead lettering from becoming data loss. If - * the source were acknowledged first, a failed dead letter publish would leave no copy of the - * message anywhere: the broker has released it and the dead letter destination never received it. - * So the source stays unsettled on anything other than a confirmed publish, including an ambiguous - * one, and the message is redelivered instead of disappearing. - * - *

An ambiguous dead letter publish therefore produces a duplicate rather than a loss. That is - * the intended trade: the dead letter destination is read by humans who can spot a duplicate, and - * it is the only side of the trade that is recoverable. - */ -public final class DeadLetterOrchestrator { - - private final MessagePublisher publisher; - private final DeadLetterEnvelopeFactory envelopeFactory; - - /** - * Creates an orchestrator over a publisher. - * - * @param publisher the publisher used for the dead letter destination - */ - public DeadLetterOrchestrator(MessagePublisher publisher) { - this(publisher, new DeadLetterEnvelopeFactory()); - } - - /** - * Creates an orchestrator with an explicit envelope factory. - * - * @param publisher the publisher used for the dead letter destination - * @param envelopeFactory the dead letter envelope factory - */ - public DeadLetterOrchestrator( - MessagePublisher publisher, DeadLetterEnvelopeFactory envelopeFactory) { - this.publisher = Objects.requireNonNull(publisher, "publisher must not be null"); - this.envelopeFactory = - Objects.requireNonNull(envelopeFactory, "envelopeFactory must not be null"); - } - - /** - * Dead letters one delivery. - * - * @param sourceProfile the profile of the destination the message came from - * @param delivery the failed delivery, still encoded - * @param failure the sanitized failure - * @param settlement the source settlement callback - * @return a stage completing with the dead letter outcome - */ - public CompletionStage deadLetter( - DestinationProfile sourceProfile, - MessageDelivery delivery, - FailureDescriptor failure, - SourceSettlement settlement) { - - Objects.requireNonNull(sourceProfile, "sourceProfile must not be null"); - Objects.requireNonNull(delivery, "delivery must not be null"); - Objects.requireNonNull(failure, "failure must not be null"); - Objects.requireNonNull(settlement, "settlement must not be null"); - - DestinationName deadLetterName = - sourceProfile - .deadLetter() - .destination() - .orElseThrow( - () -> - new MessagingConfigurationException( - "DEAD_LETTER_NOT_CONFIGURED", - "destination has no dead letter destination: " - + sourceProfile.name().value())); - - Instant failedAt = delivery.metadata().receivedAt(); - DeadLetterMetadata metadata = - new DeadLetterMetadata( - failure.category(), - failure.code(), - sourceProfile.name(), - delivery.metadata().deliveryAttempt(), - failedAt, - failedAt); - - MessageDestination destination = - new MessageDestination<>( - deadLetterName, delivery.message().messageType(), EncodedMessage.class); - - return publisher - .publish( - destination, - envelopeFactory.create(delivery.message(), metadata), - PublishOptions.defaults()) - .thenCompose( - result -> { - if (result.completion() != PublishCompletion.CONFIRMED) { - return CompletableFuture.completedFuture(new DeadLetterResult(result, false)); - } - return settleAfterConfirmation(result, settlement); - }); - } - - private static CompletionStage settleAfterConfirmation( - PublishResult result, SourceSettlement settlement) { - return settlement.settle().thenApply(ignored -> new DeadLetterResult(result, true)); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DeadLetterPolicy.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DeadLetterPolicy.java deleted file mode 100644 index 65605e7e..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DeadLetterPolicy.java +++ /dev/null @@ -1,45 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import java.util.Objects; -import java.util.Optional; - -/** - * Where permanently failed messages go. - * - * @param enabled whether dead lettering is configured - * @param destination the dead letter destination - * @param maxRedriveCount how many times a message may be redriven back - */ -public record DeadLetterPolicy( - boolean enabled, Optional destination, int maxRedriveCount) { - - public DeadLetterPolicy { - Objects.requireNonNull(destination, "destination must not be null"); - if (enabled && destination.isEmpty()) { - throw new IllegalArgumentException("an enabled dead letter policy needs a destination"); - } - if (maxRedriveCount < 0) { - throw new IllegalArgumentException("maxRedriveCount must not be negative"); - } - } - - /** - * Returns a disabled dead letter policy. - * - * @return the disabled policy - */ - public static DeadLetterPolicy disabled() { - return new DeadLetterPolicy(false, Optional.empty(), 0); - } - - /** - * Returns a policy routing to a dead letter destination. - * - * @param destination the dead letter destination - * @return the enabled policy - */ - public static DeadLetterPolicy to(DestinationName destination) { - return new DeadLetterPolicy(true, Optional.of(destination), 1); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DeadLetterResult.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DeadLetterResult.java deleted file mode 100644 index 8d6a4f6a..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DeadLetterResult.java +++ /dev/null @@ -1,17 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import dev.caskeleton.messaging.api.publish.PublishResult; -import java.util.Objects; - -/** - * The outcome of one dead letter attempt. - * - * @param publishResult what the dead letter publish returned - * @param sourceSettled whether the source message was settled afterwards - */ -public record DeadLetterResult(PublishResult publishResult, boolean sourceSettled) { - - public DeadLetterResult { - Objects.requireNonNull(publishResult, "publishResult must not be null"); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DefaultRetryDecisionEngine.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DefaultRetryDecisionEngine.java deleted file mode 100644 index 5708bd5c..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DefaultRetryDecisionEngine.java +++ /dev/null @@ -1,112 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import dev.caskeleton.messaging.api.delivery.DeliveryGuarantee; -import dev.caskeleton.messaging.api.error.FailureCategory; -import java.time.Duration; -import java.util.Objects; - -/** - * The deterministic retry decision order. - * - *

The order is fixed and evaluated top to bottom. Retryability is checked before the attempt - * budget so that a deserialization failure is parked on its first delivery instead of being - * replayed three more times against a payload that cannot change. The ordering-preserving strategy - * is checked before the re-publishing one so that an ordered destination can never fall through to - * a strategy that reorders it, even if both are technically configured. - */ -public final class DefaultRetryDecisionEngine implements RetryDecisionEngine { - - private final BackoffCalculator backoff; - - /** - * Creates an engine over a backoff calculator. - * - * @param backoff the delay calculator - */ - public DefaultRetryDecisionEngine(BackoffCalculator backoff) { - this.backoff = Objects.requireNonNull(backoff, "backoff must not be null"); - } - - @Override - public RetryDecision decide(RetryContext context) { - Objects.requireNonNull(context, "context must not be null"); - - DestinationProfile profile = context.destination(); - RetryPolicy policy = profile.retry(); - int attempt = context.delivery().deliveryAttempt(); - - if (!isRetryable(policy, context.failure().category(), context.failure().retryable())) { - return park(context); - } - if (attempt >= policy.maxAttempts()) { - return new RetryDecision.DeadLetter(context.failure()); - } - - Duration delay = backoff.delayFor(policy, attempt); - - if (policy.orderingImpact() == OrderingImpact.PRESERVE - && profile.isOrdered() - && context - .capabilities() - .supports( - dev.caskeleton.messaging.api.destination.MessagingCapabilities.Capability - .ORDERED_STREAM)) { - return new RetryDecision.PauseAndRetry(delay); - } - if (policy.mode() == RetryMode.PAUSE_PARTITION) { - return new RetryDecision.PauseAndRetry(delay); - } - if (policy.mode() == RetryMode.RETRY_DESTINATION - && policy.orderingImpact() == OrderingImpact.ALLOW_REORDER - && policy.retryDestination().isPresent()) { - return new RetryDecision.PublishToRetryDestination( - policy.retryDestination().orElseThrow(), delay); - } - if (policy.mode() == RetryMode.INLINE || policy.mode() == RetryMode.BLOCKING) { - return new RetryDecision.RetryInline(delay); - } - if (policy.mode() == RetryMode.BROKER_DELAYED - && context - .capabilities() - .supports( - dev.caskeleton.messaging.api.destination.MessagingCapabilities.Capability - .DELAYED_DELIVERY)) { - return new RetryDecision.PublishToRetryDestination( - policy.retryDestination().orElse(profile.name()), delay); - } - return new RetryDecision.DeadLetter(context.failure()); - } - - /** - * Applies the category rules, then the destination's explicit overrides. - * - *

A destination may add a category to the retryable set, but the four categories that fail - * identically on every redelivery stay non-retryable unless the profile names them explicitly. - */ - private static boolean isRetryable( - RetryPolicy policy, FailureCategory category, boolean descriptorRetryable) { - if (policy.nonRetryableCategories().contains(category)) { - return false; - } - if (policy.retryableCategories().contains(category)) { - return true; - } - return descriptorRetryable && FailureDescriptorDefaults.retryable(category); - } - - /** - * Parks a message the platform will not retry. - * - *

Dead lettering is preferred wherever a dead letter destination exists: discarding is only - * acceptable where the profile has already declared that loss is tolerable. - */ - private static RetryDecision park(RetryContext context) { - if (context.destination().deadLetter().enabled()) { - return new RetryDecision.DeadLetter(context.failure()); - } - if (context.destination().deliveryGuarantee() == DeliveryGuarantee.AT_MOST_ONCE) { - return new RetryDecision.Reject(context.failure()); - } - return new RetryDecision.DeadLetter(context.failure()); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DestinationProfile.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DestinationProfile.java deleted file mode 100644 index 11da9cb3..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DestinationProfile.java +++ /dev/null @@ -1,83 +0,0 @@ -package dev.caskeleton.messaging.policy; - -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 java.util.Objects; - -/** - * Everything the platform needs to know about one logical destination. - * - *

This is the single place where a logical name becomes a broker address, a guarantee, and a - * failure policy. Validation of the whole profile happens at startup rather than at first publish, - * so a contradiction like "preserve order, but retry through a separate topic" is a failed boot - * instead of a silent reordering in production. - * - * @param name the logical destination name - * @param broker the adapter this destination binds to - * @param kind the interaction pattern - * @param physical the broker-specific address - * @param schema the codec and compatibility contract - * @param deliveryGuarantee the broker-level delivery guarantee - * @param orderingScope the scope inside which order holds - * @param externalSideEffectGuarantee how handler side effects are protected - * @param producer the producer contract - * @param consumer the consumer contract - * @param retry the retry contract - * @param deadLetter the dead letter contract - * @param payload the size contract - * @param tier the API tier this destination is approved for - * @param production whether this profile is a production profile - * @param keyResolverConfigured whether a key resolver is registered for keyed ordering - * @param topologyAutoCreate whether the application may create topology itself - */ -public record DestinationProfile( - DestinationName name, - String broker, - DestinationKind kind, - PhysicalDestination physical, - SchemaPolicy schema, - DeliveryGuarantee deliveryGuarantee, - OrderingScope orderingScope, - ExternalSideEffectGuarantee externalSideEffectGuarantee, - ProducerPolicy producer, - ConsumerPolicy consumer, - RetryPolicy retry, - DeadLetterPolicy deadLetter, - PayloadPolicy payload, - ApiTier tier, - boolean production, - boolean keyResolverConfigured, - boolean topologyAutoCreate) { - - public DestinationProfile { - Objects.requireNonNull(tier, "tier must not be null"); - Objects.requireNonNull(name, "name must not be null"); - Objects.requireNonNull(kind, "kind must not be null"); - Objects.requireNonNull(physical, "physical must not be null"); - Objects.requireNonNull(schema, "schema must not be null"); - Objects.requireNonNull(deliveryGuarantee, "deliveryGuarantee must not be null"); - Objects.requireNonNull(orderingScope, "orderingScope must not be null"); - Objects.requireNonNull( - externalSideEffectGuarantee, "externalSideEffectGuarantee must not be null"); - Objects.requireNonNull(producer, "producer must not be null"); - Objects.requireNonNull(consumer, "consumer must not be null"); - Objects.requireNonNull(retry, "retry must not be null"); - Objects.requireNonNull(deadLetter, "deadLetter must not be null"); - Objects.requireNonNull(payload, "payload must not be null"); - if (broker == null || broker.isBlank()) { - throw new IllegalArgumentException("broker must not be blank"); - } - } - - /** - * Reports whether order must be preserved for this destination. - * - * @return true when the ordering scope is anything but {@code NONE} - */ - public boolean isOrdered() { - return orderingScope != OrderingScope.NONE; - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DestinationProfileValidator.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DestinationProfileValidator.java deleted file mode 100644 index b7bebba5..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DestinationProfileValidator.java +++ /dev/null @@ -1,208 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import dev.caskeleton.messaging.api.delivery.DeliveryGuarantee; -import dev.caskeleton.messaging.api.delivery.OrderingScope; -import dev.caskeleton.messaging.api.destination.ConfirmationRequirement; -import dev.caskeleton.messaging.api.destination.DestinationName; -import java.util.ArrayList; -import java.util.Collection; -import java.util.LinkedHashMap; -import java.util.LinkedHashSet; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; -import java.util.Set; - -/** - * Startup validation for destination profiles. - * - *

Every rule here exists because the alternative is a production surprise. A profile that asks - * for ordered delivery and configures a reordering retry does not fail on the happy path; it fails - * the first time a message is retried, months later, in a way that looks like a data bug rather - * than a configuration one. Making the contradiction a boot failure moves that discovery to the - * deploy that introduced it. - */ -public final class DestinationProfileValidator { - - /** - * Validates a single profile. - * - * @param profile the profile to validate - * @throws IllegalArgumentException when the profile is internally contradictory - */ - public void validate(DestinationProfile profile) { - Objects.requireNonNull(profile, "profile must not be null"); - - if (profile.retry().orderingImpact() == OrderingImpact.PRESERVE && profile.retry().reorders()) { - throw new IllegalArgumentException( - "retry destination cannot preserve ordering for " + profile.name().value()); - } - if (profile.isOrdered() && profile.retry().orderingImpact() == OrderingImpact.ALLOW_REORDER) { - throw new IllegalArgumentException( - "an ordered destination cannot allow a reordering retry: " + profile.name().value()); - } - if (profile.payload().maxBytes() > PayloadPolicy.HARD_MAX_BYTES) { - throw new IllegalArgumentException( - "payload maximum exceeds " + PayloadPolicy.HARD_MAX_BYTES + " bytes"); - } - if (profile.payload().claimCheckThresholdBytes() > profile.payload().maxBytes()) { - throw new IllegalArgumentException( - "claim check threshold cannot exceed the payload maximum for " + profile.name().value()); - } - if (profile.deadLetter().enabled() - && profile.deadLetter().destination().orElseThrow().equals(profile.name())) { - throw new IllegalArgumentException("dead letter destination cannot reference itself"); - } - if (profile.retry().retryDestination().filter(profile.name()::equals).isPresent()) { - throw new IllegalArgumentException( - "retry destination cannot reference itself: " + profile.name().value()); - } - if (profile.orderingScope() == OrderingScope.KEY && !profile.keyResolverConfigured()) { - throw new IllegalArgumentException( - "ordering scope KEY requires a key resolver for " + profile.name().value()); - } - if (profile.tier() == ApiTier.M1 && profile.consumer().manualSettlement()) { - throw new IllegalArgumentException( - "an M1 destination cannot configure manual settlement: " + profile.name().value()); - } - if (profile.deliveryGuarantee() == DeliveryGuarantee.AT_LEAST_ONCE - && profile.producer().confirmation() == ConfirmationRequirement.NONE) { - throw new IllegalArgumentException( - "at-least-once delivery requires a publish confirmation for " + profile.name().value()); - } - if (profile.deliveryGuarantee() == DeliveryGuarantee.AT_LEAST_ONCE - && !profile.deadLetter().enabled()) { - throw new IllegalArgumentException( - "at-least-once delivery requires a dead letter destination so a failed delivery has " - + "an executable terminal path: " - + profile.name().value()); - } - if (profile.production() && profile.topologyAutoCreate()) { - throw new IllegalArgumentException( - "a production profile must not auto-create topology: " + profile.name().value()); - } - if (profile.orderingScope() == OrderingScope.DESTINATION - && profile.consumer().concurrency() > 1) { - throw new IllegalArgumentException( - "destination-scoped ordering requires concurrency 1 for " + profile.name().value()); - } - if (profile.isOrdered() && profile.consumer().maxInFlightPerOrderingUnit() > 1) { - throw new IllegalArgumentException( - "an ordered destination allows at most one in-flight message per ordering unit: " - + profile.name().value()); - } - if (profile.physical().isEmpty()) { - throw new IllegalArgumentException( - "a destination profile requires a physical address: " + profile.name().value()); - } - if (profile.retry().mode() == RetryMode.NONE && profile.retry().maxAttempts() > 1) { - throw new IllegalArgumentException( - "retry mode NONE cannot allow more than one attempt: " + profile.name().value()); - } - if (profile.retry().mode() == RetryMode.RETRY_DESTINATION - && profile.retry().retryDestination().isEmpty()) { - throw new IllegalArgumentException( - "retry mode RETRY_DESTINATION requires a retry destination: " + profile.name().value()); - } - if (profile.retry().maxAttempts() > 1 - && profile.retry().mode() != RetryMode.NONE - && !profile.deadLetter().enabled()) { - throw new IllegalArgumentException( - "a retrying destination needs somewhere to park exhausted messages: " - + profile.name().value()); - } - } - - /** - * Validates a whole registry, including the retry and dead letter graphs. - * - *

Cycles are checked across profiles rather than per profile: an individually sane pair of - * profiles can still form a loop that replays a poison message forever. - * - * @param profiles every registered profile - * @throws IllegalArgumentException when a profile or the graph is invalid - */ - public void validateAll(Collection profiles) { - Objects.requireNonNull(profiles, "profiles must not be null"); - - Map byName = new LinkedHashMap<>(); - for (DestinationProfile profile : profiles) { - validate(profile); - if (byName.put(profile.name(), profile) != null) { - throw new IllegalArgumentException("duplicate destination profile: " + profile.name()); - } - } - - // One graph carrying both edge kinds, not two walks. - // - // Walking retry and dead-letter separately misses a cycle that alternates between them: A's - // retry points at B and B's dead letter points back at A. Neither single-edge walk revisits a - // node, both pass, and a poison message loops between the two destinations forever. The label - // is kept per edge so the reported path still says which kind each hop was. - for (DestinationProfile profile : byName.values()) { - requireCycleFree(profile, byName); - } - } - - /** Which forwarding edge a cycle walk follows. */ - private enum Edge { - RETRY("retry"), - DEAD_LETTER("dead letter"); - - private final String label; - - Edge(String label) { - this.label = label; - } - - Optional from(DestinationProfile profile) { - return this == RETRY - ? profile.retry().retryDestination() - : profile.deadLetter().destination(); - } - } - - private void requireCycleFree( - DestinationProfile start, Map byName) { - walk(start, byName, new LinkedHashSet<>(), new ArrayList<>()); - } - - /** - * Depth-first over both edge kinds at once. - * - *

{@code onPath} is the current walk rather than everything ever seen, so a diamond — two - * destinations that both forward to a third — is not mistaken for a loop. - */ - private void walk( - DestinationProfile current, - Map byName, - Set onPath, - List path) { - - if (!onPath.add(current.name())) { - throw new IllegalArgumentException( - "the retry and dead letter graph contains a cycle: " - + String.join(" -> ", path) - + " -> " - + current.name().value()); - } - path.add(current.name().value()); - - for (Edge edge : Edge.values()) { - Optional next = edge.from(current); - if (next.isEmpty()) { - continue; - } - DestinationName nextName = next.get(); - DestinationProfile nextProfile = byName.get(nextName); - if (nextProfile == null) { - throw new IllegalArgumentException( - edge.label + " destination is not registered: " + nextName.value()); - } - List branch = new ArrayList<>(path); - branch.set(branch.size() - 1, current.name().value() + " (" + edge.label + ')'); - walk(nextProfile, byName, new LinkedHashSet<>(onPath), branch); - } - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/FailureDescriptorDefaults.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/FailureDescriptorDefaults.java deleted file mode 100644 index 517cf789..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/FailureDescriptorDefaults.java +++ /dev/null @@ -1,14 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.error.FailureDescriptor; - -/** The category retry defaults, kept in one place so policy and engine cannot disagree. */ -final class FailureDescriptorDefaults { - - private FailureDescriptorDefaults() {} - - static boolean retryable(FailureCategory category) { - return FailureDescriptor.defaultRetryable(category); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/InFlightLimiter.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/InFlightLimiter.java deleted file mode 100644 index e15b7e64..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/InFlightLimiter.java +++ /dev/null @@ -1,95 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import java.time.Duration; -import java.util.Objects; -import java.util.concurrent.Semaphore; -import java.util.concurrent.TimeUnit; - -/** - * A bounded permit pool for producer-side in-flight work. - * - *

The wait is bounded on purpose. Section 40.3 of the design specifies "bounded wait, then - * {@code MessageBackpressureException}": a short wait absorbs the bursts that a saturated producer - * buffer clears on its own, while the bound stops a persistent stall from converting into unbounded - * thread occupancy in the calling application. - * - *

A zero wait is legal and means "reject immediately", which is what a latency-sensitive caller - * that would rather shed load than queue should use. - */ -public final class InFlightLimiter { - - private final Semaphore permits; - private final Duration maxWait; - private final int limit; - - /** - * Creates a limiter. - * - * @param limit the number of concurrent in-flight operations allowed - * @param maxWait how long an admission attempt may wait for a permit - */ - public InFlightLimiter(int limit, Duration maxWait) { - Objects.requireNonNull(maxWait, "maxWait must not be null"); - if (limit < 1) { - throw new IllegalArgumentException("limit must be at least 1"); - } - if (maxWait.isNegative()) { - throw new IllegalArgumentException("maxWait must not be negative"); - } - this.limit = limit; - this.maxWait = maxWait; - // Fair ordering: an unfair semaphore lets a late arrival barge ahead of a caller that has - // already been waiting, which turns a bounded wait into an unbounded one for the unlucky. - this.permits = new Semaphore(limit, true); - } - - /** - * Tries to acquire one permit, waiting no longer than the configured bound. - * - * @return true when a permit was acquired - * @throws InterruptedException when the waiting thread is interrupted - */ - public boolean tryAcquire() throws InterruptedException { - return tryAcquire(maxWait); - } - - /** - * Tries to acquire one permit, waiting no longer than the configured bound or the given budget. - * - * @param budget what the caller has left to spend on the wait - * @return true when a permit was acquired - * @throws InterruptedException when the waiting thread is interrupted - */ - public boolean tryAcquire(Duration budget) throws InterruptedException { - Objects.requireNonNull(budget, "budget must not be null"); - long wait = Math.max(0, Math.min(maxWait.toNanos(), budget.toNanos())); - return permits.tryAcquire(wait, TimeUnit.NANOSECONDS); - } - - /** Returns one permit to the pool. */ - public void release() { - // Never exceed the configured limit: an unbalanced release would raise the ceiling silently - // and the limiter would stop limiting anything. - if (permits.availablePermits() < limit) { - permits.release(); - } - } - - /** - * Returns how many operations are currently admitted. - * - * @return the in-flight count - */ - public int inFlight() { - return limit - permits.availablePermits(); - } - - /** - * Returns the configured ceiling. - * - * @return the in-flight limit - */ - public int limit() { - return limit; - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/MessagingAdmissionController.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/MessagingAdmissionController.java deleted file mode 100644 index 118f9989..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/MessagingAdmissionController.java +++ /dev/null @@ -1,225 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import dev.caskeleton.messaging.api.error.MessageBackpressureException; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import java.util.Map; -import java.util.Objects; -import java.util.concurrent.ConcurrentHashMap; -import java.util.concurrent.atomic.AtomicInteger; - -/** - * The single gate every publish passes before any transport work begins. - * - *

Order matters and is fixed here rather than left to each adapter: the payload limit is checked - * before a permit is taken. An oversized message can never succeed, so letting it occupy a - * scarce in-flight permit while it is being rejected would let a stream of bad messages starve the - * good ones. - * - *

Both refusals happen before transmission, so neither is ambiguous — the caller may resubmit - * under the same message id without risking a duplicate. That is the reason admission lives at the - * front of the pipeline instead of being folded into the adapter's error handling, where a partial - * write would already have made the outcome unknowable. - * - *

Two ceilings, because one is not enough. The per-destination ceiling stops a single slow - * downstream from consuming every permit in the process, and the process-wide ceiling stops the sum - * of well-behaved destinations from exhausting memory — without it, adding a destination silently - * raises what the process can be holding at once. - */ -public final class MessagingAdmissionController { - - private final PayloadLimitGuard payloadGuard; - private final InFlightLimiter limiter; - private final int perDestinationLimit; - private final Map perDestination = new ConcurrentHashMap<>(); - private volatile boolean acceptingNewWork = true; - - /** - * Creates an admission controller whose only ceiling is the process-wide one. - * - * @param payloadGuard the payload size guard - * @param limiter the in-flight permit pool - */ - public MessagingAdmissionController(PayloadLimitGuard payloadGuard, InFlightLimiter limiter) { - this(payloadGuard, limiter, limiter.limit()); - } - - /** - * Creates an admission controller with a per-destination ceiling. - * - * @param payloadGuard the payload size guard - * @param limiter the in-flight permit pool - * @param perDestinationLimit how much in-flight work one destination may hold - */ - public MessagingAdmissionController( - PayloadLimitGuard payloadGuard, InFlightLimiter limiter, int perDestinationLimit) { - this.payloadGuard = Objects.requireNonNull(payloadGuard, "payloadGuard must not be null"); - this.limiter = Objects.requireNonNull(limiter, "limiter must not be null"); - if (perDestinationLimit < 1) { - throw new IllegalArgumentException("perDestinationLimit must be at least 1"); - } - if (perDestinationLimit > limiter.limit()) { - throw new IllegalArgumentException( - "perDestinationLimit cannot exceed the process-wide limit, or it is not a limit"); - } - this.perDestinationLimit = perDestinationLimit; - } - - /** - * Admits one publish, or refuses it. - * - * @param destination the logical destination name - * @param payloadBytes the encoded payload size - * @throws MessageTooLargeException when the payload exceeds the destination limit - * @throws MessageBackpressureException when shutting down or no permit became available - */ - public void admit(String destination, int payloadBytes) { - admit(destination, payloadBytes, java.time.Duration.ofNanos(Long.MAX_VALUE)); - } - - /** - * Admits one publish, waiting for a permit no longer than the caller has left. - * - *

The limiter's own bound was the only one: a publish with a 100ms deadline could block its - * caller for the limiter's full wait before the deadline was even consulted. - * - * @param destination the logical destination name - * @param payloadBytes the encoded payload size - * @param budget the most this call may wait for a permit - * @throws MessageTooLargeException when the payload exceeds the destination limit - * @throws MessageBackpressureException when shutting down or no permit became available - */ - public void admit(String destination, int payloadBytes, java.time.Duration budget) { - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(budget, "budget must not be null"); - payloadGuard.checkPayload(destination, payloadBytes); - - if (!acceptingNewWork) { - throw new MessageBackpressureException( - "SHUTTING_DOWN", "the messaging runtime stopped accepting new publishes"); - } - - if (!reserve(destination)) { - throw new MessageBackpressureException( - "DESTINATION_IN_FLIGHT_LIMIT_EXCEEDED", - "%s already holds its %d in-flight publishes; one slow destination does not get to" - .formatted(destination, perDestinationLimit) - + " consume the whole process"); - } - - boolean acquired; - try { - acquired = limiter.tryAcquire(budget); - } catch (InterruptedException interrupted) { - // The destination slot was taken a moment ago and no publish will use it, so it goes back - // here: a slot leaked per interruption shrinks the destination's ceiling until it is zero. - release(destination); - Thread.currentThread().interrupt(); - throw new MessageBackpressureException( - "ADMISSION_INTERRUPTED", "interrupted while waiting for a publish permit"); - } - if (!acquired) { - release(destination); - throw new MessageBackpressureException( - "IN_FLIGHT_LIMIT_EXCEEDED", - "no publish permit became available for %s within the bounded wait" - .formatted(destination)); - } - } - - /** - * Releases the permit taken by a successful {@link #admit}. - * - *

The destination is named because the caller cannot release a permit it never took: a release - * carrying a different destination would return a slot to a queue that has nothing outstanding - * and leave the real one occupied forever. - * - * @param destination the destination this publish was admitted for - */ - public void complete(String destination) { - Objects.requireNonNull(destination, "destination must not be null"); - if (!release(destination)) { - // A completion for a destination that holds nothing: either it names the wrong destination or - // it is a second completion for the same publish. Returning the process permit anyway frees - // one nobody took, and the process-wide ceiling then reads below what is really in flight and - // admits more work than the process can carry. - return; - } - limiter.release(); - } - - /** - * Stops admitting new work, as the first step of graceful shutdown. - * - *

Permits already held stay valid: the point is to drain what is in flight, not to abandon it. - */ - public void stopAcceptingNewWork() { - acceptingNewWork = false; - } - - /** - * Reports whether new publishes are being admitted. - * - * @return true while the controller accepts new work - */ - public boolean isAcceptingNewWork() { - return acceptingNewWork; - } - - /** - * Returns the current in-flight count. - * - * @return the number of admitted, uncompleted publishes - */ - public int inFlight() { - return limiter.inFlight(); - } - - /** - * Returns how much in-flight work one destination holds. - * - * @param destination the logical destination name - * @return the destination's in-flight count - */ - public int inFlight(String destination) { - AtomicInteger counter = perDestination.get(destination); - return counter == null ? 0 : counter.get(); - } - - private boolean reserve(String destination) { - java.util.concurrent.atomic.AtomicBoolean reserved = - new java.util.concurrent.atomic.AtomicBoolean(); - perDestination.compute( - destination, - (key, existing) -> { - AtomicInteger counter = existing == null ? new AtomicInteger() : existing; - if (counter.get() >= perDestinationLimit) { - return counter; - } - counter.incrementAndGet(); - reserved.set(true); - return counter; - }); - return reserved.get(); - } - - /** - * Gives one slot back to a destination. - * - * @return true when this call actually released a slot the destination was holding - */ - private boolean release(String destination) { - java.util.concurrent.atomic.AtomicBoolean released = - new java.util.concurrent.atomic.AtomicBoolean(); - perDestination.computeIfPresent( - destination, - (key, counter) -> { - if (counter.get() <= 0) { - return null; - } - int remaining = counter.decrementAndGet(); - released.set(true); - return remaining == 0 ? null : counter; - }); - return released.get(); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/OrderingImpact.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/OrderingImpact.java deleted file mode 100644 index 81b93409..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/OrderingImpact.java +++ /dev/null @@ -1,11 +0,0 @@ -package dev.caskeleton.messaging.policy; - -/** What a retry strategy is permitted to do to message order. */ -public enum OrderingImpact { - - /** Order must survive the retry. */ - PRESERVE, - - /** The retried message may be delivered out of its original position. */ - ALLOW_REORDER -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/PayloadLimitGuard.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/PayloadLimitGuard.java deleted file mode 100644 index 4f7cf440..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/PayloadLimitGuard.java +++ /dev/null @@ -1,86 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import java.util.List; -import java.util.Objects; - -/** - * Rejects oversized payloads and batches before anything is handed to a broker. - * - *

Local rejection is deliberate. A broker that refuses an oversized record does so after the - * bytes have crossed the network, and some brokers only refuse it at the leader, after the producer - * has already buffered and batched it. Checking here keeps the failure cheap, immediate, and - * unambiguous: nothing was transmitted, so the caller may fix and resubmit under the same message - * id. - * - *

Batches are limited by count and bytes. A count limit alone lets a handful of large - * messages exceed the broker's frame; a byte limit alone lets a huge number of tiny messages exceed - * its request timeout. - */ -public final class PayloadLimitGuard { - - private final PayloadPolicy policy; - - /** - * Creates a guard for one destination's payload policy. - * - * @param policy the destination's payload limits - */ - public PayloadLimitGuard(PayloadPolicy policy) { - this.policy = Objects.requireNonNull(policy, "policy must not be null"); - } - - /** - * Checks one encoded payload against the destination limit. - * - * @param destination the logical destination name, used in the diagnostic - * @param payloadBytes the encoded payload size - * @throws MessageTooLargeException when the payload exceeds the limit - */ - public void checkPayload(String destination, int payloadBytes) { - Objects.requireNonNull(destination, "destination must not be null"); - if (payloadBytes < 0) { - throw new IllegalArgumentException("payloadBytes must not be negative"); - } - if (payloadBytes > policy.maxBytes()) { - throw new MessageTooLargeException( - "PAYLOAD_LIMIT_EXCEEDED", - "payload of %d bytes exceeds the %d byte limit for %s; use claim check" - .formatted(payloadBytes, policy.maxBytes(), destination)); - } - } - - /** - * Checks a batch against both the count and the aggregate byte limit. - * - * @param destination the logical destination name, used in the diagnostic - * @param payloadSizes each entry's encoded payload size - * @param maxBatchCount the largest accepted entry count - * @param maxBatchBytes the largest accepted aggregate size - * @throws MessageTooLargeException when the batch exceeds either limit - */ - public void checkBatch( - String destination, List payloadSizes, int maxBatchCount, long maxBatchBytes) { - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(payloadSizes, "payloadSizes must not be null"); - - if (payloadSizes.size() > maxBatchCount) { - throw new MessageTooLargeException( - "BATCH_COUNT_EXCEEDED", - "batch of %d entries exceeds the %d entry limit for %s" - .formatted(payloadSizes.size(), maxBatchCount, destination)); - } - - long total = 0; - for (int index = 0; index < payloadSizes.size(); index++) { - checkPayload(destination, payloadSizes.get(index)); - total += payloadSizes.get(index); - } - if (total > maxBatchBytes) { - throw new MessageTooLargeException( - "BATCH_BYTES_EXCEEDED", - "batch of %d bytes exceeds the %d byte limit for %s" - .formatted(total, maxBatchBytes, destination)); - } - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/PayloadPolicy.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/PayloadPolicy.java deleted file mode 100644 index 579eae72..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/PayloadPolicy.java +++ /dev/null @@ -1,39 +0,0 @@ -package dev.caskeleton.messaging.policy; - -/** - * The size contract for a destination's payloads. - * - *

The portability default is one mebibyte and the absolute ceiling is eight. Raising a broker's - * frame limit to carry large payloads trades a bounded, testable failure for an unbounded one: it - * degrades broker memory, replication latency, and consumer recovery all at once. Anything above - * the threshold is expected to travel by Claim Check instead. - * - * @param maxBytes the encoded payload ceiling for this destination - * @param claimCheckThresholdBytes the size above which payloads are offloaded - */ -public record PayloadPolicy(int maxBytes, int claimCheckThresholdBytes) { - - /** The portability default. */ - public static final int DEFAULT_MAX_BYTES = 1_048_576; - - /** The absolute ceiling no destination may exceed. */ - public static final int HARD_MAX_BYTES = 8_388_608; - - public PayloadPolicy { - if (maxBytes < 1) { - throw new IllegalArgumentException("payload maxBytes must be positive"); - } - if (claimCheckThresholdBytes < 1) { - throw new IllegalArgumentException("claimCheckThresholdBytes must be positive"); - } - } - - /** - * Returns the portability default. - * - * @return a one mebibyte policy - */ - public static PayloadPolicy defaults() { - return new PayloadPolicy(DEFAULT_MAX_BYTES, DEFAULT_MAX_BYTES); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/PhysicalDestination.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/PhysicalDestination.java deleted file mode 100644 index e6b7e156..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/PhysicalDestination.java +++ /dev/null @@ -1,125 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import java.util.Objects; -import java.util.Optional; - -/** - * The broker-specific address a logical destination maps to. - * - *

Held here and nowhere else. Once a topic name reaches application code the logical destination - * stops being a boundary, and swapping the broker under a service becomes a code change instead of - * a configuration change. - * - * @param topic the Kafka or Pulsar topic - * @param exchange the AMQP exchange - * @param routingKey the AMQP routing key - * @param queue the AMQP queue - * @param subject the NATS subject - * @param stream the NATS or Pulsar stream - */ -public record PhysicalDestination( - Optional topic, - Optional exchange, - Optional routingKey, - Optional queue, - Optional subject, - Optional stream) { - - public PhysicalDestination { - Objects.requireNonNull(topic, "topic must not be null"); - Objects.requireNonNull(exchange, "exchange must not be null"); - Objects.requireNonNull(routingKey, "routingKey must not be null"); - Objects.requireNonNull(queue, "queue must not be null"); - Objects.requireNonNull(subject, "subject must not be null"); - Objects.requireNonNull(stream, "stream must not be null"); - } - - /** - * Builds a Kafka topic mapping. - * - * @param topic the topic name - * @return the physical mapping - */ - public static PhysicalDestination kafkaTopic(String topic) { - return new PhysicalDestination( - Optional.of(topic), - Optional.empty(), - Optional.empty(), - Optional.empty(), - Optional.empty(), - Optional.empty()); - } - - /** - * Builds an AMQP exchange, routing key, and queue mapping. - * - * @param exchange the exchange name - * @param routingKey the routing key - * @param queue the queue name - * @return the physical mapping - */ - public static PhysicalDestination rabbitQueue(String exchange, String routingKey, String queue) { - return new PhysicalDestination( - Optional.empty(), - Optional.of(exchange), - Optional.of(routingKey), - Optional.of(queue), - Optional.empty(), - Optional.empty()); - } - - /** - * Builds a Pulsar topic and subscription mapping. - * - *

The subscription is part of the address, not of the consumer configuration. Two consumers on - * the same topic with different subscriptions receive independent copies of every message, so the - * subscription name determines what is delivered just as much as the topic does. - * - * @param topic the fully-qualified Pulsar topic - * @param subscription the durable subscription name - * @return the physical mapping - */ - public static PhysicalDestination pulsarTopic(String topic, String subscription) { - return new PhysicalDestination( - Optional.of(topic), - Optional.empty(), - Optional.empty(), - Optional.empty(), - Optional.empty(), - Optional.of(subscription)); - } - - /** - * Builds a NATS JetStream subject and stream mapping. - * - *

Both are required. A subject without its stream is ambiguous: JetStream lets several streams - * capture overlapping subjects, and which one a message lands in decides its retention, its - * replication, and whether it is replayable at all. - * - * @param subject the JetStream subject - * @param stream the stream capturing that subject - * @return the physical mapping - */ - public static PhysicalDestination natsStream(String subject, String stream) { - return new PhysicalDestination( - Optional.empty(), - Optional.empty(), - Optional.empty(), - Optional.empty(), - Optional.of(subject), - Optional.of(stream)); - } - - /** - * Reports whether any physical address is present. - * - * @return true when at least one address field is set - */ - public boolean isEmpty() { - return topic.isEmpty() - && exchange.isEmpty() - && queue.isEmpty() - && subject.isEmpty() - && stream.isEmpty(); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ProducerPolicy.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ProducerPolicy.java deleted file mode 100644 index c2f7ce12..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ProducerPolicy.java +++ /dev/null @@ -1,38 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import dev.caskeleton.messaging.api.destination.ConfirmationRequirement; -import java.time.Duration; -import java.util.Objects; - -/** - * The producer-side contract for a destination. - * - * @param confirmation the confirmation strength this destination demands - * @param timeout the publish deadline - * @param mandatoryRouting whether the broker must report unroutable publishes - * @param idempotentProducer whether producer-side duplicate suppression is required - */ -public record ProducerPolicy( - ConfirmationRequirement confirmation, - Duration timeout, - boolean mandatoryRouting, - boolean idempotentProducer) { - - public ProducerPolicy { - Objects.requireNonNull(confirmation, "confirmation must not be null"); - Objects.requireNonNull(timeout, "timeout must not be null"); - if (timeout.isNegative() || timeout.isZero()) { - throw new IllegalArgumentException("producer timeout must be positive"); - } - } - - /** - * Returns the Stable default: replication evidence, five seconds, mandatory routing, idempotent. - * - * @return the default producer policy - */ - public static ProducerPolicy defaults() { - return new ProducerPolicy( - ConfirmationRequirement.REPLICATION_OR_PERSISTENCE_ACK, Duration.ofSeconds(5), true, true); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/RetryContext.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/RetryContext.java deleted file mode 100644 index fd804278..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/RetryContext.java +++ /dev/null @@ -1,34 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import dev.caskeleton.messaging.api.delivery.DeliveryMetadata; -import dev.caskeleton.messaging.api.destination.MessagingCapabilities; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import java.util.Objects; - -/** - * Everything the retry engine is allowed to decide from. - * - *

Capabilities are an input rather than an assumption: the same policy resolves to - * pause-and-retry on a partitioned Kafka topic and to a retry destination on a queue that cannot - * pause, and the engine must not pick a strategy the adapter cannot actually carry out. - * - * @param destination the validated destination profile - * @param delivery transport-side facts about this attempt - * @param failure the sanitized failure - * @param capabilities what the adapter can actually do for this destination - * @param handlerMayHaveCommittedSideEffect whether the handler might already have committed - */ -public record RetryContext( - DestinationProfile destination, - DeliveryMetadata delivery, - FailureDescriptor failure, - MessagingCapabilities capabilities, - boolean handlerMayHaveCommittedSideEffect) { - - public RetryContext { - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(delivery, "delivery must not be null"); - Objects.requireNonNull(failure, "failure must not be null"); - Objects.requireNonNull(capabilities, "capabilities must not be null"); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/RetryDecision.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/RetryDecision.java deleted file mode 100644 index 735dfb1e..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/RetryDecision.java +++ /dev/null @@ -1,76 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import java.time.Duration; -import java.util.Objects; - -/** What the platform will do with a failed delivery. */ -public sealed interface RetryDecision - permits RetryDecision.RetryInline, - RetryDecision.PauseAndRetry, - RetryDecision.PublishToRetryDestination, - RetryDecision.DeadLetter, - RetryDecision.Reject { - - /** - * Retry without releasing the delivery. - * - * @param delay how long to wait first - */ - record RetryInline(Duration delay) implements RetryDecision { - public RetryInline { - Objects.requireNonNull(delay, "delay must not be null"); - } - } - - /** - * Pause the ordering unit and redeliver from the same position. - * - *

The only strategy that both retries and preserves order, because the message never leaves - * its position in the log. - * - * @param delay how long to stay paused - */ - record PauseAndRetry(Duration delay) implements RetryDecision { - public PauseAndRetry { - Objects.requireNonNull(delay, "delay must not be null"); - } - } - - /** - * Re-publish to a separate retry destination. - * - * @param destination the retry destination - * @param delay the intended delay before redelivery - */ - record PublishToRetryDestination(DestinationName destination, Duration delay) - implements RetryDecision { - public PublishToRetryDestination { - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(delay, "delay must not be null"); - } - } - - /** - * Route to the dead letter destination. - * - * @param failure the sanitized failure - */ - record DeadLetter(FailureDescriptor failure) implements RetryDecision { - public DeadLetter { - Objects.requireNonNull(failure, "failure must not be null"); - } - } - - /** - * Discard without dead lettering. - * - * @param failure the sanitized failure - */ - record Reject(FailureDescriptor failure) implements RetryDecision { - public Reject { - Objects.requireNonNull(failure, "failure must not be null"); - } - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/RetryDecisionEngine.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/RetryDecisionEngine.java deleted file mode 100644 index d65ae606..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/RetryDecisionEngine.java +++ /dev/null @@ -1,13 +0,0 @@ -package dev.caskeleton.messaging.policy; - -/** Decides what happens to a failed delivery. */ -public interface RetryDecisionEngine { - - /** - * Decides the outcome for one failed delivery. - * - * @param context the destination policy, delivery facts, failure, and capabilities - * @return the decision - */ - RetryDecision decide(RetryContext context); -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/RetryMode.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/RetryMode.java deleted file mode 100644 index 16daa2bd..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/RetryMode.java +++ /dev/null @@ -1,29 +0,0 @@ -package dev.caskeleton.messaging.policy; - -/** - * How a retry is carried out. - * - *

The mode determines whether ordering survives, which is why it is a policy decision rather - * than an adapter detail. Only {@link #NONE}, {@link #INLINE}, {@link #BLOCKING}, and {@link - * #PAUSE_PARTITION} can preserve order; the two that re-publish cannot. - */ -public enum RetryMode { - - /** No automatic retry; failures go straight to the dead letter or reject path. */ - NONE, - - /** Retry inside the same handler invocation, without releasing the delivery. */ - INLINE, - - /** Hold the consumer thread between attempts. */ - BLOCKING, - - /** Pause the ordering unit and redeliver from the same position. */ - PAUSE_PARTITION, - - /** Re-publish to a separate retry destination. Reorders relative to the source. */ - RETRY_DESTINATION, - - /** Use the broker's own delayed delivery. Reorders relative to the source. */ - BROKER_DELAYED -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/RetryPolicy.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/RetryPolicy.java deleted file mode 100644 index f4cce47c..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/RetryPolicy.java +++ /dev/null @@ -1,136 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.FailureCategory; -import java.time.Duration; -import java.util.Objects; -import java.util.Optional; -import java.util.Set; - -/** - * The retry contract for one destination. - * - *

Automatic retry is opt-in. The default for an ordinary destination is zero attempts, because a - * retry that reorders a stream, multiplies a non-idempotent side effect, or hammers a throttled - * downstream is worse than a visible failure. - * - * @param mode how the retry is carried out - * @param maxAttempts total attempts including the first delivery - * @param initialDelay the first backoff interval - * @param maxDelay the backoff ceiling - * @param multiplier the exponential backoff factor - * @param jitter whether to randomise the backoff - * @param orderingImpact what this policy is allowed to do to order - * @param retryableCategories categories added to the retryable set - * @param nonRetryableCategories categories removed from the retryable set - * @param retryDestination the destination messages are re-published to, when the mode uses one - */ -public record RetryPolicy( - RetryMode mode, - int maxAttempts, - Duration initialDelay, - Duration maxDelay, - double multiplier, - boolean jitter, - OrderingImpact orderingImpact, - Set retryableCategories, - Set nonRetryableCategories, - Optional retryDestination) { - - /** - * Creates a policy with no retry destination. - * - *

Convenience for the majority of modes, which never re-publish. - * - * @param mode how the retry is carried out - * @param maxAttempts total attempts including the first delivery - * @param initialDelay the first backoff interval - * @param maxDelay the backoff ceiling - * @param multiplier the exponential backoff factor - * @param jitter whether to randomise the backoff - * @param orderingImpact what this policy is allowed to do to order - * @param retryableCategories categories added to the retryable set - * @param nonRetryableCategories categories removed from the retryable set - */ - public RetryPolicy( - RetryMode mode, - int maxAttempts, - Duration initialDelay, - Duration maxDelay, - double multiplier, - boolean jitter, - OrderingImpact orderingImpact, - Set retryableCategories, - Set nonRetryableCategories) { - this( - mode, - maxAttempts, - initialDelay, - maxDelay, - multiplier, - jitter, - orderingImpact, - retryableCategories, - nonRetryableCategories, - Optional.empty()); - } - - public RetryPolicy { - Objects.requireNonNull(retryDestination, "retryDestination must not be null"); - Objects.requireNonNull(mode, "retry mode must not be null"); - Objects.requireNonNull(initialDelay, "initialDelay must not be null"); - Objects.requireNonNull(maxDelay, "maxDelay must not be null"); - Objects.requireNonNull(orderingImpact, "orderingImpact must not be null"); - Objects.requireNonNull(retryableCategories, "retryableCategories must not be null"); - Objects.requireNonNull(nonRetryableCategories, "nonRetryableCategories must not be null"); - - if (maxAttempts < 1) { - throw new IllegalArgumentException("maxAttempts counts the first delivery, so it is >= 1"); - } - if (initialDelay.isNegative() || maxDelay.isNegative()) { - throw new IllegalArgumentException("retry delays must not be negative"); - } - if (maxDelay.compareTo(initialDelay) < 0) { - throw new IllegalArgumentException("maxDelay must not be smaller than initialDelay"); - } - if (multiplier < 1.0) { - throw new IllegalArgumentException("retry multiplier must be at least 1.0"); - } - retryableCategories = Set.copyOf(retryableCategories); - nonRetryableCategories = Set.copyOf(nonRetryableCategories); - - Set overlap = new java.util.HashSet<>(retryableCategories); - overlap.retainAll(nonRetryableCategories); - if (!overlap.isEmpty()) { - throw new IllegalArgumentException( - "a failure category cannot be both retryable and non-retryable: " + overlap); - } - } - - /** - * Returns the safe default: no automatic retry, order preserved. - * - * @return a no-retry policy - */ - public static RetryPolicy none() { - return new RetryPolicy( - RetryMode.NONE, - 1, - Duration.ZERO, - Duration.ZERO, - 1.0, - false, - OrderingImpact.PRESERVE, - Set.of(), - Set.of()); - } - - /** - * Reports whether this mode can move a message off its original ordering unit. - * - * @return true when the mode re-publishes or defers through the broker - */ - public boolean reorders() { - return mode == RetryMode.RETRY_DESTINATION || mode == RetryMode.BROKER_DELAYED; - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/SchemaPolicy.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/SchemaPolicy.java deleted file mode 100644 index 80c07223..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/SchemaPolicy.java +++ /dev/null @@ -1,31 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.schema.SchemaCompatibility; -import java.util.Objects; -import java.util.Set; - -/** - * The codec and compatibility contract for a destination. - * - *

The message type catalog is part of the policy, not something the codec discovers at runtime. - * A destination that accepts any type it happens to be handed has no reviewable wire contract. - * - * @param codec the content type the destination is encoded with - * @param compatibility the schema evolution mode enforced for this destination - * @param messageTypes the closed catalog of types this destination carries - */ -public record SchemaPolicy( - ContentType codec, SchemaCompatibility compatibility, Set messageTypes) { - - public SchemaPolicy { - Objects.requireNonNull(codec, "codec must not be null"); - Objects.requireNonNull(compatibility, "compatibility must not be null"); - Objects.requireNonNull(messageTypes, "messageTypes must not be null"); - if (messageTypes.isEmpty()) { - throw new IllegalArgumentException("a destination must declare at least one message type"); - } - messageTypes = Set.copyOf(messageTypes); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/SourceSettlement.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/SourceSettlement.java deleted file mode 100644 index a9db7829..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/SourceSettlement.java +++ /dev/null @@ -1,21 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import java.util.concurrent.CompletionStage; - -/** - * The callback that settles the source message. - * - *

Handed to the orchestrator rather than invoked by it directly so that the ordering constraint - * — settle only after the dead letter publish confirms — lives in one place instead of being - * re-implemented by every adapter. - */ -@FunctionalInterface -public interface SourceSettlement { - - /** - * Settles the source message. - * - * @return a stage completing when settlement has been attempted - */ - CompletionStage settle(); -} diff --git a/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/DeadLetterOrchestratorTest.java b/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/DeadLetterOrchestratorTest.java deleted file mode 100644 index ecc4e36a..00000000 --- a/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/DeadLetterOrchestratorTest.java +++ /dev/null @@ -1,312 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import static org.assertj.core.api.Assertions.assertThat; - -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.DeliveryContext; -import dev.caskeleton.messaging.api.delivery.DeliveryMetadata; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -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.header.HeaderValue; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.api.header.ReservedHeaders; -import dev.caskeleton.messaging.api.publish.ConfirmationLevel; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -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.schema.EncodedMessage; -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.AtomicBoolean; -import org.junit.jupiter.api.Test; - -class DeadLetterOrchestratorTest { - - @Test - void settlesSourceOnlyAfterDlqConfirmation() { - AtomicBoolean sourceSettled = new AtomicBoolean(false); - FakePublisher publisher = FakePublisher.confirming(); - DeadLetterOrchestrator orchestrator = new DeadLetterOrchestrator(publisher); - - DeadLetterResult result = - orchestrator - .deadLetter( - DeadLetterFixtures.profile(), - DeadLetterFixtures.delivery(), - DeadLetterFixtures.failure(), - () -> { - sourceSettled.set(true); - return CompletableFuture.completedFuture(null); - }) - .toCompletableFuture() - .join(); - - assertThat(publisher.publishedBeforeSettlement()).isTrue(); - assertThat(result.sourceSettled()).isTrue(); - assertThat(sourceSettled).isTrue(); - } - - @Test - void keepsSourceUnsettledWhenDlqPublishFails() { - AtomicBoolean sourceSettled = new AtomicBoolean(false); - DeadLetterOrchestrator orchestrator = new DeadLetterOrchestrator(FakePublisher.ambiguous()); - - DeadLetterResult result = - orchestrator - .deadLetter( - DeadLetterFixtures.profile(), - DeadLetterFixtures.delivery(), - DeadLetterFixtures.failure(), - () -> { - sourceSettled.set(true); - return CompletableFuture.completedFuture(null); - }) - .toCompletableFuture() - .join(); - - assertThat(result.sourceSettled()).isFalse(); - assertThat(sourceSettled).isFalse(); - } - - @Test - void keepsSourceUnsettledWhenTheBrokerRejectsTheDeadLetterPublish() { - AtomicBoolean sourceSettled = new AtomicBoolean(false); - DeadLetterOrchestrator orchestrator = new DeadLetterOrchestrator(FakePublisher.rejecting()); - - DeadLetterResult result = - orchestrator - .deadLetter( - DeadLetterFixtures.profile(), - DeadLetterFixtures.delivery(), - DeadLetterFixtures.failure(), - () -> { - sourceSettled.set(true); - return CompletableFuture.completedFuture(null); - }) - .toCompletableFuture() - .join(); - - assertThat(result.sourceSettled()).isFalse(); - assertThat(sourceSettled).isFalse(); - } - - @Test - void preservesTheLogicalMessageIdAndPayload() { - FakePublisher publisher = FakePublisher.confirming(); - MessageDelivery delivery = DeadLetterFixtures.delivery(); - - new DeadLetterOrchestrator(publisher) - .deadLetter( - DeadLetterFixtures.profile(), - delivery, - DeadLetterFixtures.failure(), - () -> CompletableFuture.completedFuture(null)) - .toCompletableFuture() - .join(); - - MessageEnvelope published = publisher.lastEnvelope(); - assertThat(published.messageId()).isEqualTo(delivery.message().messageId()); - assertThat(published.payload().bytes()).isEqualTo(delivery.message().payload().bytes()); - } - - @Test - void publishesToTheConfiguredDeadLetterDestination() { - FakePublisher publisher = FakePublisher.confirming(); - - new DeadLetterOrchestrator(publisher) - .deadLetter( - DeadLetterFixtures.profile(), - DeadLetterFixtures.delivery(), - DeadLetterFixtures.failure(), - () -> CompletableFuture.completedFuture(null)) - .toCompletableFuture() - .join(); - - assertThat(publisher.lastDestination().name()) - .isEqualTo(new DestinationName("order-events-dlq")); - } - - @Test - void writesFailureContextIntoReservedHeadersOnly() { - FakePublisher publisher = FakePublisher.confirming(); - - new DeadLetterOrchestrator(publisher) - .deadLetter( - DeadLetterFixtures.profile(), - DeadLetterFixtures.delivery(), - DeadLetterFixtures.failure(), - () -> CompletableFuture.completedFuture(null)) - .toCompletableFuture() - .join(); - - MessageHeaders headers = publisher.lastEnvelope().headers(); - assertThat(headers.find(ReservedHeaders.FAILURE_CATEGORY)) - .map(HeaderValue::value) - .hasValue("PERMANENT_BUSINESS"); - assertThat(headers.find(ReservedHeaders.FAILURE_CODE)) - .map(HeaderValue::value) - .hasValue("ORDER_REJECTED"); - assertThat(headers.find(ReservedHeaders.ORIGIN_DESTINATION)) - .map(HeaderValue::value) - .hasValue("order-events"); - assertThat(headers.find("stacktrace")).isEmpty(); - } -} - -/** Builds dead letter fixtures. */ -final class DeadLetterFixtures { - - private DeadLetterFixtures() {} - - static DestinationProfile profile() { - return DestinationProfileFixtures.named( - "order-events", - RetryPolicy.none(), - DeadLetterPolicy.to(new DestinationName("order-events-dlq"))); - } - - static FailureDescriptor failure() { - return FailureDescriptor.of( - FailureCategory.PERMANENT_BUSINESS, "ORDER_REJECTED", "the order was rejected"); - } - - static MessageDelivery delivery() { - EncodedMessage payload = - new EncodedMessage( - "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), - ContentType.JSON, - Optional.empty()); - - MessageEnvelope envelope = - new MessageEnvelope<>( - MessageId.newId(), - new MessageType("order.created"), - new SchemaVersion(1), - Instant.parse("2026-08-10T09:15:00Z"), - Optional.of(Instant.parse("2026-08-10T09:15:00Z")), - new ProducerId("order-api"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - payload); - - return new MessageDelivery<>( - envelope, - new DeliveryMetadata( - new DestinationName("order-events"), - 3, - true, - Optional.empty(), - Optional.of("order.events.v1-0"), - Optional.of("order-projection"), - Instant.parse("2026-08-10T09:15:05Z")), - new DeliveryContext(Instant.parse("2026-08-10T09:15:35Z"), false, "order-projection")); - } -} - -/** A publisher that records call order so the settlement sequence can be asserted. */ -final class FakePublisher implements MessagePublisher { - - private final PublishCompletion completion; - private final List events = new ArrayList<>(); - - private MessageDestination lastDestination; - private MessageEnvelope lastEnvelope; - - private FakePublisher(PublishCompletion completion) { - this.completion = completion; - } - - static FakePublisher confirming() { - return new FakePublisher(PublishCompletion.CONFIRMED); - } - - static FakePublisher ambiguous() { - return new FakePublisher(PublishCompletion.AMBIGUOUS); - } - - static FakePublisher rejecting() { - return new FakePublisher(PublishCompletion.REJECTED); - } - - @Override - public CompletionStage publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - lastDestination = destination; - lastEnvelope = message; - events.add("publish"); - return CompletableFuture.completedFuture(result()); - } - - boolean publishedBeforeSettlement() { - return events.indexOf("publish") == 0; - } - - MessageDestination lastDestination() { - return lastDestination; - } - - @SuppressWarnings("unchecked") - MessageEnvelope lastEnvelope() { - return (MessageEnvelope) lastEnvelope; - } - - private PublishResult result() { - return switch (completion) { - case CONFIRMED -> - new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK), - RoutingOutcome.ROUTED, - Optional.empty(), - 1, - Duration.ofMillis(2), - Optional.empty()); - case AMBIGUOUS -> - new PublishResult( - PublishCompletion.AMBIGUOUS, - PublishEvidence.ambiguous(), - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, - Duration.ofSeconds(5), - Optional.of( - FailureDescriptor.of( - FailureCategory.AMBIGUOUS, "CONFIRM_TIMEOUT", "confirm timed out"))); - case REJECTED -> - new PublishResult( - PublishCompletion.REJECTED, - PublishEvidence.notTransmitted(), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ofMillis(1), - Optional.of( - FailureDescriptor.of( - FailureCategory.PERMANENT_BUSINESS, "DLQ_REJECTED", "broker refused"))); - }; - } -} diff --git a/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/DestinationProfileValidatorTest.java b/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/DestinationProfileValidatorTest.java deleted file mode 100644 index 7beb6be4..00000000 --- a/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/DestinationProfileValidatorTest.java +++ /dev/null @@ -1,521 +0,0 @@ -package dev.caskeleton.messaging.policy; - -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.ConfirmationRequirement; -import dev.caskeleton.messaging.api.destination.DestinationKind; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.schema.SchemaCompatibility; -import java.time.Duration; -import java.util.List; -import java.util.Optional; -import java.util.Set; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -class DestinationProfileValidatorTest { - - private final DestinationProfileValidator validator = new DestinationProfileValidator(); - - @Test - void strictOrderingRejectsRetryDestination() { - DestinationProfile profile = - DestinationProfileFixtures.kafkaOrdered( - new RetryPolicy( - RetryMode.RETRY_DESTINATION, - 5, - Duration.ofSeconds(1), - Duration.ofMinutes(1), - 2.0, - true, - OrderingImpact.PRESERVE, - Set.of(), - Set.of())); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("ordering"); - } - - @Test - void payloadAboveHardLimitIsRejected() { - DestinationProfile profile = DestinationProfileFixtures.withPayloadLimit(8_388_609); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("8388608"); - } - - @Test - void dlqCannotPointToItself() { - DestinationProfile profile = DestinationProfileFixtures.selfReferencingDlq(); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("dead letter"); - } - - @Test - void keyedOrderingRequiresAKeyResolver() { - DestinationProfile profile = DestinationProfileFixtures.keyedWithoutResolver(); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("key resolver"); - } - - @Test - void anM1DestinationCannotConfigureManualSettlement() { - DestinationProfile profile = DestinationProfileFixtures.m1WithManualSettlement(); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("manual settlement"); - } - - @Test - void atLeastOnceRequiresAPublishConfirmation() { - DestinationProfile profile = DestinationProfileFixtures.atLeastOnceWithoutConfirmation(); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("confirmation"); - } - - @Test - void atLeastOnceRequiresADeadLetterDestinationEvenWhenRetriesAreDisabled() { - DestinationProfile profile = DestinationProfileFixtures.atLeastOnceWithoutDeadLetter(); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("dead letter destination"); - } - - @Test - void aProductionProfileCannotAutoCreateTopology() { - DestinationProfile profile = DestinationProfileFixtures.productionWithAutoCreate(); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("topology"); - } - - @Test - void aRetryingDestinationNeedsADeadLetterDestination() { - DestinationProfile profile = DestinationProfileFixtures.retryingWithoutDeadLetter(); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("dead letter destination"); - } - - @Test - void retryDestinationCyclesAreRejectedAcrossProfiles() { - List cycle = DestinationProfileFixtures.retryCycle(); - - assertThatThrownBy(() -> validator.validateAll(cycle)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("cycle"); - } - - @Test - @DisplayName("a cycle that alternates retry and dead-letter edges is rejected") - void aMixedEdgeCycleIsRejected() { - List cycle = DestinationProfileFixtures.mixedEdgeCycle(); - - assertThatThrownBy(() -> validator.validateAll(cycle)) - .as("walking the two edge kinds separately misses this and the message loops forever") - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("cycle"); - } - - @Test - @DisplayName("two destinations sharing a dead letter is not a cycle") - void aSharedDeadLetterIsNotACycle() { - List diamond = DestinationProfileFixtures.sharedDeadLetter(); - - org.assertj.core.api.Assertions.assertThatCode(() -> validator.validateAll(diamond)) - .as("a diamond is not a loop; rejecting it would forbid a single shared parking queue") - .doesNotThrowAnyException(); - } - - @Test - void anUnregisteredRetryDestinationIsRejected() { - List dangling = DestinationProfileFixtures.danglingRetryDestination(); - - assertThatThrownBy(() -> validator.validateAll(dangling)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("not registered"); - } - - @Test - void aCoherentProfileValidates() { - assertThatCode(() -> validator.validate(DestinationProfileFixtures.base())) - .doesNotThrowAnyException(); - } -} - -/** Builds destination profiles for validator tests. */ -final class DestinationProfileFixtures { - - private DestinationProfileFixtures() {} - - static SchemaPolicy schema() { - return new SchemaPolicy( - ContentType.JSON, - SchemaCompatibility.BACKWARD_TRANSITIVE, - Set.of(new MessageType("order.created"))); - } - - static DestinationProfile base() { - return new DestinationProfile( - new DestinationName("order-events"), - "kafka-primary", - DestinationKind.EVENT_STREAM, - PhysicalDestination.kafkaTopic("order.events.v1"), - schema(), - DeliveryGuarantee.AT_LEAST_ONCE, - OrderingScope.NONE, - ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED, - ProducerPolicy.defaults(), - ConsumerPolicy.defaults("order-projection"), - RetryPolicy.none(), - DeadLetterPolicy.to(new DestinationName("order-events-dlq")), - PayloadPolicy.defaults(), - ApiTier.M1, - false, - false, - false); - } - - static DestinationProfile kafkaOrdered(RetryPolicy retry) { - DestinationProfile base = base(); - return new DestinationProfile( - base.name(), - base.broker(), - base.kind(), - base.physical(), - base.schema(), - base.deliveryGuarantee(), - OrderingScope.PARTITION, - base.externalSideEffectGuarantee(), - base.producer(), - base.consumer(), - retry, - DeadLetterPolicy.to(new DestinationName("order-events-dlq")), - base.payload(), - base.tier(), - base.production(), - base.keyResolverConfigured(), - base.topologyAutoCreate()); - } - - static DestinationProfile withPayloadLimit(int maxBytes) { - DestinationProfile base = base(); - return new DestinationProfile( - base.name(), - base.broker(), - base.kind(), - base.physical(), - base.schema(), - base.deliveryGuarantee(), - base.orderingScope(), - base.externalSideEffectGuarantee(), - base.producer(), - base.consumer(), - base.retry(), - base.deadLetter(), - new PayloadPolicy(maxBytes, 1_048_576), - base.tier(), - base.production(), - base.keyResolverConfigured(), - base.topologyAutoCreate()); - } - - static DestinationProfile selfReferencingDlq() { - DestinationProfile base = base(); - return new DestinationProfile( - base.name(), - base.broker(), - base.kind(), - base.physical(), - base.schema(), - base.deliveryGuarantee(), - base.orderingScope(), - base.externalSideEffectGuarantee(), - base.producer(), - base.consumer(), - base.retry(), - DeadLetterPolicy.to(base.name()), - base.payload(), - base.tier(), - base.production(), - base.keyResolverConfigured(), - base.topologyAutoCreate()); - } - - static DestinationProfile keyedWithoutResolver() { - DestinationProfile base = base(); - return new DestinationProfile( - base.name(), - base.broker(), - base.kind(), - base.physical(), - base.schema(), - base.deliveryGuarantee(), - OrderingScope.KEY, - base.externalSideEffectGuarantee(), - base.producer(), - base.consumer(), - base.retry(), - base.deadLetter(), - base.payload(), - base.tier(), - base.production(), - false, - base.topologyAutoCreate()); - } - - static DestinationProfile m1WithManualSettlement() { - DestinationProfile base = base(); - return new DestinationProfile( - base.name(), - base.broker(), - base.kind(), - base.physical(), - base.schema(), - base.deliveryGuarantee(), - base.orderingScope(), - base.externalSideEffectGuarantee(), - base.producer(), - new ConsumerPolicy(Optional.of("order-projection"), 1, 1, 16, Duration.ofSeconds(30), true), - base.retry(), - base.deadLetter(), - base.payload(), - ApiTier.M1, - base.production(), - base.keyResolverConfigured(), - base.topologyAutoCreate()); - } - - static DestinationProfile atLeastOnceWithoutConfirmation() { - DestinationProfile base = base(); - return new DestinationProfile( - base.name(), - base.broker(), - base.kind(), - base.physical(), - base.schema(), - DeliveryGuarantee.AT_LEAST_ONCE, - base.orderingScope(), - base.externalSideEffectGuarantee(), - new ProducerPolicy(ConfirmationRequirement.NONE, Duration.ofSeconds(5), true, true), - base.consumer(), - base.retry(), - base.deadLetter(), - base.payload(), - base.tier(), - base.production(), - base.keyResolverConfigured(), - base.topologyAutoCreate()); - } - - static DestinationProfile productionWithAutoCreate() { - DestinationProfile base = base(); - return new DestinationProfile( - base.name(), - base.broker(), - base.kind(), - base.physical(), - base.schema(), - base.deliveryGuarantee(), - base.orderingScope(), - base.externalSideEffectGuarantee(), - base.producer(), - base.consumer(), - base.retry(), - base.deadLetter(), - base.payload(), - base.tier(), - true, - base.keyResolverConfigured(), - true); - } - - static DestinationProfile retryingWithoutDeadLetter() { - DestinationProfile base = base(); - return new DestinationProfile( - base.name(), - base.broker(), - base.kind(), - base.physical(), - base.schema(), - base.deliveryGuarantee(), - base.orderingScope(), - base.externalSideEffectGuarantee(), - base.producer(), - base.consumer(), - new RetryPolicy( - RetryMode.BLOCKING, - 3, - Duration.ofMillis(200), - Duration.ofSeconds(2), - 2.0, - true, - OrderingImpact.PRESERVE, - Set.of(), - Set.of()), - DeadLetterPolicy.disabled(), - base.payload(), - base.tier(), - base.production(), - base.keyResolverConfigured(), - base.topologyAutoCreate()); - } - - static DestinationProfile named(String name, RetryPolicy retry, DeadLetterPolicy deadLetter) { - DestinationProfile base = base(); - return new DestinationProfile( - new DestinationName(name), - base.broker(), - base.kind(), - base.physical(), - base.schema(), - base.deliveryGuarantee(), - base.orderingScope(), - base.externalSideEffectGuarantee(), - base.producer(), - base.consumer(), - retry, - deadLetter, - base.payload(), - base.tier(), - base.production(), - base.keyResolverConfigured(), - base.topologyAutoCreate()); - } - - static DestinationProfile atLeastOnceWithoutDeadLetter() { - DestinationProfile base = base(); - return new DestinationProfile( - base.name(), - base.broker(), - base.kind(), - base.physical(), - base.schema(), - DeliveryGuarantee.AT_LEAST_ONCE, - base.orderingScope(), - base.externalSideEffectGuarantee(), - base.producer(), - base.consumer(), - RetryPolicy.none(), - DeadLetterPolicy.disabled(), - base.payload(), - base.tier(), - base.production(), - base.keyResolverConfigured(), - base.topologyAutoCreate()); - } - - static DestinationProfile atMostOnceWithoutDeadLetter() { - DestinationProfile base = base(); - return new DestinationProfile( - base.name(), - base.broker(), - base.kind(), - base.physical(), - base.schema(), - DeliveryGuarantee.AT_MOST_ONCE, - base.orderingScope(), - base.externalSideEffectGuarantee(), - base.producer(), - base.consumer(), - RetryPolicy.none(), - DeadLetterPolicy.disabled(), - base.payload(), - base.tier(), - base.production(), - base.keyResolverConfigured(), - base.topologyAutoCreate()); - } - - static DestinationProfile parking(String name) { - DestinationProfile base = atMostOnceWithoutDeadLetter(); - return new DestinationProfile( - new DestinationName(name), - base.broker(), - base.kind(), - base.physical(), - 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()); - } - - static RetryPolicy retryTo(String destination) { - return new RetryPolicy( - RetryMode.RETRY_DESTINATION, - 3, - Duration.ofSeconds(1), - Duration.ofMinutes(1), - 2.0, - true, - OrderingImpact.ALLOW_REORDER, - Set.of(), - Set.of(), - Optional.of(new DestinationName(destination))); - } - - static List retryCycle() { - return List.of( - named("alpha", retryTo("beta"), DeadLetterPolicy.to(new DestinationName("alpha-dlq"))), - named("beta", retryTo("alpha"), DeadLetterPolicy.to(new DestinationName("beta-dlq"))), - parking("alpha-dlq"), - parking("beta-dlq")); - } - - /** - * A loop that alternates edge kinds: alpha's retry to beta, beta's dead letter back to alpha. - * - *

Two separate walks — one over retry edges, one over dead-letter edges — each visit alpha - * once and terminate, so both report a clean graph while a poison message circles between the two - * destinations forever. - */ - static List mixedEdgeCycle() { - // alpha retries into beta and parks in its own DLQ; beta dead-letters back into alpha. Each - // single-edge walk visits alpha once and stops, so both report a clean graph. - return List.of( - named("alpha", retryTo("beta"), DeadLetterPolicy.to(new DestinationName("alpha-dlq"))), - named("beta", RetryPolicy.none(), DeadLetterPolicy.to(new DestinationName("alpha"))), - parking("alpha-dlq")); - } - - /** Two destinations dead-lettering into the same place: a diamond, not a cycle. */ - static List sharedDeadLetter() { - return List.of( - named("alpha", RetryPolicy.none(), DeadLetterPolicy.to(new DestinationName("shared-dlq"))), - named("beta", RetryPolicy.none(), DeadLetterPolicy.to(new DestinationName("shared-dlq"))), - parking("shared-dlq")); - } - - static List danglingRetryDestination() { - return List.of( - named("alpha", retryTo("missing"), DeadLetterPolicy.to(new DestinationName("alpha-dlq"))), - parking("alpha-dlq")); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/MessagingAdmissionControllerTest.java b/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/MessagingAdmissionControllerTest.java deleted file mode 100644 index 2306d76e..00000000 --- a/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/MessagingAdmissionControllerTest.java +++ /dev/null @@ -1,233 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.error.MessageBackpressureException; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import java.time.Duration; -import java.util.List; -import java.util.concurrent.atomic.AtomicReference; -import org.junit.jupiter.api.Test; - -class MessagingAdmissionControllerTest { - - private static final String DESTINATION = "order.created"; - private static final String OTHER_DESTINATION = "invoice.issued"; - private static final Duration WAITER_BOUND = Duration.ofSeconds(30); - - private static MessagingAdmissionController controller(int limit) { - return new MessagingAdmissionController( - new PayloadLimitGuard(new PayloadPolicy(1024, 512)), - new InFlightLimiter(limit, Duration.ZERO)); - } - - @Test - void anAdmittedPublishOccupiesAPermitUntilItCompletes() { - MessagingAdmissionController controller = controller(2); - - controller.admit(DESTINATION, 100); - - assertThat(controller.inFlight()).isEqualTo(1); - controller.complete(DESTINATION); - assertThat(controller.inFlight()).isZero(); - } - - @Test - void publishingBeyondTheInFlightLimitIsRefusedRatherThanQueued() { - MessagingAdmissionController controller = controller(1); - controller.admit(DESTINATION, 100); - - assertThatThrownBy(() -> controller.admit(DESTINATION, 100)) - .isInstanceOf(MessageBackpressureException.class) - .hasMessageContaining(DESTINATION); - } - - @Test - void backpressureIsRetryableBecauseNothingWasTransmitted() { - MessagingAdmissionController controller = controller(1); - controller.admit(DESTINATION, 100); - - assertThatThrownBy(() -> controller.admit(DESTINATION, 100)) - .isInstanceOfSatisfying( - MessageBackpressureException.class, - exception -> assertThat(exception.failure().retryable()).isTrue()); - } - - @Test - void anOversizedPayloadIsRejectedWithoutConsumingAPermit() { - MessagingAdmissionController controller = controller(1); - - assertThatThrownBy(() -> controller.admit(DESTINATION, 2048)) - .isInstanceOf(MessageTooLargeException.class); - - assertThat(controller.inFlight()) - .as("a message that can never succeed must not occupy a scarce permit") - .isZero(); - } - - @Test - void shutdownStopsAdmittingNewWorkWithoutRevokingPermitsAlreadyHeld() { - MessagingAdmissionController controller = controller(4); - controller.admit(DESTINATION, 100); - - controller.stopAcceptingNewWork(); - - assertThat(controller.isAcceptingNewWork()).isFalse(); - assertThat(controller.inFlight()).isEqualTo(1); - assertThatThrownBy(() -> controller.admit(DESTINATION, 100)) - .isInstanceOf(MessageBackpressureException.class) - .hasMessageContaining("stopped accepting"); - } - - @Test - void aReleaseWithoutAnAdmitCannotRaiseTheCeiling() { - MessagingAdmissionController controller = controller(1); - - controller.complete(DESTINATION); - controller.complete(DESTINATION); - controller.admit(DESTINATION, 100); - - assertThatThrownBy(() -> controller.admit(DESTINATION, 100)) - .as("unbalanced releases must not hand out more permits than the limit") - .isInstanceOf(MessageBackpressureException.class); - } - - @Test - void oneSlowDestinationCannotOccupyEveryPermit() { - MessagingAdmissionController controller = - new MessagingAdmissionController( - new PayloadLimitGuard(new PayloadPolicy(1024, 512)), - new InFlightLimiter(4, Duration.ZERO), - 2); - - controller.admit(DESTINATION, 100); - controller.admit(DESTINATION, 100); - - assertThatThrownBy(() -> controller.admit(DESTINATION, 100)) - .as("a single slow downstream taking every permit is how one destination stops the others") - .isInstanceOf(MessageBackpressureException.class); - assertThat(controller.inFlight("other.destination")).isZero(); - controller.admit("other.destination", 100); - assertThat(controller.inFlight()).isEqualTo(3); - } - - @Test - void aRefusedAdmissionLeavesNoDestinationSlotBehind() { - MessagingAdmissionController controller = - new MessagingAdmissionController( - new PayloadLimitGuard(new PayloadPolicy(1024, 512)), - new InFlightLimiter(1, Duration.ZERO), - 1); - controller.admit(DESTINATION, 100); - - assertThatThrownBy(() -> controller.admit("other.destination", 100)) - .isInstanceOf(MessageBackpressureException.class); - - assertThat(controller.inFlight("other.destination")) - .as("a slot leaked per refusal shrinks the destination's ceiling until it is zero") - .isZero(); - } - - @Test - void completingReturnsBothTheProcessPermitAndTheDestinationSlot() { - MessagingAdmissionController controller = - new MessagingAdmissionController( - new PayloadLimitGuard(new PayloadPolicy(1024, 512)), - new InFlightLimiter(4, Duration.ZERO), - 2); - controller.admit(DESTINATION, 100); - - controller.complete(DESTINATION); - - assertThat(controller.inFlight()).isZero(); - assertThat(controller.inFlight(DESTINATION)).isZero(); - } - - @Test - void completingAnUnknownDestinationFreesNoProcessPermit() { - MessagingAdmissionController controller = controller(2); - controller.admit(DESTINATION, 100); - - controller.complete("something-else"); - - assertThat(controller.inFlight()) - .as("a permit nobody took cannot be given back; doing so makes the ceiling fiction") - .isEqualTo(1); - } - - @Test - void aSecondCompletionForOnePublishFreesNoSecondPermit() { - MessagingAdmissionController controller = controller(4); - controller.admit(DESTINATION, 100); - - controller.complete(DESTINATION); - controller.complete(DESTINATION); - - assertThat(controller.inFlight()).isZero(); - assertThat(controller.inFlight(DESTINATION)).isZero(); - } - - @Test - void aBatchIsBoundedByCountAndByAggregateBytes() { - PayloadLimitGuard guard = new PayloadLimitGuard(new PayloadPolicy(1024, 512)); - - assertThatThrownBy(() -> guard.checkBatch(DESTINATION, List.of(10, 10, 10), 2, 10_000)) - .isInstanceOf(MessageTooLargeException.class) - .hasMessageContaining("entry limit"); - - assertThatThrownBy(() -> guard.checkBatch(DESTINATION, List.of(1000, 1000), 10, 1500)) - .isInstanceOf(MessageTooLargeException.class) - .hasMessageContaining("byte limit"); - } - - @Test - void aWaitingCallerIsAdmittedOnceAPermitIsReturned() throws InterruptedException { - MessagingAdmissionController controller = - new MessagingAdmissionController( - new PayloadLimitGuard(PayloadPolicy.defaults()), new InFlightLimiter(1, WAITER_BOUND)); - controller.admit(DESTINATION, 100); - AtomicReference refused = new AtomicReference<>(); - // Another destination, so only the process-wide permit is contested. A second publish to - // DESTINATION is refused at once by its own ceiling (equal to the process limit here) and - // never waits. - Thread waiter = - new Thread( - () -> { - try { - controller.admit(OTHER_DESTINATION, 100); - } catch (RuntimeException refusal) { - refused.set(refusal); - } - }); - - waiter.start(); - awaitQueuedOnAPermit(waiter, refused); - controller.complete(DESTINATION); - waiter.join(WAITER_BOUND.toMillis()); - - assertThat(refused.get()).as("the waiter was refused instead of admitted").isNull(); - assertThat(waiter.isAlive()).isFalse(); - assertThat(controller.inFlight()).isEqualTo(1); - assertThat(controller.inFlight(OTHER_DESTINATION)).isEqualTo(1); - } - - /** - * Waits until {@code waiter} is parked in the limiter's bounded wait, so the permit is returned - * to a caller that is already queued rather than to one that has not arrived yet. - */ - private static void awaitQueuedOnAPermit(Thread waiter, AtomicReference refused) - throws InterruptedException { - long deadline = System.nanoTime() + WAITER_BOUND.toNanos(); - while (waiter.getState() != Thread.State.TIMED_WAITING - && waiter.isAlive() - && System.nanoTime() < deadline) { - Thread.sleep(1); - } - assertThat(waiter.getState()) - .as( - "the waiter must be queued on the permit before it is returned (refused: %s)", - refused.get()) - .isEqualTo(Thread.State.TIMED_WAITING); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/RetryDecisionEngineTest.java b/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/RetryDecisionEngineTest.java deleted file mode 100644 index 6a8dc244..00000000 --- a/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/RetryDecisionEngineTest.java +++ /dev/null @@ -1,258 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.delivery.DeliveryMetadata; -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 java.time.Duration; -import java.time.Instant; -import java.util.Optional; -import java.util.Set; -import org.junit.jupiter.api.Test; - -class RetryDecisionEngineTest { - - private final DefaultRetryDecisionEngine engine = - new DefaultRetryDecisionEngine(new BackoffCalculator(() -> 1.0)); - - @Test - void deserializationFailureGoesDirectlyToParking() { - RetryDecision decision = - engine.decide(RetryContextFixtures.failure(FailureCategory.DESERIALIZATION, 1)); - - assertThat(decision).isInstanceOf(RetryDecision.DeadLetter.class); - } - - @Test - void authenticationAndConfigurationFailuresAreNeverRetried() { - assertThat(engine.decide(RetryContextFixtures.failure(FailureCategory.AUTHENTICATION, 1))) - .isInstanceOf(RetryDecision.DeadLetter.class); - assertThat(engine.decide(RetryContextFixtures.failure(FailureCategory.CONFIGURATION, 1))) - .isInstanceOf(RetryDecision.DeadLetter.class); - assertThat(engine.decide(RetryContextFixtures.failure(FailureCategory.AUTHORIZATION, 1))) - .isInstanceOf(RetryDecision.DeadLetter.class); - } - - @Test - void transientOrderedKafkaFailureUsesPauseStrategy() { - RetryDecision decision = engine.decide(RetryContextFixtures.orderedKafkaTransient(1)); - - assertThat(decision).isInstanceOf(RetryDecision.PauseAndRetry.class); - } - - @Test - void exhaustedAttemptGoesToDeadLetter() { - RetryDecision decision = engine.decide(RetryContextFixtures.transientAtMaximumAttempt()); - - assertThat(decision).isInstanceOf(RetryDecision.DeadLetter.class); - } - - @Test - void unorderedRetryDestinationModeRePublishes() { - RetryDecision decision = engine.decide(RetryContextFixtures.unorderedRetryDestination(1)); - - assertThat(decision) - .isInstanceOfSatisfying( - RetryDecision.PublishToRetryDestination.class, - publish -> - assertThat(publish.destination()) - .isEqualTo(new DestinationName("email-work-retry"))); - } - - @Test - void blockingModeRetriesInline() { - RetryDecision decision = engine.decide(RetryContextFixtures.blockingTransient(1)); - - assertThat(decision).isInstanceOf(RetryDecision.RetryInline.class); - } - - @Test - void backoffGrowsExponentiallyAndIsCappedByMaxDelay() { - BackoffCalculator calculator = new BackoffCalculator(() -> 1.0); - RetryPolicy policy = - new RetryPolicy( - RetryMode.BLOCKING, - 10, - Duration.ofMillis(200), - Duration.ofSeconds(2), - 2.0, - false, - OrderingImpact.PRESERVE, - Set.of(), - Set.of()); - - assertThat(calculator.delayFor(policy, 1)).isEqualTo(Duration.ofMillis(200)); - assertThat(calculator.delayFor(policy, 2)).isEqualTo(Duration.ofMillis(400)); - assertThat(calculator.delayFor(policy, 3)).isEqualTo(Duration.ofMillis(800)); - assertThat(calculator.delayFor(policy, 9)).isEqualTo(Duration.ofSeconds(2)); - } - - @Test - void fullJitterSpreadsRetriesAcrossTheWholeWindow() { - RetryPolicy policy = - new RetryPolicy( - RetryMode.BLOCKING, - 10, - Duration.ofSeconds(1), - Duration.ofSeconds(2), - 2.0, - true, - OrderingImpact.PRESERVE, - Set.of(), - Set.of()); - - assertThat(new BackoffCalculator(() -> 0.0).delayFor(policy, 1)).isEqualTo(Duration.ZERO); - assertThat(new BackoffCalculator(() -> 0.5).delayFor(policy, 1)) - .isEqualTo(Duration.ofMillis(500)); - } - - @Test - void anExplicitProfileOverrideCanMakeACategoryRetryable() { - RetryDecision decision = - engine.decide(RetryContextFixtures.withRetryableOverride(FailureCategory.DESERIALIZATION)); - - assertThat(decision).isInstanceOf(RetryDecision.RetryInline.class); - } - - @Test - void anAtMostOnceDestinationWithoutDlqDiscards() { - RetryDecision decision = engine.decide(RetryContextFixtures.atMostOnceWithoutDlq()); - - assertThat(decision).isInstanceOf(RetryDecision.Reject.class); - } -} - -/** Builds retry contexts for engine tests. */ -final class RetryContextFixtures { - - private RetryContextFixtures() {} - - private static final MessagingCapabilities ORDERED_KAFKA = - MessagingCapabilities.of( - MessagingCapabilities.Capability.ORDERED_STREAM, - MessagingCapabilities.Capability.DEDUPLICATED_PUBLISH); - - private static final MessagingCapabilities PLAIN_QUEUE = MessagingCapabilities.none(); - - static DeliveryMetadata delivery(int attempt) { - return new DeliveryMetadata( - new DestinationName("order-events"), - attempt, - attempt > 1, - Optional.empty(), - Optional.of("order.events.v1-0"), - Optional.of("order-projection"), - Instant.parse("2026-08-10T00:00:00Z")); - } - - static RetryContext failure(FailureCategory category, int attempt) { - return new RetryContext( - DestinationProfileFixtures.kafkaOrdered(pausePolicy()), - delivery(attempt), - FailureDescriptor.of(category, category.name(), "failed"), - ORDERED_KAFKA, - false); - } - - static RetryContext orderedKafkaTransient(int attempt) { - return new RetryContext( - DestinationProfileFixtures.kafkaOrdered(pausePolicy()), - delivery(attempt), - FailureDescriptor.of( - FailureCategory.TRANSIENT_INFRASTRUCTURE, "BROKER_TIMEOUT", "broker timed out"), - ORDERED_KAFKA, - false); - } - - static RetryContext transientAtMaximumAttempt() { - return new RetryContext( - DestinationProfileFixtures.kafkaOrdered(pausePolicy()), - delivery(3), - FailureDescriptor.of( - FailureCategory.TRANSIENT_INFRASTRUCTURE, "BROKER_TIMEOUT", "broker timed out"), - ORDERED_KAFKA, - false); - } - - static RetryContext unorderedRetryDestination(int attempt) { - return new RetryContext( - DestinationProfileFixtures.named( - "email-work", - DestinationProfileFixtures.retryTo("email-work-retry"), - DeadLetterPolicy.to(new DestinationName("email-work-dlq"))), - delivery(attempt), - FailureDescriptor.of( - FailureCategory.PROCESSING_TRANSIENT, "DOWNSTREAM_TIMEOUT", "downstream timed out"), - PLAIN_QUEUE, - false); - } - - static RetryContext blockingTransient(int attempt) { - return new RetryContext( - DestinationProfileFixtures.named( - "email-work", blockingPolicy(), DeadLetterPolicy.to(new DestinationName("email-dlq"))), - delivery(attempt), - FailureDescriptor.of(FailureCategory.THROTTLED, "RATE_LIMITED", "throttled"), - PLAIN_QUEUE, - false); - } - - static RetryContext withRetryableOverride(FailureCategory category) { - RetryPolicy policy = - new RetryPolicy( - RetryMode.BLOCKING, - 3, - Duration.ofMillis(100), - Duration.ofSeconds(1), - 2.0, - false, - OrderingImpact.PRESERVE, - Set.of(category), - Set.of()); - return new RetryContext( - DestinationProfileFixtures.named( - "email-work", policy, DeadLetterPolicy.to(new DestinationName("email-dlq"))), - delivery(1), - FailureDescriptor.of(category, category.name(), "failed"), - PLAIN_QUEUE, - false); - } - - static RetryContext atMostOnceWithoutDlq() { - return new RetryContext( - DestinationProfileFixtures.atMostOnceWithoutDeadLetter(), - delivery(1), - FailureDescriptor.of(FailureCategory.PERMANENT_BUSINESS, "INVALID", "rejected"), - PLAIN_QUEUE, - false); - } - - private static RetryPolicy pausePolicy() { - return new RetryPolicy( - RetryMode.PAUSE_PARTITION, - 3, - Duration.ofMillis(200), - Duration.ofSeconds(2), - 2.0, - false, - OrderingImpact.PRESERVE, - Set.of(), - Set.of()); - } - - private static RetryPolicy blockingPolicy() { - return new RetryPolicy( - RetryMode.BLOCKING, - 5, - Duration.ofMillis(200), - Duration.ofSeconds(2), - 2.0, - false, - OrderingImpact.PRESERVE, - Set.of(), - Set.of()); - } -} diff --git a/src/platforms/messaging/messaging-reliability-api/build.gradle b/src/platforms/messaging/messaging-reliability-api/build.gradle deleted file mode 100644 index fac7b208..00000000 --- a/src/platforms/messaging/messaging-reliability-api/build.gradle +++ /dev/null @@ -1,7 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') -} diff --git a/src/platforms/messaging/messaging-reliability-api/gradle.lockfile b/src/platforms/messaging/messaging-reliability-api/gradle.lockfile deleted file mode 100644 index d74807c4..00000000 --- a/src/platforms/messaging/messaging-reliability-api/gradle.lockfile +++ /dev/null @@ -1,82 +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.50.0=annotationProcessor,checkstyle,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.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -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.6.1=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.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty=compileClasspath,runtimeClasspath diff --git a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/ClaimCheckReference.java b/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/ClaimCheckReference.java deleted file mode 100644 index 1985439f..00000000 --- a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/ClaimCheckReference.java +++ /dev/null @@ -1,50 +0,0 @@ -package dev.caskeleton.messaging.reliability; - -import java.time.Instant; -import java.util.Objects; -import java.util.regex.Pattern; - -/** - * Points at a payload stored outside the broker. - * - *

The digest is part of the reference, not an optional extra. A claim check splits a message - * into two systems with independent retention and replication, so a consumer that fetches the - * payload has to be able to prove it got the bytes the producer stored — otherwise a truncated or - * replaced object is indistinguishable from a valid one. - * - *

The expiry is carried for the same reason: a claim check whose payload has been reaped is a - * dead message, and detecting that at fetch time is better than a mysterious not-found. - * - * @param storageKey the object key in the payload store - * @param sizeBytes the stored payload size - * @param sha256 the lowercase hex digest of the stored payload - * @param expiresAt when the payload store may reap the object - */ -public record ClaimCheckReference( - String storageKey, long sizeBytes, String sha256, Instant expiresAt) { - - private static final Pattern SHA256 = Pattern.compile("[a-f0-9]{64}"); - - public ClaimCheckReference { - Objects.requireNonNull(expiresAt, "expiresAt must not be null"); - if (storageKey == null || storageKey.isBlank()) { - throw new IllegalArgumentException("storageKey must not be blank"); - } - if (sizeBytes < 0) { - throw new IllegalArgumentException("sizeBytes must not be negative"); - } - if (sha256 == null || !SHA256.matcher(sha256).matches()) { - throw new IllegalArgumentException("sha256 must be 64 lowercase hex characters"); - } - } - - /** - * Reports whether the payload store may already have reaped this object. - * - * @param now the current instant - * @return true once the retention window has passed - */ - public boolean isExpired(Instant now) { - return !now.isBefore(expiresAt); - } -} diff --git a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/InboxRepository.java b/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/InboxRepository.java deleted file mode 100644 index 55846b4e..00000000 --- a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/InboxRepository.java +++ /dev/null @@ -1,45 +0,0 @@ -package dev.caskeleton.messaging.reliability; - -import dev.caskeleton.messaging.api.MessageId; -import java.time.Instant; - -/** - * Storage for consumer-side deduplication. - * - *

{@link #reserve} must run inside the same database transaction as the handler's side effect. - * That is the entire mechanism: the uniqueness constraint on the inbox row and the business write - * commit together, so a redelivered message either finds the row already present and skips, or - * writes both. Reserving in a separate transaction reintroduces exactly the gap the Inbox exists to - * close. - */ -public interface InboxRepository { - - /** - * Reserves a message for processing inside the caller's transaction. - * - * @param messageId the logical message identity - * @param consumerId the consumer's stable identity - * @param now the current instant - * @return true when this is the first time; false when it was already processed - */ - boolean reserve(MessageId messageId, String consumerId, Instant now); - - /** - * Reports whether a message has already been processed by a consumer. - * - * @param messageId the logical message identity - * @param consumerId the consumer's stable identity - * @return true when already recorded - */ - boolean isProcessed(MessageId messageId, String consumerId); - - /** - * Deletes at most {@code limit} processed rows older than the cutoff. - * - *

Retention must outlive the broker's maximum redelivery window, otherwise a late redelivery - * arrives after its inbox row was pruned and is processed a second time. - * - * @return how many rows were deleted; fewer than {@code limit} means the sweep is finished - */ - int purgeProcessedBefore(Instant processedBefore, int limit); -} diff --git a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxCanonicalMetadata.java b/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxCanonicalMetadata.java deleted file mode 100644 index 6747d565..00000000 --- a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxCanonicalMetadata.java +++ /dev/null @@ -1,158 +0,0 @@ -package dev.caskeleton.messaging.reliability; - -import dev.caskeleton.messaging.api.CausationId; -import dev.caskeleton.messaging.api.CorrelationId; -import dev.caskeleton.messaging.api.ProducerId; -import dev.caskeleton.messaging.api.TenantContext; -import dev.caskeleton.messaging.api.TraceContext; -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; - -/** - * The envelope facts an outbox row carries in its own columns. - * - *

They used to live nowhere. A row held identity, type, version, content type, payload and an - * arbitrary header map, so producer, tenant, correlation, causation, trace and schema were either - * invented when the envelope was rebuilt — {@code Optional.empty()} for every one of them — or - * smuggled through the header map under reserved names the platform was supposed to own. - * - *

Both routes fail in the same direction. A relay cannot filter, route or diagnose by tenant - * without decoding the payload, so the operational question "which tenant is backed up" has no - * answer; and a message that crossed the outbox arrived at its consumer with a different tenant, - * trace and correlation than the one that was published, which makes the publish path — direct, - * polling or CDC — part of the message's meaning. - * - *

Columns rather than a blob, because the point is that the database can answer questions about - * them. A versioned envelope encoding would round-trip just as faithfully and would still leave the - * relay unable to select rows for one tenant. - * - *

Every field is optional except the trace context, which has its own empty form. A row written - * before these columns existed has none of them, and a row written by a producer that genuinely has - * no correlation is not distinguishable from it — nor does it need to be, because the reader's - * behaviour is the same: carry what is there and invent nothing. - * - * @param producer the logical producing service that wrote the row - * @param occurredAt the instant the business fact occurred, when it differs from the write - * @param correlationId the workflow correlation - * @param causationId the directly causing message - * @param tenant the tenant this message belongs to - * @param partitionKey the broker distribution key - * @param orderingKey the ordering key - * @param schemaSubject the registry subject the payload was written against - * @param schemaUri the resolvable schema location, when one exists - * @param traceContext the W3C trace values active when the row was written - */ -public record OutboxCanonicalMetadata( - Optional producer, - Optional occurredAt, - Optional correlationId, - Optional causationId, - Optional tenant, - Optional partitionKey, - Optional orderingKey, - Optional schemaSubject, - Optional schemaUri, - TraceContext traceContext) { - - public OutboxCanonicalMetadata { - Objects.requireNonNull(producer, "producer must not be null"); - Objects.requireNonNull(occurredAt, "occurredAt must not be null"); - Objects.requireNonNull(correlationId, "correlationId must not be null"); - Objects.requireNonNull(causationId, "causationId must not be null"); - Objects.requireNonNull(tenant, "tenant must not be null"); - Objects.requireNonNull(partitionKey, "partitionKey must not be null"); - Objects.requireNonNull(orderingKey, "orderingKey must not be null"); - Objects.requireNonNull(schemaSubject, "schemaSubject must not be null"); - Objects.requireNonNull(schemaUri, "schemaUri must not be null"); - Objects.requireNonNull(traceContext, "traceContext must not be null"); - if (schemaUri.isPresent() && schemaSubject.isEmpty()) { - throw new IllegalArgumentException( - "a schema location without a subject cannot be resolved; a reader would have a URI and " - + "no way to know what it is a schema for"); - } - } - - /** - * Returns the metadata of a row that carries none. - * - *

Used by callers that write an outbox row from a message with no provenance of its own, and - * by the reader for rows written before these columns existed. - * - * @return empty canonical metadata - */ - public static OutboxCanonicalMetadata none() { - return new OutboxCanonicalMetadata( - Optional.empty(), - Optional.empty(), - Optional.empty(), - Optional.empty(), - Optional.empty(), - Optional.empty(), - Optional.empty(), - Optional.empty(), - Optional.empty(), - TraceContext.none()); - } - - /** - * Returns a copy naming the producing service. - * - * @param producingService the logical producing service - * @return the metadata with its producer set - */ - public OutboxCanonicalMetadata withProducer(ProducerId producingService) { - return new OutboxCanonicalMetadata( - Optional.of(Objects.requireNonNull(producingService, "producer must not be null")), - occurredAt, - correlationId, - causationId, - tenant, - partitionKey, - orderingKey, - schemaSubject, - schemaUri, - traceContext); - } - - /** - * Returns a copy bound to a tenant. - * - * @param owner the tenant this message belongs to - * @return the metadata with its tenant set - */ - public OutboxCanonicalMetadata withTenant(TenantContext owner) { - return new OutboxCanonicalMetadata( - producer, - occurredAt, - correlationId, - causationId, - Optional.of(Objects.requireNonNull(owner, "tenant must not be null")), - partitionKey, - orderingKey, - schemaSubject, - schemaUri, - traceContext); - } - - /** - * Returns a copy carrying the broker routing keys. - * - * @param distributionKey the partition key, or null for none - * @param ordering the ordering key, or null for none - * @return the metadata with its routing keys set - */ - public OutboxCanonicalMetadata withRoutingKeys(String distributionKey, String ordering) { - return new OutboxCanonicalMetadata( - producer, - occurredAt, - correlationId, - causationId, - tenant, - Optional.ofNullable(distributionKey), - Optional.ofNullable(ordering), - schemaSubject, - schemaUri, - traceContext); - } -} diff --git a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxLease.java b/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxLease.java deleted file mode 100644 index 58a6884a..00000000 --- a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxLease.java +++ /dev/null @@ -1,42 +0,0 @@ -package dev.caskeleton.messaging.reliability; - -import java.time.Instant; -import java.util.Objects; - -/** - * One relay's claim on one outbox record. - * - *

The port used to take a {@code MessageId} for every terminal transition, so a write said which - * row to change and nothing about which claim it belonged to. A relay that stalled past its lease - * could still record {@code AMBIGUOUS} over the {@code PUBLISHED} another relay had already - * written, and the row became claimable again — one message, published twice, by a system whose - * whole purpose is to publish it once. - * - *

The token is the part that makes staleness detectable. It increases on every claim, so a - * superseded relay holds a number the row no longer has and its update matches zero rows. - */ -public record OutboxLease(OutboxRecord record, String owner, long token, Instant expiresAt) { - - public OutboxLease { - Objects.requireNonNull(record, "record must not be null"); - Objects.requireNonNull(owner, "owner must not be null"); - Objects.requireNonNull(expiresAt, "expiresAt must not be null"); - if (owner.isBlank()) { - throw new IllegalArgumentException("a lease names its owner"); - } - if (token < 1) { - throw new IllegalArgumentException( - "a claim's token starts at 1; 0 is the value of a row nobody has claimed"); - } - } - - /** The claimed record's identity. */ - public dev.caskeleton.messaging.api.MessageId messageId() { - return record.messageId(); - } - - /** True when this lease has run out at the given moment. */ - public boolean expiredAt(Instant now) { - return !Objects.requireNonNull(now, "now must not be null").isBefore(expiresAt); - } -} diff --git a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRecord.java b/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRecord.java deleted file mode 100644 index d6949953..00000000 --- a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRecord.java +++ /dev/null @@ -1,140 +0,0 @@ -package dev.caskeleton.messaging.reliability; - -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 java.time.Instant; -import java.util.Arrays; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; - -/** - * One row of the transactional outbox. - * - *

The whole point of the pattern is that this row is written in the same database - * transaction as the business change. Either both commit or neither does, which removes the window - * where a service updates its state and then dies before publishing. - * - *

What the outbox does not do is remove duplicates. A relay that cannot confirm a publish will - * retry it, and the same message may reach the broker twice. Effectively-once processing comes from - * this row carrying a stable {@code messageId} and the consumer having an Inbox — not from the - * outbox alone. - * - *

{@link OutboxCanonicalMetadata} is a separate component rather than more fields here because - * the two halves answer to different owners. Identity, payload, status, attempts and lease are the - * relay's bookkeeping; the metadata is the message's own provenance, and it is the half that has to - * survive the round trip through the database unchanged. - * - * @param messageId the stable logical identity, preserved across every retry - * @param destination the logical destination - * @param messageType the catalog message type - * @param schemaVersion the payload schema revision - * @param contentType the codec media type - * @param payload the encoded payload - * @param headers the application headers to publish; reserved names are refused - * @param metadata the canonical envelope facts this row carries in its own columns - * @param createdAt when the business transaction wrote this row - * @param status the current lifecycle state - * @param attempts how many publish attempts have been made - * @param leaseExpiresAt when the current relay lease expires - * @param lastFailureCode the last sanitized failure code - */ -@SuppressWarnings("ArrayRecordComponent") -public record OutboxRecord( - MessageId messageId, - DestinationName destination, - MessageType messageType, - SchemaVersion schemaVersion, - ContentType contentType, - byte[] payload, - Map headers, - OutboxCanonicalMetadata metadata, - Instant createdAt, - OutboxStatus status, - int attempts, - Optional leaseExpiresAt, - Optional lastFailureCode) { - - public OutboxRecord { - Objects.requireNonNull(messageId, "messageId must not be null"); - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(messageType, "messageType must not be null"); - Objects.requireNonNull(schemaVersion, "schemaVersion must not be null"); - Objects.requireNonNull(contentType, "contentType must not be null"); - Objects.requireNonNull(payload, "payload must not be null"); - Objects.requireNonNull(headers, "headers must not be null"); - Objects.requireNonNull(metadata, "metadata must not be null"); - Objects.requireNonNull(createdAt, "createdAt must not be null"); - Objects.requireNonNull(status, "status must not be null"); - Objects.requireNonNull(leaseExpiresAt, "leaseExpiresAt must not be null"); - Objects.requireNonNull(lastFailureCode, "lastFailureCode must not be null"); - if (attempts < 0) { - throw new IllegalArgumentException("attempts must not be negative"); - } - payload = payload.clone(); - headers = Map.copyOf(headers); - } - - @Override - public byte[] payload() { - return payload.clone(); - } - - /** - * Returns a copy in a new lifecycle state. - * - *

The message id is never a parameter, so no state transition can change it. - * - * @param newStatus the new status - * @param newAttempts the updated attempt count - * @param failureCode the last sanitized failure code - * @return the updated record - */ - public OutboxRecord withStatus( - OutboxStatus newStatus, int newAttempts, Optional failureCode) { - return new OutboxRecord( - messageId, - destination, - messageType, - schemaVersion, - contentType, - payload, - headers, - metadata, - createdAt, - newStatus, - newAttempts, - leaseExpiresAt, - failureCode); - } - - @Override - public boolean equals(Object other) { - return other instanceof OutboxRecord record - && messageId.equals(record.messageId) - && status == record.status - && attempts == record.attempts - && Arrays.equals(payload, record.payload); - } - - @Override - public int hashCode() { - return Objects.hash(messageId, status, attempts, Arrays.hashCode(payload)); - } - - @Override - public String toString() { - return "OutboxRecord[messageId=" - + messageId.value() - + ", destination=" - + destination.value() - + ", status=" - + status - + ", attempts=" - + attempts - + "]"; - } -} diff --git a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRepository.java b/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRepository.java deleted file mode 100644 index 6765abfb..00000000 --- a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRepository.java +++ /dev/null @@ -1,92 +0,0 @@ -package dev.caskeleton.messaging.reliability; - -import dev.caskeleton.messaging.api.MessageId; -import java.time.Duration; -import java.time.Instant; -import java.util.List; -import java.util.Optional; - -/** - * Storage for the transactional outbox. - * - *

{@link #append} must be callable inside the caller's business transaction; every other method - * runs in the relay's own transaction. - */ -public interface OutboxRepository { - - /** - * Appends a record inside the caller's transaction. - * - * @param record the record to write - */ - void append(OutboxRecord record); - - /** - * Claims a batch and returns the leases, each carrying its owner and fencing token, skipping rows - * that are waiting for their backoff or out of attempts. - * - *

Claiming rather than simply selecting is what makes multiple relay instances safe: a record - * claimed by one relay is invisible to the others until its lease expires, and the token is what - * a terminal write is checked against, so a relay that stalled past its lease writes nothing. - * - *

Eligibility belongs in the row. A relay that decides in memory forgets on restart, and every - * replica decides for itself — so the same message is retried by as many workers as there are - * replicas, as often as they poll. - * - * @param owner this relay's stable identity - * @param batchSize how many records to claim - * @param leaseDuration how long the claim holds - * @param now the current instant - * @param maxAttempts the attempt budget; rows at or above it are not claimed - * @return the leases, oldest first - */ - List claimBatch( - String owner, int batchSize, Duration leaseDuration, Instant now, int maxAttempts); - - /** - * Records a confirmed publication, only if this lease still owns the row. - * - * @return {@link OutboxTransitionResult#STALE_LEASE} when another relay has taken it - */ - OutboxTransitionResult markPublished(OutboxLease lease, Instant now); - - /** - * Records an ambiguous outcome and when this row may next be claimed, only if this lease still - * owns the row. - */ - OutboxTransitionResult markAmbiguous( - OutboxLease lease, String failureCode, Instant now, Instant nextAttemptAt); - - /** - * Parks a row whose attempt budget ran out. - * - *

Separate from {@link #markFailed}: a rejected message is invalid, an exhausted one never got - * an answer. The first needs a fix, the second a redrive. - */ - OutboxTransitionResult markExhausted(OutboxLease lease, String reason, Instant now); - - /** Records a terminal failure, only if this lease still owns the row. */ - OutboxTransitionResult markFailed(OutboxLease lease, String failureCode, Instant now); - - /** Gives a claim back, only if this lease still owns the row. */ - OutboxTransitionResult releaseLease(OutboxLease lease); - - /** - * Finds one record. - * - * @param messageId the record identity - * @return the record when present - */ - Optional find(MessageId messageId); - - /** - * Deletes at most {@code limit} published rows older than the cutoff. - * - *

There is no unbounded version. Deleting everything before the cutoff in one statement is a - * single long transaction holding locks and generating WAL in proportion to the backlog, which - * shows up as the relay and the business writes stalling behind retention. - * - * @return how many rows were deleted; fewer than {@code limit} means the sweep is finished - */ - int purgePublishedBefore(Instant publishedBefore, int limit); -} diff --git a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxStatus.java b/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxStatus.java deleted file mode 100644 index d15ba366..00000000 --- a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxStatus.java +++ /dev/null @@ -1,37 +0,0 @@ -package dev.caskeleton.messaging.reliability; - -/** - * Where an outbox record is in its lifecycle. - * - *

{@link #AMBIGUOUS} is a distinct state rather than a flavour of failure. A record whose - * publish timed out may already be on the broker; retrying it is correct, but only under the same - * logical message id, and an operator looking at the table needs to be able to tell those rows - * apart from ones that definitely never landed. - */ -public enum OutboxStatus { - - /** Written by the business transaction, not yet picked up by the relay. */ - PENDING, - - /** Leased by a relay instance and being published. */ - IN_FLIGHT, - - /** Confirmed by the broker. */ - PUBLISHED, - - /** The publish outcome was unknown; the broker may hold it. */ - AMBIGUOUS, - - /** Definitively rejected; will not be retried without intervention. */ - FAILED, - - /** - * The attempt budget ran out before any confirmed publish. - * - *

Distinct from {@link #FAILED}, which means the broker refused the message: this one means - * nobody ever got an answer. Collapsing the two loses the difference between "this message is - * invalid" and "the broker was unreachable for an hour", and those need different operator - * actions — the first a fix, the second a redrive. - */ - EXHAUSTED -} diff --git a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxTransitionResult.java b/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxTransitionResult.java deleted file mode 100644 index 923c9585..00000000 --- a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxTransitionResult.java +++ /dev/null @@ -1,24 +0,0 @@ -package dev.caskeleton.messaging.reliability; - -/** - * What a terminal outbox write actually did. - * - *

The transitions returned {@code void}, so an update that matched zero rows was - * indistinguishable from one that matched one. That is precisely the stale-lease case: the relay - * believes it recorded the outcome, the row still says something else, and nothing anywhere counts - * the disagreement. - */ -public enum OutboxTransitionResult { - - /** The row moved to the requested state. */ - APPLIED, - - /** - * The row is no longer this lease's. - * - *

Another relay claimed it after the lease expired. Not an error to throw — the message is - * being handled by somebody else — but never a success either: it is the signal that this - * worker's publish attempt may have produced a duplicate, and it belongs on a metric. - */ - STALE_LEASE -} diff --git a/src/platforms/messaging/messaging-reliability-api/src/test/java/dev/caskeleton/messaging/reliability/OutboxRepositoryApiSafetyTest.java b/src/platforms/messaging/messaging-reliability-api/src/test/java/dev/caskeleton/messaging/reliability/OutboxRepositoryApiSafetyTest.java deleted file mode 100644 index 72c780e1..00000000 --- a/src/platforms/messaging/messaging-reliability-api/src/test/java/dev/caskeleton/messaging/reliability/OutboxRepositoryApiSafetyTest.java +++ /dev/null @@ -1,24 +0,0 @@ -package dev.caskeleton.messaging.reliability; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.MessageId; -import java.lang.reflect.Method; -import java.util.Set; -import org.junit.jupiter.api.Test; - -class OutboxRepositoryApiSafetyTest { - @Test - void outcomeTransitionsDoNotExposeUnfencedMessageIdOverloadsUnderTheSafeNames() { - Set fencedNames = - Set.of("markPublished", "markAmbiguous", "markFailed", "releaseLease"); - - assertThat(OutboxRepository.class.getMethods()) - .filteredOn(method -> fencedNames.contains(method.getName())) - .noneMatch(OutboxRepositoryApiSafetyTest::startsWithMessageId); - } - - private static boolean startsWithMessageId(Method method) { - return method.getParameterCount() > 0 && method.getParameterTypes()[0] == MessageId.class; - } -} diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/build.gradle b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/build.gradle deleted file mode 100644 index f549b2d0..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/build.gradle +++ /dev/null @@ -1,50 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -testing { - suites { - integrationTest(JvmTestSuite) { - dependencies { - implementation project() - } - } - } -} -configurations { - integrationTestImplementation.extendsFrom testImplementation - integrationTestRuntimeOnly.extendsFrom testRuntimeOnly -} - -// The relational implementations of the reliability ports: the outbox repository, the inbox -// repository and the destructive-operation journal. Spring JDBC for the transaction join, and SQL -// that is PostgreSQL's (`jsonb`, `FOR UPDATE SKIP LOCKED`, `ON CONFLICT`, `TIMESTAMPTZ`) — the name -// is the contract. The relay and consumer logic that uses them is messaging-reliability. -dependencies { - api project(':messaging:messaging-core-api') - api project(':messaging:messaging-reliability-api') - - // The destructive-operation journal lives here because it needs exactly what the outbox needs: - // one relational database every replica can see, and a migration lane that already exists. The - // contract it implements belongs to the admin API. - api project(':messaging:messaging-admin') - - implementation 'org.springframework:spring-jdbc' - implementation 'org.springframework:spring-tx' - - // 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') - integrationTestImplementation project(':messaging:messaging-testkit') - integrationTestImplementation 'org.testcontainers:testcontainers-postgresql' - integrationTestImplementation 'org.testcontainers:testcontainers-junit-jupiter' - integrationTestImplementation 'org.postgresql:postgresql' -} - -strictTestLanes { - lane('integrationTest') { - integration() - sourceSet = 'integrationTest' - description = 'Runs outbox, inbox and admin-journal contracts against real PostgreSQL.' - } -} diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/gradle.lockfile b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/gradle.lockfile deleted file mode 100644 index b55aa2ae..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/gradle.lockfile +++ /dev/null @@ -1,109 +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,testAnnotationProcessor -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,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,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,integrationTestAnnotationProcessor,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,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -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 -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,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -info.picocli:picocli:4.7.7=checkstyle -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.8=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -io.micrometer:micrometer-core:1.16.8=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -io.micrometer:micrometer-observation:1.16.8=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -javax.inject:javax.inject:1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -net.java.dev.jna:jna:5.18.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath -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-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,testCompileClasspath -org.assertj:assertj-core:3.27.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.checkerframework:checker-qual:3.55.1=integrationTestRuntimeClasspath -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.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.hdrhistogram:HdrHistogram:2.2.2=integrationTestRuntimeClasspath,runtimeClasspath,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,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath -org.junit:junit-bom:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.latencyutils:LatencyUtils:2.0.3=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,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,testAnnotationProcessor -org.postgresql:postgresql:42.7.14=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.reflections:reflections:0.10.2=checkstyle -org.rnorth.duct-tape:duct-tape:1.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.slf4j:slf4j-api:2.0.20=integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.springframework:spring-beans:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-core:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-jdbc:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-tx:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.testcontainers:testcontainers-database-commons:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-jdbc:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-junit-jupiter:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-postgresql: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/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/inbox/InboxPostgresIT.java b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/inbox/InboxPostgresIT.java deleted file mode 100644 index 2ec95ce0..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/inbox/InboxPostgresIT.java +++ /dev/null @@ -1,206 +0,0 @@ -package dev.caskeleton.messaging.inbox; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.testkit.DockerAvailability; -import java.io.IOException; -import java.io.InputStream; -import java.nio.charset.StandardCharsets; -import java.sql.Connection; -import java.sql.PreparedStatement; -import java.sql.ResultSet; -import java.sql.SQLException; -import java.sql.Statement; -import java.time.Instant; -import java.util.concurrent.atomic.AtomicInteger; -import javax.sql.DataSource; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.condition.EnabledIf; -import org.postgresql.ds.PGSimpleDataSource; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; -import org.testcontainers.postgresql.PostgreSQLContainer; - -/** - * Certifies the inbox against a real PostgreSQL. - * - *

The whole pattern rests on a uniqueness constraint and a shared transaction. Both are database - * behaviours: a double can be written to agree with them, and a real one either enforces them or - * does not. - * - *

The last test is the one that matters most. It commits an inbox reservation and a business - * write together, then rolls a second attempt back, and asserts that the side effect did not happen - * twice and the reservation did not survive the rollback. - */ -@Testcontainers -@EnabledIf("dockerAvailable") -class InboxPostgresIT { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - // Scope-based leak analysis cannot see the owner: @Container: the Testcontainers JUnit extension - // owns this lifecycle. - @SuppressWarnings("resource") - @Container - private static final PostgreSQLContainer POSTGRES = - new PostgreSQLContainer(System.getProperty("ca.test.image.postgres-16")) - .withDatabaseName("messaging") - .withUsername("messaging") - .withPassword("messaging"); - - private DataSource dataSource; - - private org.springframework.transaction.support.TransactionTemplate transactions; - private JdbcInboxRepository repository; - - static boolean dockerAvailable() { - return DockerAvailability.isAvailable(); - } - - @BeforeEach - void migrate() throws SQLException, IOException { - dataSource = dataSource(); - try (Connection connection = dataSource.getConnection(); - Statement statement = connection.createStatement()) { - statement.execute("DROP TABLE IF EXISTS messaging_inbox"); - statement.execute("DROP TABLE IF EXISTS projections"); - statement.execute(migration()); - statement.execute("CREATE TABLE projections (id TEXT PRIMARY KEY, applied INT NOT NULL)"); - } - repository = new JdbcInboxRepository(dataSource); - // A real Spring transaction, because the port's contract is about joining one. The previous - // tests called the Connection overload directly, which proved that overload works and said - // nothing about the interface method every consumer actually calls. - transactions = - new org.springframework.transaction.support.TransactionTemplate( - new org.springframework.jdbc.datasource.DataSourceTransactionManager(dataSource)); - } - - @Test - void theFirstReservationSucceedsAndTheSecondDoesNot() { - MessageId messageId = MessageId.newId(); - - assertThat(inTransaction(() -> repository.reserve(messageId, "order-projection", NOW))) - .isTrue(); - assertThat(inTransaction(() -> repository.reserve(messageId, "order-projection", NOW))) - .isFalse(); - } - - @Test - void twoConsumersEachReserveTheSameMessageOnce() { - MessageId messageId = MessageId.newId(); - - assertThat(inTransaction(() -> repository.reserve(messageId, "order-projection", NOW))) - .isTrue(); - assertThat(inTransaction(() -> repository.reserve(messageId, "billing-projection", NOW))) - .isTrue(); - assertThat(inTransaction(() -> repository.reserve(messageId, "order-projection", NOW))) - .isFalse(); - } - - @Test - void aProcessedMessageIsVisibleToTheQuery() { - MessageId messageId = MessageId.newId(); - inTransaction(() -> repository.reserve(messageId, "order-projection", NOW)); - - assertThat(repository.isProcessed(messageId, "order-projection")).isTrue(); - assertThat(repository.isProcessed(messageId, "billing-projection")).isFalse(); - } - - @Test - void aRedeliveryDoesNotApplyTheSideEffectTwice() throws SQLException { - MessageId messageId = MessageId.newId(); - AtomicInteger applied = new AtomicInteger(); - - handle(messageId, applied); - handle(messageId, applied); - - assertThat(applied.get()).as("the handler ran once").isEqualTo(1); - assertThat(projectionCount("o-1")).isEqualTo(1); - } - - @Test - void aRolledBackTransactionLeavesNoReservationAndNoSideEffect() throws SQLException { - MessageId messageId = MessageId.newId(); - - // Through the interface method and a real Spring transaction. This is the path a consumer - // takes; the old version called the Connection overload, which is the one path that was never - // in doubt. - try { - transactions.executeWithoutResult( - status -> { - assertThat(repository.reserve(messageId, "order-projection", NOW)).isTrue(); - new org.springframework.jdbc.core.JdbcTemplate(dataSource) - .execute("INSERT INTO projections (id, applied) VALUES ('o-2', 1)"); - status.setRollbackOnly(); - }); - } catch (RuntimeException rolledBack) { - // setRollbackOnly is the mechanism; an UnexpectedRollbackException is not a failure here. - } - - assertThat(repository.isProcessed(messageId, "order-projection")) - .as("the reservation must not outlive the transaction that made it") - .isFalse(); - assertThat(projectionCount("o-2")).isZero(); - } - - @Test - void retentionRemovesOldRows() { - MessageId purged = MessageId.newId(); - inTransaction(() -> repository.reserve(purged, "order-projection", NOW)); - - assertThat(repository.purgeProcessedBefore(NOW.plusSeconds(1), 100)).isEqualTo(1); - } - - /** Reserves and writes inside one Spring transaction, exactly as an idempotent consumer must. */ - private void handle(MessageId messageId, AtomicInteger applied) { - transactions.executeWithoutResult( - status -> { - if (!repository.reserve(messageId, "order-projection", NOW)) { - status.setRollbackOnly(); - return; - } - new org.springframework.jdbc.core.JdbcTemplate(dataSource) - .execute("INSERT INTO projections (id, applied) VALUES ('o-1', 1)"); - applied.incrementAndGet(); - }); - } - - private T inTransaction(java.util.function.Supplier work) { - return transactions.execute(status -> work.get()); - } - - private int projectionCount(String id) throws SQLException { - try (Connection connection = dataSource.getConnection(); - PreparedStatement statement = - connection.prepareStatement("SELECT count(*) FROM projections WHERE id = ?")) { - statement.setString(1, id); - try (ResultSet results = statement.executeQuery()) { - results.next(); - return results.getInt(1); - } - } - } - - private static DataSource dataSource() { - PGSimpleDataSource source = new PGSimpleDataSource(); - source.setUrl(POSTGRES.getJdbcUrl()); - source.setUser(POSTGRES.getUsername()); - source.setPassword(POSTGRES.getPassword()); - return source; - } - - private static String migration() throws IOException { - try (InputStream stream = - InboxPostgresIT.class - .getClassLoader() - .getResourceAsStream("db/migration/messaging/V1101__messaging_inbox.sql")) { - if (stream == null) { - throw new IOException("the inbox migration is missing from the classpath"); - } - return new String(stream.readAllBytes(), StandardCharsets.UTF_8); - } - } -} diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/AdminOperationJournalPostgresIT.java b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/AdminOperationJournalPostgresIT.java deleted file mode 100644 index 5af7f49c..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/AdminOperationJournalPostgresIT.java +++ /dev/null @@ -1,209 +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.admin.AdminOperationLease; -import dev.caskeleton.messaging.admin.AdminOperationState; -import dev.caskeleton.messaging.admin.PlanDigest; -import dev.caskeleton.messaging.api.error.MessageAuthorizationException; -import dev.caskeleton.messaging.testkit.DockerAvailability; -import java.io.IOException; -import java.io.InputStream; -import java.nio.charset.StandardCharsets; -import java.sql.Connection; -import java.sql.SQLException; -import java.sql.Statement; -import java.time.Duration; -import java.time.Instant; -import javax.sql.DataSource; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.condition.EnabledIf; -import org.postgresql.ds.PGSimpleDataSource; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; -import org.testcontainers.postgresql.PostgreSQLContainer; - -/** - * Certifies the durable journal against a real PostgreSQL. - * - *

The properties that matter here belong to the database, not to Java. "Exactly one replica - * executes an approval" is a primary-key conflict; "a stalled runtime cannot overwrite its - * successor" is a conditional update on a fencing token. An in-memory double can be written to - * agree with both without either being true of the deployed schema, which is exactly how the map - * this replaced looked correct for as long as nobody restarted a replica. - */ -@Testcontainers -@EnabledIf("dockerAvailable") -class AdminOperationJournalPostgresIT { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - private static final Duration LEASE = Duration.ofMinutes(5); - private static final String TICKET = "CHG-1042"; - private static final PlanDigest DIGEST = PlanDigest.ofCanonical("REDRIVE|orders.v1.dlq|50"); - - // Scope-based leak analysis cannot see the owner: @Container: the Testcontainers JUnit extension - // owns this lifecycle. - @SuppressWarnings("resource") - @Container - private static final PostgreSQLContainer POSTGRES = - new PostgreSQLContainer(System.getProperty("ca.test.image.postgres-16")) - .withDatabaseName("messaging") - .withUsername("messaging") - .withPassword("messaging"); - - private JdbcAdminOperationJournal journal; - - static boolean dockerAvailable() { - return DockerAvailability.isAvailable(); - } - - @BeforeEach - void migrate() throws SQLException, IOException { - DataSource dataSource = dataSource(); - try (Connection connection = dataSource.getConnection(); - Statement statement = connection.createStatement()) { - statement.execute("DROP TABLE IF EXISTS messaging_admin_operation"); - statement.execute(migration("V1003__messaging_admin_operation_journal.sql")); - } - journal = new JdbcAdminOperationJournal(dataSource); - } - - @Test - @DisplayName("the primary key, not application code, decides which replica wins") - void thePrimaryKeyDecidesWhichReplicaWins() { - journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW); - - assertThatThrownBy( - () -> journal.begin(TICKET, DIGEST, "op-2", "replica-b", LEASE, NOW.plusSeconds(1))) - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("replica-a"); - } - - @Test - @DisplayName("a completed operation survives the restart that forgot the map") - void aCompletedOperationSurvivesARestart() { - AdminOperationLease lease = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW); - journal.complete(lease, 50, NOW.plusSeconds(30)); - - // A fresh journal object over the same database is what a restarted replica sees. - JdbcAdminOperationJournal afterRestart = new JdbcAdminOperationJournal(dataSource()); - - assertThatThrownBy( - () -> - afterRestart.begin(TICKET, DIGEST, "op-3", "replica-a", LEASE, NOW.plusSeconds(60))) - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("already executed"); - } - - @Test - @DisplayName("an expired lease is taken over at its checkpoint, under a higher token") - void anExpiredLeaseIsTakenOverAtItsCheckpoint() { - AdminOperationLease first = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW); - journal.checkpoint(first, 30, LEASE, NOW.plusSeconds(10)); - - AdminOperationLease resumed = - journal.begin(TICKET, DIGEST, "op-1", "replica-b", LEASE, NOW.plus(Duration.ofMinutes(10))); - - assertThat(resumed.resumeFrom()).isEqualTo(30); - assertThat(resumed.leaseToken()).isEqualTo(first.leaseToken() + 1); - } - - @Test - @DisplayName("a live lease is not taken over") - void aLiveLeaseIsNotTakenOver() { - journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW); - - assertThatThrownBy( - () -> - journal.begin( - TICKET, DIGEST, "op-1", "replica-b", LEASE, NOW.plus(Duration.ofMinutes(1)))) - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("is being executed by"); - } - - @Test - @DisplayName("a superseded runtime cannot write over the one that took over") - void aSupersededRuntimeCannotWriteOverItsSuccessor() { - AdminOperationLease stale = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW); - journal.checkpoint(stale, 30, LEASE, NOW.plusSeconds(10)); - AdminOperationLease successor = - journal.begin(TICKET, DIGEST, "op-1", "replica-b", LEASE, NOW.plus(Duration.ofMinutes(10))); - journal.checkpoint(successor, 45, LEASE, NOW.plus(Duration.ofMinutes(11))); - - assertThatThrownBy(() -> journal.complete(stale, 30, NOW.plus(Duration.ofMinutes(12)))) - .isInstanceOf(MessageAuthorizationException.class) - .hasMessageContaining("no longer holds the lease"); - - assertThat(journal.find(TICKET, DIGEST)) - .hasValueSatisfying( - record -> { - assertThat(record.itemsCompleted()).isEqualTo(45); - assertThat(record.state()).isEqualTo(AdminOperationState.STARTED); - }); - } - - @Test - @DisplayName("a failed operation is resumable immediately and records why it stopped") - void aFailedOperationIsResumableImmediately() { - AdminOperationLease first = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW); - journal.fail(first, 12, "MESSAGE_BROKER_UNAVAILABLE", NOW.plusSeconds(6)); - - assertThat(journal.find(TICKET, DIGEST)) - .hasValueSatisfying( - record -> { - assertThat(record.state()).isEqualTo(AdminOperationState.FAILED); - assertThat(record.failureCode()).contains("MESSAGE_BROKER_UNAVAILABLE"); - }); - - assertThatCode( - () -> { - AdminOperationLease resumed = - journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW.plusSeconds(7)); - assertThat(resumed.resumeFrom()).isEqualTo(12); - }) - .doesNotThrowAnyException(); - } - - @Test - @DisplayName("the schema refuses a digest that is not a SHA-256") - void theSchemaRefusesADigestThatIsNotASha256() throws SQLException { - try (Connection connection = dataSource().getConnection(); - Statement statement = connection.createStatement()) { - assertThatThrownBy( - () -> - statement.execute( - """ - INSERT INTO messaging_admin_operation ( - approval_ticket, plan_digest, operation_id, state, - lease_owner, lease_expires_at, started_at) - VALUES ('CHG-9', 'not-a-digest', 'op', 'STARTED', 'r', now(), now()) - """)) - .as("a malformed digest in the journal makes the uniqueness key meaningless") - .isInstanceOf(SQLException.class); - } - } - - private static DataSource dataSource() { - PGSimpleDataSource source = new PGSimpleDataSource(); - source.setUrl(POSTGRES.getJdbcUrl()); - source.setUser(POSTGRES.getUsername()); - source.setPassword(POSTGRES.getPassword()); - return source; - } - - private static String migration(String fileName) throws IOException { - try (InputStream stream = - AdminOperationJournalPostgresIT.class - .getClassLoader() - .getResourceAsStream("db/migration/messaging/" + fileName)) { - if (stream == null) { - throw new IOException("migration " + fileName + " is missing from the classpath"); - } - return new String(stream.readAllBytes(), StandardCharsets.UTF_8); - } - } -} diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/OutboxPostgresIT.java b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/OutboxPostgresIT.java deleted file mode 100644 index 388707d5..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/OutboxPostgresIT.java +++ /dev/null @@ -1,668 +0,0 @@ -package dev.caskeleton.messaging.outbox; - -import static org.assertj.core.api.Assertions.assertThat; - -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.reliability.OutboxCanonicalMetadata; -import dev.caskeleton.messaging.reliability.OutboxLease; -import dev.caskeleton.messaging.reliability.OutboxRecord; -import dev.caskeleton.messaging.reliability.OutboxStatus; -import dev.caskeleton.messaging.testkit.DockerAvailability; -import java.io.IOException; -import java.io.InputStream; -import java.nio.charset.StandardCharsets; -import java.sql.Connection; -import java.sql.SQLException; -import java.sql.Statement; -import java.time.Duration; -import java.time.Instant; -import java.util.List; -import java.util.Map; -import java.util.Optional; -import javax.sql.DataSource; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.condition.EnabledIf; -import org.postgresql.ds.PGSimpleDataSource; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; -import org.testcontainers.postgresql.PostgreSQLContainer; - -/** - * Certifies the outbox against a real PostgreSQL. - * - *

The pattern's guarantees are claims about a database, not about Java: that a row and a - * business change commit together, that two relay instances cannot claim the same row, and that an - * ambiguous publish leaves the row claimable under its original identity. An in-memory double can - * be written to agree with any of those; only a real database settles them. - */ -@Testcontainers -@EnabledIf("dockerAvailable") -class OutboxPostgresIT { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - // Scope-based leak analysis cannot see the owner: @Container: the Testcontainers JUnit extension - // owns this lifecycle. - @SuppressWarnings("resource") - @Container - private static final PostgreSQLContainer POSTGRES = - new PostgreSQLContainer(System.getProperty("ca.test.image.postgres-16")) - .withDatabaseName("messaging") - .withUsername("messaging") - .withPassword("messaging"); - - private DataSource dataSource; - - private org.springframework.transaction.support.TransactionTemplate transactions; - private JdbcOutboxRepository repository; - - static boolean dockerAvailable() { - return DockerAvailability.isAvailable(); - } - - @BeforeEach - void migrate() throws SQLException, IOException { - dataSource = dataSource(); - try (Connection connection = dataSource.getConnection(); - Statement statement = connection.createStatement()) { - statement.execute("DROP TABLE IF EXISTS messaging_outbox"); - // The inbox migration ships in the same module now, so "every migration" creates its table - // too. - statement.execute("DROP TABLE IF EXISTS messaging_inbox"); - // Every migration in order, not just V1: a test that applies part of the schema certifies a - // database nobody deploys. - for (String migration : migrations()) { - statement.execute(migration); - } - } - repository = new JdbcOutboxRepository(dataSource); - // A real Spring transaction: the port's contract is that append joins the caller's, and the - // previous tests proved only that the Connection overload worked. - transactions = - new org.springframework.transaction.support.TransactionTemplate( - new org.springframework.jdbc.datasource.DataSourceTransactionManager(dataSource)); - } - - @Test - void anAppendedRowIsClaimableAndRoundTripsIntact() { - OutboxRecord record = record(); - appendInTransaction(record); - - List leased = claim("relay-a", NOW).stream().map(OutboxLease::record).toList(); - - assertThat(leased) - .singleElement() - .satisfies( - leasedRecord -> { - assertThat(leasedRecord.messageId()).isEqualTo(record.messageId()); - assertThat(leasedRecord.messageType()).isEqualTo(record.messageType()); - assertThat(leasedRecord.payload()).isEqualTo(record.payload()); - assertThat(leasedRecord.metadata().partitionKey()) - .as("the routing key is a column the relay can read without decoding the payload") - .contains("acct-1"); - }); - } - - @Test - void aLeasedRowIsInvisibleToASecondRelayInstance() { - appendInTransaction(record()); - - List first = claim("relay-a", NOW); - List second = claim("relay-b", NOW); - - assertThat(first).hasSize(1); - assertThat(second).as("SKIP LOCKED plus the lease keeps two relays off the same row").isEmpty(); - } - - @Test - void anExpiredLeaseBecomesClaimableAgain() { - appendInTransaction(record()); - claim("relay-a", NOW); - - List reclaimed = claim("relay-b", NOW.plusSeconds(31)); - - assertThat(reclaimed).hasSize(1); - } - - @Test - void anAmbiguousRowStaysClaimableUnderItsOriginalIdentity() { - OutboxRecord record = record(); - appendInTransaction(record); - // A terminal write is checked against the lease token, so `markAmbiguous` takes the lease that - // owns the row; no identity-keyed write exists for one relay to put an outcome on a row another - // relay currently owns. - OutboxLease lease = claim("ambiguous-relay", NOW).getFirst(); - - repository.markAmbiguous(lease, "CONFIRM_TIMEOUT", NOW, NOW); - - assertThat(repository.find(record.messageId()).orElseThrow().status()) - .isEqualTo(OutboxStatus.AMBIGUOUS); - assertThat(claim("relay-b", NOW)) - .singleElement() - .satisfies(retry -> assertThat(retry.messageId()).isEqualTo(record.messageId())); - } - - @Test - void aPublishedRowIsNotClaimedAgain() { - OutboxRecord record = record(); - appendInTransaction(record); - OutboxLease lease = claim("relay-a", NOW).getFirst(); - - repository.markPublished(lease, NOW); - - assertThat(repository.find(record.messageId()).orElseThrow().status()) - .isEqualTo(OutboxStatus.PUBLISHED); - assertThat(claim("relay-b", NOW.plusSeconds(60))).isEmpty(); - } - - @Test - void aFailedRowIsNotClaimedAgainWithoutIntervention() { - OutboxRecord record = record(); - appendInTransaction(record); - OutboxLease lease = claim("relay-a", NOW).getFirst(); - - repository.markFailed(lease, "INVALID_TOPIC", NOW); - - assertThat(claim("relay-b", NOW.plusSeconds(60))).isEmpty(); - } - - @Test - void theRowAndTheBusinessChangeCommitTogetherOrNotAtAll() throws SQLException { - OutboxRecord record = record(); - new org.springframework.jdbc.core.JdbcTemplate(dataSource) - .execute("CREATE TABLE IF NOT EXISTS orders (id TEXT PRIMARY KEY)"); - - // The interface method, inside a real Spring transaction that rolls back. This is the path - // business code takes; the old version called the Connection overload, which was never the - // one at risk. - try { - transactions.executeWithoutResult( - status -> { - new org.springframework.jdbc.core.JdbcTemplate(dataSource) - .execute("INSERT INTO orders (id) VALUES ('o-1')"); - repository.append(record); - status.setRollbackOnly(); - }); - } catch (RuntimeException rolledBack) { - // setRollbackOnly is the mechanism; the rollback exception is not a failure here. - } - - assertThat(repository.find(record.messageId())) - .as("a rolled back business change must not leave a publishable row") - .isEmpty(); - } - - @Test - void retentionRemovesOnlyPublishedRows() { - OutboxRecord published = record(); - OutboxRecord pending = record(); - appendInTransaction(published); - repository.markPublished(claim("relay-a", NOW).getFirst(), NOW); - appendInTransaction(pending); - - int removed = repository.purgePublishedBefore(NOW.plusSeconds(1), 100); - - assertThat(removed).isEqualTo(1); - assertThat(repository.find(pending.messageId())).isPresent(); - } - - /** Claims with an unlimited attempt budget, as a relay does on a row's first attempts. */ - private List claim(String owner, Instant now) { - return repository.claimBatch(owner, 10, Duration.ofSeconds(30), now, Integer.MAX_VALUE); - } - - private static OutboxRecord record() { - return record( - // The routing key is a column now, not a reserved header smuggled through the header map. - OutboxCanonicalMetadata.none().withRoutingKeys("acct-1", "acct-1")); - } - - @Test - void aNewerRowWaitsWhileAnOlderRowWithTheSameOrderingKeyIsUnfinished() { - // given - OutboxRecord older = record(ordered("customer-42"), NOW.minusSeconds(60)); - OutboxRecord newer = record(ordered("customer-42"), NOW.minusSeconds(30)); - OutboxRecord otherKey = record(ordered("customer-7"), NOW.minusSeconds(30)); - appendInTransaction(older); - appendInTransaction(newer); - appendInTransaction(otherKey); - - // when - List claimed = - repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW, Integer.MAX_VALUE); - - // then - assertThat(claimed) - .extracting(OutboxLease::messageId) - .as("a second relay, or a retry of the older row, would put the newer one first") - .containsExactlyInAnyOrder(older.messageId(), otherKey.messageId()); - } - - private static OutboxCanonicalMetadata ordered(String key) { - return OutboxCanonicalMetadata.none().withRoutingKeys(key, key); - } - - private static OutboxRecord record(OutboxCanonicalMetadata metadata) { - return record(metadata, NOW.minusSeconds(60)); - } - - private static OutboxRecord record(OutboxCanonicalMetadata metadata, Instant createdAt) { - return new OutboxRecord( - MessageId.newId(), - new DestinationName("order-events"), - new MessageType("order.created"), - new SchemaVersion(1), - ContentType.JSON, - "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), - Map.of(), - metadata, - createdAt, - OutboxStatus.PENDING, - 0, - Optional.empty(), - Optional.empty()); - } - - private static DataSource dataSource() { - PGSimpleDataSource source = new PGSimpleDataSource(); - source.setUrl(POSTGRES.getJdbcUrl()); - source.setUser(POSTGRES.getUsername()); - source.setPassword(POSTGRES.getPassword()); - return source; - } - - /** - * Every migration in the module, in version order. - * - *

Discovered rather than listed. The list said V1 and V2 above a comment claiming it was every - * migration, so V3 and V4 were never applied here — and the first symptom of that was not a - * missing check but this suite failing against a column the production schema has. A test that - * applies part of the schema certifies a database nobody deploys. - */ - private static java.util.List migrations() throws IOException { - java.net.URL directory = - OutboxPostgresIT.class.getClassLoader().getResource("db/migration/messaging"); - if (directory == null) { - throw new IOException("the messaging migrations are missing from the classpath"); - } - // The migrations may sit in a directory or, when the suite runs against the main jar, inside - // it; a jar URL is not a file URI, so list through a filesystem that understands either. - java.net.URI uri; - try { - uri = directory.toURI(); - } catch (java.net.URISyntaxException malformed) { - throw new IOException(malformed); - } - java.util.List names; - if ("jar".equals(uri.getScheme())) { - try (java.nio.file.FileSystem jar = - java.nio.file.FileSystems.newFileSystem(uri, java.util.Map.of()); - java.util.stream.Stream listed = - java.nio.file.Files.list(jar.getPath("db/migration/messaging"))) { - names = sqlNames(listed); - } - } else { - try (java.util.stream.Stream listed = - java.nio.file.Files.list(java.nio.file.Path.of(uri))) { - names = sqlNames(listed); - } - } - if (names.isEmpty()) { - throw new IOException("no migration applied; the schema under test would be empty"); - } - java.util.List statements = new java.util.ArrayList<>(); - for (String name : names) { - statements.add(migration(name)); - } - return statements; - } - - private static java.util.List sqlNames( - java.util.stream.Stream listed) { - return listed - .map(path -> path.getFileName().toString()) - .filter(name -> name.endsWith(".sql")) - .sorted() - .toList(); - } - - private int countWhere(String predicate) { - try (Connection connection = dataSource.getConnection(); - Statement statement = connection.createStatement(); - java.sql.ResultSet results = - statement.executeQuery("SELECT count(*) FROM messaging_outbox WHERE " + predicate)) { - results.next(); - return results.getInt(1); - } catch (SQLException failure) { - throw new IllegalStateException("could not count outbox rows", failure); - } - } - - private String routingKeyOf(MessageId messageId) { - try (Connection connection = dataSource.getConnection(); - java.sql.PreparedStatement statement = - connection.prepareStatement( - "SELECT routing_key FROM messaging_outbox WHERE message_id = ?")) { - statement.setObject(1, messageId.value()); - try (java.sql.ResultSet results = statement.executeQuery()) { - results.next(); - return results.getString(1); - } - } catch (SQLException failure) { - throw new IllegalStateException("could not read the routing key", failure); - } - } - - private void execute(String sql) throws SQLException { - try (Connection connection = dataSource.getConnection(); - Statement statement = connection.createStatement()) { - statement.execute(sql); - } - } - - private static String migration(String fileName) throws IOException { - try (InputStream stream = - OutboxPostgresIT.class - .getClassLoader() - .getResourceAsStream("db/migration/messaging/" + fileName)) { - if (stream == null) { - throw new IOException("migration " + fileName + " is missing from the classpath"); - } - return new String(stream.readAllBytes(), StandardCharsets.UTF_8); - } - } - - @Test - void aSupersededRelayCannotOverwriteTheOutcomeOfTheOneThatReplacedIt() { - OutboxRecord record = record(); - appendInTransaction(record); - - // Relay A claims and stalls. - java.util.List first = - repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW, Integer.MAX_VALUE); - assertThat(first).hasSize(1); - - // The lease expires and relay B takes the row and publishes it. - java.util.List second = - repository.claimBatch( - "relay-b", 10, Duration.ofSeconds(30), NOW.plusSeconds(31), Integer.MAX_VALUE); - assertThat(second).hasSize(1); - assertThat(second.get(0).token()) - .as("every claim increments the token, which is what makes the older one detectable") - .isGreaterThan(first.get(0).token()); - assertThat(repository.markPublished(second.get(0), NOW.plusSeconds(32))) - .isEqualTo(dev.caskeleton.messaging.reliability.OutboxTransitionResult.APPLIED); - - // Relay A finally wakes up and tries to record its own outcome. - assertThat( - repository.markAmbiguous( - first.get(0), "CONFIRM_TIMEOUT", NOW.plusSeconds(40), NOW.plusSeconds(40))) - .as("this write used to succeed and made a published message claimable again") - .isEqualTo(dev.caskeleton.messaging.reliability.OutboxTransitionResult.STALE_LEASE); - assertThat(repository.find(record.messageId()).orElseThrow().status()) - .isEqualTo(OutboxStatus.PUBLISHED); - } - - @Test - void aDuplicateTerminalCallFromTheSameRelayIsRefused() { - OutboxRecord record = record(); - appendInTransaction(record); - dev.caskeleton.messaging.reliability.OutboxLease lease = - repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW, Integer.MAX_VALUE).get(0); - - assertThat(repository.markPublished(lease, NOW)) - .isEqualTo(dev.caskeleton.messaging.reliability.OutboxTransitionResult.APPLIED); - assertThat(repository.markPublished(lease, NOW)) - .as("the row is no longer IN_FLIGHT, so the second write has nothing to apply to") - .isEqualTo(dev.caskeleton.messaging.reliability.OutboxTransitionResult.STALE_LEASE); - } - - @Test - void twoRelaysClaimingConcurrentlyGetDisjointRowsAndDistinctTokens() { - OutboxRecord one = record(OutboxCanonicalMetadata.none().withRoutingKeys("acct-1", "acct-1")); - OutboxRecord two = record(OutboxCanonicalMetadata.none().withRoutingKeys("acct-2", "acct-2")); - appendInTransaction(one); - appendInTransaction(two); - - java.util.List a = - repository.claimBatch("relay-a", 1, Duration.ofSeconds(30), NOW, Integer.MAX_VALUE); - java.util.List b = - repository.claimBatch("relay-b", 1, Duration.ofSeconds(30), NOW, Integer.MAX_VALUE); - - assertThat(a).hasSize(1); - assertThat(b).hasSize(1); - assertThat(a.get(0).messageId()).isNotEqualTo(b.get(0).messageId()); - } - - @Test - void anExpiryReclaimKeepsTheMessageIdAndAdvancesTheToken() { - OutboxRecord record = record(); - appendInTransaction(record); - - long firstToken = - repository - .claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW, Integer.MAX_VALUE) - .get(0) - .token(); - dev.caskeleton.messaging.reliability.OutboxLease reclaimed = - repository - .claimBatch( - "relay-b", 10, Duration.ofSeconds(30), NOW.plusSeconds(31), Integer.MAX_VALUE) - .get(0); - - assertThat(reclaimed.messageId()).isEqualTo(record.messageId()); - assertThat(reclaimed.token()).isEqualTo(firstToken + 1); - } - - @Test - void anAmbiguousRowWaitsForItsBackoffBeforeItIsClaimedAgain() { - OutboxRecord record = record(); - appendInTransaction(record); - dev.caskeleton.messaging.reliability.OutboxLease lease = - repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW, 10).get(0); - - repository.markAmbiguous(lease, "CONFIRM_TIMEOUT", NOW, NOW.plusSeconds(120)); - - assertThat(repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW.plusSeconds(1), 10)) - .as( - "an ambiguous row used to be claimable on the very next pass, so an outage republished" - + " the whole backlog every poll interval") - .isEmpty(); - assertThat( - repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW.plusSeconds(121), 10)) - .hasSize(1); - } - - @Test - void aRowOutOfAttemptsIsNotClaimedAgain() { - OutboxRecord record = record(); - appendInTransaction(record); - - Instant clock = NOW; - for (int attempt = 0; attempt < 3; attempt++) { - dev.caskeleton.messaging.reliability.OutboxLease lease = - repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), clock, 3).get(0); - repository.markAmbiguous(lease, "CONFIRM_TIMEOUT", clock, clock); - clock = clock.plusSeconds(60); - } - - assertThat(repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), clock, 3)) - .as("the configured budget was a number nothing consulted") - .isEmpty(); - } - - @Test - void anExhaustedRowIsDistinctFromARejectedOne() { - OutboxRecord record = record(); - appendInTransaction(record); - dev.caskeleton.messaging.reliability.OutboxLease lease = - repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW, 10).get(0); - - repository.markExhausted(lease, "budget spent without a confirmation", NOW); - - assertThat(repository.find(record.messageId()).orElseThrow().status()) - .as("'the broker refused this' and 'nobody ever answered' need different operator actions") - .isEqualTo(OutboxStatus.EXHAUSTED); - assertThat( - repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW.plusSeconds(600), 10)) - .isEmpty(); - } - - @Test - void aConfirmedPublishClearsTheRetryClock() { - OutboxRecord record = record(); - appendInTransaction(record); - dev.caskeleton.messaging.reliability.OutboxLease first = - repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW, 10).get(0); - repository.markAmbiguous(first, "CONFIRM_TIMEOUT", NOW, NOW.plusSeconds(60)); - - dev.caskeleton.messaging.reliability.OutboxLease second = - repository - .claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW.plusSeconds(61), 10) - .get(0); - repository.markPublished(second, NOW.plusSeconds(62)); - - assertThat(repository.find(record.messageId()).orElseThrow().status()) - .isEqualTo(OutboxStatus.PUBLISHED); - } - - @Test - void everyCanonicalColumnRoundTripsThroughTheDatabase() { - MessageId cause = MessageId.newId(); - OutboxCanonicalMetadata written = - new OutboxCanonicalMetadata( - Optional.of(new dev.caskeleton.messaging.api.ProducerId("order-api")), - Optional.of(NOW.minusSeconds(120)), - Optional.of(new dev.caskeleton.messaging.api.CorrelationId("checkout-7")), - Optional.of(new dev.caskeleton.messaging.api.CausationId(cause)), - Optional.of(new dev.caskeleton.messaging.api.TenantContext("acme")), - Optional.of("customer-42"), - Optional.of("customer-42"), - Optional.of("order.created-value"), - Optional.of("urn:schema:1"), - new dev.caskeleton.messaging.api.TraceContext( - Optional.of("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"), - Optional.empty(), - Optional.empty())); - OutboxRecord record = record(written); - - appendInTransaction(record); - - assertThat(repository.find(record.messageId()).orElseThrow().metadata()) - .as("what the relay reads back has to be what the business transaction wrote") - .isEqualTo(written); - } - - @Test - void theRelayCanSelectOneTenantsBacklogWithoutDecodingAPayload() { - appendInTransaction( - record( - OutboxCanonicalMetadata.none() - .withTenant(new dev.caskeleton.messaging.api.TenantContext("acme")))); - appendInTransaction( - record( - OutboxCanonicalMetadata.none() - .withTenant(new dev.caskeleton.messaging.api.TenantContext("globex")))); - - assertThat(countWhere("tenant = 'acme'")) - .as("the operational question an outbox backlog always raises, answerable as a SELECT") - .isEqualTo(1); - } - - @Test - void theStoredRoutingKeyFallsBackToTheMessageId() { - OutboxRecord keyed = - record(OutboxCanonicalMetadata.none().withRoutingKeys("customer-42", "customer-42")); - OutboxRecord unkeyed = record(OutboxCanonicalMetadata.none()); - appendInTransaction(keyed); - appendInTransaction(unkeyed); - - 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 - void aTenantThatBreaksTheSlugBoundIsRefusedByTheDatabase() { - org.assertj.core.api.Assertions.assertThatThrownBy( - () -> - execute( - "INSERT INTO messaging_outbox (message_id, destination, message_type, " - + "schema_version, content_type, payload, created_at, status, attempts, " - + "tenant) VALUES ('" - + MessageId.newId().value() - + "', 'order-events', 'order.created', 1, 'application/json', '\\x7b7d', " - + "now(), 'PENDING', 0, 'Tenant With Spaces')")) - .as("a CDC connector and an operator both write this table without passing through Java") - .isInstanceOf(SQLException.class) - .hasMessageContaining("ck_messaging_outbox_tenant"); - } - - @Test - void aHeaderValueWithControlCharactersRoundTrips() { - OutboxRecord record = - new OutboxRecord( - MessageId.newId(), - new DestinationName("order-events"), - new MessageType("order.created"), - new SchemaVersion(1), - ContentType.JSON, - "{}".getBytes(StandardCharsets.UTF_8), - // A tab and a newline in a header value. Only backslash and quote were escaped, so - // this produced a document PostgreSQL refuses as invalid JSONB and the append failed - // with an error naming neither the header nor the row. - Map.of("x-note", "line one\nline\ttwo"), - OutboxCanonicalMetadata.none(), - NOW.minusSeconds(60), - OutboxStatus.PENDING, - 0, - Optional.empty(), - Optional.empty()); - - appendInTransaction(record); - - assertThat(repository.find(record.messageId()).orElseThrow().headers()) - .containsEntry("x-note", "line one\nline\ttwo"); - } - - /** - * The hand-rolled reader took a quote preceded by a backslash for an escaped quote, so a value - * ending in an escaped backslash ran on into the next header and both came back wrong. - */ - @Test - void aHeaderValueEndingInABackslashRoundTripsWithoutSwallowingTheNextHeader() { - // given - OutboxRecord record = - new OutboxRecord( - MessageId.newId(), - new DestinationName("order-events"), - new MessageType("order.created"), - new SchemaVersion(1), - ContentType.JSON, - "{}".getBytes(StandardCharsets.UTF_8), - Map.of("x-path", "C:\\exports\\", "x-next", "after"), - OutboxCanonicalMetadata.none(), - NOW.minusSeconds(60), - OutboxStatus.PENDING, - 0, - Optional.empty(), - Optional.empty()); - appendInTransaction(record); - - // when - Map headers = repository.find(record.messageId()).orElseThrow().headers(); - - // then - assertThat(headers) - .containsExactlyInAnyOrderEntriesOf(Map.of("x-path", "C:\\exports\\", "x-next", "after")); - } - - private void appendInTransaction(OutboxRecord record) { - transactions.executeWithoutResult(status -> repository.append(record)); - } -} diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/inbox/JdbcInboxRepository.java b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/inbox/JdbcInboxRepository.java deleted file mode 100644 index d941d739..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/inbox/JdbcInboxRepository.java +++ /dev/null @@ -1,170 +0,0 @@ -package dev.caskeleton.messaging.inbox; - -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.reliability.InboxRepository; -import java.sql.Connection; -import java.sql.PreparedStatement; -import java.sql.ResultSet; -import java.sql.SQLException; -import java.sql.Timestamp; -import java.time.Instant; -import java.util.Objects; -import javax.sql.DataSource; -import org.springframework.jdbc.datasource.DataSourceUtils; -import org.springframework.transaction.support.TransactionSynchronizationManager; - -/** - * The PostgreSQL inbox. - * - *

Reservation is an {@code INSERT ... ON CONFLICT DO NOTHING} whose affected-row count is the - * answer: one means first delivery, zero means already processed. The composite primary key does - * the work, so there is no read-then-write race — two concurrent deliveries of the same message - * cannot both see "not processed" and both proceed. - * - *

The connection-taking overload is the one that matters. Reserving on a connection other than - * the one carrying the business write means the two commit independently, which reopens exactly the - * duplicate window the Inbox exists to close. The no-argument overload is provided only for - * retention sweeps and read-only queries. - */ -public final class JdbcInboxRepository implements InboxRepository { - - private static final String RESERVE = - """ - INSERT INTO messaging_inbox (message_id, consumer_id, processed_at) - VALUES (?, ?, ?) - ON CONFLICT (message_id, consumer_id) DO NOTHING - """; - - private final DataSource dataSource; - - /** - * Creates a repository over a data source. - * - * @param dataSource the inbox data source - */ - public JdbcInboxRepository(DataSource dataSource) { - this.dataSource = Objects.requireNonNull(dataSource, "dataSource must not be null"); - } - - /** - * Reserves a message on the caller's transactional connection. - * - *

Package-private. It used to be public and was the only path that actually joined the - * caller's transaction, while the interface method — the one {@code IdempotentConsumer} calls — - * opened a raw connection that auto-commits. A reservation that commits on its own while the - * business side effect rolls back is a message that will never be redelivered and whose work - * never happened. - * - * @param connection the connection the business write is running on - * @param messageId the logical message identity - * @param consumerId the consumer's stable identity - * @param now the current instant - * @return true when this is the first time - */ - boolean reserve(Connection connection, MessageId messageId, String consumerId, Instant now) { - Objects.requireNonNull(connection, "connection must not be null"); - Objects.requireNonNull(messageId, "messageId must not be null"); - Objects.requireNonNull(now, "now must not be null"); - if (consumerId == null || consumerId.isBlank()) { - throw new IllegalArgumentException("consumerId must not be blank"); - } - try (PreparedStatement statement = connection.prepareStatement(RESERVE)) { - statement.setObject(1, messageId.value()); - statement.setString(2, consumerId); - statement.setTimestamp(3, Timestamp.from(now)); - return statement.executeUpdate() == 1; - } catch (SQLException exception) { - throw new MessagingConfigurationException( - "INBOX_RESERVE_FAILED", "could not reserve an inbox record", exception); - } - } - - @Override - public boolean reserve(MessageId messageId, String consumerId, Instant now) { - requireActiveTransaction("reserving an inbox message"); - Connection connection = DataSourceUtils.getConnection(dataSource); - try { - return reserve(connection, messageId, consumerId, now); - } finally { - DataSourceUtils.releaseConnection(connection, dataSource); - } - } - - /** - * Refuses when there is no transaction to join, or when it cannot write. - * - *

The reservation and the side effect it guards have to commit or roll back together. Running - * the reservation on its own connection breaks that on the rollback path only — which is the path - * nobody exercises before production, and the one where the message is lost for good. - */ - private void requireActiveTransaction(String what) { - if (!TransactionSynchronizationManager.isActualTransactionActive()) { - throw new MessagingConfigurationException( - "INBOX_TRANSACTION_REQUIRED", - what - + " requires an active transaction; a reservation that commits alone marks a message" - + " processed whose work may still roll back"); - } - if (TransactionSynchronizationManager.isCurrentTransactionReadOnly()) { - throw new MessagingConfigurationException( - "INBOX_TRANSACTION_REQUIRED", - what + " requires a writable transaction; the current one is read-only"); - } - if (!TransactionSynchronizationManager.hasResource(dataSource)) { - throw new MessagingConfigurationException( - "INBOX_TRANSACTION_REQUIRED", - what - + " requires the active transaction to be bound to this DataSource; it is bound to" - + " another, so the reservation and the side effect would commit independently"); - } - } - - @Override - public boolean isProcessed(MessageId messageId, String consumerId) { - try (Connection connection = dataSource.getConnection(); - PreparedStatement statement = - connection.prepareStatement( - "SELECT 1 FROM messaging_inbox WHERE message_id = ? AND consumer_id = ?")) { - statement.setObject(1, messageId.value()); - statement.setString(2, consumerId); - try (ResultSet results = statement.executeQuery()) { - return results.next(); - } - } catch (SQLException exception) { - throw new MessagingConfigurationException( - "INBOX_QUERY_FAILED", "could not query the inbox", exception); - } - } - - @Override - public int purgeProcessedBefore(Instant processedBefore, int limit) { - Objects.requireNonNull(processedBefore, "processedBefore must not be null"); - if (limit < 1) { - throw new IllegalArgumentException("a bounded purge deletes at least one row per call"); - } - try (Connection connection = dataSource.getConnection(); - PreparedStatement statement = - connection.prepareStatement( - """ - WITH expired AS ( - SELECT message_id, consumer_id - FROM messaging_inbox - WHERE processed_at < ? - ORDER BY processed_at - LIMIT ? - FOR UPDATE SKIP LOCKED - ) - DELETE FROM messaging_inbox i - USING expired e - WHERE i.message_id = e.message_id AND i.consumer_id = e.consumer_id - """)) { - statement.setTimestamp(1, Timestamp.from(processedBefore)); - statement.setInt(2, limit); - return statement.executeUpdate(); - } catch (SQLException exception) { - throw new MessagingConfigurationException( - "INBOX_PURGE_FAILED", "a bounded inbox purge failed", exception); - } - } -} diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/JdbcAdminOperationJournal.java b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/JdbcAdminOperationJournal.java deleted file mode 100644 index 099dd96b..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/JdbcAdminOperationJournal.java +++ /dev/null @@ -1,326 +0,0 @@ -package dev.caskeleton.messaging.outbox; - -import dev.caskeleton.messaging.admin.AdminOperationJournal; -import dev.caskeleton.messaging.admin.AdminOperationLease; -import dev.caskeleton.messaging.admin.AdminOperationRecord; -import dev.caskeleton.messaging.admin.AdminOperationState; -import dev.caskeleton.messaging.admin.PlanDigest; -import dev.caskeleton.messaging.api.error.MessageAuthorizationException; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.sql.Connection; -import java.sql.PreparedStatement; -import java.sql.ResultSet; -import java.sql.SQLException; -import java.sql.Timestamp; -import java.time.Duration; -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; -import javax.sql.DataSource; -import org.springframework.jdbc.datasource.DataSourceUtils; - -/** - * The shared, durable destructive-operation journal. - * - *

Lives beside the outbox because it needs the same thing the outbox needs and nothing more: one - * relational database that every replica can see. The uniqueness that stops a second execution is - * the primary key on {@code (approval_ticket, plan_digest)}, enforced by the database rather than - * by a check-then-act in application code — two replicas that read "no row" at the same instant - * would both proceed, and only the constraint makes exactly one of them win. - * - *

Takeover is conditional on the row still carrying the token the caller read. That is what - * fences a stalled runtime out: it wakes up holding token 3, the row is at token 4, and every write - * it attempts is refused rather than overwriting the replica that resumed the work. - */ -public final class JdbcAdminOperationJournal implements AdminOperationJournal { - - private static final String SELECT = - """ - SELECT approval_ticket, plan_digest, operation_id, state, items_completed, - lease_owner, lease_token, lease_expires_at, started_at, finished_at, failure_code - FROM messaging_admin_operation - WHERE approval_ticket = ? AND plan_digest = ? - """; - - private static final String INSERT = - """ - INSERT INTO messaging_admin_operation ( - approval_ticket, plan_digest, operation_id, state, items_completed, - lease_owner, lease_token, lease_expires_at, started_at) - VALUES (?, ?, ?, 'STARTED', 0, ?, 1, ?, ?) - ON CONFLICT (approval_ticket, plan_digest) DO NOTHING - """; - - private static final String TAKE_OVER = - """ - UPDATE messaging_admin_operation - SET operation_id = ?, - state = 'STARTED', - lease_owner = ?, - lease_token = lease_token + 1, - lease_expires_at = ?, - finished_at = NULL, - failure_code = NULL - WHERE approval_ticket = ? - AND plan_digest = ? - AND lease_token = ? - -- Only a failed operation or one whose lease ran out may be taken over. A live STARTED row - -- means another replica is executing it right now. - AND (state = 'FAILED' OR lease_expires_at <= ?) - RETURNING lease_token, items_completed - """; - - private static final String CHECKPOINT = - """ - UPDATE messaging_admin_operation - SET items_completed = GREATEST(items_completed, ?), - lease_expires_at = ? - WHERE approval_ticket = ? AND plan_digest = ? AND lease_token = ? - """; - - private static final String SETTLE = - """ - UPDATE messaging_admin_operation - SET state = ?, - items_completed = GREATEST(items_completed, ?), - finished_at = ?, - failure_code = ? - WHERE approval_ticket = ? AND plan_digest = ? AND lease_token = ? - """; - - private final DataSource dataSource; - - /** - * Creates the journal. - * - * @param dataSource the shared database every replica reads - */ - public JdbcAdminOperationJournal(DataSource dataSource) { - this.dataSource = Objects.requireNonNull(dataSource, "dataSource must not be null"); - } - - @Override - public AdminOperationLease begin( - String approvalTicket, - PlanDigest planDigest, - String operationId, - String leaseOwner, - Duration leaseDuration, - Instant now) { - Objects.requireNonNull(planDigest, "planDigest must not be null"); - Objects.requireNonNull(leaseDuration, "leaseDuration must not be null"); - Objects.requireNonNull(now, "now must not be null"); - Instant expiry = now.plus(leaseDuration); - - Connection connection = DataSourceUtils.getConnection(dataSource); - try { - if (insertClaim( - connection, approvalTicket, planDigest, operationId, leaseOwner, expiry, now)) { - return new AdminOperationLease(approvalTicket, planDigest, operationId, leaseOwner, 1L, 0); - } - AdminOperationRecord existing = - read(connection, approvalTicket, planDigest) - .orElseThrow( - () -> - new MessagingConfigurationException( - "ADMIN_JOURNAL_INCONSISTENT", - "the insert conflicted but no row exists for approval " - + approvalTicket)); - refuseIfNotResumable(existing, approvalTicket, now); - return takeOver( - connection, existing, approvalTicket, planDigest, operationId, leaseOwner, expiry, now); - } catch (SQLException failure) { - throw new MessagingConfigurationException( - "ADMIN_JOURNAL_UNAVAILABLE", "the operation journal could not be reached", failure); - } finally { - DataSourceUtils.releaseConnection(connection, dataSource); - } - } - - private static void refuseIfNotResumable( - AdminOperationRecord existing, String approvalTicket, Instant now) { - if (existing.state() == AdminOperationState.COMPLETED) { - throw new MessageAuthorizationException( - "APPROVAL_ALREADY_EXECUTED", - ("approval %s was already executed to completion at %s; an approval authorises one" - + " execution, not a standing permission") - .formatted(approvalTicket, existing.finishedAt().orElse(existing.startedAt()))); - } - if (existing.state() == AdminOperationState.STARTED - && now.isBefore(existing.leaseExpiresAt())) { - throw new MessageAuthorizationException( - "ADMIN_OPERATION_IN_FLIGHT", - ("approval %s is being executed by %s until at least %s; two runtimes executing one" - + " approval is a duplicate storm, not a faster redrive") - .formatted(approvalTicket, existing.leaseOwner(), existing.leaseExpiresAt())); - } - } - - private boolean insertClaim( - Connection connection, - String approvalTicket, - PlanDigest planDigest, - String operationId, - String leaseOwner, - Instant expiry, - Instant now) - throws SQLException { - try (PreparedStatement statement = connection.prepareStatement(INSERT)) { - statement.setString(1, approvalTicket); - statement.setString(2, planDigest.value()); - statement.setString(3, operationId); - statement.setString(4, leaseOwner); - statement.setTimestamp(5, Timestamp.from(expiry)); - statement.setTimestamp(6, Timestamp.from(now)); - return statement.executeUpdate() == 1; - } - } - - private AdminOperationLease takeOver( - Connection connection, - AdminOperationRecord existing, - String approvalTicket, - PlanDigest planDigest, - String operationId, - String leaseOwner, - Instant expiry, - Instant now) - throws SQLException { - try (PreparedStatement statement = connection.prepareStatement(TAKE_OVER)) { - statement.setString(1, operationId); - statement.setString(2, leaseOwner); - statement.setTimestamp(3, Timestamp.from(expiry)); - statement.setString(4, approvalTicket); - statement.setString(5, planDigest.value()); - statement.setLong(6, existing.leaseToken()); - statement.setTimestamp(7, Timestamp.from(now)); - try (ResultSet rows = statement.executeQuery()) { - if (!rows.next()) { - // Another replica took it over between the read and this update. Refusing is correct: - // exactly one runtime executes an approval, and it is not this one. - throw new MessageAuthorizationException( - "ADMIN_OPERATION_IN_FLIGHT", - "approval " + approvalTicket + " was taken over by another runtime"); - } - return new AdminOperationLease( - approvalTicket, - planDigest, - operationId, - leaseOwner, - rows.getLong("lease_token"), - rows.getInt("items_completed")); - } - } - } - - @Override - public void checkpoint( - AdminOperationLease lease, int itemsCompleted, Duration leaseDuration, Instant now) { - Objects.requireNonNull(lease, "lease must not be null"); - Connection connection = DataSourceUtils.getConnection(dataSource); - try (PreparedStatement statement = connection.prepareStatement(CHECKPOINT)) { - statement.setInt(1, itemsCompleted); - statement.setTimestamp(2, Timestamp.from(now.plus(leaseDuration))); - statement.setString(3, lease.approvalTicket()); - statement.setString(4, lease.planDigest().value()); - statement.setLong(5, lease.leaseToken()); - requireOwned(statement.executeUpdate(), lease); - } catch (SQLException failure) { - throw new MessagingConfigurationException( - "ADMIN_JOURNAL_UNAVAILABLE", "the operation journal could not be reached", failure); - } finally { - DataSourceUtils.releaseConnection(connection, dataSource); - } - } - - @Override - public void complete(AdminOperationLease lease, int itemsCompleted, Instant now) { - settle(lease, AdminOperationState.COMPLETED, itemsCompleted, null, now); - } - - @Override - public void fail(AdminOperationLease lease, int itemsCompleted, String failureCode, Instant now) { - Objects.requireNonNull(failureCode, "failureCode must not be null"); - settle(lease, AdminOperationState.FAILED, itemsCompleted, failureCode, now); - } - - private void settle( - AdminOperationLease lease, - AdminOperationState state, - int itemsCompleted, - String failureCode, - Instant now) { - Objects.requireNonNull(lease, "lease must not be null"); - Connection connection = DataSourceUtils.getConnection(dataSource); - try (PreparedStatement statement = connection.prepareStatement(SETTLE)) { - statement.setString(1, state.name()); - statement.setInt(2, itemsCompleted); - statement.setTimestamp(3, Timestamp.from(now)); - statement.setString(4, failureCode); - statement.setString(5, lease.approvalTicket()); - statement.setString(6, lease.planDigest().value()); - statement.setLong(7, lease.leaseToken()); - requireOwned(statement.executeUpdate(), lease); - } catch (SQLException failure) { - throw new MessagingConfigurationException( - "ADMIN_JOURNAL_UNAVAILABLE", "the operation journal could not be reached", failure); - } finally { - DataSourceUtils.releaseConnection(connection, dataSource); - } - } - - private static void requireOwned(int updated, AdminOperationLease lease) { - if (updated == 1) { - return; - } - throw new MessageAuthorizationException( - "ADMIN_OPERATION_LEASE_LOST", - ("this runtime no longer holds the lease on approval %s at token %d; another runtime took" - + " the operation over and its progress must not be overwritten") - .formatted(lease.approvalTicket(), lease.leaseToken())); - } - - @Override - public Optional find(String approvalTicket, PlanDigest planDigest) { - Connection connection = DataSourceUtils.getConnection(dataSource); - try { - return read(connection, approvalTicket, planDigest); - } catch (SQLException failure) { - throw new MessagingConfigurationException( - "ADMIN_JOURNAL_UNAVAILABLE", "the operation journal could not be reached", failure); - } finally { - DataSourceUtils.releaseConnection(connection, dataSource); - } - } - - private Optional read( - Connection connection, String approvalTicket, PlanDigest planDigest) throws SQLException { - try (PreparedStatement statement = connection.prepareStatement(SELECT)) { - statement.setString(1, approvalTicket); - statement.setString(2, planDigest.value()); - try (ResultSet rows = statement.executeQuery()) { - if (!rows.next()) { - return Optional.empty(); - } - return Optional.of( - new AdminOperationRecord( - rows.getString("approval_ticket"), - new PlanDigest(rows.getString("plan_digest")), - rows.getString("operation_id"), - AdminOperationState.valueOf(rows.getString("state")), - rows.getInt("items_completed"), - rows.getString("lease_owner"), - rows.getLong("lease_token"), - rows.getTimestamp("lease_expires_at").toInstant(), - rows.getTimestamp("started_at").toInstant(), - Optional.ofNullable(rows.getTimestamp("finished_at")).map(Timestamp::toInstant), - Optional.ofNullable(rows.getString("failure_code")))); - } - } - } - - @Override - public boolean isDurable() { - return true; - } -} diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/JdbcOutboxRepository.java b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/JdbcOutboxRepository.java deleted file mode 100644 index 49eec646..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/JdbcOutboxRepository.java +++ /dev/null @@ -1,527 +0,0 @@ -package dev.caskeleton.messaging.outbox; - -import dev.caskeleton.messaging.api.CausationId; -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.CorrelationId; -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.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata; -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 java.sql.Array; -import java.sql.Connection; -import java.sql.PreparedStatement; -import java.sql.ResultSet; -import java.sql.SQLException; -import java.sql.Timestamp; -import java.time.Duration; -import java.time.Instant; -import java.util.ArrayList; -import java.util.LinkedHashMap; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; -import javax.sql.DataSource; -import org.springframework.jdbc.datasource.DataSourceUtils; -import org.springframework.transaction.support.TransactionSynchronizationManager; - -/** - * The PostgreSQL outbox. - * - *

{@link #append} deliberately takes no connection of its own: it uses the one the caller is - * already inside, which is the entire mechanism. An outbox row written on a separate connection - * commits independently of the business change and reopens the window the pattern exists to close. - * - *

Claiming uses {@code SELECT ... FOR UPDATE SKIP LOCKED}. Two relay instances polling the same - * table would otherwise both claim the same rows and publish them twice; {@code SKIP LOCKED} lets - * the second instance step over what the first already holds instead of blocking behind it. - */ -public final class JdbcOutboxRepository implements OutboxRepository { - - private static final String INSERT = - """ - INSERT INTO messaging_outbox ( - message_id, destination, message_type, schema_version, content_type, - payload, headers, created_at, status, attempts, - producer, occurred_at, correlation_id, causation_id, tenant, - partition_key, ordering_key, schema_subject, schema_uri, - traceparent, tracestate, baggage) - VALUES (?, ?, ?, ?, ?, ?, jsonb_object(?::text[]), ?, ?, ?, - ?, ?, ?, ?, ?, - ?, ?, ?, ?, - ?, ?, ?) - """; - - /** - * The columns every read of a row selects. - * - *

One constant rather than four copies of the list. The lease, claim, find and reclaim - * statements each spelled it out, and a column added to one of them and not the others is a - * message that arrives with its tenant on the claim path and without it on the lease path — a - * difference that shows up as a data bug in whichever consumer happened to be reading. - */ - private static final String COLUMNS = - """ - message_id, destination, message_type, schema_version, content_type, - payload, - ARRAY(SELECT h.key FROM jsonb_each_text(headers) h ORDER BY h.key) AS header_keys, - ARRAY(SELECT h.value FROM jsonb_each_text(headers) h ORDER BY h.key) AS header_values, - created_at, status, attempts, lease_expires_at, last_failure_code, - producer, occurred_at, correlation_id, causation_id, tenant, - partition_key, ordering_key, schema_subject, schema_uri, - traceparent, tracestate, baggage\ - """; - - /** - * The claim that records who holds the row and increments its fencing token. - * - *

The token increments on the server inside the same statement that grants the claim, so two - * relays racing for the same row cannot receive the same number. - */ - private static final String CLAIM = - """ - WITH claimable AS ( - SELECT m.message_id - FROM messaging_outbox m - WHERE m.status IN ('PENDING', 'AMBIGUOUS', 'IN_FLIGHT') - AND (m.lease_expires_at IS NULL OR m.lease_expires_at <= ?) - -- The retry clock lives in the row, not in the relay's memory. Without these two - -- predicates an AMBIGUOUS row became claimable again on the very next pass, so a - -- broker outage meant the whole backlog was republished every poll interval and the - -- configured attempt budget was a number nothing consulted. - AND (m.next_attempt_at IS NULL OR m.next_attempt_at <= ?) - AND m.attempts < ? - -- A row with an ordering key waits while an older row with the same key is still - -- unfinished. SKIP LOCKED let a second relay take the newer row while the first still - -- held the older one, and an AMBIGUOUS older row was retried after newer ones had - -- already gone out. md5 matches the partial index, which cannot hold a key that long. - AND (m.ordering_key IS NULL OR NOT EXISTS ( - SELECT 1 - FROM messaging_outbox older - WHERE older.destination = m.destination - AND md5(older.ordering_key) = md5(m.ordering_key) - AND older.ordering_key = m.ordering_key - AND older.status IN ('PENDING', 'AMBIGUOUS', 'IN_FLIGHT') - AND (older.created_at, older.message_id) < (m.created_at, m.message_id))) - ORDER BY m.created_at, m.message_id - LIMIT ? - FOR UPDATE SKIP LOCKED - ) - UPDATE messaging_outbox o - SET status = 'IN_FLIGHT', - lease_expires_at = ?, - lease_owner = ?, - lease_token = o.lease_token + 1 - FROM claimable c - WHERE o.message_id = c.message_id - RETURNING o.message_id, o.destination, o.message_type, o.schema_version, o.content_type, - o.payload, - ARRAY(SELECT h.key FROM jsonb_each_text(o.headers) h ORDER BY h.key) AS header_keys, - ARRAY(SELECT h.value FROM jsonb_each_text(o.headers) h ORDER BY h.key) - AS header_values, - o.created_at, o.status, o.attempts, - o.lease_expires_at, o.last_failure_code, o.lease_owner, o.lease_token, - o.producer, o.occurred_at, o.correlation_id, o.causation_id, o.tenant, - o.partition_key, o.ordering_key, o.schema_subject, o.schema_uri, - o.traceparent, o.tracestate, o.baggage - """; - - private final DataSource dataSource; - - /** - * Creates a repository over a data source. - * - * @param dataSource the outbox data source - */ - public JdbcOutboxRepository(DataSource dataSource) { - this.dataSource = Objects.requireNonNull(dataSource, "dataSource must not be null"); - } - - /** - * Appends a record on an existing connection. - * - *

Package-private. It used to be the public overload "business code should use", which meant - * the safe path was the one a caller had to know about and the interface method — the one the - * port documents — opened its own connection. Handing a {@code Connection} across a reliability - * API also makes the transaction the caller's problem to remember; {@link #append(OutboxRecord)} - * now joins the caller's transaction itself and refuses when there is none. - * - * @param connection the caller's transactional connection - * @param record the record to write - */ - void append(Connection connection, OutboxRecord record) { - Objects.requireNonNull(connection, "connection must not be null"); - Objects.requireNonNull(record, "record must not be null"); - try (PreparedStatement statement = connection.prepareStatement(INSERT)) { - statement.setObject(1, record.messageId().value()); - statement.setString(2, record.destination().value()); - statement.setString(3, record.messageType().value()); - statement.setInt(4, record.schemaVersion().value()); - statement.setString(5, record.contentType().value()); - statement.setBytes(6, record.payload()); - statement.setArray(7, connection.createArrayOf("text", flatten(record.headers()))); - statement.setTimestamp(8, Timestamp.from(record.createdAt())); - statement.setString(9, record.status().name()); - statement.setInt(10, record.attempts()); - OutboxCanonicalMetadata metadata = record.metadata(); - statement.setString(11, metadata.producer().map(ProducerId::value).orElse(null)); - statement.setTimestamp(12, metadata.occurredAt().map(Timestamp::from).orElse(null)); - statement.setString(13, metadata.correlationId().map(CorrelationId::value).orElse(null)); - statement.setObject( - 14, metadata.causationId().map(causation -> causation.value().value()).orElse(null)); - statement.setString(15, metadata.tenant().map(TenantContext::tenantId).orElse(null)); - statement.setString(16, metadata.partitionKey().orElse(null)); - statement.setString(17, metadata.orderingKey().orElse(null)); - statement.setString(18, metadata.schemaSubject().orElse(null)); - statement.setString(19, metadata.schemaUri().orElse(null)); - statement.setString(20, metadata.traceContext().traceparent().orElse(null)); - statement.setString(21, metadata.traceContext().tracestate().orElse(null)); - statement.setString(22, metadata.traceContext().baggage().orElse(null)); - statement.executeUpdate(); - } catch (SQLException exception) { - throw new MessagingConfigurationException( - "OUTBOX_APPEND_FAILED", "could not append an outbox record", exception); - } - } - - @Override - public void append(OutboxRecord record) { - Objects.requireNonNull(record, "record must not be null"); - // The port says this runs inside the caller's business transaction. It did not: it opened a raw - // connection from the pool, which auto-commits independently — so a business transaction that - // rolled back afterwards left the event behind and the relay published a change that never - // happened. - requireActiveTransaction("OUTBOX_TRANSACTION_REQUIRED", "appending to the outbox"); - Connection connection = DataSourceUtils.getConnection(dataSource); - try { - append(connection, record); - } finally { - // Releases only when the connection is not the transaction's; when it is, this is a no-op and - // the caller's commit or rollback decides what happens to the row. - DataSourceUtils.releaseConnection(connection, dataSource); - } - } - - /** - * Refuses when there is no transaction to join, or when it cannot write. - * - *

Fail-fast rather than "work anyway": an append that silently runs outside the caller's - * transaction produces exactly the ghost publication this repository exists to prevent, and it - * produces it only on the rollback path — which is the path nobody exercises before production. - */ - private void requireActiveTransaction(String code, String what) { - if (!TransactionSynchronizationManager.isActualTransactionActive()) { - throw new MessagingConfigurationException( - code, - what - + " requires an active transaction; without one the row commits on its own and a" - + " later rollback of the business change leaves it behind"); - } - if (TransactionSynchronizationManager.isCurrentTransactionReadOnly()) { - throw new MessagingConfigurationException( - code, what + " requires a writable transaction; the current one is read-only"); - } - if (!TransactionSynchronizationManager.hasResource(dataSource)) { - throw new MessagingConfigurationException( - code, - what - + " requires the active transaction to be bound to this DataSource; it is bound to" - + " another, so the two would commit independently"); - } - } - - @Override - public List claimBatch( - String owner, int batchSize, Duration leaseDuration, Instant now, int maxAttempts) { - Objects.requireNonNull(owner, "owner must not be null"); - Objects.requireNonNull(leaseDuration, "leaseDuration must not be null"); - Objects.requireNonNull(now, "now must not be null"); - Instant expiresAt = now.plus(leaseDuration); - return withConnection( - connection -> { - List claimed = new ArrayList<>(); - try (PreparedStatement statement = connection.prepareStatement(CLAIM)) { - statement.setTimestamp(1, Timestamp.from(now)); - statement.setTimestamp(2, Timestamp.from(now)); - statement.setInt(3, maxAttempts); - statement.setInt(4, batchSize); - statement.setTimestamp(5, Timestamp.from(expiresAt)); - statement.setString(6, owner); - try (ResultSet results = statement.executeQuery()) { - while (results.next()) { - claimed.add( - new OutboxLease( - read(results), - results.getString("lease_owner"), - results.getLong("lease_token"), - expiresAt)); - } - } - } - return List.copyOf(claimed); - }); - } - - @Override - public OutboxTransitionResult markPublished(OutboxLease lease, Instant now) { - return transition( - lease, - "UPDATE messaging_outbox SET status = 'PUBLISHED', published_at = ?, " - + "lease_expires_at = NULL, lease_owner = NULL, next_attempt_at = NULL, " - + "attempts = attempts + 1 ", - now, - null); - } - - @Override - public OutboxTransitionResult markAmbiguous( - OutboxLease lease, String failureCode, Instant now, Instant nextAttemptAt) { - Objects.requireNonNull(nextAttemptAt, "nextAttemptAt must not be null"); - // The backoff the policy computed is written onto the row. Keeping it in the relay's memory - // means a restart forgets it, and every relay computes its own — so the same row is retried by - // as many workers as there are replicas, as fast as they poll. - return transitionWithNextAttempt( - lease, - "UPDATE messaging_outbox SET status = 'AMBIGUOUS', lease_expires_at = NULL, " - + "lease_owner = NULL, last_failure_code = ?, attempts = attempts + 1, " - + "next_attempt_at = ? ", - failureCode, - nextAttemptAt); - } - - @Override - public OutboxTransitionResult markExhausted(OutboxLease lease, String reason, Instant now) { - return transition( - lease, - "UPDATE messaging_outbox SET status = 'EXHAUSTED', lease_expires_at = NULL, " - + "lease_owner = NULL, last_failure_code = ?, attempts = attempts + 1 ", - now, - reason); - } - - private OutboxTransitionResult transitionWithNextAttempt( - OutboxLease lease, String setClause, String failureCode, Instant nextAttemptAt) { - Objects.requireNonNull(lease, "lease must not be null"); - String sql = - setClause - + "WHERE message_id = ? AND status = 'IN_FLIGHT' AND lease_owner = ? AND lease_token =" - + " ?"; - return withConnection( - connection -> { - try (PreparedStatement statement = connection.prepareStatement(sql)) { - statement.setString(1, failureCode); - statement.setTimestamp(2, Timestamp.from(nextAttemptAt)); - statement.setObject(3, lease.messageId().value()); - statement.setString(4, lease.owner()); - statement.setLong(5, lease.token()); - return statement.executeUpdate() == 1 - ? OutboxTransitionResult.APPLIED - : OutboxTransitionResult.STALE_LEASE; - } - }); - } - - @Override - public OutboxTransitionResult markFailed(OutboxLease lease, String failureCode, Instant now) { - return transition( - lease, - "UPDATE messaging_outbox SET status = 'FAILED', lease_expires_at = NULL, " - + "lease_owner = NULL, last_failure_code = ?, attempts = attempts + 1 ", - now, - failureCode); - } - - @Override - public OutboxTransitionResult releaseLease(OutboxLease lease) { - return transition( - lease, - "UPDATE messaging_outbox SET status = 'PENDING', lease_expires_at = NULL, " - + "lease_owner = NULL ", - null, - null); - } - - /** - * Applies a terminal write, but only to the row this lease still owns. - * - *

The predicate carries the owner and the token as well as the id, so a relay that stalled - * past its lease writes nothing: another relay's claim incremented the token, and this update - * matches zero rows. Zero is reported rather than swallowed — a stale write means this worker may - * have produced a duplicate publication, which is exactly what an operator needs to see. - */ - private OutboxTransitionResult transition( - OutboxLease lease, String setClause, Instant now, String failureCode) { - Objects.requireNonNull(lease, "lease must not be null"); - String sql = - setClause - + "WHERE message_id = ? AND status = 'IN_FLIGHT' AND lease_owner = ? AND lease_token =" - + " ?"; - return withConnection( - connection -> { - try (PreparedStatement statement = connection.prepareStatement(sql)) { - int index = 1; - if (failureCode != null) { - statement.setString(index++, failureCode); - } else if (now != null) { - statement.setTimestamp(index++, Timestamp.from(now)); - } - statement.setObject(index++, lease.messageId().value()); - statement.setString(index++, lease.owner()); - statement.setLong(index, lease.token()); - return statement.executeUpdate() == 1 - ? OutboxTransitionResult.APPLIED - : OutboxTransitionResult.STALE_LEASE; - } - }); - } - - @Override - public Optional find(MessageId messageId) { - return withConnection( - connection -> { - try (PreparedStatement statement = - connection.prepareStatement( - "SELECT " + COLUMNS + " FROM messaging_outbox WHERE message_id = ?")) { - statement.setObject(1, messageId.value()); - try (ResultSet results = statement.executeQuery()) { - return results.next() ? Optional.of(read(results)) : Optional.empty(); - } - } - }); - } - - @Override - public int purgePublishedBefore(Instant publishedBefore, int limit) { - Objects.requireNonNull(publishedBefore, "publishedBefore must not be null"); - if (limit < 1) { - throw new IllegalArgumentException("a bounded purge deletes at least one row per call"); - } - // The CTE picks a bounded set of ids with SKIP LOCKED and deletes exactly those. An unbounded - // DELETE holds locks and writes WAL in proportion to the whole backlog, which stalls the relay - // and the business writes behind retention. - return withConnection( - connection -> { - try (PreparedStatement statement = - connection.prepareStatement( - """ - WITH expired AS ( - SELECT message_id - FROM messaging_outbox - WHERE status = 'PUBLISHED' AND published_at < ? - ORDER BY published_at - LIMIT ? - FOR UPDATE SKIP LOCKED - ) - DELETE FROM messaging_outbox o - USING expired e - WHERE o.message_id = e.message_id - """)) { - statement.setTimestamp(1, Timestamp.from(publishedBefore)); - statement.setInt(2, limit); - return statement.executeUpdate(); - } - }); - } - - private static OutboxRecord read(ResultSet results) throws SQLException { - Timestamp lease = results.getTimestamp("lease_expires_at"); - return new OutboxRecord( - new MessageId(results.getObject("message_id", java.util.UUID.class)), - new DestinationName(results.getString("destination")), - new MessageType(results.getString("message_type")), - new SchemaVersion(results.getInt("schema_version")), - new ContentType(results.getString("content_type")), - results.getBytes("payload"), - headers(results.getArray("header_keys"), results.getArray("header_values")), - readMetadata(results), - results.getTimestamp("created_at").toInstant(), - OutboxStatus.valueOf(results.getString("status")), - results.getInt("attempts"), - Optional.ofNullable(lease).map(Timestamp::toInstant), - Optional.ofNullable(results.getString("last_failure_code"))); - } - - /** - * Rebuilds the canonical metadata from the row's own columns. - * - *

Absent columns stay absent. A row written before the columns existed rebuilds with empty - * metadata, which is the same thing a row written by a producer that had none rebuilds with — and - * the reader's behaviour has to be identical in both cases, because guessing a tenant or a - * correlation is worse than carrying none. - */ - private static OutboxCanonicalMetadata readMetadata(ResultSet results) throws SQLException { - Timestamp occurredAt = results.getTimestamp("occurred_at"); - java.util.UUID causation = results.getObject("causation_id", java.util.UUID.class); - return new OutboxCanonicalMetadata( - Optional.ofNullable(results.getString("producer")).map(ProducerId::new), - Optional.ofNullable(occurredAt).map(Timestamp::toInstant), - Optional.ofNullable(results.getString("correlation_id")).map(CorrelationId::new), - Optional.ofNullable(causation).map(value -> new CausationId(new MessageId(value))), - Optional.ofNullable(results.getString("tenant")).map(TenantContext::new), - Optional.ofNullable(results.getString("partition_key")), - Optional.ofNullable(results.getString("ordering_key")), - Optional.ofNullable(results.getString("schema_subject")), - Optional.ofNullable(results.getString("schema_uri")), - new TraceContext( - Optional.ofNullable(results.getString("traceparent")), - Optional.ofNullable(results.getString("tracestate")), - Optional.ofNullable(results.getString("baggage")))); - } - - private T withConnection(ConnectionCallback callback) { - try (Connection connection = dataSource.getConnection()) { - return callback.apply(connection); - } catch (SQLException exception) { - throw new MessagingConfigurationException( - "OUTBOX_QUERY_FAILED", "an outbox query failed", exception); - } - } - - /** - * The headers as one flat key, value, key, value array for {@code jsonb_object(text[])}. - * - *

PostgreSQL builds and escapes the JSON. The hand-rolled writer and reader this replaces got - * the escaping right one way and wrong the other: the reader took a quote after an escaped - * backslash for an escaped quote, so a value ending in a backslash ran on into the next header. - */ - private static String[] flatten(Map headers) { - String[] flat = new String[headers.size() * 2]; - int index = 0; - for (Map.Entry entry : headers.entrySet()) { - flat[index++] = entry.getKey(); - flat[index++] = entry.getValue(); - } - return flat; - } - - /** Rebuilds the headers from the aligned key and value arrays the reads select. */ - private static Map headers(Array keys, Array values) throws SQLException { - Map headers = new LinkedHashMap<>(); - if (keys == null || values == null) { - return headers; - } - String[] names = (String[]) keys.getArray(); - String[] texts = (String[]) values.getArray(); - for (int index = 0; index < names.length; index++) { - headers.put(names[index], texts[index]); - } - return headers; - } - - /** A unit of work against a borrowed connection. */ - @FunctionalInterface - private interface ConnectionCallback { - - T apply(Connection connection) throws SQLException; - } -} diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1001__messaging_outbox.sql b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1001__messaging_outbox.sql deleted file mode 100644 index 25df7b71..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1001__messaging_outbox.sql +++ /dev/null @@ -1,41 +0,0 @@ --- Transactional outbox. --- --- Written by the business transaction, drained by the relay. message_id is the primary key rather --- than a surrogate: it is the logical identity the relay must preserve across every retry, and --- making it the key means no code path can accidentally publish the same row under a new id. -CREATE TABLE messaging_outbox -( - message_id UUID NOT NULL, - destination VARCHAR(160) NOT NULL, - message_type VARCHAR(240) NOT NULL, - schema_version INTEGER NOT NULL, - content_type VARCHAR(160) NOT NULL, - payload BYTEA NOT NULL, - headers JSONB NOT NULL DEFAULT '{}'::JSONB, - created_at TIMESTAMPTZ NOT NULL, - status VARCHAR(16) NOT NULL, - attempts INTEGER NOT NULL DEFAULT 0, - lease_expires_at TIMESTAMPTZ, - published_at TIMESTAMPTZ, - last_failure_code VARCHAR(120), - CONSTRAINT pk_messaging_outbox PRIMARY KEY (message_id), - CONSTRAINT ck_messaging_outbox_status - CHECK (status IN ('PENDING', 'IN_FLIGHT', 'PUBLISHED', 'AMBIGUOUS', 'FAILED')), - CONSTRAINT ck_messaging_outbox_attempts CHECK (attempts >= 0), - CONSTRAINT ck_messaging_outbox_schema_version CHECK (schema_version >= 1) -); - --- The relay's only hot query: claim the oldest rows that are publishable and unleased. The partial --- index keeps it proportional to the backlog rather than to the table, which matters because --- PUBLISHED rows accumulate until the retention job removes them. --- --- IN_FLIGHT is included. A relay that dies mid-publish leaves rows in that state, and their lease --- expiry is what makes them claimable again; omitting them here would strand those messages. -CREATE INDEX ix_messaging_outbox_claimable - ON messaging_outbox (created_at) - WHERE status IN ('PENDING', 'AMBIGUOUS', 'IN_FLIGHT'); - --- Retention sweeps read this. -CREATE INDEX ix_messaging_outbox_published_at - ON messaging_outbox (published_at) - WHERE status = 'PUBLISHED'; diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1002__messaging_outbox_lease_fencing.sql b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1002__messaging_outbox_lease_fencing.sql deleted file mode 100644 index d1cdd1a1..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1002__messaging_outbox_lease_fencing.sql +++ /dev/null @@ -1,39 +0,0 @@ --- Lease owner and fencing token. --- --- V1 recorded only lease_expires_at, so a claim said when it would end and nothing about who held --- it. The relay's terminal writes matched on message_id alone, which means a worker that stalled --- past its lease could still write: --- --- relay A claims the row and calls the broker --- the lease expires; relay B reclaims it, publishes, and records PUBLISHED --- relay A finally times out and records AMBIGUOUS over the top --- --- The row is now claimable again and the message is published a second time. Making the lease --- longer than the publish timeout lowers the odds; it does not turn a GC pause, a scheduler stall --- or a slow broker into a data constraint. A token does: every terminal write names the --- acquisition it belongs to, and a superseded worker's write matches nothing. -ALTER TABLE messaging_outbox - ADD COLUMN lease_owner VARCHAR(160), - ADD COLUMN lease_token BIGINT NOT NULL DEFAULT 0, - ADD COLUMN next_attempt_at TIMESTAMPTZ; - --- Backfill is unnecessary for correctness — the default is 0 and the first claim increments it — --- but the constraint states the invariant the code depends on. -ALTER TABLE messaging_outbox - ADD CONSTRAINT ck_messaging_outbox_lease_token CHECK (lease_token >= 0); - --- EXHAUSTED is a new terminal state: the attempt budget ran out without any confirmation, which is --- not the same as the broker rejecting the message. V1's CHECK listed five states, so writing the --- sixth failed at the constraint rather than at review. -ALTER TABLE messaging_outbox - DROP CONSTRAINT ck_messaging_outbox_status; - -ALTER TABLE messaging_outbox - ADD CONSTRAINT ck_messaging_outbox_status - CHECK (status IN ('PENDING', 'IN_FLIGHT', 'PUBLISHED', 'AMBIGUOUS', 'FAILED', 'EXHAUSTED')); - --- The claim predicate now filters on next_attempt_at as well, so the partial index has to carry it --- or every poll degrades into a scan of the backlog once rows start backing off. -CREATE INDEX ix_messaging_outbox_next_attempt - ON messaging_outbox (next_attempt_at, created_at) - WHERE status IN ('PENDING', 'AMBIGUOUS', 'IN_FLIGHT'); diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1003__messaging_admin_operation_journal.sql b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1003__messaging_admin_operation_journal.sql deleted file mode 100644 index 9c79ca89..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1003__messaging_admin_operation_journal.sql +++ /dev/null @@ -1,37 +0,0 @@ --- The destructive-operation journal. --- --- Keyed on (approval_ticket, plan_digest) rather than the ticket alone: the ticket alone cannot --- distinguish "this approval already ran" from "this approval is being presented for a different --- plan", and those need opposite answers. The primary key is what makes two replicas racing for the --- same approval resolve to one winner rather than two executions. --- --- lease_owner/lease_token/lease_expires_at are the same fencing pattern the outbox uses: a runtime --- that stalls past its lease loses it, and its later writes are refused because its token is stale. --- items_completed is the resume point — without it a retry after a crash republishes everything the --- first attempt already moved. - -CREATE TABLE IF NOT EXISTS messaging_admin_operation ( - approval_ticket VARCHAR(200) NOT NULL, - plan_digest CHAR(64) NOT NULL, - operation_id VARCHAR(200) NOT NULL, - state VARCHAR(20) NOT NULL, - items_completed INTEGER NOT NULL DEFAULT 0, - lease_owner VARCHAR(200) NOT NULL, - lease_token BIGINT NOT NULL DEFAULT 1, - lease_expires_at TIMESTAMPTZ NOT NULL, - started_at TIMESTAMPTZ NOT NULL, - finished_at TIMESTAMPTZ, - failure_code VARCHAR(200), - CONSTRAINT pk_messaging_admin_operation PRIMARY KEY (approval_ticket, plan_digest), - CONSTRAINT ck_messaging_admin_operation_state - CHECK (state IN ('STARTED', 'COMPLETED', 'FAILED')), - CONSTRAINT ck_messaging_admin_operation_items CHECK (items_completed >= 0), - CONSTRAINT ck_messaging_admin_operation_token CHECK (lease_token >= 1), - CONSTRAINT ck_messaging_admin_operation_digest CHECK (plan_digest ~ '^[0-9a-f]{64}$') -); - --- Answers "which operations are in flight right now", the question an operator asks when a redrive --- appears stuck and they are deciding whether to take it over. -CREATE INDEX IF NOT EXISTS ix_messaging_admin_operation_live - ON messaging_admin_operation (lease_expires_at) - WHERE state = 'STARTED'; diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1004__messaging_outbox_canonical_metadata.sql b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1004__messaging_outbox_canonical_metadata.sql deleted file mode 100644 index 920ed047..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1004__messaging_outbox_canonical_metadata.sql +++ /dev/null @@ -1,66 +0,0 @@ --- The envelope's canonical facts, as columns. --- --- V1 stored identity, type, version, content type, payload and a free-form header map. Everything --- else the envelope carries — producer, tenant, correlation, causation, the routing keys, the --- schema the payload was written against, the active trace — had nowhere to go, so it was either --- lost when the relay rebuilt the envelope or smuggled through the header map under the reserved --- `msg.*` names the platform is supposed to own. Smuggling is the worse of the two: a row whose --- header map contains `msg.id` overwrites another message's identity on the wire, and the consumer --- trusts the last such header it sees. --- --- Columns rather than a versioned envelope blob. Both round-trip the values faithfully; only one of --- them lets the relay answer an operator's questions. "Which tenant is the backlog for", "which --- correlation is stuck", "which rows carry a schema this consumer cannot read" are SELECTs against --- this table if the fields are columns, and payload decoding of the whole backlog if they are not. --- --- Every column is nullable. A row written before this migration has none of them, and a producer --- that genuinely has no correlation writes none either; the reader treats both the same way, which --- is to carry what is there and invent nothing. -ALTER TABLE messaging_outbox - ADD COLUMN producer VARCHAR(120), - ADD COLUMN occurred_at TIMESTAMPTZ, - ADD COLUMN correlation_id VARCHAR(160), - ADD COLUMN causation_id UUID, - ADD COLUMN tenant VARCHAR(64), - ADD COLUMN partition_key VARCHAR(1024), - ADD COLUMN ordering_key VARCHAR(1024), - ADD COLUMN schema_subject VARCHAR(240), - ADD COLUMN schema_uri VARCHAR(1024), - ADD COLUMN traceparent VARCHAR(64), - ADD COLUMN tracestate VARCHAR(512), - ADD COLUMN baggage VARCHAR(8192); - --- The same bound TenantContext enforces in Java. Stated here as well because the relay, the CDC --- connector and any operator query read this table directly: a tenant slug that only the --- application validates is a tenant slug that an INSERT from anywhere else can violate, and a --- tenant id is the field every downstream authorization decision reads. -ALTER TABLE messaging_outbox - ADD CONSTRAINT ck_messaging_outbox_tenant - CHECK (tenant IS NULL OR tenant ~ '^[a-z0-9][a-z0-9._-]{0,63}$'); - --- A schema location with no subject cannot be resolved: the reader would hold a URI and no way to --- know what it is a schema for. -ALTER TABLE messaging_outbox - ADD CONSTRAINT ck_messaging_outbox_schema_reference - CHECK (schema_uri IS NULL OR schema_subject IS NOT NULL); - --- "Which tenant is the backlog for" is the first question asked when an outbox stops draining, and --- before this column it could only be answered by decoding every payload. Partial, like the other --- outbox indexes, because PUBLISHED rows accumulate until retention removes them and no operator --- asks that question about work that already left. -CREATE INDEX ix_messaging_outbox_tenant_backlog - ON messaging_outbox (tenant, created_at) - WHERE status IN ('PENDING', 'AMBIGUOUS', 'IN_FLIGHT'); - --- The key a relay puts on the wire, computed once and stored, so both relays agree. --- --- Debezium's Event Router takes the message key from a column. It was pointed at `destination`, --- which made the key the topic name — every message on a topic sharing one key, so every message --- landing on one partition, and keyed ordering meaning nothing. The polling relay meanwhile used --- the partition key when the row had one and the message id when it did not. --- --- A generated column states that fallback once, in the place both relays read, instead of leaving --- it as a rule each of them implements separately and one of them gets wrong. -ALTER TABLE messaging_outbox - ADD COLUMN routing_key TEXT - GENERATED ALWAYS AS (COALESCE(partition_key, message_id::TEXT)) STORED; diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1005__messaging_outbox_ordering_key_index.sql b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1005__messaging_outbox_ordering_key_index.sql deleted file mode 100644 index f62af018..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1005__messaging_outbox_ordering_key_index.sql +++ /dev/null @@ -1,9 +0,0 @@ --- The claim now holds back a row while an older, unfinished row shares its destination and --- ordering key. That check runs once per candidate row, so it needs an index or every claim scans --- the backlog once per row it considers. --- --- md5 of the key rather than the key: ordering_key is VARCHAR(1024), and a long multi-byte key --- would exceed the btree entry limit and fail the business transaction that appends the row. -CREATE INDEX ix_messaging_outbox_unfinished_ordering_key - ON messaging_outbox (destination, md5(ordering_key), created_at) - WHERE ordering_key IS NOT NULL AND status IN ('PENDING', 'AMBIGUOUS', 'IN_FLIGHT'); diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1101__messaging_inbox.sql b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1101__messaging_inbox.sql deleted file mode 100644 index bb966005..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration/messaging/V1101__messaging_inbox.sql +++ /dev/null @@ -1,18 +0,0 @@ --- Consumer inbox. --- --- The composite primary key is the deduplication mechanism: reserving a message is an INSERT that --- either succeeds or violates the key, inside the same transaction as the handler's side effect. --- Two independent consumers of the same event each get their own row, so one cannot suppress the --- other. -CREATE TABLE messaging_inbox -( - message_id UUID NOT NULL, - consumer_id VARCHAR(160) NOT NULL, - processed_at TIMESTAMPTZ NOT NULL, - CONSTRAINT pk_messaging_inbox PRIMARY KEY (message_id, consumer_id) -); - --- Retention sweeps read this. The window must outlive the broker's maximum redelivery delay: --- pruning a row before its message can still be redelivered reopens the duplicate this table --- exists to close. -CREATE INDEX ix_messaging_inbox_processed_at ON messaging_inbox (processed_at); diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/inbox/JdbcInboxTransactionRequirementTest.java b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/inbox/JdbcInboxTransactionRequirementTest.java deleted file mode 100644 index 4baf5cde..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/inbox/JdbcInboxTransactionRequirementTest.java +++ /dev/null @@ -1,98 +0,0 @@ -package dev.caskeleton.messaging.inbox; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.time.Instant; -import javax.sql.DataSource; -import org.junit.jupiter.api.AfterEach; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; -import org.springframework.transaction.support.TransactionSynchronizationManager; - -/** - * What {@code reserve(...)} does when there is no transaction to join. - * - *

{@code IdempotentConsumer} calls this inside its transaction runner, and the implementation - * opened a raw connection that auto-commits. The reservation therefore survived a rollback of the - * side effect it was guarding: the message counts as processed, the work never happened, and - * redelivery is refused because the inbox row is already there. - * - *

Hermetic: the refusal has to happen before any connection is requested, and the data source - * below fails the test by being asked for one. - */ -class JdbcInboxTransactionRequirementTest { - - /** A data source that fails the test by being used: the refusal must precede any connection. */ - private final DataSource dataSource = new RefusingDataSource(); - - private final JdbcInboxRepository repository = new JdbcInboxRepository(dataSource); - - @AfterEach - void clearTransactionState() { - TransactionSynchronizationManager.clear(); - if (TransactionSynchronizationManager.hasResource(dataSource)) { - TransactionSynchronizationManager.unbindResource(dataSource); - } - } - - @Test - @DisplayName("reserving outside a transaction is refused before a connection is opened") - void reservingOutsideATransactionIsRefused() { - assertThatThrownBy(() -> repository.reserve(MessageId.newId(), "order-projection", NOW)) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("requires an active transaction"); - } - - @Test - @DisplayName("a read-only transaction is refused") - void aReadOnlyTransactionIsRefused() { - TransactionSynchronizationManager.setActualTransactionActive(true); - TransactionSynchronizationManager.setCurrentTransactionReadOnly(true); - - assertThatThrownBy(() -> repository.reserve(MessageId.newId(), "order-projection", NOW)) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("read-only"); - } - - @Test - @DisplayName("a transaction bound to another DataSource is refused") - void aTransactionOnAnotherDataSourceIsRefused() { - TransactionSynchronizationManager.setActualTransactionActive(true); - - assertThatThrownBy(() -> repository.reserve(MessageId.newId(), "order-projection", NOW)) - .as("two DataSources means two commits, which is the atomicity this exists to provide") - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("bound to this DataSource"); - } - - @Test - @DisplayName("the refusal names a code an operator can search for") - void theRefusalNamesACode() { - assertThatThrownBy(() -> repository.reserve(MessageId.newId(), "order-projection", NOW)) - .isInstanceOfSatisfying( - MessagingConfigurationException.class, - failure -> - assertThat(failure.failure().code()).isEqualTo("INBOX_TRANSACTION_REQUIRED")); - } - - private static final Instant NOW = Instant.parse("2026-08-14T00:00:00Z"); - - /** Throws if anything asks it for a connection. */ - private static final class RefusingDataSource - extends org.springframework.jdbc.datasource.AbstractDataSource { - - @Override - public java.sql.Connection getConnection() { - throw new AssertionError( - "the refusal must happen before a connection is requested; opening one is the defect"); - } - - @Override - public java.sql.Connection getConnection(String username, String password) { - return getConnection(); - } - } -} diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/JdbcOutboxTransactionRequirementTest.java b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/JdbcOutboxTransactionRequirementTest.java deleted file mode 100644 index 1b33e1a8..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/JdbcOutboxTransactionRequirementTest.java +++ /dev/null @@ -1,121 +0,0 @@ -package dev.caskeleton.messaging.outbox; - -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.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.reliability.OutboxRecord; -import dev.caskeleton.messaging.reliability.OutboxStatus; -import java.time.Instant; -import java.util.Map; -import java.util.Optional; -import javax.sql.DataSource; -import org.junit.jupiter.api.AfterEach; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; -import org.springframework.transaction.support.TransactionSynchronizationManager; - -/** - * What {@code append(record)} does when there is no transaction to join. - * - *

The port says the append runs inside the caller's business transaction. The implementation - * called {@code dataSource.getConnection()}, which auto-commits on its own connection — so a - * business transaction that rolled back afterwards left the outbox row behind and the relay - * published an event for a change that never happened. - * - *

These are hermetic: the refusal happens before any connection is requested, which is also the - * property under test. The mock would fail the test by being touched at all. - */ -class JdbcOutboxTransactionRequirementTest { - - /** A data source that fails the test by being used: the refusal must precede any connection. */ - private final DataSource dataSource = new RefusingDataSource(); - - private final JdbcOutboxRepository repository = new JdbcOutboxRepository(dataSource); - - @AfterEach - void clearTransactionState() { - TransactionSynchronizationManager.clear(); - if (TransactionSynchronizationManager.hasResource(dataSource)) { - TransactionSynchronizationManager.unbindResource(dataSource); - } - } - - @Test - @DisplayName("appending outside a transaction is refused before a connection is opened") - void appendingOutsideATransactionIsRefused() { - assertThatThrownBy(() -> repository.append(record())) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("requires an active transaction"); - } - - @Test - @DisplayName("a read-only transaction is refused") - void aReadOnlyTransactionIsRefused() { - TransactionSynchronizationManager.setActualTransactionActive(true); - TransactionSynchronizationManager.setCurrentTransactionReadOnly(true); - - assertThatThrownBy(() -> repository.append(record())) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("read-only"); - } - - @Test - @DisplayName("a transaction bound to another DataSource is refused") - void aTransactionOnAnotherDataSourceIsRefused() { - TransactionSynchronizationManager.setActualTransactionActive(true); - - assertThatThrownBy(() -> repository.append(record())) - .as("two DataSources means two commits, which is the atomicity this exists to provide") - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("bound to this DataSource"); - } - - @Test - @DisplayName("the refusal names a code an operator can search for") - void theRefusalNamesACode() { - assertThatThrownBy(() -> repository.append(record())) - .isInstanceOfSatisfying( - MessagingConfigurationException.class, - failure -> - assertThat(failure.failure().code()).isEqualTo("OUTBOX_TRANSACTION_REQUIRED")); - } - - private static OutboxRecord record() { - return new OutboxRecord( - MessageId.newId(), - new DestinationName("orders.events"), - new MessageType("order.placed"), - new SchemaVersion(1), - ContentType.JSON, - "{}".getBytes(java.nio.charset.StandardCharsets.UTF_8), - Map.of(), - dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata.none(), - Instant.parse("2026-08-14T00:00:00Z"), - OutboxStatus.PENDING, - 0, - Optional.empty(), - Optional.empty()); - } - - /** Throws if anything asks it for a connection. */ - private static final class RefusingDataSource - extends org.springframework.jdbc.datasource.AbstractDataSource { - - @Override - public java.sql.Connection getConnection() { - throw new AssertionError( - "the refusal must happen before a connection is requested; opening one is the defect"); - } - - @Override - public java.sql.Connection getConnection(String username, String password) { - return getConnection(); - } - } -} diff --git a/src/platforms/messaging/messaging-reliability/build.gradle b/src/platforms/messaging/messaging-reliability/build.gradle deleted file mode 100644 index d2f62103..00000000 --- a/src/platforms/messaging/messaging-reliability/build.gradle +++ /dev/null @@ -1,18 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -// The outbox relay and the inbox consumer logic, framework-free. What they store and claim goes -// through the ports in messaging-reliability-api; the relational implementation of those ports is -// messaging-reliability-jdbc-postgresql. Split so a leaf's name says what it depends on: this one -// is Java stdlib plus the messaging APIs, the other is Spring JDBC and PostgreSQL SQL. -dependencies { - api project(':messaging:messaging-core-api') - api project(':messaging:messaging-reliability-api') - // The relay hands encoded rows to the publisher as EncodedMessage. - - // 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') - testImplementation project(':messaging:messaging-policy') -} diff --git a/src/platforms/messaging/messaging-reliability/gradle.lockfile b/src/platforms/messaging/messaging-reliability/gradle.lockfile deleted file mode 100644 index 7feb7385..00000000 --- a/src/platforms/messaging/messaging-reliability/gradle.lockfile +++ /dev/null @@ -1,87 +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.50.0=annotationProcessor,checkstyle,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.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -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.8=testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-core:1.16.8=testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-observation:1.16.8=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.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.hdrhistogram:HdrHistogram:2.2.2=testRuntimeClasspath -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,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=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.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty=compileClasspath,runtimeClasspath diff --git a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/IdempotentConsumer.java b/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/IdempotentConsumer.java deleted file mode 100644 index 35f2bef6..00000000 --- a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/IdempotentConsumer.java +++ /dev/null @@ -1,77 +0,0 @@ -package dev.caskeleton.messaging.inbox; - -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.reliability.InboxRepository; -import java.time.Instant; -import java.util.Objects; -import java.util.function.Supplier; - -/** - * Runs a handler's side effect at most once per message and consumer. - * - *

The reservation and the side effect must share one transaction. This class does not open that - * transaction itself — the caller supplies a runner that does — because the boundary belongs to the - * application's data access layer, and a nested or separate transaction here would silently break - * the guarantee while still looking correct. - * - *

A duplicate is not an error. It is the expected consequence of at-least-once delivery, so the - * skip path is a normal outcome rather than an exception. - */ -public final class IdempotentConsumer { - - private final InboxRepository inbox; - private final TransactionRunner transactions; - - /** - * Creates an idempotent consumer. - * - * @param inbox the inbox storage - * @param transactions runs work inside one database transaction - */ - public IdempotentConsumer(InboxRepository inbox, TransactionRunner transactions) { - this.inbox = Objects.requireNonNull(inbox, "inbox must not be null"); - this.transactions = Objects.requireNonNull(transactions, "transactions must not be null"); - } - - /** - * Runs the side effect unless this message was already processed. - * - * @param the side effect's result type - * @param messageId the logical message identity - * @param consumerId the consumer's stable identity - * @param now the current instant - * @param sideEffect the business work - * @return the outcome, including whether the work ran - */ - public InboxOutcome runOnce( - MessageId messageId, String consumerId, Instant now, Supplier sideEffect) { - Objects.requireNonNull(messageId, "messageId must not be null"); - Objects.requireNonNull(sideEffect, "sideEffect must not be null"); - Objects.requireNonNull(now, "now must not be null"); - if (consumerId == null || consumerId.isBlank()) { - throw new IllegalArgumentException("consumerId must not be blank"); - } - - return transactions.inTransaction( - () -> { - if (!inbox.reserve(messageId, consumerId, now)) { - return InboxOutcome.duplicate(); - } - return InboxOutcome.processed(sideEffect.get()); - }); - } - - /** Runs work inside exactly one database transaction. */ - @FunctionalInterface - public interface TransactionRunner { - - /** - * Runs the supplied work in a transaction and returns its result. - * - * @param the result type - * @param work the work to run - * @return the work's result - */ - T inTransaction(Supplier work); - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxCleanupJob.java b/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxCleanupJob.java deleted file mode 100644 index 6baceae9..00000000 --- a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxCleanupJob.java +++ /dev/null @@ -1,65 +0,0 @@ -package dev.caskeleton.messaging.inbox; - -import dev.caskeleton.messaging.reliability.InboxRepository; -import java.time.Instant; -import java.util.Objects; - -/** - * Deletes inbox rows that are older than the retention policy allows. - * - *

Deletes in bounded batches. A single unbounded {@code DELETE} over a table that has been - * accumulating for weeks holds locks long enough to block the very reservations the inbox exists to - * serve, so the cleanup would cause the outage it is meant to prevent. - * - *

The policy is validated before the first deletion. Running a cleanup under a retention that is - * shorter than the redelivery window would actively create the duplicate-processing bug, so the job - * refuses to start rather than dutifully deleting the rows. - */ -public final class InboxCleanupJob { - - /** How many rows one pass deletes before yielding. */ - public static final int DEFAULT_BATCH_SIZE = 1_000; - - private final InboxRepository inbox; - private final InboxRetentionPolicy policy; - private final int maxBatches; - - /** - * Creates a cleanup job. - * - * @param inbox the inbox storage - * @param policy the retention policy - * @param maxBatches how many batches one run may delete - */ - public InboxCleanupJob(InboxRepository inbox, InboxRetentionPolicy policy, int maxBatches) { - this.inbox = Objects.requireNonNull(inbox, "inbox must not be null"); - this.policy = Objects.requireNonNull(policy, "policy must not be null"); - if (maxBatches < 1) { - throw new IllegalArgumentException("maxBatches must be at least 1"); - } - this.maxBatches = maxBatches; - policy.validate(); - } - - /** - * Deletes expired rows, up to the configured batch ceiling. - * - * @param now the current instant - * @return how many rows were removed - */ - public int runOnce(Instant now) { - Objects.requireNonNull(now, "now must not be null"); - Instant cutoff = policy.cutoff(now); - - int removed = 0; - for (int batch = 0; batch < maxBatches; batch++) { - int deleted = inbox.purgeProcessedBefore(cutoff, DEFAULT_BATCH_SIZE); - removed += deleted; - // A short batch means the backlog is drained; continuing would just re-scan an empty range. - if (deleted < DEFAULT_BATCH_SIZE) { - break; - } - } - return removed; - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java b/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java deleted file mode 100644 index 0bd0055a..00000000 --- a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java +++ /dev/null @@ -1,136 +0,0 @@ -package dev.caskeleton.messaging.inbox; - -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.delivery.HandleResult; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import java.time.Instant; -import java.util.Objects; -import java.util.Set; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionException; -import java.util.concurrent.CompletionStage; -import java.util.function.Supplier; - -/** - * Runs a {@link MessageHandler} at most once per message and consumer, inside the inbox - * reservation's transaction. - * - *

It is a {@code MessageHandler} itself, so the consume path has one contract. It replaced an - * {@code IdempotentMessageHandler} with a different signature that nothing called (S7-#2): the - * platform wraps a handler in this when the destination's profile declares {@code - * INBOX_TRANSACTIONAL}, and the handler does not change. - * - *

The reservation and the handler's side effect commit together or not at all: - * - *

- * - *

The handler's stage is awaited on the calling thread, inside the transaction. A handler that - * hands its write to another thread writes outside the transaction, and the inbox cannot protect - * that write. - * - * @param the payload type - */ -public final class InboxMessageHandler implements MessageHandler { - - private final MessageHandler delegate; - private final IdempotentConsumer inbox; - private final String consumerName; - private final Supplier clock; - - /** - * Wraps a handler. - * - * @param delegate the business handler - * @param inbox the reservation-and-effect runner - * @param consumerName the consumer identity the reservation is keyed on - * @param clock supplies the reservation instant - */ - public InboxMessageHandler( - MessageHandler delegate, - IdempotentConsumer inbox, - String consumerName, - Supplier clock) { - this.delegate = Objects.requireNonNull(delegate, "delegate must not be null"); - this.inbox = Objects.requireNonNull(inbox, "inbox must not be null"); - this.clock = Objects.requireNonNull(clock, "clock must not be null"); - if (consumerName == null || consumerName.isBlank()) { - throw new IllegalArgumentException("consumerName must not be blank"); - } - this.consumerName = consumerName; - } - - @Override - public MessageDestination destination() { - return delegate.destination(); - } - - @Override - public Set schemaVersions() { - return delegate.schemaVersions(); - } - - @Override - public CompletionStage handle(MessageDelivery delivery) { - Objects.requireNonNull(delivery, "delivery must not be null"); - try { - InboxOutcome outcome = - inbox.runOnce( - delivery.message().messageId(), - consumerName, - clock.get(), - () -> { - HandleResult result = answerOf(delivery); - if (!(result instanceof HandleResult.Success)) { - // Thrown, not returned: the runner rolls back only on a throw, and a reservation - // that commits without its effect suppresses the redelivery that would apply it. - throw new NotAppliedException(result); - } - return result; - }); - return CompletableFuture.completedFuture(outcome.result().orElseGet(HandleResult::success)); - } catch (NotAppliedException notApplied) { - return CompletableFuture.completedFuture(notApplied.result); - } catch (RuntimeException failed) { - return CompletableFuture.failedFuture(failed); - } - } - - private HandleResult answerOf(MessageDelivery delivery) { - CompletionStage stage = delegate.handle(delivery); - if (stage == null) { - throw new IllegalStateException("the handler returned no stage"); - } - try { - HandleResult result = stage.toCompletableFuture().join(); - if (result == null) { - throw new IllegalStateException("the handler returned no result"); - } - return result; - } catch (CompletionException failed) { - throw failed.getCause() instanceof RuntimeException cause ? cause : failed; - } - } - - /** Carries a non-success answer out of the transaction so it rolls back. */ - private static final class NotAppliedException extends RuntimeException { - - private static final long serialVersionUID = 1L; - - @SuppressWarnings("serial") - private final transient HandleResult result; - - private NotAppliedException(HandleResult result) { - super(null, null, false, false); - this.result = result; - } - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxOutcome.java b/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxOutcome.java deleted file mode 100644 index cd7ddbed..00000000 --- a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxOutcome.java +++ /dev/null @@ -1,34 +0,0 @@ -package dev.caskeleton.messaging.inbox; - -import java.util.Optional; - -/** - * Whether a message's side effect ran or was suppressed as a duplicate. - * - * @param the side effect's result type - * @param processed true when the side effect ran for the first time - * @param result the side effect's result, absent for a duplicate - */ -public record InboxOutcome(boolean processed, Optional result) { - - /** - * Returns an outcome for a first-time delivery. - * - * @param the result type - * @param value the side effect's result - * @return the processed outcome - */ - public static InboxOutcome processed(T value) { - return new InboxOutcome<>(true, Optional.ofNullable(value)); - } - - /** - * Returns an outcome for a suppressed duplicate. - * - * @param the result type - * @return the duplicate outcome - */ - public static InboxOutcome duplicate() { - return new InboxOutcome<>(false, Optional.empty()); - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxRetentionPolicy.java b/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxRetentionPolicy.java deleted file mode 100644 index ccafcaf1..00000000 --- a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxRetentionPolicy.java +++ /dev/null @@ -1,78 +0,0 @@ -package dev.caskeleton.messaging.inbox; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.time.Duration; -import java.time.Instant; -import java.util.Objects; - -/** - * How long inbox rows are kept, and the rule that makes the number safe. - * - *

Retention must exceed the broker's maximum redelivery window. That is not a tuning preference: - * a row pruned while the broker can still redeliver its message turns the inbox into a no-op for - * exactly that message, and the side effect runs a second time. The failure is silent, rare, and - * only happens under the conditions that already made the day bad. - * - *

The safety margin is multiplicative rather than additive so that it scales with the window - * itself. A stream whose redelivery window is measured in days needs more slack than one measured - * in minutes, for the same reason: the estimate of that window is proportionally less certain. - * - * @param retention how long a processed row is kept - * @param maximumRedeliveryWindow the longest the broker may redelivery a message - */ -public record InboxRetentionPolicy(Duration retention, Duration maximumRedeliveryWindow) { - - /** How much longer than the redelivery window retention must be. */ - public static final double REQUIRED_SAFETY_FACTOR = 2.0; - - /** The default for a broker whose redelivery window is bounded by a one-day log retention. */ - public static final Duration DEFAULT_RETENTION = Duration.ofDays(7); - - public InboxRetentionPolicy { - Objects.requireNonNull(retention, "retention must not be null"); - Objects.requireNonNull(maximumRedeliveryWindow, "maximumRedeliveryWindow must not be null"); - if (retention.isNegative() || retention.isZero()) { - throw new IllegalArgumentException("retention must be positive"); - } - if (maximumRedeliveryWindow.isNegative() || maximumRedeliveryWindow.isZero()) { - throw new IllegalArgumentException("maximumRedeliveryWindow must be positive"); - } - } - - /** - * Refuses a retention that could prune a row the broker can still redeliver. - * - * @throws MessagingConfigurationException when retention is too short - */ - public void validate() { - Duration required = required(); - if (retention.compareTo(required) < 0) { - throw new MessagingConfigurationException( - "INBOX_RETENTION_TOO_SHORT", - "inbox retention of %s is below the %s required for a %s redelivery window; a pruned row" - .formatted(retention, required, maximumRedeliveryWindow) - + " lets a late redelivery apply its effect twice"); - } - } - - /** - * Returns the shortest retention this redelivery window allows. - * - * @return the minimum safe retention - */ - public Duration required() { - return Duration.ofMillis( - Math.round(maximumRedeliveryWindow.toMillis() * REQUIRED_SAFETY_FACTOR)); - } - - /** - * Returns the cutoff before which rows may be deleted. - * - * @param now the current instant - * @return the retention cutoff - */ - public Instant cutoff(Instant now) { - Objects.requireNonNull(now, "now must not be null"); - return now.minus(retention); - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxCleanupJob.java b/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxCleanupJob.java deleted file mode 100644 index 5d067bd0..00000000 --- a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxCleanupJob.java +++ /dev/null @@ -1,62 +0,0 @@ -package dev.caskeleton.messaging.outbox; - -import dev.caskeleton.messaging.reliability.OutboxRepository; -import java.time.Instant; -import java.util.Objects; - -/** - * Deletes published outbox rows once they are past their retention. - * - *

Only {@code PUBLISHED} rows are eligible, and that restriction is the whole safety story. An - * {@code AMBIGUOUS} row is a message that may or may not have reached the broker; deleting it - * destroys the only record that it was ever meant to be sent. A {@code FAILED} row is the audit - * trail of a message that never went out. Both are the rows an operator most needs during an - * incident, which is exactly when a time-based sweep would otherwise remove them. - */ -public final class OutboxCleanupJob { - - /** How many rows one delete statement removes before yielding. */ - public static final int DEFAULT_BATCH_SIZE = 1_000; - - private final OutboxRepository outbox; - private final OutboxProperties properties; - private final int maxBatches; - - /** - * Creates a cleanup job. - * - * @param outbox the outbox storage - * @param properties the relay settings supplying the retention - * @param maxBatches how many delete batches one run may issue - */ - public OutboxCleanupJob(OutboxRepository outbox, OutboxProperties properties, int maxBatches) { - this.outbox = Objects.requireNonNull(outbox, "outbox must not be null"); - this.properties = Objects.requireNonNull(properties, "properties must not be null"); - if (maxBatches < 1) { - throw new IllegalArgumentException("maxBatches must be at least 1"); - } - this.maxBatches = maxBatches; - } - - /** - * Deletes expired published rows. - * - * @param now the current instant - * @return how many rows were removed - */ - public int runOnce(Instant now) { - Objects.requireNonNull(now, "now must not be null"); - Instant cutoff = now.minus(properties.retentionAfterPublish()); - - int removed = 0; - for (int batch = 0; batch < maxBatches; batch++) { - int deleted = outbox.purgePublishedBefore(cutoff, DEFAULT_BATCH_SIZE); - removed += deleted; - // A short batch means the backlog is drained; asking again would re-scan an empty range. - if (deleted < DEFAULT_BATCH_SIZE) { - break; - } - } - return removed; - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxEnvelopeFactory.java b/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxEnvelopeFactory.java deleted file mode 100644 index 1e3750c6..00000000 --- a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxEnvelopeFactory.java +++ /dev/null @@ -1,124 +0,0 @@ -package dev.caskeleton.messaging.outbox; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.ProducerId; -import dev.caskeleton.messaging.api.SchemaVersion; -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.reliability.OutboxCanonicalMetadata; -import dev.caskeleton.messaging.reliability.OutboxRecord; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.schema.SchemaReference; -import java.net.URI; -import java.util.LinkedHashMap; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; - -/** - * Rebuilds a publishable envelope from an outbox row. - * - *

The identity comes from the row, never from a fresh mint. That is what makes a retry after an - * ambiguous publish safe: the broker's deduplication, or the consumer's Inbox, sees the same id and - * collapses the duplicate. - * - *

So does everything else the envelope carries. This used to rebuild correlation, causation, - * tenant, trace and the schema reference as empty, and read the routing keys out of the row's - * header map — so a message that travelled through the outbox reached its consumer with less - * provenance than one published directly, and the publish path became part of the message's - * meaning. The row now has columns for those facts and this reads them. - * - *

Reserved header names in the row are refused outright, with no exception for the routing keys. - * They had one, because the keys had nowhere else to live; a row could therefore write {@code - * msg.partition-key} and the same code path would have accepted {@code msg.id} if the check had - * been one line looser. Now that the keys are columns, the rule is the simple one: an outbox row - * cannot write into the platform's namespace at all. - */ -public final class OutboxEnvelopeFactory { - - private final ProducerId producer; - - /** - * Creates a factory for one service. - * - * @param producer the logical producing service, used for rows that name none - */ - public OutboxEnvelopeFactory(ProducerId producer) { - this.producer = Objects.requireNonNull(producer, "producer must not be null"); - } - - /** - * Builds the envelope for one outbox row. - * - * @param record the outbox row - * @return the encoded envelope - */ - public MessageEnvelope toEnvelope(OutboxRecord record) { - Objects.requireNonNull(record, "record must not be null"); - - Map headers = new LinkedHashMap<>(); - record - .headers() - .forEach( - (name, value) -> { - // The row's headers are application data. Promoting them straight into - // MessageHeaders.platform let a row carrying `msg.id` or `msg.type` reach the wire - // as if the platform had written it — and the consumer trusts the last such header, - // so a forged identity lands in another message's inbox deduplication. - if (ReservedHeaders.isReserved(name)) { - throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException( - "RESERVED_HEADER_IN_OUTBOX_ROW", - "outbox row header '" - + name - + "' uses the reserved namespace; canonical identity and metadata come from" - + " the record's own columns, not from its header map"); - } - headers.put(new HeaderName(name), new HeaderValue(value)); - }); - - OutboxCanonicalMetadata metadata = record.metadata(); - return new MessageEnvelope<>( - record.messageId(), - record.messageType(), - record.schemaVersion(), - record.createdAt(), - // The write instant stands in when the row records no separate occurrence. It is the - // closest true statement available: the business transaction that wrote the row is the one - // the fact occurred in. - Optional.of(metadata.occurredAt().orElse(record.createdAt())), - // A row written before the producer column existed names none, and the service that owns - // this relay is the only producer it can honestly be attributed to. - metadata.producer().orElse(producer), - metadata.correlationId(), - metadata.causationId(), - record.contentType(), - metadata.partitionKey(), - metadata.orderingKey(), - metadata.tenant(), - metadata.traceContext(), - MessageHeaders.platform(headers), - new EncodedMessage( - record.payload(), record.contentType(), schemaReference(record, metadata))); - } - - /** - * Rebuilds the schema reference from the row's subject, the row's version, and its location. - * - *

The version is the row's {@code schema_version} column rather than a third copy of the same - * number: a reference whose version could disagree with the column the relay filters on is a - * reference nobody can trust. - */ - private static Optional schemaReference( - OutboxRecord record, OutboxCanonicalMetadata metadata) { - return metadata - .schemaSubject() - .map( - subject -> - new SchemaReference( - subject, - new SchemaVersion(record.schemaVersion().value()), - metadata.schemaUri().map(URI::create))); - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxProperties.java b/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxProperties.java deleted file mode 100644 index 56f4f5ff..00000000 --- a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxProperties.java +++ /dev/null @@ -1,81 +0,0 @@ -package dev.caskeleton.messaging.outbox; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.time.Duration; -import java.util.Objects; - -/** - * The relay's operational settings, and the relationships between them that have to hold. - * - *

The lease duration is the dangerous one. If it is shorter than the time a publish can take, a - * second relay claims the row while the first is still waiting for a confirm, and the message is - * published twice — under the same id, so consumers with an inbox survive it, but consumers without - * one do not. The constructor therefore requires the lease to exceed the publish timeout by a - * margin rather than merely to be positive. - * - * @param batchSize how many records one lease claims - * @param leaseDuration how long a claim holds - * @param publishTimeout the deadline for one publish - * @param pollInterval how often the relay looks for work - * @param retentionAfterPublish how long published rows are kept before deletion - * @param maxAttempts how many times a record is retried before it is parked - */ -public record OutboxProperties( - int batchSize, - Duration leaseDuration, - Duration publishTimeout, - Duration pollInterval, - Duration retentionAfterPublish, - int maxAttempts) { - - /** How much longer than the publish timeout a lease must be. */ - public static final double REQUIRED_LEASE_FACTOR = 2.0; - - public OutboxProperties { - Objects.requireNonNull(leaseDuration, "leaseDuration must not be null"); - Objects.requireNonNull(publishTimeout, "publishTimeout must not be null"); - Objects.requireNonNull(pollInterval, "pollInterval must not be null"); - Objects.requireNonNull(retentionAfterPublish, "retentionAfterPublish must not be null"); - if (batchSize < 1) { - throw new IllegalArgumentException("batchSize must be at least 1"); - } - if (maxAttempts < 1) { - throw new IllegalArgumentException("maxAttempts must be at least 1"); - } - requirePositive(leaseDuration, "leaseDuration"); - requirePositive(publishTimeout, "publishTimeout"); - requirePositive(pollInterval, "pollInterval"); - requirePositive(retentionAfterPublish, "retentionAfterPublish"); - - Duration minimumLease = - Duration.ofMillis(Math.round(publishTimeout.toMillis() * REQUIRED_LEASE_FACTOR)); - if (leaseDuration.compareTo(minimumLease) < 0) { - throw new MessagingConfigurationException( - "OUTBOX_LEASE_TOO_SHORT", - "a lease of %s can expire while a %s publish is still in flight, letting a second relay" - .formatted(leaseDuration, publishTimeout) - + " publish the same record; the minimum is %s".formatted(minimumLease)); - } - } - - /** - * Returns settings suited to a single relay against a healthy broker. - * - * @return the default properties - */ - public static OutboxProperties defaults() { - return new OutboxProperties( - 100, - Duration.ofSeconds(30), - Duration.ofSeconds(5), - Duration.ofMillis(500), - Duration.ofDays(3), - 10); - } - - private static void requirePositive(Duration value, String field) { - if (value.isNegative() || value.isZero()) { - throw new IllegalArgumentException(field + " must be positive"); - } - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelay.java b/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelay.java deleted file mode 100644 index ae4c3bb6..00000000 --- a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelay.java +++ /dev/null @@ -1,267 +0,0 @@ -package dev.caskeleton.messaging.outbox; - -import dev.caskeleton.messaging.api.MessageEnvelope; -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.MessagingException; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.reliability.OutboxLease; -import dev.caskeleton.messaging.reliability.OutboxRecord; -import dev.caskeleton.messaging.reliability.OutboxRepository; -import dev.caskeleton.messaging.reliability.OutboxTransitionResult; -import dev.caskeleton.messaging.schema.EncodedMessage; -import java.time.Duration; -import java.time.Instant; -import java.util.List; -import java.util.Objects; - -/** - * Publishes outbox rows, treating an unknown outcome as retryable rather than final. - * - *

The relay's correctness rests on one rule: an ambiguous publish is retried under the same - * message id. Minting a new id would turn a possibly-delivered message into a - * definitely-second message, and no downstream deduplication could recover from it. Marking it - * failed instead would lose a message the broker may already hold. - * - *

The relay therefore guarantees at-least-once publication and nothing more. Effectively-once - * downstream effects come from pairing it with an Inbox — which is why the platform never - * advertises the outbox as exactly-once. - */ -public final class OutboxRelay { - - private final OutboxRepository repository; - private final MessagePublisher publisher; - private final OutboxEnvelopeFactory envelopeFactory; - private final int batchSize; - - private final String owner; - - private final OutboxRetryScheduler scheduler; - - private static String defaultOwner() { - return java.lang.ProcessHandle.current().pid() - + "@" - + java.util.UUID.randomUUID().toString().substring(0, 8); - } - - private final Duration leaseDuration; - - /** - * Creates a relay. - * - * @param repository the outbox storage - * @param publisher the platform publisher - * @param envelopeFactory rebuilds envelopes from rows - * @param batchSize how many rows to claim per pass - * @param leaseDuration how long a claim holds - */ - public OutboxRelay( - OutboxRepository repository, - MessagePublisher publisher, - OutboxEnvelopeFactory envelopeFactory, - int batchSize, - Duration leaseDuration) { - this(repository, publisher, envelopeFactory, batchSize, leaseDuration, defaultOwner()); - } - - /** - * A relay with an explicit owner identity. - * - *

The owner is half of the fencing predicate. It defaults to something stable per process - * rather than per object, because two relays in one JVM sharing an owner would each be able to - * overwrite the other's terminal writes — the exact failure the token exists to prevent. - */ - public OutboxRelay( - OutboxRepository repository, - MessagePublisher publisher, - OutboxEnvelopeFactory envelopeFactory, - int batchSize, - Duration leaseDuration, - String owner) { - this( - repository, - publisher, - envelopeFactory, - batchSize, - leaseDuration, - owner, - OutboxRetryScheduler.standard()); - } - - /** - * A relay with an explicit retry policy and a process-derived owner. - * - * @param repository the outbox storage - * @param publisher the platform publisher - * @param envelopeFactory rebuilds envelopes from rows - * @param batchSize how many rows to claim per pass - * @param leaseDuration how long a claim holds - * @param scheduler the retry policy - */ - public OutboxRelay( - OutboxRepository repository, - MessagePublisher publisher, - OutboxEnvelopeFactory envelopeFactory, - int batchSize, - Duration leaseDuration, - OutboxRetryScheduler scheduler) { - this( - repository, - publisher, - envelopeFactory, - batchSize, - leaseDuration, - defaultOwner(), - scheduler); - } - - /** - * A relay with an explicit retry policy. - * - *

The scheduler was built by the auto-configuration and handed to nobody: the relay claimed - * every ambiguous row on the next pass regardless of its attempt count, so the configured budget - * of ten attempts was a number nothing read. - */ - public OutboxRelay( - OutboxRepository repository, - MessagePublisher publisher, - OutboxEnvelopeFactory envelopeFactory, - int batchSize, - Duration leaseDuration, - String owner, - OutboxRetryScheduler scheduler) { - this.owner = Objects.requireNonNull(owner, "owner must not be null"); - this.scheduler = Objects.requireNonNull(scheduler, "scheduler must not be null"); - this.repository = Objects.requireNonNull(repository, "repository must not be null"); - this.publisher = Objects.requireNonNull(publisher, "publisher must not be null"); - this.envelopeFactory = - Objects.requireNonNull(envelopeFactory, "envelopeFactory must not be null"); - this.leaseDuration = Objects.requireNonNull(leaseDuration, "leaseDuration must not be null"); - if (batchSize < 1) { - throw new IllegalArgumentException("batchSize must be at least 1"); - } - this.batchSize = batchSize; - } - - /** - * Runs one relay pass. - * - * @param now the current instant - * @return what the pass did - */ - public OutboxRelayReport runOnce(Instant now) { - Objects.requireNonNull(now, "now must not be null"); - // The claim carries an owner and a fencing token, and every write - // below is conditioned on them. Without that, a relay that stalled past its lease could record - // AMBIGUOUS over the PUBLISHED another relay had already written, making a confirmed message - // claimable again. - List batch = - repository.claimBatch(owner, batchSize, leaseDuration, now, scheduler.maxAttempts()); - - int published = 0; - int ambiguous = 0; - int failed = 0; - int stale = 0; - int exhausted = 0; - - for (OutboxLease lease : batch) { - OutboxRecord record = lease.record(); - MessageEnvelope envelope; - try { - envelope = envelopeFactory.toEnvelope(record); - } catch (RuntimeException unpublishable) { - // A row that cannot become an envelope never will. Thrown out of the pass, it took the - // rest of the batch with it: those rows stayed IN_FLIGHT until their lease expired, and the - // same row was claimed and thrown again on the next pass, forever. - if (repository.markFailed(lease, failureCode(unpublishable), now) - == OutboxTransitionResult.APPLIED) { - failed++; - } else { - stale++; - } - continue; - } - PublishResult result = publish(record, envelope); - switch (result.completion()) { - case CONFIRMED -> { - if (repository.markPublished(lease, now) == OutboxTransitionResult.APPLIED) { - published++; - } else { - stale++; - } - } - case AMBIGUOUS -> { - String code = result.failure().map(failure -> failure.code()).orElse("AMBIGUOUS"); - // The attempt this pass just spent. The claim predicate and the row both count attempts - // after the transition, so the budget has to be judged on the same number the next claim - // will read, or the last attempt is spent twice. - int spent = record.attempts() + 1; - OutboxTransitionResult transition = - scheduler - .parkReason(spent) - // A row that has spent its budget without an answer is parked under its own - // status. Leaving it AMBIGUOUS makes it a row the claim predicate silently skips - // forever, which looks identical to a healthy backlog on every dashboard. - .map(reason -> repository.markExhausted(lease, reason, now)) - .orElseGet( - () -> - repository.markAmbiguous( - lease, code, now, scheduler.nextAttemptAt(now, spent))); - if (transition == OutboxTransitionResult.APPLIED) { - if (scheduler.isExhausted(spent)) { - exhausted++; - } else { - ambiguous++; - } - } else { - stale++; - } - } - case REJECTED -> { - if (repository.markFailed( - lease, result.failure().map(failure -> failure.code()).orElse("REJECTED"), now) - == OutboxTransitionResult.APPLIED) { - failed++; - } else { - stale++; - } - } - // Unreachable while PublishCompletion has exactly these constants. Present so that a new - // completion fails loudly rather than leaving the row IN_FLIGHT with its lease ticking — - // which would look like a stalled relay rather than an unhandled case. - default -> - throw new IllegalStateException("unhandled publish completion: " + result.completion()); - } - } - return new OutboxRelayReport(batch.size(), published, ambiguous, failed, stale, exhausted); - } - - private PublishResult publish(OutboxRecord record, MessageEnvelope envelope) { - MessageDestination destination = - new MessageDestination<>(record.destination(), record.messageType(), EncodedMessage.class); - try { - return publisher - .publish(destination, envelope, PublishOptions.defaults()) - .toCompletableFuture() - .join(); - } catch (RuntimeException unknown) { - // An exception says nothing about whether the broker took the message, so the row is retried - // under the same id like any other unknown outcome — not failed, not left IN_FLIGHT. - return PublishResult.ambiguous( - Duration.ZERO, - FailureDescriptor.of( - FailureCategory.AMBIGUOUS, - "PUBLISH_OUTCOME_UNKNOWN", - "the publisher threw " + unknown.getClass().getSimpleName())); - } - } - - private static String failureCode(RuntimeException failure) { - return failure instanceof MessagingException known - ? known.failure().code() - : "OUTBOX_ROW_UNPUBLISHABLE"; - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelayReport.java b/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelayReport.java deleted file mode 100644 index d91d3f73..00000000 --- a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelayReport.java +++ /dev/null @@ -1,50 +0,0 @@ -package dev.caskeleton.messaging.outbox; - -/** - * What one relay pass did. - * - *

Ambiguous rows are counted separately from failures because they mean something operationally - * different: a rising ambiguous count is a broker confirmation problem, while a rising failed count - * is a contract or topology problem. - * - *

{@code staleLeases} is the count of terminal writes this pass could not apply because another - * relay had already taken the row. It is not an error and it is not a success: it means this worker - * published something whose outcome another worker has already recorded, so a non-zero value is the - * visible form of a duplicate publication. - * - *

{@code exhausted} is counted apart from {@code failed} for the same reason: a rejected row is - * a message the broker refused and an exhausted one is a message nobody ever answered for. The - * first needs a fix, the second needs a redrive, and a single counter for both tells an operator - * neither. - * - * @param leased how many rows were claimed - * @param published how many were confirmed - * @param ambiguous how many had an unknown outcome and stay retryable - * @param failed how many were definitively rejected - * @param staleLeases how many terminal writes were refused because the lease had been superseded - * @param exhausted how many spent their attempt budget without a confirmation and were parked - */ -public record OutboxRelayReport( - int leased, int published, int ambiguous, int failed, int staleLeases, int exhausted) { - - public OutboxRelayReport { - if (leased < 0 - || published < 0 - || ambiguous < 0 - || failed < 0 - || staleLeases < 0 - || exhausted < 0) { - throw new IllegalArgumentException("relay counters must not be negative"); - } - } - - /** A report from a pass that parked nothing. */ - public OutboxRelayReport(int leased, int published, int ambiguous, int failed, int staleLeases) { - this(leased, published, ambiguous, failed, staleLeases, 0); - } - - /** A report from a pass that observed no stale leases. */ - public OutboxRelayReport(int leased, int published, int ambiguous, int failed) { - this(leased, published, ambiguous, failed, 0, 0); - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelayWorker.java b/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelayWorker.java deleted file mode 100644 index 5de58c6c..00000000 --- a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelayWorker.java +++ /dev/null @@ -1,206 +0,0 @@ -package dev.caskeleton.messaging.outbox; - -import java.time.Duration; -import java.time.Instant; -import java.util.Objects; -import java.util.concurrent.RejectedExecutionException; -import java.util.concurrent.ScheduledExecutorService; -import java.util.concurrent.ScheduledThreadPoolExecutor; -import java.util.concurrent.TimeUnit; -import java.util.concurrent.atomic.AtomicBoolean; -import java.util.concurrent.atomic.AtomicInteger; -import java.util.concurrent.atomic.AtomicLong; -import java.util.function.Supplier; - -/** - * Runs relay passes on the schedule the retry policy decides. - * - *

The relay, its retry scheduler and the attempt budget all existed and nothing ever called - * {@code runOnce}. An outbox whose relay is never driven is the worst shape of all: the business - * transaction commits its row and reports success, and the message is never published — a silent, - * unbounded backlog rather than a visible failure. - * - *

Passes are self-scheduled rather than run at a fixed rate. A fixed rate keeps firing while the - * broker is down, and the pass after an empty or failed one is exactly where the policy's backoff - * belongs; a pass that published something resets to the base interval because work is flowing. - * - *

One thread, and the next pass is scheduled only after the previous returns. Overlapping passes - * from one process would have two claims racing on the same rows, which the fencing predicate would - * then reject as stale — correct, but it is duplicate publishing work bought at the cost of a - * duplicate publish. - */ -public final class OutboxRelayWorker implements AutoCloseable { - - /** How long {@link #close()} waits for a running pass when no deadline is given. */ - public static final Duration DEFAULT_DRAIN_DEADLINE = Duration.ofSeconds(30); - - private static final System.Logger LOG = System.getLogger(OutboxRelayWorker.class.getName()); - - private final OutboxRelay relay; - - private final OutboxRetryScheduler scheduler; - - private final Supplier clock; - - private final ScheduledExecutorService passes; - - private final AtomicBoolean running = new AtomicBoolean(); - - private final AtomicInteger unproductivePasses = new AtomicInteger(); - - private final AtomicLong completedPasses = new AtomicLong(); - - private final AtomicLong failedPasses = new AtomicLong(); - - /** - * Creates a worker driving one relay. - * - * @param relay the relay to run - * @param scheduler the policy deciding when the next pass runs - */ - public OutboxRelayWorker(OutboxRelay relay, OutboxRetryScheduler scheduler) { - this(relay, scheduler, Instant::now); - } - - /** - * Creates a worker with an explicit clock, so a pass can be driven without waiting on wall time. - * - * @param relay the relay to run - * @param scheduler the policy deciding when the next pass runs - * @param clock the source of the current instant - */ - public OutboxRelayWorker( - OutboxRelay relay, OutboxRetryScheduler scheduler, Supplier clock) { - this.relay = Objects.requireNonNull(relay, "relay must not be null"); - this.scheduler = Objects.requireNonNull(scheduler, "scheduler must not be null"); - this.clock = Objects.requireNonNull(clock, "clock must not be null"); - ScheduledThreadPoolExecutor executor = - new ScheduledThreadPoolExecutor( - 1, - runnable -> { - // Daemon: a relay thread that outlives the application would keep publishing from a - // process that has already released its other resources. - Thread thread = new Thread(runnable, "messaging-outbox-relay"); - thread.setDaemon(true); - return thread; - }); - // A pass waiting out its backoff is dropped on shutdown rather than run afterwards. Left on, - // the default policy makes stop() wait for a pass that has not started and cannot do anything - // useful, so an orderly shutdown pays the whole poll interval before it can close. - executor.setExecuteExistingDelayedTasksAfterShutdownPolicy(false); - this.passes = executor; - } - - /** Starts driving passes. Idempotent: a second call does not add a second schedule. */ - public void start() { - if (running.compareAndSet(false, true)) { - schedule(Duration.ZERO); - } - } - - /** - * Stops scheduling and lets the pass that is already running finish. - * - *

Draining rather than interrupting is the whole point. A pass killed between its claim and - * its terminal write leaves rows {@code IN_FLIGHT} holding a lease, and nothing may touch them - * until that lease expires — so an orderly shutdown would produce exactly the stall that a crash - * produces. - * - * @param deadline how long to wait for the running pass - * @return true when the running pass finished inside the deadline - */ - public boolean stop(Duration deadline) { - Objects.requireNonNull(deadline, "deadline must not be null"); - running.set(false); - passes.shutdown(); - try { - if (passes.awaitTermination(deadline.toMillis(), TimeUnit.MILLISECONDS)) { - return true; - } - } catch (InterruptedException interrupted) { - Thread.currentThread().interrupt(); - } - // The deadline passed with a pass still running. Its rows stay leased until the lease expires, - // which is the outcome the deadline exists to bound rather than to prevent. - passes.shutdownNow(); - return false; - } - - @Override - public void close() { - stop(DEFAULT_DRAIN_DEADLINE); - } - - /** - * Reports whether the worker is scheduling passes. - * - * @return true between {@link #start()} and {@link #stop(Duration)} - */ - public boolean isRunning() { - return running.get(); - } - - /** - * Returns how many passes have finished, successfully or not. - * - * @return the completed pass count - */ - public long completedPasses() { - return completedPasses.get(); - } - - /** - * Returns how many passes ended in an exception. - * - * @return the failed pass count - */ - public long failedPasses() { - return failedPasses.get(); - } - - // The scheduled future is not kept: a pass reports nothing to a caller and handles its own - // failure below, so the only thing holding it would achieve is a reference that has to be - // cleaned up. - @SuppressWarnings("FutureReturnValueIgnored") - private void schedule(Duration delay) { - if (!running.get()) { - return; - } - try { - passes.schedule(this::runPass, Math.max(0, delay.toMillis()), TimeUnit.MILLISECONDS); - } catch (RejectedExecutionException stopping) { - // stop() shut the executor between the running check and the submission. There is nothing to - // schedule onto and nothing to report: the worker is stopping, which is what was asked for. - running.set(false); - } - } - - private void runPass() { - if (!running.get()) { - return; - } - int unproductive; - try { - OutboxRelayReport report = relay.runOnce(clock.get()); - unproductive = report.published() > 0 ? reset() : unproductivePasses.incrementAndGet(); - } catch (RuntimeException passFailed) { - // A failed pass must not stop the loop: the scheduled task's own exception would cancel every - // future pass, turning one broker error into a relay that never runs again. The failure is - // counted and the next pass backs off as if nothing was published, which is true. It is also - // logged: counted silently, a relay failing every pass looked exactly like an idle one. - long failures = failedPasses.incrementAndGet(); - unproductive = unproductivePasses.incrementAndGet(); - LOG.log( - System.Logger.Level.WARNING, - "outbox relay pass failed (" + failures + " failed so far); retrying with backoff", - passFailed); - } - completedPasses.incrementAndGet(); - schedule(scheduler.backoff(unproductive)); - } - - private int reset() { - unproductivePasses.set(0); - return 0; - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxRetryScheduler.java b/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxRetryScheduler.java deleted file mode 100644 index 65f234c3..00000000 --- a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxRetryScheduler.java +++ /dev/null @@ -1,134 +0,0 @@ -package dev.caskeleton.messaging.outbox; - -import java.time.Duration; -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; - -/** - * Decides when a relay's next pass should run, and when a record has retried enough. - * - *

The same curve serves two different jobs and neither replaces the other. Backing off the - * pass is what lets a broker recover: an outage fails every record in the batch for the - * same reason, so retrying the whole backlog on the poll interval achieves nothing but load. But a - * pass-level wait is process memory — it is forgotten on restart and each replica keeps its own — - * so eligibility also has to be written on the row, or the backlog is retried as fast as the - * unluckiest replica polls. - * - *

Jitter is applied deterministically from the attempt count rather than randomly. Several relay - * instances that all started at deployment time would otherwise synchronise their retries into a - * thundering herd, and a random source would make the schedule impossible to test. - */ -public final class OutboxRetryScheduler { - - private final Duration baseInterval; - private final Duration maxInterval; - private final int maxAttempts; - - /** - * Creates a scheduler from the relay properties. - * - * @param properties the relay settings - * @param maxInterval the longest backoff between passes - */ - public OutboxRetryScheduler(OutboxProperties properties, Duration maxInterval) { - Objects.requireNonNull(properties, "properties must not be null"); - Objects.requireNonNull(maxInterval, "maxInterval must not be null"); - if (maxInterval.compareTo(properties.pollInterval()) < 0) { - throw new IllegalArgumentException("maxInterval must not be shorter than the poll interval"); - } - this.baseInterval = properties.pollInterval(); - this.maxInterval = maxInterval; - this.maxAttempts = properties.maxAttempts(); - } - - /** - * Returns when the next pass should run. - * - *

A pass that published something resets to the base interval: work is flowing, so there is no - * reason to wait. - * - * @param now the current instant - * @param consecutiveEmptyOrFailedPasses how many passes in a row did no useful work - * @return the next pass instant - */ - public Instant nextPassAt(Instant now, int consecutiveEmptyOrFailedPasses) { - Objects.requireNonNull(now, "now must not be null"); - if (consecutiveEmptyOrFailedPasses < 0) { - throw new IllegalArgumentException("consecutiveEmptyOrFailedPasses must not be negative"); - } - return now.plus(backoff(consecutiveEmptyOrFailedPasses)); - } - - /** - * Returns when a row that has spent this many attempts may be claimed again. - * - *

Written onto the row rather than held in the relay, because a deadline that lives in process - * memory is forgotten on restart and computed independently by every replica — which turns a - * backoff into every worker re-publishing the same backlog as fast as it polls. - * - * @param now the current instant - * @param attempts how many attempts the row has spent - * @return the earliest instant the row is eligible again - */ - public Instant nextAttemptAt(Instant now, int attempts) { - Objects.requireNonNull(now, "now must not be null"); - if (attempts < 1) { - throw new IllegalArgumentException("a row that has been published once has spent an attempt"); - } - return now.plus(backoff(attempts)); - } - - /** The platform's default policy, for a relay whose caller did not supply one. */ - public static OutboxRetryScheduler standard() { - return new OutboxRetryScheduler(OutboxProperties.defaults(), java.time.Duration.ofMinutes(5)); - } - - /** The attempt budget a row may spend before it is parked. */ - public int maxAttempts() { - return maxAttempts; - } - - /** - * Returns the delay before the next pass. - * - * @param consecutiveEmptyOrFailedPasses how many passes in a row did no useful work - * @return the backoff delay - */ - public Duration backoff(int consecutiveEmptyOrFailedPasses) { - if (consecutiveEmptyOrFailedPasses <= 0) { - return baseInterval; - } - // Doubling, capped. Shifting rather than Math.pow so an unbounded counter cannot overflow into - // a negative duration on a long outage. - int exponent = Math.min(consecutiveEmptyOrFailedPasses, 20); - long scaled = baseInterval.toMillis() << exponent; - long capped = Math.min(scaled, maxInterval.toMillis()); - long jittered = capped - (capped / 8) * (exponent % 3); - return Duration.ofMillis(Math.max(baseInterval.toMillis(), jittered)); - } - - /** - * Reports whether a record has exhausted its attempt budget. - * - * @param attempts how many times the record has been published - * @return true when it should be parked rather than retried - */ - public boolean isExhausted(int attempts) { - return attempts >= maxAttempts; - } - - /** - * Returns the reason a record should be parked, when it should. - * - * @param attempts how many times the record has been published - * @return the sanitized reason, or empty when the record may still retry - */ - public Optional parkReason(int attempts) { - return isExhausted(attempts) - ? Optional.of( - "the record reached its %d attempt budget without a confirmed publish" - .formatted(maxAttempts)) - : Optional.empty(); - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/IdempotentConsumerTest.java b/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/IdempotentConsumerTest.java deleted file mode 100644 index b4331a66..00000000 --- a/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/IdempotentConsumerTest.java +++ /dev/null @@ -1,140 +0,0 @@ -package dev.caskeleton.messaging.inbox; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.reliability.InboxRepository; -import java.time.Instant; -import java.util.LinkedHashSet; -import java.util.Set; -import java.util.concurrent.atomic.AtomicInteger; -import java.util.function.Supplier; -import org.junit.jupiter.api.Test; - -class IdempotentConsumerTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - private final InMemoryInbox inbox = new InMemoryInbox(); - private final SingleTransactionRunner transactions = new SingleTransactionRunner(); - private final IdempotentConsumer consumer = new IdempotentConsumer(inbox, transactions); - - @Test - void theFirstDeliveryRunsTheSideEffect() { - AtomicInteger effects = new AtomicInteger(); - MessageId messageId = MessageId.newId(); - - InboxOutcome outcome = - consumer.runOnce(messageId, "order-projection", NOW, effects::incrementAndGet); - - assertThat(outcome.processed()).isTrue(); - assertThat(outcome.result()).hasValue(1); - assertThat(effects.get()).isEqualTo(1); - } - - @Test - void aRedeliverySkipsTheSideEffect() { - AtomicInteger effects = new AtomicInteger(); - MessageId messageId = MessageId.newId(); - - consumer.runOnce(messageId, "order-projection", NOW, effects::incrementAndGet); - InboxOutcome second = - consumer.runOnce(messageId, "order-projection", NOW, effects::incrementAndGet); - - assertThat(second.processed()).isFalse(); - assertThat(second.result()).isEmpty(); - assertThat(effects.get()).isEqualTo(1); - } - - @Test - void twoConsumersEachProcessTheSameMessageOnce() { - AtomicInteger effects = new AtomicInteger(); - MessageId messageId = MessageId.newId(); - - consumer.runOnce(messageId, "order-projection", NOW, effects::incrementAndGet); - InboxOutcome other = - consumer.runOnce(messageId, "billing-projection", NOW, effects::incrementAndGet); - - assertThat(other.processed()).isTrue(); - assertThat(effects.get()).isEqualTo(2); - } - - @Test - void theReservationAndTheSideEffectShareOneTransaction() { - MessageId messageId = MessageId.newId(); - - consumer.runOnce(messageId, "order-projection", NOW, () -> transactions.depthDuringWork); - - assertThat(transactions.transactions).isEqualTo(1); - assertThat(transactions.depthDuringWork).isEqualTo(1); - } - - @Test - void aProcessedMessageIsVisibleToTheRepositoryQuery() { - MessageId messageId = MessageId.newId(); - consumer.runOnce(messageId, "order-projection", NOW, () -> "done"); - - assertThat(inbox.isProcessed(messageId, "order-projection")).isTrue(); - assertThat(inbox.isProcessed(messageId, "billing-projection")).isFalse(); - } - - @Test - void retentionPruningRemovesOldRows() { - consumer.runOnce(MessageId.newId(), "order-projection", NOW, () -> "done"); - - assertThat(inbox.purgeProcessedBefore(NOW.plusSeconds(1), 100)).isEqualTo(1); - assertThat(inbox.size()).isZero(); - } -} - -/** A deterministic inbox with the composite-key uniqueness the pattern relies on. */ -final class InMemoryInbox implements InboxRepository { - - private final Set reserved = new LinkedHashSet<>(); - - @Override - public boolean reserve(MessageId messageId, String consumerId, Instant now) { - return reserved.add(key(messageId, consumerId)); - } - - @Override - public boolean isProcessed(MessageId messageId, String consumerId) { - return reserved.contains(key(messageId, consumerId)); - } - - @Override - public int purgeProcessedBefore(Instant processedBefore, int limit) { - int removed = Math.min(reserved.size(), limit); - reserved.clear(); - return removed; - } - - int size() { - return reserved.size(); - } - - private static String key(MessageId messageId, String consumerId) { - return messageId.value() + "|" + consumerId; - } -} - -/** Records how many transactions were opened and how deeply they nested. */ -final class SingleTransactionRunner implements IdempotentConsumer.TransactionRunner { - - int transactions; - int depthDuringWork; - - private int depth; - - @Override - public T inTransaction(Supplier work) { - transactions++; - depth++; - try { - depthDuringWork = depth; - return work.get(); - } finally { - depth--; - } - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/InboxMessageHandlerTest.java b/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/InboxMessageHandlerTest.java deleted file mode 100644 index 2b672054..00000000 --- a/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/InboxMessageHandlerTest.java +++ /dev/null @@ -1,179 +0,0 @@ -package dev.caskeleton.messaging.inbox; - -import static org.assertj.core.api.Assertions.assertThat; - -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.DeliveryContext; -import dev.caskeleton.messaging.api.delivery.DeliveryMetadata; -import dev.caskeleton.messaging.api.delivery.HandleResult; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -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.header.MessageHeaders; -import dev.caskeleton.messaging.reliability.InboxRepository; -import java.time.Instant; -import java.util.ArrayList; -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.function.Function; -import java.util.function.Supplier; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** The inbox is a {@code MessageHandler} wrapping the business handler in one transaction. */ -class InboxMessageHandlerTest { - - private static final Instant NOW = Instant.parse("2026-08-14T00:00:00Z"); - private static final DestinationName ORDERS = new DestinationName("order-events"); - - private final RollbackInbox inbox = new RollbackInbox(); - private final List effects = new ArrayList<>(); - - @Test - @DisplayName("같은 메시지가 다시 배달되면 handler를 부르지 않고 Success로 답한다") - void aRedeliveredMessageIsAnsweredWithSuccessWithoutCallingTheHandler() { - // given - MessageDelivery delivery = delivery(MessageId.newId()); - MessageHandler handler = wrap(ignored -> HandleResult.success()); - handler.handle(delivery).toCompletableFuture().join(); - - // when - HandleResult redelivered = handler.handle(delivery).toCompletableFuture().join(); - - // then - assertThat(redelivered).isInstanceOf(HandleResult.Success.class); - assertThat(effects).hasSize(1); - } - - @Test - @DisplayName("handler가 Retry로 답하면 예약이 롤백되어 다음 배달에서 다시 처리된다") - void aRetryAnswerRollsTheReservationBackSoTheNextDeliveryIsProcessed() { - // given - MessageDelivery delivery = delivery(MessageId.newId()); - List answers = - new ArrayList<>(List.of(new HandleResult.Retry(failure()), HandleResult.success())); - MessageHandler handler = wrap(ignored -> answers.removeFirst()); - HandleResult first = handler.handle(delivery).toCompletableFuture().join(); - - // when - HandleResult second = handler.handle(delivery).toCompletableFuture().join(); - - // then - assertThat(first).isInstanceOf(HandleResult.Retry.class); - assertThat(second).isInstanceOf(HandleResult.Success.class); - assertThat(effects).hasSize(2); - assertThat(inbox.reserved).hasSize(1); - } - - @Test - @DisplayName("handler가 예외를 던지면 예약이 롤백되고 실패한 stage로 전달된다") - void aThrowingHandlerRollsTheReservationBackAndFailsTheStage() { - // given - MessageHandler handler = - wrap( - ignored -> { - throw new IllegalStateException("database down"); - }); - - // when - CompletableFuture stage = - handler.handle(delivery(MessageId.newId())).toCompletableFuture(); - - // then - assertThat(stage).isCompletedExceptionally(); - assertThat(inbox.reserved).isEmpty(); - } - - private MessageHandler wrap(Function, HandleResult> body) { - MessageHandler business = - new MessageHandler<>() { - @Override - public MessageDestination destination() { - return new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class); - } - - @Override - public CompletionStage handle(MessageDelivery delivery) { - effects.add(delivery.message().payload()); - return CompletableFuture.completedFuture(body.apply(delivery)); - } - }; - return new InboxMessageHandler<>( - business, new IdempotentConsumer(inbox, inbox), "order-projection", () -> NOW); - } - - private static MessageDelivery delivery(MessageId id) { - return new MessageDelivery<>( - new MessageEnvelope<>( - id, - new MessageType("order.created"), - new SchemaVersion(1), - NOW, - Optional.empty(), - new ProducerId("orders"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - "o-1"), - new DeliveryMetadata( - ORDERS, 1, false, Optional.empty(), Optional.empty(), Optional.empty(), NOW), - new DeliveryContext(NOW.plusSeconds(30), false, "order-projection")); - } - - private static FailureDescriptor failure() { - return FailureDescriptor.of( - FailureCategory.PROCESSING_TRANSIENT, "DOWNSTREAM_BUSY", "try again later"); - } - - /** An inbox whose reservations disappear when the transaction around them throws. */ - private static final class RollbackInbox - implements InboxRepository, IdempotentConsumer.TransactionRunner { - - private final Set reserved = new LinkedHashSet<>(); - - @Override - public T inTransaction(Supplier work) { - Set before = new LinkedHashSet<>(reserved); - try { - return work.get(); - } catch (RuntimeException rolledBack) { - reserved.clear(); - reserved.addAll(before); - throw rolledBack; - } - } - - @Override - public boolean reserve(MessageId messageId, String consumerId, Instant now) { - return reserved.add(messageId.value() + "|" + consumerId); - } - - @Override - public boolean isProcessed(MessageId messageId, String consumerId) { - return reserved.contains(messageId.value() + "|" + consumerId); - } - - @Override - public int purgeProcessedBefore(Instant processedBefore, int limit) { - return 0; - } - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/InboxOperationsTest.java b/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/InboxOperationsTest.java deleted file mode 100644 index d019b694..00000000 --- a/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/InboxOperationsTest.java +++ /dev/null @@ -1,149 +0,0 @@ -package dev.caskeleton.messaging.inbox; - -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.MessageId; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.reliability.InboxRepository; -import java.time.Duration; -import java.time.Instant; -import java.util.ArrayList; -import java.util.HashSet; -import java.util.List; -import java.util.Set; -import org.junit.jupiter.api.Test; - -class InboxOperationsTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - /** An inbox that remembers reservations and records the cutoffs cleanup asked for. */ - private static final class InMemoryInbox implements InboxRepository { - - private final Set reserved = new HashSet<>(); - private final List cutoffs = new ArrayList<>(); - private final List deletions; - private int pass; - - private InMemoryInbox(List deletions) { - this.deletions = deletions; - } - - @Override - public boolean reserve(MessageId messageId, String consumerId, Instant now) { - return reserved.add(messageId.value() + "|" + consumerId); - } - - @Override - public boolean isProcessed(MessageId messageId, String consumerId) { - return reserved.contains(messageId.value() + "|" + consumerId); - } - - private final List limits = new ArrayList<>(); - - @Override - public int purgeProcessedBefore(Instant processedBefore, int limit) { - cutoffs.add(processedBefore); - limits.add(limit); - return Math.min(pass < deletions.size() ? deletions.get(pass++) : 0, limit); - } - } - - private static InboxRetentionPolicy policy(Duration retention, Duration window) { - return new InboxRetentionPolicy(retention, window); - } - - @Test - void retentionShorterThanTheRedeliveryWindowIsRefused() { - assertThatThrownBy(() -> policy(Duration.ofHours(1), Duration.ofHours(6)).validate()) - .as("a pruned row lets a late redelivery apply its effect a second time") - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("twice"); - } - - @Test - void retentionAtTheSafetyFactorIsAccepted() { - assertThatCode(() -> policy(Duration.ofHours(12), Duration.ofHours(6)).validate()) - .doesNotThrowAnyException(); - } - - @Test - void theRequiredRetentionScalesWithTheWindow() { - assertThat(policy(Duration.ofDays(30), Duration.ofDays(2)).required()) - .isEqualTo(Duration.ofDays(4)); - } - - @Test - void aCleanupJobRefusesToStartUnderAnUnsafeRetention() { - assertThatThrownBy( - () -> - new InboxCleanupJob( - new InMemoryInbox(List.of(0)), - policy(Duration.ofMinutes(1), Duration.ofHours(1)), - 5)) - .as("dutifully deleting under a bad policy would create the bug the inbox prevents") - .isInstanceOf(MessagingConfigurationException.class); - } - - @Test - void cleanupAsksForBoundedBatchesAndStopsAtTheFirstShortOne() { - // given - InMemoryInbox inbox = new InMemoryInbox(List.of(1000, 500)); - - // when - new InboxCleanupJob(inbox, policy(Duration.ofDays(7), Duration.ofDays(1)), 10).runOnce(NOW); - - // then - assertThat(inbox.limits) - .as("DEFAULT_BATCH_SIZE was declared and never passed to the repository") - .containsExactly(InboxCleanupJob.DEFAULT_BATCH_SIZE, InboxCleanupJob.DEFAULT_BATCH_SIZE); - } - - @Test - void cleanupHonoursTheBatchCeilingSoItCannotRunForever() { - InMemoryInbox inbox = new InMemoryInbox(List.of(1000, 1000, 1000, 1000, 1000, 1000)); - - new InboxCleanupJob(inbox, policy(Duration.ofDays(7), Duration.ofDays(1)), 2).runOnce(NOW); - - assertThat(inbox.cutoffs).hasSize(2); - } - - @Test - void theSameMessageIsAppliedOncePerConsumerNotOncePerMessage() { - InMemoryInbox inbox = new InMemoryInbox(List.of()); - IdempotentConsumer consumer = new IdempotentConsumer(inbox, new DirectRunner()); - MessageId messageId = MessageId.newId(); - - InboxOutcome first = consumer.runOnce(messageId, "billing", NOW, () -> "charged"); - InboxOutcome second = consumer.runOnce(messageId, "analytics", NOW, () -> "counted"); - - assertThat(first.processed()).isTrue(); - assertThat(second.processed()) - .as("two independent consumers are each entitled to apply their own effect once") - .isTrue(); - } - - @Test - void aRedeliveryToTheSameConsumerIsSuppressed() { - InMemoryInbox inbox = new InMemoryInbox(List.of()); - IdempotentConsumer consumer = new IdempotentConsumer(inbox, new DirectRunner()); - MessageId messageId = MessageId.newId(); - - consumer.runOnce(messageId, "billing", NOW, () -> "charged"); - InboxOutcome redelivery = consumer.runOnce(messageId, "billing", NOW, () -> "charged"); - - assertThat(redelivery.processed()).isFalse(); - assertThat(redelivery.result()).isEmpty(); - } - - /** Runs the work inline; the real runner opens a database transaction. */ - private static final class DirectRunner implements IdempotentConsumer.TransactionRunner { - - @Override - public T inTransaction(java.util.function.Supplier work) { - return work.get(); - } - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxEnvelopeFactoryTest.java b/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxEnvelopeFactoryTest.java deleted file mode 100644 index 76745f45..00000000 --- a/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxEnvelopeFactoryTest.java +++ /dev/null @@ -1,158 +0,0 @@ -package dev.caskeleton.messaging.outbox; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -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.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.api.header.ReservedHeaders; -import dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata; -import dev.caskeleton.messaging.reliability.OutboxRecord; -import dev.caskeleton.messaging.reliability.OutboxStatus; -import dev.caskeleton.messaging.schema.EncodedMessage; -import java.nio.charset.StandardCharsets; -import java.time.Instant; -import java.util.Map; -import java.util.Optional; -import org.junit.jupiter.api.Test; - -/** - * What survives a trip through the database. - * - *

The envelope this factory rebuilds used to be poorer than the one that was written: producer - * came from the relay's own configuration, and correlation, causation, tenant, trace and the schema - * reference were all rebuilt as empty. A message published directly and the same message published - * through the outbox therefore arrived at the consumer as two different messages, and which one a - * service got depended on a deployment decision it could not see. - */ -class OutboxEnvelopeFactoryTest { - - private static final Instant WRITTEN_AT = Instant.parse("2026-08-10T09:15:00Z"); - private static final Instant OCCURRED_AT = Instant.parse("2026-08-10T09:14:00Z"); - private static final MessageId CAUSE = MessageId.newId(); - private static final String TRACEPARENT = - "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"; - - private final OutboxEnvelopeFactory factory = - new OutboxEnvelopeFactory(new ProducerId("relay-owner")); - - @Test - void everyCanonicalFieldOnTheRowReachesTheEnvelope() { - MessageEnvelope envelope = factory.toEnvelope(record(fullMetadata(), Map.of())); - - assertThat(envelope.producer()).isEqualTo(new ProducerId("order-api")); - assertThat(envelope.occurredAt()).contains(OCCURRED_AT); - assertThat(envelope.correlationId()).contains(new CorrelationId("checkout-7")); - assertThat(envelope.causationId()).contains(new CausationId(CAUSE)); - assertThat(envelope.tenantContext()).contains(new TenantContext("acme")); - assertThat(envelope.partitionKey()).contains("customer-42"); - assertThat(envelope.orderingKey()).contains("customer-42"); - assertThat(envelope.traceContext().traceparent()).contains(TRACEPARENT); - assertThat(envelope.payload().schemaReference()) - .hasValueSatisfying( - reference -> { - assertThat(reference.subject()).isEqualTo("order.created-value"); - assertThat(reference.version()).isEqualTo(new SchemaVersion(1)); - assertThat(reference.schemaUri()).contains(java.net.URI.create("urn:schema:1")); - }); - } - - @Test - void aTenantIsNeverReconstructedAsAbsent() { - assertThat(factory.toEnvelope(record(fullMetadata(), Map.of())).tenantContext()) - .as("a message published by one tenant and consumed as belonging to none is an escalation") - .contains(new TenantContext("acme")); - } - - @Test - void aRowWithoutAProducerIsAttributedToTheServiceThatOwnsTheRelay() { - MessageEnvelope envelope = - factory.toEnvelope(record(OutboxCanonicalMetadata.none(), Map.of())); - - assertThat(envelope.producer()) - .as("a row written before the column existed has no honest producer but this one") - .isEqualTo(new ProducerId("relay-owner")); - assertThat(envelope.occurredAt()) - .as("the transaction that wrote the row is the one the fact occurred in") - .contains(WRITTEN_AT); - assertThat(envelope.tenantContext()).isEmpty(); - assertThat(envelope.payload().schemaReference()).isEmpty(); - } - - @Test - void applicationHeadersOnTheRowStillTravel() { - assertThat( - factory - .toEnvelope(record(OutboxCanonicalMetadata.none(), Map.of("x-tenant-tier", "gold"))) - .headers() - .find("x-tenant-tier")) - .hasValueSatisfying(value -> assertThat(value.value()).isEqualTo("gold")); - } - - @Test - void aReservedHeaderOnTheRowIsRefusedEvenWhenItIsARoutingKey() { - assertThatThrownBy( - () -> - factory.toEnvelope( - record( - OutboxCanonicalMetadata.none(), - Map.of(ReservedHeaders.PARTITION_KEY, "customer-42")))) - .as("the routing keys were the exception that kept the reserved-name door ajar") - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("reserved namespace"); - } - - @Test - void aForgedMessageIdOnTheRowCannotOverwriteTheCanonicalOne() { - assertThatThrownBy( - () -> - factory.toEnvelope( - record( - OutboxCanonicalMetadata.none(), - Map.of(ReservedHeaders.MESSAGE_ID, MessageId.newId().value().toString())))) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining(ReservedHeaders.MESSAGE_ID); - } - - private static OutboxCanonicalMetadata fullMetadata() { - return new OutboxCanonicalMetadata( - Optional.of(new ProducerId("order-api")), - Optional.of(OCCURRED_AT), - Optional.of(new CorrelationId("checkout-7")), - Optional.of(new CausationId(CAUSE)), - Optional.of(new TenantContext("acme")), - Optional.of("customer-42"), - Optional.of("customer-42"), - Optional.of("order.created-value"), - Optional.of("urn:schema:1"), - new TraceContext(Optional.of(TRACEPARENT), Optional.empty(), Optional.empty())); - } - - private static OutboxRecord record( - OutboxCanonicalMetadata metadata, Map headers) { - return new OutboxRecord( - MessageId.newId(), - new DestinationName("order-events"), - new MessageType("order.created"), - new SchemaVersion(1), - ContentType.JSON, - "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), - headers, - metadata, - WRITTEN_AT, - OutboxStatus.PENDING, - 0, - Optional.empty(), - Optional.empty()); - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxOperationsTest.java b/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxOperationsTest.java deleted file mode 100644 index 2a52e0e1..00000000 --- a/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxOperationsTest.java +++ /dev/null @@ -1,196 +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.MessageId; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.reliability.OutboxRecord; -import dev.caskeleton.messaging.reliability.OutboxRepository; -import java.time.Duration; -import java.time.Instant; -import java.util.ArrayList; -import java.util.List; -import java.util.Optional; -import org.junit.jupiter.api.Test; - -class OutboxOperationsTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - /** Records the cutoffs a cleanup pass asked for, and how many rows each pass removed. */ - private static final class RecordingRepository implements OutboxRepository { - - private final List cutoffs = new ArrayList<>(); - private final List deletions; - private int pass; - - private RecordingRepository(List deletions) { - this.deletions = deletions; - } - - @Override - public void append(OutboxRecord record) { - throw new UnsupportedOperationException(); - } - - @Override - public java.util.List claimBatch( - String owner, int batchSize, Duration leaseDuration, Instant now, int maxAttempts) { - return java.util.List.of(); - } - - @Override - public dev.caskeleton.messaging.reliability.OutboxTransitionResult markAmbiguous( - dev.caskeleton.messaging.reliability.OutboxLease lease, - String failureCode, - Instant now, - Instant nextAttemptAt) { - throw new UnsupportedOperationException(); - } - - @Override - public dev.caskeleton.messaging.reliability.OutboxTransitionResult markExhausted( - dev.caskeleton.messaging.reliability.OutboxLease lease, String reason, Instant now) { - throw new UnsupportedOperationException(); - } - - @Override - public dev.caskeleton.messaging.reliability.OutboxTransitionResult markPublished( - dev.caskeleton.messaging.reliability.OutboxLease lease, Instant now) { - throw new UnsupportedOperationException(); - } - - @Override - public dev.caskeleton.messaging.reliability.OutboxTransitionResult markFailed( - dev.caskeleton.messaging.reliability.OutboxLease lease, String failureCode, Instant now) { - throw new UnsupportedOperationException(); - } - - @Override - public dev.caskeleton.messaging.reliability.OutboxTransitionResult releaseLease( - dev.caskeleton.messaging.reliability.OutboxLease lease) { - throw new UnsupportedOperationException(); - } - - @Override - public Optional find(MessageId messageId) { - throw new UnsupportedOperationException(); - } - - private final List limits = new ArrayList<>(); - - @Override - public int purgePublishedBefore(Instant publishedBefore, int limit) { - cutoffs.add(publishedBefore); - limits.add(limit); - return Math.min(pass < deletions.size() ? deletions.get(pass++) : 0, limit); - } - } - - @Test - void aLeaseShorterThanThePublishTimeoutIsRefused() { - assertThatThrownBy( - () -> - new OutboxProperties( - 100, - Duration.ofSeconds(4), - Duration.ofSeconds(5), - Duration.ofMillis(500), - Duration.ofDays(1), - 5)) - .as("a second relay would claim the row while the first is still awaiting its confirm") - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("lease"); - } - - @Test - void theDefaultsSatisfyTheirOwnRule() { - assertThatCode(OutboxProperties::defaults).doesNotThrowAnyException(); - } - - @Test - void cleanupAsksForBoundedBatchesAndStopsAtTheFirstShortOne() { - // given - RecordingRepository repository = new RecordingRepository(List.of(1000, 1000, 250)); - - // when - new OutboxCleanupJob(repository, OutboxProperties.defaults(), 10).runOnce(NOW); - - // then - assertThat(repository.limits) - .as("one DELETE over the whole backlog holds its locks for as long as the backlog is big") - .containsExactly( - OutboxCleanupJob.DEFAULT_BATCH_SIZE, - OutboxCleanupJob.DEFAULT_BATCH_SIZE, - OutboxCleanupJob.DEFAULT_BATCH_SIZE); - } - - @Test - void cleanupStopsAsSoonAsThereIsNothingLeft() { - RecordingRepository repository = new RecordingRepository(List.of(0)); - - new OutboxCleanupJob(repository, OutboxProperties.defaults(), 10).runOnce(NOW); - - assertThat(repository.cutoffs).hasSize(1); - } - - @Test - void cleanupNeverAsksForRowsNewerThanTheRetention() { - RecordingRepository repository = new RecordingRepository(List.of(0)); - OutboxProperties properties = OutboxProperties.defaults(); - - new OutboxCleanupJob(repository, properties, 5).runOnce(NOW); - - assertThat(repository.cutoffs).containsExactly(NOW.minus(properties.retentionAfterPublish())); - } - - @Test - void aSuccessfulPassDoesNotBackOff() { - OutboxRetryScheduler scheduler = - new OutboxRetryScheduler(OutboxProperties.defaults(), Duration.ofMinutes(1)); - - assertThat(scheduler.backoff(0)).isEqualTo(OutboxProperties.defaults().pollInterval()); - } - - @Test - void consecutiveFailuresBackOffAndThenStopGrowing() { - OutboxRetryScheduler scheduler = - new OutboxRetryScheduler(OutboxProperties.defaults(), Duration.ofSeconds(10)); - - assertThat(scheduler.backoff(3)).isGreaterThan(scheduler.backoff(1)); - assertThat(scheduler.backoff(50)) - .as("an unbounded counter must not overflow into a negative duration") - .isLessThanOrEqualTo(Duration.ofSeconds(10)) - .isPositive(); - } - - @Test - void backoffNeverDropsBelowThePollInterval() { - OutboxProperties properties = OutboxProperties.defaults(); - OutboxRetryScheduler scheduler = new OutboxRetryScheduler(properties, Duration.ofSeconds(10)); - - for (int attempt = 0; attempt <= 40; attempt++) { - assertThat(scheduler.backoff(attempt)).isGreaterThanOrEqualTo(properties.pollInterval()); - } - } - - @Test - void aRecordIsParkedOnceItsAttemptBudgetIsSpent() { - OutboxProperties properties = OutboxProperties.defaults(); - OutboxRetryScheduler scheduler = new OutboxRetryScheduler(properties, Duration.ofMinutes(1)); - - assertThat(scheduler.isExhausted(properties.maxAttempts() - 1)).isFalse(); - assertThat(scheduler.isExhausted(properties.maxAttempts())).isTrue(); - assertThat(scheduler.parkReason(properties.maxAttempts())).isPresent(); - } - - @Test - void theNextPassIsScheduledFromTheBackoff() { - OutboxRetryScheduler scheduler = - new OutboxRetryScheduler(OutboxProperties.defaults(), Duration.ofSeconds(10)); - - assertThat(scheduler.nextPassAt(NOW, 0)).isEqualTo(NOW.plus(scheduler.backoff(0))); - } -} diff --git a/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayTest.java b/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayTest.java deleted file mode 100644 index 62d45f81..00000000 --- a/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayTest.java +++ /dev/null @@ -1,686 +0,0 @@ -package dev.caskeleton.messaging.outbox; - -import static org.assertj.core.api.Assertions.assertThat; - -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.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; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.publish.ConfirmationLevel; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -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.ApiTier; -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; -import java.util.ArrayList; -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; - -class OutboxRelayTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - private final InMemoryOutboxRepository repository = new InMemoryOutboxRepository(); - - @Test - void aConfirmedPublishMarksTheRowPublished() { - OutboxRecord record = OutboxFixtures.pending(); - repository.append(record); - - OutboxRelayReport report = relay(RecordingOutboxPublisher.confirming()).runOnce(NOW); - - assertThat(report.published()).isEqualTo(1); - assertThat(repository.find(record.messageId()).orElseThrow().status()) - .isEqualTo(OutboxStatus.PUBLISHED); - } - - @Test - void aRowThatCannotBecomeAnEnvelopeFailsWhileTheRestOfItsBatchPublishes() { - // given - OutboxRecord poison = OutboxFixtures.withHeaders(Map.of("msg.id", "forged")); - OutboxRecord healthy = OutboxFixtures.pending(); - repository.append(poison); - repository.append(healthy); - - // when - relay(RecordingOutboxPublisher.confirming()).runOnce(NOW); - - // then - assertThat(List.of(poison, healthy)) - .extracting(row -> repository.find(row.messageId()).orElseThrow().status()) - .as("one bad row threw out of the pass and held the whole batch until its lease expired") - .containsExactly(OutboxStatus.FAILED, OutboxStatus.PUBLISHED); - } - - @Test - void aPublisherThatThrowsLeavesTheRowAmbiguousRatherThanStrandingTheBatch() { - // given - OutboxRecord first = OutboxFixtures.pending(); - repository.append(first); - MessagePublisher throwing = - new MessagePublisher() { - @Override - public CompletionStage publish( - MessageDestination destination, - MessageEnvelope message, - PublishOptions options) { - throw new IllegalStateException("the broker connection is gone"); - } - }; - - // when - relay(throwing).runOnce(NOW); - - // then - assertThat(repository.find(first.messageId()).orElseThrow().status()) - .as("an exception says nothing about whether the broker took the message") - .isEqualTo(OutboxStatus.AMBIGUOUS); - } - - @Test - void anAmbiguousPublishStaysRetryableRatherThanFailing() { - OutboxRecord record = OutboxFixtures.pending(); - repository.append(record); - - OutboxRelayReport report = relay(RecordingOutboxPublisher.ambiguous()).runOnce(NOW); - - assertThat(report.ambiguous()).isEqualTo(1); - assertThat(repository.find(record.messageId()).orElseThrow().status()) - .isEqualTo(OutboxStatus.AMBIGUOUS); - } - - @Test - void anAmbiguousRowIsRepublishedUnderTheSameMessageId() { - OutboxRecord record = OutboxFixtures.pending(); - repository.append(record); - RecordingOutboxPublisher publisher = RecordingOutboxPublisher.ambiguous(); - - relay(publisher).runOnce(NOW); - relay(publisher).runOnce(NOW.plusSeconds(60)); - - assertThat(publisher.publishedIds).hasSize(2); - assertThat(publisher.publishedIds.get(0)).isEqualTo(record.messageId()); - assertThat(publisher.publishedIds.get(1)).isEqualTo(record.messageId()); - } - - @Test - void anAmbiguousRowWaitsForItsBackoffBeforeItIsClaimedAgain() { - OutboxRecord record = OutboxFixtures.pending(); - repository.append(record); - RecordingOutboxPublisher publisher = RecordingOutboxPublisher.ambiguous(); - - relay(publisher).runOnce(NOW); - OutboxRelayReport tooSoon = relay(publisher).runOnce(NOW.plusMillis(100)); - - assertThat(tooSoon.leased()) - .as("a backoff nothing writes on the row is a backoff the next pass cannot see") - .isZero(); - assertThat(publisher.publishedIds).hasSize(1); - } - - @Test - void aRowThatSpendsItsAttemptBudgetIsParkedRatherThanLeftRetryable() { - OutboxRecord record = OutboxFixtures.pending(); - repository.append(record); - RecordingOutboxPublisher publisher = RecordingOutboxPublisher.ambiguous(); - OutboxRelay relay = relay(publisher, budgetOf(2)); - - relay.runOnce(NOW); - OutboxRelayReport last = relay.runOnce(NOW.plus(Duration.ofHours(1))); - - assertThat(last.exhausted()) - .as("a rejected row needs a fix and a spent one needs a redrive") - .isEqualTo(1); - assertThat(repository.find(record.messageId()).orElseThrow().status()) - .isEqualTo(OutboxStatus.EXHAUSTED); - assertThat(relay.runOnce(NOW.plus(Duration.ofDays(1))).leased()) - .as("only an operator redrive brings a parked row back") - .isZero(); - } - - @Test - void aRejectedPublishIsMarkedFailedAndNotRetried() { - OutboxRecord record = OutboxFixtures.pending(); - repository.append(record); - - relay(RecordingOutboxPublisher.rejecting()).runOnce(NOW); - - assertThat(repository.find(record.messageId()).orElseThrow().status()) - .isEqualTo(OutboxStatus.FAILED); - assertThat(repository.claimBatch("relay", 10, Duration.ofSeconds(30), NOW, Integer.MAX_VALUE)) - .isEmpty(); - } - - @Test - void aLeasedRowIsInvisibleToAnotherRelayInstance() { - repository.append(OutboxFixtures.pending()); - - List first = - repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW, Integer.MAX_VALUE); - List second = - repository.claimBatch("relay-b", 10, Duration.ofSeconds(30), NOW, Integer.MAX_VALUE); - - assertThat(first).hasSize(1); - assertThat(second).isEmpty(); - } - - @Test - void anExpiredLeaseBecomesClaimableAgain() { - repository.append(OutboxFixtures.pending()); - repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW, Integer.MAX_VALUE); - - List reclaimed = - repository.claimBatch( - "relay-b", 10, Duration.ofSeconds(30), NOW.plusSeconds(31), Integer.MAX_VALUE); - - assertThat(reclaimed).hasSize(1); - } - - @Test - void theRelayPreservesPayloadAndTypeOnTheWire() { - OutboxRecord record = OutboxFixtures.pending(); - repository.append(record); - RecordingOutboxPublisher publisher = RecordingOutboxPublisher.confirming(); - - relay(publisher).runOnce(NOW); - - MessageEnvelope envelope = publisher.publishedEnvelopes.get(0); - assertThat(envelope.messageType()).isEqualTo(new MessageType("order.created")); - 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, - publisher, - new OutboxEnvelopeFactory(new ProducerId("order-api")), - 100, - Duration.ofSeconds(30)); - } - - private OutboxRelay relay(MessagePublisher publisher, OutboxRetryScheduler scheduler) { - return new OutboxRelay( - repository, - publisher, - new OutboxEnvelopeFactory(new ProducerId("order-api")), - 100, - Duration.ofSeconds(30), - "relay-under-test", - scheduler); - } - - private static OutboxRetryScheduler budgetOf(int maxAttempts) { - OutboxProperties defaults = OutboxProperties.defaults(); - return new OutboxRetryScheduler( - new OutboxProperties( - defaults.batchSize(), - defaults.leaseDuration(), - defaults.publishTimeout(), - defaults.pollInterval(), - defaults.retentionAfterPublish(), - maxAttempts), - Duration.ofMinutes(5)); - } -} - -/** Builds outbox rows. */ -final class OutboxFixtures { - - private OutboxFixtures() {} - - static OutboxRecord pending() { - return withHeaders(Map.of()); - } - - static OutboxRecord withHeaders(Map headers) { - return new OutboxRecord( - MessageId.newId(), - new DestinationName("order-events"), - new MessageType("order.created"), - new SchemaVersion(1), - ContentType.JSON, - "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), - headers, - dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata.none(), - Instant.parse("2026-08-10T09:14:00Z"), - OutboxStatus.PENDING, - 0, - Optional.empty(), - Optional.empty()); - } -} - -/** A deterministic outbox store with the leasing semantics the relay relies on. */ -final class InMemoryOutboxRepository implements OutboxRepository { - - private final Map rows = new LinkedHashMap<>(); - private final Map leases = new LinkedHashMap<>(); - - /** Owner and token per row, mirroring the fencing columns the SQL now carries. */ - private final Map owners = new LinkedHashMap<>(); - - private final Map tokens = new LinkedHashMap<>(); - - @Override - public void append(OutboxRecord record) { - rows.put(record.messageId(), record); - } - - /** - * Mirrors the SQL exactly, including {@code IN_FLIGHT}. - * - *

An earlier version of this double left the status untouched on lease and only considered - * {@code PENDING} and {@code AMBIGUOUS} claimable. That happened to pass while the real query - * stranded every row whose relay had died mid-publish. A double that is more forgiving than the - * thing it stands in for hides exactly the defects it was written to catch, so this one follows - * the same three-state rule. - */ - private List lease(int batchSize, Duration leaseDuration, Instant now) { - List leased = new ArrayList<>(); - for (OutboxRecord record : List.copyOf(rows.values())) { - if (leased.size() >= batchSize) { - break; - } - boolean claimable = - record.status() == OutboxStatus.PENDING - || record.status() == OutboxStatus.AMBIGUOUS - || record.status() == OutboxStatus.IN_FLIGHT; - Instant leaseExpiry = leases.get(record.messageId()); - boolean unleased = leaseExpiry == null || !now.isBefore(leaseExpiry); - if (claimable && unleased) { - leases.put(record.messageId(), now.plus(leaseDuration)); - rows.put( - record.messageId(), - record.withStatus(OutboxStatus.IN_FLIGHT, record.attempts(), record.lastFailureCode())); - leased.add(record); - } - } - return List.copyOf(leased); - } - - private List claimIgnoringBudget( - String owner, int batchSize, Duration leaseDuration, Instant now) { - List claimed = new ArrayList<>(); - for (OutboxRecord record : lease(batchSize, leaseDuration, now)) { - long token = tokens.merge(record.messageId(), 1L, Long::sum); - owners.put(record.messageId(), owner); - claimed.add(new OutboxLease(record, owner, token, now.plus(leaseDuration))); - } - return List.copyOf(claimed); - } - - /** - * Refuses a write whose lease has been superseded, exactly as the SQL predicate does. - * - *

A double that accepted every terminal write would let the relay's stale-lease handling look - * correct without ever being exercised. - */ - private boolean owns(OutboxLease lease) { - return lease.owner().equals(owners.get(lease.messageId())) - && Long.valueOf(lease.token()).equals(tokens.get(lease.messageId())) - && rows.get(lease.messageId()) != null - && rows.get(lease.messageId()).status() == OutboxStatus.IN_FLIGHT; - } - - /** Per-row retry clock, mirroring next_attempt_at and the attempt budget in the SQL. */ - private final Map nextAttempts = new LinkedHashMap<>(); - - @Override - public List claimBatch( - String owner, int batchSize, Duration leaseDuration, Instant now, int maxAttempts) { - List claimed = new ArrayList<>(); - for (OutboxLease lease : claimIgnoringBudget(owner, batchSize, leaseDuration, now)) { - Instant nextAttempt = nextAttempts.get(lease.messageId()); - boolean waiting = nextAttempt != null && now.isBefore(nextAttempt); - if (waiting || lease.record().attempts() >= maxAttempts) { - // Put it back exactly as the SQL predicate would have left it: unclaimed. - releaseLeaseUnfenced(lease.messageId()); - continue; - } - claimed.add(lease); - } - return List.copyOf(claimed); - } - - @Override - public OutboxTransitionResult markAmbiguous( - OutboxLease lease, String failureCode, Instant now, Instant nextAttemptAt) { - if (!owns(lease)) { - return OutboxTransitionResult.STALE_LEASE; - } - markAmbiguousUnfenced(lease.messageId(), failureCode); - owners.remove(lease.messageId()); - nextAttempts.put(lease.messageId(), nextAttemptAt); - return OutboxTransitionResult.APPLIED; - } - - @Override - public OutboxTransitionResult markExhausted(OutboxLease lease, String reason, Instant now) { - if (!owns(lease)) { - return OutboxTransitionResult.STALE_LEASE; - } - transition(lease.messageId(), OutboxStatus.EXHAUSTED, Optional.of(reason)); - owners.remove(lease.messageId()); - leases.remove(lease.messageId()); - return OutboxTransitionResult.APPLIED; - } - - @Override - public OutboxTransitionResult markPublished(OutboxLease lease, Instant now) { - if (!owns(lease)) { - return OutboxTransitionResult.STALE_LEASE; - } - transition(lease.messageId(), OutboxStatus.PUBLISHED, Optional.empty()); - owners.remove(lease.messageId()); - return OutboxTransitionResult.APPLIED; - } - - @Override - public OutboxTransitionResult markFailed(OutboxLease lease, String failureCode, Instant now) { - if (!owns(lease)) { - return OutboxTransitionResult.STALE_LEASE; - } - markFailedUnfenced(lease.messageId(), failureCode); - owners.remove(lease.messageId()); - return OutboxTransitionResult.APPLIED; - } - - @Override - public OutboxTransitionResult releaseLease(OutboxLease lease) { - if (!owns(lease)) { - return OutboxTransitionResult.STALE_LEASE; - } - releaseLeaseUnfenced(lease.messageId()); - owners.remove(lease.messageId()); - return OutboxTransitionResult.APPLIED; - } - - private void markAmbiguousUnfenced(MessageId messageId, String failureCode) { - transition(messageId, OutboxStatus.AMBIGUOUS, Optional.of(failureCode)); - leases.remove(messageId); - } - - private void markFailedUnfenced(MessageId messageId, String failureCode) { - transition(messageId, OutboxStatus.FAILED, Optional.of(failureCode)); - } - - private void releaseLeaseUnfenced(MessageId messageId) { - leases.remove(messageId); - } - - @Override - public Optional find(MessageId messageId) { - return Optional.ofNullable(rows.get(messageId)); - } - - @Override - public int purgePublishedBefore(Instant publishedBefore, int limit) { - int before = rows.size(); - rows.values().removeIf(record -> record.status() == OutboxStatus.PUBLISHED); - return Math.min(before - rows.size(), limit); - } - - private void transition(MessageId messageId, OutboxStatus status, Optional failureCode) { - OutboxRecord record = rows.get(messageId); - if (record != null) { - rows.put(messageId, record.withStatus(status, record.attempts() + 1, failureCode)); - } - } -} - -/** A publisher that records what the relay handed it. */ -final class RecordingOutboxPublisher implements MessagePublisher { - - final List publishedIds = new ArrayList<>(); - final List> publishedEnvelopes = new ArrayList<>(); - - private final PublishCompletion completion; - - private RecordingOutboxPublisher(PublishCompletion completion) { - this.completion = completion; - } - - static RecordingOutboxPublisher confirming() { - return new RecordingOutboxPublisher(PublishCompletion.CONFIRMED); - } - - static RecordingOutboxPublisher ambiguous() { - return new RecordingOutboxPublisher(PublishCompletion.AMBIGUOUS); - } - - static RecordingOutboxPublisher rejecting() { - return new RecordingOutboxPublisher(PublishCompletion.REJECTED); - } - - @Override - public CompletionStage publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - publishedIds.add(message.messageId()); - publishedEnvelopes.add(message); - return CompletableFuture.completedFuture(result()); - } - - private PublishResult result() { - return switch (completion) { - case CONFIRMED -> - new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ofMillis(2), - Optional.empty()); - case AMBIGUOUS -> - new PublishResult( - PublishCompletion.AMBIGUOUS, - PublishEvidence.ambiguous(), - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, - Duration.ofSeconds(5), - Optional.of( - FailureDescriptor.of( - FailureCategory.AMBIGUOUS, "CONFIRM_TIMEOUT", "confirm timed out"))); - case REJECTED -> - new PublishResult( - PublishCompletion.REJECTED, - PublishEvidence.notTransmitted(), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ofMillis(1), - Optional.of( - FailureDescriptor.of( - FailureCategory.PERMANENT_BUSINESS, "INVALID_TOPIC", "unknown topic"))); - }; - } -} - -/** 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(), - ApiTier.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/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayWorkerTest.java b/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayWorkerTest.java deleted file mode 100644 index 9f71564c..00000000 --- a/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayWorkerTest.java +++ /dev/null @@ -1,178 +0,0 @@ -package dev.caskeleton.messaging.outbox; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.ProducerId; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.publish.ConfirmationLevel; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -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.reliability.OutboxRecord; -import dev.caskeleton.messaging.reliability.OutboxStatus; -import java.time.Duration; -import java.util.Optional; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import java.util.concurrent.CountDownLatch; -import java.util.concurrent.TimeUnit; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * Whether anything actually drives the relay. - * - *

The relay, its scheduler and the attempt budget were all constructed by the auto-configuration - * and {@code runOnce} was called by no production code. A business transaction would commit its - * outbox row, report success, and the message would never be published — a silent backlog rather - * than a visible failure. - */ -class OutboxRelayWorkerTest { - - private static final Duration PATIENCE = Duration.ofSeconds(5); - - private final InMemoryOutboxRepository repository = new InMemoryOutboxRepository(); - - @Test - @DisplayName("a started worker publishes the backlog without anyone calling a pass") - void aStartedWorkerPublishesTheBacklog() throws InterruptedException { - OutboxRecord record = OutboxFixtures.pending(); - repository.append(record); - OutboxRelayWorker worker = worker(RecordingOutboxPublisher.confirming()); - - worker.start(); - try { - awaitStatus(record, OutboxStatus.PUBLISHED); - } finally { - worker.stop(PATIENCE); - } - - assertThat(repository.find(record.messageId()).orElseThrow().status()) - .isEqualTo(OutboxStatus.PUBLISHED); - assertThat(worker.completedPasses()).isPositive(); - } - - @Test - @DisplayName("stopping waits for the running pass instead of stranding its claimed rows") - void stoppingWaitsForTheRunningPass() throws InterruptedException { - OutboxRecord record = OutboxFixtures.pending(); - repository.append(record); - // The publish is still in progress when stop() is called, so the row is claimed and IN_FLIGHT - // at that moment: the pass has to be allowed to finish or the lease strands the row. - SlowPublisher publisher = new SlowPublisher(Duration.ofMillis(300)); - OutboxRelayWorker worker = worker(publisher); - - worker.start(); - assertThat(publisher.started.await(PATIENCE.toMillis(), TimeUnit.MILLISECONDS)).isTrue(); - boolean drained = worker.stop(PATIENCE); - - assertThat(drained).isTrue(); - assertThat(repository.find(record.messageId()).orElseThrow().status()) - .as("a pass killed between its claim and its terminal write leaves the row leased") - .isEqualTo(OutboxStatus.PUBLISHED); - } - - @Test - @DisplayName("a pass that throws does not stop every pass after it") - void aFailedPassDoesNotEndTheLoop() throws InterruptedException { - OutboxRelayWorker worker = worker(unreachableDatabase(), new ThrowingPublisher()); - - worker.start(); - try { - long deadline = System.nanoTime() + PATIENCE.toNanos(); - while (worker.completedPasses() < 2 && System.nanoTime() < deadline) { - Thread.sleep(10); - } - } finally { - worker.stop(PATIENCE); - } - - assertThat(worker.completedPasses()) - .as("a scheduled task's own exception cancels every future run of it") - .isGreaterThanOrEqualTo(2); - assertThat(worker.failedPasses()).isPositive(); - } - - private OutboxRelayWorker worker(MessagePublisher publisher) { - return worker(repository, publisher); - } - - /** An outbox whose every call fails, as it does while its database is down. */ - private static dev.caskeleton.messaging.reliability.OutboxRepository unreachableDatabase() { - return (dev.caskeleton.messaging.reliability.OutboxRepository) - java.lang.reflect.Proxy.newProxyInstance( - OutboxRelayWorkerTest.class.getClassLoader(), - new Class[] {dev.caskeleton.messaging.reliability.OutboxRepository.class}, - (proxy, method, arguments) -> { - throw new IllegalStateException("the outbox database is unreachable"); - }); - } - - private static OutboxRelayWorker worker( - dev.caskeleton.messaging.reliability.OutboxRepository outbox, MessagePublisher publisher) { - OutboxRelay relay = - new OutboxRelay( - outbox, - publisher, - new OutboxEnvelopeFactory(new ProducerId("order-api")), - 100, - Duration.ofSeconds(30)); - return new OutboxRelayWorker(relay, OutboxRetryScheduler.standard()); - } - - private void awaitStatus(OutboxRecord record, OutboxStatus expected) throws InterruptedException { - long deadline = System.nanoTime() + PATIENCE.toNanos(); - while (System.nanoTime() < deadline) { - if (repository.find(record.messageId()).map(OutboxRecord::status).orElse(null) == expected) { - return; - } - Thread.sleep(10); - } - } - - /** A publisher that is still publishing when shutdown begins. */ - private static final class SlowPublisher implements MessagePublisher { - - private final CountDownLatch started = new CountDownLatch(1); - - private final Duration duration; - - private SlowPublisher(Duration duration) { - this.duration = duration; - } - - @Override - public CompletionStage publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - started.countDown(); - try { - Thread.sleep(duration.toMillis()); - } catch (InterruptedException interrupted) { - Thread.currentThread().interrupt(); - } - return CompletableFuture.completedFuture( - new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.BROKER_ACK), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ofMillis(1), - Optional.empty())); - } - } - - /** A publisher whose failure reaches the worker as an exception rather than a result. */ - private static final class ThrowingPublisher implements MessagePublisher { - - @Override - public CompletionStage publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - throw new IllegalStateException("the broker connection is gone"); - } - } -} diff --git a/src/platforms/messaging/messaging-runtime-core/build.gradle b/src/platforms/messaging/messaging-runtime-core/build.gradle deleted file mode 100644 index 06c462f0..00000000 --- a/src/platforms/messaging/messaging-runtime-core/build.gradle +++ /dev/null @@ -1,18 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -// The central publish and delivery orchestration. -// -// MessagePublisher was an interface with no implementation anywhere in the new platform: the -// brokers implemented MessagingTransport, the core auto-configuration built dead-letter and facade -// beans on top of a publisher bean that nothing supplied, and admission, security, runtime leases -// and observation existed as beans that no publish path ever called. A starter that filled the gap -// with an application-supplied fake would pass a context test while running none of them. -dependencies { - api project(':messaging:messaging-core-api') - api project(':messaging:messaging-policy') - api project(':messaging:messaging-transport-spi') - api project(':messaging:messaging-security') - api project(':messaging:messaging-observability') -} diff --git a/src/platforms/messaging/messaging-runtime-core/gradle.lockfile b/src/platforms/messaging/messaging-runtime-core/gradle.lockfile deleted file mode 100644 index dcab1d05..00000000 --- a/src/platforms/messaging/messaging-runtime-core/gradle.lockfile +++ /dev/null @@ -1,87 +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.50.0=annotationProcessor,checkstyle,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.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -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.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-core:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-observation:1.16.8=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.6.1=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.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DeclaredDestinationAccess.java b/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DeclaredDestinationAccess.java deleted file mode 100644 index 2c6a125d..00000000 --- a/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DeclaredDestinationAccess.java +++ /dev/null @@ -1,48 +0,0 @@ -package dev.caskeleton.messaging.runtime; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.security.DestinationAccessPolicy; -import java.util.Map; -import java.util.Objects; -import java.util.Set; - -/** - * The access policy a deployment gets when it has not written one (MSG-INT-003). - * - *

{@link DestinationAccessPolicy} is three sets of destination names and has a {@code denyAll()} - * factory. Neither is a usable default on its own: - * - *

- * - *

So the default is neither: a deployment may publish to the destinations it declared. - * Declaring a destination profile is already an act of configuration — it states the ordering - * guarantee, the retry policy and the dead-letter target — and a message to a destination nobody - * declared is not an access-control edge case, it is a typo or a module reaching past its own - * contract. That is exactly what this check is for, and it is now the thing it catches. - * - *

Consume and administer stay empty. A publisher's default has no business granting either, and - * a deployment that needs them replaces this bean — which is the point of it being a bean. - */ -public final class DeclaredDestinationAccess { - - private DeclaredDestinationAccess() {} - - /** - * Builds the policy from the declared destination profiles. - * - * @param destinations every destination the deployment configured - * @return a policy permitting publication to those destinations and nothing else - */ - public static DestinationAccessPolicy of(Map destinations) { - Objects.requireNonNull(destinations, "destinations"); - return new DestinationAccessPolicy(Set.copyOf(destinations.keySet()), Set.of(), Set.of()); - } -} diff --git a/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessor.java b/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessor.java deleted file mode 100644 index 4f1169db..00000000 --- a/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessor.java +++ /dev/null @@ -1,291 +0,0 @@ -package dev.caskeleton.messaging.runtime; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.delivery.DeliveryContext; -import dev.caskeleton.messaging.api.delivery.DeliveryGuarantee; -import dev.caskeleton.messaging.api.delivery.HandleResult; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -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.settlement.SettlementResult; -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.schema.MessageCodec; -import dev.caskeleton.messaging.schema.MessageCodecRegistry; -import dev.caskeleton.messaging.transport.TransportDelivery; -import java.time.Duration; -import java.time.InstantSource; -import java.util.HashMap; -import java.util.List; -import java.util.Map; -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.Supplier; - -/** - * Turns one still-encoded delivery into a typed {@link MessageHandler} call and exactly one broker - * settlement. - * - *

This is the consume path the platform had three half-contracts for and no assembly (S7-#2): a - * typed {@code MessageHandler} nothing called, a processor that took an untyped function, and an - * inbox handler with its own signature. There is now one handler contract, and this class is the - * one place that decodes for it, calls it, and settles. - * - *

Rules enforced here rather than left to each adapter: - * - *

- * - *

How many times a requeued delivery comes back, and what happens when the attempts run out, is - * the transport's retry policy — {@code requeue} is a request, and the Kafka consumer counts it. - */ -public final class DefaultDeliveryProcessor { - - private final DestinationProfile profile; - private final Map> handlers; - private final MessageCodecRegistry codecs; - private final DeadLetterPublisher deadLetters; - private final String consumerId; - private final InstantSource clock; - - /** - * Creates a processor for one destination. - * - * @param profile the destination being consumed - * @param handlers the handlers for that destination, at most one per message type - * @param codecs decodes payloads by content type - * @param deadLetters publishes a delivery to the destination's dead-letter destination - * @param consumerId the stable, low-cardinality consumer identity handlers see - * @param clock the clock handler deadlines are measured on - */ - public DefaultDeliveryProcessor( - DestinationProfile profile, - List> handlers, - MessageCodecRegistry codecs, - DeadLetterPublisher deadLetters, - String consumerId, - InstantSource clock) { - this.profile = Objects.requireNonNull(profile, "profile must not be null"); - this.codecs = Objects.requireNonNull(codecs, "codecs must not be null"); - this.deadLetters = Objects.requireNonNull(deadLetters, "deadLetters must not be null"); - this.clock = Objects.requireNonNull(clock, "clock must not be null"); - if (consumerId == null || consumerId.isBlank()) { - throw new IllegalArgumentException("consumerId must not be blank"); - } - this.consumerId = consumerId; - Map> byType = new HashMap<>(); - for (MessageHandler handler : Objects.requireNonNull(handlers, "handlers")) { - if (!handler.destination().name().equals(profile.name())) { - throw new IllegalArgumentException( - "handler for " - + handler.destination().name().value() - + " cannot consume " - + profile.name().value()); - } - if (byType.put(handler.destination().messageType(), handler) != null) { - throw new IllegalArgumentException( - "destination " - + profile.name().value() - + " has two handlers for " - + handler.destination().messageType().value() - + "; which one runs would depend on bean order"); - } - } - if (byType.isEmpty()) { - throw new IllegalArgumentException("a processor needs at least one handler"); - } - this.handlers = Map.copyOf(byType); - } - - /** - * Handles one delivery and settles it once. - * - * @param delivery the still-encoded delivery - * @return a stage completing once the settlement call has returned - */ - public CompletionStage process(TransportDelivery delivery) { - Objects.requireNonNull(delivery, "delivery must not be null"); - OneShotSettlement settlement = new OneShotSettlement(delivery); - - MessageEnvelope envelope = delivery.envelope(); - MessageHandler handler = handlers.get(envelope.messageType()); - if (handler == null) { - return deadLetter( - delivery, - settlement, - FailureDescriptor.of( - FailureCategory.DESERIALIZATION, - "NO_HANDLER_FOR_MESSAGE_TYPE", - "no handler is registered for this message type on this destination")); - } - return dispatch(handler, delivery, settlement); - } - - private CompletionStage dispatch( - MessageHandler handler, TransportDelivery delivery, OneShotSettlement settlement) { - MessageEnvelope envelope = delivery.envelope(); - T payload; - try { - MessageCodec codec = - codecs - .find(envelope.contentType()) - .orElseThrow( - () -> - new IllegalStateException( - "no codec for content type " + envelope.contentType().value())); - payload = - codec.decode( - envelope.messageType(), - envelope.schemaVersion(), - envelope.payload(), - handler.destination().payloadType()); - } catch (RuntimeException undecodable) { - return deadLetter( - delivery, - settlement, - new FailureDescriptor( - FailureCategory.DESERIALIZATION, - "PAYLOAD_UNDECODABLE", - false, - "the payload could not be decoded into the handler's type", - Optional.of(undecodable.getClass().getSimpleName()))); - } - - Duration timeout = profile.consumer().handlerTimeout(); - MessageDelivery typed = - new MessageDelivery<>( - envelope.withPayload(payload), - delivery.metadata(), - new DeliveryContext(clock.instant().plus(timeout), false, consumerId)); - - CompletionStage outcome; - try { - outcome = handler.handle(typed); - } catch (RuntimeException handlerFailed) { - // A handler that threw is a retry, not a discard. Treating an exception as "this message is - // undeliverable" is how a transient bug in one consumer silently drops a day of traffic. - return settlement.requeue(); - } - if (outcome == null) { - return settlement.requeue(); - } - return outcome - .handle( - (result, failure) -> - failure == null ? Optional.ofNullable(result) : Optional.empty()) - .thenCompose( - result -> - result.isEmpty() - ? settlement.requeue() - : settle(result.get(), delivery, settlement)); - } - - private CompletionStage settle( - HandleResult result, TransportDelivery delivery, OneShotSettlement settlement) { - return switch (result) { - case HandleResult.Success ignored -> settlement.acknowledge(); - case HandleResult.Retry ignored -> settlement.requeue(); - case HandleResult.Reject reject -> - profile.deliveryGuarantee() == DeliveryGuarantee.AT_MOST_ONCE - ? settlement.discard() - // Discarding on an at-least-once destination would drop a message the profile - // promised to deliver, so the rejection is kept where someone can look at it. - : deadLetter(delivery, settlement, reject.failure()); - case HandleResult.DeadLetter deadLetter -> - deadLetter(delivery, settlement, deadLetter.failure()); - }; - } - - private CompletionStage deadLetter( - TransportDelivery delivery, OneShotSettlement settlement, FailureDescriptor failure) { - if (!profile.deadLetter().enabled()) { - // Nowhere to put it. Requeueing keeps the only copy; the transport's retry budget decides - // whether the partition then parks it or keeps it. - return settlement.requeue(); - } - MessageDelivery encoded = - new MessageDelivery<>( - delivery.envelope(), - delivery.metadata(), - new DeliveryContext(clock.instant(), false, consumerId)); - CompletionStage published; - try { - published = deadLetters.publish(encoded, failure); - } catch (RuntimeException publishFailed) { - return settlement.requeue(); - } - return published - .handle((completion, error) -> error == null && completion == PublishCompletion.CONFIRMED) - .thenCompose(confirmed -> confirmed ? settlement.acknowledge() : settlement.requeue()); - } - - /** Publishes a delivery that cannot be handled to its dead-letter destination. */ - @FunctionalInterface - public interface DeadLetterPublisher { - - /** - * Publishes and reports what the broker confirmed. - * - * @param delivery the delivery, still encoded - * @param failure why it is being dead-lettered - * @return a stage completing with the publish completion - */ - CompletionStage publish( - MessageDelivery delivery, FailureDescriptor failure); - } - - /** A settlement that can be used once. */ - private static final class OneShotSettlement { - - private final TransportDelivery delivery; - - private final AtomicBoolean settled = new AtomicBoolean(); - - private OneShotSettlement(TransportDelivery delivery) { - this.delivery = delivery; - } - - private CompletionStage acknowledge() { - return once("acknowledge", () -> delivery.settlement().acknowledge()); - } - - private CompletionStage requeue() { - // The delay is the transport's retry policy; zero asks for "as soon as that policy allows". - return once("requeue", () -> delivery.settlement().requeue(Duration.ZERO)); - } - - private CompletionStage discard() { - return once("discard", () -> delivery.settlement().discard()); - } - - private CompletionStage once( - String what, Supplier> call) { - if (!settled.compareAndSet(false, true)) { - return CompletableFuture.failedFuture( - new IllegalStateException( - "this delivery has already been settled; a second " - + what - + " would tell the broker something the first call already contradicted")); - } - return call.get().thenApply(ignored -> null); - } - } -} diff --git a/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java b/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java deleted file mode 100644 index 5c4341e3..00000000 --- a/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java +++ /dev/null @@ -1,417 +0,0 @@ -package dev.caskeleton.messaging.runtime; - -import dev.caskeleton.messaging.api.MessageEnvelope; -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.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.policy.MessagingAdmissionController; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.schema.EncodedMessagePublisher; -import dev.caskeleton.messaging.schema.MessageCodec; -import dev.caskeleton.messaging.schema.MessageCodecRegistry; -import dev.caskeleton.messaging.security.DestinationAccessPolicy; -import dev.caskeleton.messaging.transport.MessagingRuntimeLease; -import dev.caskeleton.messaging.transport.MessagingRuntimeRegistry; -import dev.caskeleton.messaging.transport.MessagingTransport; -import dev.caskeleton.messaging.transport.TransportPublishRequest; -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.function.LongSupplier; - -/** - * The one publish path: resolve, authorize, encode, admit, lease, send, normalize. - * - *

{@code MessagePublisher} was an interface with no implementation. The brokers implemented - * {@code MessagingTransport}, which takes an already-resolved profile and already-encoded bytes; - * the core auto-configuration built a dead-letter orchestrator and blocking/reactive facades on top - * of a publisher bean nothing supplied; and the admission controller, access policy, runtime - * registry and observation existed as beans that no publish ever called. An application that filled - * the gap with its own publisher would pass a context test while running none of them. - * - *

The order below is fixed, not composed from a map of interceptors. Each stage's position is a - * decision: - * - *

- * - *

Everything acquired is released exactly once, on every path — success, failure, exception and - * cancellation. A permit or lease that leaks on the failure path is a limiter that shrinks by one - * per failure until it stops accepting anything. - */ -public final class DefaultMessagePublisher implements MessagePublisher, EncodedMessagePublisher { - - private final DestinationProfileRegistry destinations; - - private final DestinationAccessPolicy access; - - private final MessageCodecRegistry codecs; - - private final MessagingAdmissionController admission; - - private final MessagingRuntimeRegistry runtimes; - - private final MessagingTransport transport; - - private final LongSupplier nanoTime; - - /** - * Where every publish outcome is recorded. - * - *

{@code MessagingObservation} existed as a bean and no publish path called it, so the - * platform's own metrics described nothing. It is a constructor argument rather than an optional - * decorator because an unobserved publish path is how "the dashboards were empty during the - * incident" happens. - */ - private final dev.caskeleton.messaging.observation.MessagingObservation observation; - - public DefaultMessagePublisher( - DestinationProfileRegistry destinations, - DestinationAccessPolicy access, - MessageCodecRegistry codecs, - MessagingAdmissionController admission, - MessagingRuntimeRegistry runtimes, - MessagingTransport transport) { - this( - destinations, - access, - codecs, - admission, - runtimes, - transport, - System::nanoTime, - NO_OBSERVATION); - } - - /** A no-op observation, for a deployment that has not wired metrics. */ - private static final dev.caskeleton.messaging.observation.MessagingObservation NO_OBSERVATION = - new dev.caskeleton.messaging.observation.MessagingObservation() { - @Override - public void recordPublish( - dev.caskeleton.messaging.observation.MessagingTags tags, Duration elapsed) {} - - @Override - public void recordDelivery( - dev.caskeleton.messaging.observation.MessagingTags tags, - Duration elapsed, - int attempt) {} - - @Override - public void recordSettlement(dev.caskeleton.messaging.observation.MessagingTags tags) {} - - @Override - public void recordBacklog( - dev.caskeleton.messaging.observation.MessagingTags tags, long messages) {} - - @Override - public void recordDiagnostics( - dev.caskeleton.messaging.observation.MessagingTags tags, - java.util.Map diagnostics) {} - }; - - /** A publisher with an injectable clock, so elapsed time is testable without sleeping. */ - public DefaultMessagePublisher( - DestinationProfileRegistry destinations, - DestinationAccessPolicy access, - MessageCodecRegistry codecs, - MessagingAdmissionController admission, - MessagingRuntimeRegistry runtimes, - MessagingTransport transport, - LongSupplier nanoTime) { - this(destinations, access, codecs, admission, runtimes, transport, nanoTime, NO_OBSERVATION); - } - - /** A publisher that records every outcome. */ - public DefaultMessagePublisher( - DestinationProfileRegistry destinations, - DestinationAccessPolicy access, - MessageCodecRegistry codecs, - MessagingAdmissionController admission, - MessagingRuntimeRegistry runtimes, - MessagingTransport transport, - LongSupplier nanoTime, - dev.caskeleton.messaging.observation.MessagingObservation observation) { - this.observation = Objects.requireNonNull(observation, "observation must not be null"); - this.destinations = Objects.requireNonNull(destinations, "destinations must not be null"); - this.access = Objects.requireNonNull(access, "access must not be null"); - this.codecs = Objects.requireNonNull(codecs, "codecs must not be null"); - this.admission = Objects.requireNonNull(admission, "admission must not be null"); - this.runtimes = Objects.requireNonNull(runtimes, "runtimes must not be null"); - this.transport = Objects.requireNonNull(transport, "transport must not be null"); - this.nanoTime = Objects.requireNonNull(nanoTime, "nanoTime must not be null"); - } - - @Override - public CompletionStage publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(message, "message must not be null"); - Objects.requireNonNull(options, "options must not be null"); - - long startedAt = nanoTime.getAsLong(); - DestinationProfile profile; - MessageEnvelope encoded; - try { - profile = destinations.require(destination.name()); - requireSupportedOptions(profile, options); - if (!access.mayPublish(destination.name())) { - return rejected( - "PUBLISH_FORBIDDEN", - "this application may not publish to '" + destination.name().value() + "'", - startedAt); - } - encoded = encode(message); - } catch (RuntimeException beforeTheWire) { - return rejected("PUBLISH_PREPARATION_FAILED", sanitized(beforeTheWire), startedAt); - } - return sendEncoded(destination, profile, encoded, options, startedAt); - } - - @Override - public CompletionStage publishEncoded( - MessageDestination destination, - MessageEnvelope message, - PublishOptions options) { - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(message, "message must not be null"); - Objects.requireNonNull(options, "options must not be null"); - - long startedAt = nanoTime.getAsLong(); - DestinationProfile profile; - try { - profile = destinations.require(destination.name()); - requireSupportedOptions(profile, options); - if (!access.mayPublish(destination.name())) { - return rejected( - "PUBLISH_FORBIDDEN", - "this application may not publish to '" + destination.name().value() + "'", - startedAt); - } - requireEncodedEnvelope(message); - } catch (RuntimeException beforeTheWire) { - return rejected("PUBLISH_PREPARATION_FAILED", sanitized(beforeTheWire), startedAt); - } - return sendEncoded(destination, profile, message, options, startedAt); - } - - private CompletionStage sendEncoded( - MessageDestination destination, - DestinationProfile profile, - MessageEnvelope encoded, - PublishOptions options, - long startedAt) { - Duration remaining = remainingBudget(options.timeout(), startedAt); - if (remaining.isZero() || remaining.isNegative()) { - return rejected( - "PUBLISH_DEADLINE_EXCEEDED", - "the " - + options.timeout().toMillis() - + "ms publish deadline passed before the message reached the transport", - startedAt); - } - - // Refusals are results, not exceptions. They were thrown out of publish() on the caller's - // thread, so a CompletionStage caller — the outbox relay, the reactive facade — saw neither a - // REJECTED result nor a failed stage. The permit wait is bounded by what is left of the - // caller's deadline, not by the limiter's own bound. - try { - admission.admit(destination.name().value(), encoded.payload().bytes().length, remaining); - } catch (dev.caskeleton.messaging.api.error.MessageTooLargeException - | dev.caskeleton.messaging.api.error.MessageBackpressureException refused) { - return refused(refused.failure(), startedAt); - } - MessagingRuntimeLease lease = null; - try { - lease = runtimes.acquire(profile.broker()); - MessagingRuntimeLease held = lease; - return withDeadline( - transport.publish(new TransportPublishRequest(profile, encoded, options)), remaining) - .handle( - (result, failure) -> { - held.close(); - admission.complete(destination.name().value()); - if (failure != null) { - PublishResult ambiguous = - isDeadline(failure) - ? ambiguousResult( - "PUBLISH_DEADLINE_EXCEEDED", - "no broker outcome within the " - + options.timeout().toMillis() - + "ms publish deadline", - startedAt) - : ambiguousResult( - "PUBLISH_OUTCOME_UNKNOWN", sanitized(failure), startedAt); - observe(profile, ambiguous, startedAt); - return ambiguous; - } - observe(profile, result.result(), startedAt); - return result.result(); - }); - } catch (RuntimeException beforeTheSend) { - if (lease != null) { - lease.close(); - } - admission.complete(destination.name().value()); - // No runtime to send through — the registry closed during shutdown, or none is installed - // yet. Nothing about the message was wrong, so the refusal is marked retryable: a caller that - // trusts the flag retries it instead of parking it. - return refused( - new FailureDescriptor( - FailureCategory.TRANSIENT_INFRASTRUCTURE, - "PUBLISH_RUNTIME_UNAVAILABLE", - true, - sanitized(beforeTheSend), - Optional.empty()), - startedAt); - } - } - - private static void requireEncodedEnvelope(MessageEnvelope message) { - if (!message.contentType().equals(message.payload().contentType())) { - throw new IllegalArgumentException( - "pre-encoded envelope content type must match its encoded payload content type"); - } - } - - /** - * Refuses options the destination cannot honour, before anything is encoded or sent. - * - *

The transports accept {@code request.options()} and read nothing from it, so an option this - * destination cannot honour has to be refused here or it is honoured nowhere. A caller asking for - * broker-side deduplication got a publish with no deduplication and no error, and then skipped - * the idempotency it would otherwise have written — which is exactly the case {@code - * PublishDeduplication}'s own javadoc says must be a startup failure rather than a silent no-op. - */ - private void requireSupportedOptions(DestinationProfile profile, PublishOptions options) { - if (options.deduplication().isPresent() - && !transport - .capabilities(profile.name()) - .capabilities() - .supports( - dev.caskeleton.messaging.api.destination.MessagingCapabilities.Capability - .DEDUPLICATED_PUBLISH)) { - throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException( - "PUBLISH_DEDUPLICATION_UNSUPPORTED", - "destination '" - + profile.name().value() - + "' runs on a broker that does not suppress duplicate publishes of a stable id;" - + " the caller must keep its own idempotency rather than believing this request"); - } - } - - /** Records one publish against bounded dimensions: broker, destination, operation, outcome. */ - private void observe(DestinationProfile profile, PublishResult result, long startedAt) { - observation.recordPublish( - dev.caskeleton.messaging.observation.MessagingTags.of( - profile.broker(), - profile.name().value(), - "publish", - result.completion().name().toLowerCase(java.util.Locale.ROOT)), - elapsedSince(startedAt)); - } - - 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()); - return message.withPayload(bytes); - } - - private CompletionStage rejected(String code, String reason, long startedAt) { - return refused( - new FailureDescriptor(FailureCategory.CONFIGURATION, code, false, reason, Optional.empty()), - startedAt); - } - - private CompletionStage refused(FailureDescriptor failure, long startedAt) { - return CompletableFuture.completedFuture( - PublishResult.rejected(elapsedSince(startedAt), failure)); - } - - private PublishResult ambiguousResult(String code, String reason, long startedAt) { - return PublishResult.ambiguous( - elapsedSince(startedAt), - new FailureDescriptor(FailureCategory.AMBIGUOUS, code, true, reason, Optional.empty())); - } - - /** - * Returns what is left of the caller's deadline. - * - *

Measured from the call, not from the send. {@code PublishOptions.timeout()} is documented as - * the publish operation's deadline, so a slow destination lookup or a large encode spends the - * same budget the broker wait does; timing only the transport call would let the total exceed the - * deadline by however long preparation took. - */ - private Duration remainingBudget(Duration timeout, long startedAt) { - return timeout.minus(elapsedSince(startedAt)); - } - - /** - * Bounds the wait for a broker outcome. - * - *

The transports accepted {@code request.options()} and read nothing from it, so the deadline - * belonged to whatever the broker client happened to be configured with — a Rabbit publish - * waiting on a confirm that never arrives had no deadline at all, and the caller's thread was - * pinned to a stage that could not complete. - * - *

The bound is applied to a copy so that expiry never completes the transport's own stage: the - * adapter still owns its in-flight publish and its own bookkeeping. The permit and the runtime - * lease are released when the copy completes, which is deliberate — holding them until a stalled - * broker answers is how a rotation waits forever on a generation nobody is using. - */ - private static CompletableFuture - withDeadline( - CompletionStage inFlight, - Duration remaining) { - return inFlight - .toCompletableFuture() - .copy() - .orTimeout(remaining.toMillis(), java.util.concurrent.TimeUnit.MILLISECONDS); - } - - /** Reports whether a stage failed because the deadline passed rather than because of a broker. */ - private static boolean isDeadline(Throwable failure) { - Throwable cause = - failure instanceof java.util.concurrent.CompletionException && failure.getCause() != null - ? failure.getCause() - : failure; - return cause instanceof java.util.concurrent.TimeoutException; - } - - /** - * A failure's type, never its message. - * - *

A driver message can carry a routing key, a payload fragment or a connection string, and a - * {@code FailureDescriptor} is designed to be logged and exported. - */ - private static String sanitized(Throwable failure) { - Throwable cause = - failure instanceof java.util.concurrent.CompletionException && failure.getCause() != null - ? failure.getCause() - : failure; - return cause.getClass().getSimpleName(); - } - - private Duration elapsedSince(long startedAt) { - return Duration.ofNanos(Math.max(0, nanoTime.getAsLong() - startedAt)); - } -} diff --git a/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DestinationProfileRegistry.java b/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DestinationProfileRegistry.java deleted file mode 100644 index ea32eafc..00000000 --- a/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DestinationProfileRegistry.java +++ /dev/null @@ -1,62 +0,0 @@ -package dev.caskeleton.messaging.runtime; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.policy.DestinationProfile; -import java.util.LinkedHashMap; -import java.util.Map; -import java.util.Objects; - -/** - * The closed set of destinations this application may publish to. - * - *

Nothing resolved a logical destination to a profile before this: the brokers took an - * already-resolved {@code DestinationProfile} and the publisher that would have produced one did - * not exist. A registry rather than a lookup with a fallback, because a destination nobody declared - * has no physical name, no ordering guarantee and no payload bound — publishing to it would mean - * inventing all three at the call site. - */ -public final class DestinationProfileRegistry { - - private final Map profiles; - - private DestinationProfileRegistry(Map profiles) { - this.profiles = Map.copyOf(profiles); - } - - /** A registry over the given profiles. */ - public static DestinationProfileRegistry of(Map profiles) { - return new DestinationProfileRegistry( - new LinkedHashMap<>(Objects.requireNonNull(profiles, "profiles must not be null"))); - } - - /** An empty registry: every publish is refused until a destination is declared. */ - public static DestinationProfileRegistry empty() { - return new DestinationProfileRegistry(Map.of()); - } - - /** - * The profile for a destination. - * - * @throws MessagingConfigurationException naming the destination, because an unknown destination - * is a configuration mistake and not something to guess a default for - */ - public DestinationProfile require(DestinationName destination) { - Objects.requireNonNull(destination, "destination must not be null"); - DestinationProfile profile = profiles.get(destination); - if (profile == null) { - throw new MessagingConfigurationException( - "DESTINATION_NOT_REGISTERED", - "destination '" - + destination.value() - + "' has no registered profile; publishing to it would invent its physical name," - + " ordering guarantee and payload bound at the call site"); - } - return profile; - } - - /** How many destinations are declared. */ - public int size() { - return profiles.size(); - } -} diff --git a/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/RegisteredMessageCodecs.java b/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/RegisteredMessageCodecs.java deleted file mode 100644 index 8f153ad4..00000000 --- a/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/RegisteredMessageCodecs.java +++ /dev/null @@ -1,89 +0,0 @@ -package dev.caskeleton.messaging.runtime; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.schema.MessageCodec; -import dev.caskeleton.messaging.schema.MessageCodecRegistry; -import java.util.LinkedHashMap; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; - -/** - * The codec registry the publisher resolves against (MSG-INT-003). - * - *

{@link MessageCodecRegistry} was an interface with no implementation anywhere — declared, - * consumed by {@link DefaultMessagePublisher}, and satisfiable by nothing. That is why the platform - * could not assemble a publisher even though every piece around it existed: the publisher's - * constructor named a type the repository never built. - * - *

The default codec is a deliberate choice rather than "the first one registered". Selecting one - * by iteration order means the encoding a message is written with depends on how the map was - * populated, which is a wire-format decision made by accident. The registry takes it explicitly and - * refuses to be constructed without it. - * - *

The raw-bytes codec is never eligible as the default — that is the contract's own rule, and - * the reason is that raw bytes silently disable schema validation for every destination that forgot - * to declare an encoding. A registry that could default to it would turn a missing declaration into - * a skipped check. - */ -public final class RegisteredMessageCodecs implements MessageCodecRegistry { - - private final Map byContentType; - private final MessageCodec defaultCodec; - - private RegisteredMessageCodecs( - Map byContentType, MessageCodec defaultCodec) { - this.byContentType = Map.copyOf(byContentType); - this.defaultCodec = defaultCodec; - } - - /** - * Builds a registry from the codecs a deployment composed. - * - * @param defaultCodec the codec a destination with no declared encoding is written with - * @param codecs every codec available, including the default - * @return the registry - * @throws IllegalArgumentException when two codecs claim one content type, or the default is the - * raw-bytes codec - */ - public static RegisteredMessageCodecs of(MessageCodec defaultCodec, MessageCodec... codecs) { - Objects.requireNonNull(defaultCodec, "defaultCodec"); - Objects.requireNonNull(codecs, "codecs"); - if (ContentType.OCTET_STREAM.equals(defaultCodec.contentType())) { - throw new IllegalArgumentException( - "the raw bytes codec must not be the default: every destination that has not declared an " - + "encoding would silently skip schema validation"); - } - - Map byContentType = new LinkedHashMap<>(); - register(byContentType, defaultCodec); - for (MessageCodec codec : codecs) { - register(byContentType, codec); - } - return new RegisteredMessageCodecs(byContentType, defaultCodec); - } - - private static void register(Map into, MessageCodec codec) { - Objects.requireNonNull(codec, "codec"); - MessageCodec existing = into.putIfAbsent(codec.contentType(), codec); - if (existing != null && existing != codec) { - // Two codecs for one content type is not a preference to resolve at runtime: whichever wins - // decides how bytes on the wire are read by a consumer that was compiled against the other. - throw new IllegalArgumentException( - "two codecs claim content type " - + codec.contentType() - + "; a deployment must choose one"); - } - } - - @Override - public Optional find(ContentType contentType) { - Objects.requireNonNull(contentType, "contentType"); - return Optional.ofNullable(byContentType.get(contentType)); - } - - @Override - public MessageCodec defaultCodec() { - return defaultCodec; - } -} diff --git a/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/TransportMessagingRuntime.java b/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/TransportMessagingRuntime.java deleted file mode 100644 index bf8579ec..00000000 --- a/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/TransportMessagingRuntime.java +++ /dev/null @@ -1,67 +0,0 @@ -package dev.caskeleton.messaging.runtime; - -import dev.caskeleton.messaging.transport.MessagingRuntime; -import dev.caskeleton.messaging.transport.MessagingTransport; -import java.util.Objects; -import java.util.concurrent.atomic.AtomicBoolean; - -/** - * One transport, presented as the runtime the registry leases (MSG-INT-003). - * - *

{@link MessagingRuntime} had no implementation, so nothing could be installed into {@code - * DefaultMessagingRuntimeRegistry} and every publish failed at {@code PUBLISH_RUNTIME_UNAVAILABLE} - * — a registry constructed empty, which is the same shape the notification provider registry had. - * - *

The generation is the credential generation a rotation increments; the registry drains leases - * per generation, which is what lets a rotated credential retire without cutting live publishes. - */ -public final class TransportMessagingRuntime implements MessagingRuntime { - - private final String brokerName; - private final long generation; - private final MessagingTransport transport; - private final AtomicBoolean closed = new AtomicBoolean(); - - /** - * Creates the runtime. - * - * @param brokerName the broker id destination profiles name - * @param generation the credential generation - * @param transport the transport publishes go through - */ - public TransportMessagingRuntime( - String brokerName, long generation, MessagingTransport transport) { - this.brokerName = Objects.requireNonNull(brokerName, "brokerName"); - this.generation = generation; - this.transport = Objects.requireNonNull(transport, "transport"); - } - - @Override - public String brokerName() { - return brokerName; - } - - @Override - public long generation() { - return generation; - } - - @Override - public MessagingTransport transport() { - return transport; - } - - @Override - public boolean isClosed() { - return closed.get(); - } - - @Override - public void close() { - // Idempotent: the registry closes a drained generation, and a context shutdown may close it - // again. Closing a transport twice is not an error worth propagating into shutdown. - if (closed.compareAndSet(false, true)) { - transport.close(); - } - } -} diff --git a/src/platforms/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessorTest.java b/src/platforms/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessorTest.java deleted file mode 100644 index 8cff2f21..00000000 --- a/src/platforms/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessorTest.java +++ /dev/null @@ -1,450 +0,0 @@ -package dev.caskeleton.messaging.runtime; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.catchThrowable; - -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.DeliveryMetadata; -import dev.caskeleton.messaging.api.delivery.HandleResult; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -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.header.MessageHeaders; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.settlement.SettlementResult; -import dev.caskeleton.messaging.policy.DeadLetterPolicy; -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.schema.MessageCodec; -import dev.caskeleton.messaging.transport.TransportDelivery; -import dev.caskeleton.messaging.transport.TransportSettlement; -import java.nio.charset.StandardCharsets; -import java.time.Duration; -import java.time.Instant; -import java.time.InstantSource; -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.function.Function; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * One typed handler, one outcome, one settlement. - * - *

The processor took an untyped function and nothing assembled it; the typed {@code - * MessageHandler} had no caller (S7-#2). These tests hold the settlement rules on the one contract - * that is left. - */ -class DefaultDeliveryProcessorTest { - - private static final DestinationName ORDERS = new DestinationName("order-events"); - private static final MessageType CREATED = new MessageType("order.created"); - private static final Instant NOW = Instant.parse("2026-08-14T00:00:00Z"); - - private final RecordingSettlement settlement = new RecordingSettlement(); - - @Test - @DisplayName("성공하면 handler가 decode된 payload를 받고 한 번 acknowledge된다") - void aSuccessfulHandlerReceivesTheDecodedPayloadAndIsAcknowledgedOnce() { - // given - List received = new ArrayList<>(); - MessageHandler handler = - handler( - delivery -> { - received.add(delivery.message().payload()); - return HandleResult.success(); - }); - - // when - process(handler, confirmedDeadLetters(), RuntimeFixtures.profile(ORDERS)); - - // then - assertThat(received).containsExactly("{\"orderId\":\"o-1\"}"); - assertThat(settlement.calls()).containsExactly("acknowledge"); - } - - @Test - @DisplayName("Retry 결과는 requeue된다") - void aRetryResultIsRequeued() { - // when - process( - handler(delivery -> new HandleResult.Retry(failure())), - confirmedDeadLetters(), - RuntimeFixtures.profile(ORDERS)); - - // then - assertThat(settlement.calls()).containsExactly("requeue"); - } - - @Test - @DisplayName("예외를 던진 handler는 버려지지 않고 requeue된다") - void aThrowingHandlerIsRequeuedNotDiscarded() { - // when - process( - handler( - delivery -> { - throw new IllegalStateException("a bug in the projection"); - }), - confirmedDeadLetters(), - RuntimeFixtures.profile(ORDERS)); - - // then - assertThat(settlement.calls()).containsExactly("requeue"); - } - - @Test - @DisplayName("실패로 끝난 stage를 돌려준 handler는 requeue된다") - void aHandlerWhoseStageFailsIsRequeued() { - // given - MessageHandler handler = - new StringHandler( - delivery -> { - throw new UnsupportedOperationException("unused"); - }) { - @Override - public CompletionStage handle(MessageDelivery delivery) { - return CompletableFuture.failedFuture(new IllegalStateException("database down")); - } - }; - - // when - process(handler, confirmedDeadLetters(), RuntimeFixtures.profile(ORDERS)); - - // then - assertThat(settlement.calls()).containsExactly("requeue"); - } - - @Test - @DisplayName("dead letter는 발행이 확인된 뒤에 source를 acknowledge한다") - void aDeadLetterIsPublishedBeforeTheSourceIsAcknowledged() { - // given - List order = new ArrayList<>(); - DefaultDeliveryProcessor.DeadLetterPublisher publisher = - (delivery, failure) -> { - order.add("dead-letter published"); - return CompletableFuture.completedFuture(PublishCompletion.CONFIRMED); - }; - settlement.recordInto(order); - - // when - process( - handler(delivery -> new HandleResult.DeadLetter(failure())), - publisher, - RuntimeFixtures.profile(ORDERS)); - - // then - assertThat(order).containsExactly("dead-letter published", "acknowledge"); - } - - @Test - @DisplayName("확인되지 않은 dead letter는 acknowledge하지 않고 requeue한다") - void anUnconfirmedDeadLetterIsRequeued() { - // when - process( - handler(delivery -> new HandleResult.DeadLetter(failure())), - (delivery, failure) -> CompletableFuture.completedFuture(PublishCompletion.AMBIGUOUS), - RuntimeFixtures.profile(ORDERS)); - - // then - assertThat(settlement.calls()).containsExactly("requeue"); - } - - @Test - @DisplayName("at-least-once destination의 Reject는 버리지 않고 dead letter로 보낸다") - void aRejectOnAnAtLeastOnceDestinationIsDeadLetteredNotDiscarded() { - // given - List deadLettered = new ArrayList<>(); - - // when - process( - handler(delivery -> new HandleResult.Reject(failure())), - (delivery, failure) -> { - deadLettered.add(failure); - return CompletableFuture.completedFuture(PublishCompletion.CONFIRMED); - }, - RuntimeFixtures.profile(ORDERS)); - - // then - assertThat(deadLettered).containsExactly(failure()); - assertThat(settlement.calls()).containsExactly("acknowledge"); - } - - @Test - @DisplayName("at-most-once destination의 Reject는 discard된다") - void aRejectOnAnAtMostOnceDestinationIsDiscarded() { - // when - process( - handler(delivery -> new HandleResult.Reject(failure())), - confirmedDeadLetters(), - atMostOnce(RuntimeFixtures.profile(ORDERS))); - - // then - assertThat(settlement.calls()).containsExactly("discard"); - } - - @Test - @DisplayName("handler가 없는 message type은 재시도하지 않고 dead letter로 보낸다") - void aMessageTypeWithNoHandlerIsDeadLetteredInsteadOfRetried() { - // given - List codes = new ArrayList<>(); - MessageHandler otherType = - new StringHandler( - new MessageDestination<>(ORDERS, new MessageType("order.cancelled"), String.class), - delivery -> HandleResult.success()); - - // when - process( - otherType, - (delivery, failure) -> { - codes.add(failure.code()); - return CompletableFuture.completedFuture(PublishCompletion.CONFIRMED); - }, - RuntimeFixtures.profile(ORDERS)); - - // then - assertThat(codes).containsExactly("NO_HANDLER_FOR_MESSAGE_TYPE"); - assertThat(settlement.calls()).containsExactly("acknowledge"); - } - - @Test - @DisplayName("dead letter destination이 없으면 dead letter 대신 requeue해 유일한 사본을 지킨다") - void withoutADeadLetterDestinationADeadLetterIsRequeuedToKeepTheOnlyCopy() { - // when - process( - handler(delivery -> new HandleResult.DeadLetter(failure())), - confirmedDeadLetters(), - withoutDeadLetter(RuntimeFixtures.profile(ORDERS))); - - // then - assertThat(settlement.calls()).containsExactly("requeue"); - } - - @Test - @DisplayName("한 message type에 handler가 둘이면 processor를 만들 수 없다") - void twoHandlersForOneMessageTypeAreRefused() { - // given - List> twice = - List.of(handler(delivery -> HandleResult.success()), handler(delivery -> null)); - - // when - Throwable thrown = - catchThrowable( - () -> - new DefaultDeliveryProcessor( - RuntimeFixtures.profile(ORDERS), - twice, - RegisteredMessageCodecs.of(new Utf8Codec()), - confirmedDeadLetters(), - "order-projection", - InstantSource.fixed(NOW))); - - // then - assertThat(thrown) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("two handlers for order.created"); - } - - private void process( - MessageHandler handler, - DefaultDeliveryProcessor.DeadLetterPublisher deadLetters, - DestinationProfile profile) { - new DefaultDeliveryProcessor( - profile, - List.of(handler), - RegisteredMessageCodecs.of(new Utf8Codec()), - deadLetters, - "order-projection", - InstantSource.fixed(NOW)) - .process(new TransportDelivery(envelope(), metadata(), settlement)) - .toCompletableFuture() - .join(); - } - - private static MessageHandler handler( - Function, HandleResult> body) { - return new StringHandler(body); - } - - private static DefaultDeliveryProcessor.DeadLetterPublisher confirmedDeadLetters() { - return (delivery, failure) -> CompletableFuture.completedFuture(PublishCompletion.CONFIRMED); - } - - private static DestinationProfile atMostOnce(DestinationProfile base) { - return new DestinationProfile( - base.name(), - base.broker(), - base.kind(), - base.physical(), - base.schema(), - DeliveryGuarantee.AT_MOST_ONCE, - base.orderingScope(), - base.externalSideEffectGuarantee(), - base.producer(), - base.consumer(), - base.retry(), - base.deadLetter(), - base.payload(), - base.tier(), - base.production(), - base.keyResolverConfigured(), - base.topologyAutoCreate()); - } - - private static DestinationProfile withoutDeadLetter(DestinationProfile base) { - return new DestinationProfile( - base.name(), - base.broker(), - base.kind(), - base.physical(), - base.schema(), - base.deliveryGuarantee(), - base.orderingScope(), - base.externalSideEffectGuarantee(), - base.producer(), - base.consumer(), - base.retry(), - DeadLetterPolicy.disabled(), - base.payload(), - base.tier(), - base.production(), - base.keyResolverConfigured(), - base.topologyAutoCreate()); - } - - private static FailureDescriptor failure() { - return new FailureDescriptor( - FailureCategory.PERMANENT_BUSINESS, - "UNPROCESSABLE", - false, - "cannot be applied", - Optional.empty()); - } - - private static DeliveryMetadata metadata() { - return new DeliveryMetadata( - ORDERS, 1, false, Optional.empty(), Optional.empty(), Optional.of("order-projection"), NOW); - } - - private static MessageEnvelope envelope() { - return new MessageEnvelope<>( - MessageId.newId(), - CREATED, - new SchemaVersion(1), - NOW, - Optional.empty(), - new ProducerId("orders"), - 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())); - } - - /** A handler for {@code order.created} whose body is a function. */ - private static class StringHandler implements MessageHandler { - - private final MessageDestination destination; - private final Function, HandleResult> body; - - StringHandler(Function, HandleResult> body) { - this(new MessageDestination<>(ORDERS, CREATED, String.class), body); - } - - StringHandler( - MessageDestination destination, - Function, HandleResult> body) { - this.destination = destination; - this.body = body; - } - - @Override - public MessageDestination destination() { - return destination; - } - - @Override - public CompletionStage handle(MessageDelivery delivery) { - return CompletableFuture.completedFuture(body.apply(delivery)); - } - } - - /** Decodes JSON bytes to the raw string, which is all these tests need. */ - private static final class Utf8Codec implements MessageCodec { - - @Override - public ContentType contentType() { - return ContentType.JSON; - } - - @Override - public EncodedMessage encode(MessageType type, SchemaVersion version, Object payload) { - return new EncodedMessage( - payload.toString().getBytes(StandardCharsets.UTF_8), ContentType.JSON, Optional.empty()); - } - - @Override - public T decode( - MessageType type, SchemaVersion version, byte[] encoded, Class payloadType) { - return payloadType.cast(new String(encoded, StandardCharsets.UTF_8)); - } - } - - /** Records which terminal call the processor made, and in what order. */ - private static final class RecordingSettlement implements TransportSettlement { - - private final List calls = new ArrayList<>(); - - private List shared; - - private void recordInto(List order) { - this.shared = order; - } - - @Override - public CompletionStage acknowledge() { - return record("acknowledge"); - } - - @Override - public CompletionStage requeue(Duration delay) { - return record("requeue"); - } - - @Override - public CompletionStage discard() { - return record("discard"); - } - - private CompletionStage record(String call) { - calls.add(call); - if (shared != null) { - shared.add(call); - } - return CompletableFuture.completedFuture(SettlementResult.settled()); - } - - private List calls() { - return calls; - } - } -} diff --git a/src/platforms/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java b/src/platforms/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java deleted file mode 100644 index 5a9b7504..00000000 --- a/src/platforms/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java +++ /dev/null @@ -1,736 +0,0 @@ -package dev.caskeleton.messaging.runtime; - -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.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; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -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; -import dev.caskeleton.messaging.policy.PayloadPolicy; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.schema.EncodedMessagePublisher; -import dev.caskeleton.messaging.schema.MessageCodec; -import dev.caskeleton.messaging.schema.MessageCodecRegistry; -import dev.caskeleton.messaging.security.DestinationAccessPolicy; -import dev.caskeleton.messaging.transport.MessagingRuntime; -import dev.caskeleton.messaging.transport.MessagingRuntimeLease; -import dev.caskeleton.messaging.transport.MessagingRuntimeRegistry; -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; -import java.util.Map; -import java.util.Optional; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import java.util.concurrent.atomic.AtomicInteger; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * The publish path, end to end, without an application-supplied publisher. - * - *

There was no implementation of {@code MessagePublisher} anywhere in the new platform, so the - * admission controller, the access policy and the runtime registry were beans that no publish ever - * consulted. These tests run the real pipeline against a fake transport. - */ -class DefaultMessagePublisherTest { - - private static final DestinationName ORDERS = new DestinationName("order-events"); - - private final RecordingTransport transport = new RecordingTransport(); - - private final MessagingAdmissionController admission = - new MessagingAdmissionController( - new PayloadLimitGuard(PayloadPolicy.defaults()), - new InFlightLimiter(4, Duration.ofSeconds(1))); - - @Test - @DisplayName("a publish goes through resolution, encoding, admission, lease and transport") - void aPublishRunsTheWholePipeline() { - PublishResult result = - publisher(allowOrders()) - .publish( - new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class), - envelope(), - PublishOptions.defaults()) - .toCompletableFuture() - .join(); - - assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED); - assertThat(transport.published()).isEqualTo(1); - assertThat(admission.inFlight()) - .as("a permit that leaks per publish is a limiter that stops accepting after four") - .isZero(); - } - - @Test - @DisplayName("a pre-encoded publish skips codecs but still runs admission, runtime and transport") - void aPreEncodedPublishPreservesWireBytesWithoutBypassingThePipeline() { - SingleCodecRegistry codecs = new SingleCodecRegistry(); - DefaultMessagePublisher publisher = - new DefaultMessagePublisher( - registry(), - allowOrders(), - codecs, - admission, - new FixedRuntimeRegistry(transport), - transport); - byte[] wireBytes = "{\"already\":\"encoded\"}".getBytes(StandardCharsets.UTF_8); - MessageEnvelope encoded = - envelope().withPayload(new EncodedMessage(wireBytes, ContentType.JSON, Optional.empty())); - - PublishResult result = - ((EncodedMessagePublisher) publisher) - .publishEncoded( - new MessageDestination<>( - ORDERS, new MessageType("order.created"), EncodedMessage.class), - encoded, - PublishOptions.defaults()) - .toCompletableFuture() - .join(); - - assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED); - assertThat(codecs.encodes()).isZero(); - assertThat(transport.lastRequest().envelope().payload().bytes()).containsExactly(wireBytes); - assertThat(transport.lastRequest().envelope().payload().contentType()) - .isEqualTo(ContentType.JSON); - 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() { - DefaultMessagePublisher publisher = - new DefaultMessagePublisher( - DestinationProfileRegistry.empty(), - allowOrders(), - new SingleCodecRegistry(), - admission, - new FixedRuntimeRegistry(transport), - transport); - - PublishResult result = - publisher - .publish( - new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class), - envelope(), - PublishOptions.defaults()) - .toCompletableFuture() - .join(); - - assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); - assertThat(transport.published()).isZero(); - } - - @Test - @DisplayName("a forbidden destination is rejected before the payload is encoded") - void aForbiddenDestinationNeverEncodes() { - SingleCodecRegistry codecs = new SingleCodecRegistry(); - DefaultMessagePublisher publisher = - new DefaultMessagePublisher( - registry(), - DestinationAccessPolicy.denyAll(), - codecs, - admission, - new FixedRuntimeRegistry(transport), - transport); - - PublishResult result = - publisher - .publish( - new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class), - envelope(), - PublishOptions.defaults()) - .toCompletableFuture() - .join(); - - assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); - assertThat(codecs.encodes()) - .as("the encoded bytes are what a claim check or a log would then be holding") - .isZero(); - assertThat(admission.inFlight()).isZero(); - } - - @Test - @DisplayName("a transport failure is ambiguous, not rejected") - void aTransportFailureIsAmbiguous() { - transport.failWith(new IllegalStateException("connection reset")); - - PublishResult result = - publisher(allowOrders()) - .publish( - new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class), - envelope(), - PublishOptions.defaults()) - .toCompletableFuture() - .join(); - - assertThat(result.completion()) - .as("the request was on the wire, so the broker may hold it") - .isEqualTo(PublishCompletion.AMBIGUOUS); - assertThat(result.failure().orElseThrow().sanitizedMessage()) - .as("a driver message can carry a routing key or a payload fragment") - .isEqualTo("IllegalStateException"); - assertThat(admission.inFlight()).isZero(); - } - - @Test - @DisplayName("a broker that never answers is ambiguous at the caller's deadline") - void aStalledBrokerIsAmbiguousAtTheDeadline() { - transport.stall(); - - CompletableFuture pending = - publisher(allowOrders()) - .publish( - new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class), - envelope(), - withTimeout(Duration.ofMillis(120))) - .toCompletableFuture(); - - // Bounded rather than joined: with no deadline of its own this stage never completes, and a - // test that waits forever reports a hang instead of the missing deadline. - assertThat(pending).succeedsWithin(Duration.ofSeconds(5)); - PublishResult result = pending.join(); - - assertThat(result.completion()) - .as("the message reached the transport, so the broker may hold it") - .isEqualTo(PublishCompletion.AMBIGUOUS); - assertThat(result.failure().orElseThrow().code()).isEqualTo("PUBLISH_DEADLINE_EXCEEDED"); - assertThat(admission.inFlight()) - .as("a permit held until a stalled broker answers is a permit never returned") - .isZero(); - } - - @Test - @DisplayName("a deadline spent before the send rejects instead of publishing") - void aDeadlineSpentBeforeTheSendRejects() { - // Preparation is inside the deadline, not before it: resolution and encoding spend the same - // budget the broker wait does. - AtomicInteger reads = new AtomicInteger(); - DefaultMessagePublisher publisher = - new DefaultMessagePublisher( - registry(), - allowOrders(), - new SingleCodecRegistry(), - admission, - new FixedRuntimeRegistry(transport), - transport, - () -> Duration.ofSeconds(6L * reads.getAndIncrement()).toNanos()); - - PublishResult result = - publisher - .publish( - new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class), - envelope(), - withTimeout(Duration.ofSeconds(5))) - .toCompletableFuture() - .join(); - - assertThat(result.completion()) - .as("nothing was transmitted, so the outcome is definite") - .isEqualTo(PublishCompletion.REJECTED); - assertThat(result.failure().orElseThrow().code()).isEqualTo("PUBLISH_DEADLINE_EXCEEDED"); - assertThat(transport.published()).isZero(); - assertThat(admission.inFlight()).isZero(); - } - - @Test - void anOversizedPayloadIsRejectedAsNotRetryableInsteadOfThrown() { - // given - DefaultMessagePublisher publisher = - new DefaultMessagePublisher( - registry(), - allowOrders(), - new SingleCodecRegistry(), - new MessagingAdmissionController( - new PayloadLimitGuard(new PayloadPolicy(4, 4)), - new InFlightLimiter(4, Duration.ofSeconds(1))), - new FixedRuntimeRegistry(transport), - transport); - - // when - CompletableFuture result = - CompletableFuture.supplyAsync( - () -> - publisher - .publish( - new MessageDestination<>( - ORDERS, new MessageType("order.created"), String.class), - envelope(), - PublishOptions.defaults()) - .toCompletableFuture() - .join()); - - // then - assertThat(result) - .succeedsWithin(Duration.ofSeconds(5)) - .extracting( - PublishResult::completion, outcome -> outcome.failure().orElseThrow().retryable()) - .containsExactly(PublishCompletion.REJECTED, false); - } - - @Test - void aSaturatedPermitPoolRejectsAsRetryableWithinTheCallersDeadline() { - // given - DestinationName audit = new DestinationName("audit-events"); - DefaultMessagePublisher publisher = - new DefaultMessagePublisher( - DestinationProfileRegistry.of( - Map.of( - ORDERS, - RuntimeFixtures.profile(ORDERS), - audit, - RuntimeFixtures.profile(audit))), - new DestinationAccessPolicy( - java.util.Set.of(ORDERS, audit), java.util.Set.of(), java.util.Set.of()), - new SingleCodecRegistry(), - new MessagingAdmissionController( - new PayloadLimitGuard(PayloadPolicy.defaults()), - new InFlightLimiter(1, Duration.ofMinutes(1))), - new FixedRuntimeRegistry(transport), - transport); - transport.stall(); - publisher.publish( - new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class), - envelope(), - withTimeout(Duration.ofMinutes(1))); - - // when - CompletableFuture second = - CompletableFuture.supplyAsync( - () -> - publisher - .publish( - new MessageDestination<>( - audit, new MessageType("order.created"), String.class), - envelope(), - withTimeout(Duration.ofMillis(100))) - .toCompletableFuture() - .join()); - - // then - assertThat(second) - .as("the permit wait was the limiter's own minute, not what was left of 100ms") - .succeedsWithin(Duration.ofSeconds(5)) - .extracting( - PublishResult::completion, outcome -> outcome.failure().orElseThrow().retryable()) - .containsExactly(PublishCompletion.REJECTED, true); - } - - @Test - @DisplayName("an unavailable runtime releases the permit it took") - void anUnavailableRuntimeReleasesThePermit() { - DefaultMessagePublisher publisher = - new DefaultMessagePublisher( - registry(), - allowOrders(), - new SingleCodecRegistry(), - admission, - new FailingRuntimeRegistry(), - transport); - - PublishResult result = - publisher - .publish( - new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class), - envelope(), - PublishOptions.defaults()) - .toCompletableFuture() - .join(); - - assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); - assertThat(admission.inFlight()).isZero(); - } - - @Test - @DisplayName("runtime이 없어서 생긴 거부는 다시 시도할 수 있다고 표시한다") - void aRefusalForAnUnavailableRuntimeMayBeRetried() { - // given: the runtime registry closed during shutdown, before this publish acquired it - DefaultMessagePublisher publisher = - new DefaultMessagePublisher( - registry(), - allowOrders(), - new SingleCodecRegistry(), - admission, - new FailingRuntimeRegistry(), - transport); - - // when - PublishResult result = - publisher - .publish( - new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class), - envelope(), - PublishOptions.defaults()) - .toCompletableFuture() - .join(); - - // then: nothing about the message was wrong, so a later attempt may succeed - assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); - assertThat(result.failure()) - .get() - .extracting(FailureDescriptor::code, FailureDescriptor::retryable) - .containsExactly("PUBLISH_RUNTIME_UNAVAILABLE", true); - } - - @Test - @DisplayName("an unregistered destination names itself") - void anUnregisteredDestinationNamesItself() { - assertThatThrownBy(() -> DestinationProfileRegistry.empty().require(ORDERS)) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("order-events"); - } - - @Test - @DisplayName("every publish outcome reaches the observation") - void everyPublishOutcomeIsObserved() { - java.util.List outcomes = new java.util.ArrayList<>(); - DefaultMessagePublisher publisher = - new DefaultMessagePublisher( - registry(), - allowOrders(), - new SingleCodecRegistry(), - admission, - new FixedRuntimeRegistry(transport), - transport, - System::nanoTime, - new dev.caskeleton.messaging.observation.MessagingObservation() { - @Override - public void recordPublish( - dev.caskeleton.messaging.observation.MessagingTags tags, Duration elapsed) { - outcomes.add(tags.asMap().get("outcome")); - } - - @Override - public void recordDelivery( - dev.caskeleton.messaging.observation.MessagingTags tags, - Duration elapsed, - int attempt) {} - - @Override - public void recordSettlement( - dev.caskeleton.messaging.observation.MessagingTags tags) {} - - @Override - public void recordBacklog( - dev.caskeleton.messaging.observation.MessagingTags tags, long messages) {} - - @Override - public void recordDiagnostics( - dev.caskeleton.messaging.observation.MessagingTags tags, - Map diagnostics) {} - }); - - publisher - .publish( - new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class), - envelope(), - PublishOptions.defaults()) - .toCompletableFuture() - .join(); - - assertThat(outcomes) - .as("the observation bean existed and no publish path ever called it") - .containsExactly("confirmed"); - } - - @Test - @DisplayName("a deduplication request a broker cannot honour is refused") - void anUnsupportedDeduplicationRequestIsRefused() { - PublishResult result = - publisher(allowOrders()) - .publish( - new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class), - envelope(), - new PublishOptions( - java.time.Duration.ofSeconds(5), - dev.caskeleton.messaging.api.destination.ConfirmationRequirement - .REPLICATION_OR_PERSISTENCE_ACK, - java.util.Optional.of( - new dev.caskeleton.messaging.api.publish.PublishDeduplication( - "order-1", java.time.Duration.ofMinutes(5))))) - .toCompletableFuture() - .join(); - - assertThat(result.completion()) - .as("accepting it silently is how a caller skips the idempotency it would have written") - .isEqualTo(PublishCompletion.REJECTED); - assertThat(transport.published()).isZero(); - } - - private static PublishOptions withTimeout(Duration timeout) { - return new PublishOptions( - timeout, - dev.caskeleton.messaging.api.destination.ConfirmationRequirement - .REPLICATION_OR_PERSISTENCE_ACK, - Optional.empty()); - } - - private static DestinationAccessPolicy allowOrders() { - return new DestinationAccessPolicy( - java.util.Set.of(ORDERS), java.util.Set.of(), java.util.Set.of()); - } - - private DefaultMessagePublisher publisher(DestinationAccessPolicy access) { - return new DefaultMessagePublisher( - registry(), - access, - new SingleCodecRegistry(), - admission, - new FixedRuntimeRegistry(transport), - transport); - } - - private static DestinationProfileRegistry registry() { - return DestinationProfileRegistry.of(Map.of(ORDERS, RuntimeFixtures.profile(ORDERS))); - } - - private static MessageEnvelope envelope() { - return new MessageEnvelope<>( - MessageId.newId(), - new MessageType("order.created"), - new SchemaVersion(1), - Instant.parse("2026-08-14T00:00:00Z"), - Optional.empty(), - new ProducerId("orders"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - "{\"orderId\":\"o-1\"}"); - } - - /** A codec that counts how often it was asked to encode. */ - private static final class SingleCodecRegistry implements MessageCodecRegistry { - - private final AtomicInteger encodes = new AtomicInteger(); - - @Override - public Optional find(ContentType contentType) { - return Optional.of(codec()); - } - - @Override - public MessageCodec defaultCodec() { - return codec(); - } - - private MessageCodec codec() { - return new MessageCodec() { - @Override - public EncodedMessage encode(MessageType type, SchemaVersion version, Object payload) { - encodes.incrementAndGet(); - return new EncodedMessage( - String.valueOf(payload).getBytes(StandardCharsets.UTF_8), - ContentType.JSON, - Optional.empty()); - } - - @Override - public T decode( - MessageType type, SchemaVersion version, byte[] encoded, Class payloadType) { - return payloadType.cast(new String(encoded, StandardCharsets.UTF_8)); - } - - @Override - public ContentType contentType() { - return ContentType.JSON; - } - }; - } - - private int encodes() { - return encodes.get(); - } - } - - /** A transport that records what reached it. */ - private static final class RecordingTransport implements MessagingTransport { - - private final AtomicInteger published = new AtomicInteger(); - - private RuntimeException failure; - - private boolean stalled; - - private TransportPublishRequest lastRequest; - - private void failWith(RuntimeException failure) { - this.failure = failure; - } - - /** A broker that took the message and never says what happened to it. */ - private void stall() { - this.stalled = true; - } - - @Override - public CompletionStage publish(TransportPublishRequest request) { - this.lastRequest = request; - if (failure != null) { - return CompletableFuture.failedFuture(failure); - } - if (stalled) { - published.incrementAndGet(); - return new CompletableFuture<>(); - } - published.incrementAndGet(); - 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("not used by these tests"); - } - - @Override - public DestinationCapabilities capabilities(DestinationName destination) { - throw new UnsupportedOperationException("not used by these tests"); - } - - @Override - public String brokerName() { - return "fake"; - } - - @Override - public long generation() { - return 1; - } - - @Override - public void close() {} - - private int published() { - return published.get(); - } - - private TransportPublishRequest lastRequest() { - return lastRequest; - } - } - - /** A registry with no installed generation, which is what a rotation gap looks like. */ - private static final class FailingRuntimeRegistry implements MessagingRuntimeRegistry { - - @Override - public void install(MessagingRuntime runtime) {} - - @Override - public MessagingRuntimeLease acquire(String brokerName) { - throw new IllegalStateException("no generation installed"); - } - } - - /** A registry that always hands out a lease on the same transport. */ - private record FixedRuntimeRegistry(MessagingTransport transport) - implements MessagingRuntimeRegistry { - - @Override - public void install(MessagingRuntime runtime) {} - - @Override - public MessagingRuntimeLease acquire(String brokerName) { - return new MessagingRuntimeLease() { - @Override - public MessagingRuntime runtime() { - throw new UnsupportedOperationException("not used by these tests"); - } - - @Override - public void close() {} - }; - } - } -} diff --git a/src/platforms/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/RegisteredMessageCodecsTest.java b/src/platforms/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/RegisteredMessageCodecsTest.java deleted file mode 100644 index a6fc628c..00000000 --- a/src/platforms/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/RegisteredMessageCodecsTest.java +++ /dev/null @@ -1,88 +0,0 @@ -package dev.caskeleton.messaging.runtime; - -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.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.schema.MessageCodec; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * The registry {@link DefaultMessagePublisher} resolves against (MSG-INT-003). - * - *

{@code MessageCodecRegistry} was an interface with no implementation anywhere — declared, - * consumed by the publisher's constructor, and satisfiable by nothing. That is why the platform - * could not assemble a publisher although every piece around it existed and was tested. - */ -class RegisteredMessageCodecsTest { - - @Test - @DisplayName("the default codec is the one the deployment named") - void theDefaultCodecIsTheOneNamed() { - MessageCodec json = codec(ContentType.JSON); - MessageCodec avro = codec(ContentType.AVRO); - - assertThat(RegisteredMessageCodecs.of(json, avro).defaultCodec()) - .as( - "selecting by iteration order makes the wire format depend on how a map was populated — " - + "a format decision taken by accident") - .isSameAs(json); - } - - @Test - @DisplayName("a registered content type resolves, an unregistered one does not") - void aRegisteredContentTypeResolves() { - RegisteredMessageCodecs codecs = - RegisteredMessageCodecs.of(codec(ContentType.JSON), codec(ContentType.AVRO)); - - assertThat(codecs.find(ContentType.AVRO)).isPresent(); - assertThat(codecs.find(ContentType.PROTOBUF)) - .as("absent rather than falling back: a silent fallback re-encodes somebody's message") - .isEmpty(); - } - - @Test - @DisplayName("raw bytes cannot be the default") - void rawBytesCannotBeTheDefault() { - assertThatThrownBy(() -> RegisteredMessageCodecs.of(codec(ContentType.OCTET_STREAM))) - .as( - "a destination that forgot to declare an encoding would silently skip schema " - + "validation, which turns a missing declaration into a skipped check") - .hasMessageContaining("raw bytes codec must not be the default"); - } - - @Test - @DisplayName("two codecs claiming one content type is a configuration error") - void twoCodecsForOneContentTypeIsRefused() { - assertThatThrownBy( - () -> RegisteredMessageCodecs.of(codec(ContentType.JSON), codec(ContentType.JSON))) - .as( - "whichever won would decide how bytes on the wire are read by a consumer compiled " - + "against the other") - .hasMessageContaining("two codecs claim content type"); - } - - private static MessageCodec codec(ContentType contentType) { - return new MessageCodec() { - @Override - public ContentType contentType() { - return contentType; - } - - @Override - public EncodedMessage encode(MessageType type, SchemaVersion version, Object payload) { - throw new UnsupportedOperationException("registry test; nothing is encoded"); - } - - @Override - public T decode( - MessageType type, SchemaVersion version, byte[] bytes, Class payloadType) { - throw new UnsupportedOperationException("registry test; nothing is decoded"); - } - }; - } -} diff --git a/src/platforms/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/RuntimeFixtures.java b/src/platforms/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/RuntimeFixtures.java deleted file mode 100644 index d341d54f..00000000 --- a/src/platforms/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/RuntimeFixtures.java +++ /dev/null @@ -1,44 +0,0 @@ -package dev.caskeleton.messaging.runtime; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.policy.ApiTier; -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.schema.SchemaCompatibility; -import java.util.Set; - -/** One registered destination, so the pipeline has something real to resolve. */ -final class RuntimeFixtures { - - private RuntimeFixtures() {} - - static DestinationProfile profile(DestinationName name) { - return new DestinationProfile( - name, - "fake", - dev.caskeleton.messaging.api.destination.DestinationKind.EVENT_STREAM, - PhysicalDestination.kafkaTopic("order.events.v1"), - new dev.caskeleton.messaging.policy.SchemaPolicy( - ContentType.JSON, - SchemaCompatibility.BACKWARD_TRANSITIVE, - Set.of(new MessageType("order.created"))), - dev.caskeleton.messaging.api.delivery.DeliveryGuarantee.AT_LEAST_ONCE, - dev.caskeleton.messaging.api.delivery.OrderingScope.NONE, - dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED, - ProducerPolicy.defaults(), - ConsumerPolicy.defaults("order-projection"), - dev.caskeleton.messaging.policy.RetryPolicy.none(), - DeadLetterPolicy.to(new DestinationName("order-events-dlq")), - PayloadPolicy.defaults(), - ApiTier.M1, - false, - false, - false); - } -} diff --git a/src/platforms/messaging/messaging-schema-avro/build.gradle b/src/platforms/messaging/messaging-schema-avro/build.gradle deleted file mode 100644 index b1e8f846..00000000 --- a/src/platforms/messaging/messaging-schema-avro/build.gradle +++ /dev/null @@ -1,12 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') - - // api: AvroMessageCodec's constructors take a registry of org.apache.avro.Schema and - // AvroCompatibilityGate.check takes and compares them. A consumer cannot build that - // registry without naming the type, so hiding the dependency only stops them compiling. - api libs.avro -} diff --git a/src/platforms/messaging/messaging-schema-avro/gradle.lockfile b/src/platforms/messaging/messaging-schema-avro/gradle.lockfile deleted file mode 100644 index d2453d60..00000000 --- a/src/platforms/messaging/messaging-schema-avro/gradle.lockfile +++ /dev/null @@ -1,90 +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=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -com.fasterxml.jackson.core:jackson-core:2.21.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -com.fasterxml.jackson.core:jackson-databind:2.21.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -com.fasterxml.jackson:jackson-bom:2.21.7=compileClasspath,runtimeClasspath,testCompileClasspath,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.50.0=annotationProcessor,checkstyle,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.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -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-codec:commons-codec:1.19.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.16.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -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.avro:avro:1.12.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-compress:1.26.2=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.apache.commons:commons-lang3:3.20.0=checkstyle,compileClasspath,runtimeClasspath,spotbugs,testCompileClasspath,testRuntimeClasspath -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.6.1=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.20=compileClasspath,runtimeClasspath,spotbugs,spotbugsSlf4j,testCompileClasspath,testRuntimeClasspath -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-schema-avro/src/main/java/dev/caskeleton/messaging/schema/avro/AvroCompatibilityGate.java b/src/platforms/messaging/messaging-schema-avro/src/main/java/dev/caskeleton/messaging/schema/avro/AvroCompatibilityGate.java deleted file mode 100644 index 853c33db..00000000 --- a/src/platforms/messaging/messaging-schema-avro/src/main/java/dev/caskeleton/messaging/schema/avro/AvroCompatibilityGate.java +++ /dev/null @@ -1,73 +0,0 @@ -package dev.caskeleton.messaging.schema.avro; - -import dev.caskeleton.messaging.api.error.MessageSchemaIncompatibleException; -import dev.caskeleton.messaging.schema.SchemaCompatibility; -import java.util.List; -import java.util.Objects; -import org.apache.avro.Schema; -import org.apache.avro.SchemaCompatibility.SchemaPairCompatibility; - -/** - * Refuses an Avro schema change that would break the destination's declared compatibility mode. - * - *

Run in CI rather than at runtime. By the time a producer has published one incompatible - * record, the damage is durable: the record sits in a retained log that every current and future - * consumer must be able to read. The gate therefore checks the whole declared history for the - * transitive modes, not just the immediate predecessor, because a chain of individually compatible - * changes can still be collectively breaking for a consumer several releases behind. - */ -public final class AvroCompatibilityGate { - - /** - * Checks a candidate schema against the registered history. - * - * @param candidate the new schema - * @param history the previously registered schemas, newest first - * @param mode the destination's compatibility mode - * @throws MessageSchemaIncompatibleException when the change is not permitted - */ - public void check(Schema candidate, List history, SchemaCompatibility mode) { - Objects.requireNonNull(candidate, "candidate must not be null"); - Objects.requireNonNull(history, "history must not be null"); - Objects.requireNonNull(mode, "mode must not be null"); - - if (mode == SchemaCompatibility.NONE_EXPERIMENTAL || history.isEmpty()) { - return; - } - List checked = isTransitive(mode) ? history : history.subList(0, 1); - - for (Schema previous : checked) { - if (readsBackward(mode)) { - requireCompatible(candidate, previous, "backward"); - } - if (readsForward(mode)) { - requireCompatible(previous, candidate, "forward"); - } - } - } - - private static boolean isTransitive(SchemaCompatibility mode) { - return mode == SchemaCompatibility.BACKWARD_TRANSITIVE - || mode == SchemaCompatibility.FORWARD_TRANSITIVE - || mode == SchemaCompatibility.FULL_TRANSITIVE; - } - - private static boolean readsBackward(SchemaCompatibility mode) { - return mode != SchemaCompatibility.FORWARD && mode != SchemaCompatibility.FORWARD_TRANSITIVE; - } - - private static boolean readsForward(SchemaCompatibility mode) { - return mode != SchemaCompatibility.BACKWARD && mode != SchemaCompatibility.BACKWARD_TRANSITIVE; - } - - private static void requireCompatible(Schema reader, Schema writer, String direction) { - SchemaPairCompatibility result = - org.apache.avro.SchemaCompatibility.checkReaderWriterCompatibility(reader, writer); - if (result.getType() - != org.apache.avro.SchemaCompatibility.SchemaCompatibilityType.COMPATIBLE) { - throw new MessageSchemaIncompatibleException( - "AVRO_" + direction.toUpperCase(java.util.Locale.ROOT) + "_INCOMPATIBLE", - "the candidate Avro schema is not " + direction + " compatible"); - } - } -} diff --git a/src/platforms/messaging/messaging-schema-avro/src/main/java/dev/caskeleton/messaging/schema/avro/AvroMessageCodec.java b/src/platforms/messaging/messaging-schema-avro/src/main/java/dev/caskeleton/messaging/schema/avro/AvroMessageCodec.java deleted file mode 100644 index 631a6b0c..00000000 --- a/src/platforms/messaging/messaging-schema-avro/src/main/java/dev/caskeleton/messaging/schema/avro/AvroMessageCodec.java +++ /dev/null @@ -1,272 +0,0 @@ -package dev.caskeleton.messaging.schema.avro; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageSerializationException; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import dev.caskeleton.messaging.api.error.MessageValidationException; -import dev.caskeleton.messaging.schema.BoundedByteSink; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.schema.MessageCodec; -import dev.caskeleton.messaging.schema.MessageContractKey; -import dev.caskeleton.messaging.schema.SchemaReference; -import java.io.IOException; -import java.util.HashMap; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; -import org.apache.avro.Schema; -import org.apache.avro.generic.GenericDatumReader; -import org.apache.avro.generic.GenericDatumWriter; -import org.apache.avro.generic.GenericRecord; -import org.apache.avro.io.BinaryDecoder; -import org.apache.avro.io.BinaryEncoder; -import org.apache.avro.io.DatumReader; -import org.apache.avro.io.DatumWriter; -import org.apache.avro.io.DecoderFactory; -import org.apache.avro.io.EncoderFactory; - -/** - * The optional Avro codec, bound to a closed registry of writer schemas. - * - *

Decoding uses an explicit writer schema and reader schema pair. Avro binary carries no schema - * of its own, so decoding with the wrong schema does not fail — it produces plausible garbage. The - * registry is what makes the writer schema knowable, and passing both schemas to the reader is what - * makes evolution work: Avro resolves added, removed, and defaulted fields only when it can see - * both sides. - * - *

Single-object encoding without a header is used deliberately. The framing that would carry a - * schema fingerprint belongs to the transport headers, where the platform already carries schema - * identity for every format, rather than being duplicated inside the Avro payload for this one - * format. - */ -public final class AvroMessageCodec implements MessageCodec { - - private static final int DEFAULT_MAX_BYTES = 1_048_576; - - private final Map schemas; - private final int maxBytes; - - /** - * Creates a codec over an explicit schema registry. - * - * @param schemas each registered message type's schema, by version - */ - public AvroMessageCodec(Map> schemas) { - this(schemas, DEFAULT_MAX_BYTES); - } - - /** - * Creates a codec over an explicit schema registry and byte limit. - * - * @param schemas each registered message type's schema, by version - * @param maxBytes the maximum encoded size - */ - public AvroMessageCodec(Map> schemas, int maxBytes) { - Objects.requireNonNull(schemas, "schemas must not be null"); - if (maxBytes < 1) { - throw new IllegalArgumentException("maxBytes must be positive"); - } - this.schemas = flatten(schemas); - this.maxBytes = maxBytes; - } - - /** - * Copies the caller's nested registry into a flat, version-keyed, immutable map. - * - *

{@code Map.copyOf} on the outer map is a shallow copy: every inner {@code Map} stayed the caller's own object, so a caller that kept a reference could add, replace, - * or remove a schema version after construction and the codec would silently start encoding - * against it. Flattening to {@code (type, version)} keys copies both levels and makes the version - * part of the identity the lookup uses rather than a second hop. - */ - private static Map flatten( - Map> registry) { - Map flattened = new HashMap<>(); - registry.forEach( - (type, byVersion) -> { - Objects.requireNonNull(byVersion, "schemas for " + type.value() + " must not be null"); - byVersion.forEach( - (version, schema) -> - flattened.put( - new MessageContractKey(type, version), - Objects.requireNonNull(schema, "schema must not be null"))); - }); - return Map.copyOf(flattened); - } - - @Override - public ContentType contentType() { - return ContentType.AVRO; - } - - @Override - public EncodedMessage encode(MessageType type, SchemaVersion version, Object payload) { - Objects.requireNonNull(payload, "payload must not be null"); - Schema schema = schemaFor(type, version); - - if (!(payload instanceof GenericRecord record)) { - throw new MessageValidationException( - "AVRO_PAYLOAD_NOT_A_RECORD", - "the Avro codec encodes GenericRecord payloads, not " - + payload.getClass().getSimpleName()); - } - if (!schema.equals(record.getSchema())) { - throw new MessageValidationException( - "AVRO_SCHEMA_MISMATCH", - "the payload's schema does not match the registered schema for %s v%d" - .formatted(type.value(), version.value())); - } - - // A direct encoder, not the buffering one: the buffering encoder holds bytes back until flush, - // which would let a large record allocate freely before the sink ever sees a write. Direct - // encoding makes the bound apply to the record as it is written. - BoundedByteSink sink = BoundedByteSink.of(maxBytes, "AVRO_PAYLOAD_TOO_LARGE"); - BinaryEncoder encoder = EncoderFactory.get().directBinaryEncoder(sink, null); - DatumWriter writer = new GenericDatumWriter<>(schema); - try { - writer.write(record, encoder); - encoder.flush(); - } catch (IOException | RuntimeException failure) { - if (failure instanceof MessageTooLargeException tooLarge) { - throw tooLarge; - } - throw new MessageSerializationException( - "AVRO_ENCODE_FAILED", "the payload could not be encoded as Avro", failure); - } - - return new EncodedMessage( - sink.toByteArray(), - ContentType.AVRO, - Optional.of(SchemaReference.of(type.value(), version))); - } - - @Override - public T decode( - MessageType type, SchemaVersion version, byte[] encoded, Class payloadType) { - Objects.requireNonNull(encoded, "encoded must not be null"); - Objects.requireNonNull(payloadType, "payloadType must not be null"); - requireWithinLimit(encoded.length); - Schema writerSchema = schemaFor(type, version); - - if (!payloadType.isAssignableFrom(GenericRecord.class) - && !GenericRecord.class.isAssignableFrom(payloadType)) { - throw new MessageValidationException( - "AVRO_PAYLOAD_NOT_A_RECORD", - "the Avro codec decodes into GenericRecord, not " + payloadType.getSimpleName()); - } - - DatumReader reader = boundedReader(writerSchema, writerSchema); - BinaryDecoder decoder = DecoderFactory.get().binaryDecoder(encoded, null); - try { - return payloadType.cast(reader.read(null, decoder)); - } catch (IOException | RuntimeException failure) { - if (failure instanceof MessageTooLargeException tooLarge) { - throw tooLarge; - } - throw new MessageSerializationException( - "AVRO_DECODE_FAILED", - "the payload could not be decoded against the registered schema", - failure); - } - } - - private void requireWithinLimit(int length) { - if (length > maxBytes) { - throw new MessageTooLargeException( - "AVRO_PAYLOAD_TOO_LARGE", - "the encoded payload of %d bytes exceeds the %d byte limit".formatted(length, maxBytes)); - } - } - - /** - * Decodes using a reader schema that differs from the writer schema. - * - *

This is where Avro evolution actually happens: the reader schema is the consumer's view and - * the writer schema is what the producer wrote. Both are required — resolving with only one of - * them silently drops added fields or fails on removed ones. - * - * @param writerVersion the version the producer wrote - * @param readerVersion the version the consumer expects - * @param type the catalog message type - * @param encoded the encoded bytes - * @return the resolved record - */ - public GenericRecord decodeEvolved( - MessageType type, SchemaVersion writerVersion, SchemaVersion readerVersion, byte[] encoded) { - Objects.requireNonNull(encoded, "encoded must not be null"); - // The same bound the ordinary decode applies. It was missing here, so the evolution path — the - // one a consumer takes for every message written by a newer producer — accepted input of any - // size. - requireWithinLimit(encoded.length); - Schema writerSchema = schemaFor(type, writerVersion); - Schema readerSchema = schemaFor(type, readerVersion); - - DatumReader reader = boundedReader(writerSchema, readerSchema); - BinaryDecoder decoder = DecoderFactory.get().binaryDecoder(encoded, null); - try { - return reader.read(null, decoder); - } catch (IOException | RuntimeException failure) { - if (failure instanceof MessageTooLargeException tooLarge) { - throw tooLarge; - } - throw new MessageSerializationException( - "AVRO_EVOLUTION_FAILED", - "v%d bytes could not be resolved against the v%d reader schema" - .formatted(writerVersion.value(), readerVersion.value()), - failure); - } - } - - /** - * Builds a reader that will not allocate an array the input could not possibly fill. - * - *

Avro writes an array as a declared element count followed by the elements. The count is a - * variable-length integer, so five bytes can claim four hundred million elements, and the generic - * reader allocates the backing array from that claim before reading a single element. Bounding - * the input length does not help: the whole hostile payload is five bytes, well under any limit, - * and the failure is an {@code OutOfMemoryError} rather than an exception the codec could report - * — on a consumer thread that is the process, not the message. - * - *

The ceiling is the byte limit itself. Every element costs at least one byte on the wire even - * when it is empty, so a payload of at most {@code maxBytes} bytes cannot honestly contain more - * than {@code maxBytes} elements, and any larger claim is a lie the reader should refuse rather - * than reserve memory for. - */ - private DatumReader boundedReader(Schema writerSchema, Schema readerSchema) { - int maxElements = maxBytes; - return new GenericDatumReader<>(writerSchema, readerSchema) { - @Override - protected Object newArray(Object old, int size, Schema schema) { - if (size > maxElements) { - throw new MessageTooLargeException( - "AVRO_COLLECTION_TOO_LARGE", - ("the payload declares an array of %d elements, which %d bytes cannot contain; the" - + " claim was refused before the array was allocated") - .formatted(size, maxElements)); - } - return super.newArray(old, size, schema); - } - }; - } - - private Schema schemaFor(MessageType type, SchemaVersion version) { - Objects.requireNonNull(type, "type must not be null"); - Objects.requireNonNull(version, "version must not be null"); - Schema schema = schemas.get(new MessageContractKey(type, version)); - if (schema == null) { - boolean typeIsKnown = schemas.keySet().stream().anyMatch(known -> known.type().equals(type)); - if (!typeIsKnown) { - throw new MessageValidationException( - "AVRO_TYPE_NOT_REGISTERED", - "message type %s is not in the Avro registry".formatted(type.value())); - } - throw new MessageValidationException( - "AVRO_VERSION_NOT_REGISTERED", - "schema version %d of %s is not in the Avro registry" - .formatted(version.value(), type.value())); - } - return schema; - } -} diff --git a/src/platforms/messaging/messaging-schema-avro/src/test/java/dev/caskeleton/messaging/schema/avro/AvroCompatibilityTest.java b/src/platforms/messaging/messaging-schema-avro/src/test/java/dev/caskeleton/messaging/schema/avro/AvroCompatibilityTest.java deleted file mode 100644 index 344990dc..00000000 --- a/src/platforms/messaging/messaging-schema-avro/src/test/java/dev/caskeleton/messaging/schema/avro/AvroCompatibilityTest.java +++ /dev/null @@ -1,178 +0,0 @@ -package dev.caskeleton.messaging.schema.avro; - -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.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageSchemaIncompatibleException; -import dev.caskeleton.messaging.api.error.MessageValidationException; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.schema.SchemaCompatibility; -import java.io.IOException; -import java.io.InputStream; -import java.nio.charset.StandardCharsets; -import java.util.List; -import java.util.Map; -import org.apache.avro.Schema; -import org.apache.avro.generic.GenericData; -import org.apache.avro.generic.GenericRecord; -import org.junit.jupiter.api.Test; - -class AvroCompatibilityTest { - - private static final MessageType ORDER_CREATED = new MessageType("order.created"); - private static final SchemaVersion V1 = new SchemaVersion(1); - private static final SchemaVersion V2 = new SchemaVersion(2); - - private static final Schema V1_SCHEMA = loadV1(); - - /** - * v2 adds a defaulted field, which is the only shape of addition that stays readable both ways. - */ - private static final Schema V2_SCHEMA = - new Schema.Parser() - .parse( - """ - { - "type": "record", - "name": "OrderCreated", - "namespace": "dev.caskeleton.messaging.sample", - "fields": [ - { "name": "orderId", "type": "string" }, - { "name": "customerId", "type": "string" }, - { "name": "totalMinorUnits", "type": "long" }, - { "name": "currency", "type": "string" }, - { "name": "channel", "type": "string", "default": "WEB" } - ] - } - """); - - /** v2-breaking adds a field with no default, which an old writer can never supply. */ - private static final Schema V2_WITHOUT_DEFAULT = - new Schema.Parser() - .parse( - """ - { - "type": "record", - "name": "OrderCreated", - "namespace": "dev.caskeleton.messaging.sample", - "fields": [ - { "name": "orderId", "type": "string" }, - { "name": "customerId", "type": "string" }, - { "name": "totalMinorUnits", "type": "long" }, - { "name": "currency", "type": "string" }, - { "name": "channel", "type": "string" } - ] - } - """); - - private static Schema loadV1() { - try (InputStream stream = - AvroCompatibilityTest.class.getResourceAsStream("/schemas/order.created/v1.avsc")) { - if (stream == null) { - throw new IllegalStateException("the v1 schema fixture is missing from the classpath"); - } - return new Schema.Parser().parse(new String(stream.readAllBytes(), StandardCharsets.UTF_8)); - } catch (IOException failure) { - throw new IllegalStateException("could not read the v1 schema fixture", failure); - } - } - - private static AvroMessageCodec codec() { - return new AvroMessageCodec(Map.of(ORDER_CREATED, Map.of(V1, V1_SCHEMA, V2, V2_SCHEMA))); - } - - private static GenericRecord v1Record() { - GenericRecord record = new GenericData.Record(V1_SCHEMA); - record.put("orderId", "o-1"); - record.put("customerId", "c-1"); - record.put("totalMinorUnits", 12_500L); - record.put("currency", "KRW"); - return record; - } - - @Test - void aRoundTripPreservesEveryField() { - AvroMessageCodec codec = codec(); - - EncodedMessage encoded = codec.encode(ORDER_CREATED, V1, v1Record()); - GenericRecord decoded = codec.decode(ORDER_CREATED, V1, encoded.bytes(), GenericRecord.class); - - assertThat(decoded.get("orderId")).hasToString("o-1"); - assertThat(decoded.get("totalMinorUnits")).isEqualTo(12_500L); - assertThat(encoded.contentType()).isEqualTo(ContentType.AVRO); - } - - @Test - void theEncodedMessageCarriesItsSchemaReference() { - EncodedMessage encoded = codec().encode(ORDER_CREATED, V1, v1Record()); - - assertThat(encoded.schemaReference()) - .as("Avro binary carries no schema of its own, so identity has to travel beside it") - .hasValueSatisfying( - reference -> { - assertThat(reference.subject()).isEqualTo("order.created"); - assertThat(reference.version()).isEqualTo(V1); - }); - } - - @Test - void aV1WriterIsReadableByAV2ReaderThroughTheDefault() { - AvroMessageCodec codec = codec(); - EncodedMessage encoded = codec.encode(ORDER_CREATED, V1, v1Record()); - - GenericRecord evolved = codec.decodeEvolved(ORDER_CREATED, V1, V2, encoded.bytes()); - - assertThat(evolved.get("channel")) - .as("the reader schema's default is what makes the added field readable") - .hasToString("WEB"); - } - - @Test - void addingADefaultedFieldIsBackwardCompatible() { - assertThatCode( - () -> - new AvroCompatibilityGate() - .check(V2_SCHEMA, List.of(V1_SCHEMA), SchemaCompatibility.BACKWARD)) - .doesNotThrowAnyException(); - } - - @Test - void addingAFieldWithoutADefaultIsRejected() { - assertThatThrownBy( - () -> - new AvroCompatibilityGate() - .check(V2_WITHOUT_DEFAULT, List.of(V1_SCHEMA), SchemaCompatibility.BACKWARD)) - .isInstanceOf(MessageSchemaIncompatibleException.class); - } - - @Test - void aPayloadWhoseSchemaDiffersFromTheRegisteredOneIsRejectedBeforeEncoding() { - GenericRecord wrongShape = new GenericData.Record(V2_SCHEMA); - wrongShape.put("orderId", "o-1"); - wrongShape.put("customerId", "c-1"); - wrongShape.put("totalMinorUnits", 1L); - wrongShape.put("currency", "KRW"); - wrongShape.put("channel", "APP"); - - assertThatThrownBy(() -> codec().encode(ORDER_CREATED, V1, wrongShape)) - .as("encoding v2 data under the v1 version would produce bytes nothing can decode") - .isInstanceOf(MessageValidationException.class); - } - - @Test - void anUnregisteredVersionIsRejectedRatherThanGuessed() { - assertThatThrownBy(() -> codec().encode(ORDER_CREATED, new SchemaVersion(9), v1Record())) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("not in the Avro registry"); - } - - @Test - void anUnregisteredTypeIsRejected() { - assertThatThrownBy(() -> codec().encode(new MessageType("unknown.event"), V1, v1Record())) - .isInstanceOf(MessageValidationException.class); - } -} diff --git a/src/platforms/messaging/messaging-schema-avro/src/test/java/dev/caskeleton/messaging/schema/avro/AvroHostileInputTest.java b/src/platforms/messaging/messaging-schema-avro/src/test/java/dev/caskeleton/messaging/schema/avro/AvroHostileInputTest.java deleted file mode 100644 index c0668838..00000000 --- a/src/platforms/messaging/messaging-schema-avro/src/test/java/dev/caskeleton/messaging/schema/avro/AvroHostileInputTest.java +++ /dev/null @@ -1,134 +0,0 @@ -package dev.caskeleton.messaging.schema.avro; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageSerializationException; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import java.io.ByteArrayOutputStream; -import java.util.List; -import java.util.Map; -import org.apache.avro.Schema; -import org.apache.avro.generic.GenericData; -import org.apache.avro.generic.GenericRecord; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * What a hostile Avro payload can make the decoder allocate. - * - *

The byte limit is the wrong instrument for this attack and was the only one in place. Avro - * writes a collection as a declared element count followed by the elements, and the count is a - * variable-length integer: five bytes claim four hundred million elements. Those five bytes pass - * every length check the codec applies, and the generic reader then reserves the backing array from - * the claim before reading a single element. The result is an {@code OutOfMemoryError} — not an - * exception the codec can classify, not a message the consumer can dead-letter, and on a broker - * consumer thread it takes the process with it. - * - *

Strings, byte arrays and maps were already safe: Avro validates those lengths against the - * bytes actually remaining. Arrays were the one shape that allocated on trust, which is why the - * corpus below is narrow rather than exhaustive — it pins the case that failed, and the two cases - * that must keep working around it. - */ -class AvroHostileInputTest { - - private static final MessageType BASKET = new MessageType("basket.filled"); - private static final SchemaVersion V1 = new SchemaVersion(1); - private static final SchemaVersion V2 = new SchemaVersion(2); - - private static final Schema V1_SCHEMA = - new Schema.Parser() - .parse( - """ - { - "type": "record", - "name": "BasketFilled", - "namespace": "dev.caskeleton.messaging.sample", - "fields": [ - {"name": "items", "type": {"type": "array", "items": "string"}} - ] - } - """); - - private static final Schema V2_SCHEMA = - new Schema.Parser() - .parse( - """ - { - "type": "record", - "name": "BasketFilled", - "namespace": "dev.caskeleton.messaging.sample", - "fields": [ - {"name": "items", "type": {"type": "array", "items": "string"}}, - {"name": "channel", "type": "string", "default": "WEB"} - ] - } - """); - - @Test - @DisplayName("an array length no payload of this size could hold is refused before allocation") - void aDeclaredArrayLengthTheInputCannotContainIsRefused() { - AvroMessageCodec codec = new AvroMessageCodec(Map.of(BASKET, Map.of(V1, V1_SCHEMA))); - byte[] hostile = zigzag(400_000_000L); - - assertThat(hostile) - .as("the whole attack is five bytes, so no byte limit stands between it and the allocation") - .hasSizeLessThan(16); - assertThatThrownBy(() -> codec.decode(BASKET, V1, hostile, GenericRecord.class)) - .isInstanceOf(MessageTooLargeException.class) - .hasMessageContaining("400000000"); - } - - @Test - @DisplayName("the evolution decode refuses the same claim") - void theEvolutionDecodeAppliesTheSameCollectionBound() { - AvroMessageCodec codec = - new AvroMessageCodec(Map.of(BASKET, Map.of(V1, V1_SCHEMA, V2, V2_SCHEMA))); - - assertThatThrownBy(() -> codec.decodeEvolved(BASKET, V1, V2, zigzag(400_000_000L))) - .as("a consumer reading a newer producer takes this path for every message") - .isInstanceOf(MessageTooLargeException.class); - } - - @Test - @DisplayName("a count too large for an int fails as a decode error, not an allocation") - void aCountBeyondIntRangeFailsWhileReadingRatherThanWhileReserving() { - AvroMessageCodec codec = new AvroMessageCodec(Map.of(BASKET, Map.of(V1, V1_SCHEMA))); - - assertThatThrownBy(() -> codec.decode(BASKET, V1, zigzag(4_294_967_296L), GenericRecord.class)) - .as("the count truncates to a harmless int, and the read then runs out of input") - .isInstanceOf(MessageSerializationException.class); - } - - @Test - @DisplayName("an array a payload really contains still round trips") - void anHonestArrayIsUnaffectedByTheBound() { - AvroMessageCodec codec = new AvroMessageCodec(Map.of(BASKET, Map.of(V1, V1_SCHEMA))); - GenericRecord basket = new GenericData.Record(V1_SCHEMA); - basket.put("items", List.of("apple", "pear", "plum")); - - byte[] encoded = codec.encode(BASKET, V1, basket).bytes(); - GenericRecord decoded = codec.decode(BASKET, V1, encoded, GenericRecord.class); - - assertThat(decoded.get("items").toString()).isEqualTo("[apple, pear, plum]"); - } - - /** - * Writes one Avro variable-length integer, the way a producer encodes a collection count. - * - *

Hand-written rather than taken from an encoder because the point is to write a count with no - * elements behind it, which no encoder will do. - */ - private static byte[] zigzag(long value) { - long remaining = (value << 1) ^ (value >> 63); - ByteArrayOutputStream bytes = new ByteArrayOutputStream(); - while ((remaining & ~0x7FL) != 0) { - bytes.write((int) ((remaining & 0x7F) | 0x80)); - remaining >>>= 7; - } - bytes.write((int) remaining); - return bytes.toByteArray(); - } -} diff --git a/src/platforms/messaging/messaging-schema-avro/src/test/java/dev/caskeleton/messaging/schema/avro/AvroRegistryBoundsTest.java b/src/platforms/messaging/messaging-schema-avro/src/test/java/dev/caskeleton/messaging/schema/avro/AvroRegistryBoundsTest.java deleted file mode 100644 index 774be674..00000000 --- a/src/platforms/messaging/messaging-schema-avro/src/test/java/dev/caskeleton/messaging/schema/avro/AvroRegistryBoundsTest.java +++ /dev/null @@ -1,140 +0,0 @@ -package dev.caskeleton.messaging.schema.avro; - -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.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import dev.caskeleton.messaging.api.error.MessageValidationException; -import java.util.HashMap; -import java.util.Map; -import org.apache.avro.Schema; -import org.apache.avro.generic.GenericData; -import org.apache.avro.generic.GenericRecord; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * Two holes on the Avro side: the registry the caller could still edit, and the evolution path with - * no size bound. - * - *

{@code Map.copyOf} on a map of maps copies the outer level only. Every inner {@code - * Map} remained the caller's object, so a caller holding a reference could - * replace a registered schema after construction — and Avro binary carries no schema of its own, so - * decoding with a swapped schema does not fail, it produces plausible garbage. - * - *

{@code decodeEvolved} is the path every consumer takes when a producer moves ahead a version. - * It checked no size at all, so the bound that made the ordinary decode safe simply did not apply - * to the case it mattered most for. - */ -class AvroRegistryBoundsTest { - - private static final MessageType ORDER_CREATED = new MessageType("order.created"); - private static final SchemaVersion V1 = new SchemaVersion(1); - private static final SchemaVersion V2 = new SchemaVersion(2); - - private static final Schema V1_SCHEMA = - new Schema.Parser() - .parse( - """ - { - "type": "record", - "name": "OrderCreated", - "namespace": "dev.caskeleton.messaging.sample", - "fields": [ - {"name": "orderId", "type": "string"}, - {"name": "note", "type": "string", "default": ""} - ] - } - """); - - private static final Schema V2_SCHEMA = - new Schema.Parser() - .parse( - """ - { - "type": "record", - "name": "OrderCreated", - "namespace": "dev.caskeleton.messaging.sample", - "fields": [ - {"name": "orderId", "type": "string"}, - {"name": "note", "type": "string", "default": ""}, - {"name": "channel", "type": "string", "default": "WEB"} - ] - } - """); - - @Test - @DisplayName("mutating the map after construction does not change what the codec decodes") - void mutatingTheCallersMapAfterConstructionChangesNothing() { - Map versions = new HashMap<>(Map.of(V1, V1_SCHEMA)); - Map> registry = new HashMap<>(); - registry.put(ORDER_CREATED, versions); - AvroMessageCodec codec = new AvroMessageCodec(registry); - - versions.put(V1, V2_SCHEMA); - versions.put(V2, V2_SCHEMA); - registry.put(new MessageType("order.cancelled"), Map.of(V1, V1_SCHEMA)); - - assertThatThrownBy(() -> codec.encode(ORDER_CREATED, V2, record(V2_SCHEMA))) - .as("a version added after construction is not registered") - .isInstanceOf(MessageValidationException.class); - assertThatThrownBy( - () -> codec.encode(new MessageType("order.cancelled"), V1, record(V1_SCHEMA))) - .isInstanceOf(MessageValidationException.class); - assertThatCode(() -> codec.encode(ORDER_CREATED, V1, record(V1_SCHEMA))) - .as("the schema registered at construction is still the one in force") - .doesNotThrowAnyException(); - } - - @Test - @DisplayName("an oversized payload is refused while encoding, not after") - void anOversizedPayloadIsRefusedWhileEncoding() { - AvroMessageCodec codec = new AvroMessageCodec(Map.of(ORDER_CREATED, Map.of(V1, V1_SCHEMA)), 64); - GenericRecord large = record(V1_SCHEMA); - large.put("note", "n".repeat(4_000_000)); - - assertThatThrownBy(() -> codec.encode(ORDER_CREATED, V1, large)) - .isInstanceOf(MessageTooLargeException.class) - .hasMessageContaining("refused at byte"); - } - - @Test - @DisplayName("the evolution decode applies the same bound as the ordinary decode") - void theEvolutionDecodeAppliesTheSameBound() { - AvroMessageCodec codec = - new AvroMessageCodec(Map.of(ORDER_CREATED, Map.of(V1, V1_SCHEMA, V2, V2_SCHEMA)), 32); - - assertThatThrownBy(() -> codec.decodeEvolved(ORDER_CREATED, V1, V2, new byte[4_096])) - .as("decodeEvolved accepted input of any size") - .isInstanceOf(MessageTooLargeException.class); - } - - @Test - @DisplayName("a payload at exactly the limit still encodes") - void aPayloadAtExactlyTheLimitStillEncodes() { - AvroMessageCodec unbounded = new AvroMessageCodec(Map.of(ORDER_CREATED, Map.of(V1, V1_SCHEMA))); - int exact = unbounded.encode(ORDER_CREATED, V1, record(V1_SCHEMA)).bytes().length; - AvroMessageCodec bounded = - new AvroMessageCodec(Map.of(ORDER_CREATED, Map.of(V1, V1_SCHEMA)), exact); - - assertThat(bounded.encode(ORDER_CREATED, V1, record(V1_SCHEMA)).bytes()).hasSize(exact); - - AvroMessageCodec oneShort = - new AvroMessageCodec(Map.of(ORDER_CREATED, Map.of(V1, V1_SCHEMA)), exact - 1); - assertThatThrownBy(() -> oneShort.encode(ORDER_CREATED, V1, record(V1_SCHEMA))) - .isInstanceOf(MessageTooLargeException.class); - } - - private static GenericRecord record(Schema schema) { - GenericRecord record = new GenericData.Record(schema); - record.put("orderId", "o-1"); - record.put("note", ""); - if (schema.getField("channel") != null) { - record.put("channel", "WEB"); - } - return record; - } -} diff --git a/src/platforms/messaging/messaging-schema-avro/src/test/resources/schemas/order.created/v1.avsc b/src/platforms/messaging/messaging-schema-avro/src/test/resources/schemas/order.created/v1.avsc deleted file mode 100644 index 2d12c31e..00000000 --- a/src/platforms/messaging/messaging-schema-avro/src/test/resources/schemas/order.created/v1.avsc +++ /dev/null @@ -1,11 +0,0 @@ -{ - "type": "record", - "name": "OrderCreated", - "namespace": "dev.caskeleton.messaging.sample", - "fields": [ - { "name": "orderId", "type": "string" }, - { "name": "customerId", "type": "string" }, - { "name": "totalMinorUnits", "type": "long" }, - { "name": "currency", "type": "string" } - ] -} diff --git a/src/platforms/messaging/messaging-schema-json/build.gradle b/src/platforms/messaging/messaging-schema-json/build.gradle deleted file mode 100644 index e87b8c57..00000000 --- a/src/platforms/messaging/messaging-schema-json/build.gradle +++ /dev/null @@ -1,9 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') - - implementation 'tools.jackson.core:jackson-databind' -} diff --git a/src/platforms/messaging/messaging-schema-json/gradle.lockfile b/src/platforms/messaging/messaging-schema-json/gradle.lockfile deleted file mode 100644 index 49c04447..00000000 --- a/src/platforms/messaging/messaging-schema-json/gradle.lockfile +++ /dev/null @@ -1,86 +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=compileClasspath,runtimeClasspath,testCompileClasspath,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.50.0=annotationProcessor,checkstyle,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.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -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.6.1=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.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -tools.jackson.core:jackson-core:3.1.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -tools.jackson.core:jackson-databind:3.1.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -tools.jackson:jackson-bom:3.1.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -empty= diff --git a/src/platforms/messaging/messaging-schema-json/src/main/java/dev/caskeleton/messaging/schema/json/JacksonMessageCodec.java b/src/platforms/messaging/messaging-schema-json/src/main/java/dev/caskeleton/messaging/schema/json/JacksonMessageCodec.java deleted file mode 100644 index 71fe012f..00000000 --- a/src/platforms/messaging/messaging-schema-json/src/main/java/dev/caskeleton/messaging/schema/json/JacksonMessageCodec.java +++ /dev/null @@ -1,226 +0,0 @@ -package dev.caskeleton.messaging.schema.json; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageSerializationException; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import dev.caskeleton.messaging.api.error.MessageValidationException; -import dev.caskeleton.messaging.schema.BoundedByteSink; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.schema.MessageCodec; -import dev.caskeleton.messaging.schema.MessageContractKey; -import dev.caskeleton.messaging.schema.SchemaReference; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; -import tools.jackson.core.JacksonException; -import tools.jackson.core.StreamReadConstraints; -import tools.jackson.core.StreamReadFeature; -import tools.jackson.core.json.JsonFactory; -import tools.jackson.databind.DeserializationFeature; -import tools.jackson.databind.ObjectMapper; -import tools.jackson.databind.json.JsonMapper; - -/** - * The Stable JSON codec. - * - *

Three things make this safe to expose as the default. The message-type registry is closed, so - * a payload class only becomes reachable when someone registered it. The parser is constrained on - * depth, document length, and duplicate keys, so a hostile document cannot exhaust the consumer - * before the handler ever runs. And the encoded size is checked against the destination limit here - * rather than at the broker, so an oversized payload fails locally with {@code NOT_TRANSMITTED} - * evidence instead of ambiguously mid-flight. - * - *

Polymorphic default typing is never enabled. It is the mechanism behind most JSON - * deserialization gadget chains, and no legitimate message contract needs it. - */ -public final class JacksonMessageCodec implements MessageCodec { - - /** The portability limit shared with the other Stable codecs. */ - public static final int DEFAULT_MAX_BYTES = 1_048_576; - - /** The parser nesting depth ceiling. */ - public static final int MAX_NESTING_DEPTH = 100; - - private static final int MAX_STRING_CHARACTERS = 5_000_000; - private static final int MAX_NUMBER_DIGITS = 1_000; - - private final ObjectMapper mapper; - private final Map> registry; - private final int maxBytes; - - private JacksonMessageCodec(Map> registry, int maxBytes) { - this.registry = Map.copyOf(registry); - this.maxBytes = maxBytes; - this.mapper = strictMapper(maxBytes); - } - - /** - * Creates a codec over an explicit message-type registry. - * - * @param registry the closed map of message contract to payload class - * @return a codec with the default one mebibyte limit - */ - public static JacksonMessageCodec of(Map> registry) { - return new JacksonMessageCodec(registry, DEFAULT_MAX_BYTES); - } - - /** - * Creates a codec over an explicit registry and byte limit. - * - * @param registry the closed map of message contract to payload class - * @param maxBytes the maximum encoded size - * @return a codec - */ - public static JacksonMessageCodec of(Map> registry, int maxBytes) { - return new JacksonMessageCodec(registry, maxBytes); - } - - /** - * Creates a single-entry codec for focused tests, registered at version one. - * - * @param type the catalog message type - * @param payloadType the payload class - * @return a codec registering exactly one contract, {@code type v1} - */ - public static JacksonMessageCodec testingDefault(MessageType type, Class payloadType) { - return testingDefault(type, new SchemaVersion(1), payloadType); - } - - /** - * Creates a single-entry codec for focused tests. - * - * @param type the catalog message type - * @param version the schema version to register - * @param payloadType the payload class - * @return a codec registering exactly one contract - */ - public static JacksonMessageCodec testingDefault( - MessageType type, SchemaVersion version, Class payloadType) { - return new JacksonMessageCodec( - Map.of(new MessageContractKey(type, version), payloadType), DEFAULT_MAX_BYTES); - } - - @Override - public ContentType contentType() { - return ContentType.JSON; - } - - @Override - public EncodedMessage encode(MessageType type, SchemaVersion version, Object payload) { - Class registered = requireRegistered(type, version); - Objects.requireNonNull(payload, "payload must not be null"); - if (!registered.isInstance(payload)) { - throw new MessageValidationException( - "PAYLOAD_TYPE_MISMATCH", - "payload does not match the registered type for " + type.value()); - } - - // Streamed into a bounded sink: Jackson writes incrementally, so a payload whose serialized - // form is far larger than the limit stops at the limit instead of after the whole graph has - // been rendered into a buffer nobody bounded. - BoundedByteSink sink = BoundedByteSink.of(maxBytes, "PAYLOAD_TOO_LARGE"); - try { - mapper.writeValue(sink, payload); - } catch (JacksonException exception) { - throw unwrapTooLarge(exception); - } - return new EncodedMessage( - sink.toByteArray(), - ContentType.JSON, - Optional.of(SchemaReference.of(type.value(), version))); - } - - @Override - public T decode( - MessageType type, SchemaVersion version, byte[] encoded, Class payloadType) { - Class registered = requireRegistered(type, version); - Objects.requireNonNull(encoded, "encoded bytes must not be null"); - Objects.requireNonNull(payloadType, "payloadType must not be null"); - if (!registered.equals(payloadType)) { - throw new MessageValidationException( - "PAYLOAD_TYPE_MISMATCH", - "requested type does not match the registered type for " + type.value()); - } - if (encoded.length > maxBytes) { - throw new MessageTooLargeException( - "PAYLOAD_TOO_LARGE", - "encoded payload is " + encoded.length + " bytes, limit is " + maxBytes); - } - - try { - return mapper.readValue(encoded, payloadType); - } catch (JacksonException exception) { - throw new MessageSerializationException( - "JSON_DECODE_FAILED", "payload could not be decoded as JSON", exception); - } - } - - private Class requireRegistered(MessageType type, SchemaVersion version) { - MessageContractKey key = new MessageContractKey(type, version); - Class registered = registry.get(key); - if (registered != null) { - return registered; - } - boolean typeIsKnown = registry.keySet().stream().anyMatch(known -> known.type().equals(type)); - if (typeIsKnown) { - // Deliberately not falling back to another version's class: decoding v999 bytes with the v1 - // class is exactly the silent type confusion the version-keyed registry exists to stop. - throw new MessageValidationException( - "SCHEMA_VERSION_NOT_REGISTERED", - "no contract is registered for " - + key.describe() - + "; registered versions: " - + registeredVersions(type)); - } - throw new MessageValidationException( - "UNKNOWN_MESSAGE_TYPE", "message type is not registered: " + type.value()); - } - - private List registeredVersions(MessageType type) { - return registry.keySet().stream() - .filter(known -> known.type().equals(type)) - .map(known -> known.version().value()) - .sorted() - .toList(); - } - - /** - * Surfaces a bound violation as itself rather than as a generic encoding failure. - * - *

Jackson wraps stream failures, so the size refusal would otherwise reach the caller as - * {@code JSON_ENCODE_FAILED} — indistinguishable from a payload the mapper genuinely could not - * render, and the two need different operator responses. - */ - private static RuntimeException unwrapTooLarge(JacksonException exception) { - for (Throwable cause = exception; cause != null; cause = cause.getCause()) { - if (cause instanceof MessageTooLargeException tooLarge) { - return tooLarge; - } - } - return new MessageSerializationException( - "JSON_ENCODE_FAILED", "payload could not be encoded as JSON", exception); - } - - private static ObjectMapper strictMapper(int maxBytes) { - JsonFactory factory = - JsonFactory.builder() - .streamReadConstraints( - StreamReadConstraints.builder() - .maxNestingDepth(MAX_NESTING_DEPTH) - .maxDocumentLength(maxBytes) - .maxNumberLength(MAX_NUMBER_DIGITS) - .maxStringLength(MAX_STRING_CHARACTERS) - .maxNameLength(MAX_STRING_CHARACTERS) - .build()) - .enable(StreamReadFeature.STRICT_DUPLICATE_DETECTION) - .build(); - return JsonMapper.builder(factory) - .enable(DeserializationFeature.FAIL_ON_READING_DUP_TREE_KEY) - .enable(DeserializationFeature.FAIL_ON_TRAILING_TOKENS) - .enable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES) - .build(); - } -} diff --git a/src/platforms/messaging/messaging-schema-json/src/test/java/dev/caskeleton/messaging/schema/json/JacksonMessageCodecTest.java b/src/platforms/messaging/messaging-schema-json/src/test/java/dev/caskeleton/messaging/schema/json/JacksonMessageCodecTest.java deleted file mode 100644 index d9de94e9..00000000 --- a/src/platforms/messaging/messaging-schema-json/src/test/java/dev/caskeleton/messaging/schema/json/JacksonMessageCodecTest.java +++ /dev/null @@ -1,124 +0,0 @@ -package dev.caskeleton.messaging.schema.json; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageSerializationException; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import dev.caskeleton.messaging.api.error.MessageValidationException; -import java.nio.charset.StandardCharsets; -import org.junit.jupiter.api.Test; - -class JacksonMessageCodecTest { - - private static final MessageType ORDER_CREATED = new MessageType("order.created"); - private static final SchemaVersion V1 = new SchemaVersion(1); - - record OrderCreated(String orderId, long amount) {} - - @Test - void roundTripsRegisteredType() { - JacksonMessageCodec codec = - JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class); - - byte[] encoded = codec.encode(ORDER_CREATED, V1, new OrderCreated("o-1", 1000)).bytes(); - - assertThat(codec.decode(ORDER_CREATED, V1, encoded, OrderCreated.class)) - .isEqualTo(new OrderCreated("o-1", 1000)); - } - - @Test - void rejectsPayloadOverOneMibibyte() { - JacksonMessageCodec codec = - JacksonMessageCodec.testingDefault(new MessageType("text.large"), String.class); - String value = "a".repeat(1_048_577); - - assertThatThrownBy(() -> codec.encode(new MessageType("text.large"), V1, value)) - .isInstanceOf(MessageTooLargeException.class) - .hasMessageContaining("1048576"); - } - - @Test - void rejectsUnregisteredMessageType() { - JacksonMessageCodec codec = - JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class); - - assertThatThrownBy( - () -> codec.encode(new MessageType("order.cancelled"), V1, new OrderCreated("o", 1))) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("not registered"); - } - - @Test - void rejectsPayloadThatDoesNotMatchTheRegisteredType() { - JacksonMessageCodec codec = - JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class); - - assertThatThrownBy(() -> codec.encode(ORDER_CREATED, V1, "not an order")) - .isInstanceOf(MessageValidationException.class); - } - - @Test - void rejectsTrailingDataAfterTheDocument() { - JacksonMessageCodec codec = - JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class); - byte[] trailing = - "{\"orderId\":\"o-1\",\"amount\":1} {\"orderId\":\"o-2\",\"amount\":2}" - .getBytes(StandardCharsets.UTF_8); - - assertThatThrownBy(() -> codec.decode(ORDER_CREATED, V1, trailing, OrderCreated.class)) - .isInstanceOf(MessageSerializationException.class); - } - - @Test - void rejectsUnknownProperties() { - JacksonMessageCodec codec = - JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class); - byte[] extra = - "{\"orderId\":\"o-1\",\"amount\":1,\"injected\":true}".getBytes(StandardCharsets.UTF_8); - - assertThatThrownBy(() -> codec.decode(ORDER_CREATED, V1, extra, OrderCreated.class)) - .isInstanceOf(MessageSerializationException.class); - } - - @Test - void rejectsDuplicateKeys() { - JacksonMessageCodec codec = - JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class); - byte[] duplicate = - "{\"orderId\":\"o-1\",\"orderId\":\"o-2\",\"amount\":1}".getBytes(StandardCharsets.UTF_8); - - assertThatThrownBy(() -> codec.decode(ORDER_CREATED, V1, duplicate, OrderCreated.class)) - .isInstanceOf(MessageSerializationException.class); - } - - @Test - void rejectsNestingBeyondTheDepthCeiling() { - JacksonMessageCodec codec = - JacksonMessageCodec.testingDefault(new MessageType("deep.doc"), Object.class); - String deep = "[".repeat(200) + "]".repeat(200); - - assertThatThrownBy( - () -> - codec.decode( - new MessageType("deep.doc"), - V1, - deep.getBytes(StandardCharsets.UTF_8), - Object.class)) - .isInstanceOf(MessageSerializationException.class); - } - - @Test - void encodedMessageCarriesTheSchemaReference() { - JacksonMessageCodec codec = - JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class); - - var encoded = codec.encode(ORDER_CREATED, V1, new OrderCreated("o-1", 1000)); - - assertThat(encoded.schemaReference()).isPresent(); - assertThat(encoded.schemaReference().orElseThrow().subject()).isEqualTo("order.created"); - assertThat(encoded.contentType().value()).isEqualTo("application/json"); - } -} diff --git a/src/platforms/messaging/messaging-schema-json/src/test/java/dev/caskeleton/messaging/schema/json/JsonContractRegistryTest.java b/src/platforms/messaging/messaging-schema-json/src/test/java/dev/caskeleton/messaging/schema/json/JsonContractRegistryTest.java deleted file mode 100644 index 80249f3a..00000000 --- a/src/platforms/messaging/messaging-schema-json/src/test/java/dev/caskeleton/messaging/schema/json/JsonContractRegistryTest.java +++ /dev/null @@ -1,114 +0,0 @@ -package dev.caskeleton.messaging.schema.json; - -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.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import dev.caskeleton.messaging.api.error.MessageValidationException; -import dev.caskeleton.messaging.schema.MessageContractKey; -import java.util.List; -import java.util.Map; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * What the registry key is, and where the size limit takes effect. - * - *

Two defects met in this codec. The registry was keyed on message type alone, so a message - * labelled v999 was decoded with the v1 class and kept its v999 label — the compatibility gate and - * the audit record then both described a contract that was never registered. And the size limit was - * applied to the finished byte array, which reports an oversized payload rather than preventing - * one. - */ -class JsonContractRegistryTest { - - private static final MessageType ORDER_CREATED = new MessageType("order.created"); - private static final SchemaVersion V1 = new SchemaVersion(1); - private static final SchemaVersion V2 = new SchemaVersion(2); - - record OrderCreated(String orderId, long amount) {} - - record OrderCreatedV2(String orderId, long amount, String channel) {} - - private final JacksonMessageCodec codec = - JacksonMessageCodec.of( - Map.of( - new MessageContractKey(ORDER_CREATED, V1), OrderCreated.class, - new MessageContractKey(ORDER_CREATED, V2), OrderCreatedV2.class)); - - @Test - @DisplayName("each registered version decodes with its own class") - void eachVersionDecodesWithItsOwnClass() { - byte[] v1 = codec.encode(ORDER_CREATED, V1, new OrderCreated("o-1", 10)).bytes(); - byte[] v2 = codec.encode(ORDER_CREATED, V2, new OrderCreatedV2("o-1", 10, "APP")).bytes(); - - assertThat(codec.decode(ORDER_CREATED, V1, v1, OrderCreated.class).orderId()).isEqualTo("o-1"); - assertThat(codec.decode(ORDER_CREATED, V2, v2, OrderCreatedV2.class).channel()) - .isEqualTo("APP"); - } - - @Test - @DisplayName("an unregistered version is refused, not decoded with a neighbour's class") - void anUnregisteredVersionIsRefused() { - byte[] v1 = codec.encode(ORDER_CREATED, V1, new OrderCreated("o-1", 10)).bytes(); - - assertThatThrownBy(() -> codec.decode(ORDER_CREATED, new SchemaVersion(999), v1, Object.class)) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("order.created v999") - .hasMessageContaining("[1, 2]"); - } - - @Test - @DisplayName("the requested class must be the one registered for that exact version") - void theRequestedClassMustMatchTheVersion() { - byte[] v1 = codec.encode(ORDER_CREATED, V1, new OrderCreated("o-1", 10)).bytes(); - - assertThatThrownBy(() -> codec.decode(ORDER_CREATED, V1, v1, OrderCreatedV2.class)) - .isInstanceOf(MessageValidationException.class); - } - - @Test - @DisplayName("an unknown message type is still distinguished from an unknown version") - void anUnknownTypeIsDistinguishedFromAnUnknownVersion() { - assertThatThrownBy( - () -> codec.encode(new MessageType("order.cancelled"), V1, new OrderCreated("o", 1))) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("message type is not registered"); - } - - @Test - @DisplayName("a payload far larger than the limit stops at the limit") - void aPayloadFarLargerThanTheLimitStopsAtTheLimit() { - MessageType largeList = new MessageType("text.list"); - JacksonMessageCodec bounded = - JacksonMessageCodec.of(Map.of(new MessageContractKey(largeList, V1), List.class), 1_024); - // Roughly twenty mebibytes of JSON. The old codec rendered all of it into a byte array and - // only then compared the length with 1024. - List payload = java.util.Collections.nCopies(200_000, "x".repeat(100)); - - assertThatThrownBy(() -> bounded.encode(largeList, V1, payload)) - .isInstanceOf(MessageTooLargeException.class) - .hasMessageContaining("1024") - .hasMessageContaining("refused at byte"); - } - - @Test - @DisplayName("a payload at exactly the limit is still accepted") - void aPayloadAtExactlyTheLimitIsAccepted() { - MessageType text = new MessageType("text.exact"); - int exact = - JacksonMessageCodec.testingDefault(text, String.class) - .encode(text, V1, "a".repeat(100)) - .bytes() - .length; - JacksonMessageCodec bounded = - JacksonMessageCodec.of(Map.of(new MessageContractKey(text, V1), String.class), exact); - - assertThatCode(() -> bounded.encode(text, V1, "a".repeat(100))).doesNotThrowAnyException(); - assertThatThrownBy(() -> bounded.encode(text, V1, "a".repeat(101))) - .isInstanceOf(MessageTooLargeException.class); - } -} diff --git a/src/platforms/messaging/messaging-schema-json/src/test/java/dev/caskeleton/messaging/schema/json/PlatformOverheadPerformanceTest.java b/src/platforms/messaging/messaging-schema-json/src/test/java/dev/caskeleton/messaging/schema/json/PlatformOverheadPerformanceTest.java deleted file mode 100644 index 11b074d1..00000000 --- a/src/platforms/messaging/messaging-schema-json/src/test/java/dev/caskeleton/messaging/schema/json/PlatformOverheadPerformanceTest.java +++ /dev/null @@ -1,135 +0,0 @@ -package dev.caskeleton.messaging.schema.json; - -import static org.assertj.core.api.Assertions.assertThat; - -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.schema.EncodedMessage; -import java.time.Duration; -import java.time.Instant; -import java.util.Optional; -import org.junit.jupiter.api.Test; - -/** - * Bounds the platform's own per-message cost. - * - *

This measures what the platform adds — identity, validation, encoding — and nothing else. - * There is no broker in the loop, deliberately: broker throughput is a property of the deployment - * and varies by an order of magnitude between a laptop and a cluster, so asserting on it produces a - * test that fails for reasons nobody can act on. - * - *

The budgets are generous on purpose. The regression worth catching here is structural — an - * accidental per-message reflection call, a defensive copy that became a deep copy, a validator - * that started compiling a regex per invocation — and those cost orders of magnitude, not - * percentages. A tight budget would instead catch a busy CI agent. - */ -class PlatformOverheadPerformanceTest { - - private static final MessageType ORDER_CREATED = new MessageType("order.created"); - private static final SchemaVersion V1 = new SchemaVersion(1); - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - private static final int WARMUP = 5_000; - private static final int MEASURED = 50_000; - - /** Generous enough that only a structural regression trips it. */ - private static final Duration ENVELOPE_BUDGET_PER_MESSAGE = Duration.ofNanos(20_000); - - private static final Duration ENCODE_BUDGET_PER_MESSAGE = Duration.ofNanos(50_000); - - record OrderCreated(String orderId, long amount) {} - - @Test - void envelopeConstructionStaysWellUnderItsBudget() { - for (int i = 0; i < WARMUP; i++) { - envelope(new byte[64]); - } - - long startedAt = System.nanoTime(); - for (int i = 0; i < MEASURED; i++) { - envelope(new byte[64]); - } - Duration perMessage = Duration.ofNanos((System.nanoTime() - startedAt) / MEASURED); - - assertThat(perMessage) - .as("envelope construction per message: %s", perMessage) - .isLessThan(ENVELOPE_BUDGET_PER_MESSAGE); - } - - @Test - void jsonEncodingStaysWellUnderItsBudget() { - JacksonMessageCodec codec = - JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class); - OrderCreated payload = new OrderCreated("o-1", 1000); - - for (int i = 0; i < WARMUP; i++) { - codec.encode(ORDER_CREATED, V1, payload); - } - - long startedAt = System.nanoTime(); - for (int i = 0; i < MEASURED; i++) { - codec.encode(ORDER_CREATED, V1, payload); - } - Duration perMessage = Duration.ofNanos((System.nanoTime() - startedAt) / MEASURED); - - assertThat(perMessage) - .as("JSON encode per message: %s", perMessage) - .isLessThan(ENCODE_BUDGET_PER_MESSAGE); - } - - @Test - void aRoundTripDoesNotAllocateAGrowingRetainedSet() { - JacksonMessageCodec codec = - JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class); - OrderCreated payload = new OrderCreated("o-1", 1000); - - for (int i = 0; i < WARMUP; i++) { - byte[] encoded = codec.encode(ORDER_CREATED, V1, payload).bytes(); - codec.decode(ORDER_CREATED, V1, encoded, OrderCreated.class); - } - - Runtime runtime = Runtime.getRuntime(); - System.gc(); - long before = runtime.totalMemory() - runtime.freeMemory(); - - for (int i = 0; i < MEASURED; i++) { - byte[] encoded = codec.encode(ORDER_CREATED, V1, payload).bytes(); - codec.decode(ORDER_CREATED, V1, encoded, OrderCreated.class); - } - - System.gc(); - long after = runtime.totalMemory() - runtime.freeMemory(); - long retainedPerMessage = Math.max(0, after - before) / MEASURED; - - assertThat(retainedPerMessage) - .as( - "the codec must not retain per-message state; retained %d bytes/message", - retainedPerMessage) - .isLessThan(64); - } - - private static MessageEnvelope envelope(byte[] payload) { - return new MessageEnvelope<>( - MessageId.newId(), - ORDER_CREATED, - V1, - NOW, - Optional.of(NOW), - new ProducerId("order-api"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.of("acct-1"), - Optional.of("acct-1"), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - new EncodedMessage(payload, ContentType.JSON, Optional.empty())); - } -} diff --git a/src/platforms/messaging/messaging-schema-protobuf/build.gradle b/src/platforms/messaging/messaging-schema-protobuf/build.gradle deleted file mode 100644 index 58f78aac..00000000 --- a/src/platforms/messaging/messaging-schema-protobuf/build.gradle +++ /dev/null @@ -1,11 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') - - // api: ProtobufMessageContract is a public record over com.google.protobuf.Message and - // Parser, and registering a contract is the first thing a consumer of this codec does. - api libs.protobuf.java -} diff --git a/src/platforms/messaging/messaging-schema-protobuf/gradle.lockfile b/src/platforms/messaging/messaging-schema-protobuf/gradle.lockfile deleted file mode 100644 index af31c973..00000000 --- a/src/platforms/messaging/messaging-schema-protobuf/gradle.lockfile +++ /dev/null @@ -1,82 +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.50.0=annotationProcessor,checkstyle,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.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -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,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath -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.6.1=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.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-schema-protobuf/src/main/java/dev/caskeleton/messaging/schema/protobuf/ProtobufMessageCodec.java b/src/platforms/messaging/messaging-schema-protobuf/src/main/java/dev/caskeleton/messaging/schema/protobuf/ProtobufMessageCodec.java deleted file mode 100644 index c151c636..00000000 --- a/src/platforms/messaging/messaging-schema-protobuf/src/main/java/dev/caskeleton/messaging/schema/protobuf/ProtobufMessageCodec.java +++ /dev/null @@ -1,146 +0,0 @@ -package dev.caskeleton.messaging.schema.protobuf; - -import com.google.protobuf.InvalidProtocolBufferException; -import com.google.protobuf.Message; -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageSerializationException; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import dev.caskeleton.messaging.api.error.MessageValidationException; -import dev.caskeleton.messaging.schema.BoundedByteSink; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.schema.MessageCodec; -import dev.caskeleton.messaging.schema.MessageContractKey; -import dev.caskeleton.messaging.schema.SchemaReference; -import java.io.IOException; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; - -/** - * The optional Protobuf codec. - * - *

Bound to a closed registry of generated parsers. Protobuf's own wire format will happily - * decode almost any bytes into almost any message, so without the registry a type confusion is - * silent — the consumer gets a populated object built from the wrong schema rather than an error. - * - *

Unknown fields are preserved by the generated types, which is what makes forward compatibility - * work: an old consumer round-tripping a message written by a newer producer does not silently drop - * the fields it does not understand. - */ -public final class ProtobufMessageCodec implements MessageCodec { - - private static final int DEFAULT_MAX_BYTES = 1_048_576; - - private final Map contracts; - private final int maxBytes; - - /** - * Creates a codec over an explicit registry. - * - * @param contracts the parser and class of each registered {@code (type, version)} contract - */ - public ProtobufMessageCodec(Map contracts) { - this(contracts, DEFAULT_MAX_BYTES); - } - - /** - * Creates a codec over an explicit registry and byte limit. - * - * @param contracts the parser and class of each registered {@code (type, version)} contract - * @param maxBytes the maximum encoded size - */ - public ProtobufMessageCodec( - Map contracts, int maxBytes) { - this.contracts = Map.copyOf(Objects.requireNonNull(contracts, "contracts must not be null")); - if (maxBytes < 1) { - throw new IllegalArgumentException("maxBytes must be positive"); - } - this.maxBytes = maxBytes; - } - - @Override - public ContentType contentType() { - return ContentType.PROTOBUF; - } - - @Override - public EncodedMessage encode(MessageType type, SchemaVersion version, Object payload) { - ProtobufMessageContract contract = requireRegistered(type, version); - if (!(payload instanceof Message message) || !contract.payloadType().isInstance(payload)) { - throw new MessageValidationException( - "PAYLOAD_TYPE_MISMATCH", - "payload does not match the registered protobuf type for " + type.value()); - } - // Protobuf knows its serialized size exactly before writing a byte, so the limit is checked - // against that estimate first and enforced again by the sink. `toByteArray` allocated the whole - // encoding before anything could object. - BoundedByteSink sink = BoundedByteSink.of(maxBytes, "PAYLOAD_TOO_LARGE"); - sink.requireFits(message.getSerializedSize()); - try { - message.writeTo(sink); - } catch (IOException failure) { - throw new MessageSerializationException( - "PROTOBUF_ENCODE_FAILED", "payload could not be encoded as protobuf", failure); - } - return new EncodedMessage( - sink.toByteArray(), - ContentType.PROTOBUF, - Optional.of(SchemaReference.of(type.value(), version))); - } - - @Override - public T decode( - MessageType type, SchemaVersion version, byte[] encoded, Class payloadType) { - ProtobufMessageContract contract = requireRegistered(type, version); - Objects.requireNonNull(encoded, "encoded bytes must not be null"); - if (!contract.payloadType().equals(payloadType)) { - throw new MessageValidationException( - "PAYLOAD_TYPE_MISMATCH", - "requested type does not match the registered protobuf type for " + type.value()); - } - if (encoded.length > maxBytes) { - throw new MessageTooLargeException( - "PAYLOAD_TOO_LARGE", - "encoded payload is " + encoded.length + " bytes, limit is " + maxBytes); - } - try { - return payloadType.cast(contract.parser().parseFrom(encoded)); - } catch (InvalidProtocolBufferException exception) { - throw new MessageSerializationException( - "PROTOBUF_DECODE_FAILED", "payload could not be decoded as protobuf", exception); - } - } - - private ProtobufMessageContract requireRegistered(MessageType type, SchemaVersion version) { - MessageContractKey key = new MessageContractKey(type, version); - ProtobufMessageContract contract = contracts.get(key); - if (contract != null) { - return contract; - } - boolean typeIsKnown = contracts.keySet().stream().anyMatch(known -> known.type().equals(type)); - if (typeIsKnown) { - // Protobuf will happily decode almost any bytes with almost any parser, so falling back to - // another version's parser does not fail — it returns a populated object built from a schema - // nobody registered for this version. - throw new MessageValidationException( - "SCHEMA_VERSION_NOT_REGISTERED", - "no contract is registered for " - + key.describe() - + "; registered versions: " - + registeredVersions(type)); - } - throw new MessageValidationException( - "UNKNOWN_MESSAGE_TYPE", "message type is not registered: " + type.value()); - } - - private List registeredVersions(MessageType type) { - return contracts.keySet().stream() - .filter(known -> known.type().equals(type)) - .map(known -> known.version().value()) - .sorted() - .toList(); - } -} diff --git a/src/platforms/messaging/messaging-schema-protobuf/src/main/java/dev/caskeleton/messaging/schema/protobuf/ProtobufMessageContract.java b/src/platforms/messaging/messaging-schema-protobuf/src/main/java/dev/caskeleton/messaging/schema/protobuf/ProtobufMessageContract.java deleted file mode 100644 index 1bd70394..00000000 --- a/src/platforms/messaging/messaging-schema-protobuf/src/main/java/dev/caskeleton/messaging/schema/protobuf/ProtobufMessageContract.java +++ /dev/null @@ -1,53 +0,0 @@ -package dev.caskeleton.messaging.schema.protobuf; - -import com.google.protobuf.Message; -import com.google.protobuf.Parser; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.util.Objects; - -/** - * The parser and the generated class of one registered contract, held together. - * - *

They used to live in two parallel maps. Nothing checked that the two agreed, so a registry - * that paired {@code OrderCreated.class} with {@code OrderCancelled}'s parser was accepted at - * construction and produced a {@code ClassCastException} at decode time — on a broker thread, for - * one message type, in production. Worse, a type present in one map and absent from the other made - * {@code parsers.get(type)} return null and the decode fail with a {@code NullPointerException} - * rather than the registry error the operator needed to read. - * - *

Binding them in one value makes the mismatch impossible to express, and the constructor proves - * the pairing by parsing empty input: the parser's default instance must be an instance of the - * declared class. - * - * @param payloadType the generated message class this contract decodes into - * @param parser the generated parser for that class - */ -public record ProtobufMessageContract( - Class payloadType, Parser parser) { - - /** Verifies that the parser really produces the declared class. */ - public ProtobufMessageContract { - Objects.requireNonNull(payloadType, "payloadType must not be null"); - Objects.requireNonNull(parser, "parser must not be null"); - Message defaultInstance; - try { - defaultInstance = parser.parseFrom(new byte[0]); - } catch (Exception failure) { - throw new MessagingConfigurationException( - "PROTOBUF_CONTRACT_UNUSABLE", - "the parser registered for " - + payloadType.getName() - + " could not parse empty input, so the pairing cannot be verified", - failure); - } - if (!payloadType.isInstance(defaultInstance)) { - throw new MessagingConfigurationException( - "PROTOBUF_CONTRACT_MISMATCH", - "the parser registered for " - + payloadType.getName() - + " produces " - + defaultInstance.getClass().getName() - + "; a mismatched pairing fails at decode time on a broker thread, not here"); - } - } -} diff --git a/src/platforms/messaging/messaging-schema-protobuf/src/test/java/dev/caskeleton/messaging/schema/protobuf/ProtobufCompatibilityTest.java b/src/platforms/messaging/messaging-schema-protobuf/src/test/java/dev/caskeleton/messaging/schema/protobuf/ProtobufCompatibilityTest.java deleted file mode 100644 index 65fe8c5d..00000000 --- a/src/platforms/messaging/messaging-schema-protobuf/src/test/java/dev/caskeleton/messaging/schema/protobuf/ProtobufCompatibilityTest.java +++ /dev/null @@ -1,255 +0,0 @@ -package dev.caskeleton.messaging.schema.protobuf; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import com.google.protobuf.DescriptorProtos.DescriptorProto; -import com.google.protobuf.DescriptorProtos.FieldDescriptorProto; -import com.google.protobuf.DescriptorProtos.FileDescriptorProto; -import com.google.protobuf.Descriptors.Descriptor; -import com.google.protobuf.Descriptors.DescriptorValidationException; -import com.google.protobuf.Descriptors.FileDescriptor; -import com.google.protobuf.DynamicMessage; -import com.google.protobuf.Message; -import com.google.protobuf.Parser; -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageSerializationException; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import dev.caskeleton.messaging.api.error.MessageValidationException; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.schema.MessageContractKey; -import java.util.Map; -import org.junit.jupiter.api.Test; - -/** - * Proves the tag-number rules the {@code order_created_v1.proto} fixture documents. - * - *

Descriptors are built at runtime rather than generated by protoc. The properties under test — - * that a reader keyed on tag numbers survives a rename, that an added field decodes as its default, - * and that reusing a tag corrupts the read — are properties of the wire format, so proving them - * without a code-generation step keeps the test honest and the build free of a protoc toolchain. - */ -class ProtobufCompatibilityTest { - - private static final MessageType ORDER_CREATED = new MessageType("order.created"); - private static final SchemaVersion V1 = new SchemaVersion(1); - private static final SchemaVersion V2 = new SchemaVersion(2); - - private static final Descriptor V1_DESCRIPTOR = - descriptor( - "OrderCreatedV1", - field("order_id", 1, FieldDescriptorProto.Type.TYPE_STRING), - field("customer_id", 2, FieldDescriptorProto.Type.TYPE_STRING), - field("total_minor_units", 3, FieldDescriptorProto.Type.TYPE_INT64), - field("currency", 4, FieldDescriptorProto.Type.TYPE_STRING)); - - /** v2 renames tag 4 and appends tag 5: both are wire-compatible changes. */ - private static final Descriptor V2_DESCRIPTOR = - descriptor( - "OrderCreatedV2", - field("order_id", 1, FieldDescriptorProto.Type.TYPE_STRING), - field("customer_id", 2, FieldDescriptorProto.Type.TYPE_STRING), - field("total_minor_units", 3, FieldDescriptorProto.Type.TYPE_INT64), - field("currency_code", 4, FieldDescriptorProto.Type.TYPE_STRING), - field("channel", 5, FieldDescriptorProto.Type.TYPE_STRING)); - - /** The forbidden change: tag 4 is reused for a different type. */ - private static final Descriptor TAG_REUSE_DESCRIPTOR = - descriptor( - "OrderCreatedTagReuse", - field("order_id", 1, FieldDescriptorProto.Type.TYPE_STRING), - field("customer_id", 2, FieldDescriptorProto.Type.TYPE_STRING), - field("total_minor_units", 3, FieldDescriptorProto.Type.TYPE_INT64), - field("discount_minor_units", 4, FieldDescriptorProto.Type.TYPE_INT64)); - - private static FieldDescriptorProto field( - String name, int number, FieldDescriptorProto.Type type) { - return FieldDescriptorProto.newBuilder() - .setName(name) - .setNumber(number) - .setType(type) - .setLabel(FieldDescriptorProto.Label.LABEL_OPTIONAL) - .build(); - } - - private static Descriptor descriptor(String name, FieldDescriptorProto... fields) { - DescriptorProto.Builder message = DescriptorProto.newBuilder().setName(name); - for (FieldDescriptorProto field : fields) { - message.addField(field); - } - FileDescriptorProto file = - FileDescriptorProto.newBuilder() - .setName(name + ".proto") - .setSyntax("proto3") - .setPackage("dev.caskeleton.messaging.sample") - .addMessageType(message) - .build(); - try { - return FileDescriptor.buildFrom(file, new FileDescriptor[0]).getMessageTypes().get(0); - } catch (DescriptorValidationException failure) { - throw new IllegalStateException("could not build the test descriptor", failure); - } - } - - private static ProtobufMessageCodec codec(Descriptor descriptor) { - return codec(descriptor, V1); - } - - private static ProtobufMessageCodec codec(Descriptor descriptor, SchemaVersion version) { - return new ProtobufMessageCodec( - Map.of(new MessageContractKey(ORDER_CREATED, version), contract(descriptor))); - } - - private static ProtobufMessageContract contract(Descriptor descriptor) { - Parser parser = - DynamicMessage.getDefaultInstance(descriptor).getParserForType(); - return new ProtobufMessageContract(DynamicMessage.class, parser); - } - - private static DynamicMessage v1Message() { - return DynamicMessage.newBuilder(V1_DESCRIPTOR) - .setField(V1_DESCRIPTOR.findFieldByNumber(1), "o-1") - .setField(V1_DESCRIPTOR.findFieldByNumber(2), "c-1") - .setField(V1_DESCRIPTOR.findFieldByNumber(3), 12_500L) - .setField(V1_DESCRIPTOR.findFieldByNumber(4), "KRW") - .build(); - } - - @Test - void aRoundTripPreservesEveryField() { - ProtobufMessageCodec codec = codec(V1_DESCRIPTOR); - - EncodedMessage encoded = codec.encode(ORDER_CREATED, V1, v1Message()); - DynamicMessage decoded = codec.decode(ORDER_CREATED, V1, encoded.bytes(), DynamicMessage.class); - - assertThat(decoded.getField(V1_DESCRIPTOR.findFieldByNumber(1))).isEqualTo("o-1"); - assertThat(decoded.getField(V1_DESCRIPTOR.findFieldByNumber(3))).isEqualTo(12_500L); - assertThat(encoded.contentType()).isEqualTo(ContentType.PROTOBUF); - } - - @Test - void renamingAFieldKeepsItsValueBecauseTheTagNumberIsTheContract() throws Exception { - byte[] wire = codec(V1_DESCRIPTOR).encode(ORDER_CREATED, V1, v1Message()).bytes(); - - DynamicMessage asV2 = DynamicMessage.parseFrom(V2_DESCRIPTOR, wire); - - assertThat(asV2.getField(V2_DESCRIPTOR.findFieldByName("currency_code"))) - .as("the name changed, the tag did not, so the value survives") - .isEqualTo("KRW"); - } - - @Test - void anAddedFieldDecodesAsItsDefaultForAnOldWriter() throws Exception { - byte[] wire = codec(V1_DESCRIPTOR).encode(ORDER_CREATED, V1, v1Message()).bytes(); - - DynamicMessage asV2 = DynamicMessage.parseFrom(V2_DESCRIPTOR, wire); - - assertThat(asV2.getField(V2_DESCRIPTOR.findFieldByName("channel"))) - .as("proto3 scalars are optional on the wire, so an absent field is the default") - .isEqualTo(""); - } - - @Test - void aNewWriterIsStillReadableByAnOldReader() throws Exception { - DynamicMessage v2 = - DynamicMessage.newBuilder(V2_DESCRIPTOR) - .setField(V2_DESCRIPTOR.findFieldByNumber(1), "o-2") - .setField(V2_DESCRIPTOR.findFieldByNumber(4), "USD") - .setField(V2_DESCRIPTOR.findFieldByNumber(5), "APP") - .build(); - - DynamicMessage asV1 = DynamicMessage.parseFrom(V1_DESCRIPTOR, v2.toByteArray()); - - assertThat(asV1.getField(V1_DESCRIPTOR.findFieldByNumber(4))).isEqualTo("USD"); - assertThat(asV1.getUnknownFields().hasField(5)) - .as("the unrecognised field is retained, not dropped, so a round trip does not lose it") - .isTrue(); - } - - @Test - void reusingATagNumberCorruptsTheReadWhichIsWhyTagsAreNeverRecycled() throws Exception { - byte[] wire = codec(V1_DESCRIPTOR).encode(ORDER_CREATED, V1, v1Message()).bytes(); - - DynamicMessage reused = DynamicMessage.parseFrom(TAG_REUSE_DESCRIPTOR, wire); - - assertThat(reused.getField(TAG_REUSE_DESCRIPTOR.findFieldByName("discount_minor_units"))) - .as("the string bytes on tag 4 are not a valid int64, so the value is lost entirely") - .isEqualTo(0L); - } - - @Test - void anUnregisteredTypeIsRejectedRatherThanGuessed() { - ProtobufMessageCodec codec = codec(V1_DESCRIPTOR); - - assertThatThrownBy(() -> codec.encode(new MessageType("unknown.event"), V1, v1Message())) - .isInstanceOf(MessageValidationException.class); - } - - @Test - void anUnregisteredVersionIsRejectedRatherThanDecodedWithAnotherVersionsParser() { - ProtobufMessageCodec codec = codec(V1_DESCRIPTOR); - byte[] wire = codec.encode(ORDER_CREATED, V1, v1Message()).bytes(); - - assertThatThrownBy(() -> codec.decode(ORDER_CREATED, V2, wire, DynamicMessage.class)) - .as( - "keyed on the type alone, v2 would have decoded with the v1 parser and kept the v2 label") - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("order.created v2"); - } - - @Test - void aParserThatDoesNotProduceTheDeclaredClassIsRejectedAtConstruction() { - Parser parser = - DynamicMessage.getDefaultInstance(V1_DESCRIPTOR).getParserForType(); - - assertThatThrownBy(() -> new ProtobufMessageContract(FileDescriptorProto.class, parser)) - .as("the mismatch used to surface as a ClassCastException on a broker thread") - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("produces"); - } - - @Test - void anOversizedPayloadIsRefusedBeforeItIsSerialized() { - ProtobufMessageCodec codec = - new ProtobufMessageCodec( - Map.of(new MessageContractKey(ORDER_CREATED, V1), contract(V1_DESCRIPTOR)), 16); - - assertThatThrownBy(() -> codec.encode(ORDER_CREATED, V1, v1Message())) - .isInstanceOf(MessageTooLargeException.class) - .hasMessageContaining("refused at byte"); - } - - @Test - void aPayloadAtExactlyTheLimitIsAccepted() { - int exact = v1Message().getSerializedSize(); - ProtobufMessageCodec codec = - new ProtobufMessageCodec( - Map.of(new MessageContractKey(ORDER_CREATED, V1), contract(V1_DESCRIPTOR)), exact); - - assertThat(codec.encode(ORDER_CREATED, V1, v1Message()).bytes()).hasSize(exact); - } - - @Test - void aLengthPrefixNoPayloadOfThisSizeCouldHonourIsADecodeFailure() { - ProtobufMessageCodec codec = codec(V1_DESCRIPTOR); - // Tag 1, wire type 2 (length-delimited), then a varint claiming four hundred million bytes - // follow. The whole message is six bytes, so it passes the size limit; what must not happen is - // the parser reserving the claimed length before discovering there is nothing behind it. - byte[] hostile = {0x0A, (byte) 0x80, (byte) 0x88, (byte) 0xDE, (byte) 0xBE, 0x01}; - - assertThatThrownBy(() -> codec.decode(ORDER_CREATED, V1, hostile, DynamicMessage.class)) - .isInstanceOf(MessageSerializationException.class) - .hasMessageContaining("protobuf"); - } - - @Test - void theEncodedMessageCarriesItsSchemaReference() { - EncodedMessage encoded = codec(V1_DESCRIPTOR, V2).encode(ORDER_CREATED, V2, v1Message()); - - assertThat(encoded.schemaReference()) - .hasValueSatisfying(reference -> assertThat(reference.version()).isEqualTo(V2)); - } -} diff --git a/src/platforms/messaging/messaging-schema-protobuf/src/test/proto/order_created_v1.proto b/src/platforms/messaging/messaging-schema-protobuf/src/test/proto/order_created_v1.proto deleted file mode 100644 index d765c5a0..00000000 --- a/src/platforms/messaging/messaging-schema-protobuf/src/test/proto/order_created_v1.proto +++ /dev/null @@ -1,23 +0,0 @@ -syntax = "proto3"; - -package dev.caskeleton.messaging.sample; - -option java_package = "dev.caskeleton.messaging.sample.proto"; -option java_outer_classname = "OrderCreatedV1Proto"; -option java_multiple_files = true; - -// The v1 wire contract for order.created. -// -// Field numbers are the contract, not the field names: renaming `currency` keeps every existing -// consumer working, while reusing tag 4 for something else silently corrupts them. Tags are never -// reused, and removed fields are reserved so that a later edit cannot take the number back. -message OrderCreated { - string order_id = 1; - string customer_id = 2; - int64 total_minor_units = 3; - string currency = 4; - - // v2 adds `channel = 5`. proto3 scalars are always optional on the wire, so an old writer that - // never sets it decodes as the default rather than failing, which is what makes the addition - // backward compatible without any per-field ceremony. -} diff --git a/src/platforms/messaging/messaging-security/build.gradle b/src/platforms/messaging/messaging-security/build.gradle deleted file mode 100644 index fac7b208..00000000 --- a/src/platforms/messaging/messaging-security/build.gradle +++ /dev/null @@ -1,7 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') -} diff --git a/src/platforms/messaging/messaging-security/gradle.lockfile b/src/platforms/messaging/messaging-security/gradle.lockfile deleted file mode 100644 index d74807c4..00000000 --- a/src/platforms/messaging/messaging-security/gradle.lockfile +++ /dev/null @@ -1,82 +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.50.0=annotationProcessor,checkstyle,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.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -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.6.1=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.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty=compileClasspath,runtimeClasspath diff --git a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerAclManifest.java b/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerAclManifest.java deleted file mode 100644 index 87f84796..00000000 --- a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerAclManifest.java +++ /dev/null @@ -1,141 +0,0 @@ -package dev.caskeleton.messaging.security; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.util.LinkedHashSet; -import java.util.List; -import java.util.Objects; -import java.util.Set; - -/** - * The exact broker permissions a deployment declares it needs. - * - *

Written down so the grant can be reviewed and diffed rather than discovered from a broker - * dump. The manifest is what the platform checks itself against at startup: a runtime that holds - * more than it declares is a finding, because the extra permission is the one nobody reasoned - * about. - * - *

Destructive permissions are named separately from ordinary ones. {@code DELETE_TOPIC} and - * {@code PURGE} are not "write, but more"; they destroy data an application can never restore, so - * an application runtime declaring one is rejected outright. - * - * @param principal the broker principal the grants belong to - * @param grants the declared permissions - */ -public record BrokerAclManifest(String principal, List grants) { - - /** One declared permission over one resource pattern. */ - public record Grant(Operation operation, ResourceType resourceType, String pattern) { - - public Grant { - Objects.requireNonNull(operation, "operation must not be null"); - Objects.requireNonNull(resourceType, "resourceType must not be null"); - if (pattern == null || pattern.isBlank()) { - throw new IllegalArgumentException("pattern must not be blank"); - } - } - } - - /** The broker resources a grant can cover. */ - public enum ResourceType { - /** A topic, exchange, or stream. */ - DESTINATION, - /** A consumer group or subscription. */ - GROUP, - /** The broker or cluster itself. */ - CLUSTER - } - - /** The operations a grant can permit. */ - public enum Operation { - /** Publish to a destination. */ - WRITE(false), - /** Consume from a destination. */ - READ(false), - /** Read metadata. */ - DESCRIBE(false), - /** Create a destination or group. */ - CREATE(false), - /** Change a destination's configuration. */ - ALTER(true), - /** Remove a destination or group. */ - DELETE(true), - /** Discard the messages in a destination. */ - PURGE(true); - - private final boolean destructive; - - Operation(boolean destructive) { - this.destructive = destructive; - } - - /** - * Reports whether this operation can destroy data. - * - * @return true for the destructive operations - */ - public boolean isDestructive() { - return destructive; - } - } - - public BrokerAclManifest { - Objects.requireNonNull(grants, "grants must not be null"); - if (principal == null || principal.isBlank()) { - throw new IllegalArgumentException("principal must not be blank"); - } - grants = List.copyOf(grants); - } - - /** - * Returns the declared destructive grants. - * - * @return the destructive grants - */ - public List destructiveGrants() { - return grants.stream().filter(grant -> grant.operation().isDestructive()).toList(); - } - - /** - * Refuses a manifest that gives an application runtime destructive power. - * - * @throws MessagingConfigurationException when a destructive grant is declared - */ - public void requireApplicationRuntime() { - List destructive = destructiveGrants(); - if (!destructive.isEmpty()) { - throw new MessagingConfigurationException( - "APPLICATION_HOLDS_DESTRUCTIVE_GRANT", - "principal %s declares %s, which an application runtime must never hold" - .formatted(principal, destructive.stream().map(Grant::operation).toList())); - } - } - - /** - * Reports the permissions the runtime holds but never declared. - * - *

Excess is the finding, not the shortfall: a missing grant fails loudly on first use, while - * an undeclared extra one sits unnoticed until it is abused. - * - * @param observed the grants the broker actually reports for this principal - * @return the observed grants that this manifest does not declare - */ - public Set undeclared(Set observed) { - Objects.requireNonNull(observed, "observed must not be null"); - Set extra = new LinkedHashSet<>(observed); - extra.removeAll(Set.copyOf(grants)); - return Set.copyOf(extra); - } - - /** - * Reports the declared permissions the broker does not actually grant. - * - * @param observed the grants the broker actually reports for this principal - * @return the declared grants that are missing - */ - public Set missing(Set observed) { - Objects.requireNonNull(observed, "observed must not be null"); - Set absent = new LinkedHashSet<>(grants); - absent.removeAll(observed); - return Set.copyOf(absent); - } -} diff --git a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerCredentialProfile.java b/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerCredentialProfile.java deleted file mode 100644 index 87a4df63..00000000 --- a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerCredentialProfile.java +++ /dev/null @@ -1,93 +0,0 @@ -package dev.caskeleton.messaging.security; - -/** - * A closed set of broker authentication mechanisms, referenced by credential id. - * - *

No variant carries a secret. The platform stores an identifier and resolves the material - * through a {@link CredentialProvider} at connect time, so a rotation is a provider concern and a - * heap dump or configuration print never yields a usable credential. - */ -public sealed interface BrokerCredentialProfile - permits BrokerCredentialProfile.SaslScram, - BrokerCredentialProfile.OAuth2, - BrokerCredentialProfile.MutualTls, - BrokerCredentialProfile.UsernamePassword, - BrokerCredentialProfile.Nkey { - - /** - * Returns the credential identifier this profile resolves. - * - * @return the credential id - */ - String credentialId(); - - /** - * SASL/SCRAM authentication. - * - * @param credentialId the credential id - */ - record SaslScram(String credentialId) implements BrokerCredentialProfile { - public SaslScram { - CredentialIds.require(credentialId); - } - } - - /** - * OAuth2 bearer authentication. - * - * @param credentialId the credential id - */ - record OAuth2(String credentialId) implements BrokerCredentialProfile { - public OAuth2 { - CredentialIds.require(credentialId); - } - } - - /** - * Mutual TLS authentication: the client certificate in a key store, unlocked by the credential. - * - *

The key store was not part of the profile, so a {@code MUTUAL_TLS} credential configured a - * TLS connection with no client certificate — one every broker that asks for a certificate - * refuses. The path is not a secret and lives here; the password is, and resolves through the - * credential id like every other secret. - * - * @param credentialId the credential whose material unlocks the key store - * @param keyStoreLocation the key store holding the client certificate and private key - * @param keyStoreType the key store format, such as {@code PKCS12} - */ - record MutualTls(String credentialId, String keyStoreLocation, String keyStoreType) - implements BrokerCredentialProfile { - public MutualTls { - CredentialIds.require(credentialId); - if (keyStoreLocation == null || keyStoreLocation.isBlank()) { - throw new IllegalArgumentException( - "mutual TLS presents a client certificate, and without a key store there is none"); - } - if (keyStoreType == null || keyStoreType.isBlank()) { - throw new IllegalArgumentException("keyStoreType must not be blank"); - } - } - } - - /** - * Plain username and password authentication. - * - * @param credentialId the credential id - */ - record UsernamePassword(String credentialId) implements BrokerCredentialProfile { - public UsernamePassword { - CredentialIds.require(credentialId); - } - } - - /** - * NATS NKey authentication. - * - * @param credentialId the credential id - */ - record Nkey(String credentialId) implements BrokerCredentialProfile { - public Nkey { - CredentialIds.require(credentialId); - } - } -} diff --git a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerSecurityProfile.java b/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerSecurityProfile.java deleted file mode 100644 index 40d386fe..00000000 --- a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerSecurityProfile.java +++ /dev/null @@ -1,66 +0,0 @@ -package dev.caskeleton.messaging.security; - -import java.util.Objects; -import java.util.Optional; - -/** - * The security posture for one broker connection. - * - *

Producer, consumer, and admin credentials are separate fields rather than one connection - * credential. That separation is what makes "an application cannot purge a topic" enforceable: the - * runtime never holds admin material, so a compromised handler has nothing to escalate with. - * - * @param broker the broker name - * @param production whether this profile is used in production - * @param tlsEnabled whether transport encryption is on - * @param hostnameVerification whether the server certificate hostname is verified - * @param producer the producer credential - * @param consumer the consumer credential - * @param admin the admin credential, absent in an application runtime - * @param access the destination access policy - * @param trustStore the certificates the connection trusts; empty means the JVM default trust store - */ -public record BrokerSecurityProfile( - String broker, - boolean production, - boolean tlsEnabled, - boolean hostnameVerification, - BrokerCredentialProfile producer, - BrokerCredentialProfile consumer, - Optional admin, - DestinationAccessPolicy access, - Optional trustStore) { - - public BrokerSecurityProfile { - Objects.requireNonNull(producer, "producer credential must not be null"); - Objects.requireNonNull(consumer, "consumer credential must not be null"); - Objects.requireNonNull(admin, "admin credential must not be null"); - Objects.requireNonNull(access, "access policy must not be null"); - Objects.requireNonNull(trustStore, "trust store must not be null"); - if (broker == null || broker.isBlank()) { - throw new IllegalArgumentException("broker must not be blank"); - } - } - - /** A profile that trusts what the JVM's default trust store trusts. */ - public BrokerSecurityProfile( - String broker, - boolean production, - boolean tlsEnabled, - boolean hostnameVerification, - BrokerCredentialProfile producer, - BrokerCredentialProfile consumer, - Optional admin, - DestinationAccessPolicy access) { - this( - broker, - production, - tlsEnabled, - hostnameVerification, - producer, - consumer, - admin, - access, - Optional.empty()); - } -} diff --git a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerTlsPolicy.java b/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerTlsPolicy.java deleted file mode 100644 index 0a648ead..00000000 --- a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerTlsPolicy.java +++ /dev/null @@ -1,107 +0,0 @@ -package dev.caskeleton.messaging.security; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.util.List; -import java.util.Objects; -import java.util.Set; - -/** - * The transport-encryption rules a broker connection must satisfy before it is opened. - * - *

Checked at startup, not per connection. A TLS misconfiguration that surfaces on the first - * publish has already shipped; one that refuses to start is caught in the deployment that - * introduced it. - * - *

Disabling hostname verification is treated as a separate, worse failure than disabling TLS. - * Plaintext is at least obviously insecure, whereas TLS without hostname verification looks - * encrypted in every dashboard while accepting any certificate a man in the middle presents. - */ -public final class BrokerTlsPolicy { - - /** Protocol versions with known practical attacks. */ - /** The only protocol versions this platform will negotiate. */ - private static final Set ACCEPTED_PROTOCOLS = Set.of("TLSv1.2", "TLSv1.3"); - - /** The minimum acceptable protocol version. */ - public static final String MINIMUM_PROTOCOL = "TLSv1.2"; - - private final boolean allowPlaintextOutsideProduction; - - /** Creates a policy that permits plaintext only outside production. */ - public BrokerTlsPolicy() { - this(true); - } - - /** - * Creates a policy. - * - * @param allowPlaintextOutsideProduction whether non-production profiles may run without TLS - */ - public BrokerTlsPolicy(boolean allowPlaintextOutsideProduction) { - this.allowPlaintextOutsideProduction = allowPlaintextOutsideProduction; - } - - /** - * Validates one broker's transport security. - * - * @param profile the broker security profile - * @param enabledProtocols the protocol versions the connection would negotiate - * @throws MessagingConfigurationException when the posture is not acceptable - */ - public void validate(BrokerSecurityProfile profile, List enabledProtocols) { - Objects.requireNonNull(profile, "profile must not be null"); - Objects.requireNonNull(enabledProtocols, "enabledProtocols must not be null"); - - if (!profile.tlsEnabled()) { - if (profile.production() || !allowPlaintextOutsideProduction) { - throw new MessagingConfigurationException( - "TLS_REQUIRED", - "broker %s runs in production and must not use a plaintext connection" - .formatted(profile.broker())); - } - return; - } - - if (!profile.hostnameVerification()) { - throw new MessagingConfigurationException( - "HOSTNAME_VERIFICATION_REQUIRED", - "broker %s enables TLS without hostname verification, which accepts any certificate" - .formatted(profile.broker())); - } - - // An allowlist, not a denylist. - // - // The denylist named the old versions somebody thought of, so `SSL`, `TLSv0.9`, `PLAINTEXT` - // and any typo passed — and a protocol string the JVM does not recognise is negotiated as - // whatever the JVM defaults to, which is the outcome this policy exists to prevent. Naming the - // two acceptable versions means an unknown string fails here rather than at connect time on a - // production broker. - List unsupported = - enabledProtocols.stream() - .filter(protocol -> !ACCEPTED_PROTOCOLS.contains(protocol)) - .toList(); - if (!unsupported.isEmpty()) { - throw new MessagingConfigurationException( - "TLS_PROTOCOL_NOT_ACCEPTED", - "broker %s enables %s; only %s are accepted" - .formatted(profile.broker(), unsupported, ACCEPTED_PROTOCOLS)); - } - if (enabledProtocols.isEmpty()) { - throw new MessagingConfigurationException( - "TLS_PROTOCOL_UNSPECIFIED", - "broker %s enables TLS without naming a protocol version, so the negotiated version " - .formatted(profile.broker()) - + "depends on the JVM default rather than on this policy"); - } - } - - /** - * Reports whether a protocol version is acceptable. - * - * @param protocol the protocol version - * @return true when the version may be negotiated - */ - public static boolean isAcceptable(String protocol) { - return protocol != null && ACCEPTED_PROTOCOLS.contains(protocol); - } -} diff --git a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerTrustStore.java b/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerTrustStore.java deleted file mode 100644 index b5b7db67..00000000 --- a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerTrustStore.java +++ /dev/null @@ -1,30 +0,0 @@ -package dev.caskeleton.messaging.security; - -import java.util.Objects; -import java.util.Optional; - -/** - * The certificates a broker connection trusts, when the JVM's default trust store is not enough. - * - *

A broker signed by a private CA could not be reached at all: there was no setting for a trust - * store, so the client verified the broker against the JVM defaults and refused it. The path is not - * a secret; the store password, when the format has one, resolves through a credential id. - * - * @param location the trust store file - * @param type the trust store format, such as {@code PKCS12} or {@code PEM} - * @param passwordCredentialId the credential whose material unlocks the store, when it is locked - */ -public record BrokerTrustStore( - String location, String type, Optional passwordCredentialId) { - - public BrokerTrustStore { - Objects.requireNonNull(passwordCredentialId, "passwordCredentialId must not be null"); - if (location == null || location.isBlank()) { - throw new IllegalArgumentException("a trust store needs a location"); - } - if (type == null || type.isBlank()) { - throw new IllegalArgumentException("a trust store needs a type"); - } - passwordCredentialId.ifPresent(CredentialIds::require); - } -} diff --git a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialIds.java b/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialIds.java deleted file mode 100644 index 38faea78..00000000 --- a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialIds.java +++ /dev/null @@ -1,37 +0,0 @@ -package dev.caskeleton.messaging.security; - -import java.util.Locale; -import java.util.Set; -import java.util.regex.Pattern; - -/** - * Validation shared by every credential profile variant. - * - *

The bounded slug pattern is not cosmetic. Credential ids reach log lines and metric tags, so - * an unbounded id is a cardinality problem, and an id that looks like a secret is a leak. The - * heuristic check rejects the most common accident: pasting the secret itself where the reference - * belongs. - */ -final class CredentialIds { - - private static final Pattern VALID = Pattern.compile("[a-z0-9][a-z0-9._-]{1,63}"); - - private static final Set SECRET_LOOKING_PREFIXES = - Set.of("bearer ", "basic ", "sk-", "-----begin", "eyj"); - - private CredentialIds() {} - - static void require(String credentialId) { - if (credentialId == null || !VALID.matcher(credentialId).matches()) { - throw new IllegalArgumentException( - "credentialId must match [a-z0-9][a-z0-9._-]{1,63}: " + credentialId); - } - String lowered = credentialId.toLowerCase(Locale.ROOT); - for (String prefix : SECRET_LOOKING_PREFIXES) { - if (lowered.startsWith(prefix)) { - throw new IllegalArgumentException( - "credentialId looks like a secret value rather than a reference"); - } - } - } -} diff --git a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialProvider.java b/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialProvider.java deleted file mode 100644 index 24df0537..00000000 --- a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialProvider.java +++ /dev/null @@ -1,46 +0,0 @@ -package dev.caskeleton.messaging.security; - -import java.time.Instant; -import java.util.Optional; - -/** - * Resolves credential material from an identifier. - * - *

Implementations are expected to fetch late and cache briefly. Returning an expiry lets the - * runtime rotate a generation before the broker starts refusing connections, rather than after. - */ -public interface CredentialProvider { - - /** - * Resolves the secret for a credential id. - * - * @param credentialId the identifier - * @return the resolved material - */ - char[] resolve(String credentialId); - - /** - * Returns when the credential stops being valid, when that is known. - * - * @param credentialId the identifier - * @return the expiry instant when known - */ - Optional expiresAt(String credentialId); - - /** - * Returns the user name the secret authenticates, for mechanisms that send one. - * - *

SASL PLAIN and SCRAM send a user name and a password. The credential id is a reference into - * the store, not the principal the broker knows, and sending it as the user name authenticated as - * whoever happened to share the reference's spelling. A store that rotates by alternating between - * two users rotates the name together with the secret, so the name is resolved alongside it. - * - *

Empty by default. A SASL credential whose provider names no user is refused at startup. - * - * @param credentialId the identifier - * @return the user name, when this credential has one - */ - default Optional username(String credentialId) { - return Optional.empty(); - } -} diff --git a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialRotationPlan.java b/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialRotationPlan.java deleted file mode 100644 index f6e9e698..00000000 --- a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialRotationPlan.java +++ /dev/null @@ -1,54 +0,0 @@ -package dev.caskeleton.messaging.security; - -import java.time.Duration; -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; - -/** - * When a credential must be replaced, and how much slack remains. - * - *

Rotation is scheduled ahead of expiry rather than triggered by an authentication failure. By - * the time the broker starts refusing connections, in-flight publishes are already failing and the - * consumer has already stopped: rotating early turns an outage into a generation swap nobody - * notices. - * - * @param credentialId the credential to rotate - * @param expiresAt when the credential stops being valid, when known - * @param rotateBefore how far ahead of expiry to rotate - */ -public record CredentialRotationPlan( - String credentialId, Optional expiresAt, Duration rotateBefore) { - - public CredentialRotationPlan { - Objects.requireNonNull(expiresAt, "expiresAt must not be null"); - Objects.requireNonNull(rotateBefore, "rotateBefore must not be null"); - if (credentialId == null || credentialId.isBlank()) { - throw new IllegalArgumentException("credentialId must not be blank"); - } - if (rotateBefore.isNegative()) { - throw new IllegalArgumentException("rotateBefore must not be negative"); - } - } - - /** - * Reports whether the credential should be rotated now. - * - * @param now the current instant - * @return true once the rotation window has opened - */ - public boolean isDue(Instant now) { - Objects.requireNonNull(now, "now must not be null"); - return expiresAt.map(expiry -> !now.isBefore(expiry.minus(rotateBefore))).orElse(false); - } - - /** - * Reports whether the credential has already expired. - * - * @param now the current instant - * @return true once expired - */ - public boolean isExpired(Instant now) { - return expiresAt.map(expiry -> !now.isBefore(expiry)).orElse(false); - } -} diff --git a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialRuntime.java b/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialRuntime.java deleted file mode 100644 index 58017281..00000000 --- a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialRuntime.java +++ /dev/null @@ -1,157 +0,0 @@ -package dev.caskeleton.messaging.security; - -import java.time.Duration; -import java.time.Instant; -import java.util.Arrays; -import java.util.Objects; -import java.util.Optional; - -/** - * One credential's live state: when it was resolved, when it expires, and whether it is due for - * rotation. - * - *

Holds the material in a {@code char[]} that {@link #clear()} overwrites. A {@code String} - * cannot be erased — it stays in the constant pool and in every heap dump taken until the next GC - * decides otherwise — so the type of the field is itself part of the control. - * - *

Rotation is driven from the expiry, ahead of it. Waiting for the broker to start refusing - * connections turns a scheduled, invisible rotation into an outage. - */ -public final class CredentialRuntime { - - /** How far ahead of expiry a credential is considered due for rotation. */ - public static final Duration DEFAULT_ROTATION_LEAD = Duration.ofMinutes(30); - - private final String credentialId; - private final Instant resolvedAt; - private final Optional expiresAt; - private final Duration rotationLead; - private final Optional username; - private char[] material; - - /** - * Creates a runtime entry. - * - * @param credentialId the credential reference - * @param username the user name the secret authenticates, when the mechanism sends one - * @param material the resolved secret, taken by reference and cleared by {@link #clear()} - * @param resolvedAt when the material was resolved - * @param expiresAt when it stops being valid, when known - * @param rotationLead how far ahead of expiry rotation should begin - */ - public CredentialRuntime( - String credentialId, - Optional username, - char[] material, - Instant resolvedAt, - Optional expiresAt, - Duration rotationLead) { - CredentialIds.require(credentialId); - Objects.requireNonNull(username, "username must not be null"); - Objects.requireNonNull(material, "material must not be null"); - Objects.requireNonNull(resolvedAt, "resolvedAt must not be null"); - Objects.requireNonNull(expiresAt, "expiresAt must not be null"); - Objects.requireNonNull(rotationLead, "rotationLead must not be null"); - if (rotationLead.isNegative()) { - throw new IllegalArgumentException("rotationLead must not be negative"); - } - if (material.length == 0) { - throw new IllegalArgumentException("credential material must not be empty"); - } - this.credentialId = credentialId; - this.username = username; - this.material = material; - this.resolvedAt = resolvedAt; - this.expiresAt = expiresAt; - this.rotationLead = rotationLead; - } - - /** - * Returns the credential reference. - * - * @return the credential id - */ - public String credentialId() { - return credentialId; - } - - /** - * Returns the user name this secret authenticates, when the mechanism sends one. - * - * @return the user name - */ - public Optional username() { - return username; - } - - /** - * Returns a copy of the material. - * - *

A copy, so a caller that clears its own array cannot blind every other holder. - * - * @return the secret material - * @throws IllegalStateException once {@link #clear()} has run - */ - public char[] material() { - if (material.length == 0) { - throw new IllegalStateException("credential " + credentialId + " has already been cleared"); - } - return material.clone(); - } - - /** - * Returns when the material was resolved. - * - * @return the resolution instant - */ - public Instant resolvedAt() { - return resolvedAt; - } - - /** - * Returns the expiry when it is known. - * - * @return the expiry instant - */ - public Optional expiresAt() { - return expiresAt; - } - - /** - * Reports whether the credential has expired. - * - * @param now the current instant - * @return true when the expiry is known and has passed - */ - public boolean isExpired(Instant now) { - Objects.requireNonNull(now, "now must not be null"); - return expiresAt.map(expiry -> !now.isBefore(expiry)).orElse(false); - } - - /** - * Reports whether rotation should begin. - * - * @param now the current instant - * @return true when the credential is inside its rotation lead or already expired - */ - public boolean isDueForRotation(Instant now) { - Objects.requireNonNull(now, "now must not be null"); - return expiresAt.map(expiry -> !now.isBefore(expiry.minus(rotationLead))).orElse(false); - } - - /** Overwrites the material in place. */ - public void clear() { - Arrays.fill(material, '\0'); - material = new char[0]; - } - - /** - * Returns a representation that names the credential without revealing it. - * - * @return a safe description - */ - @Override - public String toString() { - return "CredentialRuntime[credentialId=%s, expiresAt=%s]".formatted(credentialId, expiresAt); - } -} diff --git a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialRuntimeRegistry.java b/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialRuntimeRegistry.java deleted file mode 100644 index 35a1e77c..00000000 --- a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialRuntimeRegistry.java +++ /dev/null @@ -1,140 +0,0 @@ -package dev.caskeleton.messaging.security; - -import java.time.Duration; -import java.time.Instant; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; -import java.util.concurrent.ConcurrentHashMap; - -/** - * Resolves credentials late, caches them briefly, and clears the old material on rotation. - * - *

Late resolution is what makes rotation possible at all. A credential read once at startup and - * held for the process lifetime cannot be rotated without a restart, which is why rotation gets - * skipped in practice. - * - *

The previous generation is cleared as soon as the new one is installed. Keeping it "just in - * case" is how a revoked credential stays live in memory long after the store says it is gone. - */ -public final class CredentialRuntimeRegistry { - - private final CredentialProvider provider; - private final Duration rotationLead; - private final Map resolved = new ConcurrentHashMap<>(); - - /** - * Creates a registry with the default rotation lead. - * - * @param provider the credential source - */ - public CredentialRuntimeRegistry(CredentialProvider provider) { - this(provider, CredentialRuntime.DEFAULT_ROTATION_LEAD); - } - - /** - * Creates a registry. - * - * @param provider the credential source - * @param rotationLead how far ahead of expiry rotation begins - */ - public CredentialRuntimeRegistry(CredentialProvider provider, Duration rotationLead) { - this.provider = Objects.requireNonNull(provider, "provider must not be null"); - this.rotationLead = Objects.requireNonNull(rotationLead, "rotationLead must not be null"); - } - - /** - * Returns the live credential, resolving or rotating it as needed. - * - * @param credentialId the credential reference - * @param now the current instant - * @return the live credential - */ - public CredentialRuntime resolve(String credentialId, Instant now) { - CredentialIds.require(credentialId); - Objects.requireNonNull(now, "now must not be null"); - - CredentialRuntime current = resolved.get(credentialId); - if (current != null && !current.isDueForRotation(now)) { - return current; - } - // Single-flight, keyed by credential id. - // - // get → fetch → put → clear had no synchronization at all. Two callers rotating the same - // credential both read the same old runtime and both fetched a replacement: one replacement - // was lost from the map without ever being cleared — a secret left in memory that nothing owns - // — and the caller that lost the race could clear material the winner was still using. - // - // compute holds the bin lock for this key, so exactly one fetch publishes and the previous - // generation is retired by that same caller. - return resolved.compute( - credentialId, - (key, existing) -> { - if (existing != null && !existing.isDueForRotation(now)) { - // Another thread rotated while this one waited; its replacement is the current one. - return existing; - } - CredentialRuntime replacement = fetch(key, now); - if (existing != null) { - // Cleared only after the replacement is installed, so no reader sees a window with no - // usable credential — and only by the thread that replaced it, so the material a - // concurrent reader holds is never wiped underneath it. - existing.clear(); - } - return replacement; - }); - } - - /** - * Returns the credentials that are inside their rotation lead. - * - * @param now the current instant - * @return the credential ids due for rotation - */ - public List dueForRotation(Instant now) { - Objects.requireNonNull(now, "now must not be null"); - return resolved.entrySet().stream() - .filter(entry -> entry.getValue().isDueForRotation(now)) - .map(Map.Entry::getKey) - .sorted() - .toList(); - } - - /** - * Returns the credentials that have already expired. - * - * @param now the current instant - * @return the expired credential ids - */ - public List expired(Instant now) { - Objects.requireNonNull(now, "now must not be null"); - return resolved.entrySet().stream() - .filter(entry -> entry.getValue().isExpired(now)) - .map(Map.Entry::getKey) - .sorted() - .toList(); - } - - /** - * Returns how many credentials are currently held. - * - * @return the cached credential count - */ - public int size() { - return resolved.size(); - } - - /** Clears every held credential, for shutdown. */ - public void clearAll() { - resolved.values().forEach(CredentialRuntime::clear); - resolved.clear(); - } - - private CredentialRuntime fetch(String credentialId, Instant now) { - char[] material = provider.resolve(credentialId); - Optional expiresAt = provider.expiresAt(credentialId); - return new CredentialRuntime( - credentialId, provider.username(credentialId), material, now, expiresAt, rotationLead); - } -} diff --git a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/DestinationAccessPolicy.java b/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/DestinationAccessPolicy.java deleted file mode 100644 index 2616e7e8..00000000 --- a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/DestinationAccessPolicy.java +++ /dev/null @@ -1,70 +0,0 @@ -package dev.caskeleton.messaging.security; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import java.util.Objects; -import java.util.Set; - -/** - * Which destinations each role may touch. - * - *

The platform checks this before the broker does. Relying only on broker ACLs means an - * accidental publish surfaces as a generic authorization error at runtime, in the adapter, with no - * record of which application module attempted it. - * - * @param publishable destinations the producer credential may publish to - * @param consumable destinations the consumer credential may consume - * @param administrable destinations the admin credential may operate on - */ -public record DestinationAccessPolicy( - Set publishable, - Set consumable, - Set administrable) { - - public DestinationAccessPolicy { - Objects.requireNonNull(publishable, "publishable must not be null"); - Objects.requireNonNull(consumable, "consumable must not be null"); - Objects.requireNonNull(administrable, "administrable must not be null"); - publishable = Set.copyOf(publishable); - consumable = Set.copyOf(consumable); - administrable = Set.copyOf(administrable); - } - - /** - * Returns a policy that permits nothing. - * - * @return the empty policy - */ - public static DestinationAccessPolicy denyAll() { - return new DestinationAccessPolicy(Set.of(), Set.of(), Set.of()); - } - - /** - * Reports whether publishing is permitted. - * - * @param destination the logical destination - * @return true when permitted - */ - public boolean mayPublish(DestinationName destination) { - return publishable.contains(destination); - } - - /** - * Reports whether consuming is permitted. - * - * @param destination the logical destination - * @return true when permitted - */ - public boolean mayConsume(DestinationName destination) { - return consumable.contains(destination); - } - - /** - * Reports whether administration is permitted. - * - * @param destination the logical destination - * @return true when permitted - */ - public boolean mayAdminister(DestinationName destination) { - return administrable.contains(destination); - } -} diff --git a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/DestinationAccessValidator.java b/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/DestinationAccessValidator.java deleted file mode 100644 index e8a5b04b..00000000 --- a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/DestinationAccessValidator.java +++ /dev/null @@ -1,65 +0,0 @@ -package dev.caskeleton.messaging.security; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessageAuthorizationException; -import java.util.Objects; - -/** - * Checks a destination operation against the platform's own access policy. - * - *

Runs before the broker's ACL, and the failure it raises names the logical destination and the - * role. A broker ACL denial arrives as a connection-level error with no application context, which - * makes "which module tried to publish where" an investigation rather than a log line. - */ -public final class DestinationAccessValidator { - - private final DestinationAccessPolicy policy; - - /** - * Creates a validator over an access policy. - * - * @param policy the destination access policy - */ - public DestinationAccessValidator(DestinationAccessPolicy policy) { - this.policy = Objects.requireNonNull(policy, "policy must not be null"); - } - - /** - * Requires publish permission. - * - * @param destination the logical destination - */ - public void requirePublish(DestinationName destination) { - if (!policy.mayPublish(destination)) { - throw new MessageAuthorizationException( - "DESTINATION_PUBLISH_DENIED", - "the producer credential may not publish to " + destination.value()); - } - } - - /** - * Requires consume permission. - * - * @param destination the logical destination - */ - public void requireConsume(DestinationName destination) { - if (!policy.mayConsume(destination)) { - throw new MessageAuthorizationException( - "DESTINATION_CONSUME_DENIED", - "the consumer credential may not consume " + destination.value()); - } - } - - /** - * Requires administer permission. - * - * @param destination the logical destination - */ - public void requireAdminister(DestinationName destination) { - if (!policy.mayAdminister(destination)) { - throw new MessageAuthorizationException( - "DESTINATION_ADMIN_DENIED", - "the admin credential may not administer " + destination.value()); - } - } -} diff --git a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/MessageSecurityValidator.java b/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/MessageSecurityValidator.java deleted file mode 100644 index 552ca973..00000000 --- a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/MessageSecurityValidator.java +++ /dev/null @@ -1,50 +0,0 @@ -package dev.caskeleton.messaging.security; - -import java.util.LinkedHashSet; -import java.util.Objects; -import java.util.Set; - -/** - * Startup validation of a broker's security posture. - * - *

These checks are boot failures rather than warnings. An unencrypted production broker - * connection or a shared producer/admin credential is not a degraded mode the platform can run in - * safely; both are the kind of misconfiguration that stays invisible until it is exploited. - */ -public final class MessageSecurityValidator { - - /** - * Validates one broker security profile. - * - * @param profile the profile to validate - * @throws IllegalArgumentException when the posture is unsafe - */ - public void validate(BrokerSecurityProfile profile) { - Objects.requireNonNull(profile, "profile must not be null"); - - if (profile.production() && !profile.tlsEnabled()) { - throw new IllegalArgumentException( - "a production broker connection requires TLS: " + profile.broker()); - } - if (profile.production() && !profile.hostnameVerification()) { - throw new IllegalArgumentException( - "a production broker connection requires TLS hostname verification: " + profile.broker()); - } - - Set credentialIds = new LinkedHashSet<>(); - credentialIds.add(profile.producer().credentialId()); - if (!credentialIds.add(profile.consumer().credentialId())) { - throw new IllegalArgumentException( - "producer and consumer must use separate credentials: " + profile.broker()); - } - if (profile.admin().isPresent() - && !credentialIds.add(profile.admin().orElseThrow().credentialId())) { - throw new IllegalArgumentException( - "the admin credential must be separate from producer and consumer: " + profile.broker()); - } - if (profile.production() && profile.admin().isPresent()) { - throw new IllegalArgumentException( - "an application runtime must not hold an admin credential: " + profile.broker()); - } - } -} diff --git a/src/platforms/messaging/messaging-security/src/test/java/dev/caskeleton/messaging/security/CredentialRotationContractTest.java b/src/platforms/messaging/messaging-security/src/test/java/dev/caskeleton/messaging/security/CredentialRotationContractTest.java deleted file mode 100644 index cb7e002c..00000000 --- a/src/platforms/messaging/messaging-security/src/test/java/dev/caskeleton/messaging/security/CredentialRotationContractTest.java +++ /dev/null @@ -1,109 +0,0 @@ -package dev.caskeleton.messaging.security; - -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 java.time.Duration; -import java.time.Instant; -import java.util.List; -import java.util.concurrent.Callable; -import java.util.concurrent.ExecutorService; -import java.util.concurrent.Executors; -import java.util.concurrent.Future; -import java.util.concurrent.atomic.AtomicInteger; -import java.util.stream.IntStream; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * Rotation under concurrency, and the protocol allowlist. - * - *

{@code resolve} was get → fetch → put → clear with no synchronization. Two callers rotating - * the same credential both read the same old runtime and both fetched a replacement: one - * replacement was dropped from the map without ever being cleared — a secret left in memory that - * nothing owns — and the loser could clear material the winner was still using. - */ -class CredentialRotationContractTest { - - private static final Instant NOW = Instant.parse("2026-08-14T00:00:00Z"); - - @Test - @DisplayName("a hundred concurrent resolves fetch once and publish one generation") - void concurrentResolvesFetchOnce() throws Exception { - AtomicInteger fetches = new AtomicInteger(); - CredentialRuntimeRegistry registry = registry(fetches); - - ExecutorService pool = Executors.newFixedThreadPool(16); - try { - List> work = - IntStream.range(0, 100) - .>mapToObj( - index -> () -> registry.resolve("kafka-app", NOW)) - .toList(); - List resolved = new java.util.ArrayList<>(); - for (Future future : pool.invokeAll(work)) { - resolved.add(future.get()); - } - - assertThat(fetches) - .as("every caller fetching its own replacement leaves secrets nobody owns") - .hasValue(1); - assertThat(resolved).allSatisfy(runtime -> assertThat(runtime).isSameAs(resolved.get(0))); - } finally { - pool.shutdownNow(); - } - } - - @Test - @DisplayName("the surviving generation still has its material") - void theSurvivingGenerationKeepsItsMaterial() { - CredentialRuntimeRegistry registry = registry(new AtomicInteger()); - - CredentialRuntime resolved = registry.resolve("kafka-app", NOW); - - assertThatCode(resolved::material) - .as("the losing caller used to clear material the winner was still using") - .doesNotThrowAnyException(); - } - - @Test - @DisplayName("only TLS 1.2 and 1.3 are acceptable") - void onlyModernTlsIsAcceptable() { - assertThat(BrokerTlsPolicy.isAcceptable("TLSv1.2")).isTrue(); - assertThat(BrokerTlsPolicy.isAcceptable("TLSv1.3")).isTrue(); - // Each of these passed the denylist: an unrecognised protocol string negotiates whatever the - // JVM defaults to, which is what the policy exists to prevent. - assertThat(BrokerTlsPolicy.isAcceptable("SSL")).isFalse(); - assertThat(BrokerTlsPolicy.isAcceptable("TLSv0.9")).isFalse(); - assertThat(BrokerTlsPolicy.isAcceptable("PLAINTEXT")).isFalse(); - assertThat(BrokerTlsPolicy.isAcceptable("tlsv1.3")).isFalse(); - assertThat(BrokerTlsPolicy.isAcceptable(null)).isFalse(); - } - - private static CredentialRuntimeRegistry registry(AtomicInteger fetches) { - return new CredentialRuntimeRegistry( - new CredentialProvider() { - @Override - public char[] resolve(String credentialId) { - fetches.incrementAndGet(); - return "s3cr3t".toCharArray(); - } - - @Override - public java.util.Optional expiresAt(String credentialId) { - return java.util.Optional.of(NOW.plus(Duration.ofHours(1))); - } - }, - Duration.ofMinutes(5)); - } - - @Test - @DisplayName("an unknown credential id is refused rather than fetched") - void anUnknownCredentialIdIsRefused() { - CredentialRuntimeRegistry registry = registry(new AtomicInteger()); - - assertThatThrownBy(() -> registry.resolve(" ", NOW)) - .isInstanceOf(IllegalArgumentException.class); - } -} diff --git a/src/platforms/messaging/messaging-security/src/test/java/dev/caskeleton/messaging/security/CredentialRuntimeRegistryTest.java b/src/platforms/messaging/messaging-security/src/test/java/dev/caskeleton/messaging/security/CredentialRuntimeRegistryTest.java deleted file mode 100644 index 4fe4914b..00000000 --- a/src/platforms/messaging/messaging-security/src/test/java/dev/caskeleton/messaging/security/CredentialRuntimeRegistryTest.java +++ /dev/null @@ -1,218 +0,0 @@ -package dev.caskeleton.messaging.security; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.time.Duration; -import java.time.Instant; -import java.util.List; -import java.util.Optional; -import java.util.Set; -import java.util.concurrent.atomic.AtomicInteger; -import org.junit.jupiter.api.Test; - -class CredentialRuntimeRegistryTest { - - private static final String CREDENTIAL_ID = "kafka.producer"; - private static final Instant NOW = Instant.parse("2026-08-10T09:00:00Z"); - - /** Hands out a fresh generation on each resolve so rotation is observable. */ - private static final class CountingProvider implements CredentialProvider { - - private final AtomicInteger generation = new AtomicInteger(); - private final Optional expiry; - - private CountingProvider(Optional expiry) { - this.expiry = expiry; - } - - @Override - public char[] resolve(String credentialId) { - return ("generation-" + generation.incrementAndGet()).toCharArray(); - } - - @Override - public Optional expiresAt(String credentialId) { - return expiry; - } - - int resolutions() { - return generation.get(); - } - } - - @Test - void aCredentialIsResolvedOnceAndReusedUntilItIsDue() { - CountingProvider provider = new CountingProvider(Optional.of(NOW.plus(Duration.ofHours(4)))); - CredentialRuntimeRegistry registry = new CredentialRuntimeRegistry(provider); - - registry.resolve(CREDENTIAL_ID, NOW); - registry.resolve(CREDENTIAL_ID, NOW.plus(Duration.ofMinutes(5))); - - assertThat(provider.resolutions()).isEqualTo(1); - } - - @Test - void rotationHappensBeforeExpiryNotAfterIt() { - Instant expiry = NOW.plus(Duration.ofMinutes(20)); - CountingProvider provider = new CountingProvider(Optional.of(expiry)); - CredentialRuntimeRegistry registry = new CredentialRuntimeRegistry(provider); - - registry.resolve(CREDENTIAL_ID, NOW); - registry.resolve(CREDENTIAL_ID, NOW.plus(Duration.ofMinutes(1))); - - assertThat(provider.resolutions()) - .as("waiting for the broker to refuse the connection turns rotation into an outage") - .isEqualTo(2); - } - - @Test - void theSupersededGenerationIsWipedNotJustDropped() { - Instant expiry = NOW.plus(Duration.ofMinutes(20)); - CredentialRuntimeRegistry registry = - new CredentialRuntimeRegistry(new CountingProvider(Optional.of(expiry))); - - CredentialRuntime first = registry.resolve(CREDENTIAL_ID, NOW); - registry.resolve(CREDENTIAL_ID, NOW.plus(Duration.ofMinutes(1))); - - assertThatThrownBy(first::material) - .as("a revoked credential must not stay readable in memory") - .isInstanceOf(IllegalStateException.class); - } - - @Test - void aCredentialWithNoKnownExpiryIsNeverRotatedOnATimer() { - CountingProvider provider = new CountingProvider(Optional.empty()); - CredentialRuntimeRegistry registry = new CredentialRuntimeRegistry(provider); - - registry.resolve(CREDENTIAL_ID, NOW); - registry.resolve(CREDENTIAL_ID, NOW.plus(Duration.ofDays(30))); - - assertThat(provider.resolutions()).isEqualTo(1); - } - - @Test - void materialIsHandedOutAsACopySoOneHolderCannotBlindTheOthers() { - CredentialRuntimeRegistry registry = - new CredentialRuntimeRegistry(new CountingProvider(Optional.empty())); - CredentialRuntime credential = registry.resolve(CREDENTIAL_ID, NOW); - - char[] borrowed = credential.material(); - java.util.Arrays.fill(borrowed, 'x'); - - assertThat(credential.material()).containsExactly("generation-1".toCharArray()); - } - - @Test - void theDescriptionNamesTheCredentialWithoutRevealingIt() { - CredentialRuntimeRegistry registry = - new CredentialRuntimeRegistry(new CountingProvider(Optional.empty())); - - String described = registry.resolve(CREDENTIAL_ID, NOW).toString(); - - assertThat(described).contains(CREDENTIAL_ID).doesNotContain("generation-1"); - } - - @Test - void expiredCredentialsAreReportedForAlerting() { - Instant expiry = NOW.plus(Duration.ofMinutes(5)); - CredentialRuntimeRegistry registry = - new CredentialRuntimeRegistry( - new CountingProvider(Optional.of(expiry)), Duration.ofMinutes(1)); - registry.resolve(CREDENTIAL_ID, NOW); - - assertThat(registry.expired(NOW.plus(Duration.ofMinutes(10)))).containsExactly(CREDENTIAL_ID); - } - - @Test - void clearingTheRegistryWipesEverythingItHeld() { - CredentialRuntimeRegistry registry = - new CredentialRuntimeRegistry(new CountingProvider(Optional.empty())); - CredentialRuntime credential = registry.resolve(CREDENTIAL_ID, NOW); - - registry.clearAll(); - - assertThat(registry.size()).isZero(); - assertThatThrownBy(credential::material).isInstanceOf(IllegalStateException.class); - } - - @Test - void aProductionBrokerCannotRunWithoutTls() { - assertThatThrownBy( - () -> new BrokerTlsPolicy().validate(profile(true, false, true), List.of("TLSv1.3"))) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("plaintext"); - } - - @Test - void tlsWithoutHostnameVerificationIsRefusedEvenThoughItLooksEncrypted() { - assertThatThrownBy( - () -> new BrokerTlsPolicy().validate(profile(true, true, false), List.of("TLSv1.3"))) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("hostname verification"); - } - - @Test - void anObsoleteProtocolVersionIsRefused() { - assertThatThrownBy( - () -> - new BrokerTlsPolicy() - .validate(profile(true, true, true), List.of("TLSv1.3", "TLSv1.1"))) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("TLSv1.1"); - } - - @Test - void anApplicationRuntimeMayNotHoldADestructiveGrant() { - BrokerAclManifest manifest = - new BrokerAclManifest( - "orders-api", - List.of( - new BrokerAclManifest.Grant( - BrokerAclManifest.Operation.WRITE, - BrokerAclManifest.ResourceType.DESTINATION, - "orders.*"), - new BrokerAclManifest.Grant( - BrokerAclManifest.Operation.DELETE, - BrokerAclManifest.ResourceType.DESTINATION, - "orders.*"))); - - assertThatThrownBy(manifest::requireApplicationRuntime) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("DELETE"); - } - - @Test - void aGrantTheBrokerHoldsButNobodyDeclaredIsTheFinding() { - BrokerAclManifest.Grant declared = - new BrokerAclManifest.Grant( - BrokerAclManifest.Operation.WRITE, - BrokerAclManifest.ResourceType.DESTINATION, - "orders.*"); - BrokerAclManifest.Grant extra = - new BrokerAclManifest.Grant( - BrokerAclManifest.Operation.DELETE, - BrokerAclManifest.ResourceType.DESTINATION, - "orders.*"); - BrokerAclManifest manifest = new BrokerAclManifest("orders-api", List.of(declared)); - - assertThat(manifest.undeclared(Set.of(declared, extra))) - .as("a missing grant fails loudly on first use; an extra one waits to be abused") - .containsExactly(extra); - } - - private static BrokerSecurityProfile profile( - boolean production, boolean tls, boolean hostnameVerification) { - BrokerCredentialProfile credential = new BrokerCredentialProfile.SaslScram("kafka.producer"); - return new BrokerSecurityProfile( - "kafka", - production, - tls, - hostnameVerification, - credential, - credential, - Optional.empty(), - DestinationAccessPolicy.denyAll()); - } -} diff --git a/src/platforms/messaging/messaging-security/src/test/java/dev/caskeleton/messaging/security/MessageSecurityValidatorTest.java b/src/platforms/messaging/messaging-security/src/test/java/dev/caskeleton/messaging/security/MessageSecurityValidatorTest.java deleted file mode 100644 index 060fe93a..00000000 --- a/src/platforms/messaging/messaging-security/src/test/java/dev/caskeleton/messaging/security/MessageSecurityValidatorTest.java +++ /dev/null @@ -1,148 +0,0 @@ -package dev.caskeleton.messaging.security; - -import static org.assertj.core.api.Assertions.assertThatCode; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import java.util.Optional; -import java.util.Set; -import org.junit.jupiter.api.Test; - -class MessageSecurityValidatorTest { - - private final MessageSecurityValidator validator = new MessageSecurityValidator(); - - @Test - void productionBrokerWithoutTlsIsRejected() { - BrokerSecurityProfile profile = BrokerSecurityProfileFixtures.productionWithoutTls(); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("TLS"); - } - - @Test - void productionBrokerWithoutHostnameVerificationIsRejected() { - BrokerSecurityProfile profile = BrokerSecurityProfileFixtures.productionWithoutHostnameCheck(); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("hostname"); - } - - @Test - void producerAndConsumerMustUseSeparateCredentials() { - BrokerSecurityProfile profile = BrokerSecurityProfileFixtures.sharedProducerConsumer(); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("separate credentials"); - } - - @Test - void anApplicationRuntimeMustNotHoldAnAdminCredential() { - BrokerSecurityProfile profile = BrokerSecurityProfileFixtures.productionWithAdmin(); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("admin credential"); - } - - @Test - void aCredentialIdThatLooksLikeASecretIsRejected() { - assertThatThrownBy(() -> new BrokerCredentialProfile.OAuth2("bearer abcdef123456")) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void accessPolicySeparatesPublishConsumeAndAdminister() { - DestinationName orders = new DestinationName("order-events"); - DestinationAccessPolicy policy = - new DestinationAccessPolicy(Set.of(orders), Set.of(), Set.of()); - - assertThatCode( - () -> { - if (!policy.mayPublish(orders) - || policy.mayConsume(orders) - || policy.mayAdminister(orders)) { - throw new IllegalStateException("access policy roles are not separated"); - } - }) - .doesNotThrowAnyException(); - } - - @Test - void aCoherentProductionProfileValidates() { - assertThatCode(() -> validator.validate(BrokerSecurityProfileFixtures.production())) - .doesNotThrowAnyException(); - } -} - -/** Builds broker security profiles for validator tests. */ -final class BrokerSecurityProfileFixtures { - - private BrokerSecurityProfileFixtures() {} - - static BrokerSecurityProfile production() { - return new BrokerSecurityProfile( - "kafka-primary", - true, - true, - true, - new BrokerCredentialProfile.SaslScram("kafka-producer"), - new BrokerCredentialProfile.SaslScram("kafka-consumer"), - Optional.empty(), - DestinationAccessPolicy.denyAll()); - } - - static BrokerSecurityProfile productionWithoutTls() { - BrokerSecurityProfile base = production(); - return new BrokerSecurityProfile( - base.broker(), - true, - false, - true, - base.producer(), - base.consumer(), - base.admin(), - base.access()); - } - - static BrokerSecurityProfile productionWithoutHostnameCheck() { - BrokerSecurityProfile base = production(); - return new BrokerSecurityProfile( - base.broker(), - true, - true, - false, - base.producer(), - base.consumer(), - base.admin(), - base.access()); - } - - static BrokerSecurityProfile sharedProducerConsumer() { - return new BrokerSecurityProfile( - "kafka-primary", - false, - true, - true, - new BrokerCredentialProfile.SaslScram("kafka-app"), - new BrokerCredentialProfile.SaslScram("kafka-app"), - Optional.empty(), - DestinationAccessPolicy.denyAll()); - } - - static BrokerSecurityProfile productionWithAdmin() { - BrokerSecurityProfile base = production(); - return new BrokerSecurityProfile( - base.broker(), - true, - true, - true, - base.producer(), - base.consumer(), - Optional.of(new BrokerCredentialProfile.SaslScram("kafka-admin")), - base.access()); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter-kafka/build.gradle b/src/platforms/messaging/messaging-spring-boot-starter-kafka/build.gradle deleted file mode 100644 index a985d71f..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter-kafka/build.gradle +++ /dev/null @@ -1,15 +0,0 @@ -plugins { - id 'ca.platform-module' - id 'ca.spring-config' -} - -dependencies { - // Capability artifact: selecting Kafka is a build-time decision. The core starter contains no - // Kafka client classes. - api project(':messaging:messaging-spring-boot-starter') - api project(':messaging:messaging-kafka') - // KafkaConsumerConfiguration's public consumer-factory seam names kafka-clients types. - api 'org.apache.kafka:kafka-clients' - - implementation 'org.springframework.boot:spring-boot-autoconfigure' -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter-kafka/gradle.lockfile b/src/platforms/messaging/messaging-spring-boot-starter-kafka/gradle.lockfile deleted file mode 100644 index 41a36a94..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter-kafka/gradle.lockfile +++ /dev/null @@ -1,107 +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.11.4=runtimeClasspath,testRuntimeClasspath -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.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.50.0=annotationProcessor,checkstyle,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.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -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 -commons-logging:commons-logging:1.3.6=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -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.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-core:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-observation:1.16.8=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.6.1=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.20=runtimeClasspath,spotbugs,spotbugsSlf4j,testRuntimeClasspath -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.springframework.boot:spring-boot-actuator:4.0.9=runtimeClasspath,testRuntimeClasspath -org.springframework.boot:spring-boot-autoconfigure:4.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework.boot:spring-boot-configuration-processor:4.0.9=annotationProcessor -org.springframework.boot:spring-boot:4.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-aop:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-beans:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-context:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-core:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-expression:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-jdbc:7.0.10=runtimeClasspath,testRuntimeClasspath -org.springframework:spring-tx:7.0.10=runtimeClasspath,testRuntimeClasspath -org.xerial.snappy:snappy-java:1.1.10.9=runtimeClasspath,testRuntimeClasspath -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -tools.jackson.core:jackson-core:3.1.7=runtimeClasspath,testRuntimeClasspath -tools.jackson.core:jackson-databind:3.1.7=runtimeClasspath,testRuntimeClasspath -tools.jackson:jackson-bom:3.1.7=runtimeClasspath,testRuntimeClasspath -empty= diff --git a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerCatalog.java b/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerCatalog.java deleted file mode 100644 index 726df06f..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerCatalog.java +++ /dev/null @@ -1,37 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import java.util.LinkedHashMap; -import java.util.Map; -import java.util.Objects; - -/** - * The Kafka client settings of every {@code app.messaging.brokers} entry of type {@code kafka}. - * - * @param brokers the Kafka settings, keyed by logical broker name, in declaration order - */ -public record KafkaBrokerCatalog(Map brokers) { - - public KafkaBrokerCatalog { - brokers = - java.util.Collections.unmodifiableMap( - new LinkedHashMap<>(Objects.requireNonNull(brokers, "brokers must not be null"))); - } - - /** - * The one Kafka broker the producer and the consumers connect to. - * - * @return its logical name and settings - * @throws IllegalStateException unless exactly one Kafka entry is configured - */ - public Map.Entry single() { - if (brokers.size() != 1) { - throw new IllegalStateException( - "app.messaging.broker=kafka needs exactly one app.messaging.brokers. entry with" - + " type kafka and its bootstrap-servers; found " - + brokers.size() - + ". A producer with no broker address defaults to localhost:9092 and fails at the" - + " first publish rather than at startup"); - } - return brokers.entrySet().iterator().next(); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerSettings.java b/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerSettings.java deleted file mode 100644 index 5f380359..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerSettings.java +++ /dev/null @@ -1,86 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import java.time.Duration; -import java.util.LinkedHashMap; -import java.util.List; -import java.util.Locale; -import java.util.Map; -import java.util.Objects; -import org.springframework.boot.context.properties.bind.Bindable; -import org.springframework.boot.context.properties.bind.Binder; -import org.springframework.boot.context.properties.bind.DefaultValue; -import org.springframework.core.env.Environment; - -/** - * The Kafka client part of one {@code app.messaging.brokers.} entry of type {@code kafka}. - * - *

Bound here, by the Kafka starter, from the same entry the broker-neutral {@link - * BrokerSettings} reads its family and posture from (S7-#9b). These fields used to sit in {@code - * BrokerSettings}, so the neutral starter bound Kafka client settings for deployments with no Kafka - * transport. - * - * @param bootstrapServers Kafka broker addresses - * @param enableIdempotence Kafka producer duplicate suppression on internal retry - * @param acks the Kafka acknowledgement level - * @param maxInFlightRequestsPerConnection the Kafka in-flight request ceiling - * @param deliveryTimeout the Kafka producer delivery deadline - * @param enableAutoCommit whether the Kafka consumer commits offsets on a timer; the platform - * consumer commits itself and refuses {@code true} - * @param consumerGroup the consumer group a destination without its own {@code consumer.group} - * joins - */ -public record KafkaBrokerSettings( - @DefaultValue List bootstrapServers, - @DefaultValue("true") boolean enableIdempotence, - @DefaultValue("all") String acks, - @DefaultValue("5") int maxInFlightRequestsPerConnection, - @DefaultValue("30s") Duration deliveryTimeout, - @DefaultValue("false") boolean enableAutoCommit, - @DefaultValue("") String consumerGroup) { - - public KafkaBrokerSettings { - bootstrapServers = List.copyOf(Objects.requireNonNull(bootstrapServers, "bootstrapServers")); - Objects.requireNonNull(acks, "acks must not be null"); - Objects.requireNonNull(deliveryTimeout, "deliveryTimeout must not be null"); - Objects.requireNonNull(consumerGroup, "consumerGroup must not be null"); - } - - /** - * Binds the Kafka settings of every broker entry whose family is {@code kafka}. - * - * @param environment the resolved environment - * @param compiled the compiled configuration, which names the Kafka entries - * @return the Kafka settings, keyed by logical broker name, in declaration order - * @throws dev.caskeleton.messaging.api.error.MessagingConfigurationException when a Kafka entry - * declares no address - */ - public static Map bindAll( - Environment environment, CompiledMessagingConfiguration compiled) { - Binder binder = Binder.get(environment); - Map kafka = new LinkedHashMap<>(); - compiled - .brokers() - .forEach( - (name, broker) -> { - if (broker.type() == null - || !BrokerSettings.KAFKA.equals(broker.type().toLowerCase(Locale.ROOT))) { - return; - } - String prefix = MessagingSettings.PREFIX + ".brokers." + name; - KafkaBrokerSettings settings = - binder - .bind(prefix, Bindable.of(KafkaBrokerSettings.class)) - .orElseGet(() -> binder.bindOrCreate(prefix, KafkaBrokerSettings.class)); - if (settings.bootstrapServers().isEmpty()) { - throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException( - "MESSAGING_CONFIGURATION_INVALID", - prefix - + ".bootstrap-servers: a Kafka broker needs at least one address; a client" - + " with none defaults to localhost:9092 and fails at the first publish" - + " rather than at startup"); - } - kafka.put(name, settings); - }); - return kafka; - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaConsumerConfiguration.java b/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaConsumerConfiguration.java deleted file mode 100644 index 8b385238..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaConsumerConfiguration.java +++ /dev/null @@ -1,165 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.kafka.KafkaQuarantinePublisher; -import dev.caskeleton.messaging.kafka.KafkaSecurityConfigurer; -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.security.BrokerSecurityProfile; -import dev.caskeleton.messaging.transport.MessagingTransport; -import dev.caskeleton.messaging.transport.TransportConsumerRegistration; -import dev.caskeleton.messaging.transport.TransportConsumerSpec; -import java.util.HashMap; -import java.util.Map; -import java.util.function.Function; -import org.apache.kafka.clients.consumer.ConsumerConfig; -import org.apache.kafka.clients.producer.Producer; -import org.apache.kafka.common.serialization.ByteArrayDeserializer; -import org.springframework.beans.factory.ObjectProvider; -import org.springframework.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; - -/** - * Opens a Kafka consumer for every destination a {@code MessageHandler} bean names (owner decision - * 10, S7-#2). - * - *

On when present, like the rest of the capability: an application with no handler bean gets no - * consumer, no thread and no connection; {@code app.messaging.enabled=false} removes the platform - * altogether. The broker-neutral pipeline — decode, inbox, handler, dead letter, settlement — is - * {@link MessageConsumers}; this class adds only what is Kafka's, and it reaches the broker through - * {@link MessagingTransport#register}, which refused every subscription with {@code - * KAFKA_CONSUMER_NOT_CONFIGURED} until it had a consumer factory: - * - *

- */ -@Configuration(proxyBeanMethods = false) -public class KafkaConsumerConfiguration { - - /** - * Builds a live subscription for a destination; the transport's consumer factory. - * - * @param compiled the compiled configuration - * @param catalog the Kafka client settings - * @param destinations the validated destination registry, for dead-letter topics - * @param producer the platform producer the dead-letter copy is written with, resolved when a - * subscription opens so that the startup validations run before a client is built - * @param declaredSecurity the security profiles the application declared as beans - * @param securityConfigurer the Kafka security configurer, present only with a credential source - * @param settings the bound settings supplying the drain deadline - * @return the factory - */ - @Bean - public KafkaConsumerFactory messagingKafkaConsumerFactory( - CompiledMessagingConfiguration compiled, - KafkaBrokerCatalog catalog, - ValidatedDestinationRegistry destinations, - ObjectProvider> producer, - ObjectProvider declaredSecurity, - ObjectProvider securityConfigurer, - MessagingSettings settings) { - return spec -> { - KafkaBrokerSettings broker = catalog.single().getValue(); - if (broker.enableAutoCommit()) { - throw new IllegalStateException( - "app.messaging.brokers." - + catalog.single().getKey() - + ".enable-auto-commit=true: the platform consumer commits an offset only after" - + " its delivery was settled, and a timer commit would move past unprocessed" - + " messages"); - } - return KafkaPolledRegistration.open( - spec, - consumerConfig(spec.profile(), compiled, catalog, declaredSecurity, securityConfigurer), - quarantine(spec.profile(), destinations, producer.getObject()), - settings.getShutdown().getDrainDeadline()); - }; - } - - /** - * Subscribes the consumed destinations when the context starts; empty without a handler bean. - * - * @param consumers the consume pipelines, present when a handler bean exists - * @param transport the selected transport - * @return the lifecycle - */ - @Bean - public KafkaConsumerLifecycle messagingKafkaConsumers( - ObjectProvider consumers, ObjectProvider transport) { - return new KafkaConsumerLifecycle( - () -> consumers.stream().flatMap(found -> found.consumers().stream()).toList(), - transport::getObject); - } - - /** The consumer's client configuration; package-visible so a test can read what it holds. */ - static Map consumerConfig( - DestinationProfile profile, - CompiledMessagingConfiguration compiled, - KafkaBrokerCatalog catalog, - ObjectProvider declaredSecurity, - ObjectProvider securityConfigurer) { - KafkaBrokerSettings broker = catalog.single().getValue(); - Map config = new HashMap<>(); - config.put( - ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, String.join(",", broker.bootstrapServers())); - config.put( - ConsumerConfig.GROUP_ID_CONFIG, - profile - .consumer() - .group() - .filter(group -> !group.isBlank()) - .orElseThrow( - () -> - new IllegalStateException( - "destination '" - + profile.name().value() - + "' is consumed but declares no consumer.group"))); - config.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, false); - config.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest"); - config.put(ConsumerConfig.ISOLATION_LEVEL_CONFIG, "read_committed"); - config.put(ConsumerConfig.MAX_POLL_RECORDS_CONFIG, profile.consumer().prefetch()); - config.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, ByteArrayDeserializer.class); - config.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, ByteArrayDeserializer.class); - config.putAll( - KafkaMessagingAutoConfiguration.clientSecurity( - compiled, declaredSecurity, securityConfigurer, BrokerSecurityProfile::consumer)); - return config; - } - - private static KafkaQuarantinePublisher quarantine( - DestinationProfile profile, - ValidatedDestinationRegistry destinations, - Producer producer) { - if (!profile.deadLetter().enabled()) { - return KafkaQuarantinePublisher.unavailable(); - } - DestinationName deadLetter = profile.deadLetter().destination().orElseThrow(); - String topic = - destinations - .require(deadLetter) - .physical() - .topic() - .orElseThrow( - () -> - new IllegalStateException( - "dead-letter destination '" + deadLetter.value() + "' has no Kafka topic")); - return new KafkaDeadLetterQuarantine(producer, topic, profile.producer().timeout()); - } - - /** The transport's consumer factory: a spec in, a live subscription out. */ - @FunctionalInterface - public interface KafkaConsumerFactory - extends Function {} -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaConsumerLifecycle.java b/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaConsumerLifecycle.java deleted file mode 100644 index e12e3520..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaConsumerLifecycle.java +++ /dev/null @@ -1,69 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.transport.MessagingTransport; -import dev.caskeleton.messaging.transport.TransportConsumerRegistration; -import dev.caskeleton.messaging.transport.TransportConsumerSpec; -import java.util.ArrayList; -import java.util.List; -import java.util.Objects; -import java.util.function.Supplier; -import org.springframework.context.SmartLifecycle; - -/** - * Subscribes every consumed destination through the transport when the context starts, and closes - * the subscriptions when it stops. - * - *

An application with no handler bean has no consumed destination, and this opens nothing. Both - * collaborators are looked up at start rather than injected, so a context that fails a startup - * validation fails on that validation, not on a client this bean asked for too early. - */ -final class KafkaConsumerLifecycle implements SmartLifecycle { - - private final Supplier> consumers; - private final Supplier transport; - private final List registrations = new ArrayList<>(); - - KafkaConsumerLifecycle( - Supplier> consumers, Supplier transport) { - this.consumers = Objects.requireNonNull(consumers, "consumers must not be null"); - this.transport = Objects.requireNonNull(transport, "transport must not be null"); - } - - @Override - public synchronized void start() { - if (!registrations.isEmpty()) { - return; - } - List consumed = consumers.get(); - if (consumed.isEmpty()) { - return; - } - MessagingTransport selected = transport.get(); - for (MessageConsumers.Consumer consumer : consumed) { - registrations.add( - selected.register(new TransportConsumerSpec(consumer.profile(), consumer.sink()))); - } - } - - @Override - public synchronized void stop() { - registrations.forEach(TransportConsumerRegistration::close); - registrations.clear(); - } - - @Override - public synchronized boolean isRunning() { - return !registrations.isEmpty(); - } - - /** - * Stops before the publish drain, because a handler still running may dead-letter through the - * publisher that drain closes. - * - * @return the lifecycle phase - */ - @Override - public int getPhase() { - return Integer.MAX_VALUE - 512; - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantine.java b/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantine.java deleted file mode 100644 index 85ad9c2e..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantine.java +++ /dev/null @@ -1,69 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.header.ReservedHeaders; -import dev.caskeleton.messaging.kafka.KafkaQuarantinePublisher; -import java.nio.charset.StandardCharsets; -import java.time.Duration; -import java.util.Objects; -import java.util.concurrent.ExecutionException; -import java.util.concurrent.TimeUnit; -import java.util.concurrent.TimeoutException; -import org.apache.kafka.clients.consumer.ConsumerRecord; -import org.apache.kafka.clients.producer.Producer; -import org.apache.kafka.clients.producer.ProducerRecord; -import org.apache.kafka.common.header.internals.RecordHeaders; - -/** - * Parks a record the consumer cannot deliver on the destination's dead-letter topic. - * - *

Used by the Kafka consumer for the two cases the typed pipeline never sees: a record that - * cannot even be rebuilt into an envelope, and a delivery whose attempt budget is spent. The record - * is copied as it arrived — key, value and headers — with the failure category and code added, so - * the message a redrive reads is the message that failed. - * - *

It answers {@code true} only once the broker has acknowledged the copy. The consumer commits - * past the source offset on that answer, so an unconfirmed write must say {@code false} and leave - * the source to be read again. - */ -final class KafkaDeadLetterQuarantine implements KafkaQuarantinePublisher { - - private final Producer producer; - private final String topic; - private final Duration timeout; - - KafkaDeadLetterQuarantine(Producer producer, String topic, Duration timeout) { - this.producer = Objects.requireNonNull(producer, "producer must not be null"); - this.topic = Objects.requireNonNull(topic, "topic must not be null"); - this.timeout = Objects.requireNonNull(timeout, "timeout must not be null"); - } - - @Override - public boolean quarantine( - ConsumerRecord record, FailureCategory category, Throwable reason) { - RecordHeaders headers = new RecordHeaders(record.headers().toArray()); - headers.remove(ReservedHeaders.FAILURE_CATEGORY); - headers.remove(ReservedHeaders.FAILURE_CODE); - headers.add( - ReservedHeaders.FAILURE_CATEGORY, - bytes(category == null ? FailureCategory.POISON_MESSAGE.name() : category.name())); - headers.add( - ReservedHeaders.FAILURE_CODE, - bytes(reason == null ? "UNKNOWN" : reason.getClass().getSimpleName())); - try { - producer - .send(new ProducerRecord<>(topic, null, record.key(), record.value(), headers)) - .get(timeout.toMillis(), TimeUnit.MILLISECONDS); - return true; - } catch (InterruptedException interrupted) { - Thread.currentThread().interrupt(); - return false; - } catch (ExecutionException | TimeoutException | RuntimeException notConfirmed) { - return false; - } - } - - private static byte[] bytes(String value) { - return value.getBytes(StandardCharsets.UTF_8); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java b/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java deleted file mode 100644 index 05eadb6b..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java +++ /dev/null @@ -1,322 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -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; -import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; -import org.springframework.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; - -/** - * Wires the Kafka adapter's validators and security configurer. - * - *

Conditional on the Kafka client being present, so a service that depends on the starter for - * RabbitMQ alone does not fail to start because a Kafka class is missing. That is the reason the - * per-broker configurations are separate classes rather than sections of one: a single class - * referencing both clients would require both on the classpath. - * - *

No producer or consumer bean is created here. Those need a broker profile the application has - * not declared yet at this point, and a default-constructed producer would connect to {@code - * 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 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) -@org.springframework.context.annotation.Import(KafkaConsumerConfiguration.class) -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. - * - * @return the validator - */ - @Bean - @ConditionalOnMissingBean - public KafkaProfileValidator kafkaProfileValidator() { - return new KafkaProfileValidator(); - } - - /** - * Runs the Kafka profile validator over every Kafka 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 Kafka profile validator - * @return the startup validation - */ - @Bean - public StartupProfileValidation - kafkaProfileStartupValidation( - ObjectProvider profiles, - CompiledMessagingConfiguration compiled, - KafkaBrokerCatalog catalog, - KafkaProfileValidator validator) { - return new StartupProfileValidation<>( - () -> - java.util.stream.Stream.concat( - configuredKafkaProfiles(compiled, catalog).stream(), profiles.orderedStream()) - .toList(), - validator::validate); - } - - /** - * The Kafka client settings of every Kafka broker entry, bound by this starter (S7-#9b). - * - * @param environment the resolved environment - * @param compiled the compiled configuration naming the Kafka entries - * @return the catalog - */ - @Bean - @ConditionalOnMissingBean - public KafkaBrokerCatalog kafkaBrokerCatalog( - org.springframework.core.env.Environment environment, - CompiledMessagingConfiguration compiled) { - return new KafkaBrokerCatalog(KafkaBrokerSettings.bindAll(environment, compiled)); - } - - /** - * Returns the Kafka transaction profile validator. - * - * @return the validator - */ - @Bean - @ConditionalOnMissingBean - public KafkaTransactionProfileValidator kafkaTransactionProfileValidator() { - return new KafkaTransactionProfileValidator(); - } - - /** - * Returns the producer failure classifier. - * - * @return the classifier - */ - @Bean - @ConditionalOnMissingBean - public KafkaPublishFailureClassifier kafkaPublishFailureClassifier() { - return new KafkaPublishFailureClassifier(); - } - - /** - * Returns the Kafka client 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 KafkaSecurityConfigurer kafkaSecurityConfigurer( - CredentialRuntimeRegistry credentials, BrokerTlsPolicy tlsPolicy) { - return new KafkaSecurityConfigurer(credentials, tlsPolicy); - } - - /** - * The producer this transport publishes through (MSG-INT-003). - * - *

Built from the one {@code app.messaging.brokers.} entry of type {@code kafka}. It used - * to read {@code spring.kafka.bootstrap-servers} while the compiler required and validated the - * entry's own {@code bootstrap-servers}, so one broker was described twice and only one of the - * two descriptions reached the client. - * - *

Byte-array serializers on purpose: the platform's codec registry decides the wire format, - * and a serializer configured here would be a second encoder disagreeing with it. - * - * @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( - CompiledMessagingConfiguration compiled, - KafkaBrokerCatalog catalog, - ObjectProvider declaredSecurity, - ObjectProvider securityConfigurer) { - return new org.apache.kafka.clients.producer.KafkaProducer<>( - producerConfig(compiled, catalog, declaredSecurity, securityConfigurer)); - } - - /** The producer's client configuration; package-visible so a test can read what it holds. */ - static java.util.Map producerConfig( - CompiledMessagingConfiguration compiled, - KafkaBrokerCatalog catalog, - ObjectProvider declaredSecurity, - ObjectProvider securityConfigurer) { - KafkaBrokerSettings broker = catalog.single().getValue(); - java.util.Map config = new java.util.HashMap<>(); - config.put( - org.apache.kafka.clients.producer.ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, - String.join(",", broker.bootstrapServers())); - config.put( - org.apache.kafka.clients.producer.ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, - org.apache.kafka.common.serialization.ByteArraySerializer.class); - config.put( - org.apache.kafka.clients.producer.ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, - org.apache.kafka.common.serialization.ByteArraySerializer.class); - // The entry's delivery settings, which KafkaProfileValidator checks (a stable broker must keep - // acks=all and idempotence) and which used to be replaced here by hard-coded values. - config.put(org.apache.kafka.clients.producer.ProducerConfig.ACKS_CONFIG, broker.acks()); - config.put( - org.apache.kafka.clients.producer.ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, - broker.enableIdempotence()); - config.put( - org.apache.kafka.clients.producer.ProducerConfig.MAX_IN_FLIGHT_REQUESTS_PER_CONNECTION, - broker.maxInFlightRequestsPerConnection()); - // Kafka refuses delivery.timeout.ms below linger.ms + request.timeout.ms (5ms + 30s by - // default), which made the documented 30s a startup failure. The request timeout follows a - // short delivery deadline down, and records are not held back to fill a batch. - long delivery = broker.deliveryTimeout().toMillis(); - config.put(org.apache.kafka.clients.producer.ProducerConfig.LINGER_MS_CONFIG, 0); - config.put( - org.apache.kafka.clients.producer.ProducerConfig.REQUEST_TIMEOUT_MS_CONFIG, - Math.toIntExact(Math.min(30_000L, delivery))); - config.put( - org.apache.kafka.clients.producer.ProducerConfig.DELIVERY_TIMEOUT_MS_CONFIG, - Math.toIntExact(delivery)); - // send() blocks the caller while it waits for metadata or buffer space, for Kafka's default - // 60s — before the publish deadline is even applied. Bounded by the default deadline instead. - config.put( - org.apache.kafka.clients.producer.ProducerConfig.MAX_BLOCK_MS_CONFIG, - dev.caskeleton.messaging.api.publish.PublishOptions.defaults().timeout().toMillis()); - config.putAll( - clientSecurity( - compiled, declaredSecurity, securityConfigurer, BrokerSecurityProfile::producer)); - return config; - } - - /** - * A client'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. The producer and the consumers use - * the same rule, each with its own credential. - * - * @param role picks the producer or the consumer credential of the profile - */ - static java.util.Map clientSecurity( - CompiledMessagingConfiguration compiled, - ObjectProvider declaredSecurity, - ObjectProvider securityConfigurer, - java.util.function.Function< - BrokerSecurityProfile, dev.caskeleton.messaging.security.BrokerCredentialProfile> - role) { - 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; a Kafka client cannot apply either without one"); - } - }); - return java.util.Map.of(); - } - if (profiles.size() > 1) { - throw new IllegalStateException( - "a Kafka client 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; a Kafka client cannot" - + " resolve its credential and must not connect without it"); - } - return configurer.configure( - profile, role.apply(profile), TLS_PROTOCOLS, java.time.Instant.now()); - } - - /** - * The Kafka transport the publisher writes through and the consumers subscribe through. - * - *

It was built publish-only, so {@code register} refused every subscription with {@code - * KAFKA_CONSUMER_NOT_CONFIGURED} and the consumer runtime was never constructed (S7-#2). - * - * @param producer the configured producer - * @param consumers opens a live subscription for a destination - * @return the transport - */ - @Bean - @ConditionalOnMissingBean(dev.caskeleton.messaging.transport.MessagingTransport.class) - public dev.caskeleton.messaging.kafka.KafkaMessagingTransport messagingKafkaTransport( - org.apache.kafka.clients.producer.Producer producer, - KafkaConsumerConfiguration.KafkaConsumerFactory consumers) { - // Generation 1 for the life of the producer. A SASL credential rotation does not replace the - // producer: KafkaCredentialCallbackHandler reads the rotated secret at the next authentication, - // so there is no second transport generation to install. - return new dev.caskeleton.messaging.kafka.KafkaMessagingTransport( - "kafka", 1L, producer, consumers); - } - - private static java.util.List - configuredKafkaProfiles(CompiledMessagingConfiguration compiled, KafkaBrokerCatalog catalog) { - return catalog.brokers().entrySet().stream() - .map( - entry -> { - BrokerSettings broker = compiled.brokers().get(entry.getKey()); - KafkaBrokerSettings client = entry.getValue(); - return new dev.caskeleton.messaging.kafka.KafkaBrokerProfile( - entry.getKey(), - broker.stable(), - broker.production(), - client.bootstrapServers(), - client.enableIdempotence(), - client.acks(), - client.maxInFlightRequestsPerConnection(), - client.deliveryTimeout(), - client.enableAutoCommit(), - client.consumerGroup(), - broker.tlsEnabled(), - broker.authenticationEnabled()); - }) - .toList(); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaPolledRegistration.java b/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaPolledRegistration.java deleted file mode 100644 index c309a137..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaPolledRegistration.java +++ /dev/null @@ -1,169 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.kafka.KafkaConsumerRegistrar; -import dev.caskeleton.messaging.kafka.KafkaQuarantinePublisher; -import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator; -import dev.caskeleton.messaging.transport.TransportConsumerRegistration; -import dev.caskeleton.messaging.transport.TransportConsumerSpec; -import java.time.Duration; -import java.time.Instant; -import java.util.Map; -import java.util.concurrent.CompletionStage; -import java.util.concurrent.ExecutorService; -import java.util.concurrent.Executors; -import java.util.concurrent.TimeUnit; -import org.apache.kafka.clients.consumer.KafkaConsumer; - -/** - * One live Kafka subscription: a {@link KafkaConsumerRegistrar}, the poll thread that drives it and - * the bounded pool its handlers run on. - * - *

The poll thread is the only thread that touches the {@code KafkaConsumer}: the registrar - * polls, commits and closes there, and handler work runs on a pool sized by the destination's - * {@code consumer.concurrency}. Offsets are committed through the contiguous watermark of settled - * deliveries, never on a timer. - * - *

{@link #close()} stops dispatching, lets running handlers finish up to the drain deadline, - * commits what they settled and closes the client. Work still running at the deadline is abandoned - * unsettled, so the broker redelivers it rather than the platform pretending it completed. - */ -final class KafkaPolledRegistration implements TransportConsumerRegistration { - - private static final System.Logger LOG = - System.getLogger(KafkaPolledRegistration.class.getName()); - - private static final Duration POLL_TIMEOUT = Duration.ofMillis(200); - - private final String name; - private final KafkaConsumerRegistrar registrar; - private final GracefulShutdownCoordinator drain; - private final ExecutorService handlers; - private final Duration drainDeadline; - private final Thread poller; - private volatile boolean stopping; - - private KafkaPolledRegistration( - TransportConsumerSpec spec, - Map clientConfig, - KafkaQuarantinePublisher quarantine, - Duration drainDeadline) { - this.name = spec.profile().name().value(); - this.drainDeadline = drainDeadline; - String topic = - spec.profile() - .physical() - .topic() - .orElseThrow( - () -> - new IllegalStateException( - "destination '" + name + "' is consumed from Kafka but has no topic")); - this.drain = new GracefulShutdownCoordinator(drainDeadline); - this.handlers = - Executors.newFixedThreadPool( - spec.profile().consumer().concurrency(), - Thread.ofPlatform().name("messaging-kafka-handler-" + name + "-", 0).factory()); - this.registrar = - new KafkaConsumerRegistrar( - spec, - new KafkaConsumer(clientConfig), - handlers, - drain, - POLL_TIMEOUT, - quarantine); - registrar.subscribe(topic); - this.poller = Thread.ofPlatform().name("messaging-kafka-poll-" + name).unstarted(this::loop); - } - - /** - * Opens the client, subscribes and starts polling. - * - * @param spec the destination and the pipeline its deliveries go through - * @param clientConfig the consumer client configuration - * @param quarantine where a record the consumer cannot deliver is parked - * @param drainDeadline how long {@link #close()} lets running handlers finish - * @return the live registration - */ - static KafkaPolledRegistration open( - TransportConsumerSpec spec, - Map clientConfig, - KafkaQuarantinePublisher quarantine, - Duration drainDeadline) { - KafkaPolledRegistration registration = - new KafkaPolledRegistration(spec, clientConfig, quarantine, drainDeadline); - registration.poller.start(); - return registration; - } - - @Override - public CompletionStage pause(String scope) { - return registrar.pause(scope); - } - - @Override - public CompletionStage resume(String scope) { - return registrar.resume(scope); - } - - @Override - public boolean isActive() { - return registrar.isActive() && !stopping; - } - - @Override - public void close() { - Instant startedAt = Instant.now(); - drain.beginDrain(startedAt); - Instant deadline = startedAt.plus(drainDeadline); - while (!drain.isDrained(Instant.now()) && Instant.now().isBefore(deadline)) { - if (!sleep(Duration.ofMillis(50))) { - break; - } - } - stopping = true; - try { - poller.join(POLL_TIMEOUT.toMillis() * 10); - } catch (InterruptedException interrupted) { - Thread.currentThread().interrupt(); - } - handlers.shutdownNow(); - try { - handlers.awaitTermination(1, TimeUnit.SECONDS); - } catch (InterruptedException interrupted) { - Thread.currentThread().interrupt(); - } - } - - private void loop() { - try { - while (!stopping) { - try { - registrar.pollOnce(Instant.now()); - } catch (RuntimeException failure) { - // A failed poll or commit is not a reason to stop consuming for good: nothing past the - // last successful commit is lost, and the next cycle retries it. - LOG.log( - System.Logger.Level.WARNING, - "Kafka consumer for " + name + " failed a poll cycle: " + failure); - sleep(POLL_TIMEOUT); - } - if (!drain.isAcceptingWork()) { - // pollOnce no longer polls once draining begins; it only applies settlements and - // commits. Without a pause the loop would spin. - sleep(Duration.ofMillis(20)); - } - } - } finally { - registrar.close(); - } - } - - private static boolean sleep(Duration duration) { - try { - Thread.sleep(duration.toMillis()); - return true; - } catch (InterruptedException interrupted) { - Thread.currentThread().interrupt(); - return false; - } - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantineTest.java b/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantineTest.java deleted file mode 100644 index 35c6d145..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantineTest.java +++ /dev/null @@ -1,82 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.header.ReservedHeaders; -import java.nio.charset.StandardCharsets; -import java.time.Duration; -import java.util.List; -import java.util.stream.StreamSupport; -import org.apache.kafka.clients.consumer.ConsumerRecord; -import org.apache.kafka.clients.producer.MockProducer; -import org.apache.kafka.clients.producer.ProducerRecord; -import org.apache.kafka.common.header.Header; -import org.apache.kafka.common.serialization.ByteArraySerializer; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.params.ParameterizedTest; -import org.junit.jupiter.params.provider.EnumSource; - -/** - * The dead-letter copy says which of the two quarantine paths wrote it (review 2026-11-01 06-14, - * re-review round 2 RR-02-16): a record that could not be rebuilt at all and one whose handler - * spent its attempt budget leave different failure-category bytes, so a redrive can tell a message - * that will never decode from one an outage kept failing. - */ -class KafkaDeadLetterQuarantineTest { - - private static final String DEAD_LETTER_TOPIC = "orders.dlq"; - - @ParameterizedTest - @EnumSource( - value = FailureCategory.class, - names = {"DESERIALIZATION", "POISON_MESSAGE"}) - @DisplayName("격리 사본은 원래 header를 지키고 failure-category를 호출자가 준 분류 하나로 쓴다") - void theCopyCarriesTheCategoryTheCallerGaveInPlaceOfAnyEarlierOne(FailureCategory category) { - // given - MockProducer producer = - new MockProducer<>(true, null, new ByteArraySerializer(), new ByteArraySerializer()); - KafkaDeadLetterQuarantine quarantine = - new KafkaDeadLetterQuarantine(producer, DEAD_LETTER_TOPIC, Duration.ofSeconds(1)); - ConsumerRecord record = - new ConsumerRecord<>("orders", 0, 7L, bytes("order-7"), bytes("{\"broken\"")); - record.headers().add("trace-id", bytes("trace-1")); - record.headers().add(ReservedHeaders.FAILURE_CATEGORY, bytes("STALE_FROM_AN_EARLIER_HOP")); - - // when - boolean confirmed = quarantine.quarantine(record, category, new IllegalStateException("x")); - - // then - ProducerRecord copy = producer.history().getFirst(); - assertThat( - List.of( - confirmed, - copy.topic(), - text(copy.value()), - values(copy, "trace-id"), - values(copy, ReservedHeaders.FAILURE_CATEGORY), - values(copy, ReservedHeaders.FAILURE_CODE))) - .containsExactly( - true, - DEAD_LETTER_TOPIC, - "{\"broken\"", - List.of("trace-1"), - List.of(category.name()), - List.of("IllegalStateException")); - } - - private static List values(ProducerRecord record, String header) { - return StreamSupport.stream(record.headers().headers(header).spliterator(), false) - .map(Header::value) - .map(KafkaDeadLetterQuarantineTest::text) - .toList(); - } - - private static byte[] bytes(String value) { - return value.getBytes(StandardCharsets.UTF_8); - } - - private static String text(byte[] value) { - return new String(value, StandardCharsets.UTF_8); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/README.md b/src/platforms/messaging/messaging-spring-boot-starter/README.md deleted file mode 100644 index 2cb6c3e2..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/README.md +++ /dev/null @@ -1,43 +0,0 @@ -# messaging-spring-boot-starter - -## 아티팩트 분리 - -기본 `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 -``` - -- 기본 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 - `:adapter:outbound:messaging`과 Kafka 전용 `:adapter:outbound:messaging-kafka`가 분리돼 있다. - -## 현재 broker/runtime 지원 범위 - -### Kafka - -Kafka publish runtime은 **Kafka capability artifact를 추가한 composition에서만** 조립된다. -`KafkaMessagingTransport`는 publish runtime으로 설치되지만, `KafkaConsumerRegistrar`는 capability -starter나 app-bootstrap에서 자동 생성하지 않는다. 따라서 현재 자동조립된 transport에 consume -registration을 요청하면 `KAFKA_CONSUMER_NOT_CONFIGURED`로 실패한다. - -consume을 채택하려면 애플리케이션 composition이 별도로 `KafkaConsumerRegistrar`와 handler sink를 -조립해야 한다. leaf 안의 consumer/rebalance/settlement 테스트가 초록이라는 사실은 capability -starter가 consumer runtime까지 자동 제공한다는 뜻이 아니다. - -### RabbitMQ (삭제됨) - -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/src/platforms/messaging/messaging-spring-boot-starter/build.gradle b/src/platforms/messaging/messaging-spring-boot-starter/build.gradle deleted file mode 100644 index efed4b94..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/build.gradle +++ /dev/null @@ -1,80 +0,0 @@ -plugins { - id 'ca.platform-module' - id 'ca.spring-config' -} - -// Scopes, not a flat list of `api`. -// -// `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. -testing { - suites { - integrationTest(JvmTestSuite) { - dependencies { - implementation project() - } - } - } -} -configurations { - integrationTestImplementation.extendsFrom testImplementation - integrationTestRuntimeOnly.extendsFrom testRuntimeOnly -} - -dependencies { - // Types an adopter writes against: envelopes, destinations, publish results, profiles, ports. - api project(':messaging:messaging-core-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-reliability-api') - - // Wired by the auto-configurations and never named in an adopter's source. - implementation project(':messaging:messaging-schema-json') - // 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') - // The relay and consumer logic, and the PostgreSQL stores behind their ports. - implementation project(':messaging:messaging-reliability') - implementation project(':messaging:messaging-reliability-jdbc-postgresql') - implementation project(':messaging:messaging-admin') - - implementation 'org.springframework.boot:spring-boot-autoconfigure' - implementation 'org.springframework.boot:spring-boot-actuator' - - 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 it only to the test graph; the production starter remains broker-neutral. - testImplementation project(':messaging:messaging-spring-boot-starter-kafka') - // 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 - // to ask for it; production code does not, and adding it here keeps that asymmetry visible. - testImplementation 'org.yaml:snakeyaml' - // The live round trip. MSG-INT-003's membership rule is that the starter earns - // app-bootstrap membership in the same change that proves a real broker round trip, - // so the proof has to run somewhere — and the starter is where the whole platform - // assembles. - integrationTestImplementation project(':messaging:messaging-spring-boot-starter-kafka') - integrationTestImplementation 'org.testcontainers:testcontainers-junit-jupiter' - integrationTestImplementation 'org.testcontainers:testcontainers-kafka' - // The consume round trip's inbox lane: a real PostgreSQL behind the JDBC inbox, joined to the - // handler's own write by a real transaction manager. - integrationTestImplementation project(':messaging:messaging-reliability') - integrationTestImplementation project(':messaging:messaging-reliability-jdbc-postgresql') - integrationTestImplementation 'org.springframework:spring-jdbc' - integrationTestImplementation 'org.testcontainers:testcontainers-postgresql' - integrationTestImplementation 'org.postgresql:postgresql' -} - -strictTestLanes { - lane('integrationTest') { - integration() - sourceSet = 'integrationTest' - description = 'Runs the assembled messaging starter round trip against real Kafka.' - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/gradle.lockfile b/src/platforms/messaging/messaging-spring-boot-starter/gradle.lockfile deleted file mode 100644 index e0ecae25..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/gradle.lockfile +++ /dev/null @@ -1,127 +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.11.4=integrationTestRuntimeClasspath,testRuntimeClasspath -com.fasterxml.jackson.core:jackson-annotations:2.21=integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -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,testAnnotationProcessor -com.github.luben:zstd-jni:1.5.6-10=integrationTestRuntimeClasspath,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,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,integrationTestAnnotationProcessor,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,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -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 -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,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -info.picocli:picocli:4.7.7=checkstyle -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.8=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-core:1.16.8=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-observation:1.16.8=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -javax.inject:javax.inject:1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -net.java.dev.jna:jna:5.18.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath -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-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=integrationTestCompileClasspath,integrationTestRuntimeClasspath,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=integrationTestCompileClasspath,testCompileClasspath -org.assertj:assertj-core:3.27.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.checkerframework:checker-qual:3.55.1=integrationTestRuntimeClasspath -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.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.hdrhistogram:HdrHistogram:2.2.2=integrationTestRuntimeClasspath,runtimeClasspath,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,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath -org.junit:junit-bom:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.latencyutils:LatencyUtils:2.0.3=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,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,testAnnotationProcessor -org.postgresql:postgresql:42.7.14=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.reflections:reflections:0.10.2=checkstyle -org.rnorth.duct-tape:duct-tape:1.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.slf4j:slf4j-api:2.0.20=integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs,spotbugsSlf4j,testRuntimeClasspath -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.springframework.boot:spring-boot-actuator:4.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework.boot:spring-boot-autoconfigure:4.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework.boot:spring-boot-configuration-processor:4.0.9=annotationProcessor -org.springframework.boot:spring-boot-test:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework.boot:spring-boot:4.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-aop:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-beans:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-context:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-core:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-expression:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-jdbc:7.0.10=integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -org.springframework:spring-test:7.0.10=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-tx:7.0.10=integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -org.testcontainers:testcontainers-database-commons:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-jdbc:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-junit-jupiter:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-kafka:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-postgresql:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.xerial.snappy:snappy-java:1.1.10.9=integrationTestRuntimeClasspath,testRuntimeClasspath -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -org.yaml:snakeyaml:2.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -tools.jackson.core:jackson-core:3.1.7=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -tools.jackson.core:jackson-databind:3.1.7=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -tools.jackson:jackson-bom:3.1.7=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -empty= diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingKafkaConsumeQualificationTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingKafkaConsumeQualificationTest.java deleted file mode 100644 index 13ad8fcb..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingKafkaConsumeQualificationTest.java +++ /dev/null @@ -1,461 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -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.HandleResult; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -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.destination.MessageDestination; -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.api.header.ReservedHeaders; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.inbox.IdempotentConsumer; -import dev.caskeleton.messaging.inbox.JdbcInboxRepository; -import dev.caskeleton.messaging.policy.ApiTier; -import dev.caskeleton.messaging.policy.ConsumerPolicy; -import dev.caskeleton.messaging.policy.DeadLetterPolicy; -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.policy.OrderingImpact; -import dev.caskeleton.messaging.policy.PayloadPolicy; -import dev.caskeleton.messaging.policy.PhysicalDestination; -import dev.caskeleton.messaging.policy.ProducerPolicy; -import dev.caskeleton.messaging.policy.RetryMode; -import dev.caskeleton.messaging.policy.RetryPolicy; -import dev.caskeleton.messaging.policy.SchemaPolicy; -import dev.caskeleton.messaging.schema.MessageContractKey; -import dev.caskeleton.messaging.schema.SchemaCompatibility; -import java.io.IOException; -import java.io.InputStream; -import java.nio.charset.StandardCharsets; -import java.time.Duration; -import java.time.Instant; -import java.util.List; -import java.util.Map; -import java.util.Optional; -import java.util.Properties; -import java.util.Set; -import java.util.concurrent.BlockingQueue; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import java.util.concurrent.LinkedBlockingQueue; -import java.util.concurrent.TimeUnit; -import java.util.concurrent.atomic.AtomicInteger; -import java.util.function.Function; -import javax.sql.DataSource; -import org.apache.kafka.clients.admin.Admin; -import org.apache.kafka.clients.admin.AdminClientConfig; -import org.apache.kafka.clients.consumer.ConsumerConfig; -import org.apache.kafka.clients.consumer.ConsumerRecord; -import org.apache.kafka.clients.consumer.KafkaConsumer; -import org.apache.kafka.clients.consumer.OffsetAndMetadata; -import org.apache.kafka.common.TopicPartition; -import org.apache.kafka.common.serialization.ByteArrayDeserializer; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.condition.EnabledIf; -import org.springframework.boot.autoconfigure.AutoConfigurations; -import org.springframework.boot.test.context.runner.ApplicationContextRunner; -import org.springframework.jdbc.core.JdbcTemplate; -import org.springframework.jdbc.datasource.DataSourceTransactionManager; -import org.springframework.jdbc.datasource.DriverManagerDataSource; -import org.springframework.transaction.support.TransactionTemplate; -import org.testcontainers.DockerClientFactory; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; -import org.testcontainers.kafka.KafkaContainer; -import org.testcontainers.postgresql.PostgreSQLContainer; - -/** - * A message published through the assembled platform is consumed by a {@code MessageHandler} bean - * on a real broker (owner decision 10, S7-#2). - * - *

The consume side had three contracts and no assembly: the typed handler had no caller, the - * Kafka consumer runtime was never constructed, and the transport the starter built refused every - * subscription with {@code KAFKA_CONSUMER_NOT_CONFIGURED}. These lanes run the whole path — - * publish, poll, decode, inbox, handler, settlement, offset commit — against Kafka, and against - * PostgreSQL for the inbox. - */ -@Testcontainers -@EnabledIf(value = "dockerAvailable", disabledReason = "Docker not available for the live broker") -class MessagingKafkaConsumeQualificationTest { - - private static final MessageType CREATED = new MessageType("order.created"); - - @Container - static final KafkaContainer KAFKA = new KafkaContainer(System.getProperty("ca.test.image.kafka")); - - // @Container: the Testcontainers JUnit extension owns this lifecycle. - @SuppressWarnings("resource") - @Container - static final PostgreSQLContainer POSTGRES = - new PostgreSQLContainer(System.getProperty("ca.test.image.postgres-16")) - .withDatabaseName("messaging") - .withUsername("messaging") - .withPassword("messaging"); - - static boolean dockerAvailable() { - return DockerClientFactory.instance().isDockerAvailable(); - } - - /** The payload the handlers are typed on. */ - record OrderCreated(String orderId) {} - - @Test - @DisplayName("플랫폼으로 발행한 메시지를 handler bean이 typed payload로 받고 offset이 commit된다") - void aPublishedMessageIsConsumedByTheHandlerBeanAndItsOffsetIsCommitted() { - // given - DestinationName orders = new DestinationName("consume-round-trip"); - BlockingQueue received = new LinkedBlockingQueue<>(); - MessageHandler handler = - handler( - orders, - delivery -> { - received.add(delivery.message().payload()); - return HandleResult.success(); - }); - - runner(orders, handler, RetryPolicy.none(), ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED) - .run( - context -> { - assertThat(context).hasNotFailed(); - - // when - publish(context.getBean(MessagePublisher.class), orders, envelope(MessageId.newId())); - - // then - assertThat(received.poll(60, TimeUnit.SECONDS)) - .as("the handler bean is called with the decoded payload") - .isEqualTo(new OrderCreated("o-1")); - assertThat(committedOffset(group(orders), orders.value(), 1)) - .as("the offset is committed once the delivery was settled") - .isEqualTo(1L); - }); - } - - @Test - @DisplayName("같은 메시지가 다시 배달돼도 inbox가 handler의 효과를 한 번만 남긴다") - void aRedeliveredMessageIsAppliedOnceThroughThePostgresInbox() throws Exception { - // given - DestinationName orders = new DestinationName("consume-inbox"); - DataSource dataSource = dataSource(); - JdbcTemplate jdbc = new JdbcTemplate(dataSource); - jdbc.execute("DROP TABLE IF EXISTS messaging_inbox"); - jdbc.execute("DROP TABLE IF EXISTS order_projection"); - jdbc.execute(inboxMigration()); - jdbc.execute("CREATE TABLE order_projection (order_id TEXT NOT NULL)"); - TransactionTemplate transactions = - new TransactionTemplate(new DataSourceTransactionManager(dataSource)); - IdempotentConsumer inbox = - new IdempotentConsumer( - new JdbcInboxRepository(dataSource), - new IdempotentConsumer.TransactionRunner() { - @Override - public T inTransaction(java.util.function.Supplier work) { - return transactions.execute(status -> work.get()); - } - }); - AtomicInteger calls = new AtomicInteger(); - MessageHandler handler = - handler( - orders, - delivery -> { - calls.incrementAndGet(); - // The business write joins the transaction the inbox reservation runs in. - jdbc.update( - "INSERT INTO order_projection (order_id) VALUES (?)", - delivery.message().payload().orderId()); - return HandleResult.success(); - }); - MessageEnvelope message = envelope(MessageId.newId()); - - runner(orders, handler, RetryPolicy.none(), ExternalSideEffectGuarantee.INBOX_TRANSACTIONAL) - .withBean(IdempotentConsumer.class, () -> inbox) - .run( - context -> { - assertThat(context).hasNotFailed(); - MessagePublisher publisher = context.getBean(MessagePublisher.class); - - // when - publish(publisher, orders, message); - publish(publisher, orders, message); - - // then - assertThat(committedOffset(group(orders), orders.value(), 2)) - .as("both copies were settled") - .isEqualTo(2L); - assertThat(jdbc.queryForObject("SELECT count(*) FROM order_projection", Long.class)) - .as("the second copy found the reservation and did not apply the effect again") - .isEqualTo(1L); - assertThat(calls.get()).isEqualTo(1); - }); - } - - @Test - @DisplayName("계속 Retry로 답하는 메시지는 시도 횟수를 다 쓰면 DLQ 토픽에 남고 offset은 넘어간다") - void aMessageItsHandlerKeepsRetryingIsParkedOnTheDeadLetterTopicOnceItsAttemptsAreSpent() { - // given - DestinationName orders = new DestinationName("consume-retry"); - AtomicInteger attempts = new AtomicInteger(); - MessageHandler handler = - handler( - orders, - delivery -> { - attempts.incrementAndGet(); - return new HandleResult.Retry( - FailureDescriptor.of( - FailureCategory.PROCESSING_TRANSIENT, "DOWNSTREAM_BUSY", "try later")); - }); - RetryPolicy twoAttempts = - new RetryPolicy( - RetryMode.PAUSE_PARTITION, - 2, - Duration.ZERO, - Duration.ZERO, - 1.0, - false, - OrderingImpact.PRESERVE, - Set.of(), - Set.of()); - MessageId id = MessageId.newId(); - - runner(orders, handler, twoAttempts, ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED) - .run( - context -> { - assertThat(context).hasNotFailed(); - - // when - publish(context.getBean(MessagePublisher.class), orders, envelope(id)); - - // then - assertThat(readMessageIds(dlq(orders).value())) - .as("the message is parked where someone can redrive it, identity intact") - .contains(id.value().toString()); - assertThat(committedOffset(group(orders), orders.value(), 1)).isEqualTo(1L); - assertThat(attempts.get()).isEqualTo(2); - }); - } - - private static ApplicationContextRunner runner( - DestinationName orders, - MessageHandler handler, - RetryPolicy retry, - ExternalSideEffectGuarantee sideEffect) { - // Created up front. A consumer that subscribes before its topic exists waits for the next - // metadata refresh — five minutes by default — before it is assigned anything. - createTopics(orders.value(), dlq(orders).value()); - return new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingPlatformRootAutoConfiguration.class)) - .withPropertyValues( - "app.messaging.enabled=true", - "app.messaging.broker=kafka", - "app.messaging.brokers.kafka.type=kafka", - "app.messaging.brokers.kafka.bootstrap-servers[0]=" + KAFKA.getBootstrapServers(), - "app.messaging.shutdown.drain-deadline=5s") - .withBean( - MessageContracts.class, - () -> - new MessageContracts( - Map.of( - new MessageContractKey(CREATED, new SchemaVersion(1)), OrderCreated.class))) - .withBean( - orders.value() + "Profile", - DestinationProfile.class, - () -> profile(orders, dlq(orders), retry, sideEffect)) - .withBean( - orders.value() + "DlqProfile", - DestinationProfile.class, - () -> - profile( - dlq(orders), - null, - RetryPolicy.none(), - ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED)) - .withBean(orders.value() + "Handler", MessageHandler.class, () -> handler); - } - - private static MessageHandler handler( - DestinationName orders, Function, HandleResult> body) { - return new MessageHandler<>() { - @Override - public MessageDestination destination() { - return new MessageDestination<>(orders, CREATED, OrderCreated.class); - } - - @Override - public CompletionStage handle(MessageDelivery delivery) { - return CompletableFuture.completedFuture(body.apply(delivery)); - } - }; - } - - private static void publish( - MessagePublisher publisher, DestinationName orders, MessageEnvelope message) { - PublishCompletion completion = - publisher - .publish( - new MessageDestination<>(orders, CREATED, OrderCreated.class), - message, - PublishOptions.defaults()) - .toCompletableFuture() - .join() - .completion(); - assertThat(completion).isEqualTo(PublishCompletion.CONFIRMED); - } - - private static DestinationName dlq(DestinationName source) { - return new DestinationName(source.value() + "-dlq"); - } - - private static String group(DestinationName destination) { - return destination.value() + "-projection"; - } - - private static DestinationProfile profile( - DestinationName name, - DestinationName deadLetter, - RetryPolicy retry, - ExternalSideEffectGuarantee sideEffect) { - ConsumerPolicy defaults = ConsumerPolicy.defaults(group(name)); - return new DestinationProfile( - name, - "kafka", - DestinationKind.EVENT_STREAM, - PhysicalDestination.kafkaTopic(name.value()), - new SchemaPolicy( - ContentType.JSON, SchemaCompatibility.BACKWARD_TRANSITIVE, Set.of(CREATED)), - deadLetter == null ? DeliveryGuarantee.AT_MOST_ONCE : DeliveryGuarantee.AT_LEAST_ONCE, - OrderingScope.NONE, - sideEffect, - ProducerPolicy.defaults(), - new ConsumerPolicy( - defaults.group(), - defaults.concurrency(), - defaults.maxInFlightPerOrderingUnit(), - defaults.prefetch(), - Duration.ofSeconds(10), - false), - retry, - deadLetter == null ? DeadLetterPolicy.disabled() : DeadLetterPolicy.to(deadLetter), - PayloadPolicy.defaults(), - ApiTier.M1, - false, - false, - true); - } - - private static MessageEnvelope envelope(MessageId id) { - return new MessageEnvelope<>( - id, - CREATED, - new SchemaVersion(1), - Instant.parse("2026-09-29T00:00:00Z"), - Optional.empty(), - new ProducerId("orders"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - new OrderCreated("o-1")); - } - - private static void createTopics(String... topics) { - try (Admin admin = - Admin.create( - Map.of(AdminClientConfig.BOOTSTRAP_SERVERS_CONFIG, KAFKA.getBootstrapServers()))) { - admin - .createTopics( - java.util.Arrays.stream(topics) - .map(topic -> new org.apache.kafka.clients.admin.NewTopic(topic, 1, (short) 1)) - .toList()) - .all() - .get(30, TimeUnit.SECONDS); - } catch (Exception failed) { - throw new IllegalStateException("could not create " + List.of(topics), failed); - } - } - - /** Waits, bounded, until the group has committed at least {@code expected} on partition 0. */ - private static long committedOffset(String group, String topic, long expected) throws Exception { - try (Admin admin = - Admin.create( - Map.of(AdminClientConfig.BOOTSTRAP_SERVERS_CONFIG, KAFKA.getBootstrapServers()))) { - Instant deadline = Instant.now().plusSeconds(60); - long seen = -1; - while (Instant.now().isBefore(deadline)) { - Map offsets = - admin.listConsumerGroupOffsets(group).partitionsToOffsetAndMetadata().get(); - OffsetAndMetadata committed = offsets.get(new TopicPartition(topic, 0)); - seen = committed == null ? -1 : committed.offset(); - if (seen >= expected) { - return seen; - } - TimeUnit.MILLISECONDS.sleep(200); - } - return seen; - } - } - - /** Reads the message ids that reached a topic, with a bound rather than an open-ended loop. */ - private static List readMessageIds(String topic) { - Properties config = new Properties(); - config.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, KAFKA.getBootstrapServers()); - config.put(ConsumerConfig.GROUP_ID_CONFIG, topic + "-reader"); - config.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest"); - config.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, ByteArrayDeserializer.class); - config.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, ByteArrayDeserializer.class); - try (KafkaConsumer consumer = new KafkaConsumer<>(config)) { - consumer.subscribe(List.of(topic)); - Instant deadline = Instant.now().plusSeconds(60); - while (Instant.now().isBefore(deadline)) { - List ids = - java.util.stream.StreamSupport.stream( - consumer.poll(Duration.ofSeconds(1)).records(topic).spliterator(), false) - .map(MessagingKafkaConsumeQualificationTest::messageId) - .toList(); - if (!ids.isEmpty()) { - return ids; - } - } - return List.of(); - } - } - - private static String messageId(ConsumerRecord record) { - return new String( - record.headers().lastHeader(ReservedHeaders.MESSAGE_ID).value(), StandardCharsets.UTF_8); - } - - private static DataSource dataSource() { - return new DriverManagerDataSource( - POSTGRES.getJdbcUrl(), POSTGRES.getUsername(), POSTGRES.getPassword()); - } - - private static String inboxMigration() throws IOException { - try (InputStream sql = - MessagingKafkaConsumeQualificationTest.class.getResourceAsStream( - "/db/migration/messaging/V1101__messaging_inbox.sql")) { - assertThat(sql).as("the inbox migration ships with the JDBC inbox").isNotNull(); - return new String(sql.readAllBytes(), StandardCharsets.UTF_8); - } - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingLiveRoundTripQualificationTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingLiveRoundTripQualificationTest.java deleted file mode 100644 index a4d96044..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingLiveRoundTripQualificationTest.java +++ /dev/null @@ -1,221 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -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.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import java.time.Duration; -import java.time.Instant; -import java.util.List; -import java.util.Optional; -import java.util.Properties; -import org.apache.kafka.clients.consumer.ConsumerConfig; -import org.apache.kafka.clients.consumer.ConsumerRecord; -import org.apache.kafka.clients.consumer.ConsumerRecords; -import org.apache.kafka.clients.consumer.KafkaConsumer; -import org.apache.kafka.common.serialization.ByteArrayDeserializer; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.condition.EnabledIf; -import org.springframework.boot.autoconfigure.AutoConfigurations; -import org.springframework.boot.test.context.runner.ApplicationContextRunner; -import org.testcontainers.DockerClientFactory; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; -import org.testcontainers.kafka.KafkaContainer; - -/** - * A message published through the assembled platform arrives on a real broker (MSG-INT-003). - * - *

Every messaging signal in this repository came from a fixture. The legacy adapter's {@code - * KafkaSender} existed only as a test double; the platform's publisher could not be assembled at - * all, because the starter did not depend on the leaf holding it and the codec registry it needs - * had no implementation. "Messaging works" was a statement about hand-rolled fakes. - * - *

So this test asserts the one thing a fake cannot: that bytes leave the process, reach a broker - * the platform configured itself, and can be read back by a consumer that shares nothing with the - * producing code but the topic name. - * - *

Membership rule. The wave's contract is that the starter earns {@code app-bootstrap} - * runtime membership in the same change unit that turns this green. That is why this lives here - * rather than in the composition root: the qualification has to exist and pass before anything is - * put on a deployment's classpath, not after. - */ -@Testcontainers -@EnabledIf(value = "dockerAvailable", disabledReason = "Docker not available for the live broker") -class MessagingLiveRoundTripQualificationTest { - - private static final DestinationName ORDERS = new DestinationName("order-events"); - private static final String TOPIC = "order-events"; - private static final DestinationName DLQ = new DestinationName("order-events-dlq"); - - // The version the support matrix certifies and every other fixture pins. Qualifying runtime - // membership against 3.8.0 proved the membership on a broker two minors below the one the matrix - // calls certified, so the one test that decides whether the starter may reach a deployment's - // classpath was the only one not run against what a deployment gets. - @Container - static final KafkaContainer KAFKA = new KafkaContainer(System.getProperty("ca.test.image.kafka")); - - static boolean dockerAvailable() { - return DockerClientFactory.instance().isDockerAvailable(); - } - - @Test - @DisplayName("a publish through the assembled platform is readable from the broker") - void aPublishReachesTheBroker() { - new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingPlatformRootAutoConfiguration.class)) - .withPropertyValues( - "app.messaging.enabled=true", - "app.messaging.broker=kafka", - "app.messaging.brokers.kafka.type=kafka", - "app.messaging.brokers.kafka.bootstrap-servers[0]=" + KAFKA.getBootstrapServers()) - // Both, because ValidatedDestinationRegistry refuses a profile whose dead-letter target is - // not itself registered — a good invariant, and one a fixture declaring only the happy path - // walks straight into. - // The contract the codec encodes against. Empty is fail-closed by design — a codec that - // accepted an unregistered type would put bytes on a topic consumers read with a different - // shape — so a deployment that publishes must declare what it publishes. - .withBean( - MessageContracts.class, - () -> - new MessageContracts( - java.util.Map.of( - new dev.caskeleton.messaging.schema.MessageContractKey( - new MessageType("order.created"), new SchemaVersion(1)), - String.class))) - .withBean( - "ordersProfile", - dev.caskeleton.messaging.policy.DestinationProfile.class, - () -> profile(ORDERS, DLQ)) - // The dead-letter destination has none of its own: the registry refuses a self-reference, - // and a chain of dead letters is a queue nobody drains. - .withBean( - "ordersDlqProfile", - dev.caskeleton.messaging.policy.DestinationProfile.class, - () -> profile(DLQ, null)) - .run( - context -> { - assertThat(context) - .as( - "the platform must assemble before it can publish; MSG-INT-003 was that it could not") - .hasNotFailed(); - - PublishResult result = - context - .getBean(MessagePublisher.class) - .publish( - new MessageDestination<>( - ORDERS, new MessageType("order.created"), String.class), - envelope(), - PublishOptions.defaults()) - .toCompletableFuture() - .join(); - - assertThat(result.completion()) - .as( - "CONFIRMED means the broker acknowledged it, not that the call returned. " - + "Getting here took four separate absences: the starter's dependency on " - + "messaging-runtime-core, the codec registry, the declared message " - + "contract, and a MessagingRuntime to install — each of which stopped a " - + "publish at a different stage, and none of which any fake would have hit.") - .isEqualTo(PublishCompletion.CONFIRMED); - assertThat(result.evidence().brokerAccepted()) - .as("the evidence a fixture cannot produce") - .isTrue(); - - assertThat(readBack()) - .as( - "the assertion a fake cannot make: bytes left the process and a consumer that " - + "shares nothing with the producing code but the topic name read them") - .isNotEmpty(); - }); - } - - /** Reads whatever reached the topic, with a bound rather than a poll loop that can hang. */ - private static List> readBack() { - Properties config = new Properties(); - config.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, KAFKA.getBootstrapServers()); - config.put(ConsumerConfig.GROUP_ID_CONFIG, "round-trip-qualification"); - config.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest"); - config.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, ByteArrayDeserializer.class); - config.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, ByteArrayDeserializer.class); - - try (KafkaConsumer consumer = new KafkaConsumer<>(config)) { - consumer.subscribe(List.of(TOPIC)); - Instant deadline = Instant.now().plusSeconds(30); - while (Instant.now().isBefore(deadline)) { - ConsumerRecords records = consumer.poll(Duration.ofSeconds(1)); - if (!records.isEmpty()) { - return List.of(records.records(TOPIC).iterator().next()); - } - } - return List.of(); - } - } - - /** - * The destination the platform resolves and the topic it physically writes to. - * - *

The physical topic is what the consumer below subscribes to, and they are deliberately the - * same constant: a round trip that read a different topic from the one the transport wrote would - * pass or fail for reasons unrelated to the platform. - */ - static dev.caskeleton.messaging.policy.DestinationProfile profile( - DestinationName name, DestinationName deadLetter) { - return new dev.caskeleton.messaging.policy.DestinationProfile( - name, - "kafka", - dev.caskeleton.messaging.api.destination.DestinationKind.EVENT_STREAM, - dev.caskeleton.messaging.policy.PhysicalDestination.kafkaTopic(name.value()), - new dev.caskeleton.messaging.policy.SchemaPolicy( - ContentType.JSON, - dev.caskeleton.messaging.schema.SchemaCompatibility.BACKWARD_TRANSITIVE, - java.util.Set.of(new MessageType("order.created"))), - deadLetter == null - ? dev.caskeleton.messaging.api.delivery.DeliveryGuarantee.AT_MOST_ONCE - : dev.caskeleton.messaging.api.delivery.DeliveryGuarantee.AT_LEAST_ONCE, - dev.caskeleton.messaging.api.delivery.OrderingScope.NONE, - dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED, - dev.caskeleton.messaging.policy.ProducerPolicy.defaults(), - dev.caskeleton.messaging.policy.ConsumerPolicy.defaults("round-trip"), - dev.caskeleton.messaging.policy.RetryPolicy.none(), - deadLetter == null - ? dev.caskeleton.messaging.policy.DeadLetterPolicy.disabled() - : dev.caskeleton.messaging.policy.DeadLetterPolicy.to(deadLetter), - dev.caskeleton.messaging.policy.PayloadPolicy.defaults(), - dev.caskeleton.messaging.policy.ApiTier.M1, - false, - false, - false); - } - - static MessageEnvelope envelope() { - return new MessageEnvelope<>( - MessageId.newId(), - new MessageType("order.created"), - new SchemaVersion(1), - Instant.parse("2026-08-14T00:00:00Z"), - Optional.empty(), - new ProducerId("orders"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.empty(), - dev.caskeleton.messaging.api.TraceContext.none(), - dev.caskeleton.messaging.api.header.MessageHeaders.empty(), - "{\"orderId\":\"o-1\"}"); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingSecuredBrokerQualificationTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingSecuredBrokerQualificationTest.java deleted file mode 100644 index 8a081ccd..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingSecuredBrokerQualificationTest.java +++ /dev/null @@ -1,395 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -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.security.CredentialProvider; -import java.io.IOException; -import java.nio.charset.StandardCharsets; -import java.nio.file.Path; -import java.time.Instant; -import java.util.ArrayList; -import java.util.List; -import java.util.Map; -import java.util.Optional; -import java.util.UUID; -import java.util.concurrent.TimeUnit; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.condition.EnabledIf; -import org.junit.jupiter.api.io.TempDir; -import org.springframework.boot.autoconfigure.AutoConfigurations; -import org.springframework.boot.test.context.runner.ApplicationContextRunner; -import org.testcontainers.DockerClientFactory; -import org.testcontainers.kafka.KafkaContainer; -import org.testcontainers.utility.MountableFile; - -/** - * A publish reaches a broker that trusts nobody by default (Review Focus 5, M-2e/NEW-4b, M-2d). - * - *

Both brokers present a certificate signed by a CA generated for this test, which no JVM trusts - * — so a publish is confirmed only if the configured trust store reached the client. The first - * broker then requires SASL PLAIN, and accepts only the user name the credential provider returns; - * the second requires a client certificate, which only the configured key store can present. - * - *

No secret is written in this file: the store and broker passwords are generated per run. - */ -@EnabledIf(value = "dockerAvailable", disabledReason = "Docker not available for the live broker") -class MessagingSecuredBrokerQualificationTest { - - private static final String IMAGE = System.getProperty("ca.test.image.kafka"); - - private static final String BROKER_USER = "svc-orders"; - - private static final String BROKER_STORE = "/etc/kafka/secrets/broker.p12"; - - private static final String BROKER_TRUST = "/etc/kafka/secrets/truststore.p12"; - - static boolean dockerAvailable() { - return DockerClientFactory.instance().isDockerAvailable(); - } - - @Test - void aPublishIsConfirmedByAPrivateCaBrokerThatRequiresSaslAsTheProviderUser( - @TempDir Path directory) { - // given - PrivateCa ca = new PrivateCa(directory); - String userPassword = UUID.randomUUID().toString(); - try (KafkaContainer kafka = - broker(ca, "SASL_SSL") - .withEnv("KAFKA_SASL_ENABLED_MECHANISMS", "PLAIN") - .withEnv( - "KAFKA_LISTENER_NAME_PLAINTEXT_PLAIN_SASL_JAAS_CONFIG", - "org.apache.kafka.common.security.plain.PlainLoginModule required user_" - + BROKER_USER - + "=\"" - + userPassword - + "\";")) { - kafka.start(); - ApplicationContextRunner runner = - platform(kafka, ca, Map.of("orders-producer", userPassword, "orders-consumer", "unused")) - .withPropertyValues( - "app.messaging.security.kafka.producer.type=USERNAME_PASSWORD", - "app.messaging.security.kafka.producer.credential-id=orders-producer", - "app.messaging.security.kafka.consumer.type=USERNAME_PASSWORD", - "app.messaging.security.kafka.consumer.credential-id=orders-consumer"); - - // when - List results = new ArrayList<>(); - runner.run(context -> results.add(publish(context.getBean(MessagePublisher.class)))); - - // then - assertThat(results) - .extracting(PublishResult::completion) - .containsExactly(PublishCompletion.CONFIRMED); - } - } - - @Test - void aPublishIsConfirmedByAPrivateCaBrokerThatRequiresAClientCertificate( - @TempDir Path directory) { - // given - PrivateCa ca = new PrivateCa(directory); - Path clientStore = ca.issue("orders-producer", "dns:orders-producer"); - try (KafkaContainer kafka = - broker(ca, "SSL") - .withEnv("KAFKA_SSL_CLIENT_AUTH", "required") - .withEnv("KAFKA_SSL_TRUSTSTORE_LOCATION", BROKER_TRUST) - .withEnv("KAFKA_SSL_TRUSTSTORE_TYPE", "PKCS12") - .withEnv("KAFKA_SSL_TRUSTSTORE_PASSWORD", ca.password) - .withCopyToContainer(MountableFile.forHostPath(ca.trustStore, 0644), BROKER_TRUST)) { - kafka.start(); - ApplicationContextRunner runner = - platform( - kafka, - ca, - Map.of("orders-producer-tls", ca.password, "orders-consumer-tls", ca.password)) - .withPropertyValues( - "app.messaging.security.kafka.producer.type=MUTUAL_TLS", - "app.messaging.security.kafka.producer.credential-id=orders-producer-tls", - "app.messaging.security.kafka.producer.key-store.location=" + clientStore, - "app.messaging.security.kafka.consumer.type=MUTUAL_TLS", - "app.messaging.security.kafka.consumer.credential-id=orders-consumer-tls", - "app.messaging.security.kafka.consumer.key-store.location=" + clientStore); - - // when - List results = new ArrayList<>(); - runner.run(context -> results.add(publish(context.getBean(MessagePublisher.class)))); - - // then - assertThat(results) - .extracting(PublishResult::completion) - .containsExactly(PublishCompletion.CONFIRMED); - } - } - - /** - * The Testcontainers broker with its external listener switched to a secured protocol. - * - *

The container names its host-facing listener {@code PLAINTEXT} and advertises it by that - * name; only the protocol that name maps to changes here. - */ - @SuppressWarnings("resource") - private static KafkaContainer broker(PrivateCa ca, String protocol) { - Path brokerStore = ca.issue("broker", ca.brokerSubjectAlternativeNames()); - return new KafkaContainer(IMAGE) - .withEnv( - "KAFKA_LISTENER_SECURITY_PROTOCOL_MAP", - "BROKER:PLAINTEXT,PLAINTEXT:" + protocol + ",CONTROLLER:PLAINTEXT") - .withEnv("KAFKA_SSL_KEYSTORE_LOCATION", BROKER_STORE) - .withEnv("KAFKA_SSL_KEYSTORE_TYPE", "PKCS12") - .withEnv("KAFKA_SSL_KEYSTORE_PASSWORD", ca.password) - .withEnv("KAFKA_SSL_KEY_PASSWORD", ca.password) - .withCopyToContainer(MountableFile.forHostPath(brokerStore, 0644), BROKER_STORE); - } - - /** The assembled platform, pointed at the broker through the private CA's trust store. */ - private static ApplicationContextRunner platform( - KafkaContainer kafka, PrivateCa ca, Map secrets) { - Map all = new java.util.HashMap<>(secrets); - all.put("kafka-trust", ca.password); - return new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingPlatformRootAutoConfiguration.class)) - .withPropertyValues( - "app.messaging.enabled=true", - "app.messaging.broker=kafka", - "app.messaging.brokers.kafka.type=kafka", - "app.messaging.brokers.kafka.bootstrap-servers[0]=" + kafka.getBootstrapServers(), - "app.messaging.brokers.kafka.tls-enabled=true", - "app.messaging.brokers.kafka.authentication-enabled=true", - "app.messaging.security.kafka.trust-store.location=" + ca.trustStore, - "app.messaging.security.kafka.trust-store.password-credential-id=kafka-trust", - "app.messaging.security.kafka.access.publishable[0]=order-events") - .withBean(CredentialProvider.class, () -> provider(all)) - .withBean( - MessageContracts.class, - () -> - new MessageContracts( - Map.of( - new dev.caskeleton.messaging.schema.MessageContractKey( - new MessageType("order.created"), new SchemaVersion(1)), - String.class))) - .withBean( - "ordersProfile", - dev.caskeleton.messaging.policy.DestinationProfile.class, - () -> - MessagingLiveRoundTripQualificationTest.profile( - new DestinationName("order-events"), new DestinationName("order-events-dlq"))) - .withBean( - "ordersDlqProfile", - dev.caskeleton.messaging.policy.DestinationProfile.class, - () -> - MessagingLiveRoundTripQualificationTest.profile( - new DestinationName("order-events-dlq"), null)); - } - - private static PublishResult publish(MessagePublisher publisher) { - return publisher - .publish( - new MessageDestination<>( - new DestinationName("order-events"), - new MessageType("order.created"), - String.class), - MessagingLiveRoundTripQualificationTest.envelope(), - PublishOptions.defaults()) - .toCompletableFuture() - .join(); - } - - private static CredentialProvider provider(Map secrets) { - return new CredentialProvider() { - @Override - public char[] resolve(String credentialId) { - return secrets.get(credentialId).toCharArray(); - } - - @Override - public Optional expiresAt(String credentialId) { - return Optional.empty(); - } - - @Override - public Optional username(String credentialId) { - return Optional.of(BROKER_USER); - } - }; - } - - /** - * A certificate authority made for one test run with the JDK's {@code keytool}. - * - *

Every store shares one generated password, which is also what the credential provider hands - * the client for the trust store and the client key store. - */ - private static final class PrivateCa { - - private final Path directory; - - private final String password = UUID.randomUUID().toString(); - - private final Path authority; - - private final Path certificate; - - private final Path trustStore; - - private PrivateCa(Path directory) { - this.directory = directory; - this.authority = directory.resolve("ca.p12"); - this.certificate = directory.resolve("ca.pem"); - this.trustStore = directory.resolve("truststore.p12"); - keytool( - "-genkeypair", - "-alias", - "ca", - "-keyalg", - "RSA", - "-keysize", - "2048", - "-validity", - "2", - "-dname", - "CN=messaging-test-ca", - "-ext", - "bc:c", - "-keystore", - authority.toString(), - "-storetype", - "PKCS12", - "-storepass", - password); - keytool( - "-exportcert", - "-rfc", - "-alias", - "ca", - "-keystore", - authority.toString(), - "-storepass", - password, - "-file", - certificate.toString()); - keytool( - "-importcert", - "-noprompt", - "-alias", - "ca", - "-file", - certificate.toString(), - "-keystore", - trustStore.toString(), - "-storetype", - "PKCS12", - "-storepass", - password); - } - - /** The names the client may reach the broker by, so hostname verification can pass. */ - private String brokerSubjectAlternativeNames() { - String host = DockerClientFactory.instance().dockerHostIpAddress(); - String dockerHost = - host.chars().allMatch(c -> Character.isDigit(c) || c == '.') - ? "ip:" + host - : "dns:" + host; - return "dns:localhost,ip:127.0.0.1," + dockerHost; - } - - /** Issues a key store holding a CA-signed certificate for {@code name}. */ - private Path issue(String name, String subjectAlternativeNames) { - Path store = directory.resolve(name + ".p12"); - Path request = directory.resolve(name + ".csr"); - Path signed = directory.resolve(name + ".pem"); - keytool( - "-genkeypair", - "-alias", - name, - "-keyalg", - "RSA", - "-keysize", - "2048", - "-validity", - "2", - "-dname", - "CN=" + name, - "-keystore", - store.toString(), - "-storetype", - "PKCS12", - "-storepass", - password); - keytool( - "-certreq", - "-alias", - name, - "-keystore", - store.toString(), - "-storepass", - password, - "-file", - request.toString()); - keytool( - "-gencert", - "-rfc", - "-alias", - "ca", - "-keystore", - authority.toString(), - "-storepass", - password, - "-infile", - request.toString(), - "-outfile", - signed.toString(), - "-validity", - "2", - "-ext", - "SAN=" + subjectAlternativeNames); - keytool( - "-importcert", - "-noprompt", - "-alias", - "ca", - "-file", - certificate.toString(), - "-keystore", - store.toString(), - "-storepass", - password); - keytool( - "-importcert", - "-alias", - name, - "-file", - signed.toString(), - "-keystore", - store.toString(), - "-storepass", - password); - return store; - } - - private static void keytool(String... arguments) { - List command = new ArrayList<>(); - command.add(Path.of(System.getProperty("java.home"), "bin", "keytool").toString()); - command.addAll(List.of(arguments)); - try { - Process process = new ProcessBuilder(command).redirectErrorStream(true).start(); - String output = new String(process.getInputStream().readAllBytes(), StandardCharsets.UTF_8); - if (!process.waitFor(60, TimeUnit.SECONDS) || process.exitValue() != 0) { - throw new IllegalStateException("keytool " + arguments[0] + " failed: " + output); - } - } catch (IOException failure) { - throw new IllegalStateException("keytool could not run", failure); - } catch (InterruptedException interrupted) { - Thread.currentThread().interrupt(); - throw new IllegalStateException("keytool was interrupted", interrupted); - } - } - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/BrokerSecuritySettings.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/BrokerSecuritySettings.java deleted file mode 100644 index ddc56f88..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/BrokerSecuritySettings.java +++ /dev/null @@ -1,77 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import java.util.List; -import org.springframework.boot.context.properties.bind.DefaultValue; - -/** - * One entry of {@code app.messaging.security}, keyed by the broker it secures. - * - *

No field here holds a secret, and that is a structural rule rather than a convention: the - * platform stores a credential id and resolves the material through a {@code CredentialProvider} at - * connect time, so a configuration dump or a heap dump yields a name and nothing usable. Key and - * trust store passwords follow the same rule — the stores are named by path, their passwords by - * credential id. - * - *

The admin credential is bindable and its presence on a production broker is a startup failure. - * Leaving it unbindable would have been the safer-looking choice and the wrong one: an operator who - * needs it in a non-production runtime would then configure it somewhere the platform cannot see, - * and the check that refuses it in production would have nothing to refuse. - * - * @param producer the producer credential - * @param consumer the consumer credential - * @param admin the admin credential, which an application runtime must not hold in production - * @param hostnameVerification whether the server certificate hostname is verified - * @param trustStore the certificates the connection trusts; absent means the JVM default store - * @param access which destinations each role may touch - */ -public record BrokerSecuritySettings( - Credential producer, - Credential consumer, - Credential admin, - @DefaultValue("true") boolean hostnameVerification, - TrustStore trustStore, - @DefaultValue Access access) { - - /** - * One credential reference. - * - * @param type the authentication mechanism - * @param credentialId the identifier the credential provider resolves - * @param keyStore the client certificate, for {@code MUTUAL_TLS} and nothing else - */ - public record Credential(String type, String credentialId, KeyStore keyStore) {} - - /** - * A client certificate store, unlocked by the credential it belongs to. - * - * @param location the key store file - * @param type the key store format - */ - public record KeyStore(String location, @DefaultValue("PKCS12") String type) {} - - /** - * The certificates the connection trusts. - * - * @param location the trust store file - * @param type the trust store format - * @param passwordCredentialId the credential that unlocks the store, when it is locked - */ - public record TrustStore( - String location, @DefaultValue("PKCS12") String type, String passwordCredentialId) {} - - /** - * Which destinations each role may touch. - * - *

{@code publishable} is enforced: once a broker has a security entry, the platform publishes - * only to the declared destinations of that broker that this list names. An empty list therefore - * publishes nothing. - * - * @param publishable destinations the producer credential may publish to - * @param consumable destinations the consumer credential may consume - * @param administrable destinations the admin credential may operate on - */ - public record Access( - @DefaultValue List publishable, - @DefaultValue List consumable, - @DefaultValue List administrable) {} -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/BrokerSettings.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/BrokerSettings.java deleted file mode 100644 index 1b491bee..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/BrokerSettings.java +++ /dev/null @@ -1,36 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import org.springframework.boot.context.properties.bind.DefaultValue; - -/** - * The broker-neutral part of one {@code app.messaging.brokers} entry. - * - *

This starter is broker-neutral, and its settings are too. The client settings of a family — - * Kafka's bootstrap servers, acks, idempotence — are bound by that family's starter from the same - * entry ({@code KafkaBrokerSettings} in {@code messaging-spring-boot-starter-kafka}). They used to - * be fields here, so the neutral starter carried the union of every broker's client knobs and a - * deployment that shipped no Kafka transport still bound Kafka settings. {@link - * MessagingConfigurationKeyValidator} accepts a family's keys only when that family's settings - * record is on the classpath ({@link MessagingProviderSelection#PROVIDER_BROKER_SETTINGS}). - * - *

{@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} 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 - * @param authenticationEnabled whether broker authentication is on - */ -public record BrokerSettings( - String type, - @DefaultValue("false") boolean stable, - @DefaultValue("false") boolean production, - @DefaultValue("false") boolean tlsEnabled, - @DefaultValue("false") boolean authenticationEnabled) { - - /** The broker family a Kafka entry declares. */ - public static final String KAFKA = "kafka"; -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/CompiledMessagingConfiguration.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/CompiledMessagingConfiguration.java deleted file mode 100644 index 7b65e6a6..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/CompiledMessagingConfiguration.java +++ /dev/null @@ -1,43 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.security.BrokerSecurityProfile; -import java.util.List; -import java.util.Map; -import java.util.Objects; - -/** - * What the documented broker-neutral configuration compiles to. - * - *

The core starter owns destination/security policy and the raw broker settings an adopter - * wrote. It deliberately does not construct Kafka or Rabbit profile types: doing that here would - * make the supposedly core artifact depend on both broker adapters. A broker capability compiles - * its own profile from {@link #brokers()} only when that capability artifact is present. - * - * @param destinations the destination profiles built from {@code app.messaging.destinations} - * @param brokers the validated broker settings keyed by logical broker name - * @param security the broker security profiles built from {@code app.messaging.security} - */ -public record CompiledMessagingConfiguration( - List destinations, - Map brokers, - List security) { - - public CompiledMessagingConfiguration { - Objects.requireNonNull(destinations, "destinations must not be null"); - Objects.requireNonNull(brokers, "brokers must not be null"); - Objects.requireNonNull(security, "security must not be null"); - destinations = List.copyOf(destinations); - brokers = Map.copyOf(brokers); - security = List.copyOf(security); - } - - /** - * Returns the result of compiling a deployment that configured nothing. - * - * @return the empty compilation - */ - public static CompiledMessagingConfiguration empty() { - return new CompiledMessagingConfiguration(List.of(), Map.of(), List.of()); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DestinationSettings.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DestinationSettings.java deleted file mode 100644 index 8184d6ac..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DestinationSettings.java +++ /dev/null @@ -1,177 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -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.ConfirmationRequirement; -import dev.caskeleton.messaging.api.destination.DestinationKind; -import dev.caskeleton.messaging.policy.ApiTier; -import dev.caskeleton.messaging.policy.OrderingImpact; -import dev.caskeleton.messaging.policy.RetryMode; -import dev.caskeleton.messaging.schema.SchemaCompatibility; -import java.time.Duration; -import java.util.List; -import org.springframework.boot.context.properties.bind.DefaultValue; - -/** - * One entry of {@code app.messaging.destinations}. - * - *

The shape is the one the configuration reference documents, and it is bound rather than - * described: the reference showed destination, broker and security sections for a platform whose - * only binder held four flags, so an operator who configured exactly what the page said changed - * nothing and was told nothing. - * - *

Records rather than mutable nested beans. A destination profile is a contract the platform - * validates once at startup and then relies on; a settings object whose fields can be reassigned - * afterwards offers a second, unvalidated way for that contract to change. - * - *

Defaults are the conservative ones. Retry is off, ordering is unconstrained and nothing is a - * production profile until it says so, because every one of those defaults, chosen the other way, - * is a guarantee the deployment never asked for and would discover only under load. - * - * @param broker the logical broker this destination binds to, keyed into {@code - * app.messaging.brokers} - * @param kind the interaction pattern - * @param tier the API tier this destination is approved for - * @param physical the broker-specific address - * @param schema the codec and compatibility contract - * @param guarantees the delivery, ordering and side-effect contract - * @param producer the producer contract - * @param consumer the consumer contract - * @param retry the retry contract - * @param dlq the dead letter contract - * @param payload the size contract - * @param keyResolverConfigured whether a key resolver is registered for keyed ordering - * @param production whether this profile is a production profile - * @param topologyAutoCreate whether the application may create topology itself - */ -public record DestinationSettings( - String broker, - DestinationKind kind, - @DefaultValue("M1") ApiTier tier, - @DefaultValue Physical physical, - @DefaultValue Schema schema, - @DefaultValue Guarantees guarantees, - @DefaultValue Producer producer, - @DefaultValue Consumer consumer, - @DefaultValue Retry retry, - @DefaultValue Dlq dlq, - @DefaultValue Payload payload, - @DefaultValue("false") boolean keyResolverConfigured, - @DefaultValue("false") boolean production, - @DefaultValue("false") boolean topologyAutoCreate) { - - /** - * The broker-specific address, of which exactly one family is filled in. - * - * @param topic the Kafka or Pulsar topic - * @param exchange the AMQP exchange - * @param routingKey the AMQP routing key - * @param queue the AMQP queue - * @param subject the NATS subject - * @param stream the NATS or Pulsar stream - */ - public record Physical( - String topic, - String exchange, - String routingKey, - String queue, - String subject, - String stream) {} - - /** - * The codec and compatibility contract. - * - * @param codec the content type payloads are encoded with - * @param compatibility the schema evolution mode enforced here - * @param messageTypes the closed catalog of types this destination carries - */ - public record Schema( - @DefaultValue("application/json") String codec, - @DefaultValue("BACKWARD_TRANSITIVE") SchemaCompatibility compatibility, - @DefaultValue List messageTypes) {} - - /** - * What the destination promises about delivery and order. - * - * @param delivery the broker-level delivery guarantee - * @param ordering the scope inside which order holds - * @param externalSideEffect how handler side effects are protected - */ - public record Guarantees( - @DefaultValue("AT_LEAST_ONCE") DeliveryGuarantee delivery, - @DefaultValue("NONE") OrderingScope ordering, - @DefaultValue("IDEMPOTENCY_REQUIRED") ExternalSideEffectGuarantee externalSideEffect) {} - - /** - * The producer contract. - * - * @param confirmation the confirmation strength this destination demands - * @param timeout the publish deadline - * @param mandatoryRouting whether the broker must report unroutable publishes - * @param idempotent whether producer-side duplicate suppression is required - */ - public record Producer( - @DefaultValue("REPLICATION_OR_PERSISTENCE_ACK") ConfirmationRequirement confirmation, - @DefaultValue("5s") Duration timeout, - @DefaultValue("true") boolean mandatoryRouting, - @DefaultValue("true") boolean idempotent) {} - - /** - * The consumer contract. - * - * @param group the consumer group, where the broker has one - * @param concurrency how many deliveries may be processed at once - * @param maxInFlightPerOrderingUnit the in-flight ceiling inside one ordering unit - * @param prefetch the broker prefetch window - * @param handlerTimeout the handler deadline - * @param manualSettlement whether this destination uses the M2 manual settlement tier - */ - public record Consumer( - String group, - @DefaultValue("1") int concurrency, - @DefaultValue("1") int maxInFlightPerOrderingUnit, - @DefaultValue("16") int prefetch, - @DefaultValue("30s") Duration handlerTimeout, - @DefaultValue("false") boolean manualSettlement) {} - - /** - * The retry contract, off by default. - * - * @param mode how the retry is carried out - * @param maxAttempts total attempts including the first delivery - * @param initialDelay the first backoff interval - * @param maxDelay the backoff ceiling - * @param multiplier the exponential backoff factor - * @param jitter whether to randomise the backoff - * @param orderingImpact what this policy is allowed to do to order - * @param destination the destination messages are re-published to, when the mode uses one - */ - public record Retry( - @DefaultValue("NONE") RetryMode mode, - @DefaultValue("1") int maxAttempts, - @DefaultValue("0s") Duration initialDelay, - @DefaultValue("0s") Duration maxDelay, - @DefaultValue("1.0") double multiplier, - @DefaultValue("false") boolean jitter, - @DefaultValue("PRESERVE") OrderingImpact orderingImpact, - String destination) {} - - /** - * Where permanently failed messages go. - * - * @param destination the dead letter destination; absent means dead lettering is off - * @param maxRedriveCount how many times a message may be redriven back - */ - public record Dlq(String destination, @DefaultValue("1") int maxRedriveCount) {} - - /** - * The size contract. - * - * @param maxBytes the encoded payload ceiling for this destination - * @param claimCheckThresholdBytes the size above which payloads are offloaded - */ - public record Payload( - @DefaultValue("1048576") int maxBytes, - @DefaultValue("1048576") int claimCheckThresholdBytes) {} -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageConsumers.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageConsumers.java deleted file mode 100644 index 332baa53..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageConsumers.java +++ /dev/null @@ -1,46 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.transport.TransportDelivery; -import java.util.List; -import java.util.Objects; -import java.util.concurrent.CompletionStage; -import java.util.function.Function; - -/** - * The destinations this application consumes, each with the broker-neutral pipeline its deliveries - * go through. - * - *

Built by {@link MessagingConsumeConfiguration} from the {@code MessageHandler} beans; a broker - * starter opens one consumer per entry and hands every delivery to its {@link Consumer#sink()}. The - * split keeps decoding, inbox, dead-lettering and settlement rules out of each broker starter. - * - * @param consumers one entry per consumed destination - */ -public record MessageConsumers(List consumers) { - - public MessageConsumers { - consumers = List.copyOf(Objects.requireNonNull(consumers, "consumers must not be null")); - } - - /** - * One consumed destination. - * - * @param profile the destination profile - * @param group the consumer group, which is also the inbox consumer identity - * @param sink the pipeline each still-encoded delivery goes through - */ - public record Consumer( - DestinationProfile profile, - String group, - Function> sink) { - - public Consumer { - Objects.requireNonNull(profile, "profile must not be null"); - Objects.requireNonNull(sink, "sink must not be null"); - if (group == null || group.isBlank()) { - throw new IllegalArgumentException("group must not be blank"); - } - } - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageContracts.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageContracts.java deleted file mode 100644 index 212ac85e..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageContracts.java +++ /dev/null @@ -1,86 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.schema.MessageContractKey; -import java.util.Collection; -import java.util.LinkedHashMap; -import java.util.Map; -import java.util.Objects; - -/** - * The deployment's message contracts: message type and schema version to payload class. - * - *

A named holder rather than a bare {@code Map} bean, because {@code Map} is not a neutral - * injection type in Spring — a {@code Map} injection point is interpreted as "every bean of - * type V, keyed by bean name", so a contract map registered as a bean is either ignored or turned - * into something nobody wrote. A holder makes the intent unambiguous to the container and to a - * reader. - * - *

A deployment registers what it publishes as a bean of this type. What it - * consumes it does not register at all: {@link #withConsumed} adds each handler bean's own - * declaration, so the codec decodes exactly what some handler said it reads (review 2026-11-01 - * 06-08 follow-up). A consumer whose payload type had to be registered here as well was a consumer - * whose messages were dead-lettered as undecodable whenever that second step was forgotten. - * - *

Empty is the default and it is fail-closed: no message type can be encoded, and every publish - * is refused at preparation. A codec that accepted an unregistered type would serialise whatever - * object it was handed onto a topic that consumers compiled against a different shape will read — - * which is a wire-compatibility break that looks like a working publish. - * - * @param byKey the declared contracts - */ -public record MessageContracts(Map> byKey) { - - /** Copies the map so a later mutation cannot change what a running publisher will encode. */ - public MessageContracts { - Objects.requireNonNull(byKey, "byKey"); - byKey = Map.copyOf(byKey); - } - - /** A deployment that has declared nothing, and therefore publishes nothing. */ - public static MessageContracts none() { - return new MessageContracts(Map.of()); - } - - /** - * These contracts plus every contract the given handlers consume. - * - *

A handler names its message type and payload class in {@link MessageHandler#destination()} - * and the schema versions that class reads in {@link MessageHandler#schemaVersions()}; each - * version is one contract. The same contract declared twice with the same class is one entry. - * - * @param handlers the deployment's handler beans - * @return the combined contracts - * @throws MessagingConfigurationException when two declarations give one contract different - * payload classes — the codec holds one class per contract, so one of them would decode every - * message of that type into the wrong shape - */ - public MessageContracts withConsumed(Collection> handlers) { - Map> combined = new LinkedHashMap<>(byKey); - for (MessageHandler handler : handlers) { - MessageDestination destination = handler.destination(); - for (SchemaVersion version : handler.schemaVersions()) { - MessageContractKey key = new MessageContractKey(destination.messageType(), version); - Class declared = destination.payloadType(); - Class existing = combined.putIfAbsent(key, declared); - if (existing != null && !existing.equals(declared)) { - throw new MessagingConfigurationException( - "MESSAGING_CONTRACT_CONFLICT", - "contract " - + key.describe() - + " is declared as " - + existing.getName() - + " and as " - + declared.getName() - + " (handler for destination '" - + destination.name().value() - + "'); one contract decodes into one payload class"); - } - } - } - return new MessageContracts(combined); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingAdminAutoConfiguration.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingAdminAutoConfiguration.java deleted file mode 100644 index 5238ba6a..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingAdminAutoConfiguration.java +++ /dev/null @@ -1,89 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.admin.AdminOperationJournal; -import dev.caskeleton.messaging.admin.DestructiveOperationGuard; -import dev.caskeleton.messaging.admin.runtime.BrokerTopologyInspector; -import dev.caskeleton.messaging.admin.runtime.CompositeTopologyValidator; -import dev.caskeleton.messaging.admin.runtime.InMemoryAdminOperationJournal; -import org.springframework.boot.autoconfigure.condition.ConditionalOnBean; -import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; -import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; -import org.springframework.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; - -/** - * Wires the admin plane, and only when a deployment has explicitly asked for it. - * - *

Off unless {@code app.messaging.admin.enabled=true}. An application that acquires the admin - * plane by adding a starter to its classpath is exactly the situation the plane's guards exist to - * prevent — the guards would still refuse an unapproved operation, but the beans would be reachable - * from any code in the process. - * - *

{@link dev.caskeleton.messaging.admin.runtime.DestructiveMessagingAdmin} is deliberately - * absent from this class. No bean for it is ever auto-configured: an operator tool that needs purge - * or delete registers one itself, with an admin credential this runtime does not hold. - */ -@Configuration(proxyBeanMethods = false) -@ConditionalOnProperty( - prefix = MessagingSettings.PREFIX + ".admin", - name = "enabled", - havingValue = "true") -public class MessagingAdminAutoConfiguration { - - /** - * Returns the guard that authorises non-destructive admin operations. - * - * @return the guard - */ - @Bean - @ConditionalOnMissingBean - public DestructiveOperationGuard destructiveOperationGuard() { - // false: an application runtime never holds an admin credential, so the guard refuses the - // operations that would need one. An operator tool overrides this bean with true. - return new DestructiveOperationGuard(false); - } - - /** - * Returns a single-process journal so a development runtime starts without extra wiring. - * - *

It declares itself non-durable, and {@link MessagingAdminDurabilityValidator} refuses to let - * a production profile start on it. That pairing is deliberate: the convenient default stays - * convenient for local work and becomes a startup failure — naming what to supply — the moment - * the deployment claims to be production. The previous default was an indistinguishable {@code - * ConcurrentHashMap} that silently let two replicas execute the same approval. - * - * @return the in-memory journal - */ - @Bean - @ConditionalOnMissingBean - public AdminOperationJournal adminOperationJournal() { - return new InMemoryAdminOperationJournal(); - } - - /** - * Returns the validator that refuses a production profile on a non-durable journal. - * - * @param journal the journal in use - * @param environment the Spring environment - * @return the validator - */ - @Bean - @ConditionalOnMissingBean - public MessagingAdminDurabilityValidator messagingAdminDurabilityValidator( - AdminOperationJournal journal, org.springframework.core.env.Environment environment) { - return new MessagingAdminDurabilityValidator(journal, environment); - } - - /** - * Returns the topology validator, when the application supplied a broker inspector. - * - * @param inspector reads the broker's current topology - * @return the composite validator - */ - @Bean - @ConditionalOnBean(BrokerTopologyInspector.class) - @ConditionalOnMissingBean - public CompositeTopologyValidator compositeTopologyValidator(BrokerTopologyInspector inspector) { - return new CompositeTopologyValidator(inspector); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingAdminDurabilityValidator.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingAdminDurabilityValidator.java deleted file mode 100644 index 3dc2d154..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingAdminDurabilityValidator.java +++ /dev/null @@ -1,68 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.admin.AdminOperationJournal; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.util.List; -import java.util.Objects; -import java.util.Set; -import org.springframework.beans.factory.InitializingBean; -import org.springframework.core.env.Environment; - -/** - * Refuses to start a production profile on a journal that cannot survive a restart. - * - *

The previous default was an in-memory map registered by this starter, and nothing in the - * application said so. Two replicas each had their own copy, so both could claim the same approval - * at the same moment; a restart forgot every claim, so the same approval could be executed again by - * the same process. Both failures look like a successful redrive until somebody counts the - * duplicates. - * - *

The check is a startup failure rather than a warning because the gap only shows up during the - * incident the operation was run to resolve, which is the worst possible moment to discover it. - */ -public final class MessagingAdminDurabilityValidator implements InitializingBean { - - private static final Set PRODUCTION_PROFILES = Set.of("prod", "production"); - - private final AdminOperationJournal journal; - - private final Environment environment; - - /** - * Creates the validator. - * - * @param journal the journal the admin service will use - * @param environment the Spring environment, read for active profiles - */ - public MessagingAdminDurabilityValidator(AdminOperationJournal journal, Environment environment) { - this.journal = Objects.requireNonNull(journal, "journal must not be null"); - this.environment = Objects.requireNonNull(environment, "environment must not be null"); - } - - @Override - public void afterPropertiesSet() { - validate(); - } - - /** - * Refuses a production profile on a non-durable journal. - * - * @throws MessagingConfigurationException naming what to supply - */ - public void validate() { - List active = List.of(environment.getActiveProfiles()); - boolean production = active.stream().anyMatch(PRODUCTION_PROFILES::contains); - if (!production || journal.isDurable()) { - return; - } - throw new MessagingConfigurationException( - "ADMIN_JOURNAL_NOT_DURABLE", - "the destructive-operation journal in use (" - + journal.getClass().getSimpleName() - + ") is not durable, and profiles " - + active - + " include a production profile; supply an AdminOperationJournal bean backed by the" - + " shared database (JdbcAdminOperationJournal) so one approval cannot be executed" - + " twice across replicas or across a restart"); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java deleted file mode 100644 index fd46dd1c..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java +++ /dev/null @@ -1,311 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -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.security.BrokerCredentialProfile; -import dev.caskeleton.messaging.security.BrokerSecurityProfile; -import dev.caskeleton.messaging.security.BrokerTrustStore; -import dev.caskeleton.messaging.security.DestinationAccessPolicy; -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.Optional; -import java.util.Set; - -/** - * Turns the documented configuration into the objects the platform already validates. - * - *

The gap this closes is not a missing feature but a missing binder. {@code - * docs/messaging/configuration-reference.md} described destination, broker and security sections; - * the only thing that bound was four flags, and destination profiles, broker profiles and security - * profiles had to arrive as beans an application wrote in Java. So a deployment that followed the - * documentation configured nothing, and nothing said so — which is the worst of the three possible - * outcomes, the other two being "it works" and "it refuses to start". - * - *

Every refusal here names the key. A configuration error that names a type — "no qualifying - * bean of type DestinationProfile" — tells an operator about the platform's internals rather than - * about the line they have to change. - * - *

Compiling is separate from validating on purpose. This class turns text into objects and - * checks only what the object model itself cannot express — that a destination's broker exists, - * that a dead letter destination is declared, that a security entry secures a broker somebody - * configured. Whether the resulting profile is coherent is {@code DestinationProfileValidator}'s - * question and it is asked at startup over the whole registry, so a configured profile and a - * bean-declared one are held to exactly the same rules. - */ -public final class MessagingConfigurationCompiler { - - private final MessagingSettings settings; - - /** - * Creates a compiler over the bound settings. - * - * @param settings the bound configuration - */ - public MessagingConfigurationCompiler(MessagingSettings settings) { - this.settings = Objects.requireNonNull(settings, "settings must not be null"); - } - - /** - * Compiles the bound configuration. - * - * @return the compiled destinations, broker profiles and security profiles - */ - public CompiledMessagingConfiguration compile() { - Map brokers = settings.getBrokers(); - brokers.forEach(MessagingConfigurationCompiler::validateBrokerSettings); - - List destinations = new ArrayList<>(); - settings - .getDestinations() - .forEach((name, destination) -> destinations.add(toProfile(name, destination, brokers))); - - List security = new ArrayList<>(); - settings - .getSecurity() - .forEach((name, entry) -> security.add(toSecurityProfile(name, entry, brokers))); - - return new CompiledMessagingConfiguration(destinations, brokers, security); - } - - private static String familyOf(String name, BrokerSettings broker) { - if (broker.type() == null || broker.type().isBlank()) { - throw configurationError( - key("brokers", name, "type"), - "a broker entry must declare its family; without one the platform cannot tell which of " - + "its settings apply, and would apply none of them"); - } - return broker.type().toLowerCase(Locale.ROOT); - } - - private static void validateBrokerSettings(String name, BrokerSettings broker) { - // Only the family is checked here. Its client settings — addresses, acks — belong to the - // family's starter, which binds and validates them when it builds the client. - if (!MessagingProviderSelection.registeredBrokerIds().contains(familyOf(name, broker))) { - throw configurationError( - key("brokers", name, "type"), - "'%s' is not a broker family this platform has a transport for; use one of %s" - .formatted(broker.type(), MessagingProviderSelection.registeredBrokerIds())); - } - } - - private DestinationProfile toProfile( - String name, DestinationSettings settings, Map brokers) { - if (settings.broker() == null || settings.broker().isBlank()) { - throw configurationError( - key("destinations", name, "broker"), "a destination must name the broker it binds to"); - } - if (!brokers.containsKey(settings.broker())) { - throw configurationError( - key("destinations", name, "broker"), - "'%s' is not a configured broker; declared brokers are %s" - .formatted(settings.broker(), brokers.keySet())); - } - if (settings.kind() == null) { - throw configurationError( - key("destinations", name, "kind"), - "a destination must declare its interaction pattern; the platform's retry, ordering and " - + "dead letter rules all read it"); - } - - return new DestinationProfile( - new DestinationName(name), - settings.broker(), - settings.kind(), - physical(name, settings.physical()), - schema(name, settings.schema()), - settings.guarantees().delivery(), - settings.guarantees().ordering(), - settings.guarantees().externalSideEffect(), - new ProducerPolicy( - settings.producer().confirmation(), - settings.producer().timeout(), - settings.producer().mandatoryRouting(), - settings.producer().idempotent()), - new ConsumerPolicy( - Optional.ofNullable(blankToNull(settings.consumer().group())), - settings.consumer().concurrency(), - settings.consumer().maxInFlightPerOrderingUnit(), - settings.consumer().prefetch(), - settings.consumer().handlerTimeout(), - settings.consumer().manualSettlement()), - retry(settings.retry()), - deadLetter(settings.dlq()), - new PayloadPolicy( - settings.payload().maxBytes(), settings.payload().claimCheckThresholdBytes()), - settings.tier(), - settings.production(), - settings.keyResolverConfigured(), - settings.topologyAutoCreate()); - } - - private static PhysicalDestination physical(String name, DestinationSettings.Physical physical) { - PhysicalDestination address = - new PhysicalDestination( - Optional.ofNullable(blankToNull(physical.topic())), - Optional.ofNullable(blankToNull(physical.exchange())), - Optional.ofNullable(blankToNull(physical.routingKey())), - Optional.ofNullable(blankToNull(physical.queue())), - Optional.ofNullable(blankToNull(physical.subject())), - Optional.ofNullable(blankToNull(physical.stream()))); - if (address.isEmpty()) { - throw configurationError( - key("destinations", name, "physical"), - "a destination needs a broker address — a topic, an exchange, a queue, a subject or a " - + "stream; a logical name that maps to nothing cannot be published to"); - } - return address; - } - - private static SchemaPolicy schema(String name, DestinationSettings.Schema schema) { - if (schema.messageTypes().isEmpty()) { - throw configurationError( - key("destinations", name, "schema.message-types"), - "a destination carries a closed catalog of message types; one that accepts whatever it " - + "is handed has no reviewable wire contract"); - } - Set types = new LinkedHashSet<>(); - schema.messageTypes().forEach(type -> types.add(new MessageType(type))); - return new SchemaPolicy(new ContentType(schema.codec()), schema.compatibility(), types); - } - - private static RetryPolicy retry(DestinationSettings.Retry retry) { - return new RetryPolicy( - retry.mode(), - retry.maxAttempts(), - retry.initialDelay(), - retry.maxDelay(), - retry.multiplier(), - retry.jitter(), - retry.orderingImpact(), - Set.of(), - Set.of(), - Optional.ofNullable(blankToNull(retry.destination())).map(DestinationName::new)); - } - - private static DeadLetterPolicy deadLetter(DestinationSettings.Dlq dlq) { - String destination = blankToNull(dlq.destination()); - if (destination == null) { - return DeadLetterPolicy.disabled(); - } - return new DeadLetterPolicy( - true, Optional.of(new DestinationName(destination)), dlq.maxRedriveCount()); - } - - private static BrokerSecurityProfile toSecurityProfile( - String name, BrokerSecuritySettings security, Map brokers) { - BrokerSettings broker = brokers.get(name); - if (broker == null) { - throw configurationError( - key("security", name, ""), - "'%s' is not a configured broker; a security profile for a broker nobody declared " - .formatted(name) - + "secures nothing. Declared brokers are " - + brokers.keySet()); - } - return new BrokerSecurityProfile( - name, - broker.production(), - broker.tlsEnabled(), - security.hostnameVerification(), - credential(name, "producer", security.producer()), - credential(name, "consumer", security.consumer()), - Optional.ofNullable(security.admin()).map(admin -> credential(name, "admin", admin)), - new DestinationAccessPolicy( - destinationNames(security.access().publishable()), - destinationNames(security.access().consumable()), - destinationNames(security.access().administrable())), - Optional.ofNullable(security.trustStore()).map(store -> trustStore(name, store))); - } - - private static BrokerTrustStore trustStore( - String broker, BrokerSecuritySettings.TrustStore store) { - if (blankToNull(store.location()) == null) { - throw configurationError( - key("security", broker, "trust-store.location"), - "a trust store entry needs the file it names; without one the JVM default store is used," - + " which is what leaving the entry out already says"); - } - return new BrokerTrustStore( - store.location(), - store.type(), - Optional.ofNullable(blankToNull(store.passwordCredentialId()))); - } - - private static BrokerCredentialProfile credential( - String broker, String role, BrokerSecuritySettings.Credential credential) { - // Every role that reaches here is required: the optional admin role is filtered out by its - // caller before the call. A "not required" branch would have nothing to return and fell - // through to dereference the missing credential. - if (credential == null) { - throw configurationError( - key("security", broker, role), - "a configured broker needs a %s credential; the roles are separate so that a compromised " - .formatted(role) - + "handler has nothing to escalate with"); - } - String type = credential.type() == null ? "" : credential.type().toUpperCase(Locale.ROOT); - String id = credential.credentialId(); - BrokerSecuritySettings.KeyStore keyStore = credential.keyStore(); - boolean hasKeyStore = keyStore != null && blankToNull(keyStore.location()) != null; - if ("MUTUAL_TLS".equals(type) && !hasKeyStore) { - throw configurationError( - key("security", broker, role + ".key-store"), - "MUTUAL_TLS presents a client certificate, and without a key store there is none to" - + " present; the broker refuses the handshake"); - } - if (!"MUTUAL_TLS".equals(type) && keyStore != null) { - throw configurationError( - key("security", broker, role + ".key-store"), - "only a MUTUAL_TLS credential presents a key store; a %s credential would ignore it" - .formatted(credential.type())); - } - return switch (type) { - case "SASL_SCRAM" -> new BrokerCredentialProfile.SaslScram(id); - case "OAUTH2" -> new BrokerCredentialProfile.OAuth2(id); - case "MUTUAL_TLS" -> - new BrokerCredentialProfile.MutualTls(id, keyStore.location(), keyStore.type()); - case "USERNAME_PASSWORD" -> new BrokerCredentialProfile.UsernamePassword(id); - case "NKEY" -> new BrokerCredentialProfile.Nkey(id); - default -> - throw configurationError( - key("security", broker, role + ".type"), - "'%s' is not an authentication mechanism this platform implements; the closed set is " - .formatted(credential.type()) - + "SASL_SCRAM, OAUTH2, MUTUAL_TLS, USERNAME_PASSWORD, NKEY"); - }; - } - - private static Set destinationNames(List names) { - Set destinations = new LinkedHashSet<>(); - names.forEach(name -> destinations.add(new DestinationName(name))); - return destinations; - } - - private static String blankToNull(String value) { - return value == null || value.isBlank() ? null : value; - } - - private static String key(String section, String entry, String leaf) { - String path = MessagingSettings.PREFIX + '.' + section + '.' + entry; - return leaf.isEmpty() ? path : path + '.' + leaf; - } - - private static MessagingConfigurationException configurationError(String key, String message) { - return new MessagingConfigurationException( - "MESSAGING_CONFIGURATION_INVALID", key + ": " + message); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationKeyValidator.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationKeyValidator.java deleted file mode 100644 index 56c5b676..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationKeyValidator.java +++ /dev/null @@ -1,213 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -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; -import org.springframework.beans.factory.InitializingBean; -import org.springframework.core.env.ConfigurableEnvironment; -import org.springframework.core.env.EnumerablePropertySource; -import org.springframework.core.env.PropertySource; -import org.springframework.util.ClassUtils; - -/** - * Refuses a key inside the platform's own configuration sections that nothing binds. - * - *

A misspelt prefix is loud — the whole section is missing and someone notices. A misspelt key - * inside a section that does bind is the opposite: the entry appears, the platform starts, and the - * one setting the operator came to change is the only one that did not take. {@code - * consumer.prefech: 64} is a throughput change that never happened, and the first evidence is the - * incident it was supposed to prevent. - * - *

The legal keys are derived from the settings records rather than listed here. A list would be - * a second description of the same shape, and the failure mode of a second description is that it - * is right on the day it is written: a field added to {@code DestinationSettings} would be rejected - * as unknown by the very check that exists to catch typos. - * - *

Only enumerable property sources are scanned, which in practice means files and explicitly - * supplied properties rather than environment variables. An environment variable arrives as {@code - * APP_MESSAGING_DESTINATIONS_ORDER_EVENTS_CONSUMER_PREFETCH}, and the underscores that separate the - * entry name from the leaf are the same underscores inside both, so there is no way to split it - * back without guessing. Guessing here would mean refusing valid deployments, which is worse than - * missing a typo in the one place typos are least likely — a variable somebody had to spell out in - * a deployment manifest. - */ -public final class MessagingConfigurationKeyValidator implements InitializingBean { - - private final ConfigurableEnvironment environment; - - /** - * Creates a validator over the resolved environment. - * - * @param environment the environment whose keys are checked - */ - public MessagingConfigurationKeyValidator(ConfigurableEnvironment environment) { - this.environment = Objects.requireNonNull(environment, "environment must not be null"); - } - - @Override - public void afterPropertiesSet() { - validate(); - } - - /** - * Fails when a key under a bound section is not one the settings declare. - * - * @throws MessagingConfigurationException naming the offending key - */ - public void validate() { - Map> sections = - Map.of( - "destinations", DestinationSettings.class, - "brokers", BrokerSettings.class, - "security", BrokerSecuritySettings.class); - - List rejected = new ArrayList<>(); - sections.forEach( - (section, shape) -> { - Set common = leafPaths(shape); - for (String key : keysUnder(MessagingSettings.PREFIX + '.' + section + '.')) { - Entry entry = split(key, MessagingSettings.PREFIX + '.' + section + '.'); - if (entry.leaf().isEmpty()) { - continue; - } - Set legal = - "brokers".equals(section) ? brokerLeafPaths(entry.name(), common) : common; - if (!legal.contains(entry.leaf())) { - rejected.add( - "%s binds nothing; %s entries accept %s" - .formatted(key, section, legal.stream().sorted().toList())); - } - } - }); - - for (String key : keysUnder(MessagingSettings.PREFIX + ".admin.")) { - String leaf = key.substring((MessagingSettings.PREFIX + ".admin.").length()); - if (!"enabled".equals(leaf)) { - rejected.add("%s binds nothing; admin entries accept [enabled]".formatted(key)); - } - } - - if (rejected.isEmpty()) { - return; - } - throw new MessagingConfigurationException( - "MESSAGING_CONFIGURATION_KEY_UNKNOWN", - "these messaging keys do not bind: " - + String.join("; ", rejected.stream().sorted().limit(10).toList()) - + (rejected.size() > 10 ? " (and " + (rejected.size() - 10) + " more)" : "")); - } - - /** - * The keys a broker entry accepts: the neutral ones, plus its family's own when the family's - * starter is on the classpath. - * - *

A family whose settings record is absent accepts only the neutral keys. Its client keys bind - * nothing in that deployment — there is no transport to hand them to — and {@link - * MessagingProviderSelection} refuses a selected family whose starter is missing anyway. - */ - private Set brokerLeafPaths(String brokerName, Set common) { - String type = - environment.getProperty(MessagingSettings.PREFIX + ".brokers." + brokerName + ".type", ""); - String shapeName = - MessagingProviderSelection.PROVIDER_BROKER_SETTINGS.get( - type.trim().toLowerCase(Locale.ROOT)); - if (shapeName == null - || !ClassUtils.isPresent( - shapeName, MessagingConfigurationKeyValidator.class.getClassLoader())) { - return common; - } - Set legal = new LinkedHashSet<>(common); - legal.addAll( - leafPaths( - ClassUtils.resolveClassName( - shapeName, MessagingConfigurationKeyValidator.class.getClassLoader()))); - return legal; - } - - /** One configuration key split into the map entry it configures and the leaf inside it. */ - private record Entry(String name, String leaf) {} - - private static Entry split(String key, String sectionPrefix) { - String remainder = key.substring(sectionPrefix.length()); - String name; - String leaf; - if (remainder.startsWith("[")) { - // Relaxed binding writes a map key containing a dot as `[order.events]`, so the bracket is - // the only reliable boundary when one is present. - int close = remainder.indexOf(']'); - name = close < 0 ? remainder : remainder.substring(1, close); - leaf = close < 0 ? "" : remainder.substring(close + 1); - } else { - int dot = remainder.indexOf('.'); - name = dot < 0 ? remainder : remainder.substring(0, dot); - leaf = dot < 0 ? "" : remainder.substring(dot); - } - if (leaf.startsWith(".")) { - leaf = leaf.substring(1); - } - return new Entry(name, canonical(leaf.replaceAll("\\[\\d+\\]", ""))); - } - - /** - * Returns every leaf path a settings record accepts, in the canonical kebab form. - * - *

Nested records are walked because the configuration is nested; a list-valued component is a - * leaf because its indices are stripped before the comparison. - */ - private static Set leafPaths(Class shape) { - Set paths = new LinkedHashSet<>(); - collectLeafPaths(shape, "", paths); - return paths; - } - - private static void collectLeafPaths(Class shape, String prefix, Set paths) { - for (RecordComponent component : shape.getRecordComponents()) { - String path = prefix + canonical(component.getName()); - if (component.getType().isRecord()) { - collectLeafPaths(component.getType(), path + '.', paths); - } else { - paths.add(path); - } - } - } - - /** Normalises a property path to the kebab-case form the settings records declare. */ - private static String canonical(String path) { - StringBuilder canonical = new StringBuilder(path.length() + 4); - for (int index = 0; index < path.length(); index++) { - char character = path.charAt(index); - if (character == '_') { - canonical.append('-'); - } else if (Character.isUpperCase(character)) { - if (index > 0 && path.charAt(index - 1) != '.' && path.charAt(index - 1) != '-') { - canonical.append('-'); - } - canonical.append(Character.toLowerCase(character)); - } else { - canonical.append(character); - } - } - return canonical.toString(); - } - - private List keysUnder(String prefix) { - List keys = new ArrayList<>(); - for (PropertySource source : environment.getPropertySources()) { - if (!(source instanceof EnumerablePropertySource enumerable)) { - continue; - } - for (String key : enumerable.getPropertyNames()) { - if (key.startsWith(prefix)) { - keys.add(key); - } - } - } - return keys; - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfiguration.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfiguration.java deleted file mode 100644 index 0dc88797..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfiguration.java +++ /dev/null @@ -1,151 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.inbox.IdempotentConsumer; -import dev.caskeleton.messaging.inbox.InboxMessageHandler; -import dev.caskeleton.messaging.policy.DeadLetterOrchestrator; -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.runtime.DefaultDeliveryProcessor; -import dev.caskeleton.messaging.schema.MessageCodecRegistry; -import dev.caskeleton.messaging.security.BrokerSecurityProfile; -import dev.caskeleton.messaging.security.DestinationAccessPolicy; -import java.time.Instant; -import java.time.InstantSource; -import java.util.ArrayList; -import java.util.LinkedHashMap; -import java.util.List; -import java.util.Map; -import java.util.concurrent.CompletableFuture; -import java.util.stream.Stream; -import org.springframework.beans.factory.ObjectProvider; -import org.springframework.boot.autoconfigure.condition.ConditionalOnBean; -import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; -import org.springframework.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; - -/** - * The broker-neutral consume pipeline, assembled from the application's {@link MessageHandler} - * beans (owner decision 10, S7-#2). - * - *

On when present: no handler bean, no consumer. {@code app.messaging.enabled=false} turns the - * whole platform, consumers included, off. Every contradiction a handler can declare fails startup - * here, before any broker connection opens: - * - *

    - *
  • a handler for a destination nobody declared; - *
  • a consumed destination without {@code consumer.group} — the group is also the inbox - * identity, and inventing one would split or merge consumers silently; - *
  • a destination the broker's security profile does not list as consumable; - *
  • {@code INBOX_TRANSACTIONAL} without an {@link IdempotentConsumer} bean to run it. - *
- */ -@Configuration(proxyBeanMethods = false) -public class MessagingConsumeConfiguration { - - /** - * One consume pipeline per destination at least one handler names. - * - * @param handlers the application's handlers - * @param destinations the validated destination registry - * @param codecs the codec registry - * @param deadLetters publishes to a destination's dead-letter destination - * @param inbox runs a handler inside the inbox reservation's transaction, when supplied - * @param compiled the security profiles compiled from configuration - * @param declaredSecurity the security profiles the application declared as beans - * @return the consumers - */ - @Bean - @ConditionalOnBean(MessageHandler.class) - @ConditionalOnMissingBean - public MessageConsumers messageConsumers( - ObjectProvider> handlers, - ValidatedDestinationRegistry destinations, - MessageCodecRegistry codecs, - DeadLetterOrchestrator deadLetters, - ObjectProvider inbox, - CompiledMessagingConfiguration compiled, - ObjectProvider declaredSecurity) { - Map>> byDestination = new LinkedHashMap<>(); - handlers - .orderedStream() - .forEach( - handler -> - byDestination - .computeIfAbsent(handler.destination().name(), name -> new ArrayList<>()) - .add(handler)); - - Map access = new LinkedHashMap<>(); - Stream.concat(compiled.security().stream(), declaredSecurity.orderedStream()) - .forEach(profile -> access.putIfAbsent(profile.broker(), profile.access())); - - List consumers = new ArrayList<>(); - byDestination.forEach( - (name, forDestination) -> { - DestinationProfile profile = destinations.require(name); - String group = - profile - .consumer() - .group() - .filter(value -> !value.isBlank()) - .orElseThrow( - () -> - refused( - name, - "is consumed by a handler but declares no consumer.group; the group" - + " is also the inbox identity, so the platform does not invent" - + " one")); - DestinationAccessPolicy acl = access.get(profile.broker()); - if (acl != null && !acl.mayConsume(name)) { - throw refused( - name, - "is not in app.messaging.security." + profile.broker() + ".access.consumable"); - } - List> pipeline = - profile.externalSideEffectGuarantee() - == ExternalSideEffectGuarantee.INBOX_TRANSACTIONAL - ? forDestination.stream() - .>map( - handler -> inboxed(handler, inbox.getIfAvailable(), group, name)) - .toList() - : forDestination; - DefaultDeliveryProcessor processor = - new DefaultDeliveryProcessor( - profile, - pipeline, - codecs, - (delivery, failure) -> - // The processor acknowledges the source itself once the publish confirms, - // so the orchestrator's settlement callback has nothing left to do. - deadLetters - .deadLetter( - profile, - delivery, - failure, - () -> CompletableFuture.completedFuture(null)) - .thenApply(result -> result.publishResult().completion()), - group, - InstantSource.system()); - consumers.add(new MessageConsumers.Consumer(profile, group, processor::process)); - }); - return new MessageConsumers(consumers); - } - - private static MessageHandler inboxed( - MessageHandler handler, IdempotentConsumer inbox, String group, DestinationName name) { - if (inbox == null) { - throw refused( - name, - "declares INBOX_TRANSACTIONAL but no IdempotentConsumer bean exists; without one the" - + " handler's side effect is not protected against redelivery"); - } - return new InboxMessageHandler<>(handler, inbox, group, Instant::now); - } - - private static MessagingConfigurationException refused(DestinationName name, String reason) { - return new MessagingConfigurationException( - "MESSAGING_CONSUMER_INVALID", "destination '" + name.value() + "' " + reason); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCoreAutoConfiguration.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCoreAutoConfiguration.java deleted file mode 100644 index c7fa0304..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCoreAutoConfiguration.java +++ /dev/null @@ -1,26 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import org.springframework.boot.context.properties.EnableConfigurationProperties; -import org.springframework.context.annotation.Configuration; - -/** - * Wires the platform's configuration, publish pipeline and observability. - * - *

It was one 550-line class with 28 beans (S7-#9a). It is now the entry point that imports the - * three parts, plus the consume pipeline (S7-#2), so an adopter or a test that names this class - * still gets the whole core. - * - * @see MessagingValidationConfiguration - * @see MessagingPublishConfiguration - * @see MessagingObservabilityConfiguration - * @see MessagingConsumeConfiguration - */ -@Configuration(proxyBeanMethods = false) -@EnableConfigurationProperties(MessagingSettings.class) -@org.springframework.context.annotation.Import({ - MessagingValidationConfiguration.class, - MessagingPublishConfiguration.class, - MessagingObservabilityConfiguration.class, - MessagingConsumeConfiguration.class -}) -public class MessagingCoreAutoConfiguration {} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCredentialRequirementValidator.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCredentialRequirementValidator.java deleted file mode 100644 index 02737341..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCredentialRequirementValidator.java +++ /dev/null @@ -1,92 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.security.BrokerSecurityProfile; -import java.util.List; -import java.util.Objects; -import org.springframework.beans.factory.InitializingBean; -import org.springframework.beans.factory.ObjectProvider; -import org.springframework.core.env.Environment; - -/** - * Fails startup with one actionable error when a production profile has no credential source. - * - *

The broker configurations declared {@code CredentialRuntimeRegistry} as a required constructor - * parameter, and that registry exists only when the application supplies a {@code - * CredentialProvider}. An application that enabled the starter without one therefore failed on "no - * qualifying bean of type CredentialRuntimeRegistry" — a message about this platform's internals, - * naming a type the operator has never heard of, when the thing they have to do is supply a - * credential source. - * - *

The check is scoped to production profiles. A local profile that connects to a broker with no - * authentication is a legitimate development setup; the same profile marked production is not, and - * the two must not be satisfiable by the same configuration. - * - *

It reads both the profiles an application declared as beans and the ones compiled from {@code - * app.messaging.security}. A deployment that configures its production broker in YAML and one that - * writes it in Java must meet the same refusal, or the check becomes advice about how to write the - * configuration rather than a rule about what the configuration may say. - */ -public final class MessagingCredentialRequirementValidator implements InitializingBean { - - private final ObjectProvider profiles; - - private final List configured; - - private final ObjectProvider credentials; - - private final Environment environment; - - /** - * Creates the validator. - * - * @param profiles the security profiles the application declared as beans - * @param configured the security profiles compiled from configuration - * @param credentials the application's credential source, if it supplied one - * @param environment the resolved environment, used to report the active profiles - */ - public MessagingCredentialRequirementValidator( - ObjectProvider profiles, - List configured, - ObjectProvider credentials, - Environment environment) { - this.profiles = Objects.requireNonNull(profiles, "profiles must not be null"); - this.configured = - List.copyOf(Objects.requireNonNull(configured, "configured must not be null")); - this.credentials = Objects.requireNonNull(credentials, "credentials must not be null"); - this.environment = Objects.requireNonNull(environment, "environment must not be null"); - } - - @Override - public void afterPropertiesSet() { - validate(); - } - - /** - * Refuses a production broker profile with no credential provider. - * - * @throws MessagingConfigurationException naming the profiles and what to supply - */ - public void validate() { - if (credentials.getIfAvailable() != null) { - return; - } - List production = - java.util.stream.Stream.concat(configured.stream(), profiles.stream()) - .filter(BrokerSecurityProfile::production) - .map(BrokerSecurityProfile::broker) - .distinct() - .toList(); - if (production.isEmpty()) { - return; - } - throw new MessagingConfigurationException( - "MESSAGING_CREDENTIAL_PROVIDER_REQUIRED", - "broker profile(s) " - + production - + " are marked production and no CredentialProvider bean is defined; supply one, or" - + " mark the profile non-production if this deployment genuinely connects without" - + " authentication. Active Spring profiles: " - + List.of(environment.getActiveProfiles())); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpoint.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpoint.java deleted file mode 100644 index 79f85184..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpoint.java +++ /dev/null @@ -1,78 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.policy.MessagingAdmissionController; -import java.util.LinkedHashMap; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import org.springframework.boot.actuate.endpoint.annotation.Endpoint; -import org.springframework.boot.actuate.endpoint.annotation.ReadOperation; - -/** - * Exposes what the messaging runtime is currently doing, over the actuator. - * - *

Read-only. An actuator endpoint is reachable by anything that can reach the management port, - * so a write operation here would be an unauthenticated pause or purge in most deployments — the - * admin plane exists for those, with approvals and an audit trail this endpoint deliberately does - * not duplicate. - * - *

What it reports is bounded and free of per-message identity: destination names, guarantees, - * capability tiers, and in-flight counts. No message ids, no keys, no payloads — an actuator - * response is a diagnostic surface, and a diagnostic surface that echoes message content is a - * re-identification surface too. - */ -@Endpoint(id = "messaging") -public final class MessagingEndpoint { - - private final ValidatedDestinationRegistry registry; - private final MessagingAdmissionController admission; - - /** - * Creates the endpoint. - * - *

The counts come from the gate every publish passes through. They used to come from a second - * limiter that no publish ever touched, so the endpoint reported zero in flight under any load — - * a diagnostic that is worse than absent, because it looks like an answer. - * - * @param registry the validated destination registry - * @param admission the gate every publish passes through - */ - public MessagingEndpoint( - ValidatedDestinationRegistry registry, MessagingAdmissionController admission) { - this.registry = Objects.requireNonNull(registry, "registry must not be null"); - this.admission = Objects.requireNonNull(admission, "admission must not be null"); - } - - /** - * Returns the current messaging state. - * - * @return the destinations, their declared guarantees, and the in-flight counts - */ - @ReadOperation - public Map messaging() { - Map report = new LinkedHashMap<>(); - report.put("globalInFlight", admission.inFlight()); - report.put("destinations", destinations()); - return Map.copyOf(report); - } - - private List> destinations() { - return registry.all().values().stream().map(this::describe).toList(); - } - - private Map describe(DestinationProfile profile) { - Map entry = new LinkedHashMap<>(); - entry.put("name", profile.name().value()); - entry.put("broker", profile.broker()); - entry.put("kind", profile.kind().name()); - entry.put("deliveryGuarantee", profile.deliveryGuarantee().name()); - entry.put("orderingScope", profile.orderingScope().name()); - entry.put("tier", profile.tier().name()); - entry.put("production", profile.production()); - entry.put("deadLetterEnabled", profile.deadLetter().enabled()); - entry.put("retryMode", profile.retry().mode().name()); - entry.put("inFlight", admission.inFlight(profile.name().value())); - return Map.copyOf(entry); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingObservabilityConfiguration.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingObservabilityConfiguration.java deleted file mode 100644 index bd8ca53c..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingObservabilityConfiguration.java +++ /dev/null @@ -1,77 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.observation.CardinalityGuard; -import dev.caskeleton.messaging.observation.MessagingRedactor; -import org.springframework.boot.autoconfigure.condition.ConditionalOnBean; -import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; -import org.springframework.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; - -/** - * Metrics, diagnostic redaction and the read-only actuator endpoint. - * - *

The Micrometer binding is conditional on a registry, so a narrow test or a non-observed - * adopter assembles the platform without Micrometer. - */ -@Configuration(proxyBeanMethods = false) -public class MessagingObservabilityConfiguration { - - /** - * Returns the diagnostic redactor. - * - * @return the redactor - */ - @Bean - @ConditionalOnMissingBean - public MessagingRedactor messagingRedactor() { - return new MessagingRedactor(); - } - - /** - * Returns the metric cardinality guard. - * - * @return the guard - */ - @Bean - @ConditionalOnMissingBean - public CardinalityGuard cardinalityGuard() { - return new CardinalityGuard(); - } - - /** - * Binds the platform observation seam to Micrometer when a registry is available. - * - *

Narrow tests and non-observed adopters may omit Micrometer entirely. A normal Boot runtime - * with Actuator contributes a registry, in which case publish outcomes must not fall back to the - * no-op observation constructor. - * - * @param registry the Micrometer registry - * @param guard the bounded-cardinality guard - * @param redactor the diagnostics redactor - * @return the messaging metrics binding - */ - @Bean - @ConditionalOnBean(io.micrometer.core.instrument.MeterRegistry.class) - @ConditionalOnMissingBean(dev.caskeleton.messaging.observation.MessagingObservation.class) - public dev.caskeleton.messaging.observation.MessagingObservation messagingObservation( - io.micrometer.core.instrument.MeterRegistry registry, - CardinalityGuard guard, - MessagingRedactor redactor) { - return new dev.caskeleton.messaging.observation.MessagingMetrics(registry, guard, redactor); - } - - /** - * Returns the read-only actuator endpoint. - * - * @param registry the validated destination registry - * @param admission the gate every publish passes through - * @return the endpoint - */ - @Bean - @ConditionalOnMissingBean - public MessagingEndpoint messagingEndpoint( - ValidatedDestinationRegistry registry, - dev.caskeleton.messaging.policy.MessagingAdmissionController admission) { - return new MessagingEndpoint(registry, admission); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingOutboxRelayLifecycle.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingOutboxRelayLifecycle.java deleted file mode 100644 index 4d20c471..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingOutboxRelayLifecycle.java +++ /dev/null @@ -1,69 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.outbox.OutboxRelayWorker; -import java.time.Duration; -import java.util.Objects; -import org.springframework.context.SmartLifecycle; - -/** - * Starts and stops the outbox relay with the application context. - * - *

Without this the relay is a bean an application has to remember to drive itself, and the - * failure when it forgets is silent: rows accumulate in a table that looks healthy while no message - * is ever published. - * - *

Stopping drains rather than interrupts. A pass killed between claiming a row and writing its - * outcome leaves that row {@code IN_FLIGHT} under a lease no other relay may touch until it - * expires, so an orderly shutdown would strand exactly what a crash strands. - * - *

Every replica runs its own relay. Claims are taken with {@code FOR UPDATE SKIP LOCKED} under - * an owner and a fencing token, so two relays never publish the same row; leader election would buy - * nothing here except a single point of failure for the whole outbox. - */ -public final class MessagingOutboxRelayLifecycle implements SmartLifecycle { - - private final OutboxRelayWorker worker; - - private final Duration drainDeadline; - - /** - * Creates the lifecycle. - * - * @param worker the relay worker to drive - * @param drainDeadline how long a running pass may take to finish on stop - */ - public MessagingOutboxRelayLifecycle(OutboxRelayWorker worker, Duration drainDeadline) { - this.worker = Objects.requireNonNull(worker, "worker must not be null"); - this.drainDeadline = Objects.requireNonNull(drainDeadline, "drainDeadline must not be null"); - } - - @Override - public void start() { - worker.start(); - } - - @Override - public void stop() { - worker.stop(drainDeadline); - } - - @Override - public boolean isRunning() { - return worker.isRunning(); - } - - /** - * Stops before the admission gate closes. - * - *

{@code SmartLifecycle} stops in descending phase order, so the highest phase stops first. - * The relay has to be the one that stops first: closing admission while a pass is mid-publish - * turns that pass's rows ambiguous — a shutdown that manufactures exactly the uncertainty the - * drain exists to avoid. - * - * @return the lifecycle phase - */ - @Override - public int getPhase() { - return Integer.MAX_VALUE; - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java deleted file mode 100644 index 3534ca20..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java +++ /dev/null @@ -1,42 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import org.springframework.boot.autoconfigure.AutoConfiguration; -import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; -import org.springframework.boot.context.properties.EnableConfigurationProperties; -import org.springframework.context.annotation.Import; - -/** - * The one place that decides whether this application has messaging (MSG-INT-004). - * - *

The starter registered five auto-configurations directly, and not one carried a messaging - * master condition — putting the starter on the classpath assembled the platform. That is the same - * shape the other four adapters had, and the same fix: one root owning the condition, importing - * children that carry none, so a bean added to any child next month is gated without anyone - * remembering to repeat a condition. - * - *

Provider selection is a property, not a classpath accident. Kafka and Rabbit were each - * conditioned on their client class being present, so an application that happened to have both - * libraries — a transitive dependency is enough — assembled both providers and published through - * 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. - * - *

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", - matchIfMissing = true) -@EnableConfigurationProperties(MessagingSettings.class) -@Import({ - MessagingCoreAutoConfiguration.class, - MessagingProviderSelection.class, - MessagingReliabilityAutoConfiguration.class, - MessagingAdminAutoConfiguration.class -}) -public class MessagingPlatformRootAutoConfiguration {} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPrefixMigrationValidator.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPrefixMigrationValidator.java deleted file mode 100644 index 6db80501..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPrefixMigrationValidator.java +++ /dev/null @@ -1,83 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.util.ArrayList; -import java.util.List; -import java.util.Objects; -import org.springframework.beans.factory.InitializingBean; -import org.springframework.core.env.ConfigurableEnvironment; -import org.springframework.core.env.EnumerablePropertySource; -import org.springframework.core.env.PropertySource; - -/** - * Refuses a configuration written against a prefix this platform no longer binds. - * - *

There were three namespaces. The starter's binder read {@code backend.messaging}; the deployed - * runtime and its {@code APP_MESSAGING_*} environment variables read {@code app.messaging}; and the - * configuration reference documented a bare {@code messaging} with destination, broker and security - * sections that no binder had ever contained. Two of the three bound nothing, so a deployment - * configured exactly as documented changed no behaviour and produced no error — the settings were - * simply inert. - * - *

Silence is the specific failure being fixed here. A key under a dead prefix is not a typo the - * operator will notice: it looks configured, it starts cleanly, and the first evidence that the - * limit or the flag never applied arrives during the incident it was meant to prevent. - */ -public final class MessagingPrefixMigrationValidator implements InitializingBean { - - private final ConfigurableEnvironment environment; - - public MessagingPrefixMigrationValidator(ConfigurableEnvironment environment) { - this.environment = Objects.requireNonNull(environment, "environment must not be null"); - } - - @Override - public void afterPropertiesSet() { - validate(); - } - - /** - * Fails when any key uses a superseded prefix. - * - * @throws MessagingConfigurationException naming the offending keys and the prefix to use - */ - public void validate() { - List superseded = keysUnder(MessagingSettings.SUPERSEDED_PREFIX + '.'); - List documented = keysUnder(MessagingSettings.DOCUMENTED_PREFIX + '.'); - // The documented bare prefix overlaps nothing else only because app.messaging is longer; a key - // such as `messaging.destinations` is caught here while `app.messaging.destinations` is not. - documented.removeIf(key -> key.startsWith(MessagingSettings.PREFIX + '.')); - - List offending = new ArrayList<>(superseded); - offending.addAll(documented); - if (offending.isEmpty()) { - return; - } - throw new MessagingConfigurationException( - "MESSAGING_PREFIX_SUPERSEDED", - "these properties use a prefix this platform does not bind: " - + String.join(", ", offending.stream().sorted().limit(10).toList()) - + (offending.size() > 10 ? " (and " + (offending.size() - 10) + " more)" : "") - + "; move them under '" - + MessagingSettings.PREFIX - + "', which is the prefix the runtime and the APP_MESSAGING_* variables already use." - + " Accepting both would let one deployment configure half the platform under each"); - } - - private List keysUnder(String prefix) { - List keys = new ArrayList<>(); - for (PropertySource source : environment.getPropertySources()) { - if (!(source instanceof EnumerablePropertySource enumerable)) { - // A non-enumerable source cannot be scanned, and guessing at its contents would produce a - // startup failure nobody can act on. - continue; - } - for (String key : enumerable.getPropertyNames()) { - if (key.startsWith(prefix)) { - keys.add(key); - } - } - } - return keys; - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProviderSelection.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProviderSelection.java deleted file mode 100644 index b7a248fb..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProviderSelection.java +++ /dev/null @@ -1,136 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import java.util.List; -import java.util.Map; -import org.springframework.context.EnvironmentAware; -import org.springframework.context.annotation.Configuration; -import org.springframework.context.annotation.Import; -import org.springframework.context.annotation.ImportSelector; -import org.springframework.core.env.Environment; -import org.springframework.core.type.AnnotationMetadata; -import org.springframework.util.ClassUtils; - -/** - * Selects exactly one transport, from a closed registry, by name (MSG-INT-004). - * - *

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

Three outcomes are startup errors now rather than silences: - * - *

    - *
  • 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 capability switch says yes and nothing says what - * to. - *
- * - *

The provider configurations carry no condition of their own any more. Each is reached only - * along the path this class chose, which is what makes "which transport is active" answerable by - * reading one property rather than by resolving a dependency graph. - */ -@Configuration(proxyBeanMethods = false) -@Import(MessagingProviderSelection.Selector.class) -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"); - - /** Broker id to the configuration that assembles it. */ - static final Map PROVIDER_CONFIGURATIONS = - Map.of("kafka", "dev.caskeleton.messaging.autoconfigure.KafkaMessagingAutoConfiguration"); - - /** - * Broker id to the record its starter binds the family's own keys of an {@code - * app.messaging.brokers.} entry into. - * - *

Named rather than referenced for the same reason as {@link #PROVIDER_CONFIGURATIONS}: this - * starter is broker-neutral and cannot see the class. The key validator loads it when present. - */ - static final Map PROVIDER_BROKER_SETTINGS = - Map.of("kafka", "dev.caskeleton.messaging.autoconfigure.KafkaBrokerSettings"); - - /** 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"); - - /** 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(); - } - - /** - * Resolves the selection, or throws naming the property and the values it accepts. - * - * @param environment the resolved environment - * @return the selected broker id - */ - public static String selectedBroker(Environment environment) { - String broker = environment.getProperty(MessagingSettings.PREFIX + ".broker", "").trim(); - if (broker.isEmpty()) { - throw new IllegalStateException( - MessagingSettings.PREFIX - + ".enabled=true needs a transport; set " - + MessagingSettings.PREFIX - + ".broker to one of " - + registeredBrokerIds()); - } - String clientClass = REGISTERED_BROKERS.get(broker); - if (clientClass == null) { - throw new IllegalStateException( - MessagingSettings.PREFIX - + ".broker=" - + broker - + " is not a registered transport; registered: " - + registeredBrokerIds()); - } - if (!ClassUtils.isPresent(clientClass, MessagingProviderSelection.class.getClassLoader())) { - throw new IllegalStateException( - MessagingSettings.PREFIX - + ".broker=" - + broker - + " needs " - + clientClass - + " on the classpath; the deployment selected a transport it did not ship"); - } - // The client library and the broker starter are two different build decisions, and only the - // second one carries the configuration that assembles the transport. A deployment can hold the - // Kafka client transitively and still not ship the Kafka starter — this core starter is - // broker-neutral on purpose — and until this check existed that combination reached Spring's - // import machinery, which reported a missing .class file rather than a missing capability. - String providerConfiguration = PROVIDER_CONFIGURATIONS.get(broker); - if (!ClassUtils.isPresent( - providerConfiguration, MessagingProviderSelection.class.getClassLoader())) { - throw new IllegalStateException( - MessagingSettings.PREFIX - + ".broker=" - + broker - + " needs the " - + PROVIDER_STARTERS.get(broker) - + " module on the classpath; this core starter is broker-neutral and the deployment" - + " did not compose the transport it selected"); - } - return broker; - } - - /** Imports the one configuration the selected broker names. */ - static final class Selector implements ImportSelector, EnvironmentAware { - - private Environment environment; - - @Override - public void setEnvironment(Environment environment) { - this.environment = environment; - } - - @Override - public String[] selectImports(AnnotationMetadata importingClassMetadata) { - return new String[] {PROVIDER_CONFIGURATIONS.get(selectedBroker(environment))}; - } - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPublishConfiguration.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPublishConfiguration.java deleted file mode 100644 index 471e32e4..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPublishConfiguration.java +++ /dev/null @@ -1,314 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.policy.BackoffCalculator; -import dev.caskeleton.messaging.policy.DeadLetterOrchestrator; -import dev.caskeleton.messaging.policy.DefaultRetryDecisionEngine; -import dev.caskeleton.messaging.policy.RetryDecisionEngine; -import dev.caskeleton.messaging.transport.DefaultMessagingRuntimeRegistry; -import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator; -import dev.caskeleton.messaging.transport.MessagingRuntimeRegistry; -import org.springframework.beans.factory.ObjectProvider; -import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; -import org.springframework.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; - -/** - * The publish pipeline: codecs, destination access, admission, the publisher, the runtime it - * publishes through, and the shutdown order that drains it. - * - *

The M2 and M3 surfaces are deliberately not auto-configured. Manual settlement, native - * capabilities, and the Admin Plane are opt-in beans with their own credentials, so a service - * cannot acquire them by adding the starter to its classpath. - */ -@Configuration(proxyBeanMethods = false) -public class MessagingPublishConfiguration { - - /** - * Returns the retry decision engine. - * - * @return the engine - */ - @Bean - @ConditionalOnMissingBean - public RetryDecisionEngine retryDecisionEngine() { - return new DefaultRetryDecisionEngine(new BackoffCalculator()); - } - - /** - * Returns the dead letter orchestrator. - * - * @param publisher the platform publisher - * @return the orchestrator - */ - @Bean - @ConditionalOnMissingBean - public DeadLetterOrchestrator deadLetterOrchestrator(MessagePublisher publisher) { - return new DeadLetterOrchestrator(publisher); - } - - /** - * Returns the runtime registry used for credential and topology rotation. - * - * @param properties the bound configuration - * @return the registry - */ - @Bean - @ConditionalOnMissingBean - public MessagingRuntimeRegistry messagingRuntimeRegistry(MessagingSettings properties) { - return new DefaultMessagingRuntimeRegistry(properties.getShutdown().getDrainDeadline()); - } - - /** - * Returns the graceful shutdown coordinator. - * - * @param properties the bound configuration - * @return the coordinator - */ - @Bean - @ConditionalOnMissingBean - public GracefulShutdownCoordinator gracefulShutdownCoordinator(MessagingSettings properties) { - return new GracefulShutdownCoordinator(properties.getShutdown().getDrainDeadline()); - } - - /** - * Drives the shutdown phases the admission gate and the drain coordinator only implemented. - * - * @param admission the publish admission gate - * @param drain the in-flight work coordinator - * @param properties the bound configuration supplying the drain deadline - * @return the lifecycle - */ - @Bean - @ConditionalOnMissingBean - public MessagingShutdownLifecycle messagingShutdownLifecycle( - dev.caskeleton.messaging.policy.MessagingAdmissionController admission, - GracefulShutdownCoordinator drain, - MessagingSettings properties) { - return new MessagingShutdownLifecycle( - admission, drain, properties.getShutdown().getDrainDeadline()); - } - - /** - * The codec registry, which had no implementation anywhere (MSG-INT-003). - * - *

The message contracts come from the deployment — a {@code Map} of message type and schema - * version to payload class — and default to empty, which means no message type can be - * encoded and every publish is refused at preparation. That is fail-closed on purpose: a codec - * that accepted an unregistered type would serialise whatever object it was handed and put bytes - * on a topic that consumers compiled against a different shape will read. - * - *

To those the handler beans add what they consume ({@link MessageContracts#withConsumed}): - * the decode list is what the handlers declare, so a service registers nothing to consume. The - * handlers are resolved here, so a handler whose own dependencies reach back to the publisher is - * a dependency cycle, and Spring refuses it at startup naming both beans. - * - * @param contracts the declared message contracts, if the deployment registered any - * @param handlers the deployment's message handlers, whose declarations are decoded - * @return the registry, defaulting to JSON - */ - @Bean - @ConditionalOnMissingBean(dev.caskeleton.messaging.schema.MessageCodecRegistry.class) - public dev.caskeleton.messaging.runtime.RegisteredMessageCodecs messagingCodecs( - ObjectProvider contracts, - ObjectProvider> handlers) { - return dev.caskeleton.messaging.runtime.RegisteredMessageCodecs.of( - dev.caskeleton.messaging.schema.json.JacksonMessageCodec.of( - contracts - .getIfAvailable(MessageContracts::none) - .withConsumed(handlers.orderedStream().toList()) - .byKey())); - } - - /** - * The destination profiles the publisher resolves against, from the validated registry. - * - * @param destinations the validated registry - * @return the profile registry - */ - @Bean - @ConditionalOnMissingBean - public dev.caskeleton.messaging.runtime.DestinationProfileRegistry messagingDestinationProfiles( - ValidatedDestinationRegistry destinations) { - return dev.caskeleton.messaging.runtime.DestinationProfileRegistry.of(destinations.all()); - } - - /** - * What this deployment may publish to. - * - *

The declared destinations, and nothing else. Deny-all assembles a platform that refuses - * every publish a correctly configured deployment makes; allow-all makes the check decoration. - * Declaring a destination profile is already an act of configuration, so a message to one nobody - * declared is a typo or a module reaching past its contract — which is what this check is for. - * - *

A broker with a security entry narrows that further to its {@code access.publishable} list. - * The list was compiled and then read by nothing, so a destination the security entry left out - * was published to anyway. - * - * @param destinations the validated registry - * @param compiled the security profiles compiled from configuration - * @param declared the security profiles the application declared as beans - * @return the access policy - */ - @Bean - @ConditionalOnMissingBean - public dev.caskeleton.messaging.security.DestinationAccessPolicy messagingDestinationAccess( - ValidatedDestinationRegistry destinations, - CompiledMessagingConfiguration compiled, - ObjectProvider declared) { - java.util.Map byBroker = - new java.util.HashMap<>(); - java.util.stream.Stream.concat(compiled.security().stream(), declared.orderedStream()) - .forEach( - profile -> { - if (byBroker.putIfAbsent(profile.broker(), profile.access()) != null) { - throw new IllegalStateException( - "broker '" - + profile.broker() - + "' has more than one security profile; its access list is ambiguous"); - } - }); - java.util.Map< - dev.caskeleton.messaging.api.destination.DestinationName, - dev.caskeleton.messaging.policy.DestinationProfile> - permitted = new java.util.HashMap<>(); - destinations - .all() - .forEach( - (name, profile) -> { - dev.caskeleton.messaging.security.DestinationAccessPolicy acl = - byBroker.get(profile.broker()); - if (acl == null || acl.mayPublish(name)) { - permitted.put(name, profile); - } - }); - return dev.caskeleton.messaging.runtime.DeclaredDestinationAccess.of(permitted); - } - - /** - * Payload and in-flight admission. - * - * @param properties the bound settings - * @return the admission controller - */ - @Bean - @ConditionalOnMissingBean - public dev.caskeleton.messaging.policy.MessagingAdmissionController messagingAdmission( - MessagingSettings properties) { - return new dev.caskeleton.messaging.policy.MessagingAdmissionController( - new dev.caskeleton.messaging.policy.PayloadLimitGuard( - new dev.caskeleton.messaging.policy.PayloadPolicy( - dev.caskeleton.messaging.schema.json.JacksonMessageCodec.DEFAULT_MAX_BYTES, - dev.caskeleton.messaging.schema.json.JacksonMessageCodec.DEFAULT_MAX_BYTES / 2)), - new dev.caskeleton.messaging.policy.InFlightLimiter( - properties.getBackpressure().getGlobalLimit(), java.time.Duration.ofSeconds(5)), - properties.getBackpressure().getPerDestinationLimit()); - } - - /** - * The publisher this configuration has been consuming since it was written (MSG-INT-003). - * - *

{@code deadLetterOrchestrator} takes a {@link MessagePublisher}, and no configuration - * produced one. A selected transport therefore could not assemble: the platform failed on a - * missing bean rather than publishing anywhere. {@code DefaultMessagePublisher} existed in {@code - * messaging-runtime-core} the whole time; the starter did not depend on that leaf. - * - * @param destinations the destination profiles - * @param access what may be published to - * @param codecs the codec registry - * @param admission payload and in-flight admission - * @param runtimes the runtime registry - * @param transport the selected transport - * @return the publisher - */ - @Bean - @ConditionalOnMissingBean(MessagePublisher.class) - public dev.caskeleton.messaging.runtime.DefaultMessagePublisher messagingPublisher( - dev.caskeleton.messaging.runtime.DestinationProfileRegistry destinations, - dev.caskeleton.messaging.security.DestinationAccessPolicy access, - dev.caskeleton.messaging.schema.MessageCodecRegistry codecs, - dev.caskeleton.messaging.policy.MessagingAdmissionController admission, - MessagingRuntimeRegistry runtimes, - dev.caskeleton.messaging.transport.MessagingTransport transport, - ObjectProvider observation) { - dev.caskeleton.messaging.observation.MessagingObservation configured = - observation.getIfAvailable(); - if (configured == null) { - return new dev.caskeleton.messaging.runtime.DefaultMessagePublisher( - destinations, access, codecs, admission, runtimes, transport); - } - return new dev.caskeleton.messaging.runtime.DefaultMessagePublisher( - destinations, access, codecs, admission, runtimes, transport, System::nanoTime, configured); - } - - /** - * Installs the selected transport into the runtime registry (MSG-INT-003). - * - *

The registry was constructed empty and nothing ever installed anything, so every publish - * failed at {@code PUBLISH_RUNTIME_UNAVAILABLE} — after resolving the destination, checking - * access and encoding the payload, which is as far as a message could get. The same "registry - * built empty" shape the notification provider registry had. - * - * @param runtimes the registry - * @param transport the selected transport - * @return the startup installation - */ - @Bean - public org.springframework.beans.factory.InitializingBean messagingRuntimeInstallation( - MessagingRuntimeRegistry runtimes, - ObjectProvider transport, - CompiledMessagingConfiguration compiled) { - return () -> { - dev.caskeleton.messaging.transport.MessagingTransport selected = transport.getIfAvailable(); - if (selected == null) { - // Not a silent skip of a check: MessagingProviderSelection is what guarantees a transport - // when a broker is selected, and it refuses startup by name when one is not. This - // configuration is also loadable on its own — an adopter composing the policy primitives - // without a transport — and demanding one here would refuse that. - return; - } - - String runtimeName = logicalRuntimeName(selected, compiled); - runtimes.install( - new dev.caskeleton.messaging.runtime.TransportMessagingRuntime( - runtimeName, selected.generation(), selected)); - }; - } - - private static String logicalRuntimeName( - dev.caskeleton.messaging.transport.MessagingTransport selected, - CompiledMessagingConfiguration compiled) { - String configuredFamily = - switch (selected.brokerName()) { - case "kafka" -> BrokerSettings.KAFKA; - default -> selected.brokerName(); - }; - java.util.List configuredNames = - compiled.brokers().entrySet().stream() - .filter( - entry -> - entry.getValue().type() != null - && entry.getValue().type().equalsIgnoreCase(configuredFamily)) - .map(java.util.Map.Entry::getKey) - .sorted() - .toList(); - - if (configuredNames.isEmpty()) { - // Backward compatibility for applications that declare all profiles as beans and therefore - // have no app.messaging.brokers entries. Their destination profiles historically named the - // transport family directly. - return selected.brokerName(); - } - if (configuredNames.size() != 1) { - throw new IllegalStateException( - "the selected " - + selected.brokerName() - + " transport has one client/runtime but app.messaging.brokers declares " - + configuredNames.size() - + " logical brokers " - + configuredNames - + "; configure exactly one logical broker for the selected transport"); - } - return configuredNames.getFirst(); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingReliabilityAutoConfiguration.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingReliabilityAutoConfiguration.java deleted file mode 100644 index 7696cde5..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingReliabilityAutoConfiguration.java +++ /dev/null @@ -1,218 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.inbox.IdempotentConsumer; -import dev.caskeleton.messaging.inbox.InboxCleanupJob; -import dev.caskeleton.messaging.inbox.InboxRetentionPolicy; -import dev.caskeleton.messaging.outbox.OutboxCleanupJob; -import dev.caskeleton.messaging.outbox.OutboxEnvelopeFactory; -import dev.caskeleton.messaging.outbox.OutboxProperties; -import dev.caskeleton.messaging.outbox.OutboxRelay; -import dev.caskeleton.messaging.outbox.OutboxRelayWorker; -import dev.caskeleton.messaging.outbox.OutboxRetryScheduler; -import dev.caskeleton.messaging.reliability.InboxRepository; -import dev.caskeleton.messaging.reliability.OutboxRepository; -import java.time.Duration; -import org.springframework.boot.autoconfigure.condition.ConditionalOnBean; -import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; -import org.springframework.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; - -/** - * Wires the outbox and inbox operational beans. - * - *

Every bean here is conditional on the application having supplied the corresponding - * repository. The platform cannot provide those: they write inside the application's own - * transaction, against the application's own datasource, and a default implementation would - * silently write to the wrong place — or to nowhere at all, which is worse because the outbox would - * look healthy while nothing was ever staged. - * - *

The cleanup jobs are beans but no scheduler is registered for them. Scheduling is the - * application's decision: a service running several replicas usually wants one of them to run - * cleanup, and auto-registering a fixed-rate task would have every replica delete the same rows. - * - *

The relay is the opposite case and is driven here. Its claims are fenced by owner and token - * under {@code SKIP LOCKED}, so every replica running one is safe, while nobody running one is a - * table that fills up behind a business transaction that reported success. - */ -@Configuration(proxyBeanMethods = false) -public class MessagingReliabilityAutoConfiguration { - - /** - * Returns the relay's operational settings. - * - * @return the outbox properties - */ - @Bean - @ConditionalOnMissingBean - public OutboxProperties outboxProperties() { - return OutboxProperties.defaults(); - } - - /** - * Returns the relay pass scheduler. - * - * @param properties the relay settings - * @return the scheduler - */ - @Bean - @ConditionalOnMissingBean - public OutboxRetryScheduler outboxRetryScheduler(OutboxProperties properties) { - return new OutboxRetryScheduler(properties, Duration.ofMinutes(1)); - } - - /** - * Returns the relay, when the application supplied the two things only it can supply. - * - *

The repository writes inside the application's transaction and the envelope factory carries - * the application's producer identity; the platform can invent neither, and a default for either - * would publish from the wrong place under the wrong name. - * - * @param outbox the application's outbox repository - * @param publisher the platform publisher - * @param envelopes rebuilds envelopes from rows - * @param properties the relay settings - * @param scheduler the retry policy - * @return the relay - */ - @Bean - @ConditionalOnBean({OutboxRepository.class, OutboxEnvelopeFactory.class}) - @ConditionalOnMissingBean - public OutboxRelay outboxRelay( - OutboxRepository outbox, - MessagePublisher publisher, - OutboxEnvelopeFactory envelopes, - OutboxProperties properties, - OutboxRetryScheduler scheduler) { - return new OutboxRelay( - outbox, - publisher, - envelopes, - properties.batchSize(), - properties.leaseDuration(), - scheduler); - } - - /** - * Returns the worker that runs relay passes. - * - * @param relay the relay to drive - * @param scheduler the policy deciding when the next pass runs - * @return the worker - */ - @Bean - @ConditionalOnBean(OutboxRelay.class) - @ConditionalOnMissingBean - public OutboxRelayWorker outboxRelayWorker(OutboxRelay relay, OutboxRetryScheduler scheduler) { - return new OutboxRelayWorker(relay, scheduler); - } - - /** - * Publishes the relay's failed-pass count when a meter registry exists. - * - *

{@code failedPasses()} was counted and read by nothing, so a relay failing every pass looked - * on every dashboard exactly like one with nothing to do. - * - * @param worker the relay worker - * @param registries the meter registry, when the application has one - * @return the registration, run once the context has the registry - */ - @Bean - @ConditionalOnBean(OutboxRelayWorker.class) - public org.springframework.beans.factory.InitializingBean outboxRelayMeters( - OutboxRelayWorker worker, - org.springframework.beans.factory.ObjectProvider - registries) { - return () -> - registries.ifAvailable( - registry -> - io.micrometer.core.instrument.FunctionCounter.builder( - "messaging.outbox.relay.failed.passes", - worker, - OutboxRelayWorker::failedPasses) - .description("Outbox relay passes that ended in an exception") - .register(registry)); - } - - /** - * Binds the relay worker to the context lifecycle. - * - *

The drain budget is the lease duration: a pass holds its claims for at most that long, so - * waiting longer proves nothing that waiting that long has not already proved. - * - * @param worker the relay worker - * @param properties the relay settings supplying the lease duration - * @return the lifecycle - */ - @Bean - @ConditionalOnBean(OutboxRelayWorker.class) - @ConditionalOnMissingBean - public MessagingOutboxRelayLifecycle outboxRelayLifecycle( - OutboxRelayWorker worker, OutboxProperties properties) { - return new MessagingOutboxRelayLifecycle(worker, properties.leaseDuration()); - } - - /** - * Returns the outbox cleanup job. - * - * @param outbox the application's outbox repository - * @param properties the relay settings supplying the retention - * @return the cleanup job - */ - @Bean - @ConditionalOnBean(OutboxRepository.class) - @ConditionalOnMissingBean - public OutboxCleanupJob outboxCleanupJob(OutboxRepository outbox, OutboxProperties properties) { - return new OutboxCleanupJob(outbox, properties, 20); - } - - /** - * Returns the inbox retention policy. - * - *

The redelivery window defaults to one day, which suits a broker retaining a day of log. A - * deployment whose broker retains longer must override this bean — the policy validates itself, - * so an unsafe combination fails at startup rather than duplicating a side effect later. - * - * @return the retention policy - */ - @Bean - @ConditionalOnMissingBean - public InboxRetentionPolicy inboxRetentionPolicy() { - return new InboxRetentionPolicy(InboxRetentionPolicy.DEFAULT_RETENTION, Duration.ofDays(1)); - } - - /** - * Returns the inbox runner that {@code INBOX_TRANSACTIONAL} destinations wrap their handlers in - * ({@link MessagingConsumeConfiguration}). - * - *

Assembled from the two parts the platform cannot supply itself, like every bean here: the - * application's inbox repository and the runner that opens the application's transaction, so the - * reservation and the handler's side effect commit or roll back together. Without both, an {@code - * INBOX_TRANSACTIONAL} destination still refuses to start. - * - * @param inbox the application's inbox repository - * @param transactions runs work in the application's transaction - * @return the idempotent consumer - */ - @Bean - @ConditionalOnBean({InboxRepository.class, IdempotentConsumer.TransactionRunner.class}) - @ConditionalOnMissingBean - public IdempotentConsumer idempotentConsumer( - InboxRepository inbox, IdempotentConsumer.TransactionRunner transactions) { - return new IdempotentConsumer(inbox, transactions); - } - - /** - * Returns the inbox cleanup job. - * - * @param inbox the application's inbox repository - * @param policy the retention policy - * @return the cleanup job - */ - @Bean - @ConditionalOnBean(InboxRepository.class) - @ConditionalOnMissingBean - public InboxCleanupJob inboxCleanupJob(InboxRepository inbox, InboxRetentionPolicy policy) { - return new InboxCleanupJob(inbox, policy, 20); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingSettings.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingSettings.java deleted file mode 100644 index 9985b6e3..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingSettings.java +++ /dev/null @@ -1,190 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import java.time.Duration; -import java.util.LinkedHashMap; -import java.util.Map; -import org.springframework.boot.context.properties.ConfigurationProperties; - -/** - * The platform's bound configuration. - * - *

Bound under {@code app.messaging}, which is the prefix the deployed runtime and the {@code - * APP_MESSAGING_*} environment variables already use. There were three namespaces: this binder read - * {@code backend.messaging}, the existing runtime settings read {@code app.messaging}, and the - * configuration reference documented a bare {@code messaging}. Two of the three bound nothing, so a - * deployment configured from the documentation changed no behaviour at all and nothing reported a - * problem. - * - *

{@code backend.messaging} is refused rather than quietly accepted as an alias — see {@link - * MessagingPrefixMigrationValidator}. An alias that works is a fourth thing to keep in sync, and - * the failure it prevents (a deployment split across two prefixes, each half-configuring the - * platform) is worse than an actionable startup error. - * - *

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 - * had to arrive as beans an application wrote in Java, and the documented keys were inert text. - * {@link MessagingConfigurationCompiler} turns them into those same profiles, so the documented - * shape is now the working shape. - * - *

The maps are ordered. Configuration errors name the entry that caused them, and an operator - * reading a startup failure against a file they wrote should meet the entries in the order they - * wrote them rather than in hash order. - */ -@ConfigurationProperties(prefix = MessagingSettings.PREFIX) -public class MessagingSettings { - - /** The one configuration prefix this platform binds. */ - public static final String PREFIX = "app.messaging"; - - /** The prefix this binder used to read, kept only so the migration error can name it. */ - public static final String SUPERSEDED_PREFIX = "backend.messaging"; - - /** The prefix the configuration reference documented, which nothing ever bound. */ - public static final String DOCUMENTED_PREFIX = "messaging"; - - private final Backpressure backpressure = new Backpressure(); - private final Shutdown shutdown = new Shutdown(); - private Map destinations = new LinkedHashMap<>(); - private Map brokers = new LinkedHashMap<>(); - private Map security = new LinkedHashMap<>(); - - /** - * Returns the declared destinations, keyed by logical name. - * - * @return the destination settings - */ - public Map getDestinations() { - return destinations; - } - - /** - * Sets the declared destinations. - * - * @param destinations the destination settings, keyed by logical name - */ - public void setDestinations(Map destinations) { - this.destinations = new LinkedHashMap<>(destinations); - } - - /** - * Returns the declared brokers, keyed by logical name. - * - * @return the broker settings - */ - public Map getBrokers() { - return brokers; - } - - /** - * Sets the declared brokers. - * - * @param brokers the broker settings, keyed by logical name - */ - public void setBrokers(Map brokers) { - this.brokers = new LinkedHashMap<>(brokers); - } - - /** - * Returns the declared broker security profiles, keyed by broker name. - * - * @return the security settings - */ - public Map getSecurity() { - return security; - } - - /** - * Sets the declared broker security profiles. - * - * @param security the security settings, keyed by broker name - */ - public void setSecurity(Map security) { - this.security = new LinkedHashMap<>(security); - } - - /** - * Returns the backpressure limits. - * - * @return the backpressure settings - */ - public Backpressure getBackpressure() { - return backpressure; - } - - /** - * Returns the shutdown settings. - * - * @return the shutdown settings - */ - public Shutdown getShutdown() { - return shutdown; - } - - /** In-flight limits. */ - public static class Backpressure { - - private int globalLimit = 512; - private int perDestinationLimit = 64; - - /** - * Returns the process-wide in-flight ceiling. - * - * @return the global limit - */ - public int getGlobalLimit() { - return globalLimit; - } - - /** - * Sets the process-wide in-flight ceiling. - * - * @param globalLimit the global limit - */ - public void setGlobalLimit(int globalLimit) { - this.globalLimit = globalLimit; - } - - /** - * Returns the per-destination in-flight ceiling. - * - * @return the per-destination limit - */ - public int getPerDestinationLimit() { - return perDestinationLimit; - } - - /** - * Sets the per-destination in-flight ceiling. - * - * @param perDestinationLimit the per-destination limit - */ - public void setPerDestinationLimit(int perDestinationLimit) { - this.perDestinationLimit = perDestinationLimit; - } - } - - /** Graceful shutdown settings. */ - public static class Shutdown { - - private Duration drainDeadline = Duration.ofSeconds(30); - - /** - * Returns how long a drain waits for in-flight work. - * - * @return the drain deadline - */ - public Duration getDrainDeadline() { - return drainDeadline; - } - - /** - * Sets how long a drain waits for in-flight work. - * - * @param drainDeadline the drain deadline - */ - public void setDrainDeadline(Duration drainDeadline) { - this.drainDeadline = drainDeadline; - } - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingShutdownLifecycle.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingShutdownLifecycle.java deleted file mode 100644 index 147c2661..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingShutdownLifecycle.java +++ /dev/null @@ -1,134 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.policy.MessagingAdmissionController; -import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator; -import java.time.Duration; -import java.time.Instant; -import java.util.Objects; -import java.util.concurrent.atomic.AtomicBoolean; -import java.util.function.Supplier; -import org.springframework.context.SmartLifecycle; - -/** - * Runs the platform's shutdown phases in order when the context stops. - * - *

The admission controller and the drain coordinator were beans nobody drove. Both could refuse - * new work and wait for in-flight work, and neither was ever asked to: a context shutdown went - * straight to closing beans while publishes were still in flight and handlers were still between - * their side effect and their settlement, which is the shape that turns a deploy into duplicated - * effects and unexplained ambiguous publishes. - * - *

The order is admission first, drain second. Reversed, the drain waits for a count that new - * work keeps topping up, so it either never finishes or finishes only because the deadline passed — - * and work abandoned at the deadline is redelivered rather than completed. - * - *

The wait is bounded by the same drain deadline the runtime registry uses. A handler that never - * returns must not hold the process open; what is still running when the deadline passes is left - * unsettled on purpose, so the broker redelivers it instead of the platform recording a completion - * it cannot prove. - */ -public final class MessagingShutdownLifecycle implements SmartLifecycle { - - /** - * The phase this drain stops in: {@link #getPhase()}. Public so a relay outside the platform — a - * publisher whose production code may not name this type — can be held above it by a test that - * does name it. - */ - public static final int PHASE = Integer.MAX_VALUE - 1024; - - /** How often the drain is re-checked. Short enough that a fast drain is not padded. */ - private static final Duration POLL = Duration.ofMillis(50); - - private final MessagingAdmissionController admission; - - private final GracefulShutdownCoordinator drain; - - private final Duration drainDeadline; - - private final Supplier clock; - - private final AtomicBoolean running = new AtomicBoolean(); - - /** - * Creates the lifecycle. - * - * @param admission the publish admission gate - * @param drain the in-flight work coordinator - * @param drainDeadline how long in-flight work may take - */ - public MessagingShutdownLifecycle( - MessagingAdmissionController admission, - GracefulShutdownCoordinator drain, - Duration drainDeadline) { - this(admission, drain, drainDeadline, Instant::now); - } - - /** - * Creates the lifecycle with an explicit clock, so the deadline is testable without sleeping. - * - * @param admission the publish admission gate - * @param drain the in-flight work coordinator - * @param drainDeadline how long in-flight work may take - * @param clock the source of the current instant - */ - public MessagingShutdownLifecycle( - MessagingAdmissionController admission, - GracefulShutdownCoordinator drain, - Duration drainDeadline, - Supplier clock) { - this.admission = Objects.requireNonNull(admission, "admission must not be null"); - this.drain = Objects.requireNonNull(drain, "drain must not be null"); - this.drainDeadline = Objects.requireNonNull(drainDeadline, "drainDeadline must not be null"); - this.clock = Objects.requireNonNull(clock, "clock must not be null"); - } - - @Override - public void start() { - running.set(true); - } - - @Override - public void stop() { - if (!running.compareAndSet(true, false)) { - return; - } - admission.stopAcceptingNewWork(); - Instant startedAt = clock.get(); - drain.beginDrain(startedAt); - Instant deadline = startedAt.plus(drainDeadline); - while (!drain.isDrained(clock.get()) && clock.get().isBefore(deadline)) { - try { - Thread.sleep(POLL.toMillis()); - } catch (InterruptedException interrupted) { - // The interrupt is the signal to stop waiting, not a reason to lose it: the phases below - // still have to run, and a swallowed interrupt leaves the shutdown thread looking healthy. - Thread.currentThread().interrupt(); - return; - } - } - } - - @Override - public boolean isRunning() { - return running.get(); - } - - /** - * Stops after the producers of work and before the beans that own broker connections. - * - *

{@code SmartLifecycle} stops in descending phase order. A phase above the default puts this - * drain ahead of the transports it is draining, because closing a connection first would strand - * the settlements the drain exists to flush. It sits below the outbox relays' phase for the - * mirror-image reason: refusing admission while a relay pass is mid-publish turns that pass's - * rows into refusals. The platform's own relay ({@code MessagingOutboxRelayLifecycle}, built only - * when a platform outbox repository exists) stands above it, and so must any relay outside the - * platform that publishes through it: a phase above {@link #PHASE}, finishing the publish it is - * in before this phase runs. - * - * @return the lifecycle phase, {@link #PHASE} - */ - @Override - public int getPhase() { - return PHASE; - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingValidationConfiguration.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingValidationConfiguration.java deleted file mode 100644 index 0d6a60a7..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingValidationConfiguration.java +++ /dev/null @@ -1,194 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.policy.DestinationProfileValidator; -import dev.caskeleton.messaging.security.BrokerTlsPolicy; -import dev.caskeleton.messaging.security.CredentialProvider; -import dev.caskeleton.messaging.security.CredentialRuntimeRegistry; -import dev.caskeleton.messaging.security.MessageSecurityValidator; -import java.util.List; -import org.springframework.beans.factory.ObjectProvider; -import org.springframework.boot.autoconfigure.condition.ConditionalOnBean; -import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; -import org.springframework.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; - -/** - * Compiles and validates the messaging configuration, and fails the context when it is - * contradictory. - * - *

Destination profiles are validated at context refresh through a bean that fails to construct - * when the registry is contradictory. Startup failure is the point: a profile that promises ordered - * delivery while configuring a reordering retry does not fail on the happy path, it fails months - * later on the first retry, looking like a data bug rather than a configuration one. - * - *

One of the three parts {@link MessagingCoreAutoConfiguration} used to be in a single class - * (S7-#9a): configuration and validation here, the publish pipeline in {@link - * MessagingPublishConfiguration}, observability in {@link MessagingObservabilityConfiguration}. - */ -@Configuration(proxyBeanMethods = false) -public class MessagingValidationConfiguration { - - /** - * Fails the context when a production broker profile has no credential source. - * - *

One actionable error instead of a missing-bean message naming an internal registry type. - */ - @Bean - public MessagingCredentialRequirementValidator messagingCredentialRequirementValidator( - org.springframework.beans.factory.ObjectProvider< - dev.caskeleton.messaging.security.BrokerSecurityProfile> - profiles, - CompiledMessagingConfiguration compiled, - org.springframework.beans.factory.ObjectProvider< - dev.caskeleton.messaging.security.CredentialProvider> - credentials, - org.springframework.core.env.Environment environment) { - return new MessagingCredentialRequirementValidator( - profiles, compiled.security(), credentials, environment); - } - - /** - * Fails the context when configuration uses a prefix nothing binds. - * - *

Registered here rather than left to review because the failure it catches is silent: a key - * under {@code backend.messaging} or a bare {@code messaging} looks configured and does nothing. - */ - @Bean - public MessagingPrefixMigrationValidator messagingPrefixMigrationValidator( - org.springframework.core.env.ConfigurableEnvironment environment) { - return new MessagingPrefixMigrationValidator(environment); - } - - /** - * Compiles {@code app.messaging.destinations}, {@code .brokers} and {@code .security} into the - * platform's own profile objects. - * - *

Separate from the registry bean so that a configuration error fails while compiling, with - * the offending key in the message, rather than later as a validation failure over an object - * whose origin the operator then has to work out. - * - * @param settings the bound configuration - * @return the compiled profiles - */ - @Bean - @ConditionalOnMissingBean - public CompiledMessagingConfiguration compiledMessagingConfiguration(MessagingSettings settings) { - return new MessagingConfigurationCompiler(settings).compile(); - } - - /** - * Refuses a key under the platform's own sections that nothing binds. - * - *

Registered here rather than left to review because a misspelt key inside a bound section is - * silent in a way a misspelt prefix is not: the section binds, the entry appears, and the one - * setting the operator came to change is the one that did not take. - * - * @param environment the resolved environment - * @return the key validator - */ - @Bean - @ConditionalOnMissingBean - public MessagingConfigurationKeyValidator messagingConfigurationKeyValidator( - org.springframework.core.env.ConfigurableEnvironment environment) { - return new MessagingConfigurationKeyValidator(environment); - } - - /** - * Validates every registered destination profile at startup. - * - *

Returns a marker rather than a service because its only job is to fail the context when the - * registry is inconsistent. - * - *

Configured profiles and bean-declared ones are merged before validation, not after, because - * the rules that matter most across a registry — a dead letter destination that exists, a retry - * graph with no cycle — are questions about the whole set. Validating the two halves separately - * would pass a deployment whose configured destination dead-letters into a bean-declared one that - * points back. - * - * @param profiles the profiles the application declared as beans - * @param compiled the profiles compiled from configuration - * @return the validated registry - */ - @Bean - @ConditionalOnMissingBean - public ValidatedDestinationRegistry validatedDestinationRegistry( - ObjectProvider profiles, CompiledMessagingConfiguration compiled) { - List registered = - java.util.stream.Stream.concat(compiled.destinations().stream(), profiles.orderedStream()) - .toList(); - new DestinationProfileValidator().validateAll(registered); - return new ValidatedDestinationRegistry(registered); - } - - /** - * Returns the destination profile validator. - * - * @return the validator - */ - @Bean - @ConditionalOnMissingBean - public DestinationProfileValidator destinationProfileValidator() { - return new DestinationProfileValidator(); - } - - /** - * Returns the broker security validator. - * - * @return the validator - */ - @Bean - @ConditionalOnMissingBean - public MessageSecurityValidator messageSecurityValidator() { - return new MessageSecurityValidator(); - } - - /** - * Runs the security validator over every broker security profile, declared or configured. - * - * @param profiles the security profiles the application declared as beans - * @param compiled the security profiles compiled from configuration - * @param validator the security validator - * @return the startup validation - */ - @Bean - public StartupProfileValidation - brokerSecurityStartupValidation( - ObjectProvider profiles, - CompiledMessagingConfiguration compiled, - MessageSecurityValidator validator) { - return new StartupProfileValidation<>( - () -> - java.util.stream.Stream.concat(compiled.security().stream(), profiles.orderedStream()) - .toList(), - validator::validate); - } - - /** - * Returns the credential runtime registry, when the application supplied a credential provider. - * - *

Conditional on the provider because there is no safe default: a registry with no source - * would resolve nothing, and the adapters would connect with whatever their client's defaults - * are. - * - * @param provider the application's credential source - * @return the credential runtime registry - */ - @Bean - @ConditionalOnBean(CredentialProvider.class) - @ConditionalOnMissingBean - public CredentialRuntimeRegistry credentialRuntimeRegistry(CredentialProvider provider) { - return new CredentialRuntimeRegistry(provider); - } - - /** - * Returns the transport security policy. - * - * @return the TLS policy - */ - @Bean - @ConditionalOnMissingBean - public BrokerTlsPolicy brokerTlsPolicy() { - return new BrokerTlsPolicy(); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/StartupProfileValidation.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/StartupProfileValidation.java deleted file mode 100644 index 47dc4e71..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/StartupProfileValidation.java +++ /dev/null @@ -1,46 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import java.util.List; -import java.util.Objects; -import java.util.function.Consumer; -import java.util.function.Supplier; -import org.springframework.beans.factory.InitializingBean; - -/** - * Applies one profile validator to every profile of its kind at startup. - * - *

The Kafka, RabbitMQ and security validators were all beans and none of them was injected - * anywhere: the context published a validator per broker and validated nothing. A profile that - * promises a guarantee its broker cannot give — an exactly-once claim on a non-transactional - * producer, a quorum ack on a single replica, a plaintext credential on a production listener — - * then boots cleanly and fails on the first message that depends on it, which is the wrong place to - * find out. - * - *

Validation runs as {@code afterPropertiesSet} rather than on an application event, so the - * failure happens while the context is still being built and the profile bean that caused it is - * named in the stack. - * - *

The profiles arrive through a supplier rather than an {@code ObjectProvider} because there are - * now two sources of them — beans an application declares and profiles compiled from {@code - * app.messaging} — and a validator that saw only one of the two would leave the other half of a - * deployment's configuration unchecked. Which half went unchecked would depend on how the - * deployment happened to be written, which is the worst possible rule. - * - * @param the profile type this instance validates - */ -final class StartupProfileValidation implements InitializingBean { - - private final Supplier> profiles; - - private final Consumer validator; - - StartupProfileValidation(Supplier> profiles, Consumer validator) { - this.profiles = Objects.requireNonNull(profiles, "profiles must not be null"); - this.validator = Objects.requireNonNull(validator, "validator must not be null"); - } - - @Override - public void afterPropertiesSet() { - profiles.get().forEach(validator); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/ValidatedDestinationRegistry.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/ValidatedDestinationRegistry.java deleted file mode 100644 index ebb66283..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/ValidatedDestinationRegistry.java +++ /dev/null @@ -1,59 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.policy.DestinationProfile; -import java.util.LinkedHashMap; -import java.util.List; -import java.util.Map; -import java.util.Objects; - -/** - * The registry of destination profiles that passed startup validation. - * - *

Constructing this bean is what proves the registry is coherent; nothing downstream - * re-validates it. Resolving an unregistered destination is a configuration failure rather than an - * empty {@code Optional}, because a publish to a destination nobody declared has no profile, no - * limits, and no dead letter route. - */ -public final class ValidatedDestinationRegistry { - - private final Map byName; - - /** - * Creates a registry over validated profiles. - * - * @param profiles the validated profiles - */ - public ValidatedDestinationRegistry(List profiles) { - Objects.requireNonNull(profiles, "profiles must not be null"); - Map registry = new LinkedHashMap<>(); - profiles.forEach(profile -> registry.put(profile.name(), profile)); - this.byName = Map.copyOf(registry); - } - - /** - * Resolves a destination profile. - * - * @param destination the logical destination - * @return the profile - */ - public DestinationProfile require(DestinationName destination) { - DestinationProfile profile = byName.get(destination); - if (profile == null) { - throw new MessagingConfigurationException( - "DESTINATION_NOT_REGISTERED", - "no destination profile is registered for " + destination.value()); - } - return profile; - } - - /** - * Returns every registered profile. - * - * @return the profiles, keyed by logical name - */ - public Map all() { - return byName; - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports b/src/platforms/messaging/messaging-spring-boot-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports deleted file mode 100644 index 2c270cde..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports +++ /dev/null @@ -1 +0,0 @@ -dev.caskeleton.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/BrokerAccessListTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/BrokerAccessListTest.java deleted file mode 100644 index 936c7108..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/BrokerAccessListTest.java +++ /dev/null @@ -1,102 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -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.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import java.time.Instant; -import java.util.Optional; -import org.junit.jupiter.api.Test; -import org.springframework.boot.autoconfigure.AutoConfigurations; -import org.springframework.boot.test.context.runner.ApplicationContextRunner; - -/** - * The broker's {@code access.publishable} list is enforced by the publish path, not only compiled. - * - *

The list was bound, validated and turned into a {@code DestinationAccessPolicy} that nothing - * read: the publisher's access check was built from the declared destinations alone, so a - * destination the security entry left out was published to anyway. - */ -class BrokerAccessListTest { - - private final ApplicationContextRunner runner = - new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingPlatformRootAutoConfiguration.class)) - .withUserConfiguration(KafkaProducerSecurityTest.Credentials.class) - .withPropertyValues( - "app.messaging.enabled=true", - "app.messaging.broker=kafka", - "app.messaging.brokers.kafka-primary.type=kafka", - "app.messaging.brokers.kafka-primary.bootstrap-servers[0]=localhost:9092", - "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", - "app.messaging.security.kafka-primary.access.publishable[0]=order-events") - .withPropertyValues(destination("order-events")) - .withPropertyValues(destination("audit-events")); - - @Test - void aDeclaredDestinationTheSecurityEntryDoesNotListIsRejectedAsForbidden() { - runner.run( - context -> { - // given - MessagePublisher publisher = context.getBean(MessagePublisher.class); - - // when - PublishResult result = publish(publisher, "audit-events"); - - // then - assertThat(result.failure().map(FailureDescriptor::code)).contains("PUBLISH_FORBIDDEN"); - }); - } - - private static PublishResult publish(MessagePublisher publisher, String destination) { - return publisher - .publish( - new MessageDestination<>( - new DestinationName(destination), new MessageType("order.created"), String.class), - new MessageEnvelope<>( - MessageId.newId(), - new MessageType("order.created"), - new SchemaVersion(1), - Instant.parse("2026-09-25T00:00:00Z"), - Optional.empty(), - new ProducerId("orders"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - "{}"), - PublishOptions.defaults()) - .toCompletableFuture() - .join(); - } - - private static String[] destination(String name) { - String prefix = "app.messaging.destinations." + name + "."; - return new String[] { - prefix + "broker=kafka-primary", - prefix + "kind=EVENT_STREAM", - prefix + "physical.topic=" + name, - prefix + "schema.message-types[0]=order.created", - prefix + "guarantees.delivery=AT_MOST_ONCE", - }; - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerConfigTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerConfigTest.java deleted file mode 100644 index 0340c8aa..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerConfigTest.java +++ /dev/null @@ -1,97 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.kafka.KafkaSecurityConfigurer; -import dev.caskeleton.messaging.security.BrokerSecurityProfile; -import java.util.Map; -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; - -/** - * Where the producer connects and how it delivers come from the one broker entry. - * - *

The producer read {@code spring.kafka.bootstrap-servers} while the compiler required and - * validated {@code app.messaging.brokers..bootstrap-servers}, so a broker was described twice - * and only one description was used. The entry's delivery settings were validated and then replaced - * by hard-coded values. - */ -class KafkaProducerConfigTest { - - private final ApplicationContextRunner runner = - new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingPlatformRootAutoConfiguration.class)) - .withPropertyValues( - "app.messaging.enabled=true", - "app.messaging.broker=kafka", - "app.messaging.brokers.kafka-primary.type=kafka", - // Resolvable names: the client refuses an address it cannot look up at construction. - "app.messaging.brokers.kafka-primary.bootstrap-servers[0]=localhost:9093", - "app.messaging.brokers.kafka-primary.bootstrap-servers[1]=127.0.0.1:9094"); - - @Test - void theProducerConnectsToTheBrokerEntryAddressesNotToSpringKafka() { - runner - .withPropertyValues("spring.kafka.bootstrap-servers=elsewhere:9092") - .run( - context -> - assertThat(producerConfig(context).get("bootstrap.servers")) - .isEqualTo("localhost:9093,127.0.0.1:9094")); - } - - @Test - void theProducerAppliesTheBrokerEntryDeliverySettings() { - runner - .withPropertyValues( - "app.messaging.brokers.kafka-primary.enable-idempotence=false", - "app.messaging.brokers.kafka-primary.acks=1", - "app.messaging.brokers.kafka-primary.max-in-flight-requests-per-connection=3", - "app.messaging.brokers.kafka-primary.delivery-timeout=45s") - .run( - context -> - assertThat(producerConfig(context)) - .extractingByKeys( - "enable.idempotence", - "acks", - "max.in.flight.requests.per.connection", - "delivery.timeout.ms") - .containsExactly(false, "1", 3, 45_000)); - } - - @Test - void theProducerStopsWaitingForMetadataWithinTheDefaultPublishDeadline() { - runner.run( - context -> - assertThat(producerConfig(context).get("max.block.ms")) - .as("the caller's thread waited up to Kafka's own 60s before any deadline applied") - .isEqualTo(PublishOptions.defaults().timeout().toMillis())); - } - - @Test - void aBrokerWithoutAnEntryFailsStartupNamingTheKey() { - new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingPlatformRootAutoConfiguration.class)) - .withPropertyValues( - "app.messaging.enabled=true", - "app.messaging.broker=kafka", - "spring.kafka.bootstrap-servers=localhost:9092") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .rootCause() - .hasMessageContaining("app.messaging.brokers. entry with type kafka")); - } - - private static Map producerConfig(AssertableApplicationContext context) { - return KafkaMessagingAutoConfiguration.producerConfig( - context.getBean(CompiledMessagingConfiguration.class), - context.getBean(KafkaBrokerCatalog.class), - context.getBeanProvider(BrokerSecurityProfile.class), - context.getBeanProvider(KafkaSecurityConfigurer.class)); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java deleted file mode 100644 index cfca0829..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java +++ /dev/null @@ -1,328 +0,0 @@ -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.List; -import java.util.Map; -import java.util.Optional; -import java.util.concurrent.atomic.AtomicReference; -import javax.security.auth.callback.Callback; -import javax.security.auth.callback.NameCallback; -import javax.security.auth.callback.PasswordCallback; -import org.apache.kafka.common.security.auth.AuthenticateCallbackHandler; -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", - "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", - }; - - private static final String[] MUTUAL_TLS_CREDENTIALS = { - "app.messaging.brokers.kafka-primary.tls-enabled=true", - "app.messaging.security.kafka-primary.producer.type=MUTUAL_TLS", - "app.messaging.security.kafka-primary.producer.credential-id=kafka-producer-tls", - "app.messaging.security.kafka-primary.producer.key-store.location=/etc/kafka/producer.p12", - "app.messaging.security.kafka-primary.consumer.type=MUTUAL_TLS", - "app.messaging.security.kafka-primary.consumer.credential-id=kafka-consumer-tls", - "app.messaging.security.kafka-primary.consumer.key-store.location=/etc/kafka/consumer.p12", - }; - - @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 theProducerAuthenticatesAsTheUsernameTheProviderReturnsNotAsTheCredentialId() { - runner - .withUserConfiguration(Credentials.class) - .withPropertyValues(SCRAM_CREDENTIALS) - .withPropertyValues("app.messaging.brokers.kafka-primary.tls-enabled=true") - .run( - context -> { - // given - Map config = producerConfig(context); - - // when - Answer answer = authenticate(config); - - // then - assertThat(answer).isEqualTo(new Answer(Credentials.USERNAME, Credentials.SECRET)); - }); - } - - @Test - void aRotatedPasswordReachesTheNextAuthenticationWithoutRebuildingTheProducer() { - runner - .withUserConfiguration(RotatingCredentials.class) - .withPropertyValues(SCRAM_CREDENTIALS) - .withPropertyValues("app.messaging.brokers.kafka-primary.tls-enabled=true") - .run( - context -> { - // given - Map config = producerConfig(context); - RotatingCredentials.CURRENT.set("rotated-secret"); - - // when - Answer answer = authenticate(config); - - // then - assertThat(answer.password()).isEqualTo("rotated-secret"); - }); - } - - @Test - void aPrivateCaTrustStoreReachesTheProducer() { - runner - .withUserConfiguration(Credentials.class, StoreFilesAbsent.class) - .withPropertyValues(SCRAM_CREDENTIALS) - .withPropertyValues( - "app.messaging.brokers.kafka-primary.tls-enabled=true", - "app.messaging.security.kafka-primary.trust-store.location=/etc/kafka/private-ca.p12", - "app.messaging.security.kafka-primary.trust-store.password-credential-id=kafka-trust") - .run( - context -> - assertThat(producerConfig(context)) - .extractingByKeys( - "ssl.truststore.location", "ssl.truststore.type", "ssl.truststore.password") - .containsExactly("/etc/kafka/private-ca.p12", "PKCS12", Credentials.SECRET)); - } - - @Test - void mutualTlsPresentsTheProducerKeyStoreUnlockedByItsCredential() { - runner - .withUserConfiguration(Credentials.class, StoreFilesAbsent.class) - .withPropertyValues(MUTUAL_TLS_CREDENTIALS) - .run( - context -> - assertThat(producerConfig(context)) - .extractingByKeys( - "security.protocol", - "ssl.keystore.location", - "ssl.keystore.type", - "ssl.keystore.password") - .containsExactly( - "SSL", "/etc/kafka/producer.p12", "PKCS12", Credentials.SECRET)); - } - - @Test - void mutualTlsWithoutAKeyStoreFailsStartupNamingTheKey() { - runner - .withUserConfiguration(Credentials.class) - .withPropertyValues(MUTUAL_TLS_CREDENTIALS) - .withPropertyValues("app.messaging.security.kafka-primary.producer.key-store.location=") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .as("a client certificate nobody configured cannot be presented") - .hasMessageContaining( - "app.messaging.security.kafka-primary.producer.key-store: MUTUAL_TLS")); - } - - @Test - void mutualTlsOnABrokerWithoutTlsFailsStartup() { - runner - .withUserConfiguration(Credentials.class) - .withPropertyValues(MUTUAL_TLS_CREDENTIALS) - .withPropertyValues("app.messaging.brokers.kafka-primary.tls-enabled=false") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .as("a certificate only authenticates inside a TLS handshake") - .hasMessageContaining("authenticates with a client certificate but does not")); - } - - @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.getBean(CompiledMessagingConfiguration.class), - context.getBean(KafkaBrokerCatalog.class), - context.getBeanProvider(BrokerSecurityProfile.class), - context.getBeanProvider(KafkaSecurityConfigurer.class)); - } - - /** What a SASL client is told when it asks for a name and a password. */ - private record Answer(String name, String password) {} - - /** - * Authenticates the way Kafka's SASL client does: instantiate the configured handler class, - * configure it with the client's own configuration, then ask it for a name and a password. - */ - private static Answer authenticate(Map config) throws Exception { - assertThat(config).containsKey("sasl.client.callback.handler.class"); - Class type = (Class) config.get("sasl.client.callback.handler.class"); - AuthenticateCallbackHandler handler = - (AuthenticateCallbackHandler) type.getDeclaredConstructor().newInstance(); - handler.configure(config, String.valueOf(config.get("sasl.mechanism")), List.of()); - NameCallback name = new NameCallback("name"); - PasswordCallback password = new PasswordCallback("password", false); - handler.handle(new Callback[] {name, password}); - handler.close(); - return new Answer(name.getName(), new String(password.getPassword())); - } - - /** A credential source that answers every id with the same test principal and secret. */ - @Configuration(proxyBeanMethods = false) - static class Credentials { - - static final String SECRET = "test-only-secret"; - - static final String USERNAME = "svc-orders"; - - @Bean - CredentialProvider credentialProvider() { - return new CredentialProvider() { - @Override - public char[] resolve(String credentialId) { - return SECRET.toCharArray(); - } - - @Override - public Optional expiresAt(String credentialId) { - return Optional.empty(); - } - - @Override - public Optional username(String credentialId) { - return Optional.of(USERNAME); - } - }; - } - } - - /** - * Stands in for the producer when the store paths in a test name no real file. - * - *

A real producer opens its key and trust stores while it is constructed, so a path that does - * not exist fails startup — which is the behaviour a deployment wants, and not what these tests - * are about. They read the configuration the producer would have been built from. - */ - @Configuration(proxyBeanMethods = false) - static class StoreFilesAbsent { - - @Bean - org.apache.kafka.clients.producer.Producer messagingKafkaProducer() { - return new org.apache.kafka.clients.producer.MockProducer<>(); - } - } - - /** A credential store whose secret has already expired, so every resolution reads it again. */ - @Configuration(proxyBeanMethods = false) - static class RotatingCredentials { - - static final AtomicReference CURRENT = new AtomicReference<>("first-secret"); - - @Bean - CredentialProvider credentialProvider() { - CURRENT.set("first-secret"); - return new CredentialProvider() { - @Override - public char[] resolve(String credentialId) { - return CURRENT.get().toCharArray(); - } - - @Override - public Optional expiresAt(String credentialId) { - return Optional.of(Instant.EPOCH); - } - - @Override - public Optional username(String credentialId) { - return Optional.of(Credentials.USERNAME); - } - }; - } - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingAutoConfigurationTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingAutoConfigurationTest.java deleted file mode 100644 index d3c02ea6..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingAutoConfigurationTest.java +++ /dev/null @@ -1,615 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageEnvelope; -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.destination.MessageDestination; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.policy.ApiTier; -import dev.caskeleton.messaging.policy.ConsumerPolicy; -import dev.caskeleton.messaging.policy.DeadLetterPolicy; -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.policy.MessagingAdmissionController; -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 dev.caskeleton.messaging.transport.GracefulShutdownCoordinator; -import java.util.Set; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import org.junit.jupiter.api.Test; -import org.springframework.boot.autoconfigure.AutoConfigurations; -import org.springframework.boot.test.context.runner.ApplicationContextRunner; -import org.springframework.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; - -class MessagingAutoConfigurationTest { - - private final ApplicationContextRunner runner = - new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingCoreAutoConfiguration.class)) - .withUserConfiguration(PublisherConfiguration.class); - - @Test - void wiresThePolicyTransportAndObservabilityPrimitives() { - runner.run( - context -> - assertThat(context) - .hasSingleBean(ValidatedDestinationRegistry.class) - .hasSingleBean(MessagingAdmissionController.class) - .hasSingleBean(GracefulShutdownCoordinator.class)); - } - - @Test - void installsSelectedTransportUnderConfiguredLogicalBrokerName() { - new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingCoreAutoConfiguration.class)) - .withUserConfiguration( - PublisherConfiguration.class, LogicalBrokerRuntimeConfiguration.class) - .withPropertyValues( - "app.messaging.brokers.kafka-primary.type=kafka", - "app.messaging.brokers.kafka-primary.bootstrap-servers[0]=broker-1:9092") - .run( - context -> { - assertThat(context).hasNotFailed(); - dev.caskeleton.messaging.transport.MessagingRuntimeRegistry runtimes = - context.getBean( - dev.caskeleton.messaging.transport.MessagingRuntimeRegistry.class); - - try (dev.caskeleton.messaging.transport.MessagingRuntimeLease lease = - runtimes.acquire("kafka-primary")) { - assertThat(lease.runtime().brokerName()).isEqualTo("kafka-primary"); - assertThat(lease.runtime().transport().brokerName()).isEqualTo("kafka"); - } - }); - } - - @Test - void multipleLogicalBrokersFailInsteadOfSharingOnePhysicalTransport() { - new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingCoreAutoConfiguration.class)) - .withUserConfiguration( - PublisherConfiguration.class, LogicalBrokerRuntimeConfiguration.class) - .withPropertyValues( - "app.messaging.brokers.kafka-primary.type=kafka", - "app.messaging.brokers.kafka-primary.bootstrap-servers[0]=broker-1:9092", - "app.messaging.brokers.kafka-secondary.type=kafka", - "app.messaging.brokers.kafka-secondary.bootstrap-servers[0]=broker-2:9092") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .hasMessageContaining("exactly one logical broker")); - } - - @Test - void propertiesBindFromConfiguration() { - runner - .withPropertyValues( - "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.getBackpressure().getGlobalLimit()).isEqualTo(64); - assertThat(properties.getShutdown().getDrainDeadline()) - .isEqualTo(java.time.Duration.ofSeconds(15)); - }); - } - - @Test - void aCoherentDestinationProfileIsRegistered() { - runner - .withUserConfiguration(CoherentProfileConfiguration.class) - .run( - context -> - assertThat( - context - .getBean(ValidatedDestinationRegistry.class) - .require(new DestinationName("order-events"))) - .isNotNull()); - } - - @Test - void aContradictoryDestinationProfileFailsTheContext() { - runner - .withUserConfiguration(ContradictoryProfileConfiguration.class) - .run( - context -> - assertThat(context).hasFailed().getFailure().hasMessageContaining("ordering")); - } - - @Test - void backpressureLimitsAreValidatedAtStartup() { - runner - .withPropertyValues( - "app.messaging.backpressure.global-limit=4", - "app.messaging.backpressure.per-destination-limit=8") - .run(context -> assertThat(context).hasFailed()); - } - - @Configuration(proxyBeanMethods = false) - static class LogicalBrokerRuntimeConfiguration { - - @Bean - dev.caskeleton.messaging.transport.MessagingTransport messagingTransport() { - return new dev.caskeleton.messaging.transport.MessagingTransport() { - @Override - public java.util.concurrent.CompletionStage< - dev.caskeleton.messaging.transport.TransportPublishResult> - publish(dev.caskeleton.messaging.transport.TransportPublishRequest request) { - throw new UnsupportedOperationException("not used"); - } - - @Override - public dev.caskeleton.messaging.transport.TransportConsumerRegistration register( - dev.caskeleton.messaging.transport.TransportConsumerSpec spec) { - throw new UnsupportedOperationException("not used"); - } - - @Override - public dev.caskeleton.messaging.api.destination.DestinationCapabilities capabilities( - DestinationName destination) { - throw new UnsupportedOperationException("not used"); - } - - @Override - public String brokerName() { - return "kafka"; - } - - @Override - public long generation() { - return 1L; - } - - @Override - public void close() {} - }; - } - } - - /** Supplies the publisher the facades and orchestrator depend on. */ - @Configuration(proxyBeanMethods = false) - static class PublisherConfiguration { - - @Bean - MessagePublisher messagePublisher() { - return new MessagePublisher() { - @Override - public CompletionStage publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - return CompletableFuture.failedFuture(new UnsupportedOperationException("not used")); - } - }; - } - } - - @Test - void aDeadLetterDestinationThatIsNotRegisteredFailsTheContext() { - runner - .withUserConfiguration(DanglingDeadLetterConfiguration.class) - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .hasMessageContaining("not registered")); - } - - /** A destination whose policy is internally consistent, plus the dead letter it names. */ - @Configuration(proxyBeanMethods = false) - static class CoherentProfileConfiguration { - - @Bean - DestinationProfile orderEvents() { - return profile(OrderingScope.NONE, RetryPolicy.none()); - } - - @Bean - DestinationProfile orderEventsDeadLetter() { - return named("order-events-dlq", DeadLetterPolicy.disabled()); - } - } - - /** A destination naming a dead letter destination nobody declared. */ - @Configuration(proxyBeanMethods = false) - static class DanglingDeadLetterConfiguration { - - @Bean - DestinationProfile orderEvents() { - return profile(OrderingScope.NONE, RetryPolicy.none()); - } - } - - private static DestinationProfile named(String name, DeadLetterPolicy deadLetter) { - DestinationProfile base = profile(OrderingScope.NONE, RetryPolicy.none()); - return new DestinationProfile( - new DestinationName(name), - base.broker(), - base.kind(), - base.physical(), - base.schema(), - DeliveryGuarantee.AT_MOST_ONCE, - base.orderingScope(), - base.externalSideEffectGuarantee(), - base.producer(), - base.consumer(), - base.retry(), - deadLetter, - base.payload(), - base.tier(), - base.production(), - base.keyResolverConfigured(), - base.topologyAutoCreate()); - } - - /** An ordered destination configured with a reordering retry. */ - @Configuration(proxyBeanMethods = false) - static class ContradictoryProfileConfiguration { - - @Bean - DestinationProfile orderEvents() { - return profile( - OrderingScope.PARTITION, - new RetryPolicy( - dev.caskeleton.messaging.policy.RetryMode.RETRY_DESTINATION, - 3, - java.time.Duration.ofSeconds(1), - java.time.Duration.ofMinutes(1), - 2.0, - true, - dev.caskeleton.messaging.policy.OrderingImpact.PRESERVE, - Set.of(), - Set.of())); - } - } - - private static DestinationProfile profile(OrderingScope ordering, RetryPolicy retry) { - return new DestinationProfile( - new DestinationName("order-events"), - "kafka-primary", - 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, - ordering, - ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED, - ProducerPolicy.defaults(), - ConsumerPolicy.defaults("order-projection"), - retry, - DeadLetterPolicy.to(new DestinationName("order-events-dlq")), - PayloadPolicy.defaults(), - ApiTier.M1, - false, - false, - false); - } - - @org.junit.jupiter.api.Test - @org.junit.jupiter.api.DisplayName("a broker profile the adapter cannot honour fails startup") - void anUnhonourableBrokerProfileFailsStartup() { - new org.springframework.boot.test.context.runner.ApplicationContextRunner() - .withConfiguration( - org.springframework.boot.autoconfigure.AutoConfigurations.of( - MessagingCoreAutoConfiguration.class, KafkaMessagingAutoConfiguration.class)) - .withUserConfiguration(PublisherConfiguration.class, AutoCommittingKafkaProfile.class) - .withPropertyValues( - "app.messaging.brokers.kafka.type=kafka", - "app.messaging.brokers.kafka.bootstrap-servers[0]=localhost:9092") - .run( - context -> - org.assertj.core.api.Assertions.assertThat(context) - .getFailure() - .as( - "a validator nothing injects lets a profile boot and fail on the first" - + " message that depends on the guarantee") - .hasMessageContaining("consumer auto commit is forbidden")); - } - - @org.junit.jupiter.api.Test - @org.junit.jupiter.api.DisplayName("a superseded prefix fails startup instead of binding nothing") - void aSupersededPrefixFailsStartup() { - new org.springframework.boot.test.context.runner.ApplicationContextRunner() - .withConfiguration( - org.springframework.boot.autoconfigure.AutoConfigurations.of( - MessagingCoreAutoConfiguration.class)) - .withPropertyValues("backend.messaging.backpressure.global-limit=64") - .run( - context -> - org.assertj.core.api.Assertions.assertThat(context) - .as( - "a key under a dead prefix looks configured, starts cleanly and does" - + " nothing") - .hasFailed()); - } - - @org.junit.jupiter.api.Test - @org.junit.jupiter.api.DisplayName("the documented bare prefix also fails") - void theDocumentedBarePrefixAlsoFails() { - new org.springframework.boot.test.context.runner.ApplicationContextRunner() - .withConfiguration( - org.springframework.boot.autoconfigure.AutoConfigurations.of( - MessagingCoreAutoConfiguration.class)) - .withPropertyValues("messaging.destinations.orders.broker=kafka-primary") - .run(context -> org.assertj.core.api.Assertions.assertThat(context).hasFailed()); - } - - @org.junit.jupiter.api.Test - @org.junit.jupiter.api.DisplayName("the canonical prefix passes the validator") - void theCanonicalPrefixPassesTheValidator() { - org.springframework.core.env.StandardEnvironment environment = - new org.springframework.core.env.StandardEnvironment(); - environment - .getPropertySources() - .addFirst( - new org.springframework.core.env.MapPropertySource( - "test", java.util.Map.of("app.messaging.backpressure.global-limit", "64"))); - - org.assertj.core.api.Assertions.assertThatCode( - () -> new MessagingPrefixMigrationValidator(environment).validate()) - .doesNotThrowAnyException(); - } - - @org.junit.jupiter.api.Test - @org.junit.jupiter.api.DisplayName("the migration error names the keys and the new prefix") - void theMigrationErrorNamesTheKeys() { - org.springframework.core.env.StandardEnvironment environment = - new org.springframework.core.env.StandardEnvironment(); - environment - .getPropertySources() - .addFirst( - new org.springframework.core.env.MapPropertySource( - "test", java.util.Map.of("backend.messaging.backpressure.global-limit", "64"))); - - org.assertj.core.api.Assertions.assertThatThrownBy( - () -> new MessagingPrefixMigrationValidator(environment).validate()) - .hasMessageContaining("backend.messaging.backpressure.global-limit") - .hasMessageContaining("app.messaging"); - } - - @org.junit.jupiter.api.Test - @org.junit.jupiter.api.DisplayName( - "a production profile on an in-memory journal refuses to start") - void aProductionProfileOnAnInMemoryJournalRefusesToStart() { - org.springframework.mock.env.MockEnvironment production = - new org.springframework.mock.env.MockEnvironment(); - production.setActiveProfiles("prod"); - - org.assertj.core.api.Assertions.assertThatThrownBy( - () -> - new MessagingAdminDurabilityValidator( - new dev.caskeleton.messaging.admin.runtime.InMemoryAdminOperationJournal(), - production) - .validate()) - .as( - "two replicas with their own maps each believed they were the only one executing an" - + " approval, and a restart forgot every claim") - .isInstanceOf(dev.caskeleton.messaging.api.error.MessagingConfigurationException.class) - .hasMessageContaining("not durable") - .hasMessageContaining("JdbcAdminOperationJournal"); - } - - @org.junit.jupiter.api.Test - @org.junit.jupiter.api.DisplayName("local development still starts on the in-memory journal") - void localDevelopmentStillStartsOnTheInMemoryJournal() { - org.assertj.core.api.Assertions.assertThatCode( - () -> - new MessagingAdminDurabilityValidator( - new dev.caskeleton.messaging.admin.runtime.InMemoryAdminOperationJournal(), - new org.springframework.mock.env.MockEnvironment()) - .validate()) - .doesNotThrowAnyException(); - } - - @org.junit.jupiter.api.Test - @org.junit.jupiter.api.DisplayName("a durable journal satisfies a production profile") - void aDurableJournalSatisfiesAProductionProfile() { - org.springframework.mock.env.MockEnvironment production = - new org.springframework.mock.env.MockEnvironment(); - production.setActiveProfiles("production"); - - org.assertj.core.api.Assertions.assertThatCode( - () -> - new MessagingAdminDurabilityValidator(new DurableJournal(), production).validate()) - .doesNotThrowAnyException(); - } - - @org.junit.jupiter.api.Test - @org.junit.jupiter.api.DisplayName( - "a production profile without a credential provider fails with one actionable error") - void aProductionProfileWithoutCredentialsFailsActionably() { - org.assertj.core.api.Assertions.assertThatThrownBy( - () -> - new MessagingCredentialRequirementValidator( - new StaticProvider<>( - new dev.caskeleton.messaging.security.BrokerSecurityProfile( - "kafka-primary", - true, - true, - true, - new dev.caskeleton.messaging.security.BrokerCredentialProfile - .SaslScram("kafka-app"), - new dev.caskeleton.messaging.security.BrokerCredentialProfile - .SaslScram("kafka-app"), - java.util.Optional.empty(), - dev.caskeleton.messaging.security.DestinationAccessPolicy - .denyAll())), - java.util.List.of(), - new StaticProvider(), - new org.springframework.core.env.StandardEnvironment()) - .validate()) - .as( - "the context used to fail on a missing CredentialRuntimeRegistry, naming an internal" - + " type instead of the one thing the operator has to supply") - .isInstanceOf(dev.caskeleton.messaging.api.error.MessagingConfigurationException.class) - .hasMessageContaining("CredentialProvider") - .hasMessageContaining("kafka-primary"); - } - - @org.junit.jupiter.api.Test - @org.junit.jupiter.api.DisplayName("a non-production profile without credentials still starts") - void aNonProductionProfileWithoutCredentialsStarts() { - org.assertj.core.api.Assertions.assertThatCode( - () -> - new MessagingCredentialRequirementValidator( - new StaticProvider<>( - new dev.caskeleton.messaging.security.BrokerSecurityProfile( - "kafka-local", - false, - false, - false, - new dev.caskeleton.messaging.security.BrokerCredentialProfile - .SaslScram("kafka-app"), - new dev.caskeleton.messaging.security.BrokerCredentialProfile - .SaslScram("kafka-app"), - java.util.Optional.empty(), - dev.caskeleton.messaging.security.DestinationAccessPolicy - .denyAll())), - java.util.List.of(), - new StaticProvider(), - new org.springframework.core.env.StandardEnvironment()) - .validate()) - .as("a local broker with no authentication is a legitimate development setup") - .doesNotThrowAnyException(); - } - - /** A journal that claims durability, standing in for the JDBC one. */ - private static final class DurableJournal - implements dev.caskeleton.messaging.admin.AdminOperationJournal { - - @Override - public dev.caskeleton.messaging.admin.AdminOperationLease begin( - String approvalTicket, - dev.caskeleton.messaging.admin.PlanDigest planDigest, - String operationId, - String leaseOwner, - java.time.Duration leaseDuration, - java.time.Instant now) { - throw new UnsupportedOperationException("the durability check never executes an operation"); - } - - @Override - public void checkpoint( - dev.caskeleton.messaging.admin.AdminOperationLease lease, - int itemsCompleted, - java.time.Duration leaseDuration, - java.time.Instant now) { - throw new UnsupportedOperationException("the durability check never executes an operation"); - } - - @Override - public void complete( - dev.caskeleton.messaging.admin.AdminOperationLease lease, - int itemsCompleted, - java.time.Instant now) { - throw new UnsupportedOperationException("the durability check never executes an operation"); - } - - @Override - public void fail( - dev.caskeleton.messaging.admin.AdminOperationLease lease, - int itemsCompleted, - String failureCode, - java.time.Instant now) { - throw new UnsupportedOperationException("the durability check never executes an operation"); - } - - @Override - public java.util.Optional find( - String approvalTicket, dev.caskeleton.messaging.admin.PlanDigest planDigest) { - return java.util.Optional.empty(); - } - - @Override - public boolean isDurable() { - return true; - } - } - - /** A fixed ObjectProvider, so the validator can be exercised without a container. */ - private static final class StaticProvider - implements org.springframework.beans.factory.ObjectProvider { - - private final java.util.List values; - - @SafeVarargs - private StaticProvider(T... values) { - this.values = java.util.List.of(values); - } - - @Override - public T getObject() { - return values.get(0); - } - - @Override - public T getObject(Object... args) { - return getObject(); - } - - @Override - public T getIfAvailable() { - return values.isEmpty() ? null : values.get(0); - } - - @Override - public T getIfUnique() { - return values.size() == 1 ? values.get(0) : null; - } - - @Override - public java.util.stream.Stream stream() { - return values.stream(); - } - } -} - -/** A Kafka profile that acknowledges on a timer rather than after the handler. */ -@Configuration(proxyBeanMethods = false) -class AutoCommittingKafkaProfile { - - @Bean - dev.caskeleton.messaging.kafka.KafkaBrokerProfile kafkaBrokerProfile() { - return KafkaProfiles.profile(true); - } -} - -/** Builds a Kafka broker profile whose consumer acknowledges on a timer. */ -final class KafkaProfiles { - - private KafkaProfiles() {} - - static dev.caskeleton.messaging.kafka.KafkaBrokerProfile profile(boolean enableAutoCommit) { - return new dev.caskeleton.messaging.kafka.KafkaBrokerProfile( - "kafka-primary", - true, - false, - java.util.List.of("localhost:9092"), - true, - "all", - 5, - java.time.Duration.ofSeconds(30), - enableAutoCommit, - "orders", - false, - false); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationBindingTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationBindingTest.java deleted file mode 100644 index f365f6e1..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationBindingTest.java +++ /dev/null @@ -1,364 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -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.DestinationProfile; -import java.io.IOException; -import java.io.UncheckedIOException; -import java.nio.charset.StandardCharsets; -import java.nio.file.Files; -import java.nio.file.Path; -import java.util.ArrayList; -import java.util.List; -import org.junit.jupiter.api.Test; -import org.springframework.boot.autoconfigure.AutoConfigurations; -import org.springframework.boot.env.YamlPropertySourceLoader; -import org.springframework.boot.test.context.runner.ApplicationContextRunner; -import org.springframework.core.env.PropertySource; -import org.springframework.core.io.ByteArrayResource; - -/** - * Makes the configuration reference an executable statement rather than a description. - * - *

The document described destination, broker and security sections for a platform whose binder - * held four flags. Every one of those keys was inert: a deployment that configured exactly what the - * page said started cleanly, changed nothing, and reported nothing — the outcome that is worse than - * both "it works" and "it refuses to start", because there is no moment at which anybody learns. - * - *

So the first test below reads the YAML out of the shipped page and boots a context on it. An - * edit to the document that the binder cannot honour fails here, and so does a change to the binder - * that leaves the document describing a shape that no longer exists. - * - *

The rest are the refusals. Each one is a configuration an operator can write and each fails - * startup with the key in the message, because a platform that silently ignores the line somebody - * came to change is the defect this whole suite is about. - */ -class MessagingConfigurationBindingTest { - - private final ApplicationContextRunner runner = - new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingCoreAutoConfiguration.class)) - .withUserConfiguration(MessagingAutoConfigurationTest.PublisherConfiguration.class); - - @Test - void theDocumentedConfigurationBindsToTheProfilesThePlatformUses() { - documented() - .run( - context -> { - assertThat(context).hasNotFailed(); - - DestinationProfile orders = - context - .getBean(ValidatedDestinationRegistry.class) - .require(new DestinationName("order-events")); - assertThat(orders.broker()).isEqualTo("kafka-primary"); - assertThat(orders.kind()).isEqualTo(DestinationKind.EVENT_STREAM); - assertThat(orders.physical().topic()).contains("order.events.v1"); - assertThat(orders.orderingScope()).isEqualTo(OrderingScope.KEY); - assertThat(orders.retry().maxAttempts()).isEqualTo(3); - assertThat(orders.deadLetter().destination()) - .contains(new DestinationName("order-events-dlq")); - assertThat(orders.schema().messageTypes()) - .extracting(dev.caskeleton.messaging.api.MessageType::value) - .containsExactly("order.created"); - - CompiledMessagingConfiguration compiled = - context.getBean(CompiledMessagingConfiguration.class); - assertThat(compiled.brokers()).containsOnlyKeys("kafka-primary"); - assertThat(compiled.brokers().get("kafka-primary").type()) - .isEqualTo(BrokerSettings.KAFKA); - KafkaBrokerSettings kafka = - KafkaBrokerSettings.bindAll(context.getEnvironment(), compiled) - .get("kafka-primary"); - assertThat(kafka.bootstrapServers()) - .containsExactly("broker-1:9093", "broker-2:9093"); - assertThat(kafka.enableAutoCommit()).isFalse(); - assertThat(compiled.security()) - .singleElement() - .satisfies( - security -> { - assertThat(security.broker()).isEqualTo("kafka-primary"); - assertThat(security.hostnameVerification()).isTrue(); - assertThat(security.admin()) - .as("an application runtime holds no admin credential") - .isEmpty(); - assertThat( - security.access().mayPublish(new DestinationName("order-events"))) - .isTrue(); - }); - }); - } - - @Test - void aTypoInsideTheAdminSectionFailsStartupNamingTheKey() { - runner - .withPropertyValues(minimal()) - .withPropertyValues("app.messaging.admin.enable=true") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .hasMessageContaining("app.messaging.admin.enable") - .hasMessageContaining("enabled")); - } - - @Test - void aTypoInsideABoundSectionFailsStartupNamingTheKey() { - runner - .withPropertyValues(minimal()) - .withPropertyValues("app.messaging.destinations.order-events.consumer.prefech=64") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .hasMessageContaining( - "app.messaging.destinations.order-events.consumer.prefech") - .hasMessageContaining("prefetch")); - } - - @Test - void aDestinationNamingAnUnconfiguredBrokerFailsNamingTheKey() { - runner - .withPropertyValues(minimal()) - .withPropertyValues("app.messaging.destinations.order-events.broker=kafka-secondary") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .hasMessageContaining("app.messaging.destinations.order-events.broker") - .hasMessageContaining("kafka-secondary")); - } - - @Test - void aDanglingDeadLetterDestinationFailsStartup() { - runner - .withPropertyValues(minimal()) - .withPropertyValues( - "app.messaging.destinations.order-events.dlq.destination=nobody-declared-this") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .hasMessageContaining("nobody-declared-this")); - } - - @Test - void aRetryAndDeadLetterCycleAcrossTwoDestinationsIsRefusedWithItsPath() { - runner - .withPropertyValues(minimal()) - .withPropertyValues( - "app.messaging.destinations.order-events.retry.mode=RETRY_DESTINATION", - "app.messaging.destinations.order-events.retry.max-attempts=3", - "app.messaging.destinations.order-events.retry.ordering-impact=ALLOW_REORDER", - "app.messaging.destinations.order-events.retry.destination=order-retry", - "app.messaging.destinations.order-events.dlq.destination=order-retry", - "app.messaging.destinations.order-retry.broker=kafka-primary", - "app.messaging.destinations.order-retry.kind=WORK_QUEUE", - "app.messaging.destinations.order-retry.physical.topic=order.retry.v1", - "app.messaging.destinations.order-retry.schema.message-types[0]=order.created", - "app.messaging.destinations.order-retry.dlq.destination=order-events") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .hasMessageContaining("cycle") - .hasMessageContaining("order-events") - .hasMessageContaining("order-retry")); - } - - @Test - void aRabbitMqSettingBindsNothingAndFailsNamingTheKey() { - runner - .withPropertyValues(minimal()) - .withPropertyValues("app.messaging.brokers.kafka-primary.prefetch=32") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .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 - void aSecurityEntryForAnUndeclaredBrokerFailsNamingTheKey() { - runner - .withPropertyValues(minimal()) - .withPropertyValues( - "app.messaging.security.kafka-secondary.producer.type=SASL_SCRAM", - "app.messaging.security.kafka-secondary.producer.credential-id=p", - "app.messaging.security.kafka-secondary.consumer.type=SASL_SCRAM", - "app.messaging.security.kafka-secondary.consumer.credential-id=c") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .hasMessageContaining("app.messaging.security.kafka-secondary") - .hasMessageContaining("is not a configured broker")); - } - - @Test - void producerAndConsumerSharingOneCredentialFailsStartup() { - runner - .withPropertyValues(minimal()) - .withPropertyValues( - "app.messaging.security.kafka-primary.producer.type=SASL_SCRAM", - "app.messaging.security.kafka-primary.producer.credential-id=one-account", - "app.messaging.security.kafka-primary.consumer.type=SASL_SCRAM", - "app.messaging.security.kafka-primary.consumer.credential-id=one-account") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .as("the validator was a bean nothing injected; bound values now reach it") - .hasMessageContaining("separate credentials")); - } - - @Test - void anUnknownAuthenticationMechanismFailsNamingTheKey() { - runner - .withPropertyValues(minimal()) - .withPropertyValues( - "app.messaging.security.kafka-primary.producer.type=TRUST_ME", - "app.messaging.security.kafka-primary.producer.credential-id=p", - "app.messaging.security.kafka-primary.consumer.type=SASL_SCRAM", - "app.messaging.security.kafka-primary.consumer.credential-id=c") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .hasMessageContaining("app.messaging.security.kafka-primary.producer.type") - .hasMessageContaining("TRUST_ME")); - } - - @Test - @org.junit.jupiter.api.DisplayName("주소가 없는 Kafka broker는 Kafka starter가 그 키를 이름으로 대며 기동을 거부한다") - void aKafkaBrokerWithoutAnAddressIsRefusedByTheKafkaStarterNamingTheKey() { - // given - ApplicationContextRunner kafka = - runner - .withConfiguration(AutoConfigurations.of(KafkaMessagingAutoConfiguration.class)) - .withPropertyValues("app.messaging.brokers.kafka-primary.type=kafka"); - - // when - kafka.run( - context -> - // then - assertThat(context) - .hasFailed() - .getFailure() - .rootCause() - .hasMessageContaining("app.messaging.brokers.kafka-primary.bootstrap-servers")); - } - - @Test - void aProductionKafkaBrokerWithoutTransportSecurityFailsStartup() { - runner - .withConfiguration(AutoConfigurations.of(KafkaMessagingAutoConfiguration.class)) - .withPropertyValues(minimal()) - .withPropertyValues("app.messaging.brokers.kafka-primary.production=true") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .as("the Kafka validator existed as a bean and validated nothing") - .hasMessageContaining("production Kafka connection requires TLS")); - } - - /** - * The smallest configuration that boots, which every refusal above then breaks in one way. - * - *

Written as properties rather than reused from the document because a refusal test has to - * change exactly one thing; sharing the documented fixture would make each failure depend on - * everything else the page happens to say. - */ - private static String[] minimal() { - return new String[] { - "app.messaging.brokers.kafka-primary.type=kafka", - "app.messaging.brokers.kafka-primary.bootstrap-servers[0]=broker-1:9093", - "app.messaging.destinations.order-events.broker=kafka-primary", - "app.messaging.destinations.order-events.kind=EVENT_STREAM", - "app.messaging.destinations.order-events.physical.topic=order.events.v1", - "app.messaging.destinations.order-events.schema.message-types[0]=order.created", - "app.messaging.destinations.order-events.guarantees.delivery=AT_MOST_ONCE", - }; - } - - private ApplicationContextRunner documented() { - List> sources = new ArrayList<>(); - YamlPropertySourceLoader loader = new YamlPropertySourceLoader(); - List blocks = yamlBlocks(reference()); - assertThat(blocks) - .as("the configuration reference has stopped carrying YAML examples") - .isNotEmpty(); - for (int index = 0; index < blocks.size(); index++) { - try { - sources.addAll( - loader.load( - "configuration-reference-" + index, - new ByteArrayResource(blocks.get(index).getBytes(StandardCharsets.UTF_8)))); - } catch (IOException failure) { - throw new UncheckedIOException(failure); - } - } - return runner.withInitializer( - context -> sources.forEach(context.getEnvironment().getPropertySources()::addLast)); - } - - private static List yamlBlocks(String document) { - List blocks = new ArrayList<>(); - StringBuilder current = null; - for (String line : document.lines().toList()) { - if (line.startsWith("```yaml")) { - current = new StringBuilder(); - } else if (line.startsWith("```") && current != null) { - blocks.add(current.toString()); - current = null; - } else if (current != null) { - current.append(line).append('\n'); - } - } - return blocks; - } - - private static String reference() { - Path candidate = Path.of("").toAbsolutePath(); - while (candidate != null && !Files.isDirectory(candidate.resolve("docs/messaging"))) { - candidate = candidate.getParent(); - } - if (candidate == null) { - throw new IllegalStateException("could not locate docs/messaging from the test cwd"); - } - try { - return Files.readString(candidate.resolve("docs/messaging/configuration-reference.md")); - } catch (IOException failure) { - throw new UncheckedIOException(failure); - } - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfigurationTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfigurationTest.java deleted file mode 100644 index 59766248..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfigurationTest.java +++ /dev/null @@ -1,243 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.catchThrowable; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.delivery.HandleResult; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.error.MessageValidationException; -import dev.caskeleton.messaging.schema.MessageCodec; -import dev.caskeleton.messaging.schema.MessageCodecRegistry; -import dev.caskeleton.messaging.schema.MessageContractKey; -import java.nio.charset.StandardCharsets; -import java.util.Map; -import java.util.Set; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -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; - -/** The consume pipeline turns on with a handler bean and refuses what it cannot honour. */ -class MessagingConsumeConfigurationTest { - - private final ApplicationContextRunner runner = - new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingCoreAutoConfiguration.class)) - .withUserConfiguration(MessagingAutoConfigurationTest.PublisherConfiguration.class) - .withPropertyValues( - "app.messaging.brokers.kafka-primary.type=kafka", - "app.messaging.brokers.kafka-primary.bootstrap-servers[0]=broker-1:9093", - "app.messaging.destinations.order-events.broker=kafka-primary", - "app.messaging.destinations.order-events.kind=EVENT_STREAM", - "app.messaging.destinations.order-events.physical.topic=order.events.v1", - "app.messaging.destinations.order-events.schema.message-types[0]=order.created", - "app.messaging.destinations.order-events.guarantees.delivery=AT_MOST_ONCE"); - - @Test - @DisplayName("handler bean이 없으면 consumer를 만들지 않는다") - void withoutAHandlerBeanNoConsumerIsAssembled() { - // when - runner.run( - context -> - // then - assertThat(context).hasNotFailed().doesNotHaveBean(MessageConsumers.class)); - } - - @Test - @DisplayName("handler bean이 있으면 그 destination의 consumer가 group과 함께 조립된다") - void aHandlerBeanAssemblesAConsumerForItsDestinationWithItsGroup() { - // when - runner - .withPropertyValues("app.messaging.destinations.order-events.consumer.group=projection") - .withBean("ordersHandler", MessageHandler.class, MessagingConsumeConfigurationTest::handler) - .run( - context -> { - // then - assertThat(context).hasNotFailed(); - assertThat(context.getBean(MessageConsumers.class).consumers()) - .singleElement() - .satisfies( - consumer -> { - assertThat(consumer.profile().name().value()).isEqualTo("order-events"); - assertThat(consumer.group()).isEqualTo("projection"); - }); - }); - } - - @Test - @DisplayName("consumer.group이 없는 destination을 소비하는 handler는 기동을 거부한다") - void aHandlerForADestinationWithoutAConsumerGroupFailsStartup() { - // when - runner - .withBean("ordersHandler", MessageHandler.class, MessagingConsumeConfigurationTest::handler) - .run( - context -> - // then - assertThat(context) - .hasFailed() - .getFailure() - .rootCause() - .hasMessageContaining("order-events") - .hasMessageContaining("consumer.group")); - } - - @Test - @DisplayName("INBOX_TRANSACTIONAL destination에 IdempotentConsumer가 없으면 기동을 거부한다") - void anInboxDestinationWithoutAnIdempotentConsumerFailsStartup() { - // when - runner - .withPropertyValues( - "app.messaging.destinations.order-events.consumer.group=projection", - "app.messaging.destinations.order-events.guarantees.external-side-effect=" - + "INBOX_TRANSACTIONAL") - .withBean("ordersHandler", MessageHandler.class, MessagingConsumeConfigurationTest::handler) - .run( - context -> - // then - assertThat(context) - .hasFailed() - .getFailure() - .rootCause() - .hasMessageContaining("INBOX_TRANSACTIONAL") - .hasMessageContaining("IdempotentConsumer")); - } - - @Test - @DisplayName("handler bean이 선언한 메시지 타입과 payload class는 따로 등록하지 않아도 decode된다") - void aHandlerBeansDeclaredContractIsDecodedWithoutAnyRegistration() { - // given: a handler for order.created and no MessageContracts bean at all - var consuming = - runner - .withPropertyValues("app.messaging.destinations.order-events.consumer.group=projection") - .withBean( - "ordersHandler", - MessageHandler.class, - () -> handler(OrderCreated.class, Set.of(new SchemaVersion(1)))); - - // when - consuming.run( - context -> { - OrderCreated decoded = - json(context.getBean(MessageCodecRegistry.class)) - .decode( - new MessageType("order.created"), - new SchemaVersion(1), - "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), - OrderCreated.class); - - // then - assertThat(decoded).isEqualTo(new OrderCreated("o-1")); - }); - } - - @Test - @DisplayName("handler가 선언하지 않은 schema version은 그 class로 decode하지 않고 거부한다") - void aSchemaVersionTheHandlerDoesNotDeclareIsRefused() { - // given: the handler reads version 1 only - var consuming = - runner - .withPropertyValues("app.messaging.destinations.order-events.consumer.group=projection") - .withBean( - "ordersHandler", - MessageHandler.class, - () -> handler(OrderCreated.class, Set.of(new SchemaVersion(1)))); - - // when - consuming.run( - context -> { - Throwable refused = - catchThrowable( - () -> - json(context.getBean(MessageCodecRegistry.class)) - .decode( - new MessageType("order.created"), - new SchemaVersion(2), - "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), - OrderCreated.class)); - - // then - assertThat(refused) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("order.created v2"); - }); - } - - @Test - @DisplayName("등록된 계약과 handler가 같은 type·version에 다른 class를 선언하면 기동을 거부한다") - void aHandlerThatDeclaresAnotherClassForARegisteredContractFailsStartup() { - // given: order.created v1 registered as String, and a handler reading it as OrderCreated - var conflicting = - runner - .withPropertyValues("app.messaging.destinations.order-events.consumer.group=projection") - .withBean( - MessageContracts.class, - () -> - new MessageContracts( - Map.of(MessageContractKey.of("order.created", 1), String.class))) - .withBean( - "ordersHandler", - MessageHandler.class, - () -> handler(OrderCreated.class, Set.of(new SchemaVersion(1)))); - - // when - conflicting.run( - context -> - // then - assertThat(context) - .hasFailed() - .getFailure() - .rootCause() - .hasMessageContaining("order.created v1") - .hasMessageContaining(OrderCreated.class.getName())); - } - - /** The payload a consumer of {@code order.created} reads. */ - record OrderCreated(String orderId) {} - - private static MessageCodec json(MessageCodecRegistry codecs) { - return codecs.find(ContentType.JSON).orElseThrow(); - } - - private static MessageHandler handler(Class payload, Set versions) { - return new MessageHandler<>() { - @Override - public MessageDestination destination() { - return new MessageDestination<>( - new DestinationName("order-events"), new MessageType("order.created"), payload); - } - - @Override - public Set schemaVersions() { - return versions; - } - - @Override - public CompletionStage handle(MessageDelivery delivery) { - return CompletableFuture.completedFuture(HandleResult.success()); - } - }; - } - - private static MessageHandler handler() { - return new MessageHandler<>() { - @Override - public MessageDestination destination() { - return new MessageDestination<>( - new DestinationName("order-events"), new MessageType("order.created"), String.class); - } - - @Override - public CompletionStage handle(MessageDelivery delivery) { - return CompletableFuture.completedFuture(HandleResult.success()); - } - }; - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpointTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpointTest.java deleted file mode 100644 index 75c1bfaa..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpointTest.java +++ /dev/null @@ -1,133 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -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.ApiTier; -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.schema.SchemaCompatibility; -import java.util.List; -import java.util.Map; -import java.util.Set; -import org.junit.jupiter.api.Test; - -class MessagingEndpointTest { - - private static DestinationProfile profile() { - 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, - OrderingScope.KEY, - ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED, - ProducerPolicy.defaults(), - ConsumerPolicy.defaults("orders"), - RetryPolicy.none(), - DeadLetterPolicy.to(new DestinationName("orders.v1.dlq")), - PayloadPolicy.defaults(), - ApiTier.M1, - true, - true, - false); - } - - private static MessagingEndpoint endpoint(MessagingAdmissionController admission) { - return new MessagingEndpoint(new ValidatedDestinationRegistry(List.of(profile())), admission); - } - - /** The real gate, so the endpoint reports what a publish actually occupies. */ - private static MessagingAdmissionController admission(int global, int perDestination) { - return new MessagingAdmissionController( - new PayloadLimitGuard(PayloadPolicy.defaults()), - new InFlightLimiter(global, java.time.Duration.ZERO), - perDestination); - } - - @SuppressWarnings("unchecked") - private static List> destinations(Map report) { - return (List>) report.get("destinations"); - } - - @Test - void theReportNamesEveryRegisteredDestination() { - Map report = endpoint(admission(100, 10)).messaging(); - - assertThat(destinations(report)) - .singleElement() - .satisfies(entry -> assertThat(entry.get("name")).isEqualTo("orders.v1")); - } - - @Test - void theReportCarriesTheDeclaredGuaranteesAnOperatorNeeds() { - Map entry = destinations(endpoint(admission(100, 10)).messaging()).get(0); - - assertThat(entry) - .containsEntry("deliveryGuarantee", "AT_LEAST_ONCE") - .containsEntry("orderingScope", "KEY") - .containsEntry("deadLetterEnabled", true) - .containsEntry("production", true); - } - - @Test - void theReportShowsCurrentInFlightWork() { - MessagingAdmissionController admission = admission(100, 10); - admission.admit("orders.v1", 128); - admission.admit("orders.v1", 128); - - Map report = endpoint(admission).messaging(); - - assertThat(report).containsEntry("globalInFlight", 2); - assertThat(destinations(report).get(0)).containsEntry("inFlight", 2); - } - - @Test - void theReportCarriesNoPerMessageIdentity() { - Map entry = destinations(endpoint(admission(100, 10)).messaging()).get(0); - - assertThat(entry.keySet()) - .as("an actuator response that echoes message content is a re-identification surface") - .doesNotContain("messageId", "key", "partitionKey", "offset", "payload", "tenantId"); - } - - @Test - void theEndpointIsReadOnly() { - long writeOperations = - java.util.Arrays.stream(MessagingEndpoint.class.getDeclaredMethods()) - .filter( - method -> - method.isAnnotationPresent( - org.springframework.boot.actuate.endpoint.annotation.WriteOperation - .class) - || method.isAnnotationPresent( - org.springframework.boot.actuate.endpoint.annotation.DeleteOperation - .class)) - .count(); - - assertThat(writeOperations) - .as( - "the management port is usually unauthenticated; pause and purge belong to the admin plane") - .isZero(); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingInboxAssemblyTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingInboxAssemblyTest.java deleted file mode 100644 index 1bc1271a..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingInboxAssemblyTest.java +++ /dev/null @@ -1,68 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.inbox.IdempotentConsumer; -import dev.caskeleton.messaging.reliability.InboxRepository; -import java.time.Instant; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; -import org.springframework.boot.test.context.runner.ApplicationContextRunner; - -/** - * The platform assembles its inbox runner from the two parts only the application can supply - * (review 06-08): nothing assembled it before, so an INBOX_TRANSACTIONAL destination could only - * refuse to start. - */ -class MessagingInboxAssemblyTest { - - private final ApplicationContextRunner runner = - new ApplicationContextRunner() - .withUserConfiguration(MessagingReliabilityAutoConfiguration.class); - - @Test - @DisplayName("애플리케이션이 inbox 저장소와 트랜잭션 runner를 주면 platform이 IdempotentConsumer를 만든다") - void theApplicationsInboxPartsAssembleTheIdempotentConsumer() { - // when & then - runner - .withBean(InboxRepository.class, NoInbox::new) - .withBean(IdempotentConsumer.TransactionRunner.class, () -> Runner.DIRECT) - .run(context -> assertThat(context).hasSingleBean(IdempotentConsumer.class)); - } - - @Test - @DisplayName("트랜잭션 runner가 없으면 IdempotentConsumer를 만들지 않는다") - void withoutTheApplicationsTransactionNoIdempotentConsumerIsAssembled() { - // when & then - runner - .withBean(InboxRepository.class, NoInbox::new) - .run(context -> assertThat(context).doesNotHaveBean(IdempotentConsumer.class)); - } - - private enum Runner implements IdempotentConsumer.TransactionRunner { - DIRECT; - - @Override - public T inTransaction(java.util.function.Supplier work) { - return work.get(); - } - } - - private static final class NoInbox implements InboxRepository { - @Override - public boolean reserve(MessageId messageId, String consumerId, Instant now) { - return true; - } - - @Override - public boolean isProcessed(MessageId messageId, String consumerId) { - return false; - } - - @Override - public int purgeProcessedBefore(Instant processedBefore, int limit) { - return 0; - } - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingMigrationNamespaceTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingMigrationNamespaceTest.java deleted file mode 100644 index 6cd3e521..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingMigrationNamespaceTest.java +++ /dev/null @@ -1,79 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -import java.io.IOException; -import java.net.JarURLConnection; -import java.net.URL; -import java.util.ArrayList; -import java.util.Enumeration; -import java.util.HashSet; -import java.util.List; -import java.util.Set; -import java.util.regex.Matcher; -import java.util.regex.Pattern; -import org.junit.jupiter.api.Test; - -/** - * Keeps every messaging reliability migration in one collision-free Flyway version namespace. - * - *

The starter ships both JDBC reliability modules, so this test inspects the same combined - * runtime classpath an adopter receives rather than certifying each module in isolation. - */ -class MessagingMigrationNamespaceTest { - - private static final String LOCATION = "db/migration/messaging"; - private static final Pattern VERSIONED = Pattern.compile("V(\\d+)__.+\\.sql"); - - @Test - void combinedMessagingClasspathHasUniqueReservedFlywayVersions() throws Exception { - List migrations = migrationsOnCombinedClasspath(); - - assertThat(migrations) - .as("both messaging JDBC modules must contribute migrations to the assembled starter") - .hasSizeGreaterThanOrEqualTo(5); - - Set versions = new HashSet<>(); - for (String migration : migrations) { - Matcher match = VERSIONED.matcher(migration); - assertThat(match.matches()).as("%s must be a versioned Flyway migration", migration).isTrue(); - long version = Long.parseLong(match.group(1)); - assertThat(version) - .as("%s must stay in the messaging-reserved version range", migration) - .isBetween(1000L, 1999L); - assertThat(versions.add(version)) - .as("Flyway version %s is duplicated across the assembled messaging modules", version) - .isTrue(); - } - } - - private static List migrationsOnCombinedClasspath() throws IOException { - List names = new ArrayList<>(); - Enumeration roots = - MessagingMigrationNamespaceTest.class.getClassLoader().getResources(LOCATION); - while (roots.hasMoreElements()) { - URL root = roots.nextElement(); - if ("file".equals(root.getProtocol())) { - java.io.File[] files = - new java.io.File(java.net.URI.create(root.toString())) - .listFiles((dir, name) -> name.endsWith(".sql")); - if (files != null) { - for (java.io.File file : files) { - names.add(file.getName()); - } - } - } else if ("jar".equals(root.getProtocol())) { - JarURLConnection connection = (JarURLConnection) root.openConnection(); - try (java.util.jar.JarFile jar = connection.getJarFile()) { - jar.stream() - .map(java.util.jar.JarEntry::getName) - .filter(name -> name.startsWith(LOCATION + "/")) - .filter(name -> name.endsWith(".sql")) - .map(name -> name.substring(name.lastIndexOf('/') + 1)) - .forEach(names::add); - } - } - } - return names.stream().sorted().toList(); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingOutboxRelayLifecycleTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingOutboxRelayLifecycleTest.java deleted file mode 100644 index db68ef1d..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingOutboxRelayLifecycleTest.java +++ /dev/null @@ -1,210 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.ProducerId; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.outbox.OutboxEnvelopeFactory; -import dev.caskeleton.messaging.reliability.OutboxLease; -import dev.caskeleton.messaging.reliability.OutboxRecord; -import dev.caskeleton.messaging.reliability.OutboxRepository; -import dev.caskeleton.messaging.reliability.OutboxTransitionResult; -import java.time.Duration; -import java.time.Instant; -import java.util.List; -import java.util.Optional; -import java.util.concurrent.CompletionStage; -import java.util.concurrent.CountDownLatch; -import java.util.concurrent.TimeUnit; -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.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; - -/** - * Whether a started context drives the outbox relay. - * - *

The auto-configuration built the relay's settings and its retry scheduler and never built a - * relay, let alone ran one. An application that added the starter got a table that fills up behind - * business transactions reporting success. - */ -class MessagingOutboxRelayLifecycleTest { - - private final ApplicationContextRunner runner = - new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingReliabilityAutoConfiguration.class)) - .withUserConfiguration(RelayDependencies.class); - - @Test - @DisplayName("a started context runs relay passes without the application driving them") - void aStartedContextRunsRelayPasses() { - runner.run( - context -> { - assertThat(context).hasSingleBean(MessagingOutboxRelayLifecycle.class); - CountingOutboxRepository repository = context.getBean(CountingOutboxRepository.class); - - assertThat(repository.claimed.await(5, TimeUnit.SECONDS)) - .as("a relay nobody calls is an outbox that stages messages and publishes none") - .isTrue(); - assertThat(context.getBean(MessagingOutboxRelayLifecycle.class).isRunning()).isTrue(); - }); - } - - @Test - @DisplayName("closing the context stops the relay rather than leaving it publishing") - void closingTheContextStopsTheRelay() { - MessagingOutboxRelayLifecycle[] captured = new MessagingOutboxRelayLifecycle[1]; - - runner.run( - context -> { - captured[0] = context.getBean(MessagingOutboxRelayLifecycle.class); - assertThat(captured[0].isRunning()).isTrue(); - }); - - assertThat(captured[0].isRunning()) - .as("a relay thread outliving its context publishes from a half-disposed application") - .isFalse(); - } - - @Test - void aRelayPassThatFailsIsCountedOnTheMeterRegistry() { - new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingReliabilityAutoConfiguration.class)) - .withBean( - io.micrometer.core.instrument.MeterRegistry.class, - io.micrometer.core.instrument.simple.SimpleMeterRegistry::new) - .withBean( - OutboxRepository.class, - () -> - (OutboxRepository) - java.lang.reflect.Proxy.newProxyInstance( - getClass().getClassLoader(), - new Class[] {OutboxRepository.class}, - (proxy, method, arguments) -> { - throw new IllegalStateException("the outbox database is unreachable"); - })) - .withBean( - OutboxEnvelopeFactory.class, - () -> new OutboxEnvelopeFactory(new ProducerId("order-api"))) - .withBean(MessagePublisher.class, () -> new RelayDependencies().messagePublisher()) - .run( - context -> { - // given - io.micrometer.core.instrument.MeterRegistry registry = - context.getBean(io.micrometer.core.instrument.MeterRegistry.class); - - // when - double failed = awaitFailedPasses(registry); - - // then - assertThat(failed) - .as("a pass that failed was swallowed with no log and a counter nothing read") - .isPositive(); - }); - } - - /** Reads the failed-pass counter until the relay's first pass has had time to fail. */ - private static double awaitFailedPasses(io.micrometer.core.instrument.MeterRegistry registry) - throws InterruptedException { - long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(5); - double failed = 0; - while (failed == 0 && System.nanoTime() < deadline) { - Thread.sleep(10); - failed = registry.get("messaging.outbox.relay.failed.passes").functionCounter().count(); - } - return failed; - } - - /** The two beans only the application can supply, plus the publisher the platform needs. */ - @Configuration(proxyBeanMethods = false) - static class RelayDependencies { - - @Bean - CountingOutboxRepository outboxRepository() { - return new CountingOutboxRepository(); - } - - @Bean - OutboxEnvelopeFactory outboxEnvelopeFactory() { - return new OutboxEnvelopeFactory(new ProducerId("order-api")); - } - - @Bean - MessagePublisher messagePublisher() { - return new MessagePublisher() { - @Override - public CompletionStage publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - throw new UnsupportedOperationException("this relay never claims a row to publish"); - } - }; - } - } - - /** - * An outbox that has nothing to publish and counts being asked. - * - *

Only the claim is implemented: the point under test is whether anything asks, not what the - * relay does with what it gets. Every other method throws so that a test which starts depending - * on one fails loudly instead of silently exercising a stub. - */ - static final class CountingOutboxRepository implements OutboxRepository { - - private final CountDownLatch claimed = new CountDownLatch(1); - - @Override - public List claimBatch( - String owner, int batchSize, Duration leaseDuration, Instant now, int maxAttempts) { - claimed.countDown(); - return List.of(); - } - - @Override - public void append(OutboxRecord record) { - throw new UnsupportedOperationException("not used by this test"); - } - - @Override - public OutboxTransitionResult markPublished(OutboxLease lease, Instant now) { - throw new UnsupportedOperationException("not used by this test"); - } - - @Override - public OutboxTransitionResult markAmbiguous( - OutboxLease lease, String failureCode, Instant now, Instant nextAttemptAt) { - throw new UnsupportedOperationException("not used by this test"); - } - - @Override - public OutboxTransitionResult markExhausted(OutboxLease lease, String reason, Instant now) { - throw new UnsupportedOperationException("not used by this test"); - } - - @Override - public OutboxTransitionResult markFailed(OutboxLease lease, String failureCode, Instant now) { - throw new UnsupportedOperationException("not used by this test"); - } - - @Override - public OutboxTransitionResult releaseLease(OutboxLease lease) { - throw new UnsupportedOperationException("not used by this test"); - } - - @Override - public Optional find(MessageId messageId) { - throw new UnsupportedOperationException("not used by this test"); - } - - @Override - public int purgePublishedBefore(Instant publishedBefore, int limit) { - throw new UnsupportedOperationException("not used by this test"); - } - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformAutoConfigurationRegistrationTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformAutoConfigurationRegistrationTest.java deleted file mode 100644 index a7227e6d..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformAutoConfigurationRegistrationTest.java +++ /dev/null @@ -1,104 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -import java.io.IOException; -import java.io.UncheckedIOException; -import java.nio.charset.StandardCharsets; -import java.nio.file.Files; -import java.nio.file.Path; -import java.util.List; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; -import org.springframework.boot.autoconfigure.AutoConfiguration; -import org.springframework.core.annotation.AnnotatedElementUtils; - -/** - * This leaf's auto-configurations are registered, not merely annotated. - * - *

Spring Boot needs two independent things before an auto-configuration runs: the annotation on - * the class, and a line naming it in {@code META-INF/spring/...AutoConfiguration.imports}. Tests - * that build a context with {@code AutoConfigurations.of(...)} supply the second one themselves, so - * they stay green for a capability that is present in no running application — which is exactly how - * several capabilities in this repository came to be assembled by nothing. - * - *

So this reads the registration file the jar actually ships and asserts both directions: every - * class this leaf means to register is named in it, and every name in it resolves to a class that - * carries {@code @AutoConfiguration}. A rename, a move or a deleted line fails here rather than in - * a deployment that starts and quietly does less than it says. - */ -class MessagingPlatformAutoConfigurationRegistrationTest { - - private static final String IMPORTS_RESOURCE = - "META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports"; - - /** The auto-configurations this leaf publishes. */ - private static final List PUBLISHED_ROOTS = - List.of("dev.caskeleton.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration"); - - @Test - @DisplayName("the shipped registration file names every root this leaf publishes") - void theShippedRegistrationFileNamesEveryRoot() { - assertThat(registeredNames()) - .as("the registration lines this leaf's own jar ships") - .containsAll(PUBLISHED_ROOTS); - } - - @Test - @DisplayName("every registered name resolves to a real Boot auto-configuration") - void everyRegisteredNameResolvesToAnAutoConfiguration() { - for (String name : registeredNames()) { - Class registered; - try { - registered = - Class.forName( - name, - false, - MessagingPlatformAutoConfigurationRegistrationTest.class.getClassLoader()); - } catch (ClassNotFoundException missing) { - throw new AssertionError( - IMPORTS_RESOURCE + " registers " + name + ", which does not exist", missing); - } - assertThat(AnnotatedElementUtils.hasAnnotation(registered, AutoConfiguration.class)) - .as("%s is registered but is not annotated @AutoConfiguration", name) - .isTrue(); - } - } - - /** - * The registration lines this leaf's own resource declares. - * - *

Read from this leaf's source tree rather than from the classpath. {@code - * ClassLoader#getResources} returns every registration file on the test runtime classpath — - * Spring Boot's, springdoc's, and every dependency leaf's — so asserting over that set tests - * other people's modules and fails on their conditional classes. The file below is the one this - * leaf packages, which is the thing this contract is about. - */ - private static List registeredNames() { - Path resource = leafRoot().resolve("src/main/resources/" + IMPORTS_RESOURCE); - assertThat(Files.isRegularFile(resource)).as("%s", resource).isTrue(); - List names; - try { - names = - Files.readAllLines(resource, StandardCharsets.UTF_8).stream() - .map(String::strip) - .filter(line -> !line.isEmpty() && !line.startsWith("#")) - .toList(); - } catch (IOException failure) { - throw new UncheckedIOException("cannot read " + resource, failure); - } - assertThat(names).as("%s registers nothing", resource).isNotEmpty(); - return names; - } - - /** The nearest directory above the test's working directory that ships a registration file. */ - private static Path leafRoot() { - for (Path path = Path.of("").toAbsolutePath(); path != null; path = path.getParent()) { - if (Files.isRegularFile(path.resolve("src/main/resources/" + IMPORTS_RESOURCE))) { - return path; - } - } - throw new IllegalStateException( - "no leaf shipping " + IMPORTS_RESOURCE + " found above " + Path.of("").toAbsolutePath()); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingShutdownLifecycleTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingShutdownLifecycleTest.java deleted file mode 100644 index 4c8d470e..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingShutdownLifecycleTest.java +++ /dev/null @@ -1,78 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.error.MessageBackpressureException; -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.transport.GracefulShutdownCoordinator; -import java.time.Duration; -import java.time.Instant; -import java.util.concurrent.atomic.AtomicReference; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * What a context stop actually does to in-flight messaging work. - * - *

The admission gate and the drain coordinator both existed and neither was driven by anything, - * so a shutdown went straight to destroying beans: publishes in flight, handlers between their side - * effect and their settlement, and no phase in between. - */ -class MessagingShutdownLifecycleTest { - - private static final Instant NOW = Instant.parse("2026-08-15T12:00:00Z"); - - private final MessagingAdmissionController admission = - new MessagingAdmissionController( - new PayloadLimitGuard(PayloadPolicy.defaults()), - new InFlightLimiter(4, Duration.ofMillis(10))); - - private final GracefulShutdownCoordinator drain = - new GracefulShutdownCoordinator(Duration.ofSeconds(30)); - - @Test - @DisplayName("stopping refuses new publishes before waiting for the ones in flight") - void stoppingRefusesNewPublishesFirst() { - MessagingShutdownLifecycle lifecycle = lifecycle(Duration.ofSeconds(30), NOW); - lifecycle.start(); - - lifecycle.stop(); - - assertThatThrownBy(() -> admission.admit("order-events", 16)) - .as("a drain that new work keeps topping up finishes only when the deadline passes") - .isInstanceOf(MessageBackpressureException.class); - assertThat(drain.isAcceptingWork()).isFalse(); - assertThat(lifecycle.isRunning()).isFalse(); - } - - @Test - @DisplayName("a handler that never returns does not hold the process open") - void aLeakedHandlerDoesNotHoldTheProcessOpen() { - // Work that begins and never ends: the drain can only finish by reaching its deadline. - GracefulShutdownCoordinator leaking = new GracefulShutdownCoordinator(Duration.ofMillis(100)); - leaking.tryBeginWork(); - AtomicReference clock = new AtomicReference<>(NOW); - MessagingShutdownLifecycle lifecycle = - new MessagingShutdownLifecycle( - admission, - leaking, - Duration.ofMillis(150), - () -> clock.getAndUpdate(current -> current.plusMillis(100))); - lifecycle.start(); - - lifecycle.stop(); - - assertThat(leaking.inFlight()) - .as("work still running at the deadline is abandoned unsettled, not counted as done") - .isEqualTo(1); - assertThat(leaking.abandonedWorkAtDeadline(clock.get())).isTrue(); - } - - private MessagingShutdownLifecycle lifecycle(Duration drainDeadline, Instant fixed) { - return new MessagingShutdownLifecycle(admission, drain, drainDeadline, () -> fixed); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java deleted file mode 100644 index e611c070..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java +++ /dev/null @@ -1,255 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.schema.EncodedMessagePublisher; -import java.util.Set; -import java.util.concurrent.CompletionStage; -import java.util.stream.Collectors; -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; - -/** - * 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 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 - * running is not off, whatever its bean inventory says. - */ -class MessagingStarterOffContractTest { - - private final ApplicationContextRunner runner = - new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingPlatformRootAutoConfiguration.class)); - - @Test - @DisplayName("present without the switch is on") - void presentWithoutTheSwitchIsOn() { - runner - .withPropertyValues( - "app.messaging.broker=kafka", - "app.messaging.brokers.kafka.type=kafka", - "app.messaging.brokers.kafka.bootstrap-servers[0]=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 - .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()); - - assertThat(platformBeans) - .as("off is a structural fact, not a set of individually-conditioned beans") - .isEmpty(); - }); - } - - @Test - @DisplayName("with the switch off no thread is started") - void offMeansNoThreads() { - Set before = liveThreadNames(); - - 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") - .isEmpty(); - } - - @Test - @DisplayName("on with no broker names the property") - void onWithoutABrokerNamesTheProperty() { - runner - .withPropertyValues("app.messaging.enabled=true") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .rootCause() - .hasMessageContaining("app.messaging.broker")); - } - - @Test - @DisplayName("an unregistered broker is refused, and the message lists what is registered") - void anUnregisteredBrokerIsRefused() { - runner - .withPropertyValues("app.messaging.enabled=true", "app.messaging.broker=carrier-pigeon") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .rootCause() - .hasMessageContaining("registered: [kafka]")); - } - - @Test - @DisplayName("selecting Kafka assembles Kafka") - void selectingKafkaAssemblesOnlyKafka() { - withAPublisher() - .withPropertyValues( - "app.messaging.enabled=true", - "app.messaging.broker=kafka", - "app.messaging.brokers.kafka.type=kafka", - "app.messaging.brokers.kafka.bootstrap-servers[0]=localhost:9092") - .run( - context -> { - assertThat(context).hasNotFailed(); - assertThat(context).hasSingleBean(KafkaMessagingAutoConfiguration.class); - }); - } - - @Test - @DisplayName("MSG-INT-003: a selected transport now assembles a publisher") - void aSelectedTransportAssemblesAPublisher() { - runner - .withPropertyValues( - "app.messaging.enabled=true", - "app.messaging.broker=kafka", - "app.messaging.brokers.kafka.type=kafka", - "app.messaging.brokers.kafka.bootstrap-servers[0]=localhost:9092") - .run( - context -> { - assertThat(context) - .as( - "this asserted the opposite, with the note that C3 would invert it rather" - + " than delete it. Every policy bean was in place and the platform still" - + " could not publish: no configuration produced a MessagePublisher, so" - + " DeadLetterOrchestrator had nothing to depend on." - + " DefaultMessagePublisher existed in messaging-runtime-core the whole" - + " time — the starter did not depend on that leaf.") - .hasNotFailed(); - assertThat(context).hasSingleBean(MessagePublisher.class); - assertThat(context).hasSingleBean(EncodedMessagePublisher.class); - }); - } - - @Test - @DisplayName("a selected publisher uses the Micrometer observation bean when a registry exists") - void selectedPublisherIsObserved() { - runner - .withBean( - io.micrometer.core.instrument.MeterRegistry.class, - io.micrometer.core.instrument.simple.SimpleMeterRegistry::new) - .withPropertyValues( - "app.messaging.enabled=true", - "app.messaging.broker=kafka", - "app.messaging.brokers.kafka.type=kafka", - "app.messaging.brokers.kafka.bootstrap-servers[0]=localhost:9092") - .run( - context -> { - assertThat(context) - .hasSingleBean(dev.caskeleton.messaging.observation.MessagingObservation.class); - Object publisher = context.getBean(MessagePublisher.class); - assertThat(publisher) - .isInstanceOf(dev.caskeleton.messaging.runtime.DefaultMessagePublisher.class); - - try { - java.lang.reflect.Field observation = - publisher.getClass().getDeclaredField("observation"); - observation.setAccessible(true); - assertThat(observation.get(publisher)) - .isSameAs( - context.getBean( - dev.caskeleton.messaging.observation.MessagingObservation.class)); - } catch (ReflectiveOperationException failure) { - throw new LinkageError(failure.getMessage(), failure); - } - }); - } - - @Test - @DisplayName("a selected broker with no address fails at startup, not at the first publish") - void aSelectedBrokerWithNoAddressFailsAtStartup() { - runner - .withPropertyValues("app.messaging.enabled=true", "app.messaging.broker=kafka") - .run( - context -> - assertThat(context) - .as( - "a producer built with no bootstrap servers defaults to localhost:9092 and " - + "fails on the first publish — which is a deployment that starts, " - + "reports healthy, and loses the first message somebody sends") - .hasFailed() - .getFailure() - .rootCause() - .hasMessageContaining("app.messaging.brokers.")); - } - - /** - * The same runner with a publisher supplied by the test. - * - *

Only so the selection cases are about selection. The platform having no production publisher - * of its own is a separate fact with a case of its own above, and letting it fail these two would - * have hidden a defect behind a defect. - */ - private ApplicationContextRunner withAPublisher() { - return runner.withBean( - MessagePublisher.class, - () -> - new MessagePublisher() { - @Override - public CompletionStage publish( - MessageDestination destination, - MessageEnvelope message, - PublishOptions options) { - throw new UnsupportedOperationException("never invoked; this test assembles only"); - } - }); - } - - private static Set liveThreadNames() { - return Thread.getAllStackTraces().keySet().stream() - .filter(Thread::isAlive) - .map(Thread::getName) - .collect(Collectors.toSet()); - } - - private static Set newMessagingThreadsSince(Set before) { - return liveThreadNames().stream() - .filter(name -> !before.contains(name)) - .filter( - name -> { - String lower = name.toLowerCase(java.util.Locale.ROOT); - return lower.contains("kafka") - || lower.contains("messaging") - || lower.contains("outbox"); - }) - .collect(Collectors.toSet()); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/resources/application-invalid-ordering.yml b/src/platforms/messaging/messaging-spring-boot-starter/src/test/resources/application-invalid-ordering.yml deleted file mode 100644 index c332eedf..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/resources/application-invalid-ordering.yml +++ /dev/null @@ -1,11 +0,0 @@ -# A configuration the platform must refuse. -# -# The per-destination in-flight limit exceeds the global one, which means the global limit is not -# a limit at all: a single destination could hold more work in flight than the whole process is -# allowed to. The controller rejects this at construction, so the context fails to start rather -# than running with a ceiling that does not bound anything. -backend: - messaging: - backpressure: - global-limit: 64 - per-destination-limit: 512 diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/resources/application-valid.yml b/src/platforms/messaging/messaging-spring-boot-starter/src/test/resources/application-valid.yml deleted file mode 100644 index b1894f08..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/resources/application-valid.yml +++ /dev/null @@ -1,14 +0,0 @@ -# A configuration the platform accepts. -backend: - messaging: - 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. - global-limit: 512 - per-destination-limit: 64 - shutdown: - # The design's default drain budget. Work still running at the deadline is abandoned - # unsettled so the broker redelivers it. - drain-deadline: 30s - admin: - enabled: false diff --git a/src/platforms/messaging/messaging-testkit/build.gradle b/src/platforms/messaging/messaging-testkit/build.gradle deleted file mode 100644 index 0b4b6577..00000000 --- a/src/platforms/messaging/messaging-testkit/build.gradle +++ /dev/null @@ -1,18 +0,0 @@ -plugins { - id 'ca.platform-module' - id 'me.champeau.jmh' -} - -jmh { - jmhVersion = libs.versions.jmh.get() - includeTests = true -} - -dependencies { - api project(':messaging:messaging-core-api') - api project(':messaging:messaging-policy') - api project(':messaging:messaging-transport-spi') - - api 'org.junit.jupiter:junit-jupiter' - api 'org.assertj:assertj-core' -} diff --git a/src/platforms/messaging/messaging-testkit/gradle.lockfile b/src/platforms/messaging/messaging-testkit/gradle.lockfile deleted file mode 100644 index 1894c4f3..00000000 --- a/src/platforms/messaging/messaging-testkit/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,jmhAnnotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,jmhAnnotationProcessor,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,jmhAnnotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,jmhAnnotationProcessor,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,jmhAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,jmhAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,jmhAnnotationProcessor,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,jmhAnnotationProcessor,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,jmhAnnotationProcessor,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,jmhAnnotationProcessor,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,jmhAnnotationProcessor,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,jmhAnnotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -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=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=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 -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=compileClasspath,jmhCompileClasspath,testCompileClasspath -org.assertj:assertj-core:3.27.7=compileClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,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.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,jmhAnnotationProcessor,jmhCompileClasspath,testAnnotationProcessor,testCompileClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=compileClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=jmhRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=compileClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=compileClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=compileClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=jmhRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=jmhRuntimeClasspath,testRuntimeClasspath -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=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 -org.slf4j:slf4j-api:2.0.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-testkit/src/jmh/java/dev/caskeleton/messaging/testkit/EnvelopeCodecBenchmark.java b/src/platforms/messaging/messaging-testkit/src/jmh/java/dev/caskeleton/messaging/testkit/EnvelopeCodecBenchmark.java deleted file mode 100644 index 4a7135d8..00000000 --- a/src/platforms/messaging/messaging-testkit/src/jmh/java/dev/caskeleton/messaging/testkit/EnvelopeCodecBenchmark.java +++ /dev/null @@ -1,126 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -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.UuidV7; -import dev.caskeleton.messaging.api.header.HeaderName; -import dev.caskeleton.messaging.api.header.HeaderValue; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import java.time.Instant; -import java.util.LinkedHashMap; -import java.util.Map; -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.Measurement; -import org.openjdk.jmh.annotations.Mode; -import org.openjdk.jmh.annotations.OutputTimeUnit; -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 per-message cost the platform adds before any broker is involved. - * - *

This is the number the platform is accountable for. Broker latency dominates any real publish - * and varies with the network, so measuring it would tell you about the test environment; envelope - * construction, header validation, and id generation happen on the calling thread on every message - * and are entirely the platform's. - * - *

Header validation is benchmarked separately from envelope construction because they scale - * differently: construction is constant, while validation is linear in the header count and is the - * part that a caller can make expensive by accident. - */ -@BenchmarkMode(Mode.AverageTime) -@OutputTimeUnit(TimeUnit.NANOSECONDS) -@Warmup(iterations = 3, time = 1) -@Measurement(iterations = 5, time = 1) -@Fork(1) -@State(Scope.Benchmark) -public class EnvelopeCodecBenchmark { - - private Map fewHeaders; - private Map manyHeaders; - private Instant now; - - /** Builds the header maps once, so the benchmark measures validation and not map construction. */ - @Setup - public void setUp() { - now = Instant.parse("2026-08-10T09:15:00Z"); - fewHeaders = headers(3); - manyHeaders = headers(32); - } - - private static Map headers(int count) { - Map headers = new LinkedHashMap<>(); - for (int index = 0; index < count; index++) { - headers.put(new HeaderName("x-app-" + index), new HeaderValue("value-" + index)); - } - return headers; - } - - /** - * Measures monotonic id generation, which every published message pays for. - * - * @param blackhole consumes the result - */ - @Benchmark - public void generateMessageId(Blackhole blackhole) { - blackhole.consume(UuidV7.next()); - } - - /** - * Measures header validation with a typical header count. - * - * @param blackhole consumes the result - */ - @Benchmark - public void validateFewHeaders(Blackhole blackhole) { - blackhole.consume(MessageHeaders.application(fewHeaders)); - } - - /** - * Measures header validation near the count limit, where the cost is linear. - * - * @param blackhole consumes the result - */ - @Benchmark - public void validateManyHeaders(Blackhole blackhole) { - blackhole.consume(MessageHeaders.application(manyHeaders)); - } - - /** - * Measures building one complete envelope. - * - * @param blackhole consumes the result - */ - @Benchmark - public void buildEnvelope(Blackhole blackhole) { - blackhole.consume( - 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.application(fewHeaders), - "{\"orderId\":\"o-1\"}")); - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/BrokerCertificationEvidence.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/BrokerCertificationEvidence.java deleted file mode 100644 index 360e69c1..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/BrokerCertificationEvidence.java +++ /dev/null @@ -1,146 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import java.time.Instant; -import java.util.LinkedHashMap; -import java.util.Map; -import java.util.Objects; - -/** - * One scenario actually exercised against one broker image. - * - *

Coverage used to be a constant: every scenario marked live-broker for both brokers, with the - * suite that "verified" the matrix asserting the contents of that same map. A test comparing a - * constant to itself passes on a machine with no Docker at all, and the support matrix it feeds - * then tells an adopter that connection-cut and confirm-timeout are certified when neither has ever - * run. - * - *

This record is what a lane emits after running. The image reference, commit and observation - * time are provenance: they identify the run for audit/replay. The certification equality gate - * compares the behavioral claim fields and deliberately does not use commit/time as freshness keys. - * - *

{@link #toJson()} and {@link #fromJson(String)} are the same statement in both directions: the - * certification lane writes a line per scenario it proved and the compatibility matrix reads those - * lines back. One line is one object rather than an array, so appending a scenario is an append and - * a diff of two runs is a diff of two sets of lines. - */ -public record BrokerCertificationEvidence( - String adapter, - String brokerImage, - NetworkFaultScenario scenario, - String testId, - String outcome, - String gitCommit, - Instant observedAt) { - - public BrokerCertificationEvidence { - Objects.requireNonNull(adapter, "adapter must not be null"); - Objects.requireNonNull(brokerImage, "brokerImage must not be null"); - Objects.requireNonNull(scenario, "scenario must not be null"); - Objects.requireNonNull(testId, "testId must not be null"); - Objects.requireNonNull(outcome, "outcome must not be null"); - Objects.requireNonNull(gitCommit, "gitCommit must not be null"); - Objects.requireNonNull(observedAt, "observedAt must not be null"); - if (adapter.isBlank() || brokerImage.isBlank() || testId.isBlank()) { - throw new IllegalArgumentException( - "evidence names the adapter, the broker image and the test that produced it"); - } - // The serialised form is a flat object written by hand, so a quote or a backslash in any field - // would produce a manifest line that the reader silently truncates instead of rejecting. Every - // value here is an identifier, an image reference or an instant; none of them needs escaping, - // and a value that does is a sign the caller is recording something else. - requireUnescaped(adapter, "adapter"); - requireUnescaped(brokerImage, "brokerImage"); - requireUnescaped(testId, "testId"); - requireUnescaped(outcome, "outcome"); - requireUnescaped(gitCommit, "gitCommit"); - } - - /** The order fields appear in, shared by the writer and the reader. */ - private static final String[] FIELDS = { - "adapter", "brokerImage", "scenario", "testId", "outcome", "gitCommit", "observedAt" - }; - - /** - * The machine-readable form a release lane writes out. - * - * @return one JSON object on a single line - */ - public String toJson() { - String[] values = { - adapter, brokerImage, scenario.name(), testId, outcome, gitCommit, observedAt.toString() - }; - StringBuilder json = new StringBuilder("{"); - for (int index = 0; index < FIELDS.length; index++) { - if (index > 0) { - json.append(','); - } - json.append('"').append(FIELDS[index]).append("\":\"").append(values[index]).append('"'); - } - return json.append('}').toString(); - } - - /** - * Reads back one line a lane wrote. - * - *

Hand-rolled rather than pulled from a JSON library because this module is the test support - * for a platform whose {@code *-api} leaves carry no dependencies at all, and because the shape - * is fixed by {@link #toJson()} above. A missing or unknown field is refused: evidence that - * cannot be fully read is not partial coverage, it is a manifest nobody can act on. - * - * @param json one line produced by {@link #toJson()} - * @return the evidence that line records - */ - public static BrokerCertificationEvidence fromJson(String json) { - Objects.requireNonNull(json, "json must not be null"); - Map fields = parse(json.trim()); - for (String field : FIELDS) { - if (!fields.containsKey(field)) { - throw new IllegalArgumentException( - "certification evidence is missing '" + field + "': " + json); - } - } - if (fields.size() != FIELDS.length) { - throw new IllegalArgumentException( - "certification evidence carries fields this release does not define: " + fields.keySet()); - } - return new BrokerCertificationEvidence( - fields.get("adapter"), - fields.get("brokerImage"), - NetworkFaultScenario.byName(fields.get("scenario")), - fields.get("testId"), - fields.get("outcome"), - fields.get("gitCommit"), - Instant.parse(fields.get("observedAt"))); - } - - private static Map parse(String json) { - if (json.length() < 2 || json.charAt(0) != '{' || json.charAt(json.length() - 1) != '}') { - throw new IllegalArgumentException("certification evidence is not a JSON object: " + json); - } - Map fields = new LinkedHashMap<>(); - String body = json.substring(1, json.length() - 1); - int cursor = 0; - while (cursor < body.length()) { - int keyStart = body.indexOf('"', cursor); - if (keyStart < 0) { - break; - } - int keyEnd = body.indexOf('"', keyStart + 1); - int valueStart = body.indexOf('"', keyEnd + 1); - int valueEnd = valueStart < 0 ? -1 : body.indexOf('"', valueStart + 1); - if (keyEnd < 0 || valueStart < 0 || valueEnd < 0) { - throw new IllegalArgumentException("certification evidence is truncated: " + json); - } - fields.put(body.substring(keyStart + 1, keyEnd), body.substring(valueStart + 1, valueEnd)); - cursor = valueEnd + 1; - } - return fields; - } - - private static void requireUnescaped(String value, String field) { - if (value.indexOf('"') >= 0 || value.indexOf('\\') >= 0) { - throw new IllegalArgumentException( - field + " must not contain a quote or a backslash: " + field + "='" + value + "'"); - } - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/BrokerFailureMatrix.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/BrokerFailureMatrix.java deleted file mode 100644 index 5f27cdc1..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/BrokerFailureMatrix.java +++ /dev/null @@ -1,167 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import java.util.LinkedHashMap; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; - -/** - * Which failure scenarios each adapter has actually been run against. - * - *

Records coverage, not capability. An adapter that has never been run under {@code - * connection-cut-after-write} may well handle it correctly — the point is that nobody knows, and a - * support matrix that does not distinguish "verified" from "probably fine" is how an unproven - * adapter ends up in production. - * - *

A Stable adapter must cover every scenario. That rule is enforced by a test rather than - * documented, because a promotion to Stable is exactly the moment the gap would otherwise be - * overlooked. - */ -public final class BrokerFailureMatrix { - - private final Map> coverage = new LinkedHashMap<>(); - - /** How a scenario is covered for one adapter. */ - public enum Coverage { - /** Run against a deterministic harness. */ - DETERMINISTIC, - /** Run against a live broker in a container. */ - LIVE_BROKER, - /** Not run. */ - NOT_COVERED - } - - /** - * Records how one adapter covers one scenario. - * - * @param adapter the adapter module name - * @param scenario the scenario - * @param level how it is covered - * @return this matrix - */ - public BrokerFailureMatrix record(String adapter, NetworkFaultScenario scenario, Coverage level) { - Objects.requireNonNull(scenario, "scenario must not be null"); - Objects.requireNonNull(level, "level must not be null"); - if (adapter == null || adapter.isBlank()) { - throw new IllegalArgumentException("adapter must not be blank"); - } - coverage.computeIfAbsent(adapter, key -> new LinkedHashMap<>()).put(scenario.name(), level); - return this; - } - - /** - * Returns how an adapter covers a scenario. - * - * @param adapter the adapter module name - * @param scenario the scenario - * @return the coverage level, {@link Coverage#NOT_COVERED} when nothing was recorded - */ - public Coverage coverageOf(String adapter, NetworkFaultScenario scenario) { - return Optional.ofNullable(coverage.get(adapter)) - .map(scenarios -> scenarios.get(scenario.name())) - .orElse(Coverage.NOT_COVERED); - } - - /** - * Returns the scenarios an adapter has never been run against. - * - * @param adapter the adapter module name - * @return the uncovered scenarios - */ - public List gapsFor(String adapter) { - return NetworkFaultScenario.all().stream() - .filter(scenario -> coverageOf(adapter, scenario) == Coverage.NOT_COVERED) - .toList(); - } - - /** - * Reports whether an adapter has been run against a live broker at all. - * - * @param adapter the adapter module name - * @return true when at least one scenario has live-broker evidence - */ - public boolean hasLiveBrokerCoverage(String adapter) { - return NetworkFaultScenario.all().stream() - .anyMatch(scenario -> coverageOf(adapter, scenario) == Coverage.LIVE_BROKER); - } - - /** - * Reports whether every scenario is backed by live-broker evidence or an explicitly approved gap. - * - *

This is the Stable certification predicate. A single live scenario is not certification, and - * an absent scenario is not silently converted into an approved exception. - * - * @param adapter the adapter module name - * @param approvedGaps gaps reviewed and accepted independently of this matrix - * @return true when every scenario is explained by evidence or an approved gap - */ - public boolean hasCertificationCoverage( - String adapter, java.util.Set approvedGaps) { - Objects.requireNonNull(approvedGaps, "approvedGaps must not be null"); - return NetworkFaultScenario.all().stream() - .allMatch( - scenario -> - coverageOf(adapter, scenario) == Coverage.LIVE_BROKER - || approvedGaps.contains(scenario)); - } - - /** - * Reports whether an adapter covers every scenario. - * - * @param adapter the adapter module name - * @return true when nothing is uncovered - */ - public boolean isComplete(String adapter) { - return gapsFor(adapter).isEmpty(); - } - - /** - * Returns the adapters this matrix has any record for. - * - * @return the recorded adapter names - */ - public List adapters() { - return List.copyOf(coverage.keySet()); - } - - /** - * Builds a matrix from evidence a lane actually produced. - * - *

Anything with no evidence is {@link Coverage#NOT_COVERED}. A hard-coded matrix marked every - * scenario as live-broker coverage for both brokers, and the suite that checked it asserted the - * same constants, so the whole claim passed on a machine with no Docker. A scenario is covered - * because a test ran it against a broker, not because somebody wrote the constant. - * - * @param evidence what the certification lane observed - */ - public static BrokerFailureMatrix from( - java.util.Collection evidence) { - Objects.requireNonNull(evidence, "evidence must not be null"); - BrokerFailureMatrix matrix = new BrokerFailureMatrix(); - for (BrokerCertificationEvidence observed : evidence) { - requireOutcomeMatchesExpectation(observed); - matrix.record(observed.adapter(), observed.scenario(), Coverage.LIVE_BROKER); - } - return matrix; - } - - /** - * Refuses evidence whose observed outcome contradicts the scenario it claims to cover. - * - *

Nothing compared the two, so a run that reported a definite rejection where the scenario - * says the outcome is unknowable counted as coverage of that scenario. That is worse than no - * evidence: it certifies the adapter for exactly the behaviour it got wrong, and the support - * matrix then tells an adopter the case is handled. - */ - private static void requireOutcomeMatchesExpectation(BrokerCertificationEvidence observed) { - String expected = observed.scenario().expectation().name(); - if (!expected.equals(observed.outcome())) { - throw new IllegalArgumentException( - "%s recorded %s for %s, which expects %s; a run that disagrees with the scenario is a" - .formatted( - observed.adapter(), observed.outcome(), observed.scenario().name(), expected) - + " failing certification, not coverage of it (%s)".formatted(observed.testId())); - } - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CertifiedEvidence.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CertifiedEvidence.java deleted file mode 100644 index 423bd4be..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CertifiedEvidence.java +++ /dev/null @@ -1,99 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import java.io.IOException; -import java.io.InputStream; -import java.nio.charset.StandardCharsets; -import java.util.List; -import java.util.Map; -import java.util.Set; - -/** - * The fault scenarios this repository's certification lane has actually exercised. - * - *

Read from a manifest a run produced, not from a list somebody typed. It was the list: an - * author added a line and the compatibility matrix, the cross-broker suite and the support matrix - * all believed it, on a machine that may never have started a container. "Certified against a live - * broker" then meant "a developer wrote that down", which is the one thing a certification claim - * must not mean. - * - *

The manifest is committed because a release claim has to survive the build that produced it — - * a matrix that reads {@code build/} answers differently on a clean checkout. What stops it from - * being hand-written again is the gate: {@code verifyMessagingCertificationEvidence} runs the lane - * against a real broker and refuses to pass when this file claims a scenario the run did not - * produce. Editing the file without running the lane fails the build; running the lane rewrites the - * file. - * - *

An absent or empty manifest is not an error here. It means no scenario has evidence, so every - * scenario is {@link BrokerFailureMatrix.Coverage#NOT_COVERED} and every Stable claim that depends - * on evidence fails — which is the correct reading of "nothing has been run". - */ -public final class CertifiedEvidence { - - /** Where the certification lane writes what it proved, and where the matrix reads it. */ - public static final String MANIFEST_RESOURCE = "/messaging/broker-certification-evidence.jsonl"; - - private static final List RECORDED = load(); - - private static final Map> APPROVED_GAPS = - Map.of("messaging-kafka", Set.of(NetworkFaultScenario.CONNECTION_REFUSED)); - - private CertifiedEvidence() {} - - /** - * Returns what the certification lane recorded. - * - * @return the evidence this repository can show - */ - public static List recorded() { - return RECORDED; - } - - /** - * Returns gaps that were deliberately accepted after review rather than inferred from missing - * evidence. - * - * @param adapter the adapter module name - * @return the explicit approved gaps for that adapter - */ - public static Set approvedGaps(String adapter) { - return APPROVED_GAPS.getOrDefault(adapter, Set.of()); - } - - /** - * Returns the scenarios an adapter has no evidence for. - * - *

Named explicitly so the gap is a fact in the build rather than a silent absence. - * - * @param adapter the adapter module name - * @return the uncovered scenarios - */ - public static List knownGaps(String adapter) { - Set covered = - recorded().stream() - .filter(evidence -> evidence.adapter().equals(adapter)) - .map(BrokerCertificationEvidence::scenario) - .collect(java.util.stream.Collectors.toUnmodifiableSet()); - return NetworkFaultScenario.all().stream() - .filter(scenario -> !covered.contains(scenario)) - .toList(); - } - - private static List load() { - try (InputStream manifest = CertifiedEvidence.class.getResourceAsStream(MANIFEST_RESOURCE)) { - if (manifest == null) { - return List.of(); - } - return new String(manifest.readAllBytes(), StandardCharsets.UTF_8) - .lines() - .map(String::trim) - .filter(line -> !line.isEmpty()) - .map(BrokerCertificationEvidence::fromJson) - .toList(); - } catch (IOException failure) { - // Not swallowed into "no evidence": a manifest that exists and cannot be read is a broken - // build, and reporting it as an absence would quietly demote every adapter instead. - throw new IllegalStateException( - "could not read the broker certification manifest " + MANIFEST_RESOURCE, failure); - } - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CompatibilityMatrix.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CompatibilityMatrix.java deleted file mode 100644 index 482d9b41..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CompatibilityMatrix.java +++ /dev/null @@ -1,109 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import java.util.List; -import java.util.Map; -import java.util.Objects; - -/** - * The certified broker versions and support grade for every adapter. - * - *

Held as code with a test over it rather than as a document, because a support matrix that - * lives only in prose drifts the first time an adapter is added. The test asserts the rules the - * design fixes: a Stable adapter must run the shared contract and be certified against a live - * broker, and an Experimental adapter must be disabled by default. - * - *

The certification claim is derived from lane evidence rather than declared beside the grade, - * so an adapter cannot be promoted by editing a boolean. - */ -public final class CompatibilityMatrix { - - private CompatibilityMatrix() {} - - /** The support grade an adapter has earned. */ - public enum SupportGrade { - /** Passes the shared adapter contract unchanged. */ - STABLE, - - /** Contract coverage is still being proven; disabled by default. */ - EXPERIMENTAL, - - /** Adapter SPI only; outside the supported set. */ - EXTENSION - } - - /** - * One certified adapter. - * - * @param adapter the module name - * @param brokerVersions the broker versions the adapter is certified against - * @param grade the support grade - * @param runsSharedContract whether the module runs {@link MessagingAdapterContract} - * @param enabledByDefault whether the adapter is active without an explicit opt-in - */ - public record Entry( - String adapter, - List brokerVersions, - SupportGrade grade, - boolean runsSharedContract, - boolean enabledByDefault) { - - /** - * 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 grade, 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 - */ - public boolean hasLiveBrokerCertification() { - return BrokerFailureMatrix.from(CertifiedEvidence.recorded()) - .hasCertificationCoverage(adapter, CertifiedEvidence.approvedGaps(adapter)); - } - - public Entry { - Objects.requireNonNull(grade, "grade must not be null"); - Objects.requireNonNull(brokerVersions, "brokerVersions must not be null"); - if (adapter == null || adapter.isBlank()) { - throw new IllegalArgumentException("adapter must not be blank"); - } - if (brokerVersions.isEmpty()) { - throw new IllegalArgumentException("an adapter must certify at least one broker version"); - } - brokerVersions = List.copyOf(brokerVersions); - } - } - - 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"), SupportGrade.STABLE, true, true)); - - /** - * Returns every certified adapter. - * - * @return the entries, keyed by module name - */ - public static Map entries() { - return ENTRIES; - } - - /** - * Returns one adapter's entry. - * - * @param adapter the module name - * @return the entry - */ - public static Entry of(String adapter) { - Entry entry = ENTRIES.get(adapter); - if (entry == null) { - throw new IllegalArgumentException("adapter is not in the compatibility matrix: " + adapter); - } - return entry; - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/ContractAssertions.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/ContractAssertions.java deleted file mode 100644 index 2bed0f11..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/ContractAssertions.java +++ /dev/null @@ -1,51 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import static org.assertj.core.api.Assertions.assertThat; - -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; - -/** Assertions every adapter's contract run shares. */ -public final class ContractAssertions { - - private ContractAssertions() {} - - /** - * Asserts a publish confirmed with real broker evidence. - * - * @param result the publish outcome - */ - public static void assertConfirmed(PublishResult result) { - assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED); - assertThat(result.evidence().brokerAccepted()).isTrue(); - assertThat(result.evidence().confirmationLevel()).isNotEqualTo(ConfirmationLevel.NONE); - assertThat(result.evidence().transmission()).isEqualTo(TransmissionEvidence.TRANSMITTED); - } - - /** - * Asserts a publish reported ambiguity without claiming any confirmation. - * - * @param result the publish outcome - */ - public static void assertAmbiguous(PublishResult result) { - assertThat(result.completion()).isEqualTo(PublishCompletion.AMBIGUOUS); - assertThat(result.evidence().confirmationLevel()).isEqualTo(ConfirmationLevel.NONE); - assertThat(result.evidence().brokerAccepted()).isFalse(); - assertThat(result.evidence().transmission()) - .isEqualTo(TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED); - assertThat(result.mayHaveBeenStored()).isTrue(); - } - - /** - * Asserts a publish was refused before anything left the process. - * - * @param result the publish outcome - */ - public static void assertRejectedLocally(PublishResult result) { - assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); - assertThat(result.evidence().transmission()).isEqualTo(TransmissionEvidence.NOT_TRANSMITTED); - assertThat(result.failure()).isPresent(); - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/ContractMessage.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/ContractMessage.java deleted file mode 100644 index 7c9239fe..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/ContractMessage.java +++ /dev/null @@ -1,87 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -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.schema.EncodedMessage; -import java.nio.charset.StandardCharsets; -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; - -/** - * The standard messages every adapter contract run uses. - * - *

Fixed rather than random so that a failure in one adapter can be compared byte for byte - * against another. The oversized variant exists to prove the payload limit is enforced locally: an - * adapter that lets it reach the broker turns a deterministic rejection into a broker-specific - * error. - * - * @param envelope the encoded envelope to publish - */ -public record ContractMessage(MessageEnvelope envelope) { - - private static final Instant FIXED_TIME = Instant.parse("2026-08-10T09:15:00Z"); - - public ContractMessage { - Objects.requireNonNull(envelope, "envelope must not be null"); - } - - /** - * Returns the standard small event. - * - * @return a contract message under every limit - */ - public static ContractMessage orderCreated() { - return of("{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8)); - } - - /** - * Returns a message one byte above the one mebibyte portability limit. - * - * @return an oversized contract message - */ - public static ContractMessage oversized() { - return of(new byte[1_048_577]); - } - - /** - * Builds a contract message around explicit payload bytes. - * - * @param payload the encoded payload - * @return a contract message - */ - public static ContractMessage of(byte[] payload) { - return new ContractMessage( - new MessageEnvelope<>( - MessageId.newId(), - new MessageType("order.created"), - new SchemaVersion(1), - FIXED_TIME, - Optional.of(FIXED_TIME), - new ProducerId("contract-suite"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.of("acct-1"), - Optional.of("acct-1"), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - new EncodedMessage(payload, ContentType.JSON, Optional.empty()))); - } - - /** - * Returns the logical identity of this message. - * - * @return the message id - */ - public MessageId messageId() { - return envelope.messageId(); - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/DockerAvailability.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/DockerAvailability.java deleted file mode 100644 index 542eb36a..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/DockerAvailability.java +++ /dev/null @@ -1,35 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -/** - * Reports whether a container runtime is reachable. - * - *

Live-broker suites are guarded on this rather than assumed. A developer machine or a build - * agent without Docker should skip them with a stated reason, not fail with a connection error that - * looks like a product defect — and the release gate checks separately that the suites actually ran - * where they were supposed to. - */ -public final class DockerAvailability { - - private static final boolean AVAILABLE = probe(); - - private DockerAvailability() {} - - /** - * Reports whether a container runtime is available. - * - * @return true when containers can be started - */ - public static boolean isAvailable() { - return AVAILABLE; - } - - private static boolean probe() { - try { - Class factory = Class.forName("org.testcontainers.DockerClientFactory"); - Object instance = factory.getMethod("instance").invoke(null); - return (boolean) factory.getMethod("isDockerAvailable").invoke(instance); - } catch (ReflectiveOperationException | RuntimeException exception) { - return false; - } - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/FaultController.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/FaultController.java deleted file mode 100644 index 3cc62f01..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/FaultController.java +++ /dev/null @@ -1,26 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -/** - * Injects the faults an adapter must survive. - * - *

Each fault targets an acknowledgement, not the operation itself. That is the point: - * losing a confirm is what makes an outcome ambiguous, and an adapter is only trustworthy if it - * reports the ambiguity rather than guessing which way it went. - */ -public interface FaultController { - - /** Makes the next publish complete without a broker confirmation. */ - void dropPublishConfirmation(); - - /** Makes the next settlement complete without a broker confirmation. */ - void dropSettlementConfirmation(); - - /** Makes publishes to the dead letter destination fail. */ - void failDeadLetterPublish(); - - /** Makes the next publish be refused outright by the broker. */ - void rejectPublish(); - - /** Clears every injected fault. */ - void reset(); -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/HandleOutcome.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/HandleOutcome.java deleted file mode 100644 index 460030fb..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/HandleOutcome.java +++ /dev/null @@ -1,14 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -/** What the contract suite's handler decides for a drained delivery. */ -public enum HandleOutcome { - - /** The handler succeeded and the platform may settle. */ - SUCCESS, - - /** The handler failed transiently and the message should be retried. */ - RETRY, - - /** The handler failed permanently and the message should be dead lettered. */ - DEAD_LETTER -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/MessagingAdapterContract.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/MessagingAdapterContract.java deleted file mode 100644 index d96d9d5d..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/MessagingAdapterContract.java +++ /dev/null @@ -1,139 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.publish.PublishResult; -import java.util.List; -import org.junit.jupiter.api.Test; - -/** - * The behaviour every adapter must exhibit, regardless of broker. - * - *

This suite is the platform's actual definition of "supported". A broker is Stable when it - * passes these unchanged — not when it has an adapter that compiles. Each test pins one of the - * guarantees the design refuses to weaken: ambiguity is reported rather than guessed, settlement - * follows handler success, logical identity survives retry and dead lettering, and a source is - * never acknowledged on the strength of a dead letter publish that failed. - */ -public abstract class MessagingAdapterContract { - - /** - * Returns a fresh harness for one test. - * - * @return the adapter harness under test - */ - protected abstract MessagingAdapterHarness harness(); - - @Test - void publishesAndConfirms() { - try (MessagingAdapterHarness harness = harness()) { - PublishResult result = join(harness.publish(ContractMessage.orderCreated())); - - ContractAssertions.assertConfirmed(result); - } - } - - @Test - void returnsAmbiguousWhenConfirmIsLost() { - try (MessagingAdapterHarness harness = harness()) { - harness.faults().dropPublishConfirmation(); - - PublishResult result = join(harness.publish(ContractMessage.orderCreated())); - - ContractAssertions.assertAmbiguous(result); - } - } - - @Test - void redeliversWhenSettlementIsLost() { - try (MessagingAdapterHarness harness = harness()) { - ContractMessage message = ContractMessage.orderCreated(); - join(harness.publish(message)); - harness.faults().dropSettlementConfirmation(); - - List first = harness.drain(HandleOutcome.SUCCESS); - assertThat(first) - .singleElement() - .satisfies( - delivery -> { - assertThat(delivery.messageId()).isEqualTo(message.messageId()); - assertThat(delivery.settled()).isFalse(); - }); - - List second = harness.drain(HandleOutcome.SUCCESS); - assertThat(second) - .singleElement() - .satisfies( - delivery -> { - assertThat(delivery.messageId()).isEqualTo(message.messageId()); - assertThat(delivery.attempt()).isEqualTo(2); - assertThat(delivery.redelivered()).isTrue(); - }); - } - } - - @Test - void preservesMessageIdAcrossRetryAndDlq() { - try (MessagingAdapterHarness harness = harness()) { - ContractMessage message = ContractMessage.orderCreated(); - join(harness.publish(message)); - MessageId original = message.messageId(); - - List retried = harness.drain(HandleOutcome.RETRY); - assertThat(retried) - .singleElement() - .extracting(ObservedDelivery::messageId) - .isEqualTo(original); - - List redelivered = harness.drain(HandleOutcome.DEAD_LETTER); - assertThat(redelivered) - .singleElement() - .extracting(ObservedDelivery::messageId) - .isEqualTo(original); - - assertThat(harness.deadLettered()).containsExactly(original); - } - } - - @Test - void keepsSourceUnsettledWhenDlqPublishFails() { - try (MessagingAdapterHarness harness = harness()) { - ContractMessage message = ContractMessage.orderCreated(); - join(harness.publish(message)); - harness.faults().failDeadLetterPublish(); - - List observed = harness.drain(HandleOutcome.DEAD_LETTER); - - assertThat(observed).singleElement().extracting(ObservedDelivery::settled).isEqualTo(false); - assertThat(harness.deadLettered()).isEmpty(); - assertThat(harness.unsettled()).contains(message.messageId()); - } - } - - @Test - void rejectsOversizedPayloadBeforeTransport() { - try (MessagingAdapterHarness harness = harness()) { - PublishResult result = join(harness.publish(ContractMessage.oversized())); - - ContractAssertions.assertRejectedLocally(result); - } - } - - @Test - void stopsAcceptingNewWorkDuringShutdown() { - try (MessagingAdapterHarness harness = harness()) { - assertThat(harness.isAcceptingWork()).isTrue(); - - harness.beginShutdown(); - - assertThat(harness.isAcceptingWork()).isFalse(); - PublishResult result = join(harness.publish(ContractMessage.orderCreated())); - ContractAssertions.assertRejectedLocally(result); - } - } - - private static PublishResult join(java.util.concurrent.CompletionStage stage) { - return stage.toCompletableFuture().join(); - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/MessagingAdapterHarness.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/MessagingAdapterHarness.java deleted file mode 100644 index a17f10e7..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/MessagingAdapterHarness.java +++ /dev/null @@ -1,73 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.publish.PublishResult; -import java.util.List; -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. Each broker answers those three questions with - * its own machinery, and the contract only passes if the answers match. - */ -public interface MessagingAdapterHarness extends AutoCloseable { - - /** - * Returns the broker under test. - * - * @return the broker name - */ - String brokerName(); - - /** - * Returns the fault injector for this harness. - * - * @return the fault controller - */ - FaultController faults(); - - /** - * Publishes one contract message. - * - * @param message the message to publish - * @return a stage completing with the outcome and evidence - */ - CompletionStage publish(ContractMessage message); - - /** - * Delivers everything currently pending to a handler that returns the given outcome. - * - * @param outcome what the handler decides for each delivery - * @return what the harness observed, in delivery order - */ - List drain(HandleOutcome outcome); - - /** - * Returns the identities that reached the dead letter destination. - * - * @return dead lettered message identities - */ - List deadLettered(); - - /** - * Returns the identities still unsettled at the source. - * - * @return unsettled message identities - */ - List unsettled(); - - /** Begins a graceful drain. */ - void beginShutdown(); - - /** - * Reports whether the harness still accepts new work. - * - * @return true until shutdown begins - */ - boolean isAcceptingWork(); - - @Override - void close(); -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/NetworkFaultScenario.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/NetworkFaultScenario.java deleted file mode 100644 index 403c954f..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/NetworkFaultScenario.java +++ /dev/null @@ -1,151 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import java.time.Duration; -import java.util.Objects; -import java.util.Optional; - -/** - * A named network fault, and the outcome an adapter must report while it is active. - * - *

The expected outcome is part of the scenario rather than left to each test, because the whole - * value of a fault suite is that every adapter answers the same way. A scenario that let each - * adapter declare its own expectation would pass while the adapters disagreed — which is exactly - * the situation the shared contract exists to catch. - * - *

The distinction across these scenarios is what evidence survives. A connection refused before - * any bytes leave proves nothing was published; a connection cut after the frame was written proves - * nothing at all, and the honest answer is ambiguous. - * - * @param name the scenario name, used in reports - * @param phase when the fault is injected relative to the publish - * @param expectation what the adapter must report - * @param duration how long the fault holds, when it is time-bounded - * @param rationale why this outcome is the correct one - */ -public record NetworkFaultScenario( - String name, - Phase phase, - Expectation expectation, - Optional duration, - String rationale) { - - /** When a fault takes effect relative to the operation under test. */ - public enum Phase { - /** Before any bytes leave the client. */ - BEFORE_TRANSMISSION, - /** After the frame was written but before the acknowledgement. */ - AFTER_TRANSMISSION, - /** While the consumer holds an unsettled delivery. */ - DURING_SETTLEMENT - } - - /** What the adapter must report under a fault. */ - public enum Expectation { - /** A definite rejection, with no ambiguity. */ - REJECTED, - /** An unknown outcome, reported as such rather than guessed. */ - AMBIGUOUS, - /** The message is redelivered because it was never settled. */ - REDELIVERED - } - - public NetworkFaultScenario { - Objects.requireNonNull(phase, "phase must not be null"); - Objects.requireNonNull(expectation, "expectation must not be null"); - Objects.requireNonNull(duration, "duration must not be null"); - if (name == null || name.isBlank()) { - throw new IllegalArgumentException("name must not be blank"); - } - if (rationale == null || rationale.isBlank()) { - throw new IllegalArgumentException( - "a scenario without a rationale cannot be reviewed; state why this outcome is correct"); - } - } - - /** The connection is refused before the publish frame is written. */ - public static final NetworkFaultScenario CONNECTION_REFUSED = - new NetworkFaultScenario( - "connection-refused", - Phase.BEFORE_TRANSMISSION, - Expectation.REJECTED, - Optional.empty(), - "no bytes left the client, so the broker cannot hold the message and a retry cannot " - + "duplicate it"); - - /** The connection is cut after the frame is written but before the confirm. */ - public static final NetworkFaultScenario CONNECTION_CUT_AFTER_WRITE = - new NetworkFaultScenario( - "connection-cut-after-write", - Phase.AFTER_TRANSMISSION, - Expectation.AMBIGUOUS, - Optional.empty(), - "the broker may have stored the message and only the confirm was lost; reporting a " - + "rejection here is what turns one lost confirmation into two orders"); - - /** The confirm is delayed past the publish deadline. */ - public static final NetworkFaultScenario CONFIRM_TIMEOUT = - new NetworkFaultScenario( - "confirm-timeout", - Phase.AFTER_TRANSMISSION, - Expectation.AMBIGUOUS, - Optional.of(Duration.ofSeconds(10)), - "a timeout is the absence of evidence, not evidence of absence"); - - /** The broker becomes unreachable while a delivery is unsettled. */ - public static final NetworkFaultScenario SETTLEMENT_LOST = - new NetworkFaultScenario( - "settlement-lost", - Phase.DURING_SETTLEMENT, - Expectation.REDELIVERED, - Optional.empty(), - "an unsettled delivery is redelivered by design; the handler must be idempotent rather " - + "than the platform pretending the settlement landed"); - - /** High latency without a disconnect, which slows confirms without losing them. */ - public static final NetworkFaultScenario HIGH_LATENCY = - new NetworkFaultScenario( - "high-latency", - Phase.AFTER_TRANSMISSION, - Expectation.AMBIGUOUS, - Optional.of(Duration.ofSeconds(30)), - "latency above the publish deadline is indistinguishable from a lost confirm at the " - + "moment the decision has to be made"); - - /** - * Resolves a scenario by the name a recorded run wrote down. - * - *

Evidence travels as text, so the read side has to answer what a name that this release does - * not define means. It means the manifest describes a scenario the code no longer has, and - * treating it as coverage would credit an adapter for a fault nobody can reproduce — so it is - * refused rather than skipped. - * - * @param name the scenario name as it appears in recorded evidence - * @return the scenario - */ - public static NetworkFaultScenario byName(String name) { - return all().stream() - .filter(scenario -> scenario.name().equals(name)) - .findFirst() - .orElseThrow( - () -> - new IllegalArgumentException( - "no fault scenario is named '" - + name - + "'; evidence for a scenario this release does not define is coverage of" - + " nothing")); - } - - /** - * Returns every scenario the shared fault suite runs. - * - * @return the scenarios - */ - public static java.util.List all() { - return java.util.List.of( - CONNECTION_REFUSED, - CONNECTION_CUT_AFTER_WRITE, - CONFIRM_TIMEOUT, - SETTLEMENT_LOST, - HIGH_LATENCY); - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/ObservedDelivery.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/ObservedDelivery.java deleted file mode 100644 index 79e01a4c..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/ObservedDelivery.java +++ /dev/null @@ -1,23 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import dev.caskeleton.messaging.api.MessageId; -import java.util.Objects; - -/** - * What the harness observed about one delivery attempt. - * - * @param messageId the logical identity delivered - * @param attempt the attempt number, counting the first delivery as one - * @param redelivered whether the broker flagged this as a redelivery - * @param settled whether the source was settled after handling - */ -public record ObservedDelivery( - MessageId messageId, int attempt, boolean redelivered, boolean settled) { - - public ObservedDelivery { - Objects.requireNonNull(messageId, "messageId must not be null"); - if (attempt < 1) { - throw new IllegalArgumentException("attempt counts the first delivery as 1"); - } - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl b/src/platforms/messaging/messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl deleted file mode 100644 index 5867276a..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl +++ /dev/null @@ -1,4 +0,0 @@ -{"adapter":"messaging-kafka","brokerImage":"apache/kafka@sha256:bff074a5d0051dbc0bbbcd25b045bb1fe84833ec0d3c7c965d1797dd289ec88f","scenario":"confirm-timeout","testId":"KafkaBrokerCertificationIT#aConfirmThatNeverArrivesIsReportedAsAmbiguousAndTheRecordIsThere","outcome":"AMBIGUOUS","gitCommit":"8d69e599a376e4db29fdf7b96e06fa457ba6ace1","observedAt":"2026-11-07T04:05:39.857063221Z"} -{"adapter":"messaging-kafka","brokerImage":"apache/kafka@sha256:bff074a5d0051dbc0bbbcd25b045bb1fe84833ec0d3c7c965d1797dd289ec88f","scenario":"connection-cut-after-write","testId":"KafkaBrokerCertificationIT#aConnectionCutAfterTheWriteIsReportedAsAmbiguous","outcome":"AMBIGUOUS","gitCommit":"8d69e599a376e4db29fdf7b96e06fa457ba6ace1","observedAt":"2026-11-07T04:05:43.917138801Z"} -{"adapter":"messaging-kafka","brokerImage":"apache/kafka@sha256:bff074a5d0051dbc0bbbcd25b045bb1fe84833ec0d3c7c965d1797dd289ec88f","scenario":"high-latency","testId":"KafkaBrokerCertificationIT#latencyBeyondThePublishDeadlineIsReportedAsAmbiguous","outcome":"AMBIGUOUS","gitCommit":"8d69e599a376e4db29fdf7b96e06fa457ba6ace1","observedAt":"2026-11-07T04:05:29.018486328Z"} -{"adapter":"messaging-kafka","brokerImage":"apache/kafka@sha256:bff074a5d0051dbc0bbbcd25b045bb1fe84833ec0d3c7c965d1797dd289ec88f","scenario":"settlement-lost","testId":"KafkaBrokerCertificationIT#aDeliveryLostBeforeSettlementIsRedelivered","outcome":"REDELIVERED","gitCommit":"8d69e599a376e4db29fdf7b96e06fa457ba6ace1","observedAt":"2026-11-07T04:05:51.014447Z"} diff --git a/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CertifiedEvidenceTest.java b/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CertifiedEvidenceTest.java deleted file mode 100644 index a8eacb4d..00000000 --- a/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CertifiedEvidenceTest.java +++ /dev/null @@ -1,127 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import java.io.IOException; -import java.io.InputStream; -import java.nio.charset.StandardCharsets; -import java.util.List; -import org.junit.jupiter.api.Test; - -/** - * Holds the line between evidence a run produced and evidence a developer typed. - * - *

The distinction is the whole of the finding this suite exists for. A committed list of - * scenarios reads exactly like a manifest and passes exactly the same assertions, so the only thing - * that can tell them apart is where the values come from — which is what these tests check. - */ -class CertifiedEvidenceTest { - - @Test - void everyRecordedScenarioIsALineTheCertificationLaneWrote() throws IOException { - List manifestLines = manifest(); - - assertThat(manifestLines) - .as("the certification lane writes this file; nothing else may") - .isNotEmpty(); - assertThat(CertifiedEvidence.recorded()) - .as("coverage is read from the manifest, not from a list somebody maintained beside it") - .containsExactlyElementsOf( - manifestLines.stream().map(BrokerCertificationEvidence::fromJson).toList()); - } - - @Test - void everyClaimNamesTheImageItRanAgainst() { - assertThat(CertifiedEvidence.recorded()) - .allSatisfy( - evidence -> - assertThat(evidence.brokerImage()) - .as("a floating tag makes a certification unrepeatable") - .contains(":") - .doesNotEndWith(":latest")); - } - - @Test - void everyClaimNamesTheTestThatProducedIt() { - assertThat(CertifiedEvidence.recorded()) - .allSatisfy(evidence -> assertThat(evidence.testId()).contains("#")); - } - - @Test - void aScenarioWithNoLineInTheManifestIsAGapRatherThanAnAbsence() { - 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-artemis")) - .as("an adapter no lane has run has every scenario as a gap") - .containsExactlyElementsOf(NetworkFaultScenario.all()); - } - - @Test - void anEvidenceLineRoundTripsThroughItsSerialisedForm() { - BrokerCertificationEvidence evidence = - new BrokerCertificationEvidence( - "messaging-kafka", - "apache/kafka:4.1.0", - NetworkFaultScenario.CONFIRM_TIMEOUT, - "SomeIT#someScenario", - "AMBIGUOUS", - "0123456789abcdef", - java.time.Instant.parse("2026-08-15T00:00:00Z")); - - assertThat(BrokerCertificationEvidence.fromJson(evidence.toJson())).isEqualTo(evidence); - } - - @Test - void aManifestLineMissingAFieldIsRefusedRatherThanPartiallyRead() { - assertThatThrownBy( - () -> - BrokerCertificationEvidence.fromJson( - "{\"adapter\":\"messaging-kafka\",\"scenario\":\"confirm-timeout\"}")) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("brokerImage"); - } - - @Test - void aManifestLineNamingAScenarioThisReleaseDoesNotDefineIsRefused() { - assertThatThrownBy( - () -> - BrokerCertificationEvidence.fromJson( - "{\"adapter\":\"messaging-kafka\",\"brokerImage\":\"apache/kafka:4.1.0\"," - + "\"scenario\":\"disk-full\",\"testId\":\"X#y\",\"outcome\":\"AMBIGUOUS\"," - + "\"gitCommit\":\"abc\",\"observedAt\":\"2026-08-15T00:00:00Z\"}")) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("disk-full"); - } - - @Test - void aValueThatWouldBreakTheManifestIsRefusedWhenTheEvidenceIsBuilt() { - assertThatThrownBy( - () -> - new BrokerCertificationEvidence( - "messaging-kafka", - "apache/kafka:4.1.0", - NetworkFaultScenario.CONFIRM_TIMEOUT, - "Some\"IT#someScenario", - "AMBIGUOUS", - "abc", - java.time.Instant.parse("2026-08-15T00:00:00Z"))) - .as("a quote would truncate the line the release gate reads back") - .isInstanceOf(IllegalArgumentException.class); - } - - private static List manifest() throws IOException { - try (InputStream stream = - CertifiedEvidence.class.getResourceAsStream(CertifiedEvidence.MANIFEST_RESOURCE)) { - assertThat(stream) - .as("%s is missing; no lane has produced evidence", CertifiedEvidence.MANIFEST_RESOURCE) - .isNotNull(); - return new String(stream.readAllBytes(), StandardCharsets.UTF_8) - .lines() - .map(String::trim) - .filter(line -> !line.isEmpty()) - .toList(); - } - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CompatibilityMatrixTest.java b/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CompatibilityMatrixTest.java deleted file mode 100644 index 2bff244f..00000000 --- a/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CompatibilityMatrixTest.java +++ /dev/null @@ -1,140 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import java.lang.reflect.Method; -import java.util.Arrays; -import java.util.List; -import org.junit.jupiter.api.Test; - -class CompatibilityMatrixTest { - - private static final List REQUIRED_CONTRACT_TESTS = - List.of( - "publishesAndConfirms", - "returnsAmbiguousWhenConfirmIsLost", - "redeliversWhenSettlementIsLost", - "preservesMessageIdAcrossRetryAndDlq", - "keepsSourceUnsettledWhenDlqPublishFails", - "rejectsOversizedPayloadBeforeTransport", - "stopsAcceptingNewWorkDuringShutdown"); - - @Test - void everyStableAdapterRunsTheSharedContract() { - assertThat(CompatibilityMatrix.entries().values()) - .filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE) - .isNotEmpty() - .allSatisfy(entry -> assertThat(entry.runsSharedContract()).isTrue()); - } - - @Test - void noExperimentalAdapterIsEnabledByDefault() { - assertThat(CompatibilityMatrix.entries().values()) - .filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.EXPERIMENTAL) - .allSatisfy(entry -> assertThat(entry.enabledByDefault()).isFalse()); - } - - @Test - void theStableSetIsExactlyWhatALaneHasCertified() { - assertThat(CompatibilityMatrix.entries().values()) - .filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE) - .extracting(CompatibilityMatrix.Entry::adapter) - .containsExactly("messaging-kafka"); - } - - @Test - void oneLiveScenarioCannotSatisfyAStableCertification() { - String adapter = "messaging-partial"; - BrokerFailureMatrix partial = - new BrokerFailureMatrix() - .record( - adapter, - NetworkFaultScenario.all().get(0), - BrokerFailureMatrix.Coverage.LIVE_BROKER); - - assertThat(partial.hasCertificationCoverage(adapter, java.util.Set.of())).isFalse(); - } - - @Test - void everyStableAdapterHasOnlyExplicitlyApprovedEvidenceGaps() { - assertThat(CompatibilityMatrix.entries().values()) - .filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE) - .allSatisfy( - entry -> - assertThat(CertifiedEvidence.approvedGaps(entry.adapter())) - .containsExactlyInAnyOrderElementsOf( - CertifiedEvidence.knownGaps(entry.adapter()))); - } - - @Test - void kafkaIsCertifiedAgainstWhatTheLanesRun() { - assertThat(CompatibilityMatrix.of("messaging-kafka").brokerVersions()) - .as( - "the fixtures pin apache/kafka:4.1.0 and the locked client is 4.1.1; 4.2/4.3 were" - + " declared and never executed") - .containsExactly("4.1"); - } - - @Test - void theSharedContractStillDeclaresEveryRequiredTest() { - List declared = - Arrays.stream(MessagingAdapterContract.class.getDeclaredMethods()) - .filter(method -> method.isAnnotationPresent(org.junit.jupiter.api.Test.class)) - .map(Method::getName) - .toList(); - - assertThat(declared).containsExactlyInAnyOrderElementsOf(REQUIRED_CONTRACT_TESTS); - } - - @Test - void anUnknownAdapterIsNotSilentlyTreatedAsSupported() { - assertThatThrownBy(() -> CompatibilityMatrix.of("messaging-artemis")) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void anAdapterMustCertifyAtLeastOneBrokerVersion() { - assertThatThrownBy( - () -> - new CompatibilityMatrix.Entry( - "messaging-x", List.of(), CompatibilityMatrix.SupportGrade.STABLE, true, true)) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void everyStableAdapterIsCertifiedAgainstALiveBroker() { - assertThat(CompatibilityMatrix.entries().values()) - .filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE) - .isNotEmpty() - .allSatisfy( - entry -> - assertThat(entry.hasLiveBrokerCertification()) - .as( - "%s claims Stable, so a container-backed suite must exercise a real broker", - entry.adapter()) - .isTrue()); - } - - @Test - void noExperimentalAdapterClaimsLiveBrokerCertification() { - assertThat(CompatibilityMatrix.entries().values()) - .filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.EXPERIMENTAL) - .allSatisfy(entry -> assertThat(entry.hasLiveBrokerCertification()).isFalse()); - } - - @Test - void anAdapterWithoutEvidenceCannotBeCalledStable() { - CompatibilityMatrix.Entry undeclared = - new CompatibilityMatrix.Entry( - "messaging-artemis", - List.of("2.42"), - CompatibilityMatrix.SupportGrade.STABLE, - true, - false); - - assertThat(undeclared.hasLiveBrokerCertification()) - .as("promoting an adapter used to be a boolean an author could set beside the tier") - .isFalse(); - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CrossBrokerContractSuite.java b/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CrossBrokerContractSuite.java deleted file mode 100644 index be044b0f..00000000 --- a/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CrossBrokerContractSuite.java +++ /dev/null @@ -1,135 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.testkit.BrokerFailureMatrix.Coverage; -import java.util.List; -import org.junit.jupiter.api.Test; - -/** - * The release gate over the whole adapter set. - * - *

Every other suite proves one adapter behaves correctly. This one proves the adapters agree — - * that the same fault produces the same reported outcome whichever broker is underneath, and that - * nothing has been promoted to Stable without the evidence that tier claims. - * - *

It asserts on the coverage records rather than re-running the fault suites, because it is the - * bookkeeping that rots: an adapter's own tests keep passing while the matrix quietly - * stops reflecting what was actually run. - */ -class CrossBrokerContractSuite { - - /** - * The matrix built from the evidence this repository actually has. - * - *

A hard-coded map marking every scenario live-broker for both brokers would leave the - * assertions below comparing that map to itself: the suite passes on a machine with no Docker, - * and the support matrix it feeds tells adopters that connection-cut and confirm-timeout are - * certified when neither has ever run. - * - *

{@link CertifiedEvidence#recorded()} is the manifest the certification lane wrote, so the - * assertions below fail when the shipped claim exceeds what a run produced — which is the failure - * they were written to catch. - */ - private final BrokerFailureMatrix matrix = BrokerFailureMatrix.from(CertifiedEvidence.recorded()); - - private static List stableAdapters() { - return CompatibilityMatrix.entries().values().stream() - .filter(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE) - .map(CompatibilityMatrix.Entry::adapter) - .toList(); - } - - @Test - void everyStableAdapterCoversEveryFaultScenario() { - // The gaps are named rather than asserted empty. A Stable adapter with unrun scenarios is the - // current, honest state; asserting emptiness here would only reinstate the self-declaration. - assertThat(stableAdapters()).isNotEmpty(); - assertThat(matrix.gapsFor("messaging-kafka")) - .as("what the Kafka lanes have not exercised against a live broker") - .isEqualTo(CertifiedEvidence.knownGaps("messaging-kafka")); - } - - @Test - void evidenceThatDisagreesWithItsScenarioIsNotCoverage() { - BrokerCertificationEvidence contradicting = - new BrokerCertificationEvidence( - "messaging-kafka", - "apache/kafka:4.1.0", - NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE, - "SomeIT#someScenario", - "REJECTED", - "repository-local", - java.time.Instant.parse("2026-08-15T00:00:00Z")); - - org.assertj.core.api.Assertions.assertThatThrownBy( - () -> BrokerFailureMatrix.from(List.of(contradicting))) - .as("certifying an adapter for the behaviour it got wrong is worse than no evidence") - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("AMBIGUOUS"); - } - - @Test - void aScenarioWithNoEvidenceIsNotCovered() { - assertThat(matrix.coverageOf("messaging-kafka", NetworkFaultScenario.CONNECTION_REFUSED)) - .as("no lane runs this today, and NOT_COVERED is the only honest answer") - .isEqualTo(Coverage.NOT_COVERED); - } - - @Test - void anEvidencedScenarioIsCovered() { - assertThat( - matrix.coverageOf("messaging-kafka", NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE)) - .as("the certification lane cuts the connection after the write against a container") - .isEqualTo(Coverage.LIVE_BROKER); - } - - @Test - void noExperimentalAdapterClaimsLiveBrokerFaultCoverage() { - List experimental = - CompatibilityMatrix.entries().values().stream() - .filter(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.EXPERIMENTAL) - .map(CompatibilityMatrix.Entry::adapter) - .toList(); - - assertThat(experimental) - .allSatisfy( - adapter -> - assertThat(NetworkFaultScenario.all()) - .allSatisfy( - scenario -> - assertThat(matrix.coverageOf(adapter, scenario)) - .isNotEqualTo(Coverage.LIVE_BROKER))); - } - - @Test - void aFaultThatWasNeverRecordedReadsAsUncoveredRatherThanPassing() { - assertThat(matrix.coverageOf("messaging-artemis", NetworkFaultScenario.CONFIRM_TIMEOUT)) - .isEqualTo(Coverage.NOT_COVERED); - } - - @Test - void everyAdapterAgreesThatAWriteFollowedByALostConfirmIsAmbiguous() { - assertThat(NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE.expectation()) - .as("the shared expectation is what stops two adapters answering differently") - .isEqualTo(NetworkFaultScenario.Expectation.AMBIGUOUS); - assertThat(NetworkFaultScenario.CONFIRM_TIMEOUT.expectation()) - .isEqualTo(NetworkFaultScenario.Expectation.AMBIGUOUS); - } - - @Test - void aFailureBeforeTransmissionIsTheOnlyOneReportedAsRejected() { - assertThat(NetworkFaultScenario.all()) - .filteredOn(scenario -> scenario.expectation() == NetworkFaultScenario.Expectation.REJECTED) - .allSatisfy( - scenario -> - assertThat(scenario.phase()) - .isEqualTo(NetworkFaultScenario.Phase.BEFORE_TRANSMISSION)); - } - - @Test - void everyScenarioStatesWhyItsOutcomeIsCorrect() { - assertThat(NetworkFaultScenario.all()) - .allSatisfy(scenario -> assertThat(scenario.rationale()).isNotBlank()); - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/InMemoryHarnessContractTest.java b/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/InMemoryHarnessContractTest.java deleted file mode 100644 index 5cd052a0..00000000 --- a/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/InMemoryHarnessContractTest.java +++ /dev/null @@ -1,22 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import org.junit.jupiter.api.Nested; - -/** - * Runs the shared adapter contract against the in-memory harness. - * - *

This is the contract testing itself. Every broker adapter adds the same nested class over its - * own harness, so a guarantee can only be weakened by editing the contract, where the change is - * visible, rather than by an adapter quietly not implementing it. - */ -class InMemoryHarnessContractTest { - - @Nested - class Contract extends MessagingAdapterContract { - - @Override - protected MessagingAdapterHarness harness() { - return InMemoryMessagingHarness.create(); - } - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/InMemoryMessagingHarness.java b/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/InMemoryMessagingHarness.java deleted file mode 100644 index 9f3c9c0c..00000000 --- a/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/InMemoryMessagingHarness.java +++ /dev/null @@ -1,260 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import dev.caskeleton.messaging.api.MessageId; -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.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; - -/** - * A deterministic harness that exists only to prove the contract suite itself is sound. - * - *

It is not a production adapter and must never become one. Its value is that it has no broker - * to hide behind: if a contract test passes here and fails on Kafka, the difference is in the - * adapter, not in the test. - */ -final class InMemoryMessagingHarness implements MessagingAdapterHarness { - - private static final int MAX_PAYLOAD_BYTES = 1_048_576; - - private final Deque pending = new ArrayDeque<>(); - private final List deadLetters = new ArrayList<>(); - private final Set unsettled = new LinkedHashSet<>(); - private final Faults faults = new Faults(); - - private boolean shuttingDown; - - private InMemoryMessagingHarness() {} - - static InMemoryMessagingHarness create() { - return new InMemoryMessagingHarness(); - } - - @Override - public String brokerName() { - return "in-memory"; - } - - @Override - public FaultController faults() { - return faults; - } - - @Override - public CompletionStage publish(ContractMessage message) { - if (shuttingDown) { - return completed( - rejected("SHUTTING_DOWN", "the consumer is draining and accepts no new work")); - } - if (message.envelope().payload().size() > MAX_PAYLOAD_BYTES) { - return completed( - rejected("PAYLOAD_TOO_LARGE", "encoded payload exceeds " + MAX_PAYLOAD_BYTES + " bytes")); - } - if (faults.consumeRejectPublish()) { - return completed(rejected("BROKER_REJECTED", "the broker refused the publish")); - } - - if (faults.consumeDropPublishConfirmation()) { - return completed( - new PublishResult( - PublishCompletion.AMBIGUOUS, - PublishEvidence.ambiguous(), - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, - Duration.ofMillis(1), - Optional.of( - FailureDescriptor.of( - FailureCategory.AMBIGUOUS, - "CONFIRM_LOST", - "the publish confirmation was not received")))); - } - - pending.addLast(new Pending(message.messageId(), 1, false)); - return completed( - new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK), - RoutingOutcome.ROUTED, - Optional.empty(), - 1, - Duration.ofMillis(1), - Optional.empty())); - } - - @Override - public List drain(HandleOutcome outcome) { - List batch = new ArrayList<>(pending); - pending.clear(); - - List observed = new ArrayList<>(); - for (Pending delivery : batch) { - boolean settled = - switch (outcome) { - case SUCCESS -> settleAfterSuccess(delivery); - case RETRY -> { - unsettled.add(delivery.messageId()); - redeliver(delivery); - yield false; - } - case DEAD_LETTER -> deadLetter(delivery); - }; - observed.add( - new ObservedDelivery( - delivery.messageId(), delivery.attempt(), delivery.redelivered(), settled)); - } - return List.copyOf(observed); - } - - /** - * Settles the source only when the settlement itself was confirmed. - * - *

An unconfirmed settlement leaves the message in flight, which is what produces the - * redelivery the contract expects. - */ - private boolean settleAfterSuccess(Pending delivery) { - if (faults.consumeDropSettlementConfirmation()) { - unsettled.add(delivery.messageId()); - redeliver(delivery); - return false; - } - unsettled.remove(delivery.messageId()); - return true; - } - - /** - * Publishes to the dead letter destination before settling the source. - * - *

When that publish fails the source stays unsettled and in flight. Acknowledging it here - * would destroy the last copy of a message the dead letter destination never received. - */ - private boolean deadLetter(Pending delivery) { - if (faults.deadLetterPublishFails()) { - unsettled.add(delivery.messageId()); - redeliver(delivery); - return false; - } - deadLetters.add(delivery.messageId()); - unsettled.remove(delivery.messageId()); - return true; - } - - private void redeliver(Pending delivery) { - pending.addLast(new Pending(delivery.messageId(), 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 rejected(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))); - } - - private static CompletionStage completed(PublishResult result) { - return CompletableFuture.completedFuture(result); - } - - /** One message waiting to be delivered. */ - private record Pending(MessageId messageId, int attempt, boolean redelivered) {} - - /** One-shot fault flags, consumed by the operation they target. */ - 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/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/MessagingDocumentationContractTest.java b/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/MessagingDocumentationContractTest.java deleted file mode 100644 index cc5755ba..00000000 --- a/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/MessagingDocumentationContractTest.java +++ /dev/null @@ -1,141 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import static org.assertj.core.api.Assertions.assertThat; - -import java.io.IOException; -import java.nio.file.Files; -import java.nio.file.Path; -import java.util.List; -import org.junit.jupiter.api.Test; - -/** - * Checks that the shipped documentation still describes the code. - * - *

Docs rot silently. A support matrix claiming an adapter is Stable outlives the day someone - * demoted it, and nothing fails — the tests still pass, the build is green, and the only signal is - * an operator making a decision on a page that stopped being true months ago. - * - *

The assertions are deliberately narrow: they check the claims a reader would act on, not - * prose. Asserting on wording would make every edit a test failure and the check would be deleted. - */ -class MessagingDocumentationContractTest { - - private static Path docsRoot() { - Path candidate = Path.of("").toAbsolutePath(); - while (candidate != null && !Files.isDirectory(candidate.resolve("docs/messaging"))) { - candidate = candidate.getParent(); - } - if (candidate == null) { - throw new IllegalStateException("could not locate docs/messaging from the test cwd"); - } - return candidate.resolve("docs/messaging"); - } - - private static String read(String name) { - try { - return Files.readString(docsRoot().resolve(name)); - } catch (IOException failure) { - throw new IllegalStateException("could not read " + name, failure); - } - } - - @Test - void everyDocumentTheSupportMatrixPromisesExists() { - List expected = - List.of( - "support-matrix.md", - "delivery-guarantees.md", - "retry-dlq-redrive.md", - "outbox-inbox.md", - "security.md", - "operations.md", - "configuration-reference.md", - "experimental-policy.md", - "migration-guide.md"); - - assertThat(expected) - .allSatisfy(name -> assertThat(Files.exists(docsRoot().resolve(name))).isTrue()); - } - - @Test - void theSupportMatrixNamesExactlyTheAdaptersTheCodeCallsStable() { - String matrix = read("support-matrix.md"); - - CompatibilityMatrix.entries().values().stream() - .filter(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE) - .forEach(entry -> assertThat(matrix).contains(brokerLabel(entry.adapter()))); - } - - @Test - void theSupportMatrixDoesNotCallAnExperimentalAdapterStable() { - String matrix = read("support-matrix.md"); - - CompatibilityMatrix.entries().values().stream() - .filter(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.EXPERIMENTAL) - .forEach( - entry -> - assertThat(matrix) - .as("%s is Experimental in code", entry.adapter()) - .doesNotContain("| %s | Stable".formatted(brokerLabel(entry.adapter())))); - } - - @Test - void theDocumentedKafkaVersionsMatchWhatTheCodeCertifies() { - String matrix = read("support-matrix.md"); - - CompatibilityMatrix.of("messaging-kafka") - .brokerVersions() - .forEach(version -> assertThat(matrix).contains(version)); - } - - @Test - void theUnsupportedListStillNamesTheTwoConstantsThatDoNotExist() { - String matrix = read("support-matrix.md"); - - assertThat(matrix) - .as("a reader must be able to confirm the platform never offers these") - .contains("EXACTLY_ONCE") - .contains("GLOBAL"); - } - - @Test - void noEnumConstantTheDocsDenyActuallyExists() { - assertThat( - java.util.Arrays.stream( - dev.caskeleton.messaging.api.delivery.DeliveryGuarantee.values()) - .map(Enum::name)) - .doesNotContain("EXACTLY_ONCE"); - assertThat( - java.util.Arrays.stream(dev.caskeleton.messaging.api.delivery.OrderingScope.values()) - .map(Enum::name)) - .doesNotContain("GLOBAL"); - } - - @Test - void theExperimentalPolicyStatesThatExperimentalIsOffByDefault() { - assertThat(read("experimental-policy.md")).contains("false"); - } - - @Test - void everyDocumentHasContent() { - assertThat( - List.of( - "support-matrix.md", - "delivery-guarantees.md", - "retry-dlq-redrive.md", - "outbox-inbox.md", - "security.md", - "operations.md", - "configuration-reference.md", - "experimental-policy.md", - "migration-guide.md")) - .allSatisfy(name -> assertThat(read(name).length()).isGreaterThan(500)); - } - - private static String brokerLabel(String adapter) { - return switch (adapter) { - case "messaging-kafka" -> "Kafka"; - default -> adapter; - }; - } -} diff --git a/src/platforms/messaging/messaging-transport-spi/build.gradle b/src/platforms/messaging/messaging-transport-spi/build.gradle deleted file mode 100644 index 55c8be51..00000000 --- a/src/platforms/messaging/messaging-transport-spi/build.gradle +++ /dev/null @@ -1,8 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') - api project(':messaging:messaging-policy') -} diff --git a/src/platforms/messaging/messaging-transport-spi/gradle.lockfile b/src/platforms/messaging/messaging-transport-spi/gradle.lockfile deleted file mode 100644 index d74807c4..00000000 --- a/src/platforms/messaging/messaging-transport-spi/gradle.lockfile +++ /dev/null @@ -1,82 +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.50.0=annotationProcessor,checkstyle,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.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -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.6.1=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.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty=compileClasspath,runtimeClasspath diff --git a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/DefaultMessagingRuntimeRegistry.java b/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/DefaultMessagingRuntimeRegistry.java deleted file mode 100644 index 5bdc2dec..00000000 --- a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/DefaultMessagingRuntimeRegistry.java +++ /dev/null @@ -1,254 +0,0 @@ -package dev.caskeleton.messaging.transport; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.time.Duration; -import java.time.Instant; -import java.util.ArrayList; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.concurrent.ConcurrentHashMap; -import java.util.concurrent.atomic.AtomicBoolean; -import java.util.concurrent.atomic.AtomicInteger; - -/** - * Reference-counted runtime generations with an atomic swap on install. - * - *

Rotation works by publishing a new generation and letting the old one drain. The map entry is - * replaced atomically so a caller either sees the old generation or the new one, never a - * half-rebuilt connection pool; the retired generation stays open until its last lease closes, so - * an in-flight publish still gets its confirm on the connection it started on. - * - *

A drain deadline bounds that wait. Without one, a single leaked lease would pin a revoked - * credential open indefinitely, which turns a rotation into a security non-event. - */ -public final class DefaultMessagingRuntimeRegistry - implements MessagingRuntimeRegistry, AutoCloseable { - - private static final Duration DEFAULT_DRAIN_DEADLINE = Duration.ofSeconds(30); - - private final Map current = new ConcurrentHashMap<>(); - private final List draining = new ArrayList<>(); - private final Duration drainDeadline; - - /** Creates a registry with the default thirty second drain deadline. */ - public DefaultMessagingRuntimeRegistry() { - this(DEFAULT_DRAIN_DEADLINE); - } - - /** - * Creates a registry with an explicit drain deadline. - * - * @param drainDeadline how long a retired generation may wait for its leases - */ - public DefaultMessagingRuntimeRegistry(Duration drainDeadline) { - Objects.requireNonNull(drainDeadline, "drainDeadline must not be null"); - if (drainDeadline.isNegative()) { - throw new IllegalArgumentException("drainDeadline must not be negative"); - } - this.drainDeadline = drainDeadline; - } - - @Override - public void install(MessagingRuntime runtime) { - install(runtime, Instant.now()); - } - - /** - * Installs a generation, stamping the retirement of the one it replaces. - * - * @param now when the rotation happened - */ - public void install(MessagingRuntime runtime, Instant now) { - Objects.requireNonNull(runtime, "runtime must not be null"); - Objects.requireNonNull(now, "now must not be null"); - Generation retired = current.put(runtime.brokerName(), new Generation(runtime)); - if (retired == null) { - return; - } - retired.retire(now); - if (!retired.closeIfIdle()) { - synchronized (draining) { - draining.add(retired); - } - } - } - - @Override - public MessagingRuntimeLease acquire(String brokerName) { - Objects.requireNonNull(brokerName, "brokerName must not be null"); - Generation generation = - current.computeIfPresent( - brokerName, - (key, value) -> { - value.leases.incrementAndGet(); - return value; - }); - if (generation == null) { - throw new MessagingConfigurationException( - "RUNTIME_NOT_INSTALLED", "no messaging runtime is installed for broker " + brokerName); - } - return new Lease(generation); - } - - /** - * Closes retired generations whose own drain deadline has passed. - * - *

Per generation, not per call. A single {@code retiredAt} supplied by the caller and applied - * to the whole draining list gives a generation retired thirty seconds ago and one retired a - * moment ago the same deadline, and a generation that has already gone idle and closed stays in - * the list, counted as draining forever. - * - *

Called by the platform's scheduler. Exposed as a plain method taking the current instant so - * that deadline behaviour is testable without sleeping. - * - * @param now the current instant - * @return how many generations were force closed - */ - public int closeExpiredDraining(Instant now) { - Objects.requireNonNull(now, "now must not be null"); - List expired; - synchronized (draining) { - // Anything already closed leaves the list too: it is not draining, and leaving it there is - // what made drainingCount report work that had finished. - draining.removeIf(Generation::isClosed); - expired = - draining.stream().filter(generation -> generation.expiredAt(now, drainDeadline)).toList(); - draining.removeAll(expired); - } - int closed = 0; - for (Generation generation : expired) { - if (generation.forceClose()) { - closed++; - } - } - return closed; - } - - /** - * Closes every generation this registry holds, current and draining. - * - *

Nothing closed the current generation. The registry only ever closed what a rotation had - * retired, so a process that shut down without rotating left its broker connections to the JVM's - * exit — which drops unflushed producer batches and leaves consumer sessions to time out on the - * broker instead of leaving the group. - * - *

Each generation closes exactly once, whichever path reaches it first: a drain that finished - * during shutdown must not be closed a second time here, because a second close on a broker - * client is where "already closed" exceptions come from during an otherwise clean stop. - */ - @Override - public void close() { - List pending; - synchronized (draining) { - pending = List.copyOf(draining); - draining.clear(); - } - for (Generation generation : pending) { - generation.forceClose(); - } - for (String brokerName : List.copyOf(current.keySet())) { - Generation generation = current.remove(brokerName); - if (generation != null) { - generation.forceClose(); - } - } - } - - /** - * Returns how many retired generations are still draining. - * - * @return the draining count - */ - public int drainingCount() { - synchronized (draining) { - return draining.size(); - } - } - - /** One installed generation plus its live lease count. */ - private static final class Generation { - - private final MessagingRuntime runtime; - private final AtomicInteger leases = new AtomicInteger(); - private final AtomicBoolean retired = new AtomicBoolean(); - private final AtomicBoolean closed = new AtomicBoolean(); - - /** - * When this generation was retired. - * - *

Each generation carries its own. The deadline check took one {@code retiredAt} from the - * caller and applied it to every draining generation, so a rotation during a drain either - * force-closed a generation that had just retired or gave an old one a fresh deadline — - * depending on which timestamp the caller happened to pass. - */ - private volatile Instant retiredAt; - - private Generation(MessagingRuntime runtime) { - this.runtime = runtime; - } - - void retire(Instant now) { - retiredAt = now; - retired.set(true); - } - - boolean expiredAt(Instant now, java.time.Duration drainDeadline) { - Instant since = retiredAt; - return since != null && !now.isBefore(since.plus(drainDeadline)); - } - - /** - * Closes the runtime when it is retired and no lease remains. - * - * @return true when this call closed the runtime - */ - boolean closeIfIdle() { - if (retired.get() && leases.get() == 0) { - return forceClose(); - } - return false; - } - - boolean isClosed() { - return closed.get(); - } - - boolean forceClose() { - if (closed.compareAndSet(false, true)) { - runtime.close(); - return true; - } - return false; - } - - void release() { - if (leases.decrementAndGet() == 0) { - closeIfIdle(); - } - } - } - - /** A single borrowed reference, safe to close more than once. */ - private static final class Lease implements MessagingRuntimeLease { - - private final Generation generation; - private final AtomicBoolean released = new AtomicBoolean(); - - private Lease(Generation generation) { - this.generation = generation; - } - - @Override - public MessagingRuntime runtime() { - return generation.runtime; - } - - @Override - public void close() { - if (released.compareAndSet(false, true)) { - generation.release(); - } - } - } -} diff --git a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/GracefulShutdownCoordinator.java b/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/GracefulShutdownCoordinator.java deleted file mode 100644 index 0f4d3bf5..00000000 --- a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/GracefulShutdownCoordinator.java +++ /dev/null @@ -1,139 +0,0 @@ -package dev.caskeleton.messaging.transport; - -import java.time.Duration; -import java.time.Instant; -import java.util.Objects; -import java.util.concurrent.atomic.AtomicBoolean; -import java.util.concurrent.atomic.AtomicInteger; - -/** - * Drains in-flight work without starting any more. - * - *

Shutdown has three phases, in order: stop accepting new work, let what is running finish, then - * close. Skipping the middle phase is what produces the classic shutdown bug — a handler is - * interrupted between its side effect and its settlement, so the message is redelivered and the - * effect happens twice. - * - *

The deadline exists because draining cannot be unbounded: a stuck handler would otherwise hold - * the process open forever. Work still running at the deadline is abandoned unsettled, so - * the broker redelivers it rather than the platform pretending it completed. - * - *

No retry attempt is created once draining begins. Starting a fresh attempt during shutdown - * guarantees it will be abandoned at the deadline. - */ -public final class GracefulShutdownCoordinator { - - private final Duration drainDeadline; - private final AtomicBoolean draining = new AtomicBoolean(); - private final AtomicInteger inFlight = new AtomicInteger(); - - private volatile Instant drainStartedAt; - - /** - * Creates a coordinator. - * - * @param drainDeadline how long to wait for in-flight work - */ - public GracefulShutdownCoordinator(Duration drainDeadline) { - Objects.requireNonNull(drainDeadline, "drainDeadline must not be null"); - if (drainDeadline.isNegative()) { - throw new IllegalArgumentException("drainDeadline must not be negative"); - } - this.drainDeadline = drainDeadline; - } - - /** - * Tries to start one unit of work. - * - * @return true when the work may start; false once draining has begun - */ - public boolean tryBeginWork() { - if (draining.get()) { - return false; - } - inFlight.incrementAndGet(); - if (draining.get()) { - inFlight.decrementAndGet(); - return false; - } - return true; - } - - /** - * Records that one unit of work finished. - * - *

Clamped at zero. A double release used to drive the count negative, and a negative in-flight - * count reports the drain as complete while work is still running — which is exactly when the - * process shuts down underneath it. - */ - public void endWork() { - inFlight.updateAndGet(current -> current > 0 ? current - 1 : current); - } - - /** - * Begins draining. - * - * @param now the current instant - */ - public void beginDrain(Instant now) { - Objects.requireNonNull(now, "now must not be null"); - if (draining.compareAndSet(false, true)) { - drainStartedAt = now; - } - } - - /** - * Reports whether new work is still accepted. - * - * @return true until draining begins - */ - public boolean isAcceptingWork() { - return !draining.get(); - } - - /** - * Reports whether a retry attempt may be created. - * - * @return true until draining begins - */ - public boolean mayCreateRetryAttempt() { - return !draining.get(); - } - - /** - * Returns how many units of work are still running. - * - * @return the in-flight count - */ - public int inFlight() { - return inFlight.get(); - } - - /** - * Reports whether the drain has finished, either by completing or by hitting its deadline. - * - * @param now the current instant - * @return true when it is safe to close - */ - public boolean isDrained(Instant now) { - Objects.requireNonNull(now, "now must not be null"); - if (!draining.get()) { - return false; - } - if (inFlight.get() == 0) { - return true; - } - Instant startedAt = drainStartedAt; - return startedAt != null && !now.isBefore(startedAt.plus(drainDeadline)); - } - - /** - * Reports whether work was abandoned because the deadline passed. - * - * @param now the current instant - * @return true when in-flight work outlived the deadline - */ - public boolean abandonedWorkAtDeadline(Instant now) { - return isDrained(now) && inFlight.get() > 0; - } -} diff --git a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingRuntime.java b/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingRuntime.java deleted file mode 100644 index 4155ce5c..00000000 --- a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingRuntime.java +++ /dev/null @@ -1,43 +0,0 @@ -package dev.caskeleton.messaging.transport; - -/** - * One immutable generation of a broker's connections, credentials, and topology view. - * - *

Credential rotation and topology reload replace a whole generation rather than mutating a live - * one. In-flight publishes keep the generation they started on, which is what makes a rotation - * invisible to callers instead of a burst of authentication failures. - */ -public interface MessagingRuntime extends AutoCloseable { - - /** - * Returns the broker this runtime serves. - * - * @return the broker name - */ - String brokerName(); - - /** - * Returns the generation number, increasing with each replacement. - * - * @return the generation - */ - long generation(); - - /** - * Returns the transport bound to this generation. - * - * @return the transport - */ - MessagingTransport transport(); - - /** - * Reports whether this generation has been closed. - * - * @return true once closed - */ - boolean isClosed(); - - /** Closes this generation's resources. Must be idempotent. */ - @Override - void close(); -} diff --git a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingRuntimeLease.java b/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingRuntimeLease.java deleted file mode 100644 index 2977936e..00000000 --- a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingRuntimeLease.java +++ /dev/null @@ -1,22 +0,0 @@ -package dev.caskeleton.messaging.transport; - -/** - * A borrowed reference to a runtime generation. - * - *

Holding a lease pins the generation open. A caller that has begun a publish keeps the runtime - * it started on even after a rotation installs a newer one, so a rotation never yanks a connection - * out from under an in-flight confirm. - */ -public interface MessagingRuntimeLease extends AutoCloseable { - - /** - * Returns the pinned runtime. - * - * @return the runtime generation - */ - MessagingRuntime runtime(); - - /** Releases the reference. Must be idempotent. */ - @Override - void close(); -} diff --git a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingRuntimeRegistry.java b/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingRuntimeRegistry.java deleted file mode 100644 index edf990de..00000000 --- a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingRuntimeRegistry.java +++ /dev/null @@ -1,20 +0,0 @@ -package dev.caskeleton.messaging.transport; - -/** Holds the current runtime generation for each broker. */ -public interface MessagingRuntimeRegistry { - - /** - * Installs a new generation, retiring any previous one. - * - * @param runtime the new generation - */ - void install(MessagingRuntime runtime); - - /** - * Borrows the current generation for a broker. - * - * @param brokerName the broker name - * @return a lease that pins the generation until closed - */ - MessagingRuntimeLease acquire(String brokerName); -} diff --git a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingTransport.java b/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingTransport.java deleted file mode 100644 index 5a3abd11..00000000 --- a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingTransport.java +++ /dev/null @@ -1,57 +0,0 @@ -package dev.caskeleton.messaging.transport; - -import dev.caskeleton.messaging.api.destination.DestinationCapabilities; -import dev.caskeleton.messaging.api.destination.DestinationName; -import java.util.concurrent.CompletionStage; - -/** - * The SPI every broker adapter implements. - * - *

No method returns a native client object. Handing back a raw producer or channel would let an - * application bypass destination policy, payload limits, and the settlement ordering in one call, - * and the resulting code would silently stop working the moment the broker changed. - */ -public interface MessagingTransport extends AutoCloseable { - - /** - * Publishes one already-encoded message. - * - * @param request the publish request - * @return a stage completing with the transport outcome - */ - CompletionStage publish(TransportPublishRequest request); - - /** - * Starts consuming a destination. - * - * @param spec what to consume and where to deliver it - * @return the live registration - */ - TransportConsumerRegistration register(TransportConsumerSpec spec); - - /** - * Returns what this adapter can prove for a destination. - * - * @param destination the logical destination - * @return the capability snapshot - */ - DestinationCapabilities capabilities(DestinationName destination); - - /** - * Returns the broker family name. - * - * @return a stable, low-cardinality name - */ - String brokerName(); - - /** - * Returns the runtime generation this transport belongs to. - * - * @return the generation number - */ - long generation(); - - /** Releases broker resources. */ - @Override - void close(); -} diff --git a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportConsumerRegistration.java b/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportConsumerRegistration.java deleted file mode 100644 index 8beeffe2..00000000 --- a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportConsumerRegistration.java +++ /dev/null @@ -1,40 +0,0 @@ -package dev.caskeleton.messaging.transport; - -import java.util.concurrent.CompletionStage; - -/** - * A live consumer subscription. - * - *

Pause and resume operate on an ordering unit rather than the whole consumer, because that is - * what makes {@code PAUSE_PARTITION} retry possible: one stuck key must not stall every other - * partition on the same connection. - */ -public interface TransportConsumerRegistration extends AutoCloseable { - - /** - * Pauses one ordering unit, or the whole registration when the scope is empty. - * - * @param scope the ordering unit, or an empty string for all - * @return a stage completing when the pause has taken effect - */ - CompletionStage pause(String scope); - - /** - * Resumes a previously paused scope. - * - * @param scope the ordering unit, or an empty string for all - * @return a stage completing when the resume has taken effect - */ - CompletionStage resume(String scope); - - /** - * Reports whether the registration is still delivering. - * - * @return true while active - */ - boolean isActive(); - - /** Stops delivering and releases broker resources. */ - @Override - void close(); -} diff --git a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportConsumerSpec.java b/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportConsumerSpec.java deleted file mode 100644 index 2bf901c3..00000000 --- a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportConsumerSpec.java +++ /dev/null @@ -1,21 +0,0 @@ -package dev.caskeleton.messaging.transport; - -import dev.caskeleton.messaging.policy.DestinationProfile; -import java.util.Objects; -import java.util.concurrent.CompletionStage; -import java.util.function.Function; - -/** - * What an adapter needs to start consuming a destination. - * - * @param profile the validated destination profile - * @param sink the platform callback invoked for each delivery - */ -public record TransportConsumerSpec( - DestinationProfile profile, Function> sink) { - - public TransportConsumerSpec { - Objects.requireNonNull(profile, "profile must not be null"); - Objects.requireNonNull(sink, "sink must not be null"); - } -} diff --git a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportDelivery.java b/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportDelivery.java deleted file mode 100644 index 9a980073..00000000 --- a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportDelivery.java +++ /dev/null @@ -1,29 +0,0 @@ -package dev.caskeleton.messaging.transport; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.delivery.DeliveryMetadata; -import dev.caskeleton.messaging.schema.EncodedMessage; -import java.util.Objects; - -/** - * One still-encoded delivery handed up from an adapter. - * - *

Decoding happens above the transport so that a payload the consumer cannot parse is classified - * as a schema failure by the platform, and parked, rather than being turned into an - * adapter-specific exception each broker reports differently. - * - * @param envelope the envelope carrying the encoded payload - * @param metadata transport-side delivery facts - * @param settlement the handle for settling this delivery - */ -public record TransportDelivery( - MessageEnvelope envelope, - DeliveryMetadata metadata, - TransportSettlement settlement) { - - public TransportDelivery { - Objects.requireNonNull(envelope, "envelope must not be null"); - Objects.requireNonNull(metadata, "metadata must not be null"); - Objects.requireNonNull(settlement, "settlement must not be null"); - } -} diff --git a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportPublishRequest.java b/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportPublishRequest.java deleted file mode 100644 index 30ad41a8..00000000 --- a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportPublishRequest.java +++ /dev/null @@ -1,28 +0,0 @@ -package dev.caskeleton.messaging.transport; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.schema.EncodedMessage; -import java.util.Objects; - -/** - * One publish handed to an adapter. - * - *

The payload arrives already encoded and the profile arrives already validated, so an adapter - * never chooses a codec or a limit for itself. That is what keeps two adapters from disagreeing - * about what "the same message" means. - * - * @param profile the validated destination profile - * @param envelope the envelope carrying the encoded payload - * @param options the per-call publish options - */ -public record TransportPublishRequest( - DestinationProfile profile, MessageEnvelope envelope, PublishOptions options) { - - public TransportPublishRequest { - Objects.requireNonNull(profile, "profile must not be null"); - Objects.requireNonNull(envelope, "envelope must not be null"); - Objects.requireNonNull(options, "options must not be null"); - } -} diff --git a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportPublishResult.java b/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportPublishResult.java deleted file mode 100644 index f059a4ab..00000000 --- a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportPublishResult.java +++ /dev/null @@ -1,20 +0,0 @@ -package dev.caskeleton.messaging.transport; - -import dev.caskeleton.messaging.api.publish.PublishResult; -import java.util.Objects; - -/** - * What an adapter reports back from a publish. - * - *

Adapters return the full {@link PublishResult} rather than a boolean plus an exception. An - * adapter that could not establish what the broker did is required to say so through the completion - * and evidence, which is the whole reason the ambiguity survives to the caller. - * - * @param result the outcome and its evidence - */ -public record TransportPublishResult(PublishResult result) { - - public TransportPublishResult { - Objects.requireNonNull(result, "result must not be null"); - } -} diff --git a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportSettlement.java b/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportSettlement.java deleted file mode 100644 index dd39bc1e..00000000 --- a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/TransportSettlement.java +++ /dev/null @@ -1,36 +0,0 @@ -package dev.caskeleton.messaging.transport; - -import dev.caskeleton.messaging.api.settlement.SettlementResult; -import java.time.Duration; -import java.util.concurrent.CompletionStage; - -/** - * The adapter-side handle for settling one delivery. - * - *

Deliberately not exposed to application code. Handlers state an intent; the platform decides - * when and in what order the settlement happens, and this is the seam it uses to do that. - */ -public interface TransportSettlement { - - /** - * Acknowledges the delivery. - * - * @return a stage completing with the settlement outcome - */ - CompletionStage acknowledge(); - - /** - * Returns the delivery for redelivery after a delay. - * - * @param delay how long the broker should wait - * @return a stage completing with the settlement outcome - */ - CompletionStage requeue(Duration delay); - - /** - * Discards the delivery without requeueing. - * - * @return a stage completing with the settlement outcome - */ - CompletionStage discard(); -} diff --git a/src/platforms/messaging/messaging-transport-spi/src/test/java/dev/caskeleton/messaging/transport/GracefulShutdownTest.java b/src/platforms/messaging/messaging-transport-spi/src/test/java/dev/caskeleton/messaging/transport/GracefulShutdownTest.java deleted file mode 100644 index 4c3df9f9..00000000 --- a/src/platforms/messaging/messaging-transport-spi/src/test/java/dev/caskeleton/messaging/transport/GracefulShutdownTest.java +++ /dev/null @@ -1,75 +0,0 @@ -package dev.caskeleton.messaging.transport; - -import static org.assertj.core.api.Assertions.assertThat; - -import java.time.Duration; -import java.time.Instant; -import org.junit.jupiter.api.Test; - -class GracefulShutdownTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - @Test - void drainingStopsNewWorkButLetsRunningWorkFinish() { - GracefulShutdownCoordinator coordinator = - new GracefulShutdownCoordinator(Duration.ofSeconds(30)); - assertThat(coordinator.tryBeginWork()).isTrue(); - - coordinator.beginDrain(NOW); - - assertThat(coordinator.isAcceptingWork()).isFalse(); - assertThat(coordinator.tryBeginWork()).isFalse(); - assertThat(coordinator.inFlight()).isEqualTo(1); - assertThat(coordinator.isDrained(NOW)).isFalse(); - - coordinator.endWork(); - - assertThat(coordinator.isDrained(NOW)).isTrue(); - } - - @Test - void noRetryAttemptIsCreatedOnceDrainingBegins() { - GracefulShutdownCoordinator coordinator = - new GracefulShutdownCoordinator(Duration.ofSeconds(30)); - - assertThat(coordinator.mayCreateRetryAttempt()).isTrue(); - coordinator.beginDrain(NOW); - assertThat(coordinator.mayCreateRetryAttempt()).isFalse(); - } - - @Test - void workStillRunningAtTheDeadlineIsAbandonedUnsettled() { - GracefulShutdownCoordinator coordinator = - new GracefulShutdownCoordinator(Duration.ofSeconds(30)); - coordinator.tryBeginWork(); - coordinator.beginDrain(NOW); - - assertThat(coordinator.isDrained(NOW.plusSeconds(29))).isFalse(); - assertThat(coordinator.isDrained(NOW.plusSeconds(30))).isTrue(); - assertThat(coordinator.abandonedWorkAtDeadline(NOW.plusSeconds(30))).isTrue(); - } - - @Test - void anIdleCoordinatorIsNotDrainedBeforeShutdownStarts() { - GracefulShutdownCoordinator coordinator = - new GracefulShutdownCoordinator(Duration.ofSeconds(30)); - - assertThat(coordinator.isDrained(NOW)).isFalse(); - } - - @Test - @org.junit.jupiter.api.DisplayName("a double endWork cannot drive the in-flight count negative") - void aDoubleEndWorkCannotGoNegative() { - GracefulShutdownCoordinator shutdown = - new GracefulShutdownCoordinator(java.time.Duration.ofSeconds(5)); - assertThat(shutdown.tryBeginWork()).isTrue(); - - shutdown.endWork(); - shutdown.endWork(); - - assertThat(shutdown.inFlight()) - .as("a negative count reports the drain as finished while work is still running") - .isZero(); - } -} diff --git a/src/platforms/messaging/messaging-transport-spi/src/test/java/dev/caskeleton/messaging/transport/MessagingRuntimeRegistryTest.java b/src/platforms/messaging/messaging-transport-spi/src/test/java/dev/caskeleton/messaging/transport/MessagingRuntimeRegistryTest.java deleted file mode 100644 index 3cb35972..00000000 --- a/src/platforms/messaging/messaging-transport-spi/src/test/java/dev/caskeleton/messaging/transport/MessagingRuntimeRegistryTest.java +++ /dev/null @@ -1,311 +0,0 @@ -package dev.caskeleton.messaging.transport; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -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.MessagingConfigurationException; -import java.time.Duration; -import java.time.Instant; -import java.util.concurrent.CompletionStage; -import org.junit.jupiter.api.Test; - -class MessagingRuntimeRegistryTest { - - @Test - void replacingRuntimeReturnsNewGenerationAndKeepsOldUntilReleased() { - try (DefaultMessagingRuntimeRegistry registry = new DefaultMessagingRuntimeRegistry()) { - MessagingRuntime first = MessagingRuntimeFixtures.runtime("kafka-primary", 1); - MessagingRuntime second = MessagingRuntimeFixtures.runtime("kafka-primary", 2); - - registry.install(first); - MessagingRuntimeLease lease = registry.acquire("kafka-primary"); - registry.install(second); - - assertThat(lease.runtime().generation()).isEqualTo(1); - assertThat(first.isClosed()).as("a leased generation stays open").isFalse(); - assertThat(registry.acquire("kafka-primary").runtime().generation()).isEqualTo(2); - - lease.close(); - - assertThat(first.isClosed()).isTrue(); - } - } - - @Test - void anIdleGenerationIsClosedImmediatelyOnReplacement() { - try (DefaultMessagingRuntimeRegistry registry = new DefaultMessagingRuntimeRegistry()) { - MessagingRuntime first = MessagingRuntimeFixtures.runtime("kafka-primary", 1); - - registry.install(first); - registry.install(MessagingRuntimeFixtures.runtime("kafka-primary", 2)); - - assertThat(first.isClosed()).isTrue(); - assertThat(registry.drainingCount()).isZero(); - } - } - - @Test - void closingTheRegistryClosesCurrentAndDrainingGenerationsExactlyOnce() { - try (DefaultMessagingRuntimeRegistry registry = - new DefaultMessagingRuntimeRegistry(Duration.ofSeconds(30))) { - CountingRuntime retired = new CountingRuntime("kafka-primary", 1); - CountingRuntime current = new CountingRuntime("kafka-primary", 2); - - registry.install(retired); - MessagingRuntimeLease leaked = registry.acquire("kafka-primary"); - registry.install(current, Instant.parse("2026-08-10T00:00:00Z")); - - registry.close(); - registry.close(); - - assertThat(current.closes()) - .as("a process that shut down without rotating left its connections to JVM exit") - .isEqualTo(1); - assertThat(retired.closes()) - .as("a second close on a broker client is where 'already closed' at shutdown comes from") - .isEqualTo(1); - - leaked.close(); - } - } - - @Test - void closingALeaseTwiceDoesNotDoubleRelease() { - try (DefaultMessagingRuntimeRegistry registry = new DefaultMessagingRuntimeRegistry()) { - MessagingRuntime first = MessagingRuntimeFixtures.runtime("kafka-primary", 1); - registry.install(first); - - MessagingRuntimeLease lease = registry.acquire("kafka-primary"); - lease.close(); - lease.close(); - - assertThat(first.isClosed()).as("the current generation is not retired").isFalse(); - } - } - - @Test - void theDrainDeadlineForceClosesALeakedLease() { - try (DefaultMessagingRuntimeRegistry registry = - new DefaultMessagingRuntimeRegistry(Duration.ofSeconds(30))) { - MessagingRuntime first = MessagingRuntimeFixtures.runtime("kafka-primary", 1); - - Instant retiredAt = Instant.parse("2026-08-10T00:00:00Z"); - registry.install(first); - MessagingRuntimeLease leaked = registry.acquire("kafka-primary"); - // The rotation stamps this generation's own retirement time, so the deadline below is - // measured - // from when *it* retired rather than from whatever instant the caller happened to pass. - registry.install(MessagingRuntimeFixtures.runtime("kafka-primary", 2), retiredAt); - - assertThat(registry.closeExpiredDraining(retiredAt.plusSeconds(29))).isZero(); - assertThat(first.isClosed()).isFalse(); - - assertThat(registry.closeExpiredDraining(retiredAt.plusSeconds(30))).isEqualTo(1); - assertThat(first.isClosed()).isTrue(); - - leaked.close(); - } - } - - @Test - void acquiringAnUninstalledBrokerIsAConfigurationFailure() { - try (DefaultMessagingRuntimeRegistry registry = new DefaultMessagingRuntimeRegistry()) { - - assertThatThrownBy(() -> registry.acquire("rabbit-primary")) - .isInstanceOf(MessagingConfigurationException.class); - } - } - - @Test - void generationsAreTrackedPerBroker() { - try (DefaultMessagingRuntimeRegistry registry = new DefaultMessagingRuntimeRegistry()) { - registry.install(MessagingRuntimeFixtures.runtime("kafka-primary", 7)); - registry.install(MessagingRuntimeFixtures.runtime("rabbit-primary", 3)); - - assertThat(registry.acquire("kafka-primary").runtime().generation()).isEqualTo(7); - assertThat(registry.acquire("rabbit-primary").runtime().generation()).isEqualTo(3); - } - } - - @Test - @org.junit.jupiter.api.DisplayName("each retired generation has its own drain deadline") - void eachGenerationHasItsOwnDeadline() { - try (DefaultMessagingRuntimeRegistry registry = - new DefaultMessagingRuntimeRegistry(Duration.ofSeconds(30))) { - Instant first = Instant.parse("2026-08-10T00:00:00Z"); - MessagingRuntime one = MessagingRuntimeFixtures.runtime("kafka-primary", 1); - MessagingRuntime two = MessagingRuntimeFixtures.runtime("kafka-primary", 2); - - registry.install(one); - MessagingRuntimeLease leakedOne = registry.acquire("kafka-primary"); - registry.install(two, first); - MessagingRuntimeLease leakedTwo = registry.acquire("kafka-primary"); - registry.install(MessagingRuntimeFixtures.runtime("kafka-primary", 3), first.plusSeconds(20)); - - // 35s after the first retirement, 15s after the second. - assertThat(registry.closeExpiredDraining(first.plusSeconds(35))) - .as("one caller-supplied timestamp for the whole list closed both or neither") - .isEqualTo(1); - assertThat(one.isClosed()).isTrue(); - assertThat(two.isClosed()).isFalse(); - - leakedOne.close(); - leakedTwo.close(); - } - } - - @Test - @org.junit.jupiter.api.DisplayName("a generation that closed on its own leaves the draining list") - void anIdleClosedGenerationLeavesTheDrainingList() { - try (DefaultMessagingRuntimeRegistry registry = - new DefaultMessagingRuntimeRegistry(Duration.ofSeconds(30))) { - Instant retiredAt = Instant.parse("2026-08-10T00:00:00Z"); - registry.install(MessagingRuntimeFixtures.runtime("kafka-primary", 1)); - MessagingRuntimeLease lease = registry.acquire("kafka-primary"); - registry.install(MessagingRuntimeFixtures.runtime("kafka-primary", 2), retiredAt); - - lease.close(); - registry.closeExpiredDraining(retiredAt.plusSeconds(1)); - - assertThat(registry.drainingCount()) - .as( - "a closed generation counted as draining forever, so the metric never returned to zero") - .isZero(); - } - } -} - -/** Builds runtimes that record whether they were closed. */ -final class MessagingRuntimeFixtures { - - private MessagingRuntimeFixtures() {} - - static MessagingRuntime runtime(String brokerName, long generation) { - return new FakeRuntime(brokerName, generation); - } -} - -/** A runtime that closes nothing but remembers that it was asked to. */ -final class FakeRuntime implements MessagingRuntime { - - private final String brokerName; - private final long generation; - private boolean closed; - - FakeRuntime(String brokerName, long generation) { - this.brokerName = brokerName; - this.generation = generation; - } - - @Override - public String brokerName() { - return brokerName; - } - - @Override - public long generation() { - return generation; - } - - @Override - public MessagingTransport transport() { - return new FakeTransport(brokerName, generation); - } - - @Override - public boolean isClosed() { - return closed; - } - - @Override - public void close() { - closed = true; - } -} - -/** A transport that refuses every operation; the registry test never dispatches through it. */ -final class FakeTransport implements MessagingTransport { - - private final String brokerName; - private final long generation; - - FakeTransport(String brokerName, long generation) { - this.brokerName = brokerName; - this.generation = generation; - } - - @Override - public CompletionStage publish(TransportPublishRequest request) { - throw new UnsupportedOperationException("fixture transport does not publish"); - } - - @Override - public TransportConsumerRegistration register(TransportConsumerSpec spec) { - throw new UnsupportedOperationException("fixture transport does not consume"); - } - - @Override - public DestinationCapabilities capabilities(DestinationName destination) { - return new DestinationCapabilities(destination, brokerName, MessagingCapabilities.none()); - } - - @Override - public String brokerName() { - return brokerName; - } - - @Override - public long generation() { - return generation; - } - - @Override - public void close() { - // Nothing to release. - } -} - -/** A runtime that counts how many times it was closed. */ -final class CountingRuntime implements MessagingRuntime { - - private final String brokerName; - private final long generation; - private int closes; - - CountingRuntime(String brokerName, long generation) { - this.brokerName = brokerName; - this.generation = generation; - } - - int closes() { - return closes; - } - - @Override - public String brokerName() { - return brokerName; - } - - @Override - public long generation() { - return generation; - } - - @Override - public MessagingTransport transport() { - return new FakeTransport(brokerName, generation); - } - - @Override - public boolean isClosed() { - return closes > 0; - } - - @Override - public void close() { - closes++; - } -} diff --git a/src/platforms/messaging/messaging-transport-spi/src/test/java/dev/caskeleton/messaging/transport/ResourceLeakGateTest.java b/src/platforms/messaging/messaging-transport-spi/src/test/java/dev/caskeleton/messaging/transport/ResourceLeakGateTest.java deleted file mode 100644 index e95c14da..00000000 --- a/src/platforms/messaging/messaging-transport-spi/src/test/java/dev/caskeleton/messaging/transport/ResourceLeakGateTest.java +++ /dev/null @@ -1,141 +0,0 @@ -package dev.caskeleton.messaging.transport; - -import static org.assertj.core.api.Assertions.assertThat; - -import java.time.Duration; -import java.time.Instant; -import java.util.ArrayList; -import java.util.List; -import org.junit.jupiter.api.Test; - -/** - * Pins the release paths that keep a long-running consumer from leaking. - * - *

Every resource the platform holds is bounded by something that must eventually release it: a - * runtime generation by its last lease, an in-flight slot by its handler finishing, a drain by its - * deadline. Each of those has a failure mode that is invisible in a short test and fatal over days - * — a retired generation whose credential never gets revoked, a partition that never accepts work - * again, a shutdown that never completes. - */ -class ResourceLeakGateTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - @Test - void everyRetiredGenerationIsEventuallyClosed() { - try (DefaultMessagingRuntimeRegistry registry = - new DefaultMessagingRuntimeRegistry(Duration.ofSeconds(30))) { - List generations = new ArrayList<>(); - - for (int generation = 1; generation <= 20; generation++) { - LeakTrackingRuntime runtime = new LeakTrackingRuntime("kafka-primary", generation); - generations.add(runtime); - registry.install(runtime); - registry.acquire("kafka-primary").close(); - } - - assertThat(generations.subList(0, generations.size() - 1)) - .as("only the current generation stays open") - .allSatisfy(runtime -> assertThat(runtime.isClosed()).isTrue()); - assertThat(registry.drainingCount()).isZero(); - } - } - - @Test - void aLeakedLeaseIsForceClosedAtTheDrainDeadline() { - try (DefaultMessagingRuntimeRegistry registry = - new DefaultMessagingRuntimeRegistry(Duration.ofSeconds(30))) { - LeakTrackingRuntime retired = new LeakTrackingRuntime("kafka-primary", 1); - registry.install(retired); - registry.acquire("kafka-primary"); - - registry.install(new LeakTrackingRuntime("kafka-primary", 2), NOW); - registry.closeExpiredDraining(NOW.plusSeconds(30)); - - assertThat(retired.isClosed()) - .as("a leaked lease must not pin a revoked credential open forever") - .isTrue(); - } - } - - @Test - void aDrainAlwaysTerminatesEvenWithStuckWork() { - GracefulShutdownCoordinator coordinator = - new GracefulShutdownCoordinator(Duration.ofSeconds(30)); - coordinator.tryBeginWork(); - coordinator.beginDrain(NOW); - - assertThat(coordinator.isDrained(NOW.plusSeconds(3600))) - .as("a stuck handler must not hold the process open indefinitely") - .isTrue(); - } - - @Test - void aRetiredGenerationIsClosedExactlyOnce() { - try (DefaultMessagingRuntimeRegistry registry = - new DefaultMessagingRuntimeRegistry(Duration.ofSeconds(30))) { - LeakTrackingRuntime retired = new LeakTrackingRuntime("kafka-primary", 1); - registry.install(retired); - MessagingRuntimeLease lease = registry.acquire("kafka-primary"); - registry.install(new LeakTrackingRuntime("kafka-primary", 2), NOW); - - lease.close(); - lease.close(); - registry.closeExpiredDraining(NOW.plusSeconds(60)); - - assertThat(retired.closeCount()) - .as("a second close on a real connection pool throws from a shutdown hook") - .isEqualTo(1); - } - } -} - -/** A runtime that records whether it was closed, and how many times. */ -final class LeakTrackingRuntime implements MessagingRuntime { - - private final String brokerName; - private final long generation; - private int closeCount; - - LeakTrackingRuntime(String brokerName, long generation) { - this.brokerName = brokerName; - this.generation = generation; - } - - @Override - public String brokerName() { - return brokerName; - } - - @Override - public long generation() { - return generation; - } - - @Override - public MessagingTransport transport() { - throw new UnsupportedOperationException("the leak gate never dispatches"); - } - - @Override - public boolean isClosed() { - return closeCount > 0; - } - - /** - * Returns how many times close was called. - * - *

Closing twice is as much a defect as never closing: a second close on a real connection pool - * throws, and the exception surfaces from a shutdown hook where nothing handles it. - * - * @return the close count - */ - int closeCount() { - return closeCount; - } - - @Override - public void close() { - closeCount++; - } -} diff --git a/src/settings.gradle b/src/settings.gradle index e93d4112..0d94af53 100644 --- a/src/settings.gradle +++ b/src/settings.gradle @@ -16,6 +16,22 @@ plugins { dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { + // The libraries this repository's owner publishes from their own repositories + // (docs/work/reference/related-repos.md): group dev.cakit and below, from the owner's Gitea + // Packages only, and nothing else from there. A public repository serving a dev.cakit + // artifact of the same name is never asked (dependency confusion), and a slow or absent Gitea + // affects no other dependency. Packages of a public owner are read without a token. + exclusiveContent { + forRepository { + maven { + name = 'cakitPackages' + url = 'https://git.learn.hyeonworks.com/api/packages/donghyeon.kang/maven' + } + } + filter { + includeGroupByRegex 'dev\\.cakit(\\..*)?' + } + } mavenCentral() } }