diff --git a/.github/workflows/messaging-certification.yml b/.github/workflows/messaging-certification.yml new file mode 100644 index 0000000..f90d6e4 --- /dev/null +++ b/.github/workflows/messaging-certification.yml @@ -0,0 +1,59 @@ +# 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/messaging/**" + - ".github/workflows/messaging-certification.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 + - name: Validate Gradle wrapper + id: gradle-wrapper-validation + uses: gradle/actions/wrapper-validation@3f131e8634966bd73d06cc69884922b02e6faf92 # gradle/actions@v6 + - uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # actions/setup-java@v4.7.1 + with: + distribution: temurin + java-version: "21.0.11+10" + cache: gradle + cache-dependency-path: | + src/**/*.gradle + src/**/gradle-wrapper.properties + src/**/gradle.lockfile + - 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 --no-daemon --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/messaging/messaging-kafka/build/messaging-certification/ + if-no-files-found: warn diff --git a/docs/messaging/configuration-reference.md b/docs/messaging/configuration-reference.md index 0e864ee..31afe67 100644 --- a/docs/messaging/configuration-reference.md +++ b/docs/messaging/configuration-reference.md @@ -7,60 +7,76 @@ > either of the old prefixes now fails startup with a message naming the key — see > `MessagingPrefixMigrationValidator`. +> **이 페이지는 실행된다.** 아래 YAML 블록은 `MessagingConfigurationBindingTest`가 이 파일에서 직접 +> 읽어 컨텍스트에 올린다. 문서가 설명하는 모양이 곧 바인딩되는 모양이라는 뜻이고, 문서를 고치면서 +> 코드를 고치지 않으면 테스트가 깨진다. 이전 판은 destination·broker·security 세 섹션을 설명했지만 +> 어떤 binder도 그것을 읽지 않았다 — 문서대로 설정한 배포는 아무것도 바뀌지 않았고 아무 말도 듣지 +> 못했다 (MSG-008). ## Destination profile ```yaml app: messaging: - destinations: - order-events: - broker: kafka-primary - kind: EVENT_STREAM # ASYNC_COMMAND | DOMAIN_EVENT | INTEGRATION_EVENT + destinations: + order-events: + broker: kafka-primary + kind: EVENT_STREAM # ASYNC_COMMAND | DOMAIN_EVENT | INTEGRATION_EVENT # | WORK_QUEUE | PUBLISH_SUBSCRIBE | EVENT_STREAM | REQUEST_REPLY - tier: M1 # M1 | M2 | M3 - physical: - topic: order.events.v1 - schema: - codec: application/json - compatibility: BACKWARD_TRANSITIVE - message-types: [order.created] - guarantees: - delivery: AT_LEAST_ONCE # AT_MOST_ONCE | AT_LEAST_ONCE - ordering: KEY # NONE | DESTINATION | PARTITION | KEY - external-side-effect: INBOX_TRANSACTIONAL - producer: - confirmation: REPLICATION_OR_PERSISTENCE_ACK - timeout: 5s - mandatory-routing: true - idempotent: true - consumer: - group: order-projection - concurrency: 6 - max-in-flight-per-ordering-unit: 1 - prefetch: 16 - handler-timeout: 30s - manual-settlement: false - retry: - mode: PAUSE_PARTITION # NONE | INLINE | BLOCKING | PAUSE_PARTITION + tier: M1 # M1 | M2 | M3 + physical: + topic: order.events.v1 + schema: + codec: application/json + compatibility: BACKWARD_TRANSITIVE + message-types: [order.created] + guarantees: + delivery: AT_LEAST_ONCE # AT_MOST_ONCE | AT_LEAST_ONCE + ordering: KEY # NONE | DESTINATION | PARTITION | KEY + external-side-effect: INBOX_TRANSACTIONAL + producer: + confirmation: REPLICATION_OR_PERSISTENCE_ACK + timeout: 5s + mandatory-routing: true + idempotent: true + consumer: + group: order-projection + concurrency: 1 # DESTINATION 순서를 요구하면 1이어야 한다 + max-in-flight-per-ordering-unit: 1 + prefetch: 16 + handler-timeout: 30s + manual-settlement: false + retry: + mode: PAUSE_PARTITION # NONE | INLINE | BLOCKING | PAUSE_PARTITION # | RETRY_DESTINATION | BROKER_DELAYED - max-attempts: 3 - initial-delay: 200ms - max-delay: 2s - multiplier: 2.0 - jitter: true - ordering-impact: PRESERVE # PRESERVE | ALLOW_REORDER - dlq: - destination: order-events-dlq - max-redrive-count: 1 - payload: - max-bytes: 1048576 - claim-check-threshold-bytes: 1048576 - key-resolver-configured: true - production: true - topology-auto-create: false + max-attempts: 3 + initial-delay: 200ms + max-delay: 2s + multiplier: 2.0 + jitter: true + ordering-impact: PRESERVE # PRESERVE | ALLOW_REORDER + dlq: + destination: order-events-dlq + max-redrive-count: 1 + payload: + max-bytes: 1048576 + claim-check-threshold-bytes: 1048576 + key-resolver-configured: true + production: false + topology-auto-create: false + order-events-dlq: + broker: kafka-primary + kind: WORK_QUEUE + physical: + topic: order.events.v1.dlt + schema: + message-types: [order.created] ``` +`dlq.destination`이 가리키는 destination도 선언되어야 한다. 선언되지 않은 이름은 부팅 실패이며, +메시지가 갈 곳 없는 DLQ 설정이 조용히 통과하지 않는다. `retry.destination`과 `dlq.destination`이 +섞여 만드는 순환(A의 retry가 B로, B의 dlq가 A로)도 하나의 그래프로 검사되어 경로와 함께 거절된다. + ## 기본값 | 설정 | 기본값 | 근거 | @@ -81,26 +97,36 @@ app: | Outbox polling | 500ms | | | metric dimension 상한 | 200 | cardinality 폭발 방지 | +`schema.codec`은 `application/json`, `schema.compatibility`는 `BACKWARD_TRANSITIVE`, +`guarantees.delivery`는 `AT_LEAST_ONCE`, `retry.mode`는 `NONE`이 기본값이다. 자동 retry가 기본으로 +꺼져 있는 이유는 순서를 흐트러뜨리거나 비멱등 side effect를 두 번 실행하는 retry가 눈에 보이는 +실패보다 나쁘기 때문이다. + ## Broker profile +브로커는 `app.messaging.brokers` 아래에 한 번만 기술한다. `type`이 어느 계열의 설정이 적용되는지 +결정하며, 다른 계열의 키(Kafka 항목의 `prefetch` 같은)는 무시되지 않고 부팅 실패로 거절된다 — +무시하면 그 줄을 쓴 사람은 무언가가 적용됐다고 믿게 된다. + ### Kafka ```yaml app: messaging: - brokers: - kafka-primary: - type: kafka - stable: true - production: true - bootstrap-servers: [broker-1:9093, broker-2:9093] - enable-idempotence: true # stable에서 필수 - acks: all # stable에서 필수 - max-in-flight-requests-per-connection: 5 # 최대 5 - delivery-timeout: 30s - enable-auto-commit: false # 항상 금지 - tls-enabled: true # production 필수 - authentication-enabled: true # production 필수 + brokers: + kafka-primary: + type: kafka + stable: true + production: false + bootstrap-servers: [broker-1:9093, broker-2:9093] + enable-idempotence: true # stable에서 필수 + acks: all # stable에서 필수 + max-in-flight-requests-per-connection: 5 # 최대 5 + delivery-timeout: 30s + enable-auto-commit: false # 항상 금지 + consumer-group: order-projection + tls-enabled: false # production이면 필수 + authentication-enabled: false # production이면 필수 ``` ### RabbitMQ @@ -108,40 +134,52 @@ app: ```yaml app: messaging: - brokers: - rabbit-primary: - type: rabbitmq - stable: true - production: true - addresses: [rabbit-1:5671] - publisher-confirms: true # stable에서 필수 - publisher-returns: true # stable에서 필수 - mandatory: true # stable에서 필수 - confirm-timeout: 5s - auto-ack: false # 항상 금지 - prefetch: 16 - quorum-queues: true # durable work queue 필수 - tls-enabled: true - authentication-enabled: true + brokers: + rabbit-primary: + type: rabbitmq + stable: true + production: false + addresses: [rabbit-1:5671] + publisher-confirms: true # stable에서 필수 + publisher-returns: true # stable에서 필수 + mandatory: true # stable에서 필수 + confirm-timeout: 5s + auto-ack: false # 항상 금지 + prefetch: 16 + quorum-queues: true # durable work queue 필수 + tls-enabled: false + authentication-enabled: false ``` +`production: true`인 브로커는 `tls-enabled`와 `authentication-enabled`가 모두 참이어야 하고, +그렇지 않으면 `KafkaProfileValidator` / `RabbitProfileValidator`가 부팅을 거절한다. 위 예시가 +`production: false`인 것은 이 페이지가 그대로 실행되는 fixture이기 때문이며, 실 배포는 셋 다 참이다. + ## 보안 ```yaml app: messaging: - security: - kafka-primary: - producer: { type: SASL_SCRAM, credential-id: kafka-producer } - consumer: { type: SASL_SCRAM, credential-id: kafka-consumer } - # admin은 application runtime에 설정하지 않는다 - hostname-verification: true - access: - publishable: [order-events] - consumable: [] - administrable: [] + security: + kafka-primary: + producer: { type: SASL_SCRAM, credential-id: kafka-producer } + consumer: { type: SASL_SCRAM, credential-id: kafka-consumer } + # admin은 application runtime에 설정하지 않는다 + hostname-verification: true + access: + publishable: [order-events] + consumable: [] + administrable: [] ``` +키는 `app.messaging.brokers`에 선언된 브로커 이름과 같아야 한다. `tls-enabled`와 `production`은 +브로커 쪽에만 있고 여기에 중복되지 않는다 — 하나의 브로커가 두 곳에서 기술되면 두 값이 어긋나는 +날이 오고, 어느 쪽이 이기는지는 아무도 모른다. + +`credential-id`는 이름일 뿐이고 자격 증명 자체가 아니다. 실제 재료는 `CredentialProvider`가 +연결 시점에 해석하므로, 설정 덤프나 힙 덤프에서 나오는 것은 이름뿐이다. producer와 consumer는 +서로 다른 `credential-id`를 써야 하며, 같으면 부팅에 실패한다. + ## Experimental / Optional 기본값은 전부 `false`다. @@ -149,12 +187,12 @@ app: ```yaml app: messaging: - experimental: - kafka-share: false - pulsar: false - nats: false - bridge: - spring-cloud-stream: false + experimental: + kafka-share: false + pulsar: false + nats: false + bridge: + spring-cloud-stream: false ``` ## Backpressure @@ -162,9 +200,24 @@ app: ```yaml app: messaging: - backpressure: - global-limit: 512 - per-destination-limit: 64 # global-limit 이하여야 한다 + backpressure: + global-limit: 512 + per-destination-limit: 64 # global-limit 이하여야 한다 ``` `per-destination-limit > global-limit`이면 global limit이 limit이 아니게 되므로 부팅에 실패한다. + +## 바인딩되지 않는 키 + +섹션은 바인딩되는데 그 안의 키 하나가 오타인 경우는 접두사 오타와 달리 조용하다 — 섹션은 붙고, +플랫폼은 뜨고, 바꾸러 온 그 설정만 적용되지 않는다. `MessagingConfigurationKeyValidator`가 +`app.messaging.destinations|brokers|security` 아래의 모든 키를 settings 레코드에서 파생한 목록과 +대조하고, 없는 키는 그 키 이름을 담아 부팅을 거절한다. + +허용 키 목록은 이 문서가 아니라 레코드에서 나온다. 문서에 목록을 적으면 필드가 추가된 날 그 +목록이 틀리고, 오타를 잡으라고 만든 검사가 정상 필드를 거절하게 된다. + +환경변수(`APP_MESSAGING_...`)는 이 검사의 대상이 아니다. `APP_MESSAGING_DESTINATIONS_ORDER_EVENTS_ +CONSUMER_PREFETCH`에서 entry 이름과 leaf를 가르는 밑줄은 둘 안에 있는 밑줄과 구별되지 않으므로, +되돌려 쪼개려면 추측해야 한다. 여기서의 추측은 정상 배포를 거절하는 쪽으로 틀리며, 그것은 배포 +매니페스트에 손으로 적어야 하는 변수에서 오타 하나를 놓치는 것보다 나쁘다. diff --git a/docs/messaging/support-matrix.md b/docs/messaging/support-matrix.md index 000cfca..38622f1 100644 --- a/docs/messaging/support-matrix.md +++ b/docs/messaging/support-matrix.md @@ -3,6 +3,12 @@ 플랫폼이 **무엇을 보장하는지**와 **무엇을 보장하지 않는지**를 브로커별로 고정한다. 여기 없는 조합은 지원되지 않는다. +> **등급은 증거를 따른다.** `CompatibilityMatrix.Entry.hasLiveBrokerCertification()`은 선언된 +> boolean이 아니라 `CertifiedEvidence`가 가진 레인 증거에서 파생된다. RabbitMQ가 Stable에서 내려온 +> 이유가 이것이다 — 어댑터는 공유 contract 7개를 통과하고 `RabbitBrokerIT`가 실 컨테이너에서 정상 +> 경로를 돌리지만, 이 저장소의 Stable 기준인 **장애 시나리오 증거**가 하나도 없다. 레인이 생겨 +> 증거를 내면 등급은 코드 수정 없이 따라 올라간다. + > **인증 근거.** 이 표의 버전은 이 저장소의 컨테이너 레인이 실제로 실행한 이미지다. 이전 판은 > Kafka 4.2/4.3을 선언했지만 fixture는 `apache/kafka:4.1.0`, lockfile client는 4.1.1이었다 — 표와 > 코드 상수가 서로 일치했을 뿐 어느 쪽도 실행된 적이 없었다. 장애 시나리오 커버리지도 마찬가지로 @@ -25,7 +31,7 @@ | 브로커 | 등급 | 인증 기준 | Stable 기능 | 제한 | |---|---|---|---|---| | Kafka | Stable | 4.1.x | producer idempotence, consumer group, batch, pause/resume, replay, transaction capability | Share Group은 Experimental | -| RabbitMQ | Stable | 4.3.x | exchange/routing, publisher confirm, mandatory return, manual ACK, quorum queue, retry queue, DLQ | stream 및 특수 plugin 미지원 | +| RabbitMQ | Experimental | 4.3.x | exchange/routing, publisher confirm, mandatory return, manual ACK, quorum queue, retry queue, DLQ | 장애 시나리오 레인 미실행 — 증거 없음. stream 및 특수 plugin 미지원 | | Pulsar | Experimental | 4.0 LTS + 4.2 | typed publish/consume, Shared, Key_Shared, schema | transaction 미승격, 기본 비활성 | | NATS JetStream | Experimental | 2.14.x | stream, durable consumer, explicit ACK, dedupe, replay | native DLQ 없음(플랫폼이 대행), 기본 비활성 | | Artemis/JMS | Extension | 범위 밖 | adapter SPI만 | 별도 ADR + Contract Suite 통과 필요 | @@ -86,11 +92,15 @@ Kafka와 RabbitMQ가 동일한 7개 테스트를 변경 없이 통과한다. 결 |---|---| | `KafkaBrokerIT` | `acks=all`이 실제 replication 증거를 만든다 / 잘못된 토픽은 `REJECTED` / 발행-소비 왕복에서 identity 보존 및 contiguous commit | | `KafkaAmbiguityChaosIT` | 브로커를 `docker pause`로 멈춘 상태의 publish가 **`AMBIGUOUS`** 로 보고된다 (broker acceptance 없음, confirmation level `NONE`, 비-retryable) | +| `KafkaBrokerCertificationIT` | 인증 레인. Toxiproxy를 broker 앞에 두고 connection cut / confirm 유실 / 지연 / settlement 유실을 각각 주입하고, 통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을 manifest에 쓴다 | | `RabbitBrokerIT` | exchange가 confirm했는데 어떤 큐에도 바인딩되지 않은 publish가 **`REJECTED` + `UNROUTABLE`** 로 보고된다 | | `OutboxPostgresIT` | 롤백된 트랜잭션은 발행 가능한 행을 남기지 않는다 / `SKIP LOCKED` lease가 두 relay를 분리한다 / ambiguous 행이 같은 `messageId`로 재클레임된다 | | `InboxPostgresIT` | 재전달이 side effect를 두 번 적용하지 않는다 / 롤백은 예약도 되돌린다 | Docker가 없으면 `DockerAvailability` 가드로 skip되며, 이 표의 항목은 그때 **검증되지 않은 것**으로 취급한다. +`KafkaBrokerCertificationIT`만 예외다 — 인증 레인은 가드를 달지 않고 Docker가 없으면 실패한다. skip하는 +레인은 아무도 켜지 않은 브로커에 대해 성공을 보고하기 때문이다. 그래서 이 레인은 `test`에서 태그로 +제외되고 `messagingCertificationTest`로만 실행된다. ### 3. 장애 시나리오 커버리지 (`BrokerFailureMatrix`) @@ -109,6 +119,18 @@ Docker가 없으면 `DockerAvailability` 가드로 skip되며, 이 표의 항목 커버해야 하고, Experimental 어댑터는 `LIVE_BROKER` 커버리지를 주장할 수 없다. 커버리지는 *능력*이 아니라 *무엇을 실제로 돌렸는지*의 기록이다. +**증거의 출처.** `CertifiedEvidence`는 더 이상 손으로 쓴 목록이 아니라 +`messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl`을 읽는다. 그 파일은 +`messagingCertificationTest` 레인이 실제 Kafka 컨테이너에 장애를 주입하며 만들어낸 출력이고, +`verifyMessagingCertificationEvidence`가 커밋된 manifest와 이번 실행의 출력을 대조해 다르면 빌드를 +실패시킨다. 즉 **manifest를 손으로 고치면 게이트가 깨지고, 레인을 돌리면 manifest가 다시 쓰인다.** + +오늘 Kafka가 가진 증거는 `connection-cut-after-write` · `confirm-timeout` · `high-latency` · +`settlement-lost` 네 개다. `connection-refused`는 남은 gap이며 그 이유가 있다 — Kafka producer는 연결 +존재 여부를 알기 전에 레코드를 버퍼에 넣으므로, 연결 거부는 전송에 대해 아무것도 증명하지 못하는 +delivery timeout으로 나타난다. 이를 `REJECTED`로 보고하는 것은 이 플랫폼이 금지한 추측이므로, +시나리오는 `CertifiedEvidence.knownGaps`가 이름으로 들고 있는 미커버 항목으로 남는다. + ### 실 브로커가 실제로 잡아낸 결함 이 스위트들은 장식이 아니다. 작성 과정에서 결정적 테스트가 통과하는데 실 인프라에서 실패한 diff --git a/messaging/CLAUDE.md b/messaging/CLAUDE.md index e25f9a8..0fd1942 100644 --- a/messaging/CLAUDE.md +++ b/messaging/CLAUDE.md @@ -31,25 +31,58 @@ leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이 - **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이 숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다. - (`kafka-clients`, `spring-rabbit`, `cloudevents-api`, `micrometer-core`가 이 규칙으로 `api`다.) + (`kafka-clients`, `spring-rabbit`, `cloudevents-api`, `micrometer-core`, `avro`, + `protobuf-java`, `reactor-core`가 이 규칙으로 `api`다.) - 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을 - `implementation`으로 내린 것이 그 예다. + `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로 취급한다. ## Runtime membership이 비어 있다는 것의 의미 -registry의 모든 messaging leaf는 `runtime_memberships`가 비어 있다. 이는 **build-only / -incubating**을 뜻한다: +**이 절은 한동안 사실이 아닌 채로 남아 있었다.** "registry의 모든 messaging leaf는 +`runtime_memberships`가 비어 있고 따라서 build-only"라고 쓰여 있었는데, 다섯 어댑터 remediation이 +`messaging-spring-boot-starter`를 `app-bootstrap` 의존성으로 넣으면서 그 closure 전체가 런타임 +classpath에 올라갔다. 정확한 목록은 registry가 소유하므로 여기서 세지 않는다 — 세는 순간 다시 +drift한다. -- 두 composition root(`app-bootstrap`, `sample-portfolio`) 중 어디에도 런타임으로 들어가 있지 않다. -- 따라서 이 leaf들은 컴파일·테스트·계약 검증의 대상이지, 배포된 애플리케이션이 실행하는 코드가 - 아니다. -- 애플리케이션에 실제로 배선하려면 registry의 `runtime_memberships`를 먼저 바꾸고 +지금 의미는 이렇다: + +- 대부분의 leaf는 `runtime_memberships`에 `app-bootstrap`을 갖는다. **배포된 아티팩트가 싣고 있고, + master switch `app.messaging.enabled`로 켜진다.** 기본값은 `false`다. +- 여전히 비어 있는 leaf(experimental transport, 일부 codec, bridge, testkit)만이 build-only / + incubating이다. +- **런타임에 있다는 것과 자격이 증명됐다는 것은 다르다.** Kafka publish 경로만 실브로커 round trip으로 + 자격 검증됐고(`MessagingLiveRoundTripQualificationTest`), Rabbit·JDBC inbox/outbox·claim check·admin + plane은 shipped, inactive, unqualified다. 이 구분은 + `MessagingMembershipQualificationTest`가 문서가 아니라 테스트로 붙들고 있다. +- 애플리케이션에 새로 배선하려면 registry의 `runtime_memberships`를 먼저 바꾸고 `verifyRuntimeModuleMembership`을 통과시켜야 한다. 코드만 추가하는 것으로는 런타임에 들어가지 않는다. - 지원 상태 문서(`docs/messaging/support-matrix.md`)의 tier는 이 사실과 별개다. tier는 "무엇이 증명되었는가", membership은 "무엇이 실행되는가"다. +## application이 이 family에 도달하는 경로 (MSG-015, 미해결) + +리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한 흐름은 +`application-owned port → platform anti-corruption bridge → platform`이고, §6.2는 그 bridge의 자리를 +`adapter/outbound/messaging/platformbridge/`로 지정한다. §6.3 첫 규칙: **application은 신규 +broker/runtime 타입을 직접 보지 않고 자기 port만 소유한다.** + +**현재 그 bridge가 없다.** `adapter/outbound/messaging`은 platform에 의존하지 않고(registry의 +`allowed_dependencies` 참조), `app-bootstrap`이 starter를 직접 문다. 그래서 서로를 모르는 messaging +스택 두 개가 한 아티팩트에 있고, 그것이 `kafkaSeamProducer`/`messagingKafkaProducer` bean 이름 충돌로 +드러났다. + +이것이 리뷰의 **MSG-015 (P0)** 이며 닫히지 않았다. 지금 안전한 이유는 설계가 아니라 기본값이다 — +`app.messaging.enabled=false`. 이 스위치를 켜는 배포는 port를 거치지 않는 경로로 platform을 쓰게 된다. +bridge 구현은 런타임 배선 변경이라 리뷰가 말한 대로 별도 change set이다. + ## Stable 승격에 필요한 증거 adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/support-matrix.md`가 현재 @@ -67,6 +100,20 @@ adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/ 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에서 읽어 파생한다. diff --git a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/CorrelationId.java b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/CorrelationId.java index 3d63b91..00b96bf 100644 --- a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/CorrelationId.java +++ b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/CorrelationId.java @@ -3,15 +3,22 @@ package dev.caskeleton.messaging.api; /** * Workflow-scoped correlation value shared by every message of one business flow. * - * @param value the correlation value, 1 to 160 characters + *
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_LENGTH = 160;
+ private static final int MAX_BYTES = 160;
public CorrelationId {
- if (value == null || value.isBlank() || value.length() > MAX_LENGTH) {
- throw new IllegalArgumentException("correlationId must contain 1 to 160 characters");
+ if (value == null || value.isBlank()) {
+ throw new IllegalArgumentException("correlationId must not be blank");
}
+ WireSafeText.require(value, "a correlation id", MAX_BYTES);
}
}
diff --git a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageEnvelope.java b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageEnvelope.java
index bc554b1..d5ecaa1 100644
--- a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageEnvelope.java
+++ b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageEnvelope.java
@@ -62,8 +62,18 @@ public record MessageEnvelope 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 characters
+ * @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_LENGTH = 240;
+ private static final int MAX_BYTES = 240;
public MessageType {
- if (value == null || value.isBlank() || value.length() > MAX_LENGTH) {
- throw new IllegalArgumentException("messageType must contain 1 to 240 characters");
- }
- requireWireSafe(value, "a message type", MAX_LENGTH);
- }
-
- /**
- * Characters that must never reach a broker.
- *
- * Length in Java {@code char}s bounded nothing useful: a 240-character string can be 960 UTF-8
- * 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, and both survive right up to
- * the broker that mishandles them.
- */
- private static void requireWireSafe(String value, String what, int maxBytes) {
- for (int index = 0; index < value.length(); index++) {
- char character = value.charAt(index);
- if (character < 0x20 || character == 0x7F) {
- throw new IllegalArgumentException(
- what
- + " must not contain control characters (found U+%04X)".formatted((int) character));
- }
- }
- int bytes = value.getBytes(java.nio.charset.StandardCharsets.UTF_8).length;
- if (bytes > maxBytes) {
- throw new IllegalArgumentException(what + " exceeds " + maxBytes + " UTF-8 bytes: " + bytes);
+ if (value == null || value.isBlank()) {
+ throw new IllegalArgumentException("messageType must not be blank");
}
+ WireSafeText.require(value, "a message type", MAX_BYTES);
}
}
diff --git a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/ProducerId.java b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/ProducerId.java
index 313bbc0..0bb858a 100644
--- a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/ProducerId.java
+++ b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/ProducerId.java
@@ -6,39 +6,16 @@ package dev.caskeleton.messaging.api;
* 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 characters
+ * @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_LENGTH = 120;
+ private static final int MAX_BYTES = 120;
public ProducerId {
- if (value == null || value.isBlank() || value.length() > MAX_LENGTH) {
- throw new IllegalArgumentException("producerId must contain 1 to 120 characters");
- }
- requireWireSafe(value, "a producer id", MAX_LENGTH);
- }
-
- /**
- * Characters that must never reach a broker.
- *
- * Length in Java {@code char}s bounded nothing useful: a 240-character string can be 960 UTF-8
- * 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, and both survive right up to
- * the broker that mishandles them.
- */
- private static void requireWireSafe(String value, String what, int maxBytes) {
- for (int index = 0; index < value.length(); index++) {
- char character = value.charAt(index);
- if (character < 0x20 || character == 0x7F) {
- throw new IllegalArgumentException(
- what
- + " must not contain control characters (found U+%04X)".formatted((int) character));
- }
- }
- int bytes = value.getBytes(java.nio.charset.StandardCharsets.UTF_8).length;
- if (bytes > maxBytes) {
- throw new IllegalArgumentException(what + " exceeds " + maxBytes + " UTF-8 bytes: " + bytes);
+ if (value == null || value.isBlank()) {
+ throw new IllegalArgumentException("producerId must not be blank");
}
+ WireSafeText.require(value, "a producer id", MAX_BYTES);
}
}
diff --git a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/TraceContext.java b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/TraceContext.java
index ee553f3..b71623f 100644
--- a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/TraceContext.java
+++ b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/TraceContext.java
@@ -1,7 +1,9 @@
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.
@@ -10,6 +12,13 @@ import java.util.Optional;
* 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
@@ -17,10 +26,112 @@ import java.util.Optional;
public record TraceContext(
Optional 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 + '\'');
+ }
+ }
}
/**
diff --git a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/WireSafeText.java b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/WireSafeText.java
new file mode 100644
index 0000000..f919c32
--- /dev/null
+++ b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/WireSafeText.java
@@ -0,0 +1,65 @@
+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/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/CanonicalEnvelopeHeaders.java b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/CanonicalEnvelopeHeaders.java
new file mode 100644
index 0000000..4e95526
--- /dev/null
+++ b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/CanonicalEnvelopeHeaders.java
@@ -0,0 +1,79 @@
+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 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) {
@@ -15,9 +21,6 @@ public record HeaderValue(String value) {
if (value == null) {
throw new IllegalArgumentException("header value must not be null");
}
- int bytes = value.getBytes(StandardCharsets.UTF_8).length;
- if (bytes > MAX_BYTES) {
- throw new IllegalArgumentException("header value exceeds 4096 bytes: " + bytes);
- }
+ WireSafeText.require(value, "a header value", MAX_BYTES);
}
}
diff --git a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/MessageHeaders.java b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/MessageHeaders.java
index 328412a..21bbc76 100644
--- a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/MessageHeaders.java
+++ b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/MessageHeaders.java
@@ -34,6 +34,31 @@ public final class MessageHeaders {
"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 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";
@@ -91,6 +101,7 @@ public final class ReservedHeaders {
CONTENT_TYPE,
PARTITION_KEY,
ORDERING_KEY,
+ TENANT,
REDRIVE_ID,
REDRIVE_COUNT,
RETRY_ATTEMPT,
@@ -105,6 +116,16 @@ public final class ReservedHeaders {
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.
*
@@ -112,7 +133,11 @@ public final class ReservedHeaders {
* @return true when the platform owns the name
*/
public static boolean isReserved(String name) {
- return name != null && NAMES.contains(name.toLowerCase(Locale.ROOT));
+ if (name == null) {
+ return false;
+ }
+ String normalized = name.toLowerCase(Locale.ROOT);
+ return NAMES.contains(normalized) || normalized.startsWith(PLATFORM_PREFIX);
}
/**
diff --git a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishOptions.java b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishOptions.java
index f89c75a..f3d07e5 100644
--- a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishOptions.java
+++ b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishOptions.java
@@ -2,27 +2,25 @@ package dev.caskeleton.messaging.api.publish;
import dev.caskeleton.messaging.api.destination.ConfirmationRequirement;
import java.time.Duration;
-import java.util.Map;
import java.util.Objects;
import java.util.Optional;
/**
* Per-call publish options.
*
- * {@code brokerHints} must be empty for M1 callers. Only an M3 native capability may populate
- * it, because a hint map on the general API becomes an escape hatch that quietly bypasses
- * destination policy.
+ * 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
- * @param brokerHints M3-only adapter hints
*/
public record PublishOptions(
Duration timeout,
ConfirmationRequirement confirmation,
- Optional The constructor refuses combinations that would let a caller read a stronger guarantee than
- * was actually obtained. 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.
+ * 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
@@ -72,6 +78,26 @@ public record PublishResult(
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");
+ }
}
/**
diff --git a/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/WireBoundaryRejectionTest.java b/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/WireBoundaryRejectionTest.java
new file mode 100644
index 0000000..cc73fd3
--- /dev/null
+++ b/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/WireBoundaryRejectionTest.java
@@ -0,0 +1,208 @@
+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/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/publish/PublishResultTest.java b/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/publish/PublishResultTest.java
index dc34219..2e1add5 100644
--- a/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/publish/PublishResultTest.java
+++ b/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/publish/PublishResultTest.java
@@ -11,9 +11,90 @@ 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 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 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", "apache/kafka:4.1.0");
+
+ private static final String TOXIPROXY_IMAGE =
+ System.getProperty("messaging.toxiproxy.image", "ghcr.io/shopify/toxiproxy:2.12.0");
+
+ /** 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 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 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 The platform contract does not change with the transport. The router emits the same reserved
* headers the polling relay does, so a consumer cannot tell which one published a message, and
* switching between them is a deployment decision rather than a contract change.
+ *
+ * The message key and the topic are two different questions and used to be answered by one
+ * column. {@code destination} routed the topic and became the key, so every message on a
+ * topic carried the same key, landed on one partition, and made keyed ordering a claim with no
+ * mechanism behind it. The key now comes from {@code routing_key}, the stored column that states
+ * the partition-key-or-message-id fallback once for both relays, and {@code destination} stays what
+ * it always was: routing metadata.
+ *
+ * One canonical field has no header here: the schema subject. There is no reserved header name
+ * for it, and inventing one that only this path wrote would replace a symmetric gap with an
+ * asymmetric one — the polling relay would carry a schema reference on the envelope and the CDC
+ * relay a header no adapter reads. It stays a column that the polling relay resolves, and closing
+ * it means adding the name to {@code ReservedHeaders} and teaching both broker header mappers to
+ * write and read it.
*/
public final class DebeziumOutboxEventRouter {
- /** The outbox column Debezium uses as the message key. */
+ /** The outbox column Debezium routes the topic by. */
public static final String ROUTE_BY_COLUMN = "destination";
+ /** The outbox column Debezium uses as the message key. */
+ public static final String KEY_COLUMN = "routing_key";
+
/** The outbox column carrying the logical message id. */
public static final String ID_COLUMN = "message_id";
@@ -39,7 +57,7 @@ public final class DebeziumOutboxEventRouter {
Map The same value the {@code routing_key} column computes, stated here so a test can compare
+ * the two rather than trusting that the SQL and the Java agree.
+ *
+ * @param record the outbox row
+ * @return the broker message key
+ */
+ public String routingKey(OutboxRecord record) {
+ Objects.requireNonNull(record, "record must not be null");
+ return record.metadata().partitionKey().orElseGet(() -> record.messageId().value().toString());
+ }
}
diff --git a/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumOutboxRecordMapper.java b/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumOutboxRecordMapper.java
index a1480fb..513f246 100644
--- a/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumOutboxRecordMapper.java
+++ b/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumOutboxRecordMapper.java
@@ -19,11 +19,17 @@ import java.util.Optional;
* The message id comes from the row's {@code message_id} column, never from Debezium's own event
* id. Debezium mints a fresh event id per change record, so using it would break identity across a
* CDC re-snapshot — exactly the scenario where identity matters most.
+ *
+ * The reserved headers come from {@link DebeziumOutboxEventRouter} rather than being rebuilt
+ * here. Two lists of the same headers is how the connector's configuration and the expectation this
+ * class encodes come to disagree, and the disagreement would be invisible: the test compares this
+ * output against the polling relay's, so it would pass while the connector emitted something else.
*/
public final class DebeziumOutboxRecordMapper {
private final String topicPrefix;
private final boolean aggregateIdAsPartitionKey;
+ private final DebeziumOutboxEventRouter router = new DebeziumOutboxEventRouter();
/**
* Creates a mapper from a CDC profile.
@@ -45,27 +51,29 @@ public final class DebeziumOutboxRecordMapper {
public DebeziumMappedRecord map(OutboxRecord record) {
Objects.requireNonNull(record, "record must not be null");
+ // Application headers first, canonical headers second, and the canonical ones win. The row's
+ // header map is application data; a row that wrote `msg.id` into it would otherwise overwrite
+ // the identity the platform put there, and the consumer trusts the last such header it sees.
+ // The write path refuses reserved names outright — this order is the second lock on the same
+ // door, because a CDC connector reading the table directly never passes through that check.
Map 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, headers, 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""";
+
private static final String LEASE =
"""
WITH claimable AS (
@@ -69,7 +97,10 @@ public final class JdbcOutboxRepository implements OutboxRepository {
WHERE o.message_id = c.message_id
RETURNING o.message_id, o.destination, o.message_type, o.schema_version, o.content_type,
o.payload, o.headers, o.created_at, o.status, o.attempts,
- o.lease_expires_at, o.last_failure_code
+ o.lease_expires_at, o.last_failure_code,
+ 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
""";
/**
@@ -104,7 +135,10 @@ public final class JdbcOutboxRepository implements OutboxRepository {
WHERE o.message_id = c.message_id
RETURNING o.message_id, o.destination, o.message_type, o.schema_version, o.content_type,
o.payload, o.headers, o.created_at, o.status, o.attempts,
- o.lease_expires_at, o.last_failure_code, o.lease_owner, o.lease_token
+ 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;
@@ -144,6 +178,20 @@ public final class JdbcOutboxRepository implements OutboxRepository {
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(
@@ -425,9 +473,7 @@ public final class JdbcOutboxRepository implements OutboxRepository {
connection -> {
try (PreparedStatement statement =
connection.prepareStatement(
- "SELECT message_id, destination, message_type, schema_version, content_type, "
- + "payload, headers, created_at, status, attempts, lease_expires_at, "
- + "last_failure_code FROM messaging_outbox WHERE message_id = ?")) {
+ "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. 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 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 {
@@ -28,7 +43,7 @@ public final class OutboxEnvelopeFactory {
/**
* Creates a factory for one service.
*
- * @param producer the logical producing 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");
@@ -52,13 +67,7 @@ public final class OutboxEnvelopeFactory {
// 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.
- //
- // Partition and ordering keys are the exception: they are reserved names the outbox
- // legitimately carries as routing metadata, and they are read below rather than
- // written as headers.
- if (ReservedHeaders.isReserved(name)
- && !ReservedHeaders.PARTITION_KEY.equals(name)
- && !ReservedHeaders.ORDERING_KEY.equals(name)) {
+ if (ReservedHeaders.isReserved(name)) {
throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException(
"RESERVED_HEADER_IN_OUTBOX_ROW",
"outbox row header '"
@@ -66,26 +75,50 @@ public final class OutboxEnvelopeFactory {
+ "' uses the reserved namespace; canonical identity and metadata come from"
+ " the record's own columns, not from its header map");
}
- if (!ReservedHeaders.isReserved(name)) {
- headers.put(new HeaderName(name), new HeaderValue(value));
- }
+ headers.put(new HeaderName(name), new HeaderValue(value));
});
+ OutboxCanonicalMetadata metadata = record.metadata();
return new MessageEnvelope<>(
record.messageId(),
record.messageType(),
record.schemaVersion(),
record.createdAt(),
- Optional.of(record.createdAt()),
- producer,
- Optional.empty(),
- Optional.empty(),
+ // 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(),
- Optional.ofNullable(record.headers().get(ReservedHeaders.PARTITION_KEY)),
- Optional.ofNullable(record.headers().get(ReservedHeaders.ORDERING_KEY)),
- Optional.empty(),
- TraceContext.none(),
+ metadata.partitionKey(),
+ metadata.orderingKey(),
+ metadata.tenant(),
+ metadata.traceContext(),
MessageHeaders.platform(headers),
- new EncodedMessage(record.payload(), record.contentType(), Optional.empty()));
+ 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 {@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 leased, int published, int ambiguous, int failed, int staleLeases, int exhausted) {
public OutboxRelayReport {
- if (leased < 0 || published < 0 || ambiguous < 0 || failed < 0 || staleLeases < 0) {
+ 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);
+ this(leased, published, ambiguous, failed, 0, 0);
}
}
diff --git a/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelayWorker.java b/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelayWorker.java
new file mode 100644
index 0000000..5a3ac4c
--- /dev/null
+++ b/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelayWorker.java
@@ -0,0 +1,199 @@
+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 final OutboxRelay relay;
+
+ private final OutboxRetryScheduler scheduler;
+
+ private final Supplier 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.
+ failedPasses.incrementAndGet();
+ unproductive = unproductivePasses.incrementAndGet();
+ }
+ completedPasses.incrementAndGet();
+ schedule(scheduler.backoff(unproductive));
+ }
+
+ private int reset() {
+ unproductivePasses.set(0);
+ return 0;
+ }
+}
diff --git a/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRetryScheduler.java b/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRetryScheduler.java
index 093933d..65f234c 100644
--- a/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRetryScheduler.java
+++ b/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRetryScheduler.java
@@ -8,10 +8,12 @@ import java.util.Optional;
/**
* Decides when a relay's next pass should run, and when a record has retried enough.
*
- * The backoff is on the relay, not on the individual record. A broker outage fails
- * every record in the batch for the same reason, so backing off per record would hammer the broker
- * with the whole backlog on a schedule while achieving nothing; backing off the pass lets the
- * broker recover.
+ * 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
@@ -58,6 +60,25 @@ public final class OutboxRetryScheduler {
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));
diff --git a/messaging/messaging-outbox-jdbc-postgresql/src/main/resources/db/migration/messaging/V4__messaging_outbox_canonical_metadata.sql b/messaging/messaging-outbox-jdbc-postgresql/src/main/resources/db/migration/messaging/V4__messaging_outbox_canonical_metadata.sql
new file mode 100644
index 0000000..920ed04
--- /dev/null
+++ b/messaging/messaging-outbox-jdbc-postgresql/src/main/resources/db/migration/messaging/V4__messaging_outbox_canonical_metadata.sql
@@ -0,0 +1,66 @@
+-- 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/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/DebeziumOutboxRecordMapperTest.java b/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/DebeziumOutboxRecordMapperTest.java
index c5b5117..e49e162 100644
--- a/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/DebeziumOutboxRecordMapperTest.java
+++ b/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/DebeziumOutboxRecordMapperTest.java
@@ -12,6 +12,7 @@ import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import dev.caskeleton.messaging.api.header.ReservedHeaders;
import dev.caskeleton.messaging.outbox.DebeziumOutboxProfile.RelayMode;
+import dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata;
import dev.caskeleton.messaging.reliability.OutboxRecord;
import dev.caskeleton.messaging.reliability.OutboxStatus;
import java.nio.charset.StandardCharsets;
@@ -26,6 +27,11 @@ class DebeziumOutboxRecordMapperTest {
private static final MessageId MESSAGE_ID = MessageId.newId();
private static OutboxRecord record(Map 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 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 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 {
+ repository.append(OutboxFixtures.pending());
+ OutboxRelayWorker worker = worker(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) {
+ OutboxRelay relay =
+ new OutboxRelay(
+ repository,
+ 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 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 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();
}
@@ -98,4 +156,45 @@ public final class MessagingAdmissionController {
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) {
+ AtomicInteger counter = perDestination.computeIfAbsent(destination, key -> new AtomicInteger());
+ while (true) {
+ int current = counter.get();
+ if (current >= perDestinationLimit) {
+ return false;
+ }
+ if (counter.compareAndSet(current, current + 1)) {
+ return true;
+ }
+ }
+ }
+
+ /**
+ * 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) {
+ AtomicInteger counter = perDestination.get(destination);
+ if (counter == null) {
+ return false;
+ }
+ int before = counter.getAndUpdate(current -> current > 0 ? current - 1 : current);
+ // Drop the entry at zero, atomically, so the map does not accumulate one counter per
+ // destination ever published to for the life of the process.
+ perDestination.computeIfPresent(destination, (key, value) -> value.get() == 0 ? null : value);
+ return before > 0;
+ }
}
diff --git a/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/MessagingAdmissionControllerTest.java b/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/MessagingAdmissionControllerTest.java
index 4768378..93c7820 100644
--- a/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/MessagingAdmissionControllerTest.java
+++ b/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/MessagingAdmissionControllerTest.java
@@ -26,7 +26,7 @@ class MessagingAdmissionControllerTest {
controller.admit(DESTINATION, 100);
assertThat(controller.inFlight()).isEqualTo(1);
- controller.complete();
+ controller.complete(DESTINATION);
assertThat(controller.inFlight()).isZero();
}
@@ -81,8 +81,8 @@ class MessagingAdmissionControllerTest {
void aReleaseWithoutAnAdmitCannotRaiseTheCeiling() {
MessagingAdmissionController controller = controller(1);
- controller.complete();
- controller.complete();
+ controller.complete(DESTINATION);
+ controller.complete(DESTINATION);
controller.admit(DESTINATION, 100);
assertThatThrownBy(() -> controller.admit(DESTINATION, 100))
@@ -90,6 +90,81 @@ class MessagingAdmissionControllerTest {
.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));
@@ -113,7 +188,7 @@ class MessagingAdmissionControllerTest {
Thread waiter = new Thread(() -> controller.admit(DESTINATION, 100));
waiter.start();
- controller.complete();
+ controller.complete(DESTINATION);
waiter.join(Duration.ofSeconds(5).toMillis());
assertThat(waiter.isAlive()).isFalse();
diff --git a/messaging/messaging-pulsar-experimental/src/test/java/dev/caskeleton/messaging/pulsar/PulsarAdapterContractTest.java b/messaging/messaging-pulsar-experimental/src/test/java/dev/caskeleton/messaging/pulsar/PulsarAdapterContractTest.java
index 0d3c130..0ec8223 100644
--- a/messaging/messaging-pulsar-experimental/src/test/java/dev/caskeleton/messaging/pulsar/PulsarAdapterContractTest.java
+++ b/messaging/messaging-pulsar-experimental/src/test/java/dev/caskeleton/messaging/pulsar/PulsarAdapterContractTest.java
@@ -234,8 +234,7 @@ class PulsarAdapterContractTest {
return new TransportPublishRequest(
profile(),
envelope(64),
- new PublishOptions(
- timeout, defaults.confirmation(), defaults.deduplication(), defaults.brokerHints()));
+ new PublishOptions(timeout, defaults.confirmation(), defaults.deduplication()));
}
private static TransportPublishRequest request(int payloadBytes) {
diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitDeliveryMapper.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitDeliveryMapper.java
index f78d932..0572c18 100644
--- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitDeliveryMapper.java
+++ b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitDeliveryMapper.java
@@ -13,7 +13,6 @@ 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.MessageHeaders;
import dev.caskeleton.messaging.api.header.ReservedHeaders;
import dev.caskeleton.messaging.schema.EncodedMessage;
import java.time.Instant;
@@ -87,12 +86,13 @@ public final class RabbitDeliveryMapper {
contentType,
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.PARTITION_KEY)),
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.ORDERING_KEY)),
- Optional. Everything except the names that were hoisted into envelope fields: the application's own
+ * headers, which were dropped entirely and so never survived a broker hop, and the platform's
+ * retry and redrive bookkeeping, whose loss restarted the attempt counter at one on every
+ * redelivery and left the retry budget capping nothing.
+ *
+ * The hoisted names are excluded rather than kept alongside their fields, because a duplicate
+ * that can drift from the field is how the same message ends up with two different ids depending
+ * on which one the reader trusts.
+ *
+ * @param properties the message properties
+ * @return the headers to carry on the rebuilt envelope
+ */
+ public MessageHeaders carriedForward(MessageProperties properties) {
+ Objects.requireNonNull(properties, "properties must not be null");
+ Map The publish and delivery mappers were written against each other's headers but never checked
+ * as one trip, so the application's own headers were dropped on the way back and the retry
+ * bookkeeping went with them — an attempt counter that restarts on every hop caps no redeliveries
+ * at all.
+ */
+class RabbitEnvelopeRoundTripTest {
+
+ private static final Instant NOW = Instant.parse("2026-08-15T10:00:00Z");
+
+ private final RabbitHeaderMapper headerMapper = new RabbitHeaderMapper();
+
+ private final RabbitDeliveryMapper deliveryMapper = new RabbitDeliveryMapper(headerMapper);
+
+ @Test
+ @DisplayName("an application header survives the trip through the broker")
+ void anApplicationHeaderSurvivesTheTrip() {
+ MessageEnvelope 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 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/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRecord.java b/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRecord.java
index 058c4bb..d694995 100644
--- a/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRecord.java
+++ b/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRecord.java
@@ -23,13 +23,19 @@ import java.util.Optional;
* 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 reserved and application headers to publish
+ * @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
@@ -45,6 +51,7 @@ public record OutboxRecord(
ContentType contentType,
byte[] payload,
Map The transports read {@code request.options()} for nothing: the timeout, the confirmation
- * requirement, the deduplication request and the broker hints were all accepted and ignored. 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.
+ * 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.isM1Compatible()) {
- // isM1Compatible existed and nothing called it, so an ordinary caller could attach M3 broker
- // hints to an M1 publish and have them dropped.
- throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException(
- "PUBLISH_BROKER_HINTS_UNSUPPORTED",
- "broker hints are an M3 surface and this publish path does not forward them; passing"
- + " them here would drop them silently");
- }
if (options.deduplication().isPresent()
&& !transport.capabilities(profile.name()).capabilities().deduplicatedPublish()) {
throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException(
@@ -276,7 +289,7 @@ public final class DefaultMessagePublisher implements MessagePublisher {
FailureCategory.CONFIGURATION, code, false, reason, Optional.empty()))));
}
- private PublishResult ambiguousResult(String reason, long startedAt) {
+ private PublishResult ambiguousResult(String code, String reason, long startedAt) {
return new PublishResult(
PublishCompletion.AMBIGUOUS,
PublishEvidence.ambiguous(),
@@ -286,11 +299,51 @@ public final class DefaultMessagePublisher implements MessagePublisher {
elapsedSince(startedAt),
Optional.of(
new FailureDescriptor(
- FailureCategory.AMBIGUOUS,
- "PUBLISH_OUTCOME_UNKNOWN",
- true,
- reason,
- Optional.empty())));
+ 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 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 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/messaging/messaging-schema-protobuf/build.gradle b/messaging/messaging-schema-protobuf/build.gradle
index d4854f6..560d1df 100644
--- a/messaging/messaging-schema-protobuf/build.gradle
+++ b/messaging/messaging-schema-protobuf/build.gradle
@@ -4,5 +4,7 @@ dependencies {
api project(':messaging:messaging-core-api')
api project(':messaging:messaging-schema-api')
- implementation 'com.google.protobuf:protobuf-java:4.29.3'
+ // 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 'com.google.protobuf:protobuf-java:4.29.3'
}
diff --git a/messaging/messaging-schema-protobuf/src/test/java/dev/caskeleton/messaging/schema/protobuf/ProtobufCompatibilityTest.java b/messaging/messaging-schema-protobuf/src/test/java/dev/caskeleton/messaging/schema/protobuf/ProtobufCompatibilityTest.java
index 9be1fa6..65fe8c5 100644
--- a/messaging/messaging-schema-protobuf/src/test/java/dev/caskeleton/messaging/schema/protobuf/ProtobufCompatibilityTest.java
+++ b/messaging/messaging-schema-protobuf/src/test/java/dev/caskeleton/messaging/schema/protobuf/ProtobufCompatibilityTest.java
@@ -15,6 +15,7 @@ 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;
@@ -231,6 +232,19 @@ class ProtobufCompatibilityTest {
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());
diff --git a/messaging/messaging-spring-boot-starter/build.gradle b/messaging/messaging-spring-boot-starter/build.gradle
index 4e83842..2fe8152 100644
--- a/messaging/messaging-spring-boot-starter/build.gradle
+++ b/messaging/messaging-spring-boot-starter/build.gradle
@@ -41,11 +41,18 @@ dependencies {
annotationProcessor 'org.springframework.boot:spring-boot-configuration-processor'
// The Reactor facade lives here, not in core-api: the core contract stays CompletionStage so
- // that a service which does not use Reactor never inherits it.
- implementation 'io.projectreactor:reactor-core'
+ // that a service which does not use Reactor never inherits it. api, because
+ // ReactiveMessagePublisher returns Mono — a facade whose return type an adopter cannot name
+ // is a facade they cannot call.
+ api 'io.projectreactor:reactor-core'
testImplementation 'io.projectreactor:reactor-test'
testImplementation 'org.springframework.boot:spring-boot-test'
testImplementation 'org.springframework:spring-test'
+ // 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
diff --git a/messaging/messaging-spring-boot-starter/gradle.lockfile b/messaging/messaging-spring-boot-starter/gradle.lockfile
index 3170cc1..020a2ea 100644
--- a/messaging/messaging-spring-boot-starter/gradle.lockfile
+++ b/messaging/messaging-spring-boot-starter/gradle.lockfile
@@ -137,6 +137,7 @@ org.testcontainers:testcontainers-kafka:2.0.2=testCompileClasspath,testRuntimeCl
org.testcontainers:testcontainers:2.0.2=testCompileClasspath,testRuntimeClasspath
org.xerial.snappy:snappy-java:1.1.10.7=runtimeClasspath,testRuntimeClasspath
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
+org.yaml:snakeyaml:2.5=testCompileClasspath,testRuntimeClasspath
tools.jackson.core:jackson-core:3.0.2=runtimeClasspath,testRuntimeClasspath
tools.jackson.core:jackson-databind:3.0.2=runtimeClasspath,testRuntimeClasspath
tools.jackson:jackson-bom:3.0.2=runtimeClasspath,testRuntimeClasspath
diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/BrokerSecuritySettings.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/BrokerSecuritySettings.java
new file mode 100644
index 0000000..0b629b1
--- /dev/null
+++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/BrokerSecuritySettings.java
@@ -0,0 +1,50 @@
+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.
+ *
+ * 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 access which destinations each role may touch
+ */
+public record BrokerSecuritySettings(
+ Credential producer,
+ Credential consumer,
+ Credential admin,
+ @DefaultValue("true") boolean hostnameVerification,
+ @DefaultValue Access access) {
+
+ /**
+ * One credential reference.
+ *
+ * @param type the authentication mechanism
+ * @param credentialId the identifier the credential provider resolves
+ */
+ public record Credential(String type, String credentialId) {}
+
+ /**
+ * Which destinations each role may touch.
+ *
+ * @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 Both broker families are described by one record because a deployment names its brokers in one
+ * map, and a reader of that map should not have to know which half of the fields apply. Which half
+ * does apply is decided by {@link #type()}, and the compiler refuses a field belonging to the other
+ * family rather than ignoring it — a Kafka broker carrying {@code prefetch} is a configuration the
+ * author believed was doing something.
+ *
+ * {@code tlsEnabled} and {@code production} live here rather than beside the credentials, so a
+ * broker is described once. They were previously implied by whichever object happened to be
+ * constructed, which is how a profile can be production in one validator's view and not in
+ * another's.
+ *
+ * @param type the broker family, {@code kafka} or {@code rabbitmq}
+ * @param 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
+ * @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
+ * @param consumerGroup the Kafka consumer group
+ * @param addresses RabbitMQ broker addresses
+ * @param publisherConfirms whether correlated publisher confirms are on
+ * @param publisherReturns whether unroutable returns are delivered
+ * @param mandatory whether publishes carry the mandatory flag
+ * @param confirmTimeout how long to wait for a RabbitMQ confirm
+ * @param autoAck whether the RabbitMQ consumer acknowledges on delivery
+ * @param prefetch the RabbitMQ consumer prefetch window
+ * @param quorumQueues whether durable work queues are declared as quorum queues
+ */
+public record BrokerSettings(
+ String type,
+ @DefaultValue("false") boolean stable,
+ @DefaultValue("false") boolean production,
+ @DefaultValue("false") boolean tlsEnabled,
+ @DefaultValue("false") boolean authenticationEnabled,
+ @DefaultValue List One object rather than four beans, because the four are only meaningful together: a
+ * destination names a broker, a security entry secures one, and a compile that produced three of
+ * the four would leave the fourth silently empty. Holding them as one result means the startup
+ * validations either all see this deployment's configuration or the compile failed.
+ *
+ * @param destinations the destination profiles built from {@code app.messaging.destinations}
+ * @param kafkaBrokers the Kafka profiles built from {@code app.messaging.brokers}
+ * @param rabbitBrokers the RabbitMQ profiles built from {@code app.messaging.brokers}
+ * @param security the broker security profiles built from {@code app.messaging.security}
+ */
+public record CompiledMessagingConfiguration(
+ List Empty is a legitimate state, not a failure: an application may still register its profiles
+ * as beans, which is how this platform worked before anything bound. What is not legitimate is a
+ * deployment that configured destinations and got this — which is why the compiler builds it only
+ * when the sections really are absent.
+ *
+ * @return the empty compilation
+ */
+ public static CompiledMessagingConfiguration empty() {
+ return new CompiledMessagingConfiguration(List.of(), List.of(), List.of(), List.of());
+ }
+}
diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DestinationSettings.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DestinationSettings.java
new file mode 100644
index 0000000..35304c7
--- /dev/null
+++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DestinationSettings.java
@@ -0,0 +1,177 @@
+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.CapabilityTier;
+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") CapabilityTier 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 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 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 {
+
+ /** Broker keys that only a Kafka entry may carry. */
+ private static final Set Both families are described by one record, so a Kafka entry carrying {@code prefetch} binds
+ * without complaint and does nothing. The author of that line believed it was doing something,
+ * which is the same silence this class exists to end.
+ */
+ private java.util.Optional 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 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.
*
- * @param profiles the registered profiles
+ * 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 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 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 backpressure the in-flight counters
+ * @param admission the gate every publish passes through
*/
public MessagingEndpoint(
- ValidatedDestinationRegistry registry, BackpressureController backpressure) {
+ ValidatedDestinationRegistry registry, MessagingAdmissionController admission) {
this.registry = Objects.requireNonNull(registry, "registry must not be null");
- this.backpressure = Objects.requireNonNull(backpressure, "backpressure must not be null");
+ this.admission = Objects.requireNonNull(admission, "admission must not be null");
}
/**
@@ -48,7 +52,7 @@ public class MessagingEndpoint {
@ReadOperation
public Map 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/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProviderSelection.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProviderSelection.java
index e4a39ef..c93129d 100644
--- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProviderSelection.java
+++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProviderSelection.java
@@ -48,11 +48,42 @@ public class MessagingProviderSelection {
"kafka", KafkaMessagingAutoConfiguration.class,
"rabbit", RabbitMessagingAutoConfiguration.class);
+ /**
+ * Broker ids that ship without a {@code MessagingTransport}, and why.
+ *
+ * Registered is not the same as assemblable. The Rabbit leaf ships its profile validator,
+ * failure classifier and security configurer, and no transport — the native channel bridge those
+ * would sit on has only test implementations. Selecting it therefore produced an unsatisfied
+ * dependency on {@code MessagingTransport} deep inside the core configuration, which tells an
+ * operator that a bean is missing rather than that the transport they chose is not finished.
+ *
+ * Refused here instead, next to the other selection errors, so the message names the state the
+ * deployment is actually in. An entry leaves this map on the day its transport does exist.
+ */
+ static final Map 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 {
@@ -55,6 +63,70 @@ public class MessagingReliabilityAutoConfiguration {
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);
+ }
+
+ /**
+ * 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.
*
diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingSettings.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingSettings.java
index 9d22ca8..92fef98 100644
--- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingSettings.java
+++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingSettings.java
@@ -1,6 +1,8 @@
package dev.caskeleton.messaging.autoconfigure;
import java.time.Duration;
+import java.util.LinkedHashMap;
+import java.util.Map;
import org.springframework.boot.context.properties.ConfigurationProperties;
/**
@@ -22,6 +24,17 @@ import org.springframework.boot.context.properties.ConfigurationProperties;
* is still being proven must not become load-bearing because a default turned it on, and the same
* applies to the Spring Cloud Stream bridge, which bypasses the platform's retry and dead letter
* policy by design.
+ *
+ * The destination, broker and security maps are what the configuration reference has always
+ * described and nothing bound. Until they existed, a deployment that configured them exactly as
+ * documented changed no behaviour and produced no error: the profiles the platform actually used
+ * 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 {
@@ -39,6 +52,63 @@ public class MessagingSettings {
private final Bridge bridge = new Bridge();
private final Backpressure backpressure = new Backpressure();
private final Shutdown shutdown = new Shutdown();
+ private Map 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 {
+
+ /** 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 {@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 relay's phase for the
+ * mirror-image reason: refusing admission while a relay pass is mid-publish turns that pass's
+ * rows ambiguous, which is the uncertainty the drain exists to avoid.
+ *
+ * @return the lifecycle phase
+ */
+ @Override
+ public int getPhase() {
+ return Integer.MAX_VALUE - 1024;
+ }
+}
diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/RabbitMessagingAutoConfiguration.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/RabbitMessagingAutoConfiguration.java
index 81ce786..66b14dd 100644
--- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/RabbitMessagingAutoConfiguration.java
+++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/RabbitMessagingAutoConfiguration.java
@@ -36,6 +36,30 @@ public class RabbitMessagingAutoConfiguration {
return new RabbitProfileValidator();
}
+ /**
+ * Runs the RabbitMQ profile validator over every broker profile, declared or configured.
+ *
+ * @param profiles the broker profiles the application declared as beans
+ * @param compiled the broker profiles compiled from {@code app.messaging.brokers}
+ * @param validator the RabbitMQ profile validator
+ * @return the startup validation
+ */
+ @Bean
+ public StartupProfileValidation 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 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.kafkaBrokers())
+ .singleElement()
+ .satisfies(
+ broker -> {
+ assertThat(broker.broker()).isEqualTo("kafka-primary");
+ assertThat(broker.bootstrapServers())
+ .containsExactly("broker-1:9093", "broker-2:9093");
+ assertThat(broker.enableAutoCommit()).isFalse();
+ });
+ assertThat(compiled.rabbitBrokers())
+ .singleElement()
+ .satisfies(broker -> assertThat(broker.quorumQueues()).isTrue());
+ 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 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 aRabbitSettingOnAKafkaBrokerFailsNamingTheKey() {
+ runner
+ .withPropertyValues(minimal())
+ .withPropertyValues("app.messaging.brokers.kafka-primary.prefetch=32")
+ .run(
+ context ->
+ assertThat(context)
+ .hasFailed()
+ .getFailure()
+ .hasMessageContaining("app.messaging.brokers.kafka-primary.prefetch")
+ .hasMessageContaining("RabbitMQ setting on a Kafka broker"));
+ }
+
+ @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
+ void aProductionKafkaBrokerWithoutTransportSecurityFailsStartup() {
+ runner
+ .withConfiguration(AutoConfigurations.of(KafkaMessagingAutoConfiguration.class))
+ .withPropertyValues(minimal())
+ .withPropertyValues(
+ "spring.kafka.bootstrap-servers=localhost:9092",
+ "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",
+ };
+ }
+
+ private ApplicationContextRunner documented() {
+ List 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();
+ }
+
+ /** 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 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 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 {@code BrokerFailureMatrix.shipped()} hard-coded every scenario as {@code LIVE_BROKER} for
- * both brokers, and the suite that "verified" the matrix asserted 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.
+ * 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 and the commit are here
* because "certified" is a claim about a specific broker build and a specific source tree; without
* them the evidence cannot be checked against anything later.
+ *
+ * {@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,
@@ -37,24 +44,103 @@ public record BrokerCertificationEvidence(
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 machine-readable form a release lane writes out. */
+ /** 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() {
- return "{\"adapter\":\""
- + adapter
- + "\",\"brokerImage\":\""
- + brokerImage
- + "\",\"scenario\":\""
- + scenario.name()
- + "\",\"testId\":\""
- + testId
- + "\",\"outcome\":\""
- + outcome
- + "\",\"gitCommit\":\""
- + gitCommit
- + "\",\"observedAt\":\""
- + observedAt
- + "\"}";
+ 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> profiles;
+
+ private final Consumer
> profiles, Consumer