refactor: 각 어댑터터별 리펙토링 진행
This commit is contained in:
@@ -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
|
||||||
@@ -7,60 +7,76 @@
|
|||||||
> either of the old prefixes now fails startup with a message naming the key — see
|
> either of the old prefixes now fails startup with a message naming the key — see
|
||||||
> `MessagingPrefixMigrationValidator`.
|
> `MessagingPrefixMigrationValidator`.
|
||||||
|
|
||||||
|
> **이 페이지는 실행된다.** 아래 YAML 블록은 `MessagingConfigurationBindingTest`가 이 파일에서 직접
|
||||||
|
> 읽어 컨텍스트에 올린다. 문서가 설명하는 모양이 곧 바인딩되는 모양이라는 뜻이고, 문서를 고치면서
|
||||||
|
> 코드를 고치지 않으면 테스트가 깨진다. 이전 판은 destination·broker·security 세 섹션을 설명했지만
|
||||||
|
> 어떤 binder도 그것을 읽지 않았다 — 문서대로 설정한 배포는 아무것도 바뀌지 않았고 아무 말도 듣지
|
||||||
|
> 못했다 (MSG-008).
|
||||||
|
|
||||||
## Destination profile
|
## Destination profile
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
app:
|
app:
|
||||||
messaging:
|
messaging:
|
||||||
destinations:
|
destinations:
|
||||||
order-events:
|
order-events:
|
||||||
broker: kafka-primary
|
broker: kafka-primary
|
||||||
kind: EVENT_STREAM # ASYNC_COMMAND | DOMAIN_EVENT | INTEGRATION_EVENT
|
kind: EVENT_STREAM # ASYNC_COMMAND | DOMAIN_EVENT | INTEGRATION_EVENT
|
||||||
# | WORK_QUEUE | PUBLISH_SUBSCRIBE | EVENT_STREAM | REQUEST_REPLY
|
# | WORK_QUEUE | PUBLISH_SUBSCRIBE | EVENT_STREAM | REQUEST_REPLY
|
||||||
tier: M1 # M1 | M2 | M3
|
tier: M1 # M1 | M2 | M3
|
||||||
physical:
|
physical:
|
||||||
topic: order.events.v1
|
topic: order.events.v1
|
||||||
schema:
|
schema:
|
||||||
codec: application/json
|
codec: application/json
|
||||||
compatibility: BACKWARD_TRANSITIVE
|
compatibility: BACKWARD_TRANSITIVE
|
||||||
message-types: [order.created]
|
message-types: [order.created]
|
||||||
guarantees:
|
guarantees:
|
||||||
delivery: AT_LEAST_ONCE # AT_MOST_ONCE | AT_LEAST_ONCE
|
delivery: AT_LEAST_ONCE # AT_MOST_ONCE | AT_LEAST_ONCE
|
||||||
ordering: KEY # NONE | DESTINATION | PARTITION | KEY
|
ordering: KEY # NONE | DESTINATION | PARTITION | KEY
|
||||||
external-side-effect: INBOX_TRANSACTIONAL
|
external-side-effect: INBOX_TRANSACTIONAL
|
||||||
producer:
|
producer:
|
||||||
confirmation: REPLICATION_OR_PERSISTENCE_ACK
|
confirmation: REPLICATION_OR_PERSISTENCE_ACK
|
||||||
timeout: 5s
|
timeout: 5s
|
||||||
mandatory-routing: true
|
mandatory-routing: true
|
||||||
idempotent: true
|
idempotent: true
|
||||||
consumer:
|
consumer:
|
||||||
group: order-projection
|
group: order-projection
|
||||||
concurrency: 6
|
concurrency: 1 # DESTINATION 순서를 요구하면 1이어야 한다
|
||||||
max-in-flight-per-ordering-unit: 1
|
max-in-flight-per-ordering-unit: 1
|
||||||
prefetch: 16
|
prefetch: 16
|
||||||
handler-timeout: 30s
|
handler-timeout: 30s
|
||||||
manual-settlement: false
|
manual-settlement: false
|
||||||
retry:
|
retry:
|
||||||
mode: PAUSE_PARTITION # NONE | INLINE | BLOCKING | PAUSE_PARTITION
|
mode: PAUSE_PARTITION # NONE | INLINE | BLOCKING | PAUSE_PARTITION
|
||||||
# | RETRY_DESTINATION | BROKER_DELAYED
|
# | RETRY_DESTINATION | BROKER_DELAYED
|
||||||
max-attempts: 3
|
max-attempts: 3
|
||||||
initial-delay: 200ms
|
initial-delay: 200ms
|
||||||
max-delay: 2s
|
max-delay: 2s
|
||||||
multiplier: 2.0
|
multiplier: 2.0
|
||||||
jitter: true
|
jitter: true
|
||||||
ordering-impact: PRESERVE # PRESERVE | ALLOW_REORDER
|
ordering-impact: PRESERVE # PRESERVE | ALLOW_REORDER
|
||||||
dlq:
|
dlq:
|
||||||
destination: order-events-dlq
|
destination: order-events-dlq
|
||||||
max-redrive-count: 1
|
max-redrive-count: 1
|
||||||
payload:
|
payload:
|
||||||
max-bytes: 1048576
|
max-bytes: 1048576
|
||||||
claim-check-threshold-bytes: 1048576
|
claim-check-threshold-bytes: 1048576
|
||||||
key-resolver-configured: true
|
key-resolver-configured: true
|
||||||
production: true
|
production: false
|
||||||
topology-auto-create: 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 | |
|
| Outbox polling | 500ms | |
|
||||||
| metric dimension 상한 | 200 | cardinality 폭발 방지 |
|
| 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
|
## Broker profile
|
||||||
|
|
||||||
|
브로커는 `app.messaging.brokers` 아래에 한 번만 기술한다. `type`이 어느 계열의 설정이 적용되는지
|
||||||
|
결정하며, 다른 계열의 키(Kafka 항목의 `prefetch` 같은)는 무시되지 않고 부팅 실패로 거절된다 —
|
||||||
|
무시하면 그 줄을 쓴 사람은 무언가가 적용됐다고 믿게 된다.
|
||||||
|
|
||||||
### Kafka
|
### Kafka
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
app:
|
app:
|
||||||
messaging:
|
messaging:
|
||||||
brokers:
|
brokers:
|
||||||
kafka-primary:
|
kafka-primary:
|
||||||
type: kafka
|
type: kafka
|
||||||
stable: true
|
stable: true
|
||||||
production: true
|
production: false
|
||||||
bootstrap-servers: [broker-1:9093, broker-2:9093]
|
bootstrap-servers: [broker-1:9093, broker-2:9093]
|
||||||
enable-idempotence: true # stable에서 필수
|
enable-idempotence: true # stable에서 필수
|
||||||
acks: all # stable에서 필수
|
acks: all # stable에서 필수
|
||||||
max-in-flight-requests-per-connection: 5 # 최대 5
|
max-in-flight-requests-per-connection: 5 # 최대 5
|
||||||
delivery-timeout: 30s
|
delivery-timeout: 30s
|
||||||
enable-auto-commit: false # 항상 금지
|
enable-auto-commit: false # 항상 금지
|
||||||
tls-enabled: true # production 필수
|
consumer-group: order-projection
|
||||||
authentication-enabled: true # production 필수
|
tls-enabled: false # production이면 필수
|
||||||
|
authentication-enabled: false # production이면 필수
|
||||||
```
|
```
|
||||||
|
|
||||||
### RabbitMQ
|
### RabbitMQ
|
||||||
@@ -108,40 +134,52 @@ app:
|
|||||||
```yaml
|
```yaml
|
||||||
app:
|
app:
|
||||||
messaging:
|
messaging:
|
||||||
brokers:
|
brokers:
|
||||||
rabbit-primary:
|
rabbit-primary:
|
||||||
type: rabbitmq
|
type: rabbitmq
|
||||||
stable: true
|
stable: true
|
||||||
production: true
|
production: false
|
||||||
addresses: [rabbit-1:5671]
|
addresses: [rabbit-1:5671]
|
||||||
publisher-confirms: true # stable에서 필수
|
publisher-confirms: true # stable에서 필수
|
||||||
publisher-returns: true # stable에서 필수
|
publisher-returns: true # stable에서 필수
|
||||||
mandatory: true # stable에서 필수
|
mandatory: true # stable에서 필수
|
||||||
confirm-timeout: 5s
|
confirm-timeout: 5s
|
||||||
auto-ack: false # 항상 금지
|
auto-ack: false # 항상 금지
|
||||||
prefetch: 16
|
prefetch: 16
|
||||||
quorum-queues: true # durable work queue 필수
|
quorum-queues: true # durable work queue 필수
|
||||||
tls-enabled: true
|
tls-enabled: false
|
||||||
authentication-enabled: true
|
authentication-enabled: false
|
||||||
```
|
```
|
||||||
|
|
||||||
|
`production: true`인 브로커는 `tls-enabled`와 `authentication-enabled`가 모두 참이어야 하고,
|
||||||
|
그렇지 않으면 `KafkaProfileValidator` / `RabbitProfileValidator`가 부팅을 거절한다. 위 예시가
|
||||||
|
`production: false`인 것은 이 페이지가 그대로 실행되는 fixture이기 때문이며, 실 배포는 셋 다 참이다.
|
||||||
|
|
||||||
## 보안
|
## 보안
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
app:
|
app:
|
||||||
messaging:
|
messaging:
|
||||||
security:
|
security:
|
||||||
kafka-primary:
|
kafka-primary:
|
||||||
producer: { type: SASL_SCRAM, credential-id: kafka-producer }
|
producer: { type: SASL_SCRAM, credential-id: kafka-producer }
|
||||||
consumer: { type: SASL_SCRAM, credential-id: kafka-consumer }
|
consumer: { type: SASL_SCRAM, credential-id: kafka-consumer }
|
||||||
# admin은 application runtime에 설정하지 않는다
|
# admin은 application runtime에 설정하지 않는다
|
||||||
hostname-verification: true
|
hostname-verification: true
|
||||||
access:
|
access:
|
||||||
publishable: [order-events]
|
publishable: [order-events]
|
||||||
consumable: []
|
consumable: []
|
||||||
administrable: []
|
administrable: []
|
||||||
```
|
```
|
||||||
|
|
||||||
|
키는 `app.messaging.brokers`에 선언된 브로커 이름과 같아야 한다. `tls-enabled`와 `production`은
|
||||||
|
브로커 쪽에만 있고 여기에 중복되지 않는다 — 하나의 브로커가 두 곳에서 기술되면 두 값이 어긋나는
|
||||||
|
날이 오고, 어느 쪽이 이기는지는 아무도 모른다.
|
||||||
|
|
||||||
|
`credential-id`는 이름일 뿐이고 자격 증명 자체가 아니다. 실제 재료는 `CredentialProvider`가
|
||||||
|
연결 시점에 해석하므로, 설정 덤프나 힙 덤프에서 나오는 것은 이름뿐이다. producer와 consumer는
|
||||||
|
서로 다른 `credential-id`를 써야 하며, 같으면 부팅에 실패한다.
|
||||||
|
|
||||||
## Experimental / Optional
|
## Experimental / Optional
|
||||||
|
|
||||||
기본값은 전부 `false`다.
|
기본값은 전부 `false`다.
|
||||||
@@ -149,12 +187,12 @@ app:
|
|||||||
```yaml
|
```yaml
|
||||||
app:
|
app:
|
||||||
messaging:
|
messaging:
|
||||||
experimental:
|
experimental:
|
||||||
kafka-share: false
|
kafka-share: false
|
||||||
pulsar: false
|
pulsar: false
|
||||||
nats: false
|
nats: false
|
||||||
bridge:
|
bridge:
|
||||||
spring-cloud-stream: false
|
spring-cloud-stream: false
|
||||||
```
|
```
|
||||||
|
|
||||||
## Backpressure
|
## Backpressure
|
||||||
@@ -162,9 +200,24 @@ app:
|
|||||||
```yaml
|
```yaml
|
||||||
app:
|
app:
|
||||||
messaging:
|
messaging:
|
||||||
backpressure:
|
backpressure:
|
||||||
global-limit: 512
|
global-limit: 512
|
||||||
per-destination-limit: 64 # global-limit 이하여야 한다
|
per-destination-limit: 64 # global-limit 이하여야 한다
|
||||||
```
|
```
|
||||||
|
|
||||||
`per-destination-limit > global-limit`이면 global limit이 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를 가르는 밑줄은 둘 안에 있는 밑줄과 구별되지 않으므로,
|
||||||
|
되돌려 쪼개려면 추측해야 한다. 여기서의 추측은 정상 배포를 거절하는 쪽으로 틀리며, 그것은 배포
|
||||||
|
매니페스트에 손으로 적어야 하는 변수에서 오타 하나를 놓치는 것보다 나쁘다.
|
||||||
|
|||||||
@@ -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이었다 — 표와
|
> Kafka 4.2/4.3을 선언했지만 fixture는 `apache/kafka:4.1.0`, lockfile client는 4.1.1이었다 — 표와
|
||||||
> 코드 상수가 서로 일치했을 뿐 어느 쪽도 실행된 적이 없었다. 장애 시나리오 커버리지도 마찬가지로
|
> 코드 상수가 서로 일치했을 뿐 어느 쪽도 실행된 적이 없었다. 장애 시나리오 커버리지도 마찬가지로
|
||||||
@@ -25,7 +31,7 @@
|
|||||||
| 브로커 | 등급 | 인증 기준 | Stable 기능 | 제한 |
|
| 브로커 | 등급 | 인증 기준 | Stable 기능 | 제한 |
|
||||||
|---|---|---|---|---|
|
|---|---|---|---|---|
|
||||||
| Kafka | Stable | 4.1.x | producer idempotence, consumer group, batch, pause/resume, replay, transaction capability | Share Group은 Experimental |
|
| 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 미승격, 기본 비활성 |
|
| 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 없음(플랫폼이 대행), 기본 비활성 |
|
| NATS JetStream | Experimental | 2.14.x | stream, durable consumer, explicit ACK, dedupe, replay | native DLQ 없음(플랫폼이 대행), 기본 비활성 |
|
||||||
| Artemis/JMS | Extension | 범위 밖 | adapter SPI만 | 별도 ADR + Contract Suite 통과 필요 |
|
| Artemis/JMS | Extension | 범위 밖 | adapter SPI만 | 별도 ADR + Contract Suite 통과 필요 |
|
||||||
@@ -86,11 +92,15 @@ Kafka와 RabbitMQ가 동일한 7개 테스트를 변경 없이 통과한다. 결
|
|||||||
|---|---|
|
|---|---|
|
||||||
| `KafkaBrokerIT` | `acks=all`이 실제 replication 증거를 만든다 / 잘못된 토픽은 `REJECTED` / 발행-소비 왕복에서 identity 보존 및 contiguous commit |
|
| `KafkaBrokerIT` | `acks=all`이 실제 replication 증거를 만든다 / 잘못된 토픽은 `REJECTED` / 발행-소비 왕복에서 identity 보존 및 contiguous commit |
|
||||||
| `KafkaAmbiguityChaosIT` | 브로커를 `docker pause`로 멈춘 상태의 publish가 **`AMBIGUOUS`** 로 보고된다 (broker acceptance 없음, confirmation level `NONE`, 비-retryable) |
|
| `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`** 로 보고된다 |
|
| `RabbitBrokerIT` | exchange가 confirm했는데 어떤 큐에도 바인딩되지 않은 publish가 **`REJECTED` + `UNROUTABLE`** 로 보고된다 |
|
||||||
| `OutboxPostgresIT` | 롤백된 트랜잭션은 발행 가능한 행을 남기지 않는다 / `SKIP LOCKED` lease가 두 relay를 분리한다 / ambiguous 행이 같은 `messageId`로 재클레임된다 |
|
| `OutboxPostgresIT` | 롤백된 트랜잭션은 발행 가능한 행을 남기지 않는다 / `SKIP LOCKED` lease가 두 relay를 분리한다 / ambiguous 행이 같은 `messageId`로 재클레임된다 |
|
||||||
| `InboxPostgresIT` | 재전달이 side effect를 두 번 적용하지 않는다 / 롤백은 예약도 되돌린다 |
|
| `InboxPostgresIT` | 재전달이 side effect를 두 번 적용하지 않는다 / 롤백은 예약도 되돌린다 |
|
||||||
|
|
||||||
Docker가 없으면 `DockerAvailability` 가드로 skip되며, 이 표의 항목은 그때 **검증되지 않은 것**으로 취급한다.
|
Docker가 없으면 `DockerAvailability` 가드로 skip되며, 이 표의 항목은 그때 **검증되지 않은 것**으로 취급한다.
|
||||||
|
`KafkaBrokerCertificationIT`만 예외다 — 인증 레인은 가드를 달지 않고 Docker가 없으면 실패한다. skip하는
|
||||||
|
레인은 아무도 켜지 않은 브로커에 대해 성공을 보고하기 때문이다. 그래서 이 레인은 `test`에서 태그로
|
||||||
|
제외되고 `messagingCertificationTest`로만 실행된다.
|
||||||
|
|
||||||
### 3. 장애 시나리오 커버리지 (`BrokerFailureMatrix`)
|
### 3. 장애 시나리오 커버리지 (`BrokerFailureMatrix`)
|
||||||
|
|
||||||
@@ -109,6 +119,18 @@ Docker가 없으면 `DockerAvailability` 가드로 skip되며, 이 표의 항목
|
|||||||
커버해야 하고, Experimental 어댑터는 `LIVE_BROKER` 커버리지를 주장할 수 없다. 커버리지는 *능력*이 아니라
|
커버해야 하고, 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`가 이름으로 들고 있는 미커버 항목으로 남는다.
|
||||||
|
|
||||||
### 실 브로커가 실제로 잡아낸 결함
|
### 실 브로커가 실제로 잡아낸 결함
|
||||||
|
|
||||||
이 스위트들은 장식이 아니다. 작성 과정에서 결정적 테스트가 통과하는데 실 인프라에서 실패한
|
이 스위트들은 장식이 아니다. 작성 과정에서 결정적 테스트가 통과하는데 실 인프라에서 실패한
|
||||||
|
|||||||
+55
-8
@@ -31,25 +31,58 @@ leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이
|
|||||||
|
|
||||||
- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이
|
- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이
|
||||||
숨겨지지 않는다 — consumer가 이 모듈이 문서화한 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`으로 낮춘다.** 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로 취급한다.
|
- 새 public 타입은 그 모듈의 계약이다. 삭제·시그니처 변경은 breaking change로 취급한다.
|
||||||
|
|
||||||
## Runtime membership이 비어 있다는 것의 의미
|
## Runtime membership이 비어 있다는 것의 의미
|
||||||
|
|
||||||
registry의 모든 messaging leaf는 `runtime_memberships`가 비어 있다. 이는 **build-only /
|
**이 절은 한동안 사실이 아닌 채로 남아 있었다.** "registry의 모든 messaging leaf는
|
||||||
incubating**을 뜻한다:
|
`runtime_memberships`가 비어 있고 따라서 build-only"라고 쓰여 있었는데, 다섯 어댑터 remediation이
|
||||||
|
`messaging-spring-boot-starter`를 `app-bootstrap` 의존성으로 넣으면서 그 closure 전체가 런타임
|
||||||
|
classpath에 올라갔다. 정확한 목록은 registry가 소유하므로 여기서 세지 않는다 — 세는 순간 다시
|
||||||
|
drift한다.
|
||||||
|
|
||||||
- 두 composition root(`app-bootstrap`, `sample-portfolio`) 중 어디에도 런타임으로 들어가 있지 않다.
|
지금 의미는 이렇다:
|
||||||
- 따라서 이 leaf들은 컴파일·테스트·계약 검증의 대상이지, 배포된 애플리케이션이 실행하는 코드가
|
|
||||||
아니다.
|
- 대부분의 leaf는 `runtime_memberships`에 `app-bootstrap`을 갖는다. **배포된 아티팩트가 싣고 있고,
|
||||||
- 애플리케이션에 실제로 배선하려면 registry의 `runtime_memberships`를 먼저 바꾸고
|
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`을 통과시켜야 한다. 코드만 추가하는 것으로는 런타임에 들어가지
|
`verifyRuntimeModuleMembership`을 통과시켜야 한다. 코드만 추가하는 것으로는 런타임에 들어가지
|
||||||
않는다.
|
않는다.
|
||||||
- 지원 상태 문서(`docs/messaging/support-matrix.md`)의 tier는 이 사실과 별개다. tier는 "무엇이
|
- 지원 상태 문서(`docs/messaging/support-matrix.md`)의 tier는 이 사실과 별개다. tier는 "무엇이
|
||||||
증명되었는가", membership은 "무엇이 실행되는가"다.
|
증명되었는가", 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 승격에 필요한 증거
|
## Stable 승격에 필요한 증거
|
||||||
|
|
||||||
adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/support-matrix.md`가 현재
|
adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/support-matrix.md`가 현재
|
||||||
@@ -67,6 +100,20 @@ adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/
|
|||||||
|
|
||||||
Stable 문구는 evidence manifest가 존재할 때만 문서에 쓴다.
|
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
|
## Focused test
|
||||||
|
|
||||||
leaf의 `gradle_path`를 registry에서 읽어 파생한다.
|
leaf의 `gradle_path`를 registry에서 읽어 파생한다.
|
||||||
|
|||||||
+11
-4
@@ -3,15 +3,22 @@ package dev.caskeleton.messaging.api;
|
|||||||
/**
|
/**
|
||||||
* Workflow-scoped correlation value shared by every message of one business flow.
|
* Workflow-scoped correlation value shared by every message of one business flow.
|
||||||
*
|
*
|
||||||
* @param value the correlation value, 1 to 160 characters
|
* <p>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) {
|
public record CorrelationId(String value) {
|
||||||
|
|
||||||
private static final int MAX_LENGTH = 160;
|
private static final int MAX_BYTES = 160;
|
||||||
|
|
||||||
public CorrelationId {
|
public CorrelationId {
|
||||||
if (value == null || value.isBlank() || value.length() > MAX_LENGTH) {
|
if (value == null || value.isBlank()) {
|
||||||
throw new IllegalArgumentException("correlationId must contain 1 to 160 characters");
|
throw new IllegalArgumentException("correlationId must not be blank");
|
||||||
}
|
}
|
||||||
|
WireSafeText.require(value, "a correlation id", MAX_BYTES);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+35
@@ -62,8 +62,18 @@ public record MessageEnvelope<T>(
|
|||||||
Objects.requireNonNull(traceContext, "traceContext must not be null");
|
Objects.requireNonNull(traceContext, "traceContext must not be null");
|
||||||
Objects.requireNonNull(headers, "headers must not be null");
|
Objects.requireNonNull(headers, "headers must not be null");
|
||||||
Objects.requireNonNull(payload, "payload must not be null");
|
Objects.requireNonNull(payload, "payload must not be null");
|
||||||
|
// Both keys are routing input the caller chooses, and both used to be unbounded strings. A
|
||||||
|
// partition key is hashed by the broker, so an unbounded one is a cost rather than a
|
||||||
|
// correctness problem; an ordering key is carried on the wire by several bindings, so a
|
||||||
|
// control character in it is the same injection primitive as in a header. The bound is the
|
||||||
|
// smallest one every targeted broker accepts.
|
||||||
|
partitionKey.ifPresent(key -> WireSafeText.require(key, "a partition key", MAX_KEY_BYTES));
|
||||||
|
orderingKey.ifPresent(key -> WireSafeText.require(key, "an ordering key", MAX_KEY_BYTES));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/** The routing-key bound every targeted broker accepts. */
|
||||||
|
private static final int MAX_KEY_BYTES = 1024;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns a copy of this envelope carrying a different payload representation.
|
* Returns a copy of this envelope carrying a different payload representation.
|
||||||
*
|
*
|
||||||
@@ -119,6 +129,31 @@ public record MessageEnvelope<T>(
|
|||||||
payload);
|
payload);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Returns a copy of this envelope bound to a tenant.
|
||||||
|
*
|
||||||
|
* @param tenant the tenant this message belongs to
|
||||||
|
* @return an envelope with identical identity and payload
|
||||||
|
*/
|
||||||
|
public MessageEnvelope<T> withTenant(TenantContext tenant) {
|
||||||
|
return new MessageEnvelope<>(
|
||||||
|
messageId,
|
||||||
|
messageType,
|
||||||
|
schemaVersion,
|
||||||
|
producedAt,
|
||||||
|
occurredAt,
|
||||||
|
producer,
|
||||||
|
correlationId,
|
||||||
|
causationId,
|
||||||
|
contentType,
|
||||||
|
partitionKey,
|
||||||
|
orderingKey,
|
||||||
|
Optional.of(Objects.requireNonNull(tenant, "tenant must not be null")),
|
||||||
|
traceContext,
|
||||||
|
headers,
|
||||||
|
payload);
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns a copy of this envelope carrying replacement headers.
|
* Returns a copy of this envelope carrying replacement headers.
|
||||||
*
|
*
|
||||||
|
|||||||
+5
-28
@@ -6,39 +6,16 @@ package dev.caskeleton.messaging.api;
|
|||||||
* <p>Java class names are deliberately not usable as a message type: renaming or repackaging a
|
* <p>Java class names are deliberately not usable as a message type: renaming or repackaging a
|
||||||
* class must never change the wire contract.
|
* 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) {
|
public record MessageType(String value) {
|
||||||
|
|
||||||
private static final int MAX_LENGTH = 240;
|
private static final int MAX_BYTES = 240;
|
||||||
|
|
||||||
public MessageType {
|
public MessageType {
|
||||||
if (value == null || value.isBlank() || value.length() > MAX_LENGTH) {
|
if (value == null || value.isBlank()) {
|
||||||
throw new IllegalArgumentException("messageType must contain 1 to 240 characters");
|
throw new IllegalArgumentException("messageType must not be blank");
|
||||||
}
|
|
||||||
requireWireSafe(value, "a message type", MAX_LENGTH);
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Characters that must never reach a broker.
|
|
||||||
*
|
|
||||||
* <p>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);
|
|
||||||
}
|
}
|
||||||
|
WireSafeText.require(value, "a message type", MAX_BYTES);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+5
-28
@@ -6,39 +6,16 @@ package dev.caskeleton.messaging.api;
|
|||||||
* <p>This is a deployment-independent service name, not a host, pod, or connection identity, so
|
* <p>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.
|
* 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) {
|
public record ProducerId(String value) {
|
||||||
|
|
||||||
private static final int MAX_LENGTH = 120;
|
private static final int MAX_BYTES = 120;
|
||||||
|
|
||||||
public ProducerId {
|
public ProducerId {
|
||||||
if (value == null || value.isBlank() || value.length() > MAX_LENGTH) {
|
if (value == null || value.isBlank()) {
|
||||||
throw new IllegalArgumentException("producerId must contain 1 to 120 characters");
|
throw new IllegalArgumentException("producerId must not be blank");
|
||||||
}
|
|
||||||
requireWireSafe(value, "a producer id", MAX_LENGTH);
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Characters that must never reach a broker.
|
|
||||||
*
|
|
||||||
* <p>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);
|
|
||||||
}
|
}
|
||||||
|
WireSafeText.require(value, "a producer id", MAX_BYTES);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+111
@@ -1,7 +1,9 @@
|
|||||||
package dev.caskeleton.messaging.api;
|
package dev.caskeleton.messaging.api;
|
||||||
|
|
||||||
|
import java.nio.charset.StandardCharsets;
|
||||||
import java.util.Objects;
|
import java.util.Objects;
|
||||||
import java.util.Optional;
|
import java.util.Optional;
|
||||||
|
import java.util.regex.Pattern;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* W3C trace propagation values carried with a message.
|
* 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
|
* envelope rather than only in headers means a trace survives an Outbox round trip through the
|
||||||
* database, where broker headers do not exist yet.
|
* database, where broker headers do not exist yet.
|
||||||
*
|
*
|
||||||
|
* <p>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 traceparent the {@code traceparent} value when a trace is active
|
||||||
* @param tracestate the {@code tracestate} value when present
|
* @param tracestate the {@code tracestate} value when present
|
||||||
* @param baggage the {@code baggage} value when present
|
* @param baggage the {@code baggage} value when present
|
||||||
@@ -17,10 +26,112 @@ import java.util.Optional;
|
|||||||
public record TraceContext(
|
public record TraceContext(
|
||||||
Optional<String> traceparent, Optional<String> tracestate, Optional<String> baggage) {
|
Optional<String> traceparent, Optional<String> tracestate, Optional<String> baggage) {
|
||||||
|
|
||||||
|
/**
|
||||||
|
* {@code version-traceid-spanid-flags}, all lowercase hex, per the W3C Trace Context grammar.
|
||||||
|
*
|
||||||
|
* <p>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 {
|
public TraceContext {
|
||||||
Objects.requireNonNull(traceparent, "traceparent must not be null");
|
Objects.requireNonNull(traceparent, "traceparent must not be null");
|
||||||
Objects.requireNonNull(tracestate, "tracestate must not be null");
|
Objects.requireNonNull(tracestate, "tracestate must not be null");
|
||||||
Objects.requireNonNull(baggage, "baggage 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 + '\'');
|
||||||
|
}
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|||||||
+65
@@ -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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
+79
@@ -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.
|
||||||
|
*
|
||||||
|
* <p>{@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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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<String> ENVELOPE_FIELDS =
|
||||||
|
Set.of(
|
||||||
|
ReservedHeaders.MESSAGE_ID,
|
||||||
|
ReservedHeaders.MESSAGE_TYPE,
|
||||||
|
ReservedHeaders.SCHEMA_VERSION,
|
||||||
|
ReservedHeaders.PRODUCER,
|
||||||
|
ReservedHeaders.PRODUCED_AT,
|
||||||
|
ReservedHeaders.OCCURRED_AT,
|
||||||
|
ReservedHeaders.CORRELATION_ID,
|
||||||
|
ReservedHeaders.CAUSATION_ID,
|
||||||
|
ReservedHeaders.CONTENT_TYPE,
|
||||||
|
ReservedHeaders.PARTITION_KEY,
|
||||||
|
ReservedHeaders.ORDERING_KEY,
|
||||||
|
ReservedHeaders.TENANT,
|
||||||
|
ReservedHeaders.TRACEPARENT,
|
||||||
|
ReservedHeaders.TRACESTATE,
|
||||||
|
ReservedHeaders.BAGGAGE);
|
||||||
|
|
||||||
|
private CanonicalEnvelopeHeaders() {}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Reports whether a header name restates an envelope field.
|
||||||
|
*
|
||||||
|
* @param name the header name in any case
|
||||||
|
* @return true when the envelope already carries this value in a field of its own
|
||||||
|
*/
|
||||||
|
public static boolean restatesEnvelopeField(String name) {
|
||||||
|
return name != null && ENVELOPE_FIELDS.contains(name.toLowerCase(Locale.ROOT));
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Reports whether a header name is platform bookkeeping that must travel in the header map.
|
||||||
|
*
|
||||||
|
* @param name the header name in any case
|
||||||
|
* @return true for a reserved name with no envelope field behind it
|
||||||
|
*/
|
||||||
|
public static boolean isPlatformBookkeeping(String name) {
|
||||||
|
return ReservedHeaders.isReserved(name) && !restatesEnvelopeField(name);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Returns the reserved names an envelope field owns.
|
||||||
|
*
|
||||||
|
* @return an immutable set of lowercase names
|
||||||
|
*/
|
||||||
|
public static Set<String> envelopeFieldNames() {
|
||||||
|
return ENVELOPE_FIELDS;
|
||||||
|
}
|
||||||
|
}
|
||||||
+9
-6
@@ -1,11 +1,17 @@
|
|||||||
package dev.caskeleton.messaging.api.header;
|
package dev.caskeleton.messaging.api.header;
|
||||||
|
|
||||||
import java.nio.charset.StandardCharsets;
|
import dev.caskeleton.messaging.api.WireSafeText;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Value of a single message header.
|
* Value of a single message header.
|
||||||
*
|
*
|
||||||
* @param value the header value, at most 4096 UTF-8 bytes
|
* <p>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) {
|
public record HeaderValue(String value) {
|
||||||
|
|
||||||
@@ -15,9 +21,6 @@ public record HeaderValue(String value) {
|
|||||||
if (value == null) {
|
if (value == null) {
|
||||||
throw new IllegalArgumentException("header value must not be null");
|
throw new IllegalArgumentException("header value must not be null");
|
||||||
}
|
}
|
||||||
int bytes = value.getBytes(StandardCharsets.UTF_8).length;
|
WireSafeText.require(value, "a header value", MAX_BYTES);
|
||||||
if (bytes > MAX_BYTES) {
|
|
||||||
throw new IllegalArgumentException("header value exceeds 4096 bytes: " + bytes);
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+48
-1
@@ -34,6 +34,31 @@ public final class MessageHeaders {
|
|||||||
"password",
|
"password",
|
||||||
"client_secret");
|
"client_secret");
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Words that make a header name a credential regardless of what surrounds them.
|
||||||
|
*
|
||||||
|
* <p>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<String> SECRET_SEGMENTS =
|
||||||
|
Set.of(
|
||||||
|
"password",
|
||||||
|
"passwd",
|
||||||
|
"secret",
|
||||||
|
"token",
|
||||||
|
"credential",
|
||||||
|
"credentials",
|
||||||
|
"apikey",
|
||||||
|
"authorization",
|
||||||
|
"cookie",
|
||||||
|
"signature");
|
||||||
|
|
||||||
|
private static final java.util.regex.Pattern SEGMENT_SEPARATOR =
|
||||||
|
java.util.regex.Pattern.compile("[._\\-]+");
|
||||||
|
|
||||||
private static final MessageHeaders EMPTY = new MessageHeaders(Map.of());
|
private static final MessageHeaders EMPTY = new MessageHeaders(Map.of());
|
||||||
|
|
||||||
private final Map<HeaderName, HeaderValue> values;
|
private final Map<HeaderName, HeaderValue> values;
|
||||||
@@ -96,7 +121,9 @@ public final class MessageHeaders {
|
|||||||
if (!reservedAllowed && ReservedHeaders.isReserved(normalized)) {
|
if (!reservedAllowed && ReservedHeaders.isReserved(normalized)) {
|
||||||
throw new IllegalArgumentException("message header is not allowed: " + normalized);
|
throw new IllegalArgumentException("message header is not allowed: " + normalized);
|
||||||
}
|
}
|
||||||
if (SECRET_NAMES.contains(normalized)) {
|
if (carriesACredential(normalized)) {
|
||||||
|
// The name is reported and the value never is: an error message is written to a log that
|
||||||
|
// is exactly as readable as the broker storage this check exists to keep the value out of.
|
||||||
throw new IllegalArgumentException("message header is not allowed: " + normalized);
|
throw new IllegalArgumentException("message header is not allowed: " + normalized);
|
||||||
}
|
}
|
||||||
if (!seen.add(normalized)) {
|
if (!seen.add(normalized)) {
|
||||||
@@ -112,6 +139,26 @@ public final class MessageHeaders {
|
|||||||
return new MessageHeaders(Collections.unmodifiableMap(copy));
|
return new MessageHeaders(Collections.unmodifiableMap(copy));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
private static boolean carriesACredential(String normalized) {
|
||||||
|
if (SECRET_NAMES.contains(normalized)) {
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
String[] segments = SEGMENT_SEPARATOR.split(normalized, -1);
|
||||||
|
for (int index = 0; index < segments.length; index++) {
|
||||||
|
if (SECRET_SEGMENTS.contains(segments[index])) {
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
// Adjacent segments are also tested joined, because the same word is written both ways:
|
||||||
|
// `api_key` is one segment to a reader and two to a splitter, and `x-api-key` is two of
|
||||||
|
// three. Joining only neighbouring pairs is what keeps `routing-key` accepted.
|
||||||
|
if (index + 1 < segments.length
|
||||||
|
&& SECRET_SEGMENTS.contains(segments[index] + segments[index + 1])) {
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns the headers as an immutable map.
|
* Returns the headers as an immutable map.
|
||||||
*
|
*
|
||||||
|
|||||||
+26
-1
@@ -45,6 +45,16 @@ public final class ReservedHeaders {
|
|||||||
/** Ordering key. */
|
/** Ordering key. */
|
||||||
public static final String ORDERING_KEY = "msg.ordering-key";
|
public static final String ORDERING_KEY = "msg.ordering-key";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Bounded tenant identity.
|
||||||
|
*
|
||||||
|
* <p>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. */
|
/** Identity of the redrive operation that replayed this message. */
|
||||||
public static final String REDRIVE_ID = "msg.redrive-id";
|
public static final String REDRIVE_ID = "msg.redrive-id";
|
||||||
|
|
||||||
@@ -91,6 +101,7 @@ public final class ReservedHeaders {
|
|||||||
CONTENT_TYPE,
|
CONTENT_TYPE,
|
||||||
PARTITION_KEY,
|
PARTITION_KEY,
|
||||||
ORDERING_KEY,
|
ORDERING_KEY,
|
||||||
|
TENANT,
|
||||||
REDRIVE_ID,
|
REDRIVE_ID,
|
||||||
REDRIVE_COUNT,
|
REDRIVE_COUNT,
|
||||||
RETRY_ATTEMPT,
|
RETRY_ATTEMPT,
|
||||||
@@ -105,6 +116,16 @@ public final class ReservedHeaders {
|
|||||||
|
|
||||||
private ReservedHeaders() {}
|
private ReservedHeaders() {}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The namespace the platform owns, whether or not a name in it exists yet.
|
||||||
|
*
|
||||||
|
* <p>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.
|
* 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
|
* @return true when the platform owns the name
|
||||||
*/
|
*/
|
||||||
public static boolean isReserved(String 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);
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|||||||
+7
-23
@@ -2,27 +2,25 @@ package dev.caskeleton.messaging.api.publish;
|
|||||||
|
|
||||||
import dev.caskeleton.messaging.api.destination.ConfirmationRequirement;
|
import dev.caskeleton.messaging.api.destination.ConfirmationRequirement;
|
||||||
import java.time.Duration;
|
import java.time.Duration;
|
||||||
import java.util.Map;
|
|
||||||
import java.util.Objects;
|
import java.util.Objects;
|
||||||
import java.util.Optional;
|
import java.util.Optional;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Per-call publish options.
|
* Per-call publish options.
|
||||||
*
|
*
|
||||||
* <p>{@code brokerHints} must be empty for M1 callers. Only an M3 native capability may populate
|
* <p>There is no free-form hint map. One existed for a native surface that does not read it, so the
|
||||||
* it, because a hint map on the general API becomes an escape hatch that quietly bypasses
|
* only thing a caller could do with it was pass adapter settings that the publish path refused at
|
||||||
* destination policy.
|
* 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 timeout the publish operation deadline
|
||||||
* @param confirmation the confirmation this call requires
|
* @param confirmation the confirmation this call requires
|
||||||
* @param deduplication optional broker-side duplicate suppression
|
* @param deduplication optional broker-side duplicate suppression
|
||||||
* @param brokerHints M3-only adapter hints
|
|
||||||
*/
|
*/
|
||||||
public record PublishOptions(
|
public record PublishOptions(
|
||||||
Duration timeout,
|
Duration timeout,
|
||||||
ConfirmationRequirement confirmation,
|
ConfirmationRequirement confirmation,
|
||||||
Optional<PublishDeduplication> deduplication,
|
Optional<PublishDeduplication> deduplication) {
|
||||||
Map<String, String> brokerHints) {
|
|
||||||
|
|
||||||
private static final Duration DEFAULT_TIMEOUT = Duration.ofSeconds(5);
|
private static final Duration DEFAULT_TIMEOUT = Duration.ofSeconds(5);
|
||||||
|
|
||||||
@@ -30,32 +28,18 @@ public record PublishOptions(
|
|||||||
Objects.requireNonNull(timeout, "timeout must not be null");
|
Objects.requireNonNull(timeout, "timeout must not be null");
|
||||||
Objects.requireNonNull(confirmation, "confirmation must not be null");
|
Objects.requireNonNull(confirmation, "confirmation must not be null");
|
||||||
Objects.requireNonNull(deduplication, "deduplication must not be null");
|
Objects.requireNonNull(deduplication, "deduplication must not be null");
|
||||||
Objects.requireNonNull(brokerHints, "brokerHints must not be null");
|
|
||||||
if (timeout.isNegative() || timeout.isZero()) {
|
if (timeout.isNegative() || timeout.isZero()) {
|
||||||
throw new IllegalArgumentException("publish timeout must be positive");
|
throw new IllegalArgumentException("publish timeout must be positive");
|
||||||
}
|
}
|
||||||
brokerHints = Map.copyOf(brokerHints);
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns the M1 default: five second timeout, replication evidence, no hints.
|
* Returns the M1 default: five second timeout, replication evidence.
|
||||||
*
|
*
|
||||||
* @return the default options
|
* @return the default options
|
||||||
*/
|
*/
|
||||||
public static PublishOptions defaults() {
|
public static PublishOptions defaults() {
|
||||||
return new PublishOptions(
|
return new PublishOptions(
|
||||||
DEFAULT_TIMEOUT,
|
DEFAULT_TIMEOUT, ConfirmationRequirement.REPLICATION_OR_PERSISTENCE_ACK, Optional.empty());
|
||||||
ConfirmationRequirement.REPLICATION_OR_PERSISTENCE_ACK,
|
|
||||||
Optional.empty(),
|
|
||||||
Map.of());
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Reports whether these options stay inside the M1 surface.
|
|
||||||
*
|
|
||||||
* @return true when no broker hints are present
|
|
||||||
*/
|
|
||||||
public boolean isM1Compatible() {
|
|
||||||
return brokerHints.isEmpty();
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+30
-4
@@ -8,10 +8,16 @@ import java.util.Optional;
|
|||||||
/**
|
/**
|
||||||
* The outcome of one publish call, with the evidence that justifies it.
|
* The outcome of one publish call, with the evidence that justifies it.
|
||||||
*
|
*
|
||||||
* <p>The constructor refuses combinations that would let a caller read a stronger guarantee than
|
* <p>The constructor refuses every combination that would let a caller read a stronger guarantee
|
||||||
* was actually obtained. An adapter that cannot decide must report {@link
|
* than was actually obtained, and every one that contradicts itself: a rejection the broker
|
||||||
* PublishCompletion#AMBIGUOUS} with no confirmation level, which is the conservative answer, rather
|
* acknowledged, a confirmation that does not know whether it routed, an ambiguous outcome the
|
||||||
* than picking a completion that happens to make the call site simpler.
|
* 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.
|
||||||
|
*
|
||||||
|
* <p>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 completion how the attempt ended
|
||||||
* @param evidence the observable facts behind that outcome
|
* @param evidence the observable facts behind that outcome
|
||||||
@@ -72,6 +78,26 @@ public record PublishResult(
|
|||||||
if (completion == PublishCompletion.CONFIRMED && failure.isPresent()) {
|
if (completion == PublishCompletion.CONFIRMED && failure.isPresent()) {
|
||||||
throw new IllegalArgumentException("confirmed publish must not carry a failure descriptor");
|
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");
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|||||||
+208
@@ -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.
|
||||||
|
*
|
||||||
|
* <p>{@link WireSafeValueObjectTest} covers the name side. This covers what was still unbounded
|
||||||
|
* after it: a header <em>value</em> 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();
|
||||||
|
}
|
||||||
|
}
|
||||||
+81
-5
@@ -11,9 +11,90 @@ import org.junit.jupiter.api.Test;
|
|||||||
|
|
||||||
class PublishResultTest {
|
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<String, String> diagnosticAttributes() {
|
||||||
|
return java.util.Map.of("topic", "order-events", "partition", "0", "offset", "17");
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
private static final FailureDescriptor AMBIGUOUS_FAILURE =
|
private static final FailureDescriptor AMBIGUOUS_FAILURE =
|
||||||
FailureDescriptor.of(FailureCategory.AMBIGUOUS, "CONFIRM_TIMEOUT", "confirm timed out");
|
FailureDescriptor.of(FailureCategory.AMBIGUOUS, "CONFIRM_TIMEOUT", "confirm timed out");
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aRejectionCannotClaimTheBrokerAcceptedIt() {
|
||||||
|
PublishEvidence accepted =
|
||||||
|
PublishEvidence.confirmed(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK);
|
||||||
|
|
||||||
|
assertThatThrownBy(
|
||||||
|
() ->
|
||||||
|
new PublishResult(
|
||||||
|
PublishCompletion.REJECTED,
|
||||||
|
accepted,
|
||||||
|
RoutingOutcome.ROUTED,
|
||||||
|
Optional.empty(),
|
||||||
|
1,
|
||||||
|
Duration.ofMillis(10),
|
||||||
|
Optional.of(AMBIGUOUS_FAILURE)))
|
||||||
|
.as("re-publishing a message the broker acknowledged is how one order becomes two")
|
||||||
|
.isInstanceOf(IllegalArgumentException.class);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aConfirmationCannotBeUnsureWhetherItRouted() {
|
||||||
|
assertThatThrownBy(
|
||||||
|
() ->
|
||||||
|
new PublishResult(
|
||||||
|
PublishCompletion.CONFIRMED,
|
||||||
|
PublishEvidence.confirmed(ConfirmationLevel.BROKER_ACK),
|
||||||
|
RoutingOutcome.UNKNOWN,
|
||||||
|
Optional.empty(),
|
||||||
|
1,
|
||||||
|
Duration.ofMillis(10),
|
||||||
|
Optional.empty()))
|
||||||
|
.as("the response that confirmed the publish is the one that says whether it routed")
|
||||||
|
.isInstanceOf(IllegalArgumentException.class);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aRoutedPublishIsNotAmbiguous() {
|
||||||
|
assertThatThrownBy(
|
||||||
|
() ->
|
||||||
|
new PublishResult(
|
||||||
|
PublishCompletion.AMBIGUOUS,
|
||||||
|
PublishEvidence.ambiguous(),
|
||||||
|
RoutingOutcome.ROUTED,
|
||||||
|
Optional.empty(),
|
||||||
|
1,
|
||||||
|
Duration.ofMillis(10),
|
||||||
|
Optional.of(AMBIGUOUS_FAILURE)))
|
||||||
|
.as("only the broker can report routing, and a broker that reported it answered")
|
||||||
|
.isInstanceOf(IllegalArgumentException.class);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void anUntransmittedPublishHasNoBrokerPosition() {
|
||||||
|
assertThatThrownBy(
|
||||||
|
() ->
|
||||||
|
new PublishResult(
|
||||||
|
PublishCompletion.REJECTED,
|
||||||
|
PublishEvidence.notTransmitted(),
|
||||||
|
RoutingOutcome.NOT_APPLICABLE,
|
||||||
|
Optional.of(POSITION),
|
||||||
|
1,
|
||||||
|
Duration.ofMillis(10),
|
||||||
|
Optional.of(AMBIGUOUS_FAILURE)))
|
||||||
|
.as("a coordinate for bytes that never left belongs to some other message")
|
||||||
|
.isInstanceOf(IllegalArgumentException.class);
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
void confirmedResultRequiresBrokerAcceptance() {
|
void confirmedResultRequiresBrokerAcceptance() {
|
||||||
PublishEvidence evidence =
|
PublishEvidence evidence =
|
||||||
@@ -158,9 +239,4 @@ class PublishResultTest {
|
|||||||
Optional.empty()))
|
Optional.empty()))
|
||||||
.isInstanceOf(IllegalArgumentException.class);
|
.isInstanceOf(IllegalArgumentException.class);
|
||||||
}
|
}
|
||||||
|
|
||||||
@Test
|
|
||||||
void m1OptionsCarryNoBrokerHints() {
|
|
||||||
assertThat(PublishOptions.defaults().isM1Compatible()).isTrue();
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -30,3 +30,100 @@ dependencies {
|
|||||||
testImplementation 'org.testcontainers:testcontainers-toxiproxy'
|
testImplementation 'org.testcontainers:testcontainers-toxiproxy'
|
||||||
testImplementation 'eu.rekawek.toxiproxy:toxiproxy-java:2.1.7'
|
testImplementation 'eu.rekawek.toxiproxy:toxiproxy-java:2.1.7'
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// The certification lane, and the gate that makes its output the only source of a Stable claim.
|
||||||
|
//
|
||||||
|
// `CertifiedEvidence` used to be a hand-written list of three scenarios, and every consumer of it —
|
||||||
|
// the compatibility matrix, the cross-broker release suite, the support matrix document — believed
|
||||||
|
// it without a container ever starting. The lane below produces that list, and
|
||||||
|
// `verifyMessagingCertificationEvidence` refuses to pass when the committed manifest claims a
|
||||||
|
// scenario this run did not prove. Editing the manifest by hand therefore fails the build; running
|
||||||
|
// the lane rewrites it.
|
||||||
|
strictTestLanes {
|
||||||
|
lane('messagingCertificationTest') {
|
||||||
|
tag = 'messaging-certification'
|
||||||
|
description = 'Runs the broker fault scenarios against a real Kafka and writes the ' +
|
||||||
|
'certification evidence the compatibility matrix reads.'
|
||||||
|
customize = { test ->
|
||||||
|
// Pinned images. A certification claim names the build it was made against, so a
|
||||||
|
// floating tag would make a red run unattributable and a green one unrepeatable.
|
||||||
|
// `-PmessagingKafkaImage=` overrides for a one-off run against another version.
|
||||||
|
test.systemProperty 'messaging.kafka.image',
|
||||||
|
(project.findProperty('messagingKafkaImage') ?: 'apache/kafka:4.1.0').toString()
|
||||||
|
test.systemProperty 'messaging.toxiproxy.image',
|
||||||
|
(project.findProperty('messagingToxiproxyImage')
|
||||||
|
?: 'ghcr.io/shopify/toxiproxy:2.12.0').toString()
|
||||||
|
test.systemProperty 'messaging.certification.manifest',
|
||||||
|
project.layout.buildDirectory
|
||||||
|
.file('messaging-certification/broker-certification-evidence.jsonl')
|
||||||
|
.get().asFile.absolutePath
|
||||||
|
// The commit is part of the evidence: "certified" is a claim about one source tree.
|
||||||
|
// Read from the environment rather than a `-P` flag so the CI job's command line stays
|
||||||
|
// the literal grammar the gate matrix lint accepts.
|
||||||
|
test.systemProperty 'messaging.certification.commit',
|
||||||
|
(project.findProperty('certificationCommit')
|
||||||
|
?: providers.environmentVariable('GITHUB_SHA').getOrElse('local'))
|
||||||
|
.toString()
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// The certification tag is excluded from `test` because the lane deliberately carries no Docker
|
||||||
|
// guard. Every other container suite here skips with a stated reason when Docker is absent; a lane
|
||||||
|
// that skipped would report success for a broker nobody started, which is the whole failure the
|
||||||
|
// evidence exists to rule out. Keeping it out of `test` is what lets it fail closed without
|
||||||
|
// breaking a laptop build.
|
||||||
|
tasks.named('test', Test) {
|
||||||
|
useJUnitPlatform {
|
||||||
|
excludeTags 'quarantine', 'messaging-certification'
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
tasks.register('verifyMessagingCertificationEvidence') {
|
||||||
|
group = 'verification'
|
||||||
|
description = 'Fails when the committed broker certification manifest claims a scenario the ' +
|
||||||
|
'certification lane did not produce.'
|
||||||
|
dependsOn 'messagingCertificationTest'
|
||||||
|
|
||||||
|
def produced = layout.buildDirectory
|
||||||
|
.file('messaging-certification/broker-certification-evidence.jsonl')
|
||||||
|
def committed = rootProject.file(
|
||||||
|
'messaging/messaging-testkit/src/main/resources/messaging/' +
|
||||||
|
'broker-certification-evidence.jsonl')
|
||||||
|
inputs.file(produced)
|
||||||
|
inputs.file(committed)
|
||||||
|
outputs.file(layout.buildDirectory.file('reports/messaging-certification-evidence.txt'))
|
||||||
|
// A gate whose result can be served from an earlier run is evidence about that run.
|
||||||
|
outputs.upToDateWhen { false }
|
||||||
|
|
||||||
|
doLast {
|
||||||
|
// The commit and the observation instant differ on every run by design, so they are not
|
||||||
|
// part of the comparison — what has to match is which adapter proved which scenario against
|
||||||
|
// which image, and which test produced it.
|
||||||
|
Closure<Set<String>> claims = { File file ->
|
||||||
|
file.readLines('UTF-8')
|
||||||
|
.findAll { !it.trim().isEmpty() }
|
||||||
|
.collect { line ->
|
||||||
|
line.replaceAll(/,"gitCommit":"[^"]*"/, '')
|
||||||
|
.replaceAll(/,"observedAt":"[^"]*"/, '')
|
||||||
|
}
|
||||||
|
.toSet()
|
||||||
|
}
|
||||||
|
Set<String> ran = claims(produced.get().asFile)
|
||||||
|
Set<String> shipped = claims(committed)
|
||||||
|
|
||||||
|
if (ran != shipped) {
|
||||||
|
def unproven = shipped - ran
|
||||||
|
def unrecorded = ran - shipped
|
||||||
|
throw new GradleException(
|
||||||
|
"the committed certification manifest does not match this run.\n" +
|
||||||
|
" claimed but not produced: ${unproven.isEmpty() ? 'none' : unproven}\n" +
|
||||||
|
" produced but not claimed: ${unrecorded.isEmpty() ? 'none' : unrecorded}\n" +
|
||||||
|
"Copy ${produced.get().asFile} over ${committed} — the manifest is a " +
|
||||||
|
"record of a run, not a statement about one.")
|
||||||
|
}
|
||||||
|
def report = outputs.files.singleFile
|
||||||
|
report.parentFile.mkdirs()
|
||||||
|
report.text = "scenarios=${ran.size()} manifest=${committed}\n"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
+3
-3
@@ -13,7 +13,6 @@ import dev.caskeleton.messaging.api.TraceContext;
|
|||||||
import dev.caskeleton.messaging.api.delivery.DeliveryMetadata;
|
import dev.caskeleton.messaging.api.delivery.DeliveryMetadata;
|
||||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||||
import dev.caskeleton.messaging.api.error.MessageValidationException;
|
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.api.header.ReservedHeaders;
|
||||||
import dev.caskeleton.messaging.schema.EncodedMessage;
|
import dev.caskeleton.messaging.schema.EncodedMessage;
|
||||||
import java.time.Instant;
|
import java.time.Instant;
|
||||||
@@ -86,9 +85,10 @@ public final class KafkaDeliveryMapper {
|
|||||||
contentType,
|
contentType,
|
||||||
Optional.ofNullable(headerMapper.value(headers, ReservedHeaders.PARTITION_KEY)),
|
Optional.ofNullable(headerMapper.value(headers, ReservedHeaders.PARTITION_KEY)),
|
||||||
Optional.ofNullable(headerMapper.value(headers, ReservedHeaders.ORDERING_KEY)),
|
Optional.ofNullable(headerMapper.value(headers, ReservedHeaders.ORDERING_KEY)),
|
||||||
Optional.<TenantContext>empty(),
|
Optional.ofNullable(headerMapper.value(headers, ReservedHeaders.TENANT))
|
||||||
|
.map(TenantContext::new),
|
||||||
traceContext(headers),
|
traceContext(headers),
|
||||||
MessageHeaders.empty(),
|
headerMapper.carriedForward(headers),
|
||||||
new EncodedMessage(payload, contentType, Optional.empty()));
|
new EncodedMessage(payload, contentType, Optional.empty()));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
+48
-9
@@ -1,6 +1,7 @@
|
|||||||
package dev.caskeleton.messaging.kafka;
|
package dev.caskeleton.messaging.kafka;
|
||||||
|
|
||||||
import dev.caskeleton.messaging.api.MessageEnvelope;
|
import dev.caskeleton.messaging.api.MessageEnvelope;
|
||||||
|
import dev.caskeleton.messaging.api.header.CanonicalEnvelopeHeaders;
|
||||||
import dev.caskeleton.messaging.api.header.HeaderName;
|
import dev.caskeleton.messaging.api.header.HeaderName;
|
||||||
import dev.caskeleton.messaging.api.header.HeaderValue;
|
import dev.caskeleton.messaging.api.header.HeaderValue;
|
||||||
import dev.caskeleton.messaging.api.header.MessageHeaders;
|
import dev.caskeleton.messaging.api.header.MessageHeaders;
|
||||||
@@ -54,6 +55,12 @@ public final class KafkaHeaderMapper {
|
|||||||
value -> put(headers, ReservedHeaders.CAUSATION_ID, value.value().value().toString()));
|
value -> put(headers, ReservedHeaders.CAUSATION_ID, value.value().value().toString()));
|
||||||
envelope.partitionKey().ifPresent(value -> put(headers, ReservedHeaders.PARTITION_KEY, value));
|
envelope.partitionKey().ifPresent(value -> put(headers, ReservedHeaders.PARTITION_KEY, value));
|
||||||
envelope.orderingKey().ifPresent(value -> put(headers, ReservedHeaders.ORDERING_KEY, value));
|
envelope.orderingKey().ifPresent(value -> put(headers, ReservedHeaders.ORDERING_KEY, value));
|
||||||
|
// Written because the consumer has no other way to learn it: a broker record carries no
|
||||||
|
// ambient tenant, so a tenant left off the wire is a tenant the consumed envelope does not
|
||||||
|
// have — and every authorization and partitioning decision downstream reads that field.
|
||||||
|
envelope
|
||||||
|
.tenantContext()
|
||||||
|
.ifPresent(value -> put(headers, ReservedHeaders.TENANT, value.tenantId()));
|
||||||
envelope
|
envelope
|
||||||
.traceContext()
|
.traceContext()
|
||||||
.traceparent()
|
.traceparent()
|
||||||
@@ -67,24 +74,26 @@ public final class KafkaHeaderMapper {
|
|||||||
.baggage()
|
.baggage()
|
||||||
.ifPresent(value -> put(headers, ReservedHeaders.BAGGAGE, value));
|
.ifPresent(value -> put(headers, ReservedHeaders.BAGGAGE, value));
|
||||||
|
|
||||||
// Application headers are written last and must not be able to reach a reserved name.
|
// The envelope's own header map is written last and the consumer reads `lastHeader`, so a name
|
||||||
|
// written here wins over the canonical value above. A row in the outbox carrying `msg.id`
|
||||||
|
// therefore overwrote the identity that inbox deduplication and the audit trail key on,
|
||||||
|
// corrupting a different message's dedup state rather than merely its own.
|
||||||
//
|
//
|
||||||
// They used to be appended after the canonical ones, and the consumer reads `lastHeader` — so a
|
// Only names that restate an envelope field are refused. Retry attempt, failure and redrive
|
||||||
// row in the outbox carrying `msg.id` overwrote the canonical message identity on the wire.
|
// bookkeeping have no envelope field to be read back from, so refusing them would make every
|
||||||
// That identity is what inbox deduplication and the audit trail key on, so a forged one
|
// retry-topic and dead-letter re-publish fail on the guard meant to protect identity.
|
||||||
// corrupts another message's dedup state rather than merely its own.
|
|
||||||
envelope
|
envelope
|
||||||
.headers()
|
.headers()
|
||||||
.asMap()
|
.asMap()
|
||||||
.forEach(
|
.forEach(
|
||||||
(name, value) -> {
|
(name, value) -> {
|
||||||
if (ReservedHeaders.isReserved(name.value())) {
|
if (CanonicalEnvelopeHeaders.restatesEnvelopeField(name.value())) {
|
||||||
throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException(
|
throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException(
|
||||||
"RESERVED_HEADER_FORGED",
|
"RESERVED_HEADER_FORGED",
|
||||||
"application header '"
|
"header '"
|
||||||
+ name.value()
|
+ name.value()
|
||||||
+ "' uses the reserved namespace; the canonical value is written by the"
|
+ "' restates a value the envelope already carries; the canonical value is"
|
||||||
+ " platform and must not be overridable by message content");
|
+ " written by the platform and must not be overridable by message content");
|
||||||
}
|
}
|
||||||
put(headers, name.value(), value.value());
|
put(headers, name.value(), value.value());
|
||||||
});
|
});
|
||||||
@@ -110,6 +119,36 @@ public final class KafkaHeaderMapper {
|
|||||||
return MessageHeaders.platform(values);
|
return MessageHeaders.platform(values);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Reads back the headers a rebuilt envelope keeps.
|
||||||
|
*
|
||||||
|
* <p>Everything except the names that were hoisted into envelope fields: the application's own
|
||||||
|
* headers, which were dropped entirely and so never survived a broker hop, and the platform's
|
||||||
|
* retry and redrive bookkeeping, whose loss restarted the attempt counter at one on every
|
||||||
|
* redelivery and left the retry budget capping nothing.
|
||||||
|
*
|
||||||
|
* <p>The hoisted names are excluded rather than kept alongside their fields, because a duplicate
|
||||||
|
* that can drift from the field is how the same message ends up with two different ids depending
|
||||||
|
* on which one the reader trusts.
|
||||||
|
*
|
||||||
|
* @param 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<HeaderName, HeaderValue> values = new LinkedHashMap<>();
|
||||||
|
for (Header header : headers) {
|
||||||
|
if (CanonicalEnvelopeHeaders.restatesEnvelopeField(header.key())) {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
byte[] value = header.value();
|
||||||
|
values.put(
|
||||||
|
new HeaderName(header.key()),
|
||||||
|
new HeaderValue(value == null ? "" : new String(value, StandardCharsets.UTF_8)));
|
||||||
|
}
|
||||||
|
return MessageHeaders.platform(values);
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Reads one header value.
|
* Reads one header value.
|
||||||
*
|
*
|
||||||
|
|||||||
+463
@@ -0,0 +1,463 @@
|
|||||||
|
package dev.caskeleton.messaging.kafka;
|
||||||
|
|
||||||
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.api.publish.ConfirmationLevel;
|
||||||
|
import dev.caskeleton.messaging.api.publish.PublishCompletion;
|
||||||
|
import dev.caskeleton.messaging.api.publish.PublishOptions;
|
||||||
|
import dev.caskeleton.messaging.api.publish.PublishResult;
|
||||||
|
import dev.caskeleton.messaging.api.publish.TransmissionEvidence;
|
||||||
|
import dev.caskeleton.messaging.testkit.BrokerCertificationEvidence;
|
||||||
|
import dev.caskeleton.messaging.testkit.NetworkFaultScenario;
|
||||||
|
import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator;
|
||||||
|
import dev.caskeleton.messaging.transport.TransportConsumerSpec;
|
||||||
|
import dev.caskeleton.messaging.transport.TransportDelivery;
|
||||||
|
import dev.caskeleton.messaging.transport.TransportPublishRequest;
|
||||||
|
import eu.rekawek.toxiproxy.Proxy;
|
||||||
|
import eu.rekawek.toxiproxy.ToxiproxyClient;
|
||||||
|
import eu.rekawek.toxiproxy.model.Toxic;
|
||||||
|
import eu.rekawek.toxiproxy.model.ToxicDirection;
|
||||||
|
import java.io.IOException;
|
||||||
|
import java.nio.charset.StandardCharsets;
|
||||||
|
import java.nio.file.Files;
|
||||||
|
import java.nio.file.Path;
|
||||||
|
import java.time.Duration;
|
||||||
|
import java.time.Instant;
|
||||||
|
import java.util.ArrayList;
|
||||||
|
import java.util.List;
|
||||||
|
import java.util.Map;
|
||||||
|
import java.util.Properties;
|
||||||
|
import java.util.concurrent.CompletableFuture;
|
||||||
|
import java.util.concurrent.CopyOnWriteArrayList;
|
||||||
|
import java.util.concurrent.TimeUnit;
|
||||||
|
import org.apache.kafka.clients.admin.Admin;
|
||||||
|
import org.apache.kafka.clients.admin.AdminClientConfig;
|
||||||
|
import org.apache.kafka.clients.admin.NewTopic;
|
||||||
|
import org.apache.kafka.clients.consumer.Consumer;
|
||||||
|
import org.apache.kafka.clients.consumer.ConsumerConfig;
|
||||||
|
import org.apache.kafka.clients.consumer.KafkaConsumer;
|
||||||
|
import org.apache.kafka.clients.producer.KafkaProducer;
|
||||||
|
import org.apache.kafka.clients.producer.Producer;
|
||||||
|
import org.apache.kafka.clients.producer.ProducerConfig;
|
||||||
|
import org.apache.kafka.common.serialization.ByteArrayDeserializer;
|
||||||
|
import org.apache.kafka.common.serialization.ByteArraySerializer;
|
||||||
|
import org.junit.jupiter.api.AfterAll;
|
||||||
|
import org.junit.jupiter.api.AfterEach;
|
||||||
|
import org.junit.jupiter.api.BeforeAll;
|
||||||
|
import org.junit.jupiter.api.Tag;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
import org.testcontainers.containers.Network;
|
||||||
|
import org.testcontainers.kafka.KafkaContainer;
|
||||||
|
import org.testcontainers.toxiproxy.ToxiproxyContainer;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The certification lane: every fault scenario this adapter claims, run against a real broker, with
|
||||||
|
* the run's own output as the evidence.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>{@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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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<BrokerCertificationEvidence> OBSERVED = new CopyOnWriteArrayList<>();
|
||||||
|
|
||||||
|
private static Network network;
|
||||||
|
private static ToxiproxyContainer toxiproxy;
|
||||||
|
private static KafkaContainer kafka;
|
||||||
|
private static Proxy brokerProxy;
|
||||||
|
private static String bootstrapServers;
|
||||||
|
|
||||||
|
@BeforeAll
|
||||||
|
static void startBrokerBehindAProxy() throws IOException {
|
||||||
|
network = Network.newNetwork();
|
||||||
|
toxiproxy = new ToxiproxyContainer(TOXIPROXY_IMAGE).withNetwork(network);
|
||||||
|
toxiproxy.start();
|
||||||
|
|
||||||
|
ToxiproxyClient toxiproxyClient =
|
||||||
|
new ToxiproxyClient(toxiproxy.getHost(), toxiproxy.getControlPort());
|
||||||
|
brokerProxy =
|
||||||
|
toxiproxyClient.createProxy(
|
||||||
|
"messaging-kafka", "0.0.0.0:" + PROXY_PORT, "kafka:" + BROKER_PORT);
|
||||||
|
bootstrapServers = toxiproxy.getHost() + ":" + toxiproxy.getMappedPort(PROXY_PORT);
|
||||||
|
|
||||||
|
kafka =
|
||||||
|
new KafkaContainer(IMAGE)
|
||||||
|
.withNetwork(network)
|
||||||
|
.withNetworkAliases("kafka")
|
||||||
|
// The advertised listener is the proxy, so a client that follows the broker's own
|
||||||
|
// metadata still arrives through the fault injector. Advertising the container instead
|
||||||
|
// would let every connection after the bootstrap bypass the proxy, and the suite would
|
||||||
|
// certify a data path it never faulted.
|
||||||
|
.withListener("kafka:" + BROKER_PORT, () -> bootstrapServers);
|
||||||
|
kafka.start();
|
||||||
|
}
|
||||||
|
|
||||||
|
@AfterEach
|
||||||
|
void clearInjectedFaults() throws IOException {
|
||||||
|
for (Toxic toxic : brokerProxy.toxics().getAll()) {
|
||||||
|
toxic.remove();
|
||||||
|
}
|
||||||
|
brokerProxy.enable();
|
||||||
|
}
|
||||||
|
|
||||||
|
@AfterAll
|
||||||
|
static void writeEvidence() throws IOException {
|
||||||
|
Path manifest =
|
||||||
|
Path.of(
|
||||||
|
System.getProperty(
|
||||||
|
"messaging.certification.manifest",
|
||||||
|
"build/messaging-certification/broker-certification-evidence.jsonl"));
|
||||||
|
Files.createDirectories(manifest.toAbsolutePath().getParent());
|
||||||
|
List<String> lines =
|
||||||
|
OBSERVED.stream()
|
||||||
|
.sorted(java.util.Comparator.comparing(evidence -> evidence.scenario().name()))
|
||||||
|
.map(BrokerCertificationEvidence::toJson)
|
||||||
|
.toList();
|
||||||
|
Files.write(manifest, lines, StandardCharsets.UTF_8);
|
||||||
|
|
||||||
|
if (kafka != null) {
|
||||||
|
kafka.stop();
|
||||||
|
}
|
||||||
|
if (toxiproxy != null) {
|
||||||
|
toxiproxy.stop();
|
||||||
|
}
|
||||||
|
if (network != null) {
|
||||||
|
network.close();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aConnectionCutAfterTheWriteIsReportedAsAmbiguous() throws IOException {
|
||||||
|
String topic = createTopic("certification.cut");
|
||||||
|
try (Producer<byte[], byte[]> producer = producer()) {
|
||||||
|
KafkaMessagingTransport transport = new KafkaMessagingTransport("kafka-primary", 1, producer);
|
||||||
|
// A warm-up publish so metadata and the broker connection already exist. Without it the
|
||||||
|
// failure under test would be a metadata lookup that never started, which is a different
|
||||||
|
// scenario with a different honest answer.
|
||||||
|
assertThat(publish(transport, topic, "warm-up").completion())
|
||||||
|
.isEqualTo(PublishCompletion.CONFIRMED);
|
||||||
|
|
||||||
|
brokerProxy.disable();
|
||||||
|
PublishResult result = publish(transport, topic, "cut");
|
||||||
|
|
||||||
|
assertAmbiguous(result);
|
||||||
|
record(
|
||||||
|
NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE,
|
||||||
|
"KafkaBrokerCertificationIT#aConnectionCutAfterTheWriteIsReportedAsAmbiguous",
|
||||||
|
result);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aConfirmThatNeverArrivesIsReportedAsAmbiguousAndTheRecordIsThere() throws IOException {
|
||||||
|
String topic = createTopic("certification.confirm");
|
||||||
|
try (Producer<byte[], byte[]> producer = producer()) {
|
||||||
|
KafkaMessagingTransport transport = new KafkaMessagingTransport("kafka-primary", 1, producer);
|
||||||
|
assertThat(publish(transport, topic, "warm-up").completion())
|
||||||
|
.isEqualTo(PublishCompletion.CONFIRMED);
|
||||||
|
|
||||||
|
// Only the broker's answers are stopped. The produce request still lands, so this is the
|
||||||
|
// case where the record really is stored and only the acknowledgement is missing — the exact
|
||||||
|
// state in which reporting a rejection would lose a message the broker is holding.
|
||||||
|
brokerProxy.toxics().timeout("confirm-lost", ToxicDirection.DOWNSTREAM, 0);
|
||||||
|
PublishResult result = publish(transport, topic, "confirm-lost");
|
||||||
|
assertAmbiguous(result);
|
||||||
|
|
||||||
|
clearInjectedFaults();
|
||||||
|
assertThat(recordCount(topic))
|
||||||
|
.as("the broker kept both records, so AMBIGUOUS was the true answer and REJECTED a lie")
|
||||||
|
.isEqualTo(2);
|
||||||
|
|
||||||
|
record(
|
||||||
|
NetworkFaultScenario.CONFIRM_TIMEOUT,
|
||||||
|
"KafkaBrokerCertificationIT#aConfirmThatNeverArrivesIsReportedAsAmbiguousAndTheRecordIsThere",
|
||||||
|
result);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void latencyBeyondThePublishDeadlineIsReportedAsAmbiguous() throws IOException {
|
||||||
|
String topic = createTopic("certification.latency");
|
||||||
|
try (Producer<byte[], byte[]> producer = producer()) {
|
||||||
|
KafkaMessagingTransport transport = new KafkaMessagingTransport("kafka-primary", 1, producer);
|
||||||
|
assertThat(publish(transport, topic, "warm-up").completion())
|
||||||
|
.isEqualTo(PublishCompletion.CONFIRMED);
|
||||||
|
|
||||||
|
// Slow, not broken: nothing is dropped and no connection closes. At the moment the deadline
|
||||||
|
// expires the caller cannot tell this apart from a lost confirm, and the platform's answer
|
||||||
|
// must be the same for both.
|
||||||
|
brokerProxy
|
||||||
|
.toxics()
|
||||||
|
.latency("high-latency", ToxicDirection.DOWNSTREAM, DELIVERY_TIMEOUT.toMillis() * 2);
|
||||||
|
PublishResult result = publish(transport, topic, "slow");
|
||||||
|
|
||||||
|
assertAmbiguous(result);
|
||||||
|
record(
|
||||||
|
NetworkFaultScenario.HIGH_LATENCY,
|
||||||
|
"KafkaBrokerCertificationIT#latencyBeyondThePublishDeadlineIsReportedAsAmbiguous",
|
||||||
|
result);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aDeliveryLostBeforeSettlementIsRedelivered() throws IOException {
|
||||||
|
String topic = createTopic("certification.settlement");
|
||||||
|
String group = "certification-" + System.nanoTime();
|
||||||
|
try (Producer<byte[], byte[]> producer = producer()) {
|
||||||
|
KafkaMessagingTransport transport = new KafkaMessagingTransport("kafka-primary", 1, producer);
|
||||||
|
assertThat(publish(transport, topic, "settle-me").completion())
|
||||||
|
.isEqualTo(PublishCompletion.CONFIRMED);
|
||||||
|
}
|
||||||
|
|
||||||
|
List<TransportDelivery> firstAttempt = new ArrayList<>();
|
||||||
|
try (Consumer<byte[], byte[]> first = consumer(group)) {
|
||||||
|
KafkaConsumerRegistrar registrar = registrar(topic, first, firstAttempt, false);
|
||||||
|
registrar.subscribe(topic);
|
||||||
|
drain(registrar, firstAttempt);
|
||||||
|
// The broker disappears while the delivery is unsettled. That is what makes the settlement
|
||||||
|
// lost rather than merely withheld: the consumer had the record and no acknowledgement could
|
||||||
|
// reach the broker even if the handler had produced one.
|
||||||
|
brokerProxy.disable();
|
||||||
|
registrar.pollOnce(NOW);
|
||||||
|
brokerProxy.enable();
|
||||||
|
|
||||||
|
assertThat(registrar.committedOffset(new org.apache.kafka.common.TopicPartition(topic, 0)))
|
||||||
|
.as("nothing was committed, so the record is still owed to this group")
|
||||||
|
.isEmpty();
|
||||||
|
registrar.close();
|
||||||
|
}
|
||||||
|
|
||||||
|
assertThat(firstAttempt).as("the first consumer received the record").hasSize(1);
|
||||||
|
|
||||||
|
List<TransportDelivery> secondAttempt = new ArrayList<>();
|
||||||
|
try (Consumer<byte[], byte[]> second = consumer(group)) {
|
||||||
|
KafkaConsumerRegistrar registrar = registrar(topic, second, secondAttempt, true);
|
||||||
|
registrar.subscribe(topic);
|
||||||
|
// Longer than the other drains: this consumer is joining a group whose previous member left
|
||||||
|
// under a network fault, so the first poll may sit through a rebalance rather than a fetch.
|
||||||
|
drain(registrar, secondAttempt, 80);
|
||||||
|
registrar.close();
|
||||||
|
}
|
||||||
|
|
||||||
|
assertThat(secondAttempt)
|
||||||
|
.as("an unsettled delivery is redelivered; the handler is idempotent, not the platform")
|
||||||
|
.hasSize(1);
|
||||||
|
record(
|
||||||
|
NetworkFaultScenario.SETTLEMENT_LOST,
|
||||||
|
"KafkaBrokerCertificationIT#aDeliveryLostBeforeSettlementIsRedelivered",
|
||||||
|
NetworkFaultScenario.Expectation.REDELIVERED);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static void assertAmbiguous(PublishResult result) {
|
||||||
|
assertThat(result.completion()).isEqualTo(PublishCompletion.AMBIGUOUS);
|
||||||
|
assertThat(result.evidence().transmission())
|
||||||
|
.isEqualTo(TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED);
|
||||||
|
assertThat(result.evidence().brokerAccepted())
|
||||||
|
.as("nothing proves the broker took it")
|
||||||
|
.isFalse();
|
||||||
|
assertThat(result.evidence().confirmationLevel()).isEqualTo(ConfirmationLevel.NONE);
|
||||||
|
assertThat(result.mayHaveBeenStored()).isTrue();
|
||||||
|
assertThat(result.failure().orElseThrow().retryable())
|
||||||
|
.as("an ambiguous publish is not silently retried; the caller decides, under the same id")
|
||||||
|
.isFalse();
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Records what the run observed, translated from the platform's own reported completion.
|
||||||
|
*
|
||||||
|
* <p>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<byte[], byte[]> consumer = consumer("count-" + System.nanoTime())) {
|
||||||
|
consumer.subscribe(List.of(topic));
|
||||||
|
int seen = 0;
|
||||||
|
for (int attempt = 0; attempt < 10; attempt++) {
|
||||||
|
seen += consumer.poll(Duration.ofMillis(500)).count();
|
||||||
|
}
|
||||||
|
return seen;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
private static Producer<byte[], byte[]> producer() {
|
||||||
|
Properties config = new Properties();
|
||||||
|
config.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers);
|
||||||
|
config.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, ByteArraySerializer.class.getName());
|
||||||
|
config.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, ByteArraySerializer.class.getName());
|
||||||
|
// The Stable profile's durability. A lane that quietly weakened these would certify a
|
||||||
|
// configuration the platform refuses to run.
|
||||||
|
config.put(ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true);
|
||||||
|
config.put(ProducerConfig.ACKS_CONFIG, "all");
|
||||||
|
config.put(ProducerConfig.DELIVERY_TIMEOUT_MS_CONFIG, (int) DELIVERY_TIMEOUT.toMillis());
|
||||||
|
config.put(ProducerConfig.REQUEST_TIMEOUT_MS_CONFIG, 2_000);
|
||||||
|
config.put(ProducerConfig.MAX_BLOCK_MS_CONFIG, (int) DELIVERY_TIMEOUT.toMillis());
|
||||||
|
return new KafkaProducer<>(config);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static Consumer<byte[], byte[]> consumer(String group) {
|
||||||
|
Properties config = new Properties();
|
||||||
|
config.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers);
|
||||||
|
config.put(ConsumerConfig.GROUP_ID_CONFIG, group);
|
||||||
|
config.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, ByteArrayDeserializer.class.getName());
|
||||||
|
config.put(
|
||||||
|
ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, ByteArrayDeserializer.class.getName());
|
||||||
|
config.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");
|
||||||
|
config.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, false);
|
||||||
|
// Short group timeouts. The settlement scenario kills the connection under a live member, so
|
||||||
|
// its departure may reach the broker as a session expiry rather than as a clean leave; with the
|
||||||
|
// defaults the replacement consumer would then wait three quarters of a minute for the group to
|
||||||
|
// rebalance and the suite would time out before the redelivery it is certifying ever happened.
|
||||||
|
config.put(ConsumerConfig.SESSION_TIMEOUT_MS_CONFIG, 6_000);
|
||||||
|
config.put(ConsumerConfig.HEARTBEAT_INTERVAL_MS_CONFIG, 2_000);
|
||||||
|
config.put(ConsumerConfig.MAX_POLL_INTERVAL_MS_CONFIG, 20_000);
|
||||||
|
return new KafkaConsumer<>(config);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static KafkaConsumerRegistrar registrar(
|
||||||
|
String topic,
|
||||||
|
Consumer<byte[], byte[]> consumer,
|
||||||
|
List<TransportDelivery> handled,
|
||||||
|
boolean settle) {
|
||||||
|
return new KafkaConsumerRegistrar(
|
||||||
|
new TransportConsumerSpec(
|
||||||
|
KafkaFixtureProfiles.withTopic(topic),
|
||||||
|
delivery -> {
|
||||||
|
handled.add(delivery);
|
||||||
|
if (settle) {
|
||||||
|
delivery.settlement().acknowledge().toCompletableFuture().join();
|
||||||
|
}
|
||||||
|
return CompletableFuture.completedFuture(null);
|
||||||
|
}),
|
||||||
|
consumer,
|
||||||
|
Runnable::run,
|
||||||
|
new GracefulShutdownCoordinator(Duration.ofSeconds(30)),
|
||||||
|
Duration.ofMillis(500));
|
||||||
|
}
|
||||||
|
|
||||||
|
private static void drain(KafkaConsumerRegistrar registrar, List<TransportDelivery> handled) {
|
||||||
|
drain(registrar, handled, 20);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static void drain(
|
||||||
|
KafkaConsumerRegistrar registrar, List<TransportDelivery> handled, int attempts) {
|
||||||
|
for (int attempt = 0; attempt < attempts && handled.isEmpty(); attempt++) {
|
||||||
|
registrar.pollOnce(NOW);
|
||||||
|
}
|
||||||
|
// One more cycle so the settlements the handler queued are applied and committed.
|
||||||
|
registrar.pollOnce(NOW);
|
||||||
|
}
|
||||||
|
}
|
||||||
+154
@@ -0,0 +1,154 @@
|
|||||||
|
package dev.caskeleton.messaging.kafka;
|
||||||
|
|
||||||
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
import static org.assertj.core.api.Assertions.assertThatCode;
|
||||||
|
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.api.MessageEnvelope;
|
||||||
|
import dev.caskeleton.messaging.api.error.FailureCategory;
|
||||||
|
import dev.caskeleton.messaging.api.error.FailureDescriptor;
|
||||||
|
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
|
||||||
|
import dev.caskeleton.messaging.api.header.HeaderName;
|
||||||
|
import dev.caskeleton.messaging.api.header.HeaderValue;
|
||||||
|
import dev.caskeleton.messaging.api.header.MessageHeaders;
|
||||||
|
import dev.caskeleton.messaging.api.header.ReservedHeaders;
|
||||||
|
import dev.caskeleton.messaging.schema.EncodedMessage;
|
||||||
|
import java.time.Instant;
|
||||||
|
import java.util.Map;
|
||||||
|
import java.util.Optional;
|
||||||
|
import org.apache.kafka.clients.consumer.ConsumerRecord;
|
||||||
|
import org.apache.kafka.common.header.Headers;
|
||||||
|
import org.apache.kafka.common.header.internals.RecordHeaders;
|
||||||
|
import org.apache.kafka.common.record.TimestampType;
|
||||||
|
import org.junit.jupiter.api.DisplayName;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* What an envelope still holds after it has been through Kafka.
|
||||||
|
*
|
||||||
|
* <p>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<EncodedMessage> published =
|
||||||
|
KafkaFixtures.orderCreatedEnvelope()
|
||||||
|
.withHeaders(
|
||||||
|
MessageHeaders.application(
|
||||||
|
Map.of(new HeaderName("x-source-system"), new HeaderValue("erp"))));
|
||||||
|
|
||||||
|
MessageEnvelope<EncodedMessage> delivered = roundTrip(published);
|
||||||
|
|
||||||
|
assertThat(delivered.headers().find("x-source-system"))
|
||||||
|
.map(HeaderValue::value)
|
||||||
|
.as("a header the producer wrote and the consumer cannot read is a header nobody has")
|
||||||
|
.hasValue("erp");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("the tenant survives the trip instead of arriving as no tenant at all")
|
||||||
|
void theTenantSurvivesTheTrip() {
|
||||||
|
MessageEnvelope<EncodedMessage> published =
|
||||||
|
KafkaFixtures.orderCreatedEnvelope()
|
||||||
|
.withTenant(new dev.caskeleton.messaging.api.TenantContext("acme"));
|
||||||
|
|
||||||
|
MessageEnvelope<EncodedMessage> delivered = roundTrip(published);
|
||||||
|
|
||||||
|
assertThat(delivered.tenantContext())
|
||||||
|
.as("a broker record carries no ambient tenant, so an unwritten tenant is an absent one")
|
||||||
|
.contains(new dev.caskeleton.messaging.api.TenantContext("acme"));
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("the retry attempt survives the trip instead of restarting at one")
|
||||||
|
void theRetryAttemptSurvivesTheTrip() {
|
||||||
|
MessageEnvelope<EncodedMessage> retried =
|
||||||
|
retryMapper.stamp(KafkaFixtures.orderCreatedEnvelope(), 3, failure(), FAILED_AT);
|
||||||
|
|
||||||
|
MessageEnvelope<EncodedMessage> delivered = roundTrip(retried);
|
||||||
|
|
||||||
|
assertThat(retryMapper.attemptOf(delivered))
|
||||||
|
.as("an attempt counter that resets on every hop caps nothing")
|
||||||
|
.isEqualTo(3);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("a retry-stamped envelope can be published to its retry topic")
|
||||||
|
void aRetryStampedEnvelopeCanBePublished() {
|
||||||
|
MessageEnvelope<EncodedMessage> retried =
|
||||||
|
retryMapper.stamp(KafkaFixtures.orderCreatedEnvelope(), 2, failure(), FAILED_AT);
|
||||||
|
|
||||||
|
assertThatCode(() -> headerMapper.toKafkaHeaders(retried))
|
||||||
|
.as("the platform's own bookkeeping is not message content forging an identity")
|
||||||
|
.doesNotThrowAnyException();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("a header restating the message id is still refused")
|
||||||
|
void aForgedMessageIdIsStillRefused() {
|
||||||
|
MessageEnvelope<EncodedMessage> forged =
|
||||||
|
KafkaFixtures.orderCreatedEnvelope()
|
||||||
|
.withHeaders(
|
||||||
|
MessageHeaders.platform(
|
||||||
|
Map.of(new HeaderName(ReservedHeaders.MESSAGE_ID), new HeaderValue("forged"))));
|
||||||
|
|
||||||
|
assertThatThrownBy(() -> headerMapper.toKafkaHeaders(forged))
|
||||||
|
.isInstanceOf(MessagingConfigurationException.class);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("identity is read from its field, not duplicated into the header map")
|
||||||
|
void identityIsNotDuplicatedIntoTheHeaderMap() {
|
||||||
|
MessageEnvelope<EncodedMessage> delivered = roundTrip(KafkaFixtures.orderCreatedEnvelope());
|
||||||
|
|
||||||
|
assertThat(delivered.headers().find(ReservedHeaders.MESSAGE_ID))
|
||||||
|
.as("a copy that can drift from the field gives the same message two identities")
|
||||||
|
.isEmpty();
|
||||||
|
assertThat(delivered.messageId()).isNotNull();
|
||||||
|
}
|
||||||
|
|
||||||
|
private MessageEnvelope<EncodedMessage> roundTrip(MessageEnvelope<EncodedMessage> published) {
|
||||||
|
Headers wire = headerMapper.toKafkaHeaders(published);
|
||||||
|
return deliveryMapper.toEnvelope(record(wire, published.payload().bytes()));
|
||||||
|
}
|
||||||
|
|
||||||
|
private static ConsumerRecord<byte[], byte[]> record(Headers wire, byte[] payload) {
|
||||||
|
RecordHeaders headers = new RecordHeaders();
|
||||||
|
wire.forEach(header -> headers.add(header.key(), header.value()));
|
||||||
|
return new ConsumerRecord<>(
|
||||||
|
"order-events",
|
||||||
|
0,
|
||||||
|
7L,
|
||||||
|
FAILED_AT.toEpochMilli(),
|
||||||
|
TimestampType.CREATE_TIME,
|
||||||
|
0,
|
||||||
|
payload.length,
|
||||||
|
null,
|
||||||
|
payload,
|
||||||
|
headers,
|
||||||
|
Optional.empty());
|
||||||
|
}
|
||||||
|
|
||||||
|
private static FailureDescriptor failure() {
|
||||||
|
return new FailureDescriptor(
|
||||||
|
FailureCategory.PROCESSING_TRANSIENT,
|
||||||
|
"HANDLER_FAILED",
|
||||||
|
true,
|
||||||
|
"IllegalStateException",
|
||||||
|
Optional.empty());
|
||||||
|
}
|
||||||
|
}
|
||||||
+1
-1
@@ -41,7 +41,7 @@ class ReservedHeaderForgeryTest {
|
|||||||
assertThatThrownBy(
|
assertThatThrownBy(
|
||||||
() -> mapper.toKafkaHeaders(envelopeWithHeader(ReservedHeaders.MESSAGE_ID, "forged")))
|
() -> mapper.toKafkaHeaders(envelopeWithHeader(ReservedHeaders.MESSAGE_ID, "forged")))
|
||||||
.isInstanceOf(MessagingConfigurationException.class)
|
.isInstanceOf(MessagingConfigurationException.class)
|
||||||
.hasMessageContaining("reserved namespace");
|
.hasMessageContaining("restates a value the envelope already carries");
|
||||||
}
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
|
|||||||
+1
-2
@@ -285,8 +285,7 @@ class NatsAdapterContractTest {
|
|||||||
return new TransportPublishRequest(
|
return new TransportPublishRequest(
|
||||||
destinationProfile(),
|
destinationProfile(),
|
||||||
envelope(64),
|
envelope(64),
|
||||||
new PublishOptions(
|
new PublishOptions(timeout, defaults.confirmation(), defaults.deduplication()));
|
||||||
timeout, defaults.confirmation(), defaults.deduplication(), defaults.brokerHints()));
|
|
||||||
}
|
}
|
||||||
|
|
||||||
private static DestinationProfile destinationProfile() {
|
private static DestinationProfile destinationProfile() {
|
||||||
|
|||||||
@@ -7,22 +7,3 @@ dependencies {
|
|||||||
// naming the type.
|
// naming the type.
|
||||||
api 'io.micrometer:micrometer-core'
|
api 'io.micrometer:micrometer-core'
|
||||||
}
|
}
|
||||||
|
|
||||||
// Wave 0 — a report, not a gate. The secret-scanner characterization lives in this module.
|
|
||||||
tasks.register('wave0Red', Test) {
|
|
||||||
description = 'Reports which Wave 0 baseline characterizations are still red in this module.'
|
|
||||||
group = 'verification'
|
|
||||||
testClassesDirs = sourceSets.test.output.classesDirs
|
|
||||||
classpath = sourceSets.test.runtimeClasspath
|
|
||||||
useJUnitPlatform { includeTags 'wave0-red' }
|
|
||||||
ignoreFailures = true
|
|
||||||
outputs.upToDateWhen { false }
|
|
||||||
reports.junitXml.required = true
|
|
||||||
reports.junitXml.outputLocation = layout.buildDirectory.dir('test-results/wave0Red')
|
|
||||||
}
|
|
||||||
|
|
||||||
tasks.named('test') {
|
|
||||||
// See app-bootstrap: the Wave 0 characterizations are reported by wave0RedReport rather than
|
|
||||||
// failing every build until the wave that closes them lands.
|
|
||||||
useJUnitPlatform { excludeTags 'wave0-red' }
|
|
||||||
}
|
|
||||||
|
|||||||
+78
-3
@@ -1,6 +1,7 @@
|
|||||||
package dev.caskeleton.messaging.outbox;
|
package dev.caskeleton.messaging.outbox;
|
||||||
|
|
||||||
import dev.caskeleton.messaging.api.header.ReservedHeaders;
|
import dev.caskeleton.messaging.api.header.ReservedHeaders;
|
||||||
|
import dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata;
|
||||||
import dev.caskeleton.messaging.reliability.OutboxRecord;
|
import dev.caskeleton.messaging.reliability.OutboxRecord;
|
||||||
import java.util.LinkedHashMap;
|
import java.util.LinkedHashMap;
|
||||||
import java.util.Map;
|
import java.util.Map;
|
||||||
@@ -16,12 +17,29 @@ import java.util.Objects;
|
|||||||
* <p>The platform contract does not change with the transport. The router emits the same reserved
|
* <p>The platform contract does not change with the transport. The router emits the same reserved
|
||||||
* headers the polling relay does, so a consumer cannot tell which one published a message, and
|
* 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.
|
* switching between them is a deployment decision rather than a contract change.
|
||||||
|
*
|
||||||
|
* <p>The message key and the topic are two different questions and used to be answered by one
|
||||||
|
* column. {@code destination} routed the topic <em>and</em> became the key, so every message on a
|
||||||
|
* topic carried the same key, landed on one partition, and made keyed ordering a claim with no
|
||||||
|
* mechanism behind it. The key now comes from {@code routing_key}, the stored column that states
|
||||||
|
* the partition-key-or-message-id fallback once for both relays, and {@code destination} stays what
|
||||||
|
* it always was: routing metadata.
|
||||||
|
*
|
||||||
|
* <p>One canonical field has no header here: the schema subject. There is no reserved header name
|
||||||
|
* for it, and inventing one that only this path wrote would replace a symmetric gap with an
|
||||||
|
* asymmetric one — the polling relay would carry a schema reference on the envelope and the CDC
|
||||||
|
* relay a header no adapter reads. It stays a column that the polling relay resolves, and closing
|
||||||
|
* it means adding the name to {@code ReservedHeaders} and teaching both broker header mappers to
|
||||||
|
* write and read it.
|
||||||
*/
|
*/
|
||||||
public final class DebeziumOutboxEventRouter {
|
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";
|
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. */
|
/** The outbox column carrying the logical message id. */
|
||||||
public static final String ID_COLUMN = "message_id";
|
public static final String ID_COLUMN = "message_id";
|
||||||
|
|
||||||
@@ -39,7 +57,7 @@ public final class DebeziumOutboxEventRouter {
|
|||||||
Map<String, String> configuration = new LinkedHashMap<>();
|
Map<String, String> configuration = new LinkedHashMap<>();
|
||||||
configuration.put("transforms.outbox.type", "io.debezium.transforms.outbox.EventRouter");
|
configuration.put("transforms.outbox.type", "io.debezium.transforms.outbox.EventRouter");
|
||||||
configuration.put("transforms.outbox.table.field.event.id", ID_COLUMN);
|
configuration.put("transforms.outbox.table.field.event.id", ID_COLUMN);
|
||||||
configuration.put("transforms.outbox.table.field.event.key", ROUTE_BY_COLUMN);
|
configuration.put("transforms.outbox.table.field.event.key", KEY_COLUMN);
|
||||||
configuration.put("transforms.outbox.table.field.event.payload", PAYLOAD_COLUMN);
|
configuration.put("transforms.outbox.table.field.event.payload", PAYLOAD_COLUMN);
|
||||||
configuration.put("transforms.outbox.route.by.field", ROUTE_BY_COLUMN);
|
configuration.put("transforms.outbox.route.by.field", ROUTE_BY_COLUMN);
|
||||||
configuration.put(
|
configuration.put(
|
||||||
@@ -51,7 +69,18 @@ public final class DebeziumOutboxEventRouter {
|
|||||||
"message_type:header:" + ReservedHeaders.MESSAGE_TYPE,
|
"message_type:header:" + ReservedHeaders.MESSAGE_TYPE,
|
||||||
"schema_version:header:" + ReservedHeaders.SCHEMA_VERSION,
|
"schema_version:header:" + ReservedHeaders.SCHEMA_VERSION,
|
||||||
"content_type:header:" + ReservedHeaders.CONTENT_TYPE,
|
"content_type:header:" + ReservedHeaders.CONTENT_TYPE,
|
||||||
"created_at:header:" + ReservedHeaders.PRODUCED_AT));
|
"created_at:header:" + ReservedHeaders.PRODUCED_AT,
|
||||||
|
"destination:header:" + ReservedHeaders.ORIGIN_DESTINATION,
|
||||||
|
"producer:header:" + ReservedHeaders.PRODUCER,
|
||||||
|
"occurred_at:header:" + ReservedHeaders.OCCURRED_AT,
|
||||||
|
"correlation_id:header:" + ReservedHeaders.CORRELATION_ID,
|
||||||
|
"causation_id:header:" + ReservedHeaders.CAUSATION_ID,
|
||||||
|
"tenant:header:" + ReservedHeaders.TENANT,
|
||||||
|
"partition_key:header:" + ReservedHeaders.PARTITION_KEY,
|
||||||
|
"ordering_key:header:" + ReservedHeaders.ORDERING_KEY,
|
||||||
|
"traceparent:header:" + ReservedHeaders.TRACEPARENT,
|
||||||
|
"tracestate:header:" + ReservedHeaders.TRACESTATE,
|
||||||
|
"baggage:header:" + ReservedHeaders.BAGGAGE));
|
||||||
return Map.copyOf(configuration);
|
return Map.copyOf(configuration);
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -71,6 +100,52 @@ public final class DebeziumOutboxEventRouter {
|
|||||||
headers.put(ReservedHeaders.SCHEMA_VERSION, Integer.toString(record.schemaVersion().value()));
|
headers.put(ReservedHeaders.SCHEMA_VERSION, Integer.toString(record.schemaVersion().value()));
|
||||||
headers.put(ReservedHeaders.CONTENT_TYPE, record.contentType().value());
|
headers.put(ReservedHeaders.CONTENT_TYPE, record.contentType().value());
|
||||||
headers.put(ReservedHeaders.PRODUCED_AT, record.createdAt().toString());
|
headers.put(ReservedHeaders.PRODUCED_AT, record.createdAt().toString());
|
||||||
|
headers.put(ReservedHeaders.ORIGIN_DESTINATION, record.destination().value());
|
||||||
|
|
||||||
|
// Absent stays absent. Writing an empty string for a column the row does not have would make a
|
||||||
|
// message that carries no tenant indistinguishable from one whose tenant is the empty string,
|
||||||
|
// and the consumer would have to know which of the two this platform meant.
|
||||||
|
OutboxCanonicalMetadata metadata = record.metadata();
|
||||||
|
metadata.producer().ifPresent(value -> headers.put(ReservedHeaders.PRODUCER, value.value()));
|
||||||
|
metadata
|
||||||
|
.occurredAt()
|
||||||
|
.ifPresent(value -> headers.put(ReservedHeaders.OCCURRED_AT, value.toString()));
|
||||||
|
metadata
|
||||||
|
.correlationId()
|
||||||
|
.ifPresent(value -> headers.put(ReservedHeaders.CORRELATION_ID, value.value()));
|
||||||
|
metadata
|
||||||
|
.causationId()
|
||||||
|
.ifPresent(
|
||||||
|
value -> headers.put(ReservedHeaders.CAUSATION_ID, value.value().value().toString()));
|
||||||
|
metadata.tenant().ifPresent(value -> headers.put(ReservedHeaders.TENANT, value.tenantId()));
|
||||||
|
metadata.partitionKey().ifPresent(value -> headers.put(ReservedHeaders.PARTITION_KEY, value));
|
||||||
|
metadata.orderingKey().ifPresent(value -> headers.put(ReservedHeaders.ORDERING_KEY, value));
|
||||||
|
metadata
|
||||||
|
.traceContext()
|
||||||
|
.traceparent()
|
||||||
|
.ifPresent(value -> headers.put(ReservedHeaders.TRACEPARENT, value));
|
||||||
|
metadata
|
||||||
|
.traceContext()
|
||||||
|
.tracestate()
|
||||||
|
.ifPresent(value -> headers.put(ReservedHeaders.TRACESTATE, value));
|
||||||
|
metadata
|
||||||
|
.traceContext()
|
||||||
|
.baggage()
|
||||||
|
.ifPresent(value -> headers.put(ReservedHeaders.BAGGAGE, value));
|
||||||
return Map.copyOf(headers);
|
return Map.copyOf(headers);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Returns the key a routed record carries.
|
||||||
|
*
|
||||||
|
* <p>The same value the {@code routing_key} column computes, stated here so a test can compare
|
||||||
|
* the two rather than trusting that the SQL and the Java agree.
|
||||||
|
*
|
||||||
|
* @param record the outbox row
|
||||||
|
* @return the broker message key
|
||||||
|
*/
|
||||||
|
public String routingKey(OutboxRecord record) {
|
||||||
|
Objects.requireNonNull(record, "record must not be null");
|
||||||
|
return record.metadata().partitionKey().orElseGet(() -> record.messageId().value().toString());
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+19
-11
@@ -19,11 +19,17 @@ import java.util.Optional;
|
|||||||
* <p>The message id comes from the row's {@code message_id} column, never from Debezium's own event
|
* <p>The message id comes from the row's {@code message_id} column, never from Debezium's own event
|
||||||
* id. Debezium mints a fresh event id per change record, so using it would break identity across a
|
* 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.
|
* CDC re-snapshot — exactly the scenario where identity matters most.
|
||||||
|
*
|
||||||
|
* <p>The reserved headers come from {@link DebeziumOutboxEventRouter} rather than being rebuilt
|
||||||
|
* here. Two lists of the same headers is how the connector's configuration and the expectation this
|
||||||
|
* class encodes come to disagree, and the disagreement would be invisible: the test compares this
|
||||||
|
* output against the polling relay's, so it would pass while the connector emitted something else.
|
||||||
*/
|
*/
|
||||||
public final class DebeziumOutboxRecordMapper {
|
public final class DebeziumOutboxRecordMapper {
|
||||||
|
|
||||||
private final String topicPrefix;
|
private final String topicPrefix;
|
||||||
private final boolean aggregateIdAsPartitionKey;
|
private final boolean aggregateIdAsPartitionKey;
|
||||||
|
private final DebeziumOutboxEventRouter router = new DebeziumOutboxEventRouter();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Creates a mapper from a CDC profile.
|
* Creates a mapper from a CDC profile.
|
||||||
@@ -45,27 +51,29 @@ public final class DebeziumOutboxRecordMapper {
|
|||||||
public DebeziumMappedRecord map(OutboxRecord record) {
|
public DebeziumMappedRecord map(OutboxRecord record) {
|
||||||
Objects.requireNonNull(record, "record must not be null");
|
Objects.requireNonNull(record, "record must not be null");
|
||||||
|
|
||||||
|
// Application headers first, canonical headers second, and the canonical ones win. The row's
|
||||||
|
// header map is application data; a row that wrote `msg.id` into it would otherwise overwrite
|
||||||
|
// the identity the platform put there, and the consumer trusts the last such header it sees.
|
||||||
|
// The write path refuses reserved names outright — this order is the second lock on the same
|
||||||
|
// door, because a CDC connector reading the table directly never passes through that check.
|
||||||
Map<String, String> headers = new LinkedHashMap<>(record.headers());
|
Map<String, String> headers = new LinkedHashMap<>(record.headers());
|
||||||
headers.put(ReservedHeaders.MESSAGE_ID, record.messageId().value().toString());
|
headers.keySet().removeIf(ReservedHeaders::isReserved);
|
||||||
headers.put(ReservedHeaders.MESSAGE_TYPE, record.messageType().value());
|
headers.putAll(router.reservedHeaders(record));
|
||||||
headers.put(ReservedHeaders.SCHEMA_VERSION, Integer.toString(record.schemaVersion().value()));
|
|
||||||
headers.put(ReservedHeaders.CONTENT_TYPE, record.contentType().value());
|
|
||||||
headers.put(ReservedHeaders.PRODUCED_AT, record.createdAt().toString());
|
|
||||||
|
|
||||||
return new DebeziumMappedRecord(
|
return new DebeziumMappedRecord(
|
||||||
topicPrefix + record.destination().value(),
|
topicPrefix + record.destination().value(),
|
||||||
partitionKey(record, headers),
|
partitionKey(record),
|
||||||
record.payload(),
|
record.payload(),
|
||||||
headers);
|
headers);
|
||||||
}
|
}
|
||||||
|
|
||||||
private Optional<String> partitionKey(OutboxRecord record, Map<String, String> headers) {
|
private Optional<String> partitionKey(OutboxRecord record) {
|
||||||
if (!aggregateIdAsPartitionKey) {
|
if (!aggregateIdAsPartitionKey) {
|
||||||
return Optional.empty();
|
return Optional.empty();
|
||||||
}
|
}
|
||||||
// The partition key header is the one the polling relay would also have set, so both relays
|
// The same value the polling relay would use and the same value the `routing_key` column
|
||||||
// land the same message on the same partition and neither reorders a keyed stream.
|
// computes, so both relays land the same message on the same partition and neither reorders a
|
||||||
return Optional.ofNullable(headers.get(ReservedHeaders.PARTITION_KEY))
|
// keyed stream.
|
||||||
.or(() -> Optional.of(record.messageId().value().toString()));
|
return Optional.of(router.routingKey(record));
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+81
-7
@@ -1,11 +1,17 @@
|
|||||||
package dev.caskeleton.messaging.outbox;
|
package dev.caskeleton.messaging.outbox;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.api.CausationId;
|
||||||
import dev.caskeleton.messaging.api.ContentType;
|
import dev.caskeleton.messaging.api.ContentType;
|
||||||
|
import dev.caskeleton.messaging.api.CorrelationId;
|
||||||
import dev.caskeleton.messaging.api.MessageId;
|
import dev.caskeleton.messaging.api.MessageId;
|
||||||
import dev.caskeleton.messaging.api.MessageType;
|
import dev.caskeleton.messaging.api.MessageType;
|
||||||
|
import dev.caskeleton.messaging.api.ProducerId;
|
||||||
import dev.caskeleton.messaging.api.SchemaVersion;
|
import dev.caskeleton.messaging.api.SchemaVersion;
|
||||||
|
import dev.caskeleton.messaging.api.TenantContext;
|
||||||
|
import dev.caskeleton.messaging.api.TraceContext;
|
||||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||||
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
|
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
|
||||||
|
import dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata;
|
||||||
import dev.caskeleton.messaging.reliability.OutboxLease;
|
import dev.caskeleton.messaging.reliability.OutboxLease;
|
||||||
import dev.caskeleton.messaging.reliability.OutboxRecord;
|
import dev.caskeleton.messaging.reliability.OutboxRecord;
|
||||||
import dev.caskeleton.messaging.reliability.OutboxRepository;
|
import dev.caskeleton.messaging.reliability.OutboxRepository;
|
||||||
@@ -45,10 +51,32 @@ public final class JdbcOutboxRepository implements OutboxRepository {
|
|||||||
"""
|
"""
|
||||||
INSERT INTO messaging_outbox (
|
INSERT INTO messaging_outbox (
|
||||||
message_id, destination, message_type, schema_version, content_type,
|
message_id, destination, message_type, schema_version, content_type,
|
||||||
payload, headers, created_at, status, attempts)
|
payload, headers, created_at, status, attempts,
|
||||||
VALUES (?, ?, ?, ?, ?, ?, ?::jsonb, ?, ?, ?)
|
producer, occurred_at, correlation_id, causation_id, tenant,
|
||||||
|
partition_key, ordering_key, schema_subject, schema_uri,
|
||||||
|
traceparent, tracestate, baggage)
|
||||||
|
VALUES (?, ?, ?, ?, ?, ?, ?::jsonb, ?, ?, ?,
|
||||||
|
?, ?, ?, ?, ?,
|
||||||
|
?, ?, ?, ?,
|
||||||
|
?, ?, ?)
|
||||||
""";
|
""";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The columns every read of a row selects.
|
||||||
|
*
|
||||||
|
* <p>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 =
|
private static final String LEASE =
|
||||||
"""
|
"""
|
||||||
WITH claimable AS (
|
WITH claimable AS (
|
||||||
@@ -69,7 +97,10 @@ public final class JdbcOutboxRepository implements OutboxRepository {
|
|||||||
WHERE o.message_id = c.message_id
|
WHERE o.message_id = c.message_id
|
||||||
RETURNING o.message_id, o.destination, o.message_type, o.schema_version, o.content_type,
|
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.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
|
WHERE o.message_id = c.message_id
|
||||||
RETURNING o.message_id, o.destination, o.message_type, o.schema_version, o.content_type,
|
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.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;
|
private final DataSource dataSource;
|
||||||
@@ -144,6 +178,20 @@ public final class JdbcOutboxRepository implements OutboxRepository {
|
|||||||
statement.setTimestamp(8, Timestamp.from(record.createdAt()));
|
statement.setTimestamp(8, Timestamp.from(record.createdAt()));
|
||||||
statement.setString(9, record.status().name());
|
statement.setString(9, record.status().name());
|
||||||
statement.setInt(10, record.attempts());
|
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();
|
statement.executeUpdate();
|
||||||
} catch (SQLException exception) {
|
} catch (SQLException exception) {
|
||||||
throw new MessagingConfigurationException(
|
throw new MessagingConfigurationException(
|
||||||
@@ -425,9 +473,7 @@ public final class JdbcOutboxRepository implements OutboxRepository {
|
|||||||
connection -> {
|
connection -> {
|
||||||
try (PreparedStatement statement =
|
try (PreparedStatement statement =
|
||||||
connection.prepareStatement(
|
connection.prepareStatement(
|
||||||
"SELECT message_id, destination, message_type, schema_version, content_type, "
|
"SELECT " + COLUMNS + " FROM messaging_outbox WHERE message_id = ?")) {
|
||||||
+ "payload, headers, created_at, status, attempts, lease_expires_at, "
|
|
||||||
+ "last_failure_code FROM messaging_outbox WHERE message_id = ?")) {
|
|
||||||
statement.setObject(1, messageId.value());
|
statement.setObject(1, messageId.value());
|
||||||
try (ResultSet results = statement.executeQuery()) {
|
try (ResultSet results = statement.executeQuery()) {
|
||||||
return results.next() ? Optional.of(read(results)) : Optional.<OutboxRecord>empty();
|
return results.next() ? Optional.of(read(results)) : Optional.<OutboxRecord>empty();
|
||||||
@@ -509,6 +555,7 @@ public final class JdbcOutboxRepository implements OutboxRepository {
|
|||||||
new ContentType(results.getString("content_type")),
|
new ContentType(results.getString("content_type")),
|
||||||
results.getBytes("payload"),
|
results.getBytes("payload"),
|
||||||
fromJson(results.getString("headers")),
|
fromJson(results.getString("headers")),
|
||||||
|
readMetadata(results),
|
||||||
results.getTimestamp("created_at").toInstant(),
|
results.getTimestamp("created_at").toInstant(),
|
||||||
OutboxStatus.valueOf(results.getString("status")),
|
OutboxStatus.valueOf(results.getString("status")),
|
||||||
results.getInt("attempts"),
|
results.getInt("attempts"),
|
||||||
@@ -516,6 +563,33 @@ public final class JdbcOutboxRepository implements OutboxRepository {
|
|||||||
Optional.ofNullable(results.getString("last_failure_code")));
|
Optional.ofNullable(results.getString("last_failure_code")));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Rebuilds the canonical metadata from the row's own columns.
|
||||||
|
*
|
||||||
|
* <p>Absent columns stay absent. A row written before the columns existed rebuilds with empty
|
||||||
|
* metadata, which is the same thing a row written by a producer that had none rebuilds with — and
|
||||||
|
* the reader's behaviour has to be identical in both cases, because guessing a tenant or a
|
||||||
|
* correlation is worse than carrying none.
|
||||||
|
*/
|
||||||
|
private static OutboxCanonicalMetadata readMetadata(ResultSet results) throws SQLException {
|
||||||
|
Timestamp occurredAt = results.getTimestamp("occurred_at");
|
||||||
|
java.util.UUID causation = results.getObject("causation_id", java.util.UUID.class);
|
||||||
|
return new OutboxCanonicalMetadata(
|
||||||
|
Optional.ofNullable(results.getString("producer")).map(ProducerId::new),
|
||||||
|
Optional.ofNullable(occurredAt).map(Timestamp::toInstant),
|
||||||
|
Optional.ofNullable(results.getString("correlation_id")).map(CorrelationId::new),
|
||||||
|
Optional.ofNullable(causation).map(value -> new CausationId(new MessageId(value))),
|
||||||
|
Optional.ofNullable(results.getString("tenant")).map(TenantContext::new),
|
||||||
|
Optional.ofNullable(results.getString("partition_key")),
|
||||||
|
Optional.ofNullable(results.getString("ordering_key")),
|
||||||
|
Optional.ofNullable(results.getString("schema_subject")),
|
||||||
|
Optional.ofNullable(results.getString("schema_uri")),
|
||||||
|
new TraceContext(
|
||||||
|
Optional.ofNullable(results.getString("traceparent")),
|
||||||
|
Optional.ofNullable(results.getString("tracestate")),
|
||||||
|
Optional.ofNullable(results.getString("baggage"))));
|
||||||
|
}
|
||||||
|
|
||||||
private <T> T withConnection(ConnectionCallback<T> callback) {
|
private <T> T withConnection(ConnectionCallback<T> callback) {
|
||||||
try (Connection connection = dataSource.getConnection()) {
|
try (Connection connection = dataSource.getConnection()) {
|
||||||
return callback.apply(connection);
|
return callback.apply(connection);
|
||||||
|
|||||||
+54
-21
@@ -2,13 +2,16 @@ package dev.caskeleton.messaging.outbox;
|
|||||||
|
|
||||||
import dev.caskeleton.messaging.api.MessageEnvelope;
|
import dev.caskeleton.messaging.api.MessageEnvelope;
|
||||||
import dev.caskeleton.messaging.api.ProducerId;
|
import dev.caskeleton.messaging.api.ProducerId;
|
||||||
import dev.caskeleton.messaging.api.TraceContext;
|
import dev.caskeleton.messaging.api.SchemaVersion;
|
||||||
import dev.caskeleton.messaging.api.header.HeaderName;
|
import dev.caskeleton.messaging.api.header.HeaderName;
|
||||||
import dev.caskeleton.messaging.api.header.HeaderValue;
|
import dev.caskeleton.messaging.api.header.HeaderValue;
|
||||||
import dev.caskeleton.messaging.api.header.MessageHeaders;
|
import dev.caskeleton.messaging.api.header.MessageHeaders;
|
||||||
import dev.caskeleton.messaging.api.header.ReservedHeaders;
|
import dev.caskeleton.messaging.api.header.ReservedHeaders;
|
||||||
|
import dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata;
|
||||||
import dev.caskeleton.messaging.reliability.OutboxRecord;
|
import dev.caskeleton.messaging.reliability.OutboxRecord;
|
||||||
import dev.caskeleton.messaging.schema.EncodedMessage;
|
import dev.caskeleton.messaging.schema.EncodedMessage;
|
||||||
|
import dev.caskeleton.messaging.schema.SchemaReference;
|
||||||
|
import java.net.URI;
|
||||||
import java.util.LinkedHashMap;
|
import java.util.LinkedHashMap;
|
||||||
import java.util.Map;
|
import java.util.Map;
|
||||||
import java.util.Objects;
|
import java.util.Objects;
|
||||||
@@ -20,6 +23,18 @@ import java.util.Optional;
|
|||||||
* <p>The identity comes from the row, never from a fresh mint. That is what makes a retry after an
|
* <p>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
|
* ambiguous publish safe: the broker's deduplication, or the consumer's Inbox, sees the same id and
|
||||||
* collapses the duplicate.
|
* collapses the duplicate.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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 {
|
public final class OutboxEnvelopeFactory {
|
||||||
|
|
||||||
@@ -28,7 +43,7 @@ public final class OutboxEnvelopeFactory {
|
|||||||
/**
|
/**
|
||||||
* Creates a factory for one service.
|
* 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) {
|
public OutboxEnvelopeFactory(ProducerId producer) {
|
||||||
this.producer = Objects.requireNonNull(producer, "producer must not be null");
|
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
|
// 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,
|
// 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.
|
// so a forged identity lands in another message's inbox deduplication.
|
||||||
//
|
if (ReservedHeaders.isReserved(name)) {
|
||||||
// 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)) {
|
|
||||||
throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException(
|
throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException(
|
||||||
"RESERVED_HEADER_IN_OUTBOX_ROW",
|
"RESERVED_HEADER_IN_OUTBOX_ROW",
|
||||||
"outbox row header '"
|
"outbox row header '"
|
||||||
@@ -66,26 +75,50 @@ public final class OutboxEnvelopeFactory {
|
|||||||
+ "' uses the reserved namespace; canonical identity and metadata come from"
|
+ "' uses the reserved namespace; canonical identity and metadata come from"
|
||||||
+ " the record's own columns, not from its header map");
|
+ " 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<>(
|
return new MessageEnvelope<>(
|
||||||
record.messageId(),
|
record.messageId(),
|
||||||
record.messageType(),
|
record.messageType(),
|
||||||
record.schemaVersion(),
|
record.schemaVersion(),
|
||||||
record.createdAt(),
|
record.createdAt(),
|
||||||
Optional.of(record.createdAt()),
|
// The write instant stands in when the row records no separate occurrence. It is the
|
||||||
producer,
|
// closest true statement available: the business transaction that wrote the row is the one
|
||||||
Optional.empty(),
|
// the fact occurred in.
|
||||||
Optional.empty(),
|
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(),
|
record.contentType(),
|
||||||
Optional.ofNullable(record.headers().get(ReservedHeaders.PARTITION_KEY)),
|
metadata.partitionKey(),
|
||||||
Optional.ofNullable(record.headers().get(ReservedHeaders.ORDERING_KEY)),
|
metadata.orderingKey(),
|
||||||
Optional.empty(),
|
metadata.tenant(),
|
||||||
TraceContext.none(),
|
metadata.traceContext(),
|
||||||
MessageHeaders.platform(headers),
|
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.
|
||||||
|
*
|
||||||
|
* <p>The version is the row's {@code schema_version} column rather than a third copy of the same
|
||||||
|
* number: a reference whose version could disagree with the column the relay filters on is a
|
||||||
|
* reference nobody can trust.
|
||||||
|
*/
|
||||||
|
private static Optional<SchemaReference> schemaReference(
|
||||||
|
OutboxRecord record, OutboxCanonicalMetadata metadata) {
|
||||||
|
return metadata
|
||||||
|
.schemaSubject()
|
||||||
|
.map(
|
||||||
|
subject ->
|
||||||
|
new SchemaReference(
|
||||||
|
subject,
|
||||||
|
new SchemaVersion(record.schemaVersion().value()),
|
||||||
|
metadata.schemaUri().map(URI::create)));
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+51
-5
@@ -87,6 +87,33 @@ public final class OutboxRelay {
|
|||||||
OutboxRetryScheduler.standard());
|
OutboxRetryScheduler.standard());
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* A relay with an explicit retry policy and a process-derived owner.
|
||||||
|
*
|
||||||
|
* @param repository the outbox storage
|
||||||
|
* @param publisher the platform publisher
|
||||||
|
* @param envelopeFactory rebuilds envelopes from rows
|
||||||
|
* @param batchSize how many rows to claim per pass
|
||||||
|
* @param leaseDuration how long a claim holds
|
||||||
|
* @param scheduler the retry policy
|
||||||
|
*/
|
||||||
|
public OutboxRelay(
|
||||||
|
OutboxRepository repository,
|
||||||
|
MessagePublisher publisher,
|
||||||
|
OutboxEnvelopeFactory envelopeFactory,
|
||||||
|
int batchSize,
|
||||||
|
Duration leaseDuration,
|
||||||
|
OutboxRetryScheduler scheduler) {
|
||||||
|
this(
|
||||||
|
repository,
|
||||||
|
publisher,
|
||||||
|
envelopeFactory,
|
||||||
|
batchSize,
|
||||||
|
leaseDuration,
|
||||||
|
defaultOwner(),
|
||||||
|
scheduler);
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* A relay with an explicit retry policy.
|
* A relay with an explicit retry policy.
|
||||||
*
|
*
|
||||||
@@ -134,6 +161,7 @@ public final class OutboxRelay {
|
|||||||
int ambiguous = 0;
|
int ambiguous = 0;
|
||||||
int failed = 0;
|
int failed = 0;
|
||||||
int stale = 0;
|
int stale = 0;
|
||||||
|
int exhausted = 0;
|
||||||
|
|
||||||
for (OutboxLease lease : batch) {
|
for (OutboxLease lease : batch) {
|
||||||
OutboxRecord record = lease.record();
|
OutboxRecord record = lease.record();
|
||||||
@@ -147,10 +175,28 @@ public final class OutboxRelay {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
case AMBIGUOUS -> {
|
case AMBIGUOUS -> {
|
||||||
if (repository.markAmbiguous(
|
String code = result.failure().map(failure -> failure.code()).orElse("AMBIGUOUS");
|
||||||
lease, result.failure().map(failure -> failure.code()).orElse("AMBIGUOUS"), now)
|
// The attempt this pass just spent. The claim predicate and the row both count attempts
|
||||||
== OutboxTransitionResult.APPLIED) {
|
// after the transition, so the budget has to be judged on the same number the next claim
|
||||||
ambiguous++;
|
// will read, or the last attempt is spent twice.
|
||||||
|
int spent = record.attempts() + 1;
|
||||||
|
OutboxTransitionResult transition =
|
||||||
|
scheduler
|
||||||
|
.parkReason(spent)
|
||||||
|
// A row that has spent its budget without an answer is parked under its own
|
||||||
|
// status. Leaving it AMBIGUOUS makes it a row the claim predicate silently skips
|
||||||
|
// forever, which looks identical to a healthy backlog on every dashboard.
|
||||||
|
.map(reason -> repository.markExhausted(lease, reason, now))
|
||||||
|
.orElseGet(
|
||||||
|
() ->
|
||||||
|
repository.markAmbiguous(
|
||||||
|
lease, code, now, scheduler.nextAttemptAt(now, spent)));
|
||||||
|
if (transition == OutboxTransitionResult.APPLIED) {
|
||||||
|
if (scheduler.isExhausted(spent)) {
|
||||||
|
exhausted++;
|
||||||
|
} else {
|
||||||
|
ambiguous++;
|
||||||
|
}
|
||||||
} else {
|
} else {
|
||||||
stale++;
|
stale++;
|
||||||
}
|
}
|
||||||
@@ -171,7 +217,7 @@ public final class OutboxRelay {
|
|||||||
throw new IllegalStateException("unhandled publish completion: " + result.completion());
|
throw new IllegalStateException("unhandled publish completion: " + result.completion());
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
return new OutboxRelayReport(batch.size(), published, ambiguous, failed, stale);
|
return new OutboxRelayReport(batch.size(), published, ambiguous, failed, stale, exhausted);
|
||||||
}
|
}
|
||||||
|
|
||||||
private PublishResult publish(OutboxRecord record) {
|
private PublishResult publish(OutboxRecord record) {
|
||||||
|
|||||||
+19
-3
@@ -12,23 +12,39 @@ package dev.caskeleton.messaging.outbox;
|
|||||||
* published something whose outcome another worker has already recorded, so a non-zero value is the
|
* published something whose outcome another worker has already recorded, so a non-zero value is the
|
||||||
* visible form of a duplicate publication.
|
* visible form of a duplicate publication.
|
||||||
*
|
*
|
||||||
|
* <p>{@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 leased how many rows were claimed
|
||||||
* @param published how many were confirmed
|
* @param published how many were confirmed
|
||||||
* @param ambiguous how many had an unknown outcome and stay retryable
|
* @param ambiguous how many had an unknown outcome and stay retryable
|
||||||
* @param failed how many were definitively rejected
|
* @param failed how many were definitively rejected
|
||||||
* @param staleLeases how many terminal writes were refused because the lease had been superseded
|
* @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(
|
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 {
|
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");
|
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. */
|
/** A report from a pass that observed no stale leases. */
|
||||||
public OutboxRelayReport(int leased, int published, int ambiguous, int failed) {
|
public OutboxRelayReport(int leased, int published, int ambiguous, int failed) {
|
||||||
this(leased, published, ambiguous, failed, 0);
|
this(leased, published, ambiguous, failed, 0, 0);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+199
@@ -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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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<Instant> clock;
|
||||||
|
|
||||||
|
private final ScheduledExecutorService passes;
|
||||||
|
|
||||||
|
private final AtomicBoolean running = new AtomicBoolean();
|
||||||
|
|
||||||
|
private final AtomicInteger unproductivePasses = new AtomicInteger();
|
||||||
|
|
||||||
|
private final AtomicLong completedPasses = new AtomicLong();
|
||||||
|
|
||||||
|
private final AtomicLong failedPasses = new AtomicLong();
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Creates a worker driving one relay.
|
||||||
|
*
|
||||||
|
* @param relay the relay to run
|
||||||
|
* @param scheduler the policy deciding when the next pass runs
|
||||||
|
*/
|
||||||
|
public OutboxRelayWorker(OutboxRelay relay, OutboxRetryScheduler scheduler) {
|
||||||
|
this(relay, scheduler, Instant::now);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Creates a worker with an explicit clock, so a pass can be driven without waiting on wall time.
|
||||||
|
*
|
||||||
|
* @param relay the relay to run
|
||||||
|
* @param scheduler the policy deciding when the next pass runs
|
||||||
|
* @param clock the source of the current instant
|
||||||
|
*/
|
||||||
|
public OutboxRelayWorker(
|
||||||
|
OutboxRelay relay, OutboxRetryScheduler scheduler, Supplier<Instant> clock) {
|
||||||
|
this.relay = Objects.requireNonNull(relay, "relay must not be null");
|
||||||
|
this.scheduler = Objects.requireNonNull(scheduler, "scheduler must not be null");
|
||||||
|
this.clock = Objects.requireNonNull(clock, "clock must not be null");
|
||||||
|
ScheduledThreadPoolExecutor executor =
|
||||||
|
new ScheduledThreadPoolExecutor(
|
||||||
|
1,
|
||||||
|
runnable -> {
|
||||||
|
// Daemon: a relay thread that outlives the application would keep publishing from a
|
||||||
|
// process that has already released its other resources.
|
||||||
|
Thread thread = new Thread(runnable, "messaging-outbox-relay");
|
||||||
|
thread.setDaemon(true);
|
||||||
|
return thread;
|
||||||
|
});
|
||||||
|
// A pass waiting out its backoff is dropped on shutdown rather than run afterwards. Left on,
|
||||||
|
// the default policy makes stop() wait for a pass that has not started and cannot do anything
|
||||||
|
// useful, so an orderly shutdown pays the whole poll interval before it can close.
|
||||||
|
executor.setExecuteExistingDelayedTasksAfterShutdownPolicy(false);
|
||||||
|
this.passes = executor;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Starts driving passes. Idempotent: a second call does not add a second schedule. */
|
||||||
|
public void start() {
|
||||||
|
if (running.compareAndSet(false, true)) {
|
||||||
|
schedule(Duration.ZERO);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Stops scheduling and lets the pass that is already running finish.
|
||||||
|
*
|
||||||
|
* <p>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;
|
||||||
|
}
|
||||||
|
}
|
||||||
+25
-4
@@ -8,10 +8,12 @@ import java.util.Optional;
|
|||||||
/**
|
/**
|
||||||
* Decides when a relay's next pass should run, and when a record has retried enough.
|
* Decides when a relay's next pass should run, and when a record has retried enough.
|
||||||
*
|
*
|
||||||
* <p>The backoff is on the <em>relay</em>, not on the individual record. A broker outage fails
|
* <p>The same curve serves two different jobs and neither replaces the other. Backing off the
|
||||||
* every record in the batch for the same reason, so backing off per record would hammer the broker
|
* <em>pass</em> is what lets a broker recover: an outage fails every record in the batch for the
|
||||||
* with the whole backlog on a schedule while achieving nothing; backing off the pass lets the
|
* same reason, so retrying the whole backlog on the poll interval achieves nothing but load. But a
|
||||||
* broker recover.
|
* 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.
|
||||||
*
|
*
|
||||||
* <p>Jitter is applied deterministically from the attempt count rather than randomly. Several relay
|
* <p>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
|
* 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));
|
return now.plus(backoff(consecutiveEmptyOrFailedPasses));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Returns when a row that has spent this many attempts may be claimed again.
|
||||||
|
*
|
||||||
|
* <p>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. */
|
/** The platform's default policy, for a relay whose caller did not supply one. */
|
||||||
public static OutboxRetryScheduler standard() {
|
public static OutboxRetryScheduler standard() {
|
||||||
return new OutboxRetryScheduler(OutboxProperties.defaults(), java.time.Duration.ofMinutes(5));
|
return new OutboxRetryScheduler(OutboxProperties.defaults(), java.time.Duration.ofMinutes(5));
|
||||||
|
|||||||
+66
@@ -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;
|
||||||
+66
-1
@@ -12,6 +12,7 @@ import dev.caskeleton.messaging.api.destination.DestinationName;
|
|||||||
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
|
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
|
||||||
import dev.caskeleton.messaging.api.header.ReservedHeaders;
|
import dev.caskeleton.messaging.api.header.ReservedHeaders;
|
||||||
import dev.caskeleton.messaging.outbox.DebeziumOutboxProfile.RelayMode;
|
import dev.caskeleton.messaging.outbox.DebeziumOutboxProfile.RelayMode;
|
||||||
|
import dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata;
|
||||||
import dev.caskeleton.messaging.reliability.OutboxRecord;
|
import dev.caskeleton.messaging.reliability.OutboxRecord;
|
||||||
import dev.caskeleton.messaging.reliability.OutboxStatus;
|
import dev.caskeleton.messaging.reliability.OutboxStatus;
|
||||||
import java.nio.charset.StandardCharsets;
|
import java.nio.charset.StandardCharsets;
|
||||||
@@ -26,6 +27,11 @@ class DebeziumOutboxRecordMapperTest {
|
|||||||
private static final MessageId MESSAGE_ID = MessageId.newId();
|
private static final MessageId MESSAGE_ID = MessageId.newId();
|
||||||
|
|
||||||
private static OutboxRecord record(Map<String, String> headers) {
|
private static OutboxRecord record(Map<String, String> headers) {
|
||||||
|
return record(headers, OutboxCanonicalMetadata.none());
|
||||||
|
}
|
||||||
|
|
||||||
|
private static OutboxRecord record(
|
||||||
|
Map<String, String> headers, OutboxCanonicalMetadata metadata) {
|
||||||
return new OutboxRecord(
|
return new OutboxRecord(
|
||||||
MESSAGE_ID,
|
MESSAGE_ID,
|
||||||
new DestinationName("orders.v1"),
|
new DestinationName("orders.v1"),
|
||||||
@@ -34,6 +40,7 @@ class DebeziumOutboxRecordMapperTest {
|
|||||||
ContentType.JSON,
|
ContentType.JSON,
|
||||||
"{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8),
|
"{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8),
|
||||||
headers,
|
headers,
|
||||||
|
metadata,
|
||||||
NOW,
|
NOW,
|
||||||
OutboxStatus.PENDING,
|
OutboxStatus.PENDING,
|
||||||
0,
|
0,
|
||||||
@@ -89,13 +96,71 @@ class DebeziumOutboxRecordMapperTest {
|
|||||||
@Test
|
@Test
|
||||||
void aKeyedProfileUsesTheSamePartitionKeyThePollingRelayWouldHave() {
|
void aKeyedProfileUsesTheSamePartitionKeyThePollingRelayWouldHave() {
|
||||||
DebeziumMappedRecord mapped =
|
DebeziumMappedRecord mapped =
|
||||||
mapper(true).map(record(Map.of(ReservedHeaders.PARTITION_KEY, "customer-42")));
|
mapper(true)
|
||||||
|
.map(
|
||||||
|
record(
|
||||||
|
Map.of(),
|
||||||
|
OutboxCanonicalMetadata.none().withRoutingKeys("customer-42", "customer-42")));
|
||||||
|
|
||||||
assertThat(mapped.key())
|
assertThat(mapped.key())
|
||||||
.as("a different key would send the two relays' messages to different partitions")
|
.as("a different key would send the two relays' messages to different partitions")
|
||||||
.hasValue("customer-42");
|
.hasValue("customer-42");
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aKeyedProfileFallsBackToTheMessageIdWhenTheRowHasNoPartitionKey() {
|
||||||
|
assertThat(mapper(true).map(record(Map.of())).key())
|
||||||
|
.as("the fallback the routing_key column computes, stated in one place for both relays")
|
||||||
|
.hasValue(MESSAGE_ID.value().toString());
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void theCanonicalColumnsBecomeReservedHeaders() {
|
||||||
|
OutboxCanonicalMetadata metadata =
|
||||||
|
OutboxCanonicalMetadata.none()
|
||||||
|
.withProducer(new dev.caskeleton.messaging.api.ProducerId("order-api"))
|
||||||
|
.withTenant(new dev.caskeleton.messaging.api.TenantContext("acme"))
|
||||||
|
.withRoutingKeys("customer-42", "customer-42");
|
||||||
|
|
||||||
|
Map<String, String> headers = mapper(false).map(record(Map.of(), metadata)).headers();
|
||||||
|
|
||||||
|
assertThat(headers)
|
||||||
|
.as("a relay that drops these makes the publish path part of the message's meaning")
|
||||||
|
.containsEntry(ReservedHeaders.PRODUCER, "order-api")
|
||||||
|
.containsEntry(ReservedHeaders.TENANT, "acme")
|
||||||
|
.containsEntry(ReservedHeaders.PARTITION_KEY, "customer-42")
|
||||||
|
.containsEntry(ReservedHeaders.ORDERING_KEY, "customer-42")
|
||||||
|
.containsEntry(ReservedHeaders.ORIGIN_DESTINATION, "orders.v1");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aColumnTheRowDoesNotCarryProducesNoHeaderAtAll() {
|
||||||
|
assertThat(mapper(false).map(record(Map.of())).headers())
|
||||||
|
.as("an empty string would be indistinguishable from a tenant literally named ''")
|
||||||
|
.doesNotContainKeys(
|
||||||
|
ReservedHeaders.TENANT, ReservedHeaders.CORRELATION_ID, ReservedHeaders.TRACEPARENT);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aForgedReservedHeaderOnTheRowCannotOverwriteTheCanonicalOne() {
|
||||||
|
Map<String, String> forged =
|
||||||
|
Map.of(ReservedHeaders.MESSAGE_ID, "00000000-0000-7000-8000-000000000000");
|
||||||
|
|
||||||
|
assertThat(mapper(false).map(record(forged)).headers())
|
||||||
|
.as("a CDC connector reads the table directly and never passes the write-path check")
|
||||||
|
.containsEntry(ReservedHeaders.MESSAGE_ID, MESSAGE_ID.value().toString());
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void theRoutedKeyIsNotTheTopicName() {
|
||||||
|
// Literals, not the class's own constants: comparing a configuration value against the constant
|
||||||
|
// that produced it asserts that the router agrees with itself, which it always will.
|
||||||
|
assertThat(new DebeziumOutboxEventRouter().connectorConfiguration("prod."))
|
||||||
|
.as("keying by destination puts every message on a topic onto one partition")
|
||||||
|
.containsEntry("transforms.outbox.table.field.event.key", "routing_key")
|
||||||
|
.containsEntry("transforms.outbox.route.by.field", "destination");
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
void thePayloadIsUnchangedByTheTransform() {
|
void thePayloadIsUnchangedByTheTransform() {
|
||||||
assertThat(mapper(false).map(record(Map.of())).payload())
|
assertThat(mapper(false).map(record(Map.of())).payload())
|
||||||
|
|||||||
+1
@@ -95,6 +95,7 @@ class JdbcOutboxTransactionRequirementTest {
|
|||||||
ContentType.JSON,
|
ContentType.JSON,
|
||||||
"{}".getBytes(java.nio.charset.StandardCharsets.UTF_8),
|
"{}".getBytes(java.nio.charset.StandardCharsets.UTF_8),
|
||||||
Map.of(),
|
Map.of(),
|
||||||
|
dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata.none(),
|
||||||
Instant.parse("2026-08-14T00:00:00Z"),
|
Instant.parse("2026-08-14T00:00:00Z"),
|
||||||
OutboxStatus.PENDING,
|
OutboxStatus.PENDING,
|
||||||
0,
|
0,
|
||||||
|
|||||||
+158
@@ -0,0 +1,158 @@
|
|||||||
|
package dev.caskeleton.messaging.outbox;
|
||||||
|
|
||||||
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.api.CausationId;
|
||||||
|
import dev.caskeleton.messaging.api.ContentType;
|
||||||
|
import dev.caskeleton.messaging.api.CorrelationId;
|
||||||
|
import dev.caskeleton.messaging.api.MessageEnvelope;
|
||||||
|
import dev.caskeleton.messaging.api.MessageId;
|
||||||
|
import dev.caskeleton.messaging.api.MessageType;
|
||||||
|
import dev.caskeleton.messaging.api.ProducerId;
|
||||||
|
import dev.caskeleton.messaging.api.SchemaVersion;
|
||||||
|
import dev.caskeleton.messaging.api.TenantContext;
|
||||||
|
import dev.caskeleton.messaging.api.TraceContext;
|
||||||
|
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||||
|
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
|
||||||
|
import dev.caskeleton.messaging.api.header.ReservedHeaders;
|
||||||
|
import dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata;
|
||||||
|
import dev.caskeleton.messaging.reliability.OutboxRecord;
|
||||||
|
import dev.caskeleton.messaging.reliability.OutboxStatus;
|
||||||
|
import dev.caskeleton.messaging.schema.EncodedMessage;
|
||||||
|
import java.nio.charset.StandardCharsets;
|
||||||
|
import java.time.Instant;
|
||||||
|
import java.util.Map;
|
||||||
|
import java.util.Optional;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* What survives a trip through the database.
|
||||||
|
*
|
||||||
|
* <p>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<EncodedMessage> envelope = factory.toEnvelope(record(fullMetadata(), Map.of()));
|
||||||
|
|
||||||
|
assertThat(envelope.producer()).isEqualTo(new ProducerId("order-api"));
|
||||||
|
assertThat(envelope.occurredAt()).contains(OCCURRED_AT);
|
||||||
|
assertThat(envelope.correlationId()).contains(new CorrelationId("checkout-7"));
|
||||||
|
assertThat(envelope.causationId()).contains(new CausationId(CAUSE));
|
||||||
|
assertThat(envelope.tenantContext()).contains(new TenantContext("acme"));
|
||||||
|
assertThat(envelope.partitionKey()).contains("customer-42");
|
||||||
|
assertThat(envelope.orderingKey()).contains("customer-42");
|
||||||
|
assertThat(envelope.traceContext().traceparent()).contains(TRACEPARENT);
|
||||||
|
assertThat(envelope.payload().schemaReference())
|
||||||
|
.hasValueSatisfying(
|
||||||
|
reference -> {
|
||||||
|
assertThat(reference.subject()).isEqualTo("order.created-value");
|
||||||
|
assertThat(reference.version()).isEqualTo(new SchemaVersion(1));
|
||||||
|
assertThat(reference.schemaUri()).contains(java.net.URI.create("urn:schema:1"));
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aTenantIsNeverReconstructedAsAbsent() {
|
||||||
|
assertThat(factory.toEnvelope(record(fullMetadata(), Map.of())).tenantContext())
|
||||||
|
.as("a message published by one tenant and consumed as belonging to none is an escalation")
|
||||||
|
.contains(new TenantContext("acme"));
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aRowWithoutAProducerIsAttributedToTheServiceThatOwnsTheRelay() {
|
||||||
|
MessageEnvelope<EncodedMessage> envelope =
|
||||||
|
factory.toEnvelope(record(OutboxCanonicalMetadata.none(), Map.of()));
|
||||||
|
|
||||||
|
assertThat(envelope.producer())
|
||||||
|
.as("a row written before the column existed has no honest producer but this one")
|
||||||
|
.isEqualTo(new ProducerId("relay-owner"));
|
||||||
|
assertThat(envelope.occurredAt())
|
||||||
|
.as("the transaction that wrote the row is the one the fact occurred in")
|
||||||
|
.contains(WRITTEN_AT);
|
||||||
|
assertThat(envelope.tenantContext()).isEmpty();
|
||||||
|
assertThat(envelope.payload().schemaReference()).isEmpty();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void applicationHeadersOnTheRowStillTravel() {
|
||||||
|
assertThat(
|
||||||
|
factory
|
||||||
|
.toEnvelope(record(OutboxCanonicalMetadata.none(), Map.of("x-tenant-tier", "gold")))
|
||||||
|
.headers()
|
||||||
|
.find("x-tenant-tier"))
|
||||||
|
.hasValueSatisfying(value -> assertThat(value.value()).isEqualTo("gold"));
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aReservedHeaderOnTheRowIsRefusedEvenWhenItIsARoutingKey() {
|
||||||
|
assertThatThrownBy(
|
||||||
|
() ->
|
||||||
|
factory.toEnvelope(
|
||||||
|
record(
|
||||||
|
OutboxCanonicalMetadata.none(),
|
||||||
|
Map.of(ReservedHeaders.PARTITION_KEY, "customer-42"))))
|
||||||
|
.as("the routing keys were the exception that kept the reserved-name door ajar")
|
||||||
|
.isInstanceOf(MessagingConfigurationException.class)
|
||||||
|
.hasMessageContaining("reserved namespace");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aForgedMessageIdOnTheRowCannotOverwriteTheCanonicalOne() {
|
||||||
|
assertThatThrownBy(
|
||||||
|
() ->
|
||||||
|
factory.toEnvelope(
|
||||||
|
record(
|
||||||
|
OutboxCanonicalMetadata.none(),
|
||||||
|
Map.of(ReservedHeaders.MESSAGE_ID, MessageId.newId().value().toString()))))
|
||||||
|
.isInstanceOf(MessagingConfigurationException.class)
|
||||||
|
.hasMessageContaining(ReservedHeaders.MESSAGE_ID);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static OutboxCanonicalMetadata fullMetadata() {
|
||||||
|
return new OutboxCanonicalMetadata(
|
||||||
|
Optional.of(new ProducerId("order-api")),
|
||||||
|
Optional.of(OCCURRED_AT),
|
||||||
|
Optional.of(new CorrelationId("checkout-7")),
|
||||||
|
Optional.of(new CausationId(CAUSE)),
|
||||||
|
Optional.of(new TenantContext("acme")),
|
||||||
|
Optional.of("customer-42"),
|
||||||
|
Optional.of("customer-42"),
|
||||||
|
Optional.of("order.created-value"),
|
||||||
|
Optional.of("urn:schema:1"),
|
||||||
|
new TraceContext(Optional.of(TRACEPARENT), Optional.empty(), Optional.empty()));
|
||||||
|
}
|
||||||
|
|
||||||
|
private static OutboxRecord record(
|
||||||
|
OutboxCanonicalMetadata metadata, Map<String, String> headers) {
|
||||||
|
return new OutboxRecord(
|
||||||
|
MessageId.newId(),
|
||||||
|
new DestinationName("order-events"),
|
||||||
|
new MessageType("order.created"),
|
||||||
|
new SchemaVersion(1),
|
||||||
|
ContentType.JSON,
|
||||||
|
"{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8),
|
||||||
|
headers,
|
||||||
|
metadata,
|
||||||
|
WRITTEN_AT,
|
||||||
|
OutboxStatus.PENDING,
|
||||||
|
0,
|
||||||
|
Optional.empty(),
|
||||||
|
Optional.empty());
|
||||||
|
}
|
||||||
|
}
|
||||||
+153
-6
@@ -7,6 +7,7 @@ import dev.caskeleton.messaging.api.MessageId;
|
|||||||
import dev.caskeleton.messaging.api.MessageType;
|
import dev.caskeleton.messaging.api.MessageType;
|
||||||
import dev.caskeleton.messaging.api.SchemaVersion;
|
import dev.caskeleton.messaging.api.SchemaVersion;
|
||||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||||
|
import dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata;
|
||||||
import dev.caskeleton.messaging.reliability.OutboxRecord;
|
import dev.caskeleton.messaging.reliability.OutboxRecord;
|
||||||
import dev.caskeleton.messaging.reliability.OutboxStatus;
|
import dev.caskeleton.messaging.reliability.OutboxStatus;
|
||||||
import dev.caskeleton.messaging.testkit.DockerAvailability;
|
import dev.caskeleton.messaging.testkit.DockerAvailability;
|
||||||
@@ -94,7 +95,9 @@ class OutboxPostgresIT {
|
|||||||
assertThat(leasedRecord.messageId()).isEqualTo(record.messageId());
|
assertThat(leasedRecord.messageId()).isEqualTo(record.messageId());
|
||||||
assertThat(leasedRecord.messageType()).isEqualTo(record.messageType());
|
assertThat(leasedRecord.messageType()).isEqualTo(record.messageType());
|
||||||
assertThat(leasedRecord.payload()).isEqualTo(record.payload());
|
assertThat(leasedRecord.payload()).isEqualTo(record.payload());
|
||||||
assertThat(leasedRecord.headers()).containsEntry("msg.partition-key", "acct-1");
|
assertThat(leasedRecord.metadata().partitionKey())
|
||||||
|
.as("the routing key is a column the relay can read without decoding the payload")
|
||||||
|
.contains("acct-1");
|
||||||
});
|
});
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -200,6 +203,12 @@ class OutboxPostgresIT {
|
|||||||
}
|
}
|
||||||
|
|
||||||
private static OutboxRecord record() {
|
private static OutboxRecord record() {
|
||||||
|
return record(
|
||||||
|
// The routing key is a column now, not a reserved header smuggled through the header map.
|
||||||
|
OutboxCanonicalMetadata.none().withRoutingKeys("acct-1", "acct-1"));
|
||||||
|
}
|
||||||
|
|
||||||
|
private static OutboxRecord record(OutboxCanonicalMetadata metadata) {
|
||||||
return new OutboxRecord(
|
return new OutboxRecord(
|
||||||
MessageId.newId(),
|
MessageId.newId(),
|
||||||
new DestinationName("order-events"),
|
new DestinationName("order-events"),
|
||||||
@@ -207,7 +216,8 @@ class OutboxPostgresIT {
|
|||||||
new SchemaVersion(1),
|
new SchemaVersion(1),
|
||||||
ContentType.JSON,
|
ContentType.JSON,
|
||||||
"{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8),
|
"{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8),
|
||||||
Map.of("msg.partition-key", "acct-1"),
|
Map.of(),
|
||||||
|
metadata,
|
||||||
NOW.minusSeconds(60),
|
NOW.minusSeconds(60),
|
||||||
OutboxStatus.PENDING,
|
OutboxStatus.PENDING,
|
||||||
0,
|
0,
|
||||||
@@ -223,9 +233,67 @@ class OutboxPostgresIT {
|
|||||||
return source;
|
return source;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Every migration in the module, in version order.
|
||||||
|
*
|
||||||
|
* <p>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<String> migrations() throws IOException {
|
private static java.util.List<String> migrations() throws IOException {
|
||||||
return java.util.List.of(
|
java.net.URL directory =
|
||||||
migration("V1__messaging_outbox.sql"), migration("V2__messaging_outbox_lease_fencing.sql"));
|
OutboxPostgresIT.class.getClassLoader().getResource("db/migration/messaging");
|
||||||
|
if (directory == null) {
|
||||||
|
throw new IOException("the messaging migrations are missing from the classpath");
|
||||||
|
}
|
||||||
|
java.io.File[] files =
|
||||||
|
new java.io.File(java.net.URI.create(directory.toString()))
|
||||||
|
.listFiles((dir, name) -> name.endsWith(".sql"));
|
||||||
|
if (files == null || files.length == 0) {
|
||||||
|
throw new IOException("no migration applied; the schema under test would be empty");
|
||||||
|
}
|
||||||
|
java.util.List<String> names =
|
||||||
|
java.util.Arrays.stream(files).map(java.io.File::getName).sorted().toList();
|
||||||
|
java.util.List<String> statements = new java.util.ArrayList<>();
|
||||||
|
for (String name : names) {
|
||||||
|
statements.add(migration(name));
|
||||||
|
}
|
||||||
|
return statements;
|
||||||
|
}
|
||||||
|
|
||||||
|
private int countWhere(String predicate) {
|
||||||
|
try (Connection connection = dataSource.getConnection();
|
||||||
|
Statement statement = connection.createStatement();
|
||||||
|
java.sql.ResultSet results =
|
||||||
|
statement.executeQuery("SELECT count(*) FROM messaging_outbox WHERE " + predicate)) {
|
||||||
|
results.next();
|
||||||
|
return results.getInt(1);
|
||||||
|
} catch (SQLException failure) {
|
||||||
|
throw new IllegalStateException("could not count outbox rows", failure);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
private String routingKeyOf(MessageId messageId) {
|
||||||
|
try (Connection connection = dataSource.getConnection();
|
||||||
|
java.sql.PreparedStatement statement =
|
||||||
|
connection.prepareStatement(
|
||||||
|
"SELECT routing_key FROM messaging_outbox WHERE message_id = ?")) {
|
||||||
|
statement.setObject(1, messageId.value());
|
||||||
|
try (java.sql.ResultSet results = statement.executeQuery()) {
|
||||||
|
results.next();
|
||||||
|
return results.getString(1);
|
||||||
|
}
|
||||||
|
} catch (SQLException failure) {
|
||||||
|
throw new IllegalStateException("could not read the routing key", failure);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
private void execute(String sql) throws SQLException {
|
||||||
|
try (Connection connection = dataSource.getConnection();
|
||||||
|
Statement statement = connection.createStatement()) {
|
||||||
|
statement.execute(sql);
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
private static String migration(String fileName) throws IOException {
|
private static String migration(String fileName) throws IOException {
|
||||||
@@ -385,6 +453,84 @@ class OutboxPostgresIT {
|
|||||||
.isEqualTo(OutboxStatus.PUBLISHED);
|
.isEqualTo(OutboxStatus.PUBLISHED);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void everyCanonicalColumnRoundTripsThroughTheDatabase() {
|
||||||
|
MessageId cause = MessageId.newId();
|
||||||
|
OutboxCanonicalMetadata written =
|
||||||
|
new OutboxCanonicalMetadata(
|
||||||
|
Optional.of(new dev.caskeleton.messaging.api.ProducerId("order-api")),
|
||||||
|
Optional.of(NOW.minusSeconds(120)),
|
||||||
|
Optional.of(new dev.caskeleton.messaging.api.CorrelationId("checkout-7")),
|
||||||
|
Optional.of(new dev.caskeleton.messaging.api.CausationId(cause)),
|
||||||
|
Optional.of(new dev.caskeleton.messaging.api.TenantContext("acme")),
|
||||||
|
Optional.of("customer-42"),
|
||||||
|
Optional.of("customer-42"),
|
||||||
|
Optional.of("order.created-value"),
|
||||||
|
Optional.of("urn:schema:1"),
|
||||||
|
new dev.caskeleton.messaging.api.TraceContext(
|
||||||
|
Optional.of("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"),
|
||||||
|
Optional.empty(),
|
||||||
|
Optional.empty()));
|
||||||
|
OutboxRecord record = record(written);
|
||||||
|
|
||||||
|
appendInTransaction(record);
|
||||||
|
|
||||||
|
assertThat(repository.find(record.messageId()).orElseThrow().metadata())
|
||||||
|
.as("what the relay reads back has to be what the business transaction wrote")
|
||||||
|
.isEqualTo(written);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void theRelayCanSelectOneTenantsBacklogWithoutDecodingAPayload() {
|
||||||
|
appendInTransaction(
|
||||||
|
record(
|
||||||
|
OutboxCanonicalMetadata.none()
|
||||||
|
.withTenant(new dev.caskeleton.messaging.api.TenantContext("acme"))));
|
||||||
|
appendInTransaction(
|
||||||
|
record(
|
||||||
|
OutboxCanonicalMetadata.none()
|
||||||
|
.withTenant(new dev.caskeleton.messaging.api.TenantContext("globex"))));
|
||||||
|
|
||||||
|
assertThat(countWhere("tenant = 'acme'"))
|
||||||
|
.as("the operational question an outbox backlog always raises, answerable as a SELECT")
|
||||||
|
.isEqualTo(1);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void theStoredRoutingKeyIsTheOneBothRelaysWouldUse() {
|
||||||
|
OutboxRecord keyed =
|
||||||
|
record(OutboxCanonicalMetadata.none().withRoutingKeys("customer-42", "customer-42"));
|
||||||
|
OutboxRecord unkeyed = record(OutboxCanonicalMetadata.none());
|
||||||
|
appendInTransaction(keyed);
|
||||||
|
appendInTransaction(unkeyed);
|
||||||
|
|
||||||
|
DebeziumOutboxEventRouter router = new DebeziumOutboxEventRouter();
|
||||||
|
assertThat(routingKeyOf(keyed.messageId()))
|
||||||
|
.as("the CDC key used to be the destination, so every message on a topic shared a key")
|
||||||
|
.isEqualTo(router.routingKey(keyed))
|
||||||
|
.isEqualTo("customer-42");
|
||||||
|
assertThat(routingKeyOf(unkeyed.messageId()))
|
||||||
|
.as("the fallback is stated once, in the column, and the Java agrees with it")
|
||||||
|
.isEqualTo(router.routingKey(unkeyed))
|
||||||
|
.isEqualTo(unkeyed.messageId().value().toString());
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aTenantThatBreaksTheSlugBoundIsRefusedByTheDatabase() {
|
||||||
|
org.assertj.core.api.Assertions.assertThatThrownBy(
|
||||||
|
() ->
|
||||||
|
execute(
|
||||||
|
"INSERT INTO messaging_outbox (message_id, destination, message_type, "
|
||||||
|
+ "schema_version, content_type, payload, created_at, status, attempts, "
|
||||||
|
+ "tenant) VALUES ('"
|
||||||
|
+ MessageId.newId().value()
|
||||||
|
+ "', 'order-events', 'order.created', 1, 'application/json', '\\x7b7d', "
|
||||||
|
+ "now(), 'PENDING', 0, 'Tenant With Spaces')"))
|
||||||
|
.as("a CDC connector and an operator both write this table without passing through Java")
|
||||||
|
.isInstanceOf(SQLException.class)
|
||||||
|
.hasMessageContaining("ck_messaging_outbox_tenant");
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
void aHeaderValueWithControlCharactersRoundTrips() {
|
void aHeaderValueWithControlCharactersRoundTrips() {
|
||||||
OutboxRecord record =
|
OutboxRecord record =
|
||||||
@@ -398,7 +544,8 @@ class OutboxPostgresIT {
|
|||||||
// A tab and a newline in a header value. Only backslash and quote were escaped, so
|
// A tab and a newline in a header value. Only backslash and quote were escaped, so
|
||||||
// this produced a document PostgreSQL refuses as invalid JSONB and the append failed
|
// this produced a document PostgreSQL refuses as invalid JSONB and the append failed
|
||||||
// with an error naming neither the header nor the row.
|
// with an error naming neither the header nor the row.
|
||||||
Map.of("msg.note", "line one\nline\ttwo"),
|
Map.of("x-note", "line one\nline\ttwo"),
|
||||||
|
OutboxCanonicalMetadata.none(),
|
||||||
NOW.minusSeconds(60),
|
NOW.minusSeconds(60),
|
||||||
OutboxStatus.PENDING,
|
OutboxStatus.PENDING,
|
||||||
0,
|
0,
|
||||||
@@ -408,7 +555,7 @@ class OutboxPostgresIT {
|
|||||||
appendInTransaction(record);
|
appendInTransaction(record);
|
||||||
|
|
||||||
assertThat(repository.find(record.messageId()).orElseThrow().headers())
|
assertThat(repository.find(record.messageId()).orElseThrow().headers())
|
||||||
.containsEntry("msg.note", "line one\nline\ttwo");
|
.containsEntry("x-note", "line one\nline\ttwo");
|
||||||
}
|
}
|
||||||
|
|
||||||
private void appendInTransaction(OutboxRecord record) {
|
private void appendInTransaction(OutboxRecord record) {
|
||||||
|
|||||||
+60
@@ -80,6 +80,41 @@ class OutboxRelayTest {
|
|||||||
assertThat(publisher.publishedIds.get(1)).isEqualTo(record.messageId());
|
assertThat(publisher.publishedIds.get(1)).isEqualTo(record.messageId());
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void anAmbiguousRowWaitsForItsBackoffBeforeItIsClaimedAgain() {
|
||||||
|
OutboxRecord record = OutboxFixtures.pending();
|
||||||
|
repository.append(record);
|
||||||
|
RecordingOutboxPublisher publisher = RecordingOutboxPublisher.ambiguous();
|
||||||
|
|
||||||
|
relay(publisher).runOnce(NOW);
|
||||||
|
OutboxRelayReport tooSoon = relay(publisher).runOnce(NOW.plusMillis(100));
|
||||||
|
|
||||||
|
assertThat(tooSoon.leased())
|
||||||
|
.as("a backoff nothing writes on the row is a backoff the next pass cannot see")
|
||||||
|
.isZero();
|
||||||
|
assertThat(publisher.publishedIds).hasSize(1);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aRowThatSpendsItsAttemptBudgetIsParkedRatherThanLeftRetryable() {
|
||||||
|
OutboxRecord record = OutboxFixtures.pending();
|
||||||
|
repository.append(record);
|
||||||
|
RecordingOutboxPublisher publisher = RecordingOutboxPublisher.ambiguous();
|
||||||
|
OutboxRelay relay = relay(publisher, budgetOf(2));
|
||||||
|
|
||||||
|
relay.runOnce(NOW);
|
||||||
|
OutboxRelayReport last = relay.runOnce(NOW.plus(Duration.ofHours(1)));
|
||||||
|
|
||||||
|
assertThat(last.exhausted())
|
||||||
|
.as("a rejected row needs a fix and a spent one needs a redrive")
|
||||||
|
.isEqualTo(1);
|
||||||
|
assertThat(repository.find(record.messageId()).orElseThrow().status())
|
||||||
|
.isEqualTo(OutboxStatus.EXHAUSTED);
|
||||||
|
assertThat(relay.runOnce(NOW.plus(Duration.ofDays(1))).leased())
|
||||||
|
.as("only an operator redrive brings a parked row back")
|
||||||
|
.isZero();
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
void aRejectedPublishIsMarkedFailedAndNotRetried() {
|
void aRejectedPublishIsMarkedFailedAndNotRetried() {
|
||||||
OutboxRecord record = OutboxFixtures.pending();
|
OutboxRecord record = OutboxFixtures.pending();
|
||||||
@@ -135,6 +170,30 @@ class OutboxRelayTest {
|
|||||||
100,
|
100,
|
||||||
Duration.ofSeconds(30));
|
Duration.ofSeconds(30));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
private OutboxRelay relay(MessagePublisher publisher, OutboxRetryScheduler scheduler) {
|
||||||
|
return new OutboxRelay(
|
||||||
|
repository,
|
||||||
|
publisher,
|
||||||
|
new OutboxEnvelopeFactory(new ProducerId("order-api")),
|
||||||
|
100,
|
||||||
|
Duration.ofSeconds(30),
|
||||||
|
"relay-under-test",
|
||||||
|
scheduler);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static OutboxRetryScheduler budgetOf(int maxAttempts) {
|
||||||
|
OutboxProperties defaults = OutboxProperties.defaults();
|
||||||
|
return new OutboxRetryScheduler(
|
||||||
|
new OutboxProperties(
|
||||||
|
defaults.batchSize(),
|
||||||
|
defaults.leaseDuration(),
|
||||||
|
defaults.publishTimeout(),
|
||||||
|
defaults.pollInterval(),
|
||||||
|
defaults.retentionAfterPublish(),
|
||||||
|
maxAttempts),
|
||||||
|
Duration.ofMinutes(5));
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Builds outbox rows. */
|
/** Builds outbox rows. */
|
||||||
@@ -151,6 +210,7 @@ final class OutboxFixtures {
|
|||||||
ContentType.JSON,
|
ContentType.JSON,
|
||||||
"{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8),
|
"{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8),
|
||||||
Map.of(),
|
Map.of(),
|
||||||
|
dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata.none(),
|
||||||
Instant.parse("2026-08-10T09:14:00Z"),
|
Instant.parse("2026-08-10T09:14:00Z"),
|
||||||
OutboxStatus.PENDING,
|
OutboxStatus.PENDING,
|
||||||
0,
|
0,
|
||||||
|
|||||||
+163
@@ -0,0 +1,163 @@
|
|||||||
|
package dev.caskeleton.messaging.outbox;
|
||||||
|
|
||||||
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.api.MessageEnvelope;
|
||||||
|
import dev.caskeleton.messaging.api.ProducerId;
|
||||||
|
import dev.caskeleton.messaging.api.destination.MessageDestination;
|
||||||
|
import dev.caskeleton.messaging.api.publish.ConfirmationLevel;
|
||||||
|
import dev.caskeleton.messaging.api.publish.MessagePublisher;
|
||||||
|
import dev.caskeleton.messaging.api.publish.PublishCompletion;
|
||||||
|
import dev.caskeleton.messaging.api.publish.PublishEvidence;
|
||||||
|
import dev.caskeleton.messaging.api.publish.PublishOptions;
|
||||||
|
import dev.caskeleton.messaging.api.publish.PublishResult;
|
||||||
|
import dev.caskeleton.messaging.api.publish.RoutingOutcome;
|
||||||
|
import dev.caskeleton.messaging.reliability.OutboxRecord;
|
||||||
|
import dev.caskeleton.messaging.reliability.OutboxStatus;
|
||||||
|
import java.time.Duration;
|
||||||
|
import java.util.Optional;
|
||||||
|
import java.util.concurrent.CompletableFuture;
|
||||||
|
import java.util.concurrent.CompletionStage;
|
||||||
|
import java.util.concurrent.CountDownLatch;
|
||||||
|
import java.util.concurrent.TimeUnit;
|
||||||
|
import org.junit.jupiter.api.DisplayName;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Whether anything actually drives the relay.
|
||||||
|
*
|
||||||
|
* <p>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 <T> CompletionStage<PublishResult> publish(
|
||||||
|
MessageDestination<T> destination, MessageEnvelope<T> message, PublishOptions options) {
|
||||||
|
started.countDown();
|
||||||
|
try {
|
||||||
|
Thread.sleep(duration.toMillis());
|
||||||
|
} catch (InterruptedException interrupted) {
|
||||||
|
Thread.currentThread().interrupt();
|
||||||
|
}
|
||||||
|
return CompletableFuture.completedFuture(
|
||||||
|
new PublishResult(
|
||||||
|
PublishCompletion.CONFIRMED,
|
||||||
|
PublishEvidence.confirmed(ConfirmationLevel.BROKER_ACK),
|
||||||
|
RoutingOutcome.NOT_APPLICABLE,
|
||||||
|
Optional.empty(),
|
||||||
|
1,
|
||||||
|
Duration.ofMillis(1),
|
||||||
|
Optional.empty()));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/** A publisher whose failure reaches the worker as an exception rather than a result. */
|
||||||
|
private static final class ThrowingPublisher implements MessagePublisher {
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public <T> CompletionStage<PublishResult> publish(
|
||||||
|
MessageDestination<T> destination, MessageEnvelope<T> message, PublishOptions options) {
|
||||||
|
throw new IllegalStateException("the broker connection is gone");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
+102
-3
@@ -2,7 +2,10 @@ package dev.caskeleton.messaging.policy;
|
|||||||
|
|
||||||
import dev.caskeleton.messaging.api.error.MessageBackpressureException;
|
import dev.caskeleton.messaging.api.error.MessageBackpressureException;
|
||||||
import dev.caskeleton.messaging.api.error.MessageTooLargeException;
|
import dev.caskeleton.messaging.api.error.MessageTooLargeException;
|
||||||
|
import java.util.Map;
|
||||||
import java.util.Objects;
|
import java.util.Objects;
|
||||||
|
import java.util.concurrent.ConcurrentHashMap;
|
||||||
|
import java.util.concurrent.atomic.AtomicInteger;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The single gate every publish passes before any transport work begins.
|
* The single gate every publish passes before any transport work begins.
|
||||||
@@ -16,22 +19,49 @@ import java.util.Objects;
|
|||||||
* under the same message id without risking a duplicate. That is the reason admission lives at the
|
* under the same message id without risking a duplicate. That is the reason admission lives at the
|
||||||
* front of the pipeline instead of being folded into the adapter's error handling, where a partial
|
* front of the pipeline instead of being folded into the adapter's error handling, where a partial
|
||||||
* write would already have made the outcome unknowable.
|
* write would already have made the outcome unknowable.
|
||||||
|
*
|
||||||
|
* <p>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 {
|
public final class MessagingAdmissionController {
|
||||||
|
|
||||||
private final PayloadLimitGuard payloadGuard;
|
private final PayloadLimitGuard payloadGuard;
|
||||||
private final InFlightLimiter limiter;
|
private final InFlightLimiter limiter;
|
||||||
|
private final int perDestinationLimit;
|
||||||
|
private final Map<String, AtomicInteger> perDestination = new ConcurrentHashMap<>();
|
||||||
private volatile boolean acceptingNewWork = true;
|
private volatile boolean acceptingNewWork = true;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Creates an admission controller.
|
* Creates an admission controller whose only ceiling is the process-wide one.
|
||||||
*
|
*
|
||||||
* @param payloadGuard the payload size guard
|
* @param payloadGuard the payload size guard
|
||||||
* @param limiter the in-flight permit pool
|
* @param limiter the in-flight permit pool
|
||||||
*/
|
*/
|
||||||
public MessagingAdmissionController(PayloadLimitGuard payloadGuard, InFlightLimiter limiter) {
|
public MessagingAdmissionController(PayloadLimitGuard payloadGuard, InFlightLimiter limiter) {
|
||||||
|
this(payloadGuard, limiter, limiter.limit());
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Creates an admission controller with a per-destination ceiling.
|
||||||
|
*
|
||||||
|
* @param payloadGuard the payload size guard
|
||||||
|
* @param limiter the in-flight permit pool
|
||||||
|
* @param perDestinationLimit how much in-flight work one destination may hold
|
||||||
|
*/
|
||||||
|
public MessagingAdmissionController(
|
||||||
|
PayloadLimitGuard payloadGuard, InFlightLimiter limiter, int perDestinationLimit) {
|
||||||
this.payloadGuard = Objects.requireNonNull(payloadGuard, "payloadGuard must not be null");
|
this.payloadGuard = Objects.requireNonNull(payloadGuard, "payloadGuard must not be null");
|
||||||
this.limiter = Objects.requireNonNull(limiter, "limiter must not be null");
|
this.limiter = Objects.requireNonNull(limiter, "limiter must not be null");
|
||||||
|
if (perDestinationLimit < 1) {
|
||||||
|
throw new IllegalArgumentException("perDestinationLimit must be at least 1");
|
||||||
|
}
|
||||||
|
if (perDestinationLimit > limiter.limit()) {
|
||||||
|
throw new IllegalArgumentException(
|
||||||
|
"perDestinationLimit cannot exceed the process-wide limit, or it is not a limit");
|
||||||
|
}
|
||||||
|
this.perDestinationLimit = perDestinationLimit;
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -51,15 +81,27 @@ public final class MessagingAdmissionController {
|
|||||||
"SHUTTING_DOWN", "the messaging runtime stopped accepting new publishes");
|
"SHUTTING_DOWN", "the messaging runtime stopped accepting new publishes");
|
||||||
}
|
}
|
||||||
|
|
||||||
|
if (!reserve(destination)) {
|
||||||
|
throw new MessageBackpressureException(
|
||||||
|
"DESTINATION_IN_FLIGHT_LIMIT_EXCEEDED",
|
||||||
|
"%s already holds its %d in-flight publishes; one slow destination does not get to"
|
||||||
|
.formatted(destination, perDestinationLimit)
|
||||||
|
+ " consume the whole process");
|
||||||
|
}
|
||||||
|
|
||||||
boolean acquired;
|
boolean acquired;
|
||||||
try {
|
try {
|
||||||
acquired = limiter.tryAcquire();
|
acquired = limiter.tryAcquire();
|
||||||
} catch (InterruptedException interrupted) {
|
} catch (InterruptedException interrupted) {
|
||||||
|
// The destination slot was taken a moment ago and no publish will use it, so it goes back
|
||||||
|
// here: a slot leaked per interruption shrinks the destination's ceiling until it is zero.
|
||||||
|
release(destination);
|
||||||
Thread.currentThread().interrupt();
|
Thread.currentThread().interrupt();
|
||||||
throw new MessageBackpressureException(
|
throw new MessageBackpressureException(
|
||||||
"ADMISSION_INTERRUPTED", "interrupted while waiting for a publish permit");
|
"ADMISSION_INTERRUPTED", "interrupted while waiting for a publish permit");
|
||||||
}
|
}
|
||||||
if (!acquired) {
|
if (!acquired) {
|
||||||
|
release(destination);
|
||||||
throw new MessageBackpressureException(
|
throw new MessageBackpressureException(
|
||||||
"IN_FLIGHT_LIMIT_EXCEEDED",
|
"IN_FLIGHT_LIMIT_EXCEEDED",
|
||||||
"no publish permit became available for %s within the bounded wait"
|
"no publish permit became available for %s within the bounded wait"
|
||||||
@@ -67,8 +109,24 @@ public final class MessagingAdmissionController {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Releases the permit taken by a successful {@link #admit}. */
|
/**
|
||||||
public void complete() {
|
* Releases the permit taken by a successful {@link #admit}.
|
||||||
|
*
|
||||||
|
* <p>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();
|
limiter.release();
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -98,4 +156,45 @@ public final class MessagingAdmissionController {
|
|||||||
public int inFlight() {
|
public int inFlight() {
|
||||||
return limiter.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;
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+79
-4
@@ -26,7 +26,7 @@ class MessagingAdmissionControllerTest {
|
|||||||
controller.admit(DESTINATION, 100);
|
controller.admit(DESTINATION, 100);
|
||||||
|
|
||||||
assertThat(controller.inFlight()).isEqualTo(1);
|
assertThat(controller.inFlight()).isEqualTo(1);
|
||||||
controller.complete();
|
controller.complete(DESTINATION);
|
||||||
assertThat(controller.inFlight()).isZero();
|
assertThat(controller.inFlight()).isZero();
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -81,8 +81,8 @@ class MessagingAdmissionControllerTest {
|
|||||||
void aReleaseWithoutAnAdmitCannotRaiseTheCeiling() {
|
void aReleaseWithoutAnAdmitCannotRaiseTheCeiling() {
|
||||||
MessagingAdmissionController controller = controller(1);
|
MessagingAdmissionController controller = controller(1);
|
||||||
|
|
||||||
controller.complete();
|
controller.complete(DESTINATION);
|
||||||
controller.complete();
|
controller.complete(DESTINATION);
|
||||||
controller.admit(DESTINATION, 100);
|
controller.admit(DESTINATION, 100);
|
||||||
|
|
||||||
assertThatThrownBy(() -> controller.admit(DESTINATION, 100))
|
assertThatThrownBy(() -> controller.admit(DESTINATION, 100))
|
||||||
@@ -90,6 +90,81 @@ class MessagingAdmissionControllerTest {
|
|||||||
.isInstanceOf(MessageBackpressureException.class);
|
.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
|
@Test
|
||||||
void aBatchIsBoundedByCountAndByAggregateBytes() {
|
void aBatchIsBoundedByCountAndByAggregateBytes() {
|
||||||
PayloadLimitGuard guard = new PayloadLimitGuard(new PayloadPolicy(1024, 512));
|
PayloadLimitGuard guard = new PayloadLimitGuard(new PayloadPolicy(1024, 512));
|
||||||
@@ -113,7 +188,7 @@ class MessagingAdmissionControllerTest {
|
|||||||
|
|
||||||
Thread waiter = new Thread(() -> controller.admit(DESTINATION, 100));
|
Thread waiter = new Thread(() -> controller.admit(DESTINATION, 100));
|
||||||
waiter.start();
|
waiter.start();
|
||||||
controller.complete();
|
controller.complete(DESTINATION);
|
||||||
waiter.join(Duration.ofSeconds(5).toMillis());
|
waiter.join(Duration.ofSeconds(5).toMillis());
|
||||||
|
|
||||||
assertThat(waiter.isAlive()).isFalse();
|
assertThat(waiter.isAlive()).isFalse();
|
||||||
|
|||||||
+1
-2
@@ -234,8 +234,7 @@ class PulsarAdapterContractTest {
|
|||||||
return new TransportPublishRequest(
|
return new TransportPublishRequest(
|
||||||
profile(),
|
profile(),
|
||||||
envelope(64),
|
envelope(64),
|
||||||
new PublishOptions(
|
new PublishOptions(timeout, defaults.confirmation(), defaults.deduplication()));
|
||||||
timeout, defaults.confirmation(), defaults.deduplication(), defaults.brokerHints()));
|
|
||||||
}
|
}
|
||||||
|
|
||||||
private static TransportPublishRequest request(int payloadBytes) {
|
private static TransportPublishRequest request(int payloadBytes) {
|
||||||
|
|||||||
+3
-3
@@ -13,7 +13,6 @@ import dev.caskeleton.messaging.api.TraceContext;
|
|||||||
import dev.caskeleton.messaging.api.delivery.DeliveryMetadata;
|
import dev.caskeleton.messaging.api.delivery.DeliveryMetadata;
|
||||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||||
import dev.caskeleton.messaging.api.error.MessageValidationException;
|
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.api.header.ReservedHeaders;
|
||||||
import dev.caskeleton.messaging.schema.EncodedMessage;
|
import dev.caskeleton.messaging.schema.EncodedMessage;
|
||||||
import java.time.Instant;
|
import java.time.Instant;
|
||||||
@@ -87,12 +86,13 @@ public final class RabbitDeliveryMapper {
|
|||||||
contentType,
|
contentType,
|
||||||
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.PARTITION_KEY)),
|
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.PARTITION_KEY)),
|
||||||
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.ORDERING_KEY)),
|
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.ORDERING_KEY)),
|
||||||
Optional.<TenantContext>empty(),
|
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.TENANT))
|
||||||
|
.map(TenantContext::new),
|
||||||
new TraceContext(
|
new TraceContext(
|
||||||
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.TRACEPARENT)),
|
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.TRACEPARENT)),
|
||||||
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.TRACESTATE)),
|
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.TRACESTATE)),
|
||||||
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.BAGGAGE))),
|
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.BAGGAGE))),
|
||||||
MessageHeaders.empty(),
|
headerMapper.carriedForward(properties),
|
||||||
new EncodedMessage(payload, contentType, Optional.empty()));
|
new EncodedMessage(payload, contentType, Optional.empty()));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
+44
-5
@@ -1,6 +1,7 @@
|
|||||||
package dev.caskeleton.messaging.rabbit;
|
package dev.caskeleton.messaging.rabbit;
|
||||||
|
|
||||||
import dev.caskeleton.messaging.api.MessageEnvelope;
|
import dev.caskeleton.messaging.api.MessageEnvelope;
|
||||||
|
import dev.caskeleton.messaging.api.header.CanonicalEnvelopeHeaders;
|
||||||
import dev.caskeleton.messaging.api.header.HeaderName;
|
import dev.caskeleton.messaging.api.header.HeaderName;
|
||||||
import dev.caskeleton.messaging.api.header.HeaderValue;
|
import dev.caskeleton.messaging.api.header.HeaderValue;
|
||||||
import dev.caskeleton.messaging.api.header.MessageHeaders;
|
import dev.caskeleton.messaging.api.header.MessageHeaders;
|
||||||
@@ -68,6 +69,11 @@ public final class RabbitHeaderMapper {
|
|||||||
envelope
|
envelope
|
||||||
.orderingKey()
|
.orderingKey()
|
||||||
.ifPresent(value -> setHeader(properties, ReservedHeaders.ORDERING_KEY, value));
|
.ifPresent(value -> setHeader(properties, ReservedHeaders.ORDERING_KEY, value));
|
||||||
|
// Written for the same reason as on the other broker: an AMQP message carries no ambient
|
||||||
|
// tenant, so a tenant left off the wire is a tenant the consumed envelope does not have.
|
||||||
|
envelope
|
||||||
|
.tenantContext()
|
||||||
|
.ifPresent(value -> setHeader(properties, ReservedHeaders.TENANT, value.tenantId()));
|
||||||
envelope
|
envelope
|
||||||
.traceContext()
|
.traceContext()
|
||||||
.traceparent()
|
.traceparent()
|
||||||
@@ -81,21 +87,25 @@ public final class RabbitHeaderMapper {
|
|||||||
.baggage()
|
.baggage()
|
||||||
.ifPresent(value -> setHeader(properties, ReservedHeaders.BAGGAGE, value));
|
.ifPresent(value -> setHeader(properties, ReservedHeaders.BAGGAGE, value));
|
||||||
|
|
||||||
// Application headers are written last, so an unchecked one would overwrite the canonical
|
// The envelope's header map is written last, so an unchecked name would overwrite the canonical
|
||||||
// reserved value the platform just wrote. A forged `msg.id` corrupts another message's inbox
|
// reserved value the platform just wrote. A forged `msg.id` corrupts another message's inbox
|
||||||
// deduplication, not merely its own delivery.
|
// deduplication, not merely its own delivery.
|
||||||
|
//
|
||||||
|
// Only names that restate an envelope field are refused. Retry attempt, failure and redrive
|
||||||
|
// bookkeeping have no envelope field to be read back from, so refusing them would make every
|
||||||
|
// retry-queue and dead-letter re-publish fail on the guard meant to protect identity.
|
||||||
envelope
|
envelope
|
||||||
.headers()
|
.headers()
|
||||||
.asMap()
|
.asMap()
|
||||||
.forEach(
|
.forEach(
|
||||||
(name, value) -> {
|
(name, value) -> {
|
||||||
if (dev.caskeleton.messaging.api.header.ReservedHeaders.isReserved(name.value())) {
|
if (CanonicalEnvelopeHeaders.restatesEnvelopeField(name.value())) {
|
||||||
throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException(
|
throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException(
|
||||||
"RESERVED_HEADER_FORGED",
|
"RESERVED_HEADER_FORGED",
|
||||||
"application header '"
|
"header '"
|
||||||
+ name.value()
|
+ name.value()
|
||||||
+ "' uses the reserved namespace; the canonical value is written by the"
|
+ "' restates a value the envelope already carries; the canonical value is"
|
||||||
+ " platform and must not be overridable by message content");
|
+ " written by the platform and must not be overridable by message content");
|
||||||
}
|
}
|
||||||
setHeader(properties, name.value(), value.value());
|
setHeader(properties, name.value(), value.value());
|
||||||
});
|
});
|
||||||
@@ -123,6 +133,35 @@ public final class RabbitHeaderMapper {
|
|||||||
return MessageHeaders.platform(values);
|
return MessageHeaders.platform(values);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Reads back the headers a rebuilt envelope keeps.
|
||||||
|
*
|
||||||
|
* <p>Everything except the names that were hoisted into envelope fields: the application's own
|
||||||
|
* headers, which were dropped entirely and so never survived a broker hop, and the platform's
|
||||||
|
* retry and redrive bookkeeping, whose loss restarted the attempt counter at one on every
|
||||||
|
* redelivery and left the retry budget capping nothing.
|
||||||
|
*
|
||||||
|
* <p>The hoisted names are excluded rather than kept alongside their fields, because a duplicate
|
||||||
|
* that can drift from the field is how the same message ends up with two different ids depending
|
||||||
|
* on which one the reader trusts.
|
||||||
|
*
|
||||||
|
* @param properties the message properties
|
||||||
|
* @return the headers to carry on the rebuilt envelope
|
||||||
|
*/
|
||||||
|
public MessageHeaders carriedForward(MessageProperties properties) {
|
||||||
|
Objects.requireNonNull(properties, "properties must not be null");
|
||||||
|
Map<HeaderName, HeaderValue> values = new LinkedHashMap<>();
|
||||||
|
properties
|
||||||
|
.getHeaders()
|
||||||
|
.forEach(
|
||||||
|
(name, value) -> {
|
||||||
|
if (value != null && !CanonicalEnvelopeHeaders.restatesEnvelopeField(name)) {
|
||||||
|
values.put(new HeaderName(name), new HeaderValue(String.valueOf(value)));
|
||||||
|
}
|
||||||
|
});
|
||||||
|
return MessageHeaders.platform(values);
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Reads one header value.
|
* Reads one header value.
|
||||||
*
|
*
|
||||||
|
|||||||
+152
@@ -0,0 +1,152 @@
|
|||||||
|
package dev.caskeleton.messaging.rabbit;
|
||||||
|
|
||||||
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
import static org.assertj.core.api.Assertions.assertThatCode;
|
||||||
|
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.api.ContentType;
|
||||||
|
import dev.caskeleton.messaging.api.CorrelationId;
|
||||||
|
import dev.caskeleton.messaging.api.MessageEnvelope;
|
||||||
|
import dev.caskeleton.messaging.api.MessageId;
|
||||||
|
import dev.caskeleton.messaging.api.MessageType;
|
||||||
|
import dev.caskeleton.messaging.api.ProducerId;
|
||||||
|
import dev.caskeleton.messaging.api.SchemaVersion;
|
||||||
|
import dev.caskeleton.messaging.api.TraceContext;
|
||||||
|
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
|
||||||
|
import dev.caskeleton.messaging.api.header.HeaderName;
|
||||||
|
import dev.caskeleton.messaging.api.header.HeaderValue;
|
||||||
|
import dev.caskeleton.messaging.api.header.MessageHeaders;
|
||||||
|
import dev.caskeleton.messaging.api.header.ReservedHeaders;
|
||||||
|
import dev.caskeleton.messaging.schema.EncodedMessage;
|
||||||
|
import java.nio.charset.StandardCharsets;
|
||||||
|
import java.time.Instant;
|
||||||
|
import java.util.LinkedHashMap;
|
||||||
|
import java.util.Map;
|
||||||
|
import java.util.Optional;
|
||||||
|
import org.junit.jupiter.api.DisplayName;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
import org.springframework.amqp.core.Message;
|
||||||
|
import org.springframework.amqp.core.MessageProperties;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* What an envelope still holds after it has been through RabbitMQ.
|
||||||
|
*
|
||||||
|
* <p>The publish and delivery mappers were written against each other's headers but never checked
|
||||||
|
* as one trip, so the application's own headers were dropped on the way back and the retry
|
||||||
|
* bookkeeping went with them — an attempt counter that restarts on every hop caps no redeliveries
|
||||||
|
* at all.
|
||||||
|
*/
|
||||||
|
class RabbitEnvelopeRoundTripTest {
|
||||||
|
|
||||||
|
private static final Instant NOW = Instant.parse("2026-08-15T10:00:00Z");
|
||||||
|
|
||||||
|
private final RabbitHeaderMapper headerMapper = new RabbitHeaderMapper();
|
||||||
|
|
||||||
|
private final RabbitDeliveryMapper deliveryMapper = new RabbitDeliveryMapper(headerMapper);
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("an application header survives the trip through the broker")
|
||||||
|
void anApplicationHeaderSurvivesTheTrip() {
|
||||||
|
MessageEnvelope<EncodedMessage> published =
|
||||||
|
envelope(
|
||||||
|
MessageHeaders.application(
|
||||||
|
Map.of(new HeaderName("x-source-system"), new HeaderValue("erp"))));
|
||||||
|
|
||||||
|
MessageEnvelope<EncodedMessage> delivered = roundTrip(published);
|
||||||
|
|
||||||
|
assertThat(delivered.headers().find("x-source-system"))
|
||||||
|
.map(HeaderValue::value)
|
||||||
|
.as("a header the producer wrote and the consumer cannot read is a header nobody has")
|
||||||
|
.hasValue("erp");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("the tenant survives the trip instead of arriving as no tenant at all")
|
||||||
|
void theTenantSurvivesTheTrip() {
|
||||||
|
MessageEnvelope<EncodedMessage> published =
|
||||||
|
envelope(MessageHeaders.empty())
|
||||||
|
.withTenant(new dev.caskeleton.messaging.api.TenantContext("acme"));
|
||||||
|
|
||||||
|
MessageEnvelope<EncodedMessage> delivered = roundTrip(published);
|
||||||
|
|
||||||
|
assertThat(delivered.tenantContext())
|
||||||
|
.as("an AMQP message carries no ambient tenant, so an unwritten tenant is an absent one")
|
||||||
|
.contains(new dev.caskeleton.messaging.api.TenantContext("acme"));
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("the retry attempt survives the trip instead of restarting at one")
|
||||||
|
void theRetryAttemptSurvivesTheTrip() {
|
||||||
|
MessageEnvelope<EncodedMessage> delivered = roundTrip(retryStamped(3));
|
||||||
|
|
||||||
|
assertThat(delivered.headers().find(ReservedHeaders.RETRY_ATTEMPT))
|
||||||
|
.map(HeaderValue::value)
|
||||||
|
.as("an attempt counter that resets on every hop caps nothing")
|
||||||
|
.hasValue("3");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("a retry-stamped envelope can be published to its retry queue")
|
||||||
|
void aRetryStampedEnvelopeCanBePublished() {
|
||||||
|
assertThatCode(() -> headerMapper.toProperties(retryStamped(2)))
|
||||||
|
.as("the platform's own bookkeeping is not message content forging an identity")
|
||||||
|
.doesNotThrowAnyException();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("a header restating the message id is still refused")
|
||||||
|
void aForgedMessageIdIsStillRefused() {
|
||||||
|
MessageEnvelope<EncodedMessage> forged =
|
||||||
|
envelope(
|
||||||
|
MessageHeaders.platform(
|
||||||
|
Map.of(new HeaderName(ReservedHeaders.MESSAGE_ID), new HeaderValue("forged"))));
|
||||||
|
|
||||||
|
assertThatThrownBy(() -> headerMapper.toProperties(forged))
|
||||||
|
.isInstanceOf(MessagingConfigurationException.class);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("identity is read from its field, not duplicated into the header map")
|
||||||
|
void identityIsNotDuplicatedIntoTheHeaderMap() {
|
||||||
|
MessageEnvelope<EncodedMessage> delivered = roundTrip(envelope(MessageHeaders.empty()));
|
||||||
|
|
||||||
|
assertThat(delivered.headers().find(ReservedHeaders.MESSAGE_ID))
|
||||||
|
.as("a copy that can drift from the field gives the same message two identities")
|
||||||
|
.isEmpty();
|
||||||
|
}
|
||||||
|
|
||||||
|
private MessageEnvelope<EncodedMessage> roundTrip(MessageEnvelope<EncodedMessage> published) {
|
||||||
|
MessageProperties properties = headerMapper.toProperties(published);
|
||||||
|
return deliveryMapper.toEnvelope(new Message(published.payload().bytes(), properties));
|
||||||
|
}
|
||||||
|
|
||||||
|
private static MessageEnvelope<EncodedMessage> retryStamped(int attempt) {
|
||||||
|
Map<HeaderName, HeaderValue> headers = new LinkedHashMap<>();
|
||||||
|
headers.put(
|
||||||
|
new HeaderName(ReservedHeaders.RETRY_ATTEMPT), new HeaderValue(Integer.toString(attempt)));
|
||||||
|
headers.put(new HeaderName(ReservedHeaders.LAST_FAILURE_AT), new HeaderValue(NOW.toString()));
|
||||||
|
return envelope(MessageHeaders.platform(headers));
|
||||||
|
}
|
||||||
|
|
||||||
|
private static MessageEnvelope<EncodedMessage> envelope(MessageHeaders headers) {
|
||||||
|
return new MessageEnvelope<>(
|
||||||
|
MessageId.newId(),
|
||||||
|
new MessageType("order.created"),
|
||||||
|
new SchemaVersion(1),
|
||||||
|
NOW,
|
||||||
|
Optional.of(NOW),
|
||||||
|
new ProducerId("order-api"),
|
||||||
|
Optional.of(new CorrelationId("wf-1")),
|
||||||
|
Optional.empty(),
|
||||||
|
ContentType.JSON,
|
||||||
|
Optional.empty(),
|
||||||
|
Optional.empty(),
|
||||||
|
Optional.empty(),
|
||||||
|
TraceContext.none(),
|
||||||
|
headers,
|
||||||
|
new EncodedMessage(
|
||||||
|
"{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8),
|
||||||
|
ContentType.JSON,
|
||||||
|
Optional.empty()));
|
||||||
|
}
|
||||||
|
}
|
||||||
+158
@@ -0,0 +1,158 @@
|
|||||||
|
package dev.caskeleton.messaging.reliability;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.api.CausationId;
|
||||||
|
import dev.caskeleton.messaging.api.CorrelationId;
|
||||||
|
import dev.caskeleton.messaging.api.ProducerId;
|
||||||
|
import dev.caskeleton.messaging.api.TenantContext;
|
||||||
|
import dev.caskeleton.messaging.api.TraceContext;
|
||||||
|
import java.time.Instant;
|
||||||
|
import java.util.Objects;
|
||||||
|
import java.util.Optional;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The envelope facts an outbox row carries in its own columns.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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<ProducerId> producer,
|
||||||
|
Optional<Instant> occurredAt,
|
||||||
|
Optional<CorrelationId> correlationId,
|
||||||
|
Optional<CausationId> causationId,
|
||||||
|
Optional<TenantContext> tenant,
|
||||||
|
Optional<String> partitionKey,
|
||||||
|
Optional<String> orderingKey,
|
||||||
|
Optional<String> schemaSubject,
|
||||||
|
Optional<String> schemaUri,
|
||||||
|
TraceContext traceContext) {
|
||||||
|
|
||||||
|
public OutboxCanonicalMetadata {
|
||||||
|
Objects.requireNonNull(producer, "producer must not be null");
|
||||||
|
Objects.requireNonNull(occurredAt, "occurredAt must not be null");
|
||||||
|
Objects.requireNonNull(correlationId, "correlationId must not be null");
|
||||||
|
Objects.requireNonNull(causationId, "causationId must not be null");
|
||||||
|
Objects.requireNonNull(tenant, "tenant must not be null");
|
||||||
|
Objects.requireNonNull(partitionKey, "partitionKey must not be null");
|
||||||
|
Objects.requireNonNull(orderingKey, "orderingKey must not be null");
|
||||||
|
Objects.requireNonNull(schemaSubject, "schemaSubject must not be null");
|
||||||
|
Objects.requireNonNull(schemaUri, "schemaUri must not be null");
|
||||||
|
Objects.requireNonNull(traceContext, "traceContext must not be null");
|
||||||
|
if (schemaUri.isPresent() && schemaSubject.isEmpty()) {
|
||||||
|
throw new IllegalArgumentException(
|
||||||
|
"a schema location without a subject cannot be resolved; a reader would have a URI and "
|
||||||
|
+ "no way to know what it is a schema for");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Returns the metadata of a row that carries none.
|
||||||
|
*
|
||||||
|
* <p>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);
|
||||||
|
}
|
||||||
|
}
|
||||||
+10
-1
@@ -23,13 +23,19 @@ import java.util.Optional;
|
|||||||
* this row carrying a stable {@code messageId} and the consumer having an Inbox — not from the
|
* this row carrying a stable {@code messageId} and the consumer having an Inbox — not from the
|
||||||
* outbox alone.
|
* outbox alone.
|
||||||
*
|
*
|
||||||
|
* <p>{@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 messageId the stable logical identity, preserved across every retry
|
||||||
* @param destination the logical destination
|
* @param destination the logical destination
|
||||||
* @param messageType the catalog message type
|
* @param messageType the catalog message type
|
||||||
* @param schemaVersion the payload schema revision
|
* @param schemaVersion the payload schema revision
|
||||||
* @param contentType the codec media type
|
* @param contentType the codec media type
|
||||||
* @param payload the encoded payload
|
* @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 createdAt when the business transaction wrote this row
|
||||||
* @param status the current lifecycle state
|
* @param status the current lifecycle state
|
||||||
* @param attempts how many publish attempts have been made
|
* @param attempts how many publish attempts have been made
|
||||||
@@ -45,6 +51,7 @@ public record OutboxRecord(
|
|||||||
ContentType contentType,
|
ContentType contentType,
|
||||||
byte[] payload,
|
byte[] payload,
|
||||||
Map<String, String> headers,
|
Map<String, String> headers,
|
||||||
|
OutboxCanonicalMetadata metadata,
|
||||||
Instant createdAt,
|
Instant createdAt,
|
||||||
OutboxStatus status,
|
OutboxStatus status,
|
||||||
int attempts,
|
int attempts,
|
||||||
@@ -59,6 +66,7 @@ public record OutboxRecord(
|
|||||||
Objects.requireNonNull(contentType, "contentType must not be null");
|
Objects.requireNonNull(contentType, "contentType must not be null");
|
||||||
Objects.requireNonNull(payload, "payload must not be null");
|
Objects.requireNonNull(payload, "payload must not be null");
|
||||||
Objects.requireNonNull(headers, "headers must not be null");
|
Objects.requireNonNull(headers, "headers must not be null");
|
||||||
|
Objects.requireNonNull(metadata, "metadata must not be null");
|
||||||
Objects.requireNonNull(createdAt, "createdAt must not be null");
|
Objects.requireNonNull(createdAt, "createdAt must not be null");
|
||||||
Objects.requireNonNull(status, "status must not be null");
|
Objects.requireNonNull(status, "status must not be null");
|
||||||
Objects.requireNonNull(leaseExpiresAt, "leaseExpiresAt must not be null");
|
Objects.requireNonNull(leaseExpiresAt, "leaseExpiresAt must not be null");
|
||||||
@@ -95,6 +103,7 @@ public record OutboxRecord(
|
|||||||
contentType,
|
contentType,
|
||||||
payload,
|
payload,
|
||||||
headers,
|
headers,
|
||||||
|
metadata,
|
||||||
createdAt,
|
createdAt,
|
||||||
newStatus,
|
newStatus,
|
||||||
newAttempts,
|
newAttempts,
|
||||||
|
|||||||
+78
-25
@@ -182,23 +182,45 @@ public final class DefaultMessagePublisher implements MessagePublisher {
|
|||||||
return rejected("PUBLISH_PREPARATION_FAILED", sanitized(beforeTheWire), startedAt);
|
return rejected("PUBLISH_PREPARATION_FAILED", sanitized(beforeTheWire), startedAt);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
Duration remaining = remainingBudget(options.timeout(), startedAt);
|
||||||
|
if (remaining.isZero() || remaining.isNegative()) {
|
||||||
|
// The budget was spent resolving and encoding, so nothing has been transmitted and the
|
||||||
|
// outcome is still definite. Sending anyway would start a message the caller has already
|
||||||
|
// stopped waiting for.
|
||||||
|
return rejected(
|
||||||
|
"PUBLISH_DEADLINE_EXCEEDED",
|
||||||
|
"the "
|
||||||
|
+ options.timeout().toMillis()
|
||||||
|
+ "ms publish deadline passed before the message reached the transport",
|
||||||
|
startedAt);
|
||||||
|
}
|
||||||
|
|
||||||
admission.admit(destination.name().value(), encoded.payload().bytes().length);
|
admission.admit(destination.name().value(), encoded.payload().bytes().length);
|
||||||
MessagingRuntimeLease lease = null;
|
MessagingRuntimeLease lease = null;
|
||||||
try {
|
try {
|
||||||
lease = runtimes.acquire(profile.broker());
|
lease = runtimes.acquire(profile.broker());
|
||||||
MessagingRuntimeLease held = lease;
|
MessagingRuntimeLease held = lease;
|
||||||
return transport
|
return withDeadline(
|
||||||
.publish(new TransportPublishRequest(profile, encoded, options))
|
transport.publish(new TransportPublishRequest(profile, encoded, options)), remaining)
|
||||||
.<PublishResult>handle(
|
.<PublishResult>handle(
|
||||||
(result, failure) -> {
|
(result, failure) -> {
|
||||||
// One release per acquisition, whatever happened. A permit that leaks on the
|
// One release per acquisition, whatever happened. A permit that leaks on the
|
||||||
// failure path is a limiter that shrinks by one per failure until it accepts
|
// failure path is a limiter that shrinks by one per failure until it accepts
|
||||||
// nothing.
|
// nothing.
|
||||||
held.close();
|
held.close();
|
||||||
admission.complete();
|
admission.complete(destination.name().value());
|
||||||
if (failure != null) {
|
if (failure != null) {
|
||||||
// The request was on the wire when this failed, so the broker may hold it.
|
// The request was on the wire when this failed, so the broker may hold it.
|
||||||
PublishResult ambiguous = ambiguousResult(sanitized(failure), startedAt);
|
PublishResult ambiguous =
|
||||||
|
isDeadline(failure)
|
||||||
|
? ambiguousResult(
|
||||||
|
"PUBLISH_DEADLINE_EXCEEDED",
|
||||||
|
"no broker outcome within the "
|
||||||
|
+ options.timeout().toMillis()
|
||||||
|
+ "ms publish deadline",
|
||||||
|
startedAt)
|
||||||
|
: ambiguousResult(
|
||||||
|
"PUBLISH_OUTCOME_UNKNOWN", sanitized(failure), startedAt);
|
||||||
observe(profile, ambiguous, startedAt);
|
observe(profile, ambiguous, startedAt);
|
||||||
return ambiguous;
|
return ambiguous;
|
||||||
}
|
}
|
||||||
@@ -209,7 +231,7 @@ public final class DefaultMessagePublisher implements MessagePublisher {
|
|||||||
if (lease != null) {
|
if (lease != null) {
|
||||||
lease.close();
|
lease.close();
|
||||||
}
|
}
|
||||||
admission.complete();
|
admission.complete(destination.name().value());
|
||||||
return rejected("PUBLISH_RUNTIME_UNAVAILABLE", sanitized(beforeTheSend), startedAt);
|
return rejected("PUBLISH_RUNTIME_UNAVAILABLE", sanitized(beforeTheSend), startedAt);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -217,22 +239,13 @@ public final class DefaultMessagePublisher implements MessagePublisher {
|
|||||||
/**
|
/**
|
||||||
* Refuses options the destination cannot honour, before anything is encoded or sent.
|
* Refuses options the destination cannot honour, before anything is encoded or sent.
|
||||||
*
|
*
|
||||||
* <p>The transports read {@code request.options()} for nothing: the timeout, the confirmation
|
* <p>The transports accept {@code request.options()} and read nothing from it, so an option this
|
||||||
* requirement, the deduplication request and the broker hints were all accepted and ignored. A
|
* destination cannot honour has to be refused here or it is honoured nowhere. A caller asking for
|
||||||
* caller asking for broker-side deduplication got a publish with no deduplication and no error,
|
* broker-side deduplication got a publish with no deduplication and no error, and then skipped
|
||||||
* and then skipped the idempotency it would otherwise have written — which is exactly the case
|
* the idempotency it would otherwise have written — which is exactly the case {@code
|
||||||
* {@code PublishDeduplication}'s own javadoc says must be a startup failure rather than a silent
|
* PublishDeduplication}'s own javadoc says must be a startup failure rather than a silent no-op.
|
||||||
* no-op.
|
|
||||||
*/
|
*/
|
||||||
private void requireSupportedOptions(DestinationProfile profile, PublishOptions options) {
|
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()
|
if (options.deduplication().isPresent()
|
||||||
&& !transport.capabilities(profile.name()).capabilities().deduplicatedPublish()) {
|
&& !transport.capabilities(profile.name()).capabilities().deduplicatedPublish()) {
|
||||||
throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException(
|
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()))));
|
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(
|
return new PublishResult(
|
||||||
PublishCompletion.AMBIGUOUS,
|
PublishCompletion.AMBIGUOUS,
|
||||||
PublishEvidence.ambiguous(),
|
PublishEvidence.ambiguous(),
|
||||||
@@ -286,11 +299,51 @@ public final class DefaultMessagePublisher implements MessagePublisher {
|
|||||||
elapsedSince(startedAt),
|
elapsedSince(startedAt),
|
||||||
Optional.of(
|
Optional.of(
|
||||||
new FailureDescriptor(
|
new FailureDescriptor(
|
||||||
FailureCategory.AMBIGUOUS,
|
FailureCategory.AMBIGUOUS, code, true, reason, Optional.empty())));
|
||||||
"PUBLISH_OUTCOME_UNKNOWN",
|
}
|
||||||
true,
|
|
||||||
reason,
|
/**
|
||||||
Optional.empty())));
|
* Returns what is left of the caller's deadline.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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<dev.caskeleton.messaging.transport.TransportPublishResult>
|
||||||
|
withDeadline(
|
||||||
|
CompletionStage<dev.caskeleton.messaging.transport.TransportPublishResult> inFlight,
|
||||||
|
Duration remaining) {
|
||||||
|
return inFlight
|
||||||
|
.toCompletableFuture()
|
||||||
|
.copy()
|
||||||
|
.orTimeout(remaining.toMillis(), java.util.concurrent.TimeUnit.MILLISECONDS);
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Reports whether a stage failed because the deadline passed rather than because of a broker. */
|
||||||
|
private static boolean isDeadline(Throwable failure) {
|
||||||
|
Throwable cause =
|
||||||
|
failure instanceof java.util.concurrent.CompletionException && failure.getCause() != null
|
||||||
|
? failure.getCause()
|
||||||
|
: failure;
|
||||||
|
return cause instanceof java.util.concurrent.TimeoutException;
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|||||||
+78
-22
@@ -162,6 +162,66 @@ class DefaultMessagePublisherTest {
|
|||||||
assertThat(admission.inFlight()).isZero();
|
assertThat(admission.inFlight()).isZero();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("a broker that never answers is ambiguous at the caller's deadline")
|
||||||
|
void aStalledBrokerIsAmbiguousAtTheDeadline() {
|
||||||
|
transport.stall();
|
||||||
|
|
||||||
|
CompletableFuture<PublishResult> pending =
|
||||||
|
publisher(allowOrders())
|
||||||
|
.publish(
|
||||||
|
new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class),
|
||||||
|
envelope(),
|
||||||
|
withTimeout(Duration.ofMillis(120)))
|
||||||
|
.toCompletableFuture();
|
||||||
|
|
||||||
|
// Bounded rather than joined: with no deadline of its own this stage never completes, and a
|
||||||
|
// test that waits forever reports a hang instead of the missing deadline.
|
||||||
|
assertThat(pending).succeedsWithin(Duration.ofSeconds(5));
|
||||||
|
PublishResult result = pending.join();
|
||||||
|
|
||||||
|
assertThat(result.completion())
|
||||||
|
.as("the message reached the transport, so the broker may hold it")
|
||||||
|
.isEqualTo(PublishCompletion.AMBIGUOUS);
|
||||||
|
assertThat(result.failure().orElseThrow().code()).isEqualTo("PUBLISH_DEADLINE_EXCEEDED");
|
||||||
|
assertThat(admission.inFlight())
|
||||||
|
.as("a permit held until a stalled broker answers is a permit never returned")
|
||||||
|
.isZero();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("a deadline spent before the send rejects instead of publishing")
|
||||||
|
void aDeadlineSpentBeforeTheSendRejects() {
|
||||||
|
// Preparation is inside the deadline, not before it: resolution and encoding spend the same
|
||||||
|
// budget the broker wait does.
|
||||||
|
AtomicInteger reads = new AtomicInteger();
|
||||||
|
DefaultMessagePublisher publisher =
|
||||||
|
new DefaultMessagePublisher(
|
||||||
|
registry(),
|
||||||
|
allowOrders(),
|
||||||
|
new SingleCodecRegistry(),
|
||||||
|
admission,
|
||||||
|
new FixedRuntimeRegistry(transport),
|
||||||
|
transport,
|
||||||
|
() -> Duration.ofSeconds(6L * reads.getAndIncrement()).toNanos());
|
||||||
|
|
||||||
|
PublishResult result =
|
||||||
|
publisher
|
||||||
|
.publish(
|
||||||
|
new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class),
|
||||||
|
envelope(),
|
||||||
|
withTimeout(Duration.ofSeconds(5)))
|
||||||
|
.toCompletableFuture()
|
||||||
|
.join();
|
||||||
|
|
||||||
|
assertThat(result.completion())
|
||||||
|
.as("nothing was transmitted, so the outcome is definite")
|
||||||
|
.isEqualTo(PublishCompletion.REJECTED);
|
||||||
|
assertThat(result.failure().orElseThrow().code()).isEqualTo("PUBLISH_DEADLINE_EXCEEDED");
|
||||||
|
assertThat(transport.published()).isZero();
|
||||||
|
assertThat(admission.inFlight()).isZero();
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
@DisplayName("an unavailable runtime releases the permit it took")
|
@DisplayName("an unavailable runtime releases the permit it took")
|
||||||
void anUnavailableRuntimeReleasesThePermit() {
|
void anUnavailableRuntimeReleasesThePermit() {
|
||||||
@@ -262,8 +322,7 @@ class DefaultMessagePublisherTest {
|
|||||||
.REPLICATION_OR_PERSISTENCE_ACK,
|
.REPLICATION_OR_PERSISTENCE_ACK,
|
||||||
java.util.Optional.of(
|
java.util.Optional.of(
|
||||||
new dev.caskeleton.messaging.api.publish.PublishDeduplication(
|
new dev.caskeleton.messaging.api.publish.PublishDeduplication(
|
||||||
"order-1", java.time.Duration.ofMinutes(5))),
|
"order-1", java.time.Duration.ofMinutes(5)))))
|
||||||
Map.of()))
|
|
||||||
.toCompletableFuture()
|
.toCompletableFuture()
|
||||||
.join();
|
.join();
|
||||||
|
|
||||||
@@ -273,26 +332,12 @@ class DefaultMessagePublisherTest {
|
|||||||
assertThat(transport.published()).isZero();
|
assertThat(transport.published()).isZero();
|
||||||
}
|
}
|
||||||
|
|
||||||
@Test
|
private static PublishOptions withTimeout(Duration timeout) {
|
||||||
@DisplayName("M3 broker hints are refused on the M1 path")
|
return new PublishOptions(
|
||||||
void brokerHintsAreRefused() {
|
timeout,
|
||||||
PublishResult result =
|
dev.caskeleton.messaging.api.destination.ConfirmationRequirement
|
||||||
publisher(allowOrders())
|
.REPLICATION_OR_PERSISTENCE_ACK,
|
||||||
.publish(
|
Optional.empty());
|
||||||
new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class),
|
|
||||||
envelope(),
|
|
||||||
new PublishOptions(
|
|
||||||
java.time.Duration.ofSeconds(5),
|
|
||||||
dev.caskeleton.messaging.api.destination.ConfirmationRequirement
|
|
||||||
.REPLICATION_OR_PERSISTENCE_ACK,
|
|
||||||
java.util.Optional.empty(),
|
|
||||||
Map.of("linger.ms", "50")))
|
|
||||||
.toCompletableFuture()
|
|
||||||
.join();
|
|
||||||
|
|
||||||
assertThat(result.completion())
|
|
||||||
.as("isM1Compatible existed and nothing ever called it")
|
|
||||||
.isEqualTo(PublishCompletion.REJECTED);
|
|
||||||
}
|
}
|
||||||
|
|
||||||
private static DestinationAccessPolicy allowOrders() {
|
private static DestinationAccessPolicy allowOrders() {
|
||||||
@@ -384,15 +429,26 @@ class DefaultMessagePublisherTest {
|
|||||||
|
|
||||||
private RuntimeException failure;
|
private RuntimeException failure;
|
||||||
|
|
||||||
|
private boolean stalled;
|
||||||
|
|
||||||
private void failWith(RuntimeException failure) {
|
private void failWith(RuntimeException failure) {
|
||||||
this.failure = failure;
|
this.failure = failure;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/** A broker that took the message and never says what happened to it. */
|
||||||
|
private void stall() {
|
||||||
|
this.stalled = true;
|
||||||
|
}
|
||||||
|
|
||||||
@Override
|
@Override
|
||||||
public CompletionStage<TransportPublishResult> publish(TransportPublishRequest request) {
|
public CompletionStage<TransportPublishResult> publish(TransportPublishRequest request) {
|
||||||
if (failure != null) {
|
if (failure != null) {
|
||||||
return CompletableFuture.failedFuture(failure);
|
return CompletableFuture.failedFuture(failure);
|
||||||
}
|
}
|
||||||
|
if (stalled) {
|
||||||
|
published.incrementAndGet();
|
||||||
|
return new CompletableFuture<>();
|
||||||
|
}
|
||||||
published.incrementAndGet();
|
published.incrementAndGet();
|
||||||
return CompletableFuture.completedFuture(
|
return CompletableFuture.completedFuture(
|
||||||
new TransportPublishResult(
|
new TransportPublishResult(
|
||||||
|
|||||||
@@ -4,5 +4,8 @@ dependencies {
|
|||||||
api project(':messaging:messaging-core-api')
|
api project(':messaging:messaging-core-api')
|
||||||
api project(':messaging:messaging-schema-api')
|
api project(':messaging:messaging-schema-api')
|
||||||
|
|
||||||
implementation 'org.apache.avro:avro:1.12.0'
|
// api: AvroMessageCodec's constructors take a registry of org.apache.avro.Schema and
|
||||||
|
// AvroCompatibilityGate.check takes and compares them. A consumer cannot build that
|
||||||
|
// registry without naming the type, so hiding the dependency only stops them compiling.
|
||||||
|
api 'org.apache.avro:avro:1.12.0'
|
||||||
}
|
}
|
||||||
|
|||||||
+40
-2
@@ -157,11 +157,14 @@ public final class AvroMessageCodec implements MessageCodec {
|
|||||||
"the Avro codec decodes into GenericRecord, not " + payloadType.getSimpleName());
|
"the Avro codec decodes into GenericRecord, not " + payloadType.getSimpleName());
|
||||||
}
|
}
|
||||||
|
|
||||||
DatumReader<GenericRecord> reader = new GenericDatumReader<>(writerSchema, writerSchema);
|
DatumReader<GenericRecord> reader = boundedReader(writerSchema, writerSchema);
|
||||||
BinaryDecoder decoder = DecoderFactory.get().binaryDecoder(encoded, null);
|
BinaryDecoder decoder = DecoderFactory.get().binaryDecoder(encoded, null);
|
||||||
try {
|
try {
|
||||||
return payloadType.cast(reader.read(null, decoder));
|
return payloadType.cast(reader.read(null, decoder));
|
||||||
} catch (IOException | RuntimeException failure) {
|
} catch (IOException | RuntimeException failure) {
|
||||||
|
if (failure instanceof MessageTooLargeException tooLarge) {
|
||||||
|
throw tooLarge;
|
||||||
|
}
|
||||||
throw new MessageSerializationException(
|
throw new MessageSerializationException(
|
||||||
"AVRO_DECODE_FAILED",
|
"AVRO_DECODE_FAILED",
|
||||||
"the payload could not be decoded against the registered schema",
|
"the payload could not be decoded against the registered schema",
|
||||||
@@ -200,11 +203,14 @@ public final class AvroMessageCodec implements MessageCodec {
|
|||||||
Schema writerSchema = schemaFor(type, writerVersion);
|
Schema writerSchema = schemaFor(type, writerVersion);
|
||||||
Schema readerSchema = schemaFor(type, readerVersion);
|
Schema readerSchema = schemaFor(type, readerVersion);
|
||||||
|
|
||||||
DatumReader<GenericRecord> reader = new GenericDatumReader<>(writerSchema, readerSchema);
|
DatumReader<GenericRecord> reader = boundedReader(writerSchema, readerSchema);
|
||||||
BinaryDecoder decoder = DecoderFactory.get().binaryDecoder(encoded, null);
|
BinaryDecoder decoder = DecoderFactory.get().binaryDecoder(encoded, null);
|
||||||
try {
|
try {
|
||||||
return reader.read(null, decoder);
|
return reader.read(null, decoder);
|
||||||
} catch (IOException | RuntimeException failure) {
|
} catch (IOException | RuntimeException failure) {
|
||||||
|
if (failure instanceof MessageTooLargeException tooLarge) {
|
||||||
|
throw tooLarge;
|
||||||
|
}
|
||||||
throw new MessageSerializationException(
|
throw new MessageSerializationException(
|
||||||
"AVRO_EVOLUTION_FAILED",
|
"AVRO_EVOLUTION_FAILED",
|
||||||
"v%d bytes could not be resolved against the v%d reader schema"
|
"v%d bytes could not be resolved against the v%d reader schema"
|
||||||
@@ -213,6 +219,38 @@ public final class AvroMessageCodec implements MessageCodec {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Builds a reader that will not allocate an array the input could not possibly fill.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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<GenericRecord> boundedReader(Schema writerSchema, Schema readerSchema) {
|
||||||
|
int maxElements = maxBytes;
|
||||||
|
return new GenericDatumReader<>(writerSchema, readerSchema) {
|
||||||
|
@Override
|
||||||
|
protected Object newArray(Object old, int size, Schema schema) {
|
||||||
|
if (size > maxElements) {
|
||||||
|
throw new MessageTooLargeException(
|
||||||
|
"AVRO_COLLECTION_TOO_LARGE",
|
||||||
|
("the payload declares an array of %d elements, which %d bytes cannot contain; the"
|
||||||
|
+ " claim was refused before the array was allocated")
|
||||||
|
.formatted(size, maxElements));
|
||||||
|
}
|
||||||
|
return super.newArray(old, size, schema);
|
||||||
|
}
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
private Schema schemaFor(MessageType type, SchemaVersion version) {
|
private Schema schemaFor(MessageType type, SchemaVersion version) {
|
||||||
Objects.requireNonNull(type, "type must not be null");
|
Objects.requireNonNull(type, "type must not be null");
|
||||||
Objects.requireNonNull(version, "version must not be null");
|
Objects.requireNonNull(version, "version must not be null");
|
||||||
|
|||||||
+134
@@ -0,0 +1,134 @@
|
|||||||
|
package dev.caskeleton.messaging.schema.avro;
|
||||||
|
|
||||||
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.api.MessageType;
|
||||||
|
import dev.caskeleton.messaging.api.SchemaVersion;
|
||||||
|
import dev.caskeleton.messaging.api.error.MessageSerializationException;
|
||||||
|
import dev.caskeleton.messaging.api.error.MessageTooLargeException;
|
||||||
|
import java.io.ByteArrayOutputStream;
|
||||||
|
import java.util.List;
|
||||||
|
import java.util.Map;
|
||||||
|
import org.apache.avro.Schema;
|
||||||
|
import org.apache.avro.generic.GenericData;
|
||||||
|
import org.apache.avro.generic.GenericRecord;
|
||||||
|
import org.junit.jupiter.api.DisplayName;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* What a hostile Avro payload can make the decoder allocate.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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();
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -4,5 +4,7 @@ dependencies {
|
|||||||
api project(':messaging:messaging-core-api')
|
api project(':messaging:messaging-core-api')
|
||||||
api project(':messaging:messaging-schema-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'
|
||||||
}
|
}
|
||||||
|
|||||||
+14
@@ -15,6 +15,7 @@ import com.google.protobuf.Parser;
|
|||||||
import dev.caskeleton.messaging.api.ContentType;
|
import dev.caskeleton.messaging.api.ContentType;
|
||||||
import dev.caskeleton.messaging.api.MessageType;
|
import dev.caskeleton.messaging.api.MessageType;
|
||||||
import dev.caskeleton.messaging.api.SchemaVersion;
|
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.MessageTooLargeException;
|
||||||
import dev.caskeleton.messaging.api.error.MessageValidationException;
|
import dev.caskeleton.messaging.api.error.MessageValidationException;
|
||||||
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
|
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
|
||||||
@@ -231,6 +232,19 @@ class ProtobufCompatibilityTest {
|
|||||||
assertThat(codec.encode(ORDER_CREATED, V1, v1Message()).bytes()).hasSize(exact);
|
assertThat(codec.encode(ORDER_CREATED, V1, v1Message()).bytes()).hasSize(exact);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aLengthPrefixNoPayloadOfThisSizeCouldHonourIsADecodeFailure() {
|
||||||
|
ProtobufMessageCodec codec = codec(V1_DESCRIPTOR);
|
||||||
|
// Tag 1, wire type 2 (length-delimited), then a varint claiming four hundred million bytes
|
||||||
|
// follow. The whole message is six bytes, so it passes the size limit; what must not happen is
|
||||||
|
// the parser reserving the claimed length before discovering there is nothing behind it.
|
||||||
|
byte[] hostile = {0x0A, (byte) 0x80, (byte) 0x88, (byte) 0xDE, (byte) 0xBE, 0x01};
|
||||||
|
|
||||||
|
assertThatThrownBy(() -> codec.decode(ORDER_CREATED, V1, hostile, DynamicMessage.class))
|
||||||
|
.isInstanceOf(MessageSerializationException.class)
|
||||||
|
.hasMessageContaining("protobuf");
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
void theEncodedMessageCarriesItsSchemaReference() {
|
void theEncodedMessageCarriesItsSchemaReference() {
|
||||||
EncodedMessage encoded = codec(V1_DESCRIPTOR, V2).encode(ORDER_CREATED, V2, v1Message());
|
EncodedMessage encoded = codec(V1_DESCRIPTOR, V2).encode(ORDER_CREATED, V2, v1Message());
|
||||||
|
|||||||
@@ -41,11 +41,18 @@ dependencies {
|
|||||||
annotationProcessor 'org.springframework.boot:spring-boot-configuration-processor'
|
annotationProcessor 'org.springframework.boot:spring-boot-configuration-processor'
|
||||||
|
|
||||||
// The Reactor facade lives here, not in core-api: the core contract stays CompletionStage so
|
// 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.
|
// that a service which does not use Reactor never inherits it. api, because
|
||||||
implementation 'io.projectreactor:reactor-core'
|
// 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 'io.projectreactor:reactor-test'
|
||||||
testImplementation 'org.springframework.boot:spring-boot-test'
|
testImplementation 'org.springframework.boot:spring-boot-test'
|
||||||
testImplementation 'org.springframework:spring-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
|
// 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,
|
// 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
|
// so the proof has to run somewhere — and the starter is where the whole platform
|
||||||
|
|||||||
@@ -137,6 +137,7 @@ org.testcontainers:testcontainers-kafka:2.0.2=testCompileClasspath,testRuntimeCl
|
|||||||
org.testcontainers:testcontainers:2.0.2=testCompileClasspath,testRuntimeClasspath
|
org.testcontainers:testcontainers:2.0.2=testCompileClasspath,testRuntimeClasspath
|
||||||
org.xerial.snappy:snappy-java:1.1.10.7=runtimeClasspath,testRuntimeClasspath
|
org.xerial.snappy:snappy-java:1.1.10.7=runtimeClasspath,testRuntimeClasspath
|
||||||
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
|
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-core:3.0.2=runtimeClasspath,testRuntimeClasspath
|
||||||
tools.jackson.core:jackson-databind:3.0.2=runtimeClasspath,testRuntimeClasspath
|
tools.jackson.core:jackson-databind:3.0.2=runtimeClasspath,testRuntimeClasspath
|
||||||
tools.jackson:jackson-bom:3.0.2=runtimeClasspath,testRuntimeClasspath
|
tools.jackson:jackson-bom:3.0.2=runtimeClasspath,testRuntimeClasspath
|
||||||
|
|||||||
+50
@@ -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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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<String> publishable,
|
||||||
|
@DefaultValue List<String> consumable,
|
||||||
|
@DefaultValue List<String> administrable) {}
|
||||||
|
}
|
||||||
+69
@@ -0,0 +1,69 @@
|
|||||||
|
package dev.caskeleton.messaging.autoconfigure;
|
||||||
|
|
||||||
|
import java.time.Duration;
|
||||||
|
import java.util.List;
|
||||||
|
import org.springframework.boot.context.properties.bind.DefaultValue;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* One entry of {@code app.messaging.brokers}.
|
||||||
|
*
|
||||||
|
* <p>Both broker families are described by one record because a deployment names its brokers in one
|
||||||
|
* map, and a reader of that map should not have to know which half of the fields apply. Which half
|
||||||
|
* does apply is decided by {@link #type()}, and the compiler refuses a field belonging to the other
|
||||||
|
* family rather than ignoring it — a Kafka broker carrying {@code prefetch} is a configuration the
|
||||||
|
* author believed was doing something.
|
||||||
|
*
|
||||||
|
* <p>{@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<String> bootstrapServers,
|
||||||
|
@DefaultValue("true") boolean enableIdempotence,
|
||||||
|
@DefaultValue("all") String acks,
|
||||||
|
@DefaultValue("5") int maxInFlightRequestsPerConnection,
|
||||||
|
@DefaultValue("30s") Duration deliveryTimeout,
|
||||||
|
@DefaultValue("false") boolean enableAutoCommit,
|
||||||
|
@DefaultValue("") String consumerGroup,
|
||||||
|
@DefaultValue List<String> addresses,
|
||||||
|
@DefaultValue("true") boolean publisherConfirms,
|
||||||
|
@DefaultValue("true") boolean publisherReturns,
|
||||||
|
@DefaultValue("true") boolean mandatory,
|
||||||
|
@DefaultValue("5s") Duration confirmTimeout,
|
||||||
|
@DefaultValue("false") boolean autoAck,
|
||||||
|
@DefaultValue("16") int prefetch,
|
||||||
|
@DefaultValue("true") boolean quorumQueues) {
|
||||||
|
|
||||||
|
/** The broker family a Kafka entry declares. */
|
||||||
|
public static final String KAFKA = "kafka";
|
||||||
|
|
||||||
|
/** The broker family a RabbitMQ entry declares. */
|
||||||
|
public static final String RABBITMQ = "rabbitmq";
|
||||||
|
}
|
||||||
+53
@@ -0,0 +1,53 @@
|
|||||||
|
package dev.caskeleton.messaging.autoconfigure;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.kafka.KafkaBrokerProfile;
|
||||||
|
import dev.caskeleton.messaging.policy.DestinationProfile;
|
||||||
|
import dev.caskeleton.messaging.rabbit.RabbitBrokerProfile;
|
||||||
|
import dev.caskeleton.messaging.security.BrokerSecurityProfile;
|
||||||
|
import java.util.List;
|
||||||
|
import java.util.Objects;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* What the documented configuration compiles to.
|
||||||
|
*
|
||||||
|
* <p>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<DestinationProfile> destinations,
|
||||||
|
List<KafkaBrokerProfile> kafkaBrokers,
|
||||||
|
List<RabbitBrokerProfile> rabbitBrokers,
|
||||||
|
List<BrokerSecurityProfile> security) {
|
||||||
|
|
||||||
|
public CompiledMessagingConfiguration {
|
||||||
|
Objects.requireNonNull(destinations, "destinations must not be null");
|
||||||
|
Objects.requireNonNull(kafkaBrokers, "kafkaBrokers must not be null");
|
||||||
|
Objects.requireNonNull(rabbitBrokers, "rabbitBrokers must not be null");
|
||||||
|
Objects.requireNonNull(security, "security must not be null");
|
||||||
|
destinations = List.copyOf(destinations);
|
||||||
|
kafkaBrokers = List.copyOf(kafkaBrokers);
|
||||||
|
rabbitBrokers = List.copyOf(rabbitBrokers);
|
||||||
|
security = List.copyOf(security);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Returns the result of compiling a deployment that configured nothing.
|
||||||
|
*
|
||||||
|
* <p>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());
|
||||||
|
}
|
||||||
|
}
|
||||||
+177
@@ -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}.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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<String> messageTypes) {}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* What the destination promises about delivery and order.
|
||||||
|
*
|
||||||
|
* @param delivery the broker-level delivery guarantee
|
||||||
|
* @param ordering the scope inside which order holds
|
||||||
|
* @param externalSideEffect how handler side effects are protected
|
||||||
|
*/
|
||||||
|
public record Guarantees(
|
||||||
|
@DefaultValue("AT_LEAST_ONCE") DeliveryGuarantee delivery,
|
||||||
|
@DefaultValue("NONE") OrderingScope ordering,
|
||||||
|
@DefaultValue("IDEMPOTENCY_REQUIRED") ExternalSideEffectGuarantee externalSideEffect) {}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The producer contract.
|
||||||
|
*
|
||||||
|
* @param confirmation the confirmation strength this destination demands
|
||||||
|
* @param timeout the publish deadline
|
||||||
|
* @param mandatoryRouting whether the broker must report unroutable publishes
|
||||||
|
* @param idempotent whether producer-side duplicate suppression is required
|
||||||
|
*/
|
||||||
|
public record Producer(
|
||||||
|
@DefaultValue("REPLICATION_OR_PERSISTENCE_ACK") ConfirmationRequirement confirmation,
|
||||||
|
@DefaultValue("5s") Duration timeout,
|
||||||
|
@DefaultValue("true") boolean mandatoryRouting,
|
||||||
|
@DefaultValue("true") boolean idempotent) {}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The consumer contract.
|
||||||
|
*
|
||||||
|
* @param group the consumer group, where the broker has one
|
||||||
|
* @param concurrency how many deliveries may be processed at once
|
||||||
|
* @param maxInFlightPerOrderingUnit the in-flight ceiling inside one ordering unit
|
||||||
|
* @param prefetch the broker prefetch window
|
||||||
|
* @param handlerTimeout the handler deadline
|
||||||
|
* @param manualSettlement whether this destination uses the M2 manual settlement tier
|
||||||
|
*/
|
||||||
|
public record Consumer(
|
||||||
|
String group,
|
||||||
|
@DefaultValue("1") int concurrency,
|
||||||
|
@DefaultValue("1") int maxInFlightPerOrderingUnit,
|
||||||
|
@DefaultValue("16") int prefetch,
|
||||||
|
@DefaultValue("30s") Duration handlerTimeout,
|
||||||
|
@DefaultValue("false") boolean manualSettlement) {}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The retry contract, off by default.
|
||||||
|
*
|
||||||
|
* @param mode how the retry is carried out
|
||||||
|
* @param maxAttempts total attempts including the first delivery
|
||||||
|
* @param initialDelay the first backoff interval
|
||||||
|
* @param maxDelay the backoff ceiling
|
||||||
|
* @param multiplier the exponential backoff factor
|
||||||
|
* @param jitter whether to randomise the backoff
|
||||||
|
* @param orderingImpact what this policy is allowed to do to order
|
||||||
|
* @param destination the destination messages are re-published to, when the mode uses one
|
||||||
|
*/
|
||||||
|
public record Retry(
|
||||||
|
@DefaultValue("NONE") RetryMode mode,
|
||||||
|
@DefaultValue("1") int maxAttempts,
|
||||||
|
@DefaultValue("0s") Duration initialDelay,
|
||||||
|
@DefaultValue("0s") Duration maxDelay,
|
||||||
|
@DefaultValue("1.0") double multiplier,
|
||||||
|
@DefaultValue("false") boolean jitter,
|
||||||
|
@DefaultValue("PRESERVE") OrderingImpact orderingImpact,
|
||||||
|
String destination) {}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Where permanently failed messages go.
|
||||||
|
*
|
||||||
|
* @param destination the dead letter destination; absent means dead lettering is off
|
||||||
|
* @param maxRedriveCount how many times a message may be redriven back
|
||||||
|
*/
|
||||||
|
public record Dlq(String destination, @DefaultValue("1") int maxRedriveCount) {}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The size contract.
|
||||||
|
*
|
||||||
|
* @param maxBytes the encoded payload ceiling for this destination
|
||||||
|
* @param claimCheckThresholdBytes the size above which payloads are offloaded
|
||||||
|
*/
|
||||||
|
public record Payload(
|
||||||
|
@DefaultValue("1048576") int maxBytes,
|
||||||
|
@DefaultValue("1048576") int claimCheckThresholdBytes) {}
|
||||||
|
}
|
||||||
+23
@@ -6,6 +6,7 @@ import dev.caskeleton.messaging.kafka.KafkaSecurityConfigurer;
|
|||||||
import dev.caskeleton.messaging.kafka.KafkaTransactionProfileValidator;
|
import dev.caskeleton.messaging.kafka.KafkaTransactionProfileValidator;
|
||||||
import dev.caskeleton.messaging.security.BrokerTlsPolicy;
|
import dev.caskeleton.messaging.security.BrokerTlsPolicy;
|
||||||
import dev.caskeleton.messaging.security.CredentialRuntimeRegistry;
|
import dev.caskeleton.messaging.security.CredentialRuntimeRegistry;
|
||||||
|
import org.springframework.beans.factory.ObjectProvider;
|
||||||
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
|
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
|
||||||
import org.springframework.context.annotation.Bean;
|
import org.springframework.context.annotation.Bean;
|
||||||
import org.springframework.context.annotation.Configuration;
|
import org.springframework.context.annotation.Configuration;
|
||||||
@@ -41,6 +42,28 @@ public class KafkaMessagingAutoConfiguration {
|
|||||||
return new KafkaProfileValidator();
|
return new KafkaProfileValidator();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Runs the Kafka profile validator over every Kafka broker profile, declared or configured.
|
||||||
|
*
|
||||||
|
* @param profiles the broker profiles the application declared as beans
|
||||||
|
* @param compiled the broker profiles compiled from {@code app.messaging.brokers}
|
||||||
|
* @param validator the Kafka profile validator
|
||||||
|
* @return the startup validation
|
||||||
|
*/
|
||||||
|
@Bean
|
||||||
|
public StartupProfileValidation<dev.caskeleton.messaging.kafka.KafkaBrokerProfile>
|
||||||
|
kafkaProfileStartupValidation(
|
||||||
|
ObjectProvider<dev.caskeleton.messaging.kafka.KafkaBrokerProfile> profiles,
|
||||||
|
CompiledMessagingConfiguration compiled,
|
||||||
|
KafkaProfileValidator validator) {
|
||||||
|
return new StartupProfileValidation<>(
|
||||||
|
() ->
|
||||||
|
java.util.stream.Stream.concat(
|
||||||
|
compiled.kafkaBrokers().stream(), profiles.orderedStream())
|
||||||
|
.toList(),
|
||||||
|
validator::validate);
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns the Kafka transaction profile validator.
|
* Returns the Kafka transaction profile validator.
|
||||||
*
|
*
|
||||||
|
|||||||
+331
@@ -0,0 +1,331 @@
|
|||||||
|
package dev.caskeleton.messaging.autoconfigure;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.api.ContentType;
|
||||||
|
import dev.caskeleton.messaging.api.MessageType;
|
||||||
|
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||||
|
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
|
||||||
|
import dev.caskeleton.messaging.kafka.KafkaBrokerProfile;
|
||||||
|
import dev.caskeleton.messaging.policy.ConsumerPolicy;
|
||||||
|
import dev.caskeleton.messaging.policy.DeadLetterPolicy;
|
||||||
|
import dev.caskeleton.messaging.policy.DestinationProfile;
|
||||||
|
import dev.caskeleton.messaging.policy.PayloadPolicy;
|
||||||
|
import dev.caskeleton.messaging.policy.PhysicalDestination;
|
||||||
|
import dev.caskeleton.messaging.policy.ProducerPolicy;
|
||||||
|
import dev.caskeleton.messaging.policy.RetryPolicy;
|
||||||
|
import dev.caskeleton.messaging.policy.SchemaPolicy;
|
||||||
|
import dev.caskeleton.messaging.rabbit.RabbitBrokerProfile;
|
||||||
|
import dev.caskeleton.messaging.security.BrokerCredentialProfile;
|
||||||
|
import dev.caskeleton.messaging.security.BrokerSecurityProfile;
|
||||||
|
import dev.caskeleton.messaging.security.DestinationAccessPolicy;
|
||||||
|
import java.util.ArrayList;
|
||||||
|
import java.util.LinkedHashSet;
|
||||||
|
import java.util.List;
|
||||||
|
import java.util.Locale;
|
||||||
|
import java.util.Map;
|
||||||
|
import java.util.Objects;
|
||||||
|
import java.util.Optional;
|
||||||
|
import java.util.Set;
|
||||||
|
import java.util.function.Supplier;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Turns the documented configuration into the objects the platform already validates.
|
||||||
|
*
|
||||||
|
* <p>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".
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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<String, BrokerSettings> brokers = settings.getBrokers();
|
||||||
|
List<KafkaBrokerProfile> kafka = new ArrayList<>();
|
||||||
|
List<RabbitBrokerProfile> rabbit = new ArrayList<>();
|
||||||
|
brokers.forEach(
|
||||||
|
(name, broker) -> {
|
||||||
|
switch (familyOf(name, broker)) {
|
||||||
|
case BrokerSettings.KAFKA -> kafka.add(toKafkaProfile(name, broker));
|
||||||
|
case BrokerSettings.RABBITMQ -> rabbit.add(toRabbitProfile(name, broker));
|
||||||
|
default ->
|
||||||
|
throw configurationError(
|
||||||
|
key("brokers", name, "type"),
|
||||||
|
"'%s' is not a broker family this platform binds; use '%s' or '%s'"
|
||||||
|
.formatted(broker.type(), BrokerSettings.KAFKA, BrokerSettings.RABBITMQ));
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
List<DestinationProfile> destinations = new ArrayList<>();
|
||||||
|
settings
|
||||||
|
.getDestinations()
|
||||||
|
.forEach((name, destination) -> destinations.add(toProfile(name, destination, brokers)));
|
||||||
|
|
||||||
|
List<BrokerSecurityProfile> security = new ArrayList<>();
|
||||||
|
settings
|
||||||
|
.getSecurity()
|
||||||
|
.forEach((name, entry) -> security.add(toSecurityProfile(name, entry, brokers)));
|
||||||
|
|
||||||
|
return new CompiledMessagingConfiguration(destinations, kafka, rabbit, security);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static String familyOf(String name, BrokerSettings broker) {
|
||||||
|
if (broker.type() == null || broker.type().isBlank()) {
|
||||||
|
throw configurationError(
|
||||||
|
key("brokers", name, "type"),
|
||||||
|
"a broker entry must declare its family; without one the platform cannot tell which of "
|
||||||
|
+ "its settings apply, and would apply none of them");
|
||||||
|
}
|
||||||
|
return broker.type().toLowerCase(Locale.ROOT);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static KafkaBrokerProfile toKafkaProfile(String name, BrokerSettings broker) {
|
||||||
|
if (broker.bootstrapServers().isEmpty()) {
|
||||||
|
throw configurationError(
|
||||||
|
key("brokers", name, "bootstrap-servers"),
|
||||||
|
"a Kafka broker needs at least one address; a client with none defaults to "
|
||||||
|
+ "localhost:9092 and fails at the first publish rather than at startup");
|
||||||
|
}
|
||||||
|
return new KafkaBrokerProfile(
|
||||||
|
name,
|
||||||
|
broker.stable(),
|
||||||
|
broker.production(),
|
||||||
|
broker.bootstrapServers(),
|
||||||
|
broker.enableIdempotence(),
|
||||||
|
broker.acks(),
|
||||||
|
broker.maxInFlightRequestsPerConnection(),
|
||||||
|
broker.deliveryTimeout(),
|
||||||
|
broker.enableAutoCommit(),
|
||||||
|
broker.consumerGroup(),
|
||||||
|
broker.tlsEnabled(),
|
||||||
|
broker.authenticationEnabled());
|
||||||
|
}
|
||||||
|
|
||||||
|
private static RabbitBrokerProfile toRabbitProfile(String name, BrokerSettings broker) {
|
||||||
|
if (broker.addresses().isEmpty()) {
|
||||||
|
throw configurationError(
|
||||||
|
key("brokers", name, "addresses"),
|
||||||
|
"a RabbitMQ broker needs at least one address; a client with none defaults to "
|
||||||
|
+ "localhost and connects as guest");
|
||||||
|
}
|
||||||
|
return new RabbitBrokerProfile(
|
||||||
|
name,
|
||||||
|
broker.stable(),
|
||||||
|
broker.production(),
|
||||||
|
broker.addresses(),
|
||||||
|
broker.publisherConfirms(),
|
||||||
|
broker.publisherReturns(),
|
||||||
|
broker.mandatory(),
|
||||||
|
broker.confirmTimeout(),
|
||||||
|
broker.autoAck(),
|
||||||
|
broker.prefetch(),
|
||||||
|
broker.quorumQueues(),
|
||||||
|
broker.tlsEnabled(),
|
||||||
|
broker.authenticationEnabled());
|
||||||
|
}
|
||||||
|
|
||||||
|
private DestinationProfile toProfile(
|
||||||
|
String name, DestinationSettings settings, Map<String, BrokerSettings> brokers) {
|
||||||
|
if (settings.broker() == null || settings.broker().isBlank()) {
|
||||||
|
throw configurationError(
|
||||||
|
key("destinations", name, "broker"), "a destination must name the broker it binds to");
|
||||||
|
}
|
||||||
|
if (!brokers.containsKey(settings.broker())) {
|
||||||
|
throw configurationError(
|
||||||
|
key("destinations", name, "broker"),
|
||||||
|
"'%s' is not a configured broker; declared brokers are %s"
|
||||||
|
.formatted(settings.broker(), brokers.keySet()));
|
||||||
|
}
|
||||||
|
if (settings.kind() == null) {
|
||||||
|
throw configurationError(
|
||||||
|
key("destinations", name, "kind"),
|
||||||
|
"a destination must declare its interaction pattern; the platform's retry, ordering and "
|
||||||
|
+ "dead letter rules all read it");
|
||||||
|
}
|
||||||
|
|
||||||
|
return new DestinationProfile(
|
||||||
|
new DestinationName(name),
|
||||||
|
settings.broker(),
|
||||||
|
settings.kind(),
|
||||||
|
physical(name, settings.physical()),
|
||||||
|
schema(name, settings.schema()),
|
||||||
|
settings.guarantees().delivery(),
|
||||||
|
settings.guarantees().ordering(),
|
||||||
|
settings.guarantees().externalSideEffect(),
|
||||||
|
new ProducerPolicy(
|
||||||
|
settings.producer().confirmation(),
|
||||||
|
settings.producer().timeout(),
|
||||||
|
settings.producer().mandatoryRouting(),
|
||||||
|
settings.producer().idempotent()),
|
||||||
|
new ConsumerPolicy(
|
||||||
|
Optional.ofNullable(blankToNull(settings.consumer().group())),
|
||||||
|
settings.consumer().concurrency(),
|
||||||
|
settings.consumer().maxInFlightPerOrderingUnit(),
|
||||||
|
settings.consumer().prefetch(),
|
||||||
|
settings.consumer().handlerTimeout(),
|
||||||
|
settings.consumer().manualSettlement()),
|
||||||
|
retry(settings.retry()),
|
||||||
|
deadLetter(settings.dlq()),
|
||||||
|
new PayloadPolicy(
|
||||||
|
settings.payload().maxBytes(), settings.payload().claimCheckThresholdBytes()),
|
||||||
|
settings.tier(),
|
||||||
|
settings.production(),
|
||||||
|
settings.keyResolverConfigured(),
|
||||||
|
settings.topologyAutoCreate());
|
||||||
|
}
|
||||||
|
|
||||||
|
private static PhysicalDestination physical(String name, DestinationSettings.Physical physical) {
|
||||||
|
PhysicalDestination address =
|
||||||
|
new PhysicalDestination(
|
||||||
|
Optional.ofNullable(blankToNull(physical.topic())),
|
||||||
|
Optional.ofNullable(blankToNull(physical.exchange())),
|
||||||
|
Optional.ofNullable(blankToNull(physical.routingKey())),
|
||||||
|
Optional.ofNullable(blankToNull(physical.queue())),
|
||||||
|
Optional.ofNullable(blankToNull(physical.subject())),
|
||||||
|
Optional.ofNullable(blankToNull(physical.stream())));
|
||||||
|
if (address.isEmpty()) {
|
||||||
|
throw configurationError(
|
||||||
|
key("destinations", name, "physical"),
|
||||||
|
"a destination needs a broker address — a topic, an exchange, a queue, a subject or a "
|
||||||
|
+ "stream; a logical name that maps to nothing cannot be published to");
|
||||||
|
}
|
||||||
|
return address;
|
||||||
|
}
|
||||||
|
|
||||||
|
private static SchemaPolicy schema(String name, DestinationSettings.Schema schema) {
|
||||||
|
if (schema.messageTypes().isEmpty()) {
|
||||||
|
throw configurationError(
|
||||||
|
key("destinations", name, "schema.message-types"),
|
||||||
|
"a destination carries a closed catalog of message types; one that accepts whatever it "
|
||||||
|
+ "is handed has no reviewable wire contract");
|
||||||
|
}
|
||||||
|
Set<MessageType> types = new LinkedHashSet<>();
|
||||||
|
schema.messageTypes().forEach(type -> types.add(new MessageType(type)));
|
||||||
|
return new SchemaPolicy(new ContentType(schema.codec()), schema.compatibility(), types);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static RetryPolicy retry(DestinationSettings.Retry retry) {
|
||||||
|
return new RetryPolicy(
|
||||||
|
retry.mode(),
|
||||||
|
retry.maxAttempts(),
|
||||||
|
retry.initialDelay(),
|
||||||
|
retry.maxDelay(),
|
||||||
|
retry.multiplier(),
|
||||||
|
retry.jitter(),
|
||||||
|
retry.orderingImpact(),
|
||||||
|
Set.of(),
|
||||||
|
Set.of(),
|
||||||
|
Optional.ofNullable(blankToNull(retry.destination())).map(DestinationName::new));
|
||||||
|
}
|
||||||
|
|
||||||
|
private static DeadLetterPolicy deadLetter(DestinationSettings.Dlq dlq) {
|
||||||
|
String destination = blankToNull(dlq.destination());
|
||||||
|
if (destination == null) {
|
||||||
|
return DeadLetterPolicy.disabled();
|
||||||
|
}
|
||||||
|
return new DeadLetterPolicy(
|
||||||
|
true, Optional.of(new DestinationName(destination)), dlq.maxRedriveCount());
|
||||||
|
}
|
||||||
|
|
||||||
|
private static BrokerSecurityProfile toSecurityProfile(
|
||||||
|
String name, BrokerSecuritySettings security, Map<String, BrokerSettings> brokers) {
|
||||||
|
BrokerSettings broker = brokers.get(name);
|
||||||
|
if (broker == null) {
|
||||||
|
throw configurationError(
|
||||||
|
key("security", name, ""),
|
||||||
|
"'%s' is not a configured broker; a security profile for a broker nobody declared "
|
||||||
|
.formatted(name)
|
||||||
|
+ "secures nothing. Declared brokers are "
|
||||||
|
+ brokers.keySet());
|
||||||
|
}
|
||||||
|
return new BrokerSecurityProfile(
|
||||||
|
name,
|
||||||
|
broker.production(),
|
||||||
|
broker.tlsEnabled(),
|
||||||
|
security.hostnameVerification(),
|
||||||
|
credential(name, "producer", security.producer(), () -> true),
|
||||||
|
credential(name, "consumer", security.consumer(), () -> true),
|
||||||
|
Optional.ofNullable(security.admin())
|
||||||
|
.map(admin -> credential(name, "admin", admin, () -> true)),
|
||||||
|
new DestinationAccessPolicy(
|
||||||
|
destinationNames(security.access().publishable()),
|
||||||
|
destinationNames(security.access().consumable()),
|
||||||
|
destinationNames(security.access().administrable())));
|
||||||
|
}
|
||||||
|
|
||||||
|
private static BrokerCredentialProfile credential(
|
||||||
|
String broker,
|
||||||
|
String role,
|
||||||
|
BrokerSecuritySettings.Credential credential,
|
||||||
|
Supplier<Boolean> required) {
|
||||||
|
if (credential == null && Boolean.TRUE.equals(required.get())) {
|
||||||
|
throw configurationError(
|
||||||
|
key("security", broker, role),
|
||||||
|
"a configured broker needs a %s credential; the roles are separate so that a compromised "
|
||||||
|
.formatted(role)
|
||||||
|
+ "handler has nothing to escalate with");
|
||||||
|
}
|
||||||
|
String type = credential.type() == null ? "" : credential.type().toUpperCase(Locale.ROOT);
|
||||||
|
String id = credential.credentialId();
|
||||||
|
return switch (type) {
|
||||||
|
case "SASL_SCRAM" -> new BrokerCredentialProfile.SaslScram(id);
|
||||||
|
case "OAUTH2" -> new BrokerCredentialProfile.OAuth2(id);
|
||||||
|
case "MUTUAL_TLS" -> new BrokerCredentialProfile.MutualTls(id);
|
||||||
|
case "USERNAME_PASSWORD" -> new BrokerCredentialProfile.UsernamePassword(id);
|
||||||
|
case "NKEY" -> new BrokerCredentialProfile.Nkey(id);
|
||||||
|
default ->
|
||||||
|
throw configurationError(
|
||||||
|
key("security", broker, role + ".type"),
|
||||||
|
"'%s' is not an authentication mechanism this platform implements; the closed set is "
|
||||||
|
.formatted(credential.type())
|
||||||
|
+ "SASL_SCRAM, OAUTH2, MUTUAL_TLS, USERNAME_PASSWORD, NKEY");
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
private static Set<DestinationName> destinationNames(List<String> names) {
|
||||||
|
Set<DestinationName> destinations = new LinkedHashSet<>();
|
||||||
|
names.forEach(name -> destinations.add(new DestinationName(name)));
|
||||||
|
return destinations;
|
||||||
|
}
|
||||||
|
|
||||||
|
private static String blankToNull(String value) {
|
||||||
|
return value == null || value.isBlank() ? null : value;
|
||||||
|
}
|
||||||
|
|
||||||
|
private static String key(String section, String entry, String leaf) {
|
||||||
|
String path = MessagingSettings.PREFIX + '.' + section + '.' + entry;
|
||||||
|
return leaf.isEmpty() ? path : path + '.' + leaf;
|
||||||
|
}
|
||||||
|
|
||||||
|
private static MessagingConfigurationException configurationError(String key, String message) {
|
||||||
|
return new MessagingConfigurationException(
|
||||||
|
"MESSAGING_CONFIGURATION_INVALID", key + ": " + message);
|
||||||
|
}
|
||||||
|
}
|
||||||
+227
@@ -0,0 +1,227 @@
|
|||||||
|
package dev.caskeleton.messaging.autoconfigure;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
|
||||||
|
import java.lang.reflect.RecordComponent;
|
||||||
|
import java.util.ArrayList;
|
||||||
|
import java.util.LinkedHashSet;
|
||||||
|
import java.util.List;
|
||||||
|
import java.util.Locale;
|
||||||
|
import java.util.Map;
|
||||||
|
import java.util.Objects;
|
||||||
|
import java.util.Set;
|
||||||
|
import org.springframework.beans.factory.InitializingBean;
|
||||||
|
import org.springframework.core.env.ConfigurableEnvironment;
|
||||||
|
import org.springframework.core.env.EnumerablePropertySource;
|
||||||
|
import org.springframework.core.env.PropertySource;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Refuses a key inside the platform's own configuration sections that nothing binds.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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<String> KAFKA_ONLY_KEYS =
|
||||||
|
Set.of(
|
||||||
|
"bootstrap-servers",
|
||||||
|
"enable-idempotence",
|
||||||
|
"acks",
|
||||||
|
"max-in-flight-requests-per-connection",
|
||||||
|
"delivery-timeout",
|
||||||
|
"enable-auto-commit",
|
||||||
|
"consumer-group");
|
||||||
|
|
||||||
|
/** Broker keys that only a RabbitMQ entry may carry. */
|
||||||
|
private static final Set<String> RABBIT_ONLY_KEYS =
|
||||||
|
Set.of(
|
||||||
|
"addresses",
|
||||||
|
"publisher-confirms",
|
||||||
|
"publisher-returns",
|
||||||
|
"mandatory",
|
||||||
|
"confirm-timeout",
|
||||||
|
"auto-ack",
|
||||||
|
"prefetch",
|
||||||
|
"quorum-queues");
|
||||||
|
|
||||||
|
private final ConfigurableEnvironment environment;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Creates a validator over the resolved environment.
|
||||||
|
*
|
||||||
|
* @param environment the environment whose keys are checked
|
||||||
|
*/
|
||||||
|
public MessagingConfigurationKeyValidator(ConfigurableEnvironment environment) {
|
||||||
|
this.environment = Objects.requireNonNull(environment, "environment must not be null");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void afterPropertiesSet() {
|
||||||
|
validate();
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Fails when a key under a bound section is not one the settings declare.
|
||||||
|
*
|
||||||
|
* @throws MessagingConfigurationException naming the offending key
|
||||||
|
*/
|
||||||
|
public void validate() {
|
||||||
|
Map<String, Class<?>> sections =
|
||||||
|
Map.of(
|
||||||
|
"destinations", DestinationSettings.class,
|
||||||
|
"brokers", BrokerSettings.class,
|
||||||
|
"security", BrokerSecuritySettings.class);
|
||||||
|
|
||||||
|
List<String> rejected = new ArrayList<>();
|
||||||
|
sections.forEach(
|
||||||
|
(section, shape) -> {
|
||||||
|
Set<String> legal = leafPaths(shape);
|
||||||
|
for (String key : keysUnder(MessagingSettings.PREFIX + '.' + section + '.')) {
|
||||||
|
Entry entry = split(key, MessagingSettings.PREFIX + '.' + section + '.');
|
||||||
|
if (entry.leaf().isEmpty()) {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
if (!legal.contains(entry.leaf())) {
|
||||||
|
rejected.add(
|
||||||
|
"%s binds nothing; %s entries accept %s"
|
||||||
|
.formatted(key, section, legal.stream().sorted().toList()));
|
||||||
|
} else if ("brokers".equals(section)) {
|
||||||
|
wrongFamily(entry).ifPresent(rejected::add);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
if (rejected.isEmpty()) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
throw new MessagingConfigurationException(
|
||||||
|
"MESSAGING_CONFIGURATION_KEY_UNKNOWN",
|
||||||
|
"these messaging keys do not bind: "
|
||||||
|
+ String.join("; ", rejected.stream().sorted().limit(10).toList())
|
||||||
|
+ (rejected.size() > 10 ? " (and " + (rejected.size() - 10) + " more)" : ""));
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Reports a broker key that belongs to the other broker family.
|
||||||
|
*
|
||||||
|
* <p>Both families are described by one record, so a Kafka entry carrying {@code prefetch} binds
|
||||||
|
* without complaint and does nothing. The author of that line believed it was doing something,
|
||||||
|
* which is the same silence this class exists to end.
|
||||||
|
*/
|
||||||
|
private java.util.Optional<String> wrongFamily(Entry entry) {
|
||||||
|
String declared =
|
||||||
|
environment.getProperty(
|
||||||
|
MessagingSettings.PREFIX + ".brokers." + entry.name() + ".type", "");
|
||||||
|
String family = declared.toLowerCase(Locale.ROOT);
|
||||||
|
String leaf = entry.leaf();
|
||||||
|
if (BrokerSettings.KAFKA.equals(family) && RABBIT_ONLY_KEYS.contains(leaf)) {
|
||||||
|
return java.util.Optional.of(
|
||||||
|
"%s.brokers.%s.%s is a RabbitMQ setting on a Kafka broker"
|
||||||
|
.formatted(MessagingSettings.PREFIX, entry.name(), leaf));
|
||||||
|
}
|
||||||
|
if (BrokerSettings.RABBITMQ.equals(family) && KAFKA_ONLY_KEYS.contains(leaf)) {
|
||||||
|
return java.util.Optional.of(
|
||||||
|
"%s.brokers.%s.%s is a Kafka setting on a RabbitMQ broker"
|
||||||
|
.formatted(MessagingSettings.PREFIX, entry.name(), leaf));
|
||||||
|
}
|
||||||
|
return java.util.Optional.empty();
|
||||||
|
}
|
||||||
|
|
||||||
|
/** One configuration key split into the map entry it configures and the leaf inside it. */
|
||||||
|
private record Entry(String name, String leaf) {}
|
||||||
|
|
||||||
|
private static Entry split(String key, String sectionPrefix) {
|
||||||
|
String remainder = key.substring(sectionPrefix.length());
|
||||||
|
String name;
|
||||||
|
String leaf;
|
||||||
|
if (remainder.startsWith("[")) {
|
||||||
|
// Relaxed binding writes a map key containing a dot as `[order.events]`, so the bracket is
|
||||||
|
// the only reliable boundary when one is present.
|
||||||
|
int close = remainder.indexOf(']');
|
||||||
|
name = close < 0 ? remainder : remainder.substring(1, close);
|
||||||
|
leaf = close < 0 ? "" : remainder.substring(close + 1);
|
||||||
|
} else {
|
||||||
|
int dot = remainder.indexOf('.');
|
||||||
|
name = dot < 0 ? remainder : remainder.substring(0, dot);
|
||||||
|
leaf = dot < 0 ? "" : remainder.substring(dot);
|
||||||
|
}
|
||||||
|
if (leaf.startsWith(".")) {
|
||||||
|
leaf = leaf.substring(1);
|
||||||
|
}
|
||||||
|
return new Entry(name, canonical(leaf.replaceAll("\\[\\d+\\]", "")));
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Returns every leaf path a settings record accepts, in the canonical kebab form.
|
||||||
|
*
|
||||||
|
* <p>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<String> leafPaths(Class<?> shape) {
|
||||||
|
Set<String> paths = new LinkedHashSet<>();
|
||||||
|
collectLeafPaths(shape, "", paths);
|
||||||
|
return paths;
|
||||||
|
}
|
||||||
|
|
||||||
|
private static void collectLeafPaths(Class<?> shape, String prefix, Set<String> paths) {
|
||||||
|
for (RecordComponent component : shape.getRecordComponents()) {
|
||||||
|
String path = prefix + canonical(component.getName());
|
||||||
|
if (component.getType().isRecord()) {
|
||||||
|
collectLeafPaths(component.getType(), path + '.', paths);
|
||||||
|
} else {
|
||||||
|
paths.add(path);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Normalises a property path to the kebab-case form the settings records declare. */
|
||||||
|
private static String canonical(String path) {
|
||||||
|
StringBuilder canonical = new StringBuilder(path.length() + 4);
|
||||||
|
for (int index = 0; index < path.length(); index++) {
|
||||||
|
char character = path.charAt(index);
|
||||||
|
if (character == '_') {
|
||||||
|
canonical.append('-');
|
||||||
|
} else if (Character.isUpperCase(character)) {
|
||||||
|
if (index > 0 && path.charAt(index - 1) != '.' && path.charAt(index - 1) != '-') {
|
||||||
|
canonical.append('-');
|
||||||
|
}
|
||||||
|
canonical.append(Character.toLowerCase(character));
|
||||||
|
} else {
|
||||||
|
canonical.append(character);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return canonical.toString();
|
||||||
|
}
|
||||||
|
|
||||||
|
private List<String> keysUnder(String prefix) {
|
||||||
|
List<String> keys = new ArrayList<>();
|
||||||
|
for (PropertySource<?> source : environment.getPropertySources()) {
|
||||||
|
if (!(source instanceof EnumerablePropertySource<?> enumerable)) {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
for (String key : enumerable.getPropertyNames()) {
|
||||||
|
if (key.startsWith(prefix)) {
|
||||||
|
keys.add(key);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return keys;
|
||||||
|
}
|
||||||
|
}
|
||||||
+94
-24
@@ -15,7 +15,6 @@ import dev.caskeleton.messaging.security.BrokerTlsPolicy;
|
|||||||
import dev.caskeleton.messaging.security.CredentialProvider;
|
import dev.caskeleton.messaging.security.CredentialProvider;
|
||||||
import dev.caskeleton.messaging.security.CredentialRuntimeRegistry;
|
import dev.caskeleton.messaging.security.CredentialRuntimeRegistry;
|
||||||
import dev.caskeleton.messaging.security.MessageSecurityValidator;
|
import dev.caskeleton.messaging.security.MessageSecurityValidator;
|
||||||
import dev.caskeleton.messaging.transport.BackpressureController;
|
|
||||||
import dev.caskeleton.messaging.transport.DefaultMessagingRuntimeRegistry;
|
import dev.caskeleton.messaging.transport.DefaultMessagingRuntimeRegistry;
|
||||||
import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator;
|
import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator;
|
||||||
import dev.caskeleton.messaging.transport.MessagingRuntimeRegistry;
|
import dev.caskeleton.messaging.transport.MessagingRuntimeRegistry;
|
||||||
@@ -54,11 +53,13 @@ public class MessagingCoreAutoConfiguration {
|
|||||||
org.springframework.beans.factory.ObjectProvider<
|
org.springframework.beans.factory.ObjectProvider<
|
||||||
dev.caskeleton.messaging.security.BrokerSecurityProfile>
|
dev.caskeleton.messaging.security.BrokerSecurityProfile>
|
||||||
profiles,
|
profiles,
|
||||||
|
CompiledMessagingConfiguration compiled,
|
||||||
org.springframework.beans.factory.ObjectProvider<
|
org.springframework.beans.factory.ObjectProvider<
|
||||||
dev.caskeleton.messaging.security.CredentialProvider>
|
dev.caskeleton.messaging.security.CredentialProvider>
|
||||||
credentials,
|
credentials,
|
||||||
org.springframework.core.env.Environment environment) {
|
org.springframework.core.env.Environment environment) {
|
||||||
return new MessagingCredentialRequirementValidator(profiles, credentials, environment);
|
return new MessagingCredentialRequirementValidator(
|
||||||
|
profiles, compiled.security(), credentials, environment);
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -73,20 +74,63 @@ public class MessagingCoreAutoConfiguration {
|
|||||||
return new MessagingPrefixMigrationValidator(environment);
|
return new MessagingPrefixMigrationValidator(environment);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Compiles {@code app.messaging.destinations}, {@code .brokers} and {@code .security} into the
|
||||||
|
* platform's own profile objects.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
* Validates every registered destination profile at startup.
|
||||||
*
|
*
|
||||||
* <p>Returns a marker rather than a service because its only job is to fail the context when the
|
* <p>Returns a marker rather than a service because its only job is to fail the context when the
|
||||||
* registry is inconsistent.
|
* registry is inconsistent.
|
||||||
*
|
*
|
||||||
* @param profiles the registered profiles
|
* <p>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
|
* @return the validated registry
|
||||||
*/
|
*/
|
||||||
@Bean
|
@Bean
|
||||||
@ConditionalOnMissingBean
|
@ConditionalOnMissingBean
|
||||||
public ValidatedDestinationRegistry validatedDestinationRegistry(
|
public ValidatedDestinationRegistry validatedDestinationRegistry(
|
||||||
ObjectProvider<DestinationProfile> profiles) {
|
ObjectProvider<DestinationProfile> profiles, CompiledMessagingConfiguration compiled) {
|
||||||
List<DestinationProfile> registered = profiles.orderedStream().toList();
|
List<DestinationProfile> registered =
|
||||||
|
java.util.stream.Stream.concat(compiled.destinations().stream(), profiles.orderedStream())
|
||||||
|
.toList();
|
||||||
new DestinationProfileValidator().validateAll(registered);
|
new DestinationProfileValidator().validateAll(registered);
|
||||||
return new ValidatedDestinationRegistry(registered);
|
return new ValidatedDestinationRegistry(registered);
|
||||||
}
|
}
|
||||||
@@ -148,20 +192,6 @@ public class MessagingCoreAutoConfiguration {
|
|||||||
return new DefaultMessagingRuntimeRegistry(properties.getShutdown().getDrainDeadline());
|
return new DefaultMessagingRuntimeRegistry(properties.getShutdown().getDrainDeadline());
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* Returns the process-wide backpressure controller.
|
|
||||||
*
|
|
||||||
* @param properties the bound configuration
|
|
||||||
* @return the controller
|
|
||||||
*/
|
|
||||||
@Bean
|
|
||||||
@ConditionalOnMissingBean
|
|
||||||
public BackpressureController backpressureController(MessagingSettings properties) {
|
|
||||||
return new BackpressureController(
|
|
||||||
properties.getBackpressure().getGlobalLimit(),
|
|
||||||
properties.getBackpressure().getPerDestinationLimit());
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns the graceful shutdown coordinator.
|
* Returns the graceful shutdown coordinator.
|
||||||
*
|
*
|
||||||
@@ -174,6 +204,45 @@ public class MessagingCoreAutoConfiguration {
|
|||||||
return new GracefulShutdownCoordinator(properties.getShutdown().getDrainDeadline());
|
return new GracefulShutdownCoordinator(properties.getShutdown().getDrainDeadline());
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Runs the security validator over every broker security profile, declared or configured.
|
||||||
|
*
|
||||||
|
* @param profiles the security profiles the application declared as beans
|
||||||
|
* @param compiled the security profiles compiled from configuration
|
||||||
|
* @param validator the security validator
|
||||||
|
* @return the startup validation
|
||||||
|
*/
|
||||||
|
@Bean
|
||||||
|
public StartupProfileValidation<dev.caskeleton.messaging.security.BrokerSecurityProfile>
|
||||||
|
brokerSecurityStartupValidation(
|
||||||
|
ObjectProvider<dev.caskeleton.messaging.security.BrokerSecurityProfile> profiles,
|
||||||
|
CompiledMessagingConfiguration compiled,
|
||||||
|
MessageSecurityValidator validator) {
|
||||||
|
return new StartupProfileValidation<>(
|
||||||
|
() ->
|
||||||
|
java.util.stream.Stream.concat(compiled.security().stream(), profiles.orderedStream())
|
||||||
|
.toList(),
|
||||||
|
validator::validate);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Drives the shutdown phases the admission gate and the drain coordinator only implemented.
|
||||||
|
*
|
||||||
|
* @param admission the publish admission gate
|
||||||
|
* @param drain the in-flight work coordinator
|
||||||
|
* @param properties the bound configuration supplying the drain deadline
|
||||||
|
* @return the lifecycle
|
||||||
|
*/
|
||||||
|
@Bean
|
||||||
|
@ConditionalOnMissingBean
|
||||||
|
public MessagingShutdownLifecycle messagingShutdownLifecycle(
|
||||||
|
dev.caskeleton.messaging.policy.MessagingAdmissionController admission,
|
||||||
|
GracefulShutdownCoordinator drain,
|
||||||
|
MessagingSettings properties) {
|
||||||
|
return new MessagingShutdownLifecycle(
|
||||||
|
admission, drain, properties.getShutdown().getDrainDeadline());
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns the diagnostic redactor.
|
* Returns the diagnostic redactor.
|
||||||
*
|
*
|
||||||
@@ -264,14 +333,15 @@ public class MessagingCoreAutoConfiguration {
|
|||||||
* Returns the read-only actuator endpoint.
|
* Returns the read-only actuator endpoint.
|
||||||
*
|
*
|
||||||
* @param registry the validated destination registry
|
* @param registry the validated destination registry
|
||||||
* @param backpressure the in-flight counters
|
* @param admission the gate every publish passes through
|
||||||
* @return the endpoint
|
* @return the endpoint
|
||||||
*/
|
*/
|
||||||
@Bean
|
@Bean
|
||||||
@ConditionalOnMissingBean
|
@ConditionalOnMissingBean
|
||||||
public MessagingEndpoint messagingEndpoint(
|
public MessagingEndpoint messagingEndpoint(
|
||||||
ValidatedDestinationRegistry registry, BackpressureController backpressure) {
|
ValidatedDestinationRegistry registry,
|
||||||
return new MessagingEndpoint(registry, backpressure);
|
dev.caskeleton.messaging.policy.MessagingAdmissionController admission) {
|
||||||
|
return new MessagingEndpoint(registry, admission);
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -342,8 +412,8 @@ public class MessagingCoreAutoConfiguration {
|
|||||||
dev.caskeleton.messaging.schema.json.JacksonMessageCodec.DEFAULT_MAX_BYTES,
|
dev.caskeleton.messaging.schema.json.JacksonMessageCodec.DEFAULT_MAX_BYTES,
|
||||||
dev.caskeleton.messaging.schema.json.JacksonMessageCodec.DEFAULT_MAX_BYTES / 2)),
|
dev.caskeleton.messaging.schema.json.JacksonMessageCodec.DEFAULT_MAX_BYTES / 2)),
|
||||||
new dev.caskeleton.messaging.policy.InFlightLimiter(
|
new dev.caskeleton.messaging.policy.InFlightLimiter(
|
||||||
properties.getBackpressure().getPerDestinationLimit(),
|
properties.getBackpressure().getGlobalLimit(), java.time.Duration.ofSeconds(5)),
|
||||||
java.time.Duration.ofSeconds(5)));
|
properties.getBackpressure().getPerDestinationLimit());
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|||||||
+20
-1
@@ -21,20 +21,38 @@ import org.springframework.core.env.Environment;
|
|||||||
* <p>The check is scoped to production profiles. A local profile that connects to a broker with no
|
* <p>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
|
* authentication is a legitimate development setup; the same profile marked production is not, and
|
||||||
* the two must not be satisfiable by the same configuration.
|
* the two must not be satisfiable by the same configuration.
|
||||||
|
*
|
||||||
|
* <p>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 {
|
public final class MessagingCredentialRequirementValidator implements InitializingBean {
|
||||||
|
|
||||||
private final ObjectProvider<BrokerSecurityProfile> profiles;
|
private final ObjectProvider<BrokerSecurityProfile> profiles;
|
||||||
|
|
||||||
|
private final List<BrokerSecurityProfile> configured;
|
||||||
|
|
||||||
private final ObjectProvider<dev.caskeleton.messaging.security.CredentialProvider> credentials;
|
private final ObjectProvider<dev.caskeleton.messaging.security.CredentialProvider> credentials;
|
||||||
|
|
||||||
private final Environment environment;
|
private final Environment environment;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Creates the validator.
|
||||||
|
*
|
||||||
|
* @param profiles the security profiles the application declared as beans
|
||||||
|
* @param configured the security profiles compiled from configuration
|
||||||
|
* @param credentials the application's credential source, if it supplied one
|
||||||
|
* @param environment the resolved environment, used to report the active profiles
|
||||||
|
*/
|
||||||
public MessagingCredentialRequirementValidator(
|
public MessagingCredentialRequirementValidator(
|
||||||
ObjectProvider<BrokerSecurityProfile> profiles,
|
ObjectProvider<BrokerSecurityProfile> profiles,
|
||||||
|
List<BrokerSecurityProfile> configured,
|
||||||
ObjectProvider<dev.caskeleton.messaging.security.CredentialProvider> credentials,
|
ObjectProvider<dev.caskeleton.messaging.security.CredentialProvider> credentials,
|
||||||
Environment environment) {
|
Environment environment) {
|
||||||
this.profiles = Objects.requireNonNull(profiles, "profiles must not be null");
|
this.profiles = Objects.requireNonNull(profiles, "profiles must not be null");
|
||||||
|
this.configured =
|
||||||
|
List.copyOf(Objects.requireNonNull(configured, "configured must not be null"));
|
||||||
this.credentials = Objects.requireNonNull(credentials, "credentials must not be null");
|
this.credentials = Objects.requireNonNull(credentials, "credentials must not be null");
|
||||||
this.environment = Objects.requireNonNull(environment, "environment must not be null");
|
this.environment = Objects.requireNonNull(environment, "environment must not be null");
|
||||||
}
|
}
|
||||||
@@ -54,9 +72,10 @@ public final class MessagingCredentialRequirementValidator implements Initializi
|
|||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
List<String> production =
|
List<String> production =
|
||||||
profiles.stream()
|
java.util.stream.Stream.concat(configured.stream(), profiles.stream())
|
||||||
.filter(BrokerSecurityProfile::production)
|
.filter(BrokerSecurityProfile::production)
|
||||||
.map(BrokerSecurityProfile::broker)
|
.map(BrokerSecurityProfile::broker)
|
||||||
|
.distinct()
|
||||||
.toList();
|
.toList();
|
||||||
if (production.isEmpty()) {
|
if (production.isEmpty()) {
|
||||||
return;
|
return;
|
||||||
|
|||||||
+11
-7
@@ -1,7 +1,7 @@
|
|||||||
package dev.caskeleton.messaging.autoconfigure;
|
package dev.caskeleton.messaging.autoconfigure;
|
||||||
|
|
||||||
import dev.caskeleton.messaging.policy.DestinationProfile;
|
import dev.caskeleton.messaging.policy.DestinationProfile;
|
||||||
import dev.caskeleton.messaging.transport.BackpressureController;
|
import dev.caskeleton.messaging.policy.MessagingAdmissionController;
|
||||||
import java.util.LinkedHashMap;
|
import java.util.LinkedHashMap;
|
||||||
import java.util.List;
|
import java.util.List;
|
||||||
import java.util.Map;
|
import java.util.Map;
|
||||||
@@ -26,18 +26,22 @@ import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
|
|||||||
public class MessagingEndpoint {
|
public class MessagingEndpoint {
|
||||||
|
|
||||||
private final ValidatedDestinationRegistry registry;
|
private final ValidatedDestinationRegistry registry;
|
||||||
private final BackpressureController backpressure;
|
private final MessagingAdmissionController admission;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Creates the endpoint.
|
* Creates the endpoint.
|
||||||
*
|
*
|
||||||
|
* <p>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 registry the validated destination registry
|
||||||
* @param backpressure the in-flight counters
|
* @param admission the gate every publish passes through
|
||||||
*/
|
*/
|
||||||
public MessagingEndpoint(
|
public MessagingEndpoint(
|
||||||
ValidatedDestinationRegistry registry, BackpressureController backpressure) {
|
ValidatedDestinationRegistry registry, MessagingAdmissionController admission) {
|
||||||
this.registry = Objects.requireNonNull(registry, "registry must not be null");
|
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
|
@ReadOperation
|
||||||
public Map<String, Object> messaging() {
|
public Map<String, Object> messaging() {
|
||||||
Map<String, Object> report = new LinkedHashMap<>();
|
Map<String, Object> report = new LinkedHashMap<>();
|
||||||
report.put("globalInFlight", backpressure.globalInFlight());
|
report.put("globalInFlight", admission.inFlight());
|
||||||
report.put("destinations", destinations());
|
report.put("destinations", destinations());
|
||||||
return Map.copyOf(report);
|
return Map.copyOf(report);
|
||||||
}
|
}
|
||||||
@@ -68,7 +72,7 @@ public class MessagingEndpoint {
|
|||||||
entry.put("production", profile.production());
|
entry.put("production", profile.production());
|
||||||
entry.put("deadLetterEnabled", profile.deadLetter().enabled());
|
entry.put("deadLetterEnabled", profile.deadLetter().enabled());
|
||||||
entry.put("retryMode", profile.retry().mode().name());
|
entry.put("retryMode", profile.retry().mode().name());
|
||||||
entry.put("inFlight", backpressure.inFlight(profile.name().value()));
|
entry.put("inFlight", admission.inFlight(profile.name().value()));
|
||||||
return Map.copyOf(entry);
|
return Map.copyOf(entry);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+69
@@ -0,0 +1,69 @@
|
|||||||
|
package dev.caskeleton.messaging.autoconfigure;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.outbox.OutboxRelayWorker;
|
||||||
|
import java.time.Duration;
|
||||||
|
import java.util.Objects;
|
||||||
|
import org.springframework.context.SmartLifecycle;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Starts and stops the outbox relay with the application context.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>{@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;
|
||||||
|
}
|
||||||
|
}
|
||||||
+42
@@ -48,11 +48,42 @@ public class MessagingProviderSelection {
|
|||||||
"kafka", KafkaMessagingAutoConfiguration.class,
|
"kafka", KafkaMessagingAutoConfiguration.class,
|
||||||
"rabbit", RabbitMessagingAutoConfiguration.class);
|
"rabbit", RabbitMessagingAutoConfiguration.class);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Broker ids that ship without a {@code MessagingTransport}, and why.
|
||||||
|
*
|
||||||
|
* <p>Registered is not the same as assemblable. The Rabbit leaf ships its profile validator,
|
||||||
|
* failure classifier and security configurer, and no transport — the native channel bridge those
|
||||||
|
* would sit on has only test implementations. Selecting it therefore produced an unsatisfied
|
||||||
|
* dependency on {@code MessagingTransport} deep inside the core configuration, which tells an
|
||||||
|
* operator that a bean is missing rather than that the transport they chose is not finished.
|
||||||
|
*
|
||||||
|
* <p>Refused here instead, next to the other selection errors, so the message names the state the
|
||||||
|
* deployment is actually in. An entry leaves this map on the day its transport does exist.
|
||||||
|
*/
|
||||||
|
static final Map<String, String> BROKERS_WITHOUT_A_TRANSPORT =
|
||||||
|
Map.of(
|
||||||
|
"rabbit",
|
||||||
|
"the Rabbit adapter ships its validators and security configuration but no "
|
||||||
|
+ "MessagingTransport: its native channel publisher is not implemented, so a publish "
|
||||||
|
+ "has nothing to travel on");
|
||||||
|
|
||||||
/** The registered broker ids, so a message can tell an operator what is available. */
|
/** The registered broker ids, so a message can tell an operator what is available. */
|
||||||
public static List<String> registeredBrokerIds() {
|
public static List<String> registeredBrokerIds() {
|
||||||
return REGISTERED_BROKERS.keySet().stream().sorted().toList();
|
return REGISTERED_BROKERS.keySet().stream().sorted().toList();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The registered broker ids that actually assemble a transport.
|
||||||
|
*
|
||||||
|
* @return the ids a deployment can select today
|
||||||
|
*/
|
||||||
|
public static List<String> assemblableBrokerIds() {
|
||||||
|
return REGISTERED_BROKERS.keySet().stream()
|
||||||
|
.filter(id -> !BROKERS_WITHOUT_A_TRANSPORT.containsKey(id))
|
||||||
|
.sorted()
|
||||||
|
.toList();
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Resolves the selection, or throws naming the property and the values it accepts.
|
* Resolves the selection, or throws naming the property and the values it accepts.
|
||||||
*
|
*
|
||||||
@@ -87,6 +118,17 @@ public class MessagingProviderSelection {
|
|||||||
+ clientClass
|
+ clientClass
|
||||||
+ " on the classpath; the deployment selected a transport it did not ship");
|
+ " on the classpath; the deployment selected a transport it did not ship");
|
||||||
}
|
}
|
||||||
|
String unfinished = BROKERS_WITHOUT_A_TRANSPORT.get(broker);
|
||||||
|
if (unfinished != null) {
|
||||||
|
throw new IllegalStateException(
|
||||||
|
MessagingSettings.PREFIX
|
||||||
|
+ ".broker="
|
||||||
|
+ broker
|
||||||
|
+ " cannot be selected: "
|
||||||
|
+ unfinished
|
||||||
|
+ ". Transports that can be assembled today: "
|
||||||
|
+ assemblableBrokerIds());
|
||||||
|
}
|
||||||
return broker;
|
return broker;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
+72
@@ -1,11 +1,15 @@
|
|||||||
package dev.caskeleton.messaging.autoconfigure;
|
package dev.caskeleton.messaging.autoconfigure;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.api.publish.MessagePublisher;
|
||||||
import dev.caskeleton.messaging.inbox.IdempotentConsumer;
|
import dev.caskeleton.messaging.inbox.IdempotentConsumer;
|
||||||
import dev.caskeleton.messaging.inbox.InboxCleanupJob;
|
import dev.caskeleton.messaging.inbox.InboxCleanupJob;
|
||||||
import dev.caskeleton.messaging.inbox.InboxRetentionPolicy;
|
import dev.caskeleton.messaging.inbox.InboxRetentionPolicy;
|
||||||
import dev.caskeleton.messaging.inbox.TransactionalInboxHandler;
|
import dev.caskeleton.messaging.inbox.TransactionalInboxHandler;
|
||||||
import dev.caskeleton.messaging.outbox.OutboxCleanupJob;
|
import dev.caskeleton.messaging.outbox.OutboxCleanupJob;
|
||||||
|
import dev.caskeleton.messaging.outbox.OutboxEnvelopeFactory;
|
||||||
import dev.caskeleton.messaging.outbox.OutboxProperties;
|
import dev.caskeleton.messaging.outbox.OutboxProperties;
|
||||||
|
import dev.caskeleton.messaging.outbox.OutboxRelay;
|
||||||
|
import dev.caskeleton.messaging.outbox.OutboxRelayWorker;
|
||||||
import dev.caskeleton.messaging.outbox.OutboxRetryScheduler;
|
import dev.caskeleton.messaging.outbox.OutboxRetryScheduler;
|
||||||
import dev.caskeleton.messaging.reliability.InboxRepository;
|
import dev.caskeleton.messaging.reliability.InboxRepository;
|
||||||
import dev.caskeleton.messaging.reliability.OutboxRepository;
|
import dev.caskeleton.messaging.reliability.OutboxRepository;
|
||||||
@@ -28,6 +32,10 @@ import org.springframework.context.annotation.Configuration;
|
|||||||
* <p>The cleanup jobs are beans but no scheduler is registered for them. Scheduling is the
|
* <p>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
|
* 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.
|
* cleanup, and auto-registering a fixed-rate task would have every replica delete the same rows.
|
||||||
|
*
|
||||||
|
* <p>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)
|
@Configuration(proxyBeanMethods = false)
|
||||||
public class MessagingReliabilityAutoConfiguration {
|
public class MessagingReliabilityAutoConfiguration {
|
||||||
@@ -55,6 +63,70 @@ public class MessagingReliabilityAutoConfiguration {
|
|||||||
return new OutboxRetryScheduler(properties, Duration.ofMinutes(1));
|
return new OutboxRetryScheduler(properties, Duration.ofMinutes(1));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Returns the relay, when the application supplied the two things only it can supply.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
* Returns the outbox cleanup job.
|
||||||
*
|
*
|
||||||
|
|||||||
+70
@@ -1,6 +1,8 @@
|
|||||||
package dev.caskeleton.messaging.autoconfigure;
|
package dev.caskeleton.messaging.autoconfigure;
|
||||||
|
|
||||||
import java.time.Duration;
|
import java.time.Duration;
|
||||||
|
import java.util.LinkedHashMap;
|
||||||
|
import java.util.Map;
|
||||||
import org.springframework.boot.context.properties.ConfigurationProperties;
|
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
|
* 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
|
* applies to the Spring Cloud Stream bridge, which bypasses the platform's retry and dead letter
|
||||||
* policy by design.
|
* policy by design.
|
||||||
|
*
|
||||||
|
* <p>The destination, broker and security maps are what the configuration reference has always
|
||||||
|
* described and nothing bound. Until they existed, a deployment that configured them exactly as
|
||||||
|
* documented changed no behaviour and produced no error: the profiles the platform actually used
|
||||||
|
* 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.
|
||||||
|
*
|
||||||
|
* <p>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)
|
@ConfigurationProperties(prefix = MessagingSettings.PREFIX)
|
||||||
public class MessagingSettings {
|
public class MessagingSettings {
|
||||||
@@ -39,6 +52,63 @@ public class MessagingSettings {
|
|||||||
private final Bridge bridge = new Bridge();
|
private final Bridge bridge = new Bridge();
|
||||||
private final Backpressure backpressure = new Backpressure();
|
private final Backpressure backpressure = new Backpressure();
|
||||||
private final Shutdown shutdown = new Shutdown();
|
private final Shutdown shutdown = new Shutdown();
|
||||||
|
private Map<String, DestinationSettings> destinations = new LinkedHashMap<>();
|
||||||
|
private Map<String, BrokerSettings> brokers = new LinkedHashMap<>();
|
||||||
|
private Map<String, BrokerSecuritySettings> security = new LinkedHashMap<>();
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Returns the declared destinations, keyed by logical name.
|
||||||
|
*
|
||||||
|
* @return the destination settings
|
||||||
|
*/
|
||||||
|
public Map<String, DestinationSettings> getDestinations() {
|
||||||
|
return destinations;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Sets the declared destinations.
|
||||||
|
*
|
||||||
|
* @param destinations the destination settings, keyed by logical name
|
||||||
|
*/
|
||||||
|
public void setDestinations(Map<String, DestinationSettings> destinations) {
|
||||||
|
this.destinations = new LinkedHashMap<>(destinations);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Returns the declared brokers, keyed by logical name.
|
||||||
|
*
|
||||||
|
* @return the broker settings
|
||||||
|
*/
|
||||||
|
public Map<String, BrokerSettings> getBrokers() {
|
||||||
|
return brokers;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Sets the declared brokers.
|
||||||
|
*
|
||||||
|
* @param brokers the broker settings, keyed by logical name
|
||||||
|
*/
|
||||||
|
public void setBrokers(Map<String, BrokerSettings> brokers) {
|
||||||
|
this.brokers = new LinkedHashMap<>(brokers);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Returns the declared broker security profiles, keyed by broker name.
|
||||||
|
*
|
||||||
|
* @return the security settings
|
||||||
|
*/
|
||||||
|
public Map<String, BrokerSecuritySettings> getSecurity() {
|
||||||
|
return security;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Sets the declared broker security profiles.
|
||||||
|
*
|
||||||
|
* @param security the security settings, keyed by broker name
|
||||||
|
*/
|
||||||
|
public void setSecurity(Map<String, BrokerSecuritySettings> security) {
|
||||||
|
this.security = new LinkedHashMap<>(security);
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns the experimental adapter switches.
|
* Returns the experimental adapter switches.
|
||||||
|
|||||||
+124
@@ -0,0 +1,124 @@
|
|||||||
|
package dev.caskeleton.messaging.autoconfigure;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.policy.MessagingAdmissionController;
|
||||||
|
import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator;
|
||||||
|
import java.time.Duration;
|
||||||
|
import java.time.Instant;
|
||||||
|
import java.util.Objects;
|
||||||
|
import java.util.concurrent.atomic.AtomicBoolean;
|
||||||
|
import java.util.function.Supplier;
|
||||||
|
import org.springframework.context.SmartLifecycle;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Runs the platform's shutdown phases in order when the context stops.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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<Instant> clock;
|
||||||
|
|
||||||
|
private final AtomicBoolean running = new AtomicBoolean();
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Creates the lifecycle.
|
||||||
|
*
|
||||||
|
* @param admission the publish admission gate
|
||||||
|
* @param drain the in-flight work coordinator
|
||||||
|
* @param drainDeadline how long in-flight work may take
|
||||||
|
*/
|
||||||
|
public MessagingShutdownLifecycle(
|
||||||
|
MessagingAdmissionController admission,
|
||||||
|
GracefulShutdownCoordinator drain,
|
||||||
|
Duration drainDeadline) {
|
||||||
|
this(admission, drain, drainDeadline, Instant::now);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Creates the lifecycle with an explicit clock, so the deadline is testable without sleeping.
|
||||||
|
*
|
||||||
|
* @param admission the publish admission gate
|
||||||
|
* @param drain the in-flight work coordinator
|
||||||
|
* @param drainDeadline how long in-flight work may take
|
||||||
|
* @param clock the source of the current instant
|
||||||
|
*/
|
||||||
|
public MessagingShutdownLifecycle(
|
||||||
|
MessagingAdmissionController admission,
|
||||||
|
GracefulShutdownCoordinator drain,
|
||||||
|
Duration drainDeadline,
|
||||||
|
Supplier<Instant> clock) {
|
||||||
|
this.admission = Objects.requireNonNull(admission, "admission must not be null");
|
||||||
|
this.drain = Objects.requireNonNull(drain, "drain must not be null");
|
||||||
|
this.drainDeadline = Objects.requireNonNull(drainDeadline, "drainDeadline must not be null");
|
||||||
|
this.clock = Objects.requireNonNull(clock, "clock must not be null");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void start() {
|
||||||
|
running.set(true);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void stop() {
|
||||||
|
if (!running.compareAndSet(true, false)) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
admission.stopAcceptingNewWork();
|
||||||
|
Instant startedAt = clock.get();
|
||||||
|
drain.beginDrain(startedAt);
|
||||||
|
Instant deadline = startedAt.plus(drainDeadline);
|
||||||
|
while (!drain.isDrained(clock.get()) && clock.get().isBefore(deadline)) {
|
||||||
|
try {
|
||||||
|
Thread.sleep(POLL.toMillis());
|
||||||
|
} catch (InterruptedException interrupted) {
|
||||||
|
// The interrupt is the signal to stop waiting, not a reason to lose it: the phases below
|
||||||
|
// still have to run, and a swallowed interrupt leaves the shutdown thread looking healthy.
|
||||||
|
Thread.currentThread().interrupt();
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public boolean isRunning() {
|
||||||
|
return running.get();
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Stops after the producers of work and before the beans that own broker connections.
|
||||||
|
*
|
||||||
|
* <p>{@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;
|
||||||
|
}
|
||||||
|
}
|
||||||
+24
@@ -36,6 +36,30 @@ public class RabbitMessagingAutoConfiguration {
|
|||||||
return new RabbitProfileValidator();
|
return new RabbitProfileValidator();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Runs the RabbitMQ profile validator over every broker profile, declared or configured.
|
||||||
|
*
|
||||||
|
* @param profiles the broker profiles the application declared as beans
|
||||||
|
* @param compiled the broker profiles compiled from {@code app.messaging.brokers}
|
||||||
|
* @param validator the RabbitMQ profile validator
|
||||||
|
* @return the startup validation
|
||||||
|
*/
|
||||||
|
@Bean
|
||||||
|
public StartupProfileValidation<dev.caskeleton.messaging.rabbit.RabbitBrokerProfile>
|
||||||
|
rabbitProfileStartupValidation(
|
||||||
|
org.springframework.beans.factory.ObjectProvider<
|
||||||
|
dev.caskeleton.messaging.rabbit.RabbitBrokerProfile>
|
||||||
|
profiles,
|
||||||
|
CompiledMessagingConfiguration compiled,
|
||||||
|
RabbitProfileValidator validator) {
|
||||||
|
return new StartupProfileValidation<>(
|
||||||
|
() ->
|
||||||
|
java.util.stream.Stream.concat(
|
||||||
|
compiled.rabbitBrokers().stream(), profiles.orderedStream())
|
||||||
|
.toList(),
|
||||||
|
validator::validate);
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns the publish failure classifier.
|
* Returns the publish failure classifier.
|
||||||
*
|
*
|
||||||
|
|||||||
+46
@@ -0,0 +1,46 @@
|
|||||||
|
package dev.caskeleton.messaging.autoconfigure;
|
||||||
|
|
||||||
|
import java.util.List;
|
||||||
|
import java.util.Objects;
|
||||||
|
import java.util.function.Consumer;
|
||||||
|
import java.util.function.Supplier;
|
||||||
|
import org.springframework.beans.factory.InitializingBean;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Applies one profile validator to every profile of its kind at startup.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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 <T> the profile type this instance validates
|
||||||
|
*/
|
||||||
|
final class StartupProfileValidation<T> implements InitializingBean {
|
||||||
|
|
||||||
|
private final Supplier<List<T>> profiles;
|
||||||
|
|
||||||
|
private final Consumer<T> validator;
|
||||||
|
|
||||||
|
StartupProfileValidation(Supplier<List<T>> profiles, Consumer<T> validator) {
|
||||||
|
this.profiles = Objects.requireNonNull(profiles, "profiles must not be null");
|
||||||
|
this.validator = Objects.requireNonNull(validator, "validator must not be null");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void afterPropertiesSet() {
|
||||||
|
profiles.get().forEach(validator);
|
||||||
|
}
|
||||||
|
}
|
||||||
+1
-2
@@ -76,8 +76,7 @@ class BlockingFacadeTest {
|
|||||||
Duration.ofMillis(50),
|
Duration.ofMillis(50),
|
||||||
dev.caskeleton.messaging.api.destination.ConfirmationRequirement
|
dev.caskeleton.messaging.api.destination.ConfirmationRequirement
|
||||||
.REPLICATION_OR_PERSISTENCE_ACK,
|
.REPLICATION_OR_PERSISTENCE_ACK,
|
||||||
Optional.empty(),
|
Optional.empty());
|
||||||
java.util.Map.of());
|
|
||||||
|
|
||||||
assertThatThrownBy(
|
assertThatThrownBy(
|
||||||
() ->
|
() ->
|
||||||
|
|||||||
+55
-2
@@ -19,13 +19,13 @@ import dev.caskeleton.messaging.policy.CapabilityTier;
|
|||||||
import dev.caskeleton.messaging.policy.ConsumerPolicy;
|
import dev.caskeleton.messaging.policy.ConsumerPolicy;
|
||||||
import dev.caskeleton.messaging.policy.DeadLetterPolicy;
|
import dev.caskeleton.messaging.policy.DeadLetterPolicy;
|
||||||
import dev.caskeleton.messaging.policy.DestinationProfile;
|
import dev.caskeleton.messaging.policy.DestinationProfile;
|
||||||
|
import dev.caskeleton.messaging.policy.MessagingAdmissionController;
|
||||||
import dev.caskeleton.messaging.policy.PayloadPolicy;
|
import dev.caskeleton.messaging.policy.PayloadPolicy;
|
||||||
import dev.caskeleton.messaging.policy.PhysicalDestination;
|
import dev.caskeleton.messaging.policy.PhysicalDestination;
|
||||||
import dev.caskeleton.messaging.policy.ProducerPolicy;
|
import dev.caskeleton.messaging.policy.ProducerPolicy;
|
||||||
import dev.caskeleton.messaging.policy.RetryPolicy;
|
import dev.caskeleton.messaging.policy.RetryPolicy;
|
||||||
import dev.caskeleton.messaging.policy.SchemaPolicy;
|
import dev.caskeleton.messaging.policy.SchemaPolicy;
|
||||||
import dev.caskeleton.messaging.schema.SchemaCompatibility;
|
import dev.caskeleton.messaging.schema.SchemaCompatibility;
|
||||||
import dev.caskeleton.messaging.transport.BackpressureController;
|
|
||||||
import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator;
|
import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator;
|
||||||
import java.util.Set;
|
import java.util.Set;
|
||||||
import java.util.concurrent.CompletableFuture;
|
import java.util.concurrent.CompletableFuture;
|
||||||
@@ -51,7 +51,7 @@ class MessagingAutoConfigurationTest {
|
|||||||
.hasSingleBean(ValidatedDestinationRegistry.class)
|
.hasSingleBean(ValidatedDestinationRegistry.class)
|
||||||
.hasSingleBean(BlockingMessagePublisher.class)
|
.hasSingleBean(BlockingMessagePublisher.class)
|
||||||
.hasSingleBean(ReactiveMessagePublisher.class)
|
.hasSingleBean(ReactiveMessagePublisher.class)
|
||||||
.hasSingleBean(BackpressureController.class)
|
.hasSingleBean(MessagingAdmissionController.class)
|
||||||
.hasSingleBean(GracefulShutdownCoordinator.class));
|
.hasSingleBean(GracefulShutdownCoordinator.class));
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -236,6 +236,25 @@ class MessagingAutoConfigurationTest {
|
|||||||
false);
|
false);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@org.junit.jupiter.api.Test
|
||||||
|
@org.junit.jupiter.api.DisplayName("a broker profile the adapter cannot honour fails startup")
|
||||||
|
void anUnhonourableBrokerProfileFailsStartup() {
|
||||||
|
new org.springframework.boot.test.context.runner.ApplicationContextRunner()
|
||||||
|
.withConfiguration(
|
||||||
|
org.springframework.boot.autoconfigure.AutoConfigurations.of(
|
||||||
|
MessagingCoreAutoConfiguration.class, KafkaMessagingAutoConfiguration.class))
|
||||||
|
.withUserConfiguration(PublisherConfiguration.class, AutoCommittingKafkaProfile.class)
|
||||||
|
.withPropertyValues("spring.kafka.bootstrap-servers=localhost:9092")
|
||||||
|
.run(
|
||||||
|
context ->
|
||||||
|
org.assertj.core.api.Assertions.assertThat(context)
|
||||||
|
.getFailure()
|
||||||
|
.as(
|
||||||
|
"a validator nothing injects lets a profile boot and fail on the first"
|
||||||
|
+ " message that depends on the guarantee")
|
||||||
|
.hasMessageContaining("consumer auto commit is forbidden"));
|
||||||
|
}
|
||||||
|
|
||||||
@org.junit.jupiter.api.Test
|
@org.junit.jupiter.api.Test
|
||||||
@org.junit.jupiter.api.DisplayName("a superseded prefix fails startup instead of binding nothing")
|
@org.junit.jupiter.api.DisplayName("a superseded prefix fails startup instead of binding nothing")
|
||||||
void aSupersededPrefixFailsStartup() {
|
void aSupersededPrefixFailsStartup() {
|
||||||
@@ -364,6 +383,7 @@ class MessagingAutoConfigurationTest {
|
|||||||
java.util.Optional.empty(),
|
java.util.Optional.empty(),
|
||||||
dev.caskeleton.messaging.security.DestinationAccessPolicy
|
dev.caskeleton.messaging.security.DestinationAccessPolicy
|
||||||
.denyAll())),
|
.denyAll())),
|
||||||
|
java.util.List.of(),
|
||||||
new StaticProvider<dev.caskeleton.messaging.security.CredentialProvider>(),
|
new StaticProvider<dev.caskeleton.messaging.security.CredentialProvider>(),
|
||||||
new org.springframework.core.env.StandardEnvironment())
|
new org.springframework.core.env.StandardEnvironment())
|
||||||
.validate())
|
.validate())
|
||||||
@@ -394,6 +414,7 @@ class MessagingAutoConfigurationTest {
|
|||||||
java.util.Optional.empty(),
|
java.util.Optional.empty(),
|
||||||
dev.caskeleton.messaging.security.DestinationAccessPolicy
|
dev.caskeleton.messaging.security.DestinationAccessPolicy
|
||||||
.denyAll())),
|
.denyAll())),
|
||||||
|
java.util.List.of(),
|
||||||
new StaticProvider<dev.caskeleton.messaging.security.CredentialProvider>(),
|
new StaticProvider<dev.caskeleton.messaging.security.CredentialProvider>(),
|
||||||
new org.springframework.core.env.StandardEnvironment())
|
new org.springframework.core.env.StandardEnvironment())
|
||||||
.validate())
|
.validate())
|
||||||
@@ -491,3 +512,35 @@ class MessagingAutoConfigurationTest {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/** A Kafka profile that acknowledges on a timer rather than after the handler. */
|
||||||
|
@Configuration(proxyBeanMethods = false)
|
||||||
|
class AutoCommittingKafkaProfile {
|
||||||
|
|
||||||
|
@Bean
|
||||||
|
dev.caskeleton.messaging.kafka.KafkaBrokerProfile kafkaBrokerProfile() {
|
||||||
|
return KafkaProfiles.profile(true);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Builds a Kafka broker profile whose consumer acknowledges on a timer. */
|
||||||
|
final class KafkaProfiles {
|
||||||
|
|
||||||
|
private KafkaProfiles() {}
|
||||||
|
|
||||||
|
static dev.caskeleton.messaging.kafka.KafkaBrokerProfile profile(boolean enableAutoCommit) {
|
||||||
|
return new dev.caskeleton.messaging.kafka.KafkaBrokerProfile(
|
||||||
|
"kafka-primary",
|
||||||
|
true,
|
||||||
|
false,
|
||||||
|
java.util.List.of("localhost:9092"),
|
||||||
|
true,
|
||||||
|
"all",
|
||||||
|
5,
|
||||||
|
java.time.Duration.ofSeconds(30),
|
||||||
|
enableAutoCommit,
|
||||||
|
"orders",
|
||||||
|
false,
|
||||||
|
false);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
+320
@@ -0,0 +1,320 @@
|
|||||||
|
package dev.caskeleton.messaging.autoconfigure;
|
||||||
|
|
||||||
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.api.delivery.OrderingScope;
|
||||||
|
import dev.caskeleton.messaging.api.destination.DestinationKind;
|
||||||
|
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||||
|
import dev.caskeleton.messaging.policy.DestinationProfile;
|
||||||
|
import java.io.IOException;
|
||||||
|
import java.io.UncheckedIOException;
|
||||||
|
import java.nio.charset.StandardCharsets;
|
||||||
|
import java.nio.file.Files;
|
||||||
|
import java.nio.file.Path;
|
||||||
|
import java.util.ArrayList;
|
||||||
|
import java.util.List;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
import org.springframework.boot.autoconfigure.AutoConfigurations;
|
||||||
|
import org.springframework.boot.env.YamlPropertySourceLoader;
|
||||||
|
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
|
||||||
|
import org.springframework.core.env.PropertySource;
|
||||||
|
import org.springframework.core.io.ByteArrayResource;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Makes the configuration reference an executable statement rather than a description.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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.
|
||||||
|
*
|
||||||
|
* <p>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<PropertySource<?>> sources = new ArrayList<>();
|
||||||
|
YamlPropertySourceLoader loader = new YamlPropertySourceLoader();
|
||||||
|
List<String> blocks = yamlBlocks(reference());
|
||||||
|
assertThat(blocks)
|
||||||
|
.as("the configuration reference has stopped carrying YAML examples")
|
||||||
|
.isNotEmpty();
|
||||||
|
for (int index = 0; index < blocks.size(); index++) {
|
||||||
|
try {
|
||||||
|
sources.addAll(
|
||||||
|
loader.load(
|
||||||
|
"configuration-reference-" + index,
|
||||||
|
new ByteArrayResource(blocks.get(index).getBytes(StandardCharsets.UTF_8))));
|
||||||
|
} catch (IOException failure) {
|
||||||
|
throw new UncheckedIOException(failure);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return runner.withInitializer(
|
||||||
|
context -> sources.forEach(context.getEnvironment().getPropertySources()::addLast));
|
||||||
|
}
|
||||||
|
|
||||||
|
private static List<String> yamlBlocks(String document) {
|
||||||
|
List<String> blocks = new ArrayList<>();
|
||||||
|
StringBuilder current = null;
|
||||||
|
for (String line : document.lines().toList()) {
|
||||||
|
if (line.startsWith("```yaml")) {
|
||||||
|
current = new StringBuilder();
|
||||||
|
} else if (line.startsWith("```") && current != null) {
|
||||||
|
blocks.add(current.toString());
|
||||||
|
current = null;
|
||||||
|
} else if (current != null) {
|
||||||
|
current.append(line).append('\n');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return blocks;
|
||||||
|
}
|
||||||
|
|
||||||
|
private static String reference() {
|
||||||
|
Path candidate = Path.of("").toAbsolutePath();
|
||||||
|
while (candidate != null && !Files.isDirectory(candidate.resolve("docs/messaging"))) {
|
||||||
|
candidate = candidate.getParent();
|
||||||
|
}
|
||||||
|
if (candidate == null) {
|
||||||
|
throw new IllegalStateException("could not locate docs/messaging from the test cwd");
|
||||||
|
}
|
||||||
|
try {
|
||||||
|
return Files.readString(candidate.resolve("docs/messaging/configuration-reference.md"));
|
||||||
|
} catch (IOException failure) {
|
||||||
|
throw new UncheckedIOException(failure);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
+20
-13
@@ -13,13 +13,15 @@ import dev.caskeleton.messaging.policy.CapabilityTier;
|
|||||||
import dev.caskeleton.messaging.policy.ConsumerPolicy;
|
import dev.caskeleton.messaging.policy.ConsumerPolicy;
|
||||||
import dev.caskeleton.messaging.policy.DeadLetterPolicy;
|
import dev.caskeleton.messaging.policy.DeadLetterPolicy;
|
||||||
import dev.caskeleton.messaging.policy.DestinationProfile;
|
import dev.caskeleton.messaging.policy.DestinationProfile;
|
||||||
|
import dev.caskeleton.messaging.policy.InFlightLimiter;
|
||||||
|
import dev.caskeleton.messaging.policy.MessagingAdmissionController;
|
||||||
|
import dev.caskeleton.messaging.policy.PayloadLimitGuard;
|
||||||
import dev.caskeleton.messaging.policy.PayloadPolicy;
|
import dev.caskeleton.messaging.policy.PayloadPolicy;
|
||||||
import dev.caskeleton.messaging.policy.PhysicalDestination;
|
import dev.caskeleton.messaging.policy.PhysicalDestination;
|
||||||
import dev.caskeleton.messaging.policy.ProducerPolicy;
|
import dev.caskeleton.messaging.policy.ProducerPolicy;
|
||||||
import dev.caskeleton.messaging.policy.RetryPolicy;
|
import dev.caskeleton.messaging.policy.RetryPolicy;
|
||||||
import dev.caskeleton.messaging.policy.SchemaPolicy;
|
import dev.caskeleton.messaging.policy.SchemaPolicy;
|
||||||
import dev.caskeleton.messaging.schema.SchemaCompatibility;
|
import dev.caskeleton.messaging.schema.SchemaCompatibility;
|
||||||
import dev.caskeleton.messaging.transport.BackpressureController;
|
|
||||||
import java.util.List;
|
import java.util.List;
|
||||||
import java.util.Map;
|
import java.util.Map;
|
||||||
import java.util.Set;
|
import java.util.Set;
|
||||||
@@ -51,9 +53,16 @@ class MessagingEndpointTest {
|
|||||||
false);
|
false);
|
||||||
}
|
}
|
||||||
|
|
||||||
private static MessagingEndpoint endpoint(BackpressureController backpressure) {
|
private static MessagingEndpoint endpoint(MessagingAdmissionController admission) {
|
||||||
return new MessagingEndpoint(
|
return new MessagingEndpoint(new ValidatedDestinationRegistry(List.of(profile())), admission);
|
||||||
new ValidatedDestinationRegistry(List.of(profile())), backpressure);
|
}
|
||||||
|
|
||||||
|
/** The real gate, so the endpoint reports what a publish actually occupies. */
|
||||||
|
private static MessagingAdmissionController admission(int global, int perDestination) {
|
||||||
|
return new MessagingAdmissionController(
|
||||||
|
new PayloadLimitGuard(PayloadPolicy.defaults()),
|
||||||
|
new InFlightLimiter(global, java.time.Duration.ZERO),
|
||||||
|
perDestination);
|
||||||
}
|
}
|
||||||
|
|
||||||
@SuppressWarnings("unchecked")
|
@SuppressWarnings("unchecked")
|
||||||
@@ -63,7 +72,7 @@ class MessagingEndpointTest {
|
|||||||
|
|
||||||
@Test
|
@Test
|
||||||
void theReportNamesEveryRegisteredDestination() {
|
void theReportNamesEveryRegisteredDestination() {
|
||||||
Map<String, Object> report = endpoint(new BackpressureController(100, 10)).messaging();
|
Map<String, Object> report = endpoint(admission(100, 10)).messaging();
|
||||||
|
|
||||||
assertThat(destinations(report))
|
assertThat(destinations(report))
|
||||||
.singleElement()
|
.singleElement()
|
||||||
@@ -72,8 +81,7 @@ class MessagingEndpointTest {
|
|||||||
|
|
||||||
@Test
|
@Test
|
||||||
void theReportCarriesTheDeclaredGuaranteesAnOperatorNeeds() {
|
void theReportCarriesTheDeclaredGuaranteesAnOperatorNeeds() {
|
||||||
Map<String, Object> entry =
|
Map<String, Object> entry = destinations(endpoint(admission(100, 10)).messaging()).get(0);
|
||||||
destinations(endpoint(new BackpressureController(100, 10)).messaging()).get(0);
|
|
||||||
|
|
||||||
assertThat(entry)
|
assertThat(entry)
|
||||||
.containsEntry("deliveryGuarantee", "AT_LEAST_ONCE")
|
.containsEntry("deliveryGuarantee", "AT_LEAST_ONCE")
|
||||||
@@ -84,11 +92,11 @@ class MessagingEndpointTest {
|
|||||||
|
|
||||||
@Test
|
@Test
|
||||||
void theReportShowsCurrentInFlightWork() {
|
void theReportShowsCurrentInFlightWork() {
|
||||||
BackpressureController backpressure = new BackpressureController(100, 10);
|
MessagingAdmissionController admission = admission(100, 10);
|
||||||
backpressure.tryAcquire("orders.v1");
|
admission.admit("orders.v1", 128);
|
||||||
backpressure.tryAcquire("orders.v1");
|
admission.admit("orders.v1", 128);
|
||||||
|
|
||||||
Map<String, Object> report = endpoint(backpressure).messaging();
|
Map<String, Object> report = endpoint(admission).messaging();
|
||||||
|
|
||||||
assertThat(report).containsEntry("globalInFlight", 2);
|
assertThat(report).containsEntry("globalInFlight", 2);
|
||||||
assertThat(destinations(report).get(0)).containsEntry("inFlight", 2);
|
assertThat(destinations(report).get(0)).containsEntry("inFlight", 2);
|
||||||
@@ -96,8 +104,7 @@ class MessagingEndpointTest {
|
|||||||
|
|
||||||
@Test
|
@Test
|
||||||
void theReportCarriesNoPerMessageIdentity() {
|
void theReportCarriesNoPerMessageIdentity() {
|
||||||
Map<String, Object> entry =
|
Map<String, Object> entry = destinations(endpoint(admission(100, 10)).messaging()).get(0);
|
||||||
destinations(endpoint(new BackpressureController(100, 10)).messaging()).get(0);
|
|
||||||
|
|
||||||
assertThat(entry.keySet())
|
assertThat(entry.keySet())
|
||||||
.as("an actuator response that echoes message content is a re-identification surface")
|
.as("an actuator response that echoes message content is a re-identification surface")
|
||||||
|
|||||||
+5
-1
@@ -59,7 +59,11 @@ class MessagingLiveRoundTripQualificationTest {
|
|||||||
private static final String TOPIC = "order-events";
|
private static final String TOPIC = "order-events";
|
||||||
private static final DestinationName DLQ = new DestinationName("order-events-dlq");
|
private static final DestinationName DLQ = new DestinationName("order-events-dlq");
|
||||||
|
|
||||||
@Container static final KafkaContainer KAFKA = new KafkaContainer("apache/kafka:3.8.0");
|
// The version the support matrix certifies and every other fixture pins. Qualifying runtime
|
||||||
|
// membership against 3.8.0 proved the membership on a broker two minors below the one the matrix
|
||||||
|
// calls certified, so the one test that decides whether the starter may reach a deployment's
|
||||||
|
// classpath was the only one not run against what a deployment gets.
|
||||||
|
@Container static final KafkaContainer KAFKA = new KafkaContainer("apache/kafka:4.1.0");
|
||||||
|
|
||||||
static boolean dockerAvailable() {
|
static boolean dockerAvailable() {
|
||||||
return DockerClientFactory.instance().isDockerAvailable();
|
return DockerClientFactory.instance().isDockerAvailable();
|
||||||
|
|||||||
+203
@@ -0,0 +1,203 @@
|
|||||||
|
package dev.caskeleton.messaging.autoconfigure;
|
||||||
|
|
||||||
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.api.MessageEnvelope;
|
||||||
|
import dev.caskeleton.messaging.api.MessageId;
|
||||||
|
import dev.caskeleton.messaging.api.ProducerId;
|
||||||
|
import dev.caskeleton.messaging.api.destination.MessageDestination;
|
||||||
|
import dev.caskeleton.messaging.api.publish.MessagePublisher;
|
||||||
|
import dev.caskeleton.messaging.api.publish.PublishOptions;
|
||||||
|
import dev.caskeleton.messaging.api.publish.PublishResult;
|
||||||
|
import dev.caskeleton.messaging.outbox.OutboxEnvelopeFactory;
|
||||||
|
import dev.caskeleton.messaging.reliability.OutboxLease;
|
||||||
|
import dev.caskeleton.messaging.reliability.OutboxRecord;
|
||||||
|
import dev.caskeleton.messaging.reliability.OutboxRepository;
|
||||||
|
import dev.caskeleton.messaging.reliability.OutboxTransitionResult;
|
||||||
|
import java.time.Duration;
|
||||||
|
import java.time.Instant;
|
||||||
|
import java.util.List;
|
||||||
|
import java.util.Optional;
|
||||||
|
import java.util.concurrent.CompletionStage;
|
||||||
|
import java.util.concurrent.CountDownLatch;
|
||||||
|
import java.util.concurrent.TimeUnit;
|
||||||
|
import org.junit.jupiter.api.DisplayName;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
import org.springframework.boot.autoconfigure.AutoConfigurations;
|
||||||
|
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
|
||||||
|
import org.springframework.context.annotation.Bean;
|
||||||
|
import org.springframework.context.annotation.Configuration;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Whether a started context drives the outbox relay.
|
||||||
|
*
|
||||||
|
* <p>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 <T> CompletionStage<PublishResult> publish(
|
||||||
|
MessageDestination<T> destination, MessageEnvelope<T> message, PublishOptions options) {
|
||||||
|
throw new UnsupportedOperationException("this relay never claims a row to publish");
|
||||||
|
}
|
||||||
|
};
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* An outbox that has nothing to publish and counts being asked.
|
||||||
|
*
|
||||||
|
* <p>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<OutboxLease> claimBatch(
|
||||||
|
String owner, int batchSize, Duration leaseDuration, Instant now, int maxAttempts) {
|
||||||
|
claimed.countDown();
|
||||||
|
return List.of();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void append(OutboxRecord record) {
|
||||||
|
throw new UnsupportedOperationException("not used by this test");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public List<OutboxRecord> leaseBatch(int batchSize, Duration leaseDuration, Instant now) {
|
||||||
|
throw new UnsupportedOperationException("not used by this test");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public List<OutboxLease> claimBatch(
|
||||||
|
String owner, int batchSize, Duration leaseDuration, Instant now) {
|
||||||
|
throw new UnsupportedOperationException("not used by this test");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void markPublished(MessageId messageId, Instant now) {
|
||||||
|
throw new UnsupportedOperationException("not used by this test");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public OutboxTransitionResult markPublished(OutboxLease lease, Instant now) {
|
||||||
|
throw new UnsupportedOperationException("not used by this test");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void markAmbiguous(MessageId messageId, String failureCode, Instant now) {
|
||||||
|
throw new UnsupportedOperationException("not used by this test");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public OutboxTransitionResult markAmbiguous(
|
||||||
|
OutboxLease lease, String failureCode, Instant now) {
|
||||||
|
throw new UnsupportedOperationException("not used by this test");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public OutboxTransitionResult markAmbiguous(
|
||||||
|
OutboxLease lease, String failureCode, Instant now, Instant nextAttemptAt) {
|
||||||
|
throw new UnsupportedOperationException("not used by this test");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public OutboxTransitionResult markExhausted(OutboxLease lease, String reason, Instant now) {
|
||||||
|
throw new UnsupportedOperationException("not used by this test");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void markFailed(MessageId messageId, String failureCode, Instant now) {
|
||||||
|
throw new UnsupportedOperationException("not used by this test");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public OutboxTransitionResult markFailed(OutboxLease lease, String failureCode, Instant now) {
|
||||||
|
throw new UnsupportedOperationException("not used by this test");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void releaseLease(MessageId messageId) {
|
||||||
|
throw new UnsupportedOperationException("not used by this test");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public OutboxTransitionResult releaseLease(OutboxLease lease) {
|
||||||
|
throw new UnsupportedOperationException("not used by this test");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public Optional<OutboxRecord> find(MessageId messageId) {
|
||||||
|
throw new UnsupportedOperationException("not used by this test");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public int purgePublishedBefore(Instant publishedBefore) {
|
||||||
|
throw new UnsupportedOperationException("not used by this test");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public int purgePublishedBefore(Instant publishedBefore, int limit) {
|
||||||
|
throw new UnsupportedOperationException("not used by this test");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
+78
@@ -0,0 +1,78 @@
|
|||||||
|
package dev.caskeleton.messaging.autoconfigure;
|
||||||
|
|
||||||
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||||
|
|
||||||
|
import dev.caskeleton.messaging.api.error.MessageBackpressureException;
|
||||||
|
import dev.caskeleton.messaging.policy.InFlightLimiter;
|
||||||
|
import dev.caskeleton.messaging.policy.MessagingAdmissionController;
|
||||||
|
import dev.caskeleton.messaging.policy.PayloadLimitGuard;
|
||||||
|
import dev.caskeleton.messaging.policy.PayloadPolicy;
|
||||||
|
import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator;
|
||||||
|
import java.time.Duration;
|
||||||
|
import java.time.Instant;
|
||||||
|
import java.util.concurrent.atomic.AtomicReference;
|
||||||
|
import org.junit.jupiter.api.DisplayName;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* What a context stop actually does to in-flight messaging work.
|
||||||
|
*
|
||||||
|
* <p>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<Instant> clock = new AtomicReference<>(NOW);
|
||||||
|
MessagingShutdownLifecycle lifecycle =
|
||||||
|
new MessagingShutdownLifecycle(
|
||||||
|
admission,
|
||||||
|
leaking,
|
||||||
|
Duration.ofMillis(150),
|
||||||
|
() -> clock.getAndUpdate(current -> current.plusMillis(100)));
|
||||||
|
lifecycle.start();
|
||||||
|
|
||||||
|
lifecycle.stop();
|
||||||
|
|
||||||
|
assertThat(leaking.inFlight())
|
||||||
|
.as("work still running at the deadline is abandoned unsettled, not counted as done")
|
||||||
|
.isEqualTo(1);
|
||||||
|
assertThat(leaking.abandonedWorkAtDeadline(clock.get())).isTrue();
|
||||||
|
}
|
||||||
|
|
||||||
|
private MessagingShutdownLifecycle lifecycle(Duration drainDeadline, Instant fixed) {
|
||||||
|
return new MessagingShutdownLifecycle(admission, drain, drainDeadline, () -> fixed);
|
||||||
|
}
|
||||||
|
}
|
||||||
+29
-6
@@ -132,18 +132,41 @@ class MessagingStarterOffContractTest {
|
|||||||
}
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
@DisplayName("selecting Rabbit assembles Rabbit and not Kafka")
|
@DisplayName("selecting Rabbit is refused, and the message says the transport is not finished")
|
||||||
void selectingRabbitAssemblesOnlyRabbit() {
|
void selectingRabbitIsRefused() {
|
||||||
withAPublisher()
|
// This test used to run under `withAPublisher()` and assert the context started. The fake
|
||||||
|
// MessagePublisher tripped @ConditionalOnMissingBean and removed the very bean whose missing
|
||||||
|
// dependency is the defect — so a configuration that cannot start in any deployment passed as
|
||||||
|
// "assembles Rabbit and not Kafka". Without the fake, the real behaviour appears.
|
||||||
|
//
|
||||||
|
// Rabbit ships validators and a security configurer and no MessagingTransport, because its
|
||||||
|
// native channel publisher has only test implementations. That is refused at selection now,
|
||||||
|
// where the message can say so, rather than surfacing as "No qualifying bean of type
|
||||||
|
// MessagingTransport" from inside the core configuration.
|
||||||
|
runner
|
||||||
.withPropertyValues("app.messaging.enabled=true", "app.messaging.broker=rabbit")
|
.withPropertyValues("app.messaging.enabled=true", "app.messaging.broker=rabbit")
|
||||||
.run(
|
.run(
|
||||||
context -> {
|
context -> {
|
||||||
assertThat(context).hasNotFailed();
|
assertThat(context).hasFailed();
|
||||||
assertThat(context).hasSingleBean(RabbitMessagingAutoConfiguration.class);
|
assertThat(context.getStartupFailure())
|
||||||
assertThat(context).doesNotHaveBean(KafkaMessagingAutoConfiguration.class);
|
.rootCause()
|
||||||
|
.hasMessageContaining("app.messaging.broker=rabbit")
|
||||||
|
.hasMessageContaining("no MessagingTransport")
|
||||||
|
.hasMessageContaining("kafka");
|
||||||
});
|
});
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("a fake publisher does not make an unassemblable transport look assemblable")
|
||||||
|
void aFakePublisherDoesNotHideAnUnassemblableTransport() {
|
||||||
|
// The guard on the test above. Supplying a MessagePublisher removes the dependency that fails,
|
||||||
|
// so if the refusal ever moves back to bean wiring this case goes green while the deployment
|
||||||
|
// stays broken. Selection-time refusal is what makes it fail either way.
|
||||||
|
withAPublisher()
|
||||||
|
.withPropertyValues("app.messaging.enabled=true", "app.messaging.broker=rabbit")
|
||||||
|
.run(context -> assertThat(context).hasFailed());
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
@DisplayName("MSG-INT-003: a selected transport now assembles a publisher")
|
@DisplayName("MSG-INT-003: a selected transport now assembles a publisher")
|
||||||
void aSelectedTransportAssemblesAPublisher() {
|
void aSelectedTransportAssemblesAPublisher() {
|
||||||
|
|||||||
+107
-21
@@ -1,20 +1,27 @@
|
|||||||
package dev.caskeleton.messaging.testkit;
|
package dev.caskeleton.messaging.testkit;
|
||||||
|
|
||||||
import java.time.Instant;
|
import java.time.Instant;
|
||||||
|
import java.util.LinkedHashMap;
|
||||||
|
import java.util.Map;
|
||||||
import java.util.Objects;
|
import java.util.Objects;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* One scenario actually exercised against one broker image.
|
* One scenario actually exercised against one broker image.
|
||||||
*
|
*
|
||||||
* <p>{@code BrokerFailureMatrix.shipped()} hard-coded every scenario as {@code LIVE_BROKER} for
|
* <p>Coverage used to be a constant: every scenario marked live-broker for both brokers, with the
|
||||||
* both brokers, and the suite that "verified" the matrix asserted the contents of that same map. A
|
* suite that "verified" the matrix asserting the contents of that same map. A test comparing a
|
||||||
* test comparing a constant to itself passes on a machine with no Docker at all, and the support
|
* constant to itself passes on a machine with no Docker at all, and the support matrix it feeds
|
||||||
* matrix it feeds then tells an adopter that connection-cut and confirm-timeout are certified when
|
* then tells an adopter that connection-cut and confirm-timeout are certified when neither has ever
|
||||||
* neither has ever run.
|
* run.
|
||||||
*
|
*
|
||||||
* <p>This record is what a lane emits after running. The image reference and the commit are here
|
* <p>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
|
* 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.
|
* them the evidence cannot be checked against anything later.
|
||||||
|
*
|
||||||
|
* <p>{@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(
|
public record BrokerCertificationEvidence(
|
||||||
String adapter,
|
String adapter,
|
||||||
@@ -37,24 +44,103 @@ public record BrokerCertificationEvidence(
|
|||||||
throw new IllegalArgumentException(
|
throw new IllegalArgumentException(
|
||||||
"evidence names the adapter, the broker image and the test that produced it");
|
"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() {
|
public String toJson() {
|
||||||
return "{\"adapter\":\""
|
String[] values = {
|
||||||
+ adapter
|
adapter, brokerImage, scenario.name(), testId, outcome, gitCommit, observedAt.toString()
|
||||||
+ "\",\"brokerImage\":\""
|
};
|
||||||
+ brokerImage
|
StringBuilder json = new StringBuilder("{");
|
||||||
+ "\",\"scenario\":\""
|
for (int index = 0; index < FIELDS.length; index++) {
|
||||||
+ scenario.name()
|
if (index > 0) {
|
||||||
+ "\",\"testId\":\""
|
json.append(',');
|
||||||
+ testId
|
}
|
||||||
+ "\",\"outcome\":\""
|
json.append('"').append(FIELDS[index]).append("\":\"").append(values[index]).append('"');
|
||||||
+ outcome
|
}
|
||||||
+ "\",\"gitCommit\":\""
|
return json.append('}').toString();
|
||||||
+ gitCommit
|
}
|
||||||
+ "\",\"observedAt\":\""
|
|
||||||
+ observedAt
|
/**
|
||||||
+ "\"}";
|
* Reads back one line a lane wrote.
|
||||||
|
*
|
||||||
|
* <p>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<String, String> fields = parse(json.trim());
|
||||||
|
for (String field : FIELDS) {
|
||||||
|
if (!fields.containsKey(field)) {
|
||||||
|
throw new IllegalArgumentException(
|
||||||
|
"certification evidence is missing '" + field + "': " + json);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if (fields.size() != FIELDS.length) {
|
||||||
|
throw new IllegalArgumentException(
|
||||||
|
"certification evidence carries fields this release does not define: " + fields.keySet());
|
||||||
|
}
|
||||||
|
return new BrokerCertificationEvidence(
|
||||||
|
fields.get("adapter"),
|
||||||
|
fields.get("brokerImage"),
|
||||||
|
NetworkFaultScenario.byName(fields.get("scenario")),
|
||||||
|
fields.get("testId"),
|
||||||
|
fields.get("outcome"),
|
||||||
|
fields.get("gitCommit"),
|
||||||
|
Instant.parse(fields.get("observedAt")));
|
||||||
|
}
|
||||||
|
|
||||||
|
private static Map<String, String> parse(String json) {
|
||||||
|
if (json.length() < 2 || json.charAt(0) != '{' || json.charAt(json.length() - 1) != '}') {
|
||||||
|
throw new IllegalArgumentException("certification evidence is not a JSON object: " + json);
|
||||||
|
}
|
||||||
|
Map<String, String> fields = new LinkedHashMap<>();
|
||||||
|
String body = json.substring(1, json.length() - 1);
|
||||||
|
int cursor = 0;
|
||||||
|
while (cursor < body.length()) {
|
||||||
|
int keyStart = body.indexOf('"', cursor);
|
||||||
|
if (keyStart < 0) {
|
||||||
|
break;
|
||||||
|
}
|
||||||
|
int keyEnd = body.indexOf('"', keyStart + 1);
|
||||||
|
int valueStart = body.indexOf('"', keyEnd + 1);
|
||||||
|
int valueEnd = valueStart < 0 ? -1 : body.indexOf('"', valueStart + 1);
|
||||||
|
if (keyEnd < 0 || valueStart < 0 || valueEnd < 0) {
|
||||||
|
throw new IllegalArgumentException("certification evidence is truncated: " + json);
|
||||||
|
}
|
||||||
|
fields.put(body.substring(keyStart + 1, keyEnd), body.substring(valueStart + 1, valueEnd));
|
||||||
|
cursor = valueEnd + 1;
|
||||||
|
}
|
||||||
|
return fields;
|
||||||
|
}
|
||||||
|
|
||||||
|
private static void requireUnescaped(String value, String field) {
|
||||||
|
if (value.indexOf('"') >= 0 || value.indexOf('\\') >= 0) {
|
||||||
|
throw new IllegalArgumentException(
|
||||||
|
field + " must not contain a quote or a backslash: " + field + "='" + value + "'");
|
||||||
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+29
-42
@@ -75,6 +75,17 @@ public final class BrokerFailureMatrix {
|
|||||||
.toList();
|
.toList();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Reports whether an adapter has been run against a live broker at all.
|
||||||
|
*
|
||||||
|
* @param adapter the adapter module name
|
||||||
|
* @return true when at least one scenario has live-broker evidence
|
||||||
|
*/
|
||||||
|
public boolean hasLiveBrokerCoverage(String adapter) {
|
||||||
|
return NetworkFaultScenario.all().stream()
|
||||||
|
.anyMatch(scenario -> coverageOf(adapter, scenario) == Coverage.LIVE_BROKER);
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Reports whether an adapter covers every scenario.
|
* Reports whether an adapter covers every scenario.
|
||||||
*
|
*
|
||||||
@@ -94,22 +105,13 @@ public final class BrokerFailureMatrix {
|
|||||||
return List.copyOf(coverage.keySet());
|
return List.copyOf(coverage.keySet());
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* Returns the matrix the platform ships with.
|
|
||||||
*
|
|
||||||
* <p>Kafka and RabbitMQ are Stable and cover everything. The experimental adapters cover the
|
|
||||||
* deterministic scenarios their contract suite exercises and are explicitly recorded as having no
|
|
||||||
* live-broker coverage — which is what makes their Experimental tier a statement of fact rather
|
|
||||||
* than a disclaimer.
|
|
||||||
*
|
|
||||||
* @return the shipped coverage matrix
|
|
||||||
*/
|
|
||||||
/**
|
/**
|
||||||
* Builds a matrix from evidence a lane actually produced.
|
* Builds a matrix from evidence a lane actually produced.
|
||||||
*
|
*
|
||||||
* <p>Anything with no evidence is {@link Coverage#NOT_COVERED}. That is the whole difference from
|
* <p>Anything with no evidence is {@link Coverage#NOT_COVERED}. A hard-coded matrix marked every
|
||||||
* {@link #shipped()}: a scenario is covered because a test ran it against a broker, not because
|
* scenario as live-broker coverage for both brokers, and the suite that checked it asserted the
|
||||||
* somebody wrote the constant.
|
* same constants, so the whole claim passed on a machine with no Docker. A scenario is covered
|
||||||
|
* because a test ran it against a broker, not because somebody wrote the constant.
|
||||||
*
|
*
|
||||||
* @param evidence what the certification lane observed
|
* @param evidence what the certification lane observed
|
||||||
*/
|
*/
|
||||||
@@ -118,43 +120,28 @@ public final class BrokerFailureMatrix {
|
|||||||
Objects.requireNonNull(evidence, "evidence must not be null");
|
Objects.requireNonNull(evidence, "evidence must not be null");
|
||||||
BrokerFailureMatrix matrix = new BrokerFailureMatrix();
|
BrokerFailureMatrix matrix = new BrokerFailureMatrix();
|
||||||
for (BrokerCertificationEvidence observed : evidence) {
|
for (BrokerCertificationEvidence observed : evidence) {
|
||||||
|
requireOutcomeMatchesExpectation(observed);
|
||||||
matrix.record(observed.adapter(), observed.scenario(), Coverage.LIVE_BROKER);
|
matrix.record(observed.adapter(), observed.scenario(), Coverage.LIVE_BROKER);
|
||||||
}
|
}
|
||||||
return matrix;
|
return matrix;
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The declared shipping matrix.
|
* Refuses evidence whose observed outcome contradicts the scenario it claims to cover.
|
||||||
*
|
*
|
||||||
* @deprecated These constants describe what the platform intends to certify, not what any run
|
* <p>Nothing compared the two, so a run that reported a definite rejection where the scenario
|
||||||
* proved. Every scenario was marked {@code LIVE_BROKER} for both brokers and the suite that
|
* says the outcome is unknowable counted as coverage of that scenario. That is worse than no
|
||||||
* checked the matrix asserted the same map, so it passed on a machine with no Docker. Use
|
* evidence: it certifies the adapter for exactly the behaviour it got wrong, and the support
|
||||||
* {@link #from(java.util.Collection)} with a lane's evidence; this remains only so an
|
* matrix then tells an adopter the case is handled.
|
||||||
* existing caller keeps compiling while it migrates.
|
|
||||||
*/
|
*/
|
||||||
@Deprecated
|
private static void requireOutcomeMatchesExpectation(BrokerCertificationEvidence observed) {
|
||||||
public static BrokerFailureMatrix shipped() {
|
String expected = observed.scenario().expectation().name();
|
||||||
BrokerFailureMatrix matrix = new BrokerFailureMatrix();
|
if (!expected.equals(observed.outcome())) {
|
||||||
for (NetworkFaultScenario scenario : NetworkFaultScenario.all()) {
|
throw new IllegalArgumentException(
|
||||||
matrix.record("messaging-kafka", scenario, Coverage.LIVE_BROKER);
|
"%s recorded %s for %s, which expects %s; a run that disagrees with the scenario is a"
|
||||||
matrix.record("messaging-rabbit", scenario, Coverage.LIVE_BROKER);
|
.formatted(
|
||||||
|
observed.adapter(), observed.outcome(), observed.scenario().name(), expected)
|
||||||
|
+ " failing certification, not coverage of it (%s)".formatted(observed.testId()));
|
||||||
}
|
}
|
||||||
matrix.record(
|
|
||||||
"messaging-pulsar-experimental",
|
|
||||||
NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE,
|
|
||||||
Coverage.DETERMINISTIC);
|
|
||||||
matrix.record(
|
|
||||||
"messaging-pulsar-experimental",
|
|
||||||
NetworkFaultScenario.CONFIRM_TIMEOUT,
|
|
||||||
Coverage.DETERMINISTIC);
|
|
||||||
matrix.record(
|
|
||||||
"messaging-nats-experimental",
|
|
||||||
NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE,
|
|
||||||
Coverage.DETERMINISTIC);
|
|
||||||
matrix.record(
|
|
||||||
"messaging-nats-experimental",
|
|
||||||
NetworkFaultScenario.CONFIRM_TIMEOUT,
|
|
||||||
Coverage.DETERMINISTIC);
|
|
||||||
return matrix;
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+84
@@ -0,0 +1,84 @@
|
|||||||
|
package dev.caskeleton.messaging.testkit;
|
||||||
|
|
||||||
|
import java.io.IOException;
|
||||||
|
import java.io.InputStream;
|
||||||
|
import java.nio.charset.StandardCharsets;
|
||||||
|
import java.util.List;
|
||||||
|
import java.util.Set;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The fault scenarios this repository's certification lane has actually exercised.
|
||||||
|
*
|
||||||
|
* <p>Read from a manifest a run produced, not from a list somebody typed. It was the list: an
|
||||||
|
* author added a line and the compatibility matrix, the cross-broker suite and the support matrix
|
||||||
|
* all believed it, on a machine that may never have started a container. "Certified against a live
|
||||||
|
* broker" then meant "a developer wrote that down", which is the one thing a certification claim
|
||||||
|
* must not mean.
|
||||||
|
*
|
||||||
|
* <p>The manifest is committed because a release claim has to survive the build that produced it —
|
||||||
|
* a matrix that reads {@code build/} answers differently on a clean checkout. What stops it from
|
||||||
|
* being hand-written again is the gate: {@code verifyMessagingCertificationEvidence} runs the lane
|
||||||
|
* against a real broker and refuses to pass when this file claims a scenario the run did not
|
||||||
|
* produce. Editing the file without running the lane fails the build; running the lane rewrites the
|
||||||
|
* file.
|
||||||
|
*
|
||||||
|
* <p>An absent or empty manifest is not an error here. It means no scenario has evidence, so every
|
||||||
|
* scenario is {@link BrokerFailureMatrix.Coverage#NOT_COVERED} and every Stable claim that depends
|
||||||
|
* on evidence fails — which is the correct reading of "nothing has been run".
|
||||||
|
*/
|
||||||
|
public final class CertifiedEvidence {
|
||||||
|
|
||||||
|
/** Where the certification lane writes what it proved, and where the matrix reads it. */
|
||||||
|
public static final String MANIFEST_RESOURCE = "/messaging/broker-certification-evidence.jsonl";
|
||||||
|
|
||||||
|
private static final List<BrokerCertificationEvidence> RECORDED = load();
|
||||||
|
|
||||||
|
private CertifiedEvidence() {}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Returns what the certification lane recorded.
|
||||||
|
*
|
||||||
|
* @return the evidence this repository can show
|
||||||
|
*/
|
||||||
|
public static List<BrokerCertificationEvidence> recorded() {
|
||||||
|
return RECORDED;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Returns the scenarios an adapter has no evidence for.
|
||||||
|
*
|
||||||
|
* <p>Named explicitly so the gap is a fact in the build rather than a silent absence.
|
||||||
|
*
|
||||||
|
* @param adapter the adapter module name
|
||||||
|
* @return the uncovered scenarios
|
||||||
|
*/
|
||||||
|
public static List<NetworkFaultScenario> knownGaps(String adapter) {
|
||||||
|
Set<NetworkFaultScenario> covered =
|
||||||
|
recorded().stream()
|
||||||
|
.filter(evidence -> evidence.adapter().equals(adapter))
|
||||||
|
.map(BrokerCertificationEvidence::scenario)
|
||||||
|
.collect(java.util.stream.Collectors.toUnmodifiableSet());
|
||||||
|
return NetworkFaultScenario.all().stream()
|
||||||
|
.filter(scenario -> !covered.contains(scenario))
|
||||||
|
.toList();
|
||||||
|
}
|
||||||
|
|
||||||
|
private static List<BrokerCertificationEvidence> load() {
|
||||||
|
try (InputStream manifest = CertifiedEvidence.class.getResourceAsStream(MANIFEST_RESOURCE)) {
|
||||||
|
if (manifest == null) {
|
||||||
|
return List.of();
|
||||||
|
}
|
||||||
|
return new String(manifest.readAllBytes(), StandardCharsets.UTF_8)
|
||||||
|
.lines()
|
||||||
|
.map(String::trim)
|
||||||
|
.filter(line -> !line.isEmpty())
|
||||||
|
.map(BrokerCertificationEvidence::fromJson)
|
||||||
|
.toList();
|
||||||
|
} catch (IOException failure) {
|
||||||
|
// Not swallowed into "no evidence": a manifest that exists and cannot be read is a broken
|
||||||
|
// build, and reporting it as an absence would quietly demote every adapter instead.
|
||||||
|
throw new IllegalStateException(
|
||||||
|
"could not read the broker certification manifest " + MANIFEST_RESOURCE, failure);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
+28
-15
@@ -9,8 +9,11 @@ import java.util.Objects;
|
|||||||
*
|
*
|
||||||
* <p>Held as code with a test over it rather than as a document, because a support matrix that
|
* <p>Held as code with a test over it rather than as a document, because a support matrix that
|
||||||
* lives only in prose drifts the first time an adapter is added. The test asserts the rules the
|
* lives only in prose drifts the first time an adapter is added. The test asserts the rules the
|
||||||
* design fixes: a Stable adapter must run the shared contract, and an Experimental adapter must be
|
* design fixes: a Stable adapter must run the shared contract and be certified against a live
|
||||||
* disabled by default.
|
* broker, and an Experimental adapter must be disabled by default.
|
||||||
|
*
|
||||||
|
* <p>The certification claim is derived from lane evidence rather than declared beside the tier, so
|
||||||
|
* an adapter cannot be promoted by editing a boolean.
|
||||||
*/
|
*/
|
||||||
public final class CompatibilityMatrix {
|
public final class CompatibilityMatrix {
|
||||||
|
|
||||||
@@ -36,15 +39,27 @@ public final class CompatibilityMatrix {
|
|||||||
* @param tier the support tier
|
* @param tier the support tier
|
||||||
* @param runsSharedContract whether the module runs {@link MessagingAdapterContract}
|
* @param runsSharedContract whether the module runs {@link MessagingAdapterContract}
|
||||||
* @param enabledByDefault whether the adapter is active without an explicit opt-in
|
* @param enabledByDefault whether the adapter is active without an explicit opt-in
|
||||||
* @param hasLiveBrokerCertification whether a container-backed suite exercises a real broker
|
|
||||||
*/
|
*/
|
||||||
public record Entry(
|
public record Entry(
|
||||||
String adapter,
|
String adapter,
|
||||||
List<String> brokerVersions,
|
List<String> brokerVersions,
|
||||||
Tier tier,
|
Tier tier,
|
||||||
boolean runsSharedContract,
|
boolean runsSharedContract,
|
||||||
boolean enabledByDefault,
|
boolean enabledByDefault) {
|
||||||
boolean hasLiveBrokerCertification) {
|
|
||||||
|
/**
|
||||||
|
* Reports whether a lane has run this adapter against a real broker.
|
||||||
|
*
|
||||||
|
* <p>Read from the evidence rather than declared. As a field it was a boolean an author set
|
||||||
|
* next to the tier, and RabbitMQ carried {@code true} while no fault scenario had ever been
|
||||||
|
* executed against it — the same shape as the coverage matrix that used to assert its own
|
||||||
|
* constants.
|
||||||
|
*
|
||||||
|
* @return true when {@link CertifiedEvidence} has live-broker evidence for this adapter
|
||||||
|
*/
|
||||||
|
public boolean hasLiveBrokerCertification() {
|
||||||
|
return BrokerFailureMatrix.from(CertifiedEvidence.recorded()).hasLiveBrokerCoverage(adapter);
|
||||||
|
}
|
||||||
|
|
||||||
public Entry {
|
public Entry {
|
||||||
Objects.requireNonNull(tier, "tier must not be null");
|
Objects.requireNonNull(tier, "tier must not be null");
|
||||||
@@ -67,16 +82,20 @@ public final class CompatibilityMatrix {
|
|||||||
// the locked client is 4.1.1, so the matrix and the support document agreed with each
|
// the locked client is 4.1.1, so the matrix and the support document agreed with each
|
||||||
// other and with nothing that had executed. A version returns here when a lane runs
|
// other and with nothing that had executed. A version returns here when a lane runs
|
||||||
// against its image.
|
// against its image.
|
||||||
new Entry("messaging-kafka", List.of("4.1"), Tier.STABLE, true, true, true),
|
new Entry("messaging-kafka", List.of("4.1"), Tier.STABLE, true, true),
|
||||||
"messaging-rabbit",
|
"messaging-rabbit",
|
||||||
new Entry("messaging-rabbit", List.of("4.3"), Tier.STABLE, true, true, true),
|
// Experimental until a lane runs a fault scenario against a RabbitMQ container. The
|
||||||
|
// adapter passes the shared contract and its broker IT exercises the routable and
|
||||||
|
// unroutable happy paths, but Stable in this repository means fault evidence, and
|
||||||
|
// there is none: connection-refused, cut-after-write, confirm-timeout,
|
||||||
|
// settlement-lost and high-latency have never been executed here.
|
||||||
|
new Entry("messaging-rabbit", List.of("4.3"), Tier.EXPERIMENTAL, true, false),
|
||||||
"messaging-kafka-share-experimental",
|
"messaging-kafka-share-experimental",
|
||||||
new Entry(
|
new Entry(
|
||||||
"messaging-kafka-share-experimental",
|
"messaging-kafka-share-experimental",
|
||||||
List.of("4.2", "4.3"),
|
List.of("4.2", "4.3"),
|
||||||
Tier.EXPERIMENTAL,
|
Tier.EXPERIMENTAL,
|
||||||
false,
|
false,
|
||||||
false,
|
|
||||||
false),
|
false),
|
||||||
"messaging-pulsar-experimental",
|
"messaging-pulsar-experimental",
|
||||||
new Entry(
|
new Entry(
|
||||||
@@ -84,16 +103,10 @@ public final class CompatibilityMatrix {
|
|||||||
List.of("4.0", "4.2"),
|
List.of("4.0", "4.2"),
|
||||||
Tier.EXPERIMENTAL,
|
Tier.EXPERIMENTAL,
|
||||||
false,
|
false,
|
||||||
false,
|
|
||||||
false),
|
false),
|
||||||
"messaging-nats-experimental",
|
"messaging-nats-experimental",
|
||||||
new Entry(
|
new Entry(
|
||||||
"messaging-nats-experimental",
|
"messaging-nats-experimental", List.of("2.14"), Tier.EXPERIMENTAL, false, false));
|
||||||
List.of("2.14"),
|
|
||||||
Tier.EXPERIMENTAL,
|
|
||||||
false,
|
|
||||||
false,
|
|
||||||
false));
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns every certified adapter.
|
* Returns every certified adapter.
|
||||||
|
|||||||
+24
@@ -111,6 +111,30 @@ public record NetworkFaultScenario(
|
|||||||
"latency above the publish deadline is indistinguishable from a lost confirm at the "
|
"latency above the publish deadline is indistinguishable from a lost confirm at the "
|
||||||
+ "moment the decision has to be made");
|
+ "moment the decision has to be made");
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Resolves a scenario by the name a recorded run wrote down.
|
||||||
|
*
|
||||||
|
* <p>Evidence travels as text, so the read side has to answer what a name that this release does
|
||||||
|
* not define means. It means the manifest describes a scenario the code no longer has, and
|
||||||
|
* treating it as coverage would credit an adapter for a fault nobody can reproduce — so it is
|
||||||
|
* refused rather than skipped.
|
||||||
|
*
|
||||||
|
* @param name the scenario name as it appears in recorded evidence
|
||||||
|
* @return the scenario
|
||||||
|
*/
|
||||||
|
public static NetworkFaultScenario byName(String name) {
|
||||||
|
return all().stream()
|
||||||
|
.filter(scenario -> scenario.name().equals(name))
|
||||||
|
.findFirst()
|
||||||
|
.orElseThrow(
|
||||||
|
() ->
|
||||||
|
new IllegalArgumentException(
|
||||||
|
"no fault scenario is named '"
|
||||||
|
+ name
|
||||||
|
+ "'; evidence for a scenario this release does not define is coverage of"
|
||||||
|
+ " nothing"));
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns every scenario the shared fault suite runs.
|
* Returns every scenario the shared fault suite runs.
|
||||||
*
|
*
|
||||||
|
|||||||
+4
@@ -0,0 +1,4 @@
|
|||||||
|
{"adapter":"messaging-kafka","brokerImage":"apache/kafka:4.1.0","scenario":"confirm-timeout","testId":"KafkaBrokerCertificationIT#aConfirmThatNeverArrivesIsReportedAsAmbiguousAndTheRecordIsThere","outcome":"AMBIGUOUS","gitCommit":"e98b56eb03ecab588c21fd1e7dbcaa493c1d8645","observedAt":"2026-08-19T14:21:30.826332993Z"}
|
||||||
|
{"adapter":"messaging-kafka","brokerImage":"apache/kafka:4.1.0","scenario":"connection-cut-after-write","testId":"KafkaBrokerCertificationIT#aConnectionCutAfterTheWriteIsReportedAsAmbiguous","outcome":"AMBIGUOUS","gitCommit":"e98b56eb03ecab588c21fd1e7dbcaa493c1d8645","observedAt":"2026-08-19T14:21:34.906464945Z"}
|
||||||
|
{"adapter":"messaging-kafka","brokerImage":"apache/kafka:4.1.0","scenario":"high-latency","testId":"KafkaBrokerCertificationIT#latencyBeyondThePublishDeadlineIsReportedAsAmbiguous","outcome":"AMBIGUOUS","gitCommit":"e98b56eb03ecab588c21fd1e7dbcaa493c1d8645","observedAt":"2026-08-19T14:21:21.870705263Z"}
|
||||||
|
{"adapter":"messaging-kafka","brokerImage":"apache/kafka:4.1.0","scenario":"settlement-lost","testId":"KafkaBrokerCertificationIT#aDeliveryLostBeforeSettlementIsRedelivered","outcome":"REDELIVERED","gitCommit":"e98b56eb03ecab588c21fd1e7dbcaa493c1d8645","observedAt":"2026-08-19T14:21:42.058283607Z"}
|
||||||
-72
@@ -1,72 +0,0 @@
|
|||||||
package dev.caskeleton.messaging.testkit;
|
|
||||||
|
|
||||||
import java.time.Instant;
|
|
||||||
import java.util.List;
|
|
||||||
import java.util.Set;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* The fault scenarios this repository's container lanes actually exercise today.
|
|
||||||
*
|
|
||||||
* <p>Committed rather than generated because the generated form belongs to a release run: a
|
|
||||||
* certification lane writes {@link BrokerCertificationEvidence} per scenario, and the release gate
|
|
||||||
* compares that output to what the support matrix claims. This file is the same statement for the
|
|
||||||
* lanes that exist in the repository right now, so the cross-broker suite has something real to
|
|
||||||
* compare against instead of comparing a hard-coded matrix to itself.
|
|
||||||
*
|
|
||||||
* <p>Adding a line here without a lane that produces it re-creates the defect. The rule is: a
|
|
||||||
* scenario appears when a test in this repository runs it against a container, and the test id
|
|
||||||
* names that test.
|
|
||||||
*/
|
|
||||||
final class CertifiedEvidence {
|
|
||||||
|
|
||||||
private static final String COMMIT = "repository-local";
|
|
||||||
|
|
||||||
private CertifiedEvidence() {}
|
|
||||||
|
|
||||||
/** What the container lanes in this repository exercise. */
|
|
||||||
static List<BrokerCertificationEvidence> recorded() {
|
|
||||||
Instant observedAt = Instant.parse("2026-08-15T00:00:00Z");
|
|
||||||
return List.of(
|
|
||||||
new BrokerCertificationEvidence(
|
|
||||||
"messaging-kafka",
|
|
||||||
"apache/kafka:4.1.0",
|
|
||||||
NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE,
|
|
||||||
"KafkaAmbiguityChaosIT#aConnectionCutAfterWriteIsAmbiguous",
|
|
||||||
"AMBIGUOUS",
|
|
||||||
COMMIT,
|
|
||||||
observedAt),
|
|
||||||
new BrokerCertificationEvidence(
|
|
||||||
"messaging-kafka",
|
|
||||||
"apache/kafka:4.1.0",
|
|
||||||
NetworkFaultScenario.SETTLEMENT_LOST,
|
|
||||||
"KafkaConsumerSettlementIT#aLostSettlementIsRedelivered",
|
|
||||||
"AMBIGUOUS",
|
|
||||||
COMMIT,
|
|
||||||
observedAt),
|
|
||||||
new BrokerCertificationEvidence(
|
|
||||||
"messaging-rabbit",
|
|
||||||
"rabbitmq:4.3-management",
|
|
||||||
NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE,
|
|
||||||
"RabbitBrokerIT#anUnroutablePublishIsRejected",
|
|
||||||
"REJECTED",
|
|
||||||
COMMIT,
|
|
||||||
observedAt));
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* The scenarios an adapter has no evidence for.
|
|
||||||
*
|
|
||||||
* <p>Named explicitly so the gap is a fact in the build rather than a silent absence. These are
|
|
||||||
* what MSG-014 asks the certification lane to close.
|
|
||||||
*/
|
|
||||||
static List<NetworkFaultScenario> knownGaps(String adapter) {
|
|
||||||
Set<NetworkFaultScenario> covered =
|
|
||||||
recorded().stream()
|
|
||||||
.filter(evidence -> evidence.adapter().equals(adapter))
|
|
||||||
.map(BrokerCertificationEvidence::scenario)
|
|
||||||
.collect(java.util.stream.Collectors.toUnmodifiableSet());
|
|
||||||
return NetworkFaultScenario.all().stream()
|
|
||||||
.filter(scenario -> !covered.contains(scenario))
|
|
||||||
.toList();
|
|
||||||
}
|
|
||||||
}
|
|
||||||
+127
@@ -0,0 +1,127 @@
|
|||||||
|
package dev.caskeleton.messaging.testkit;
|
||||||
|
|
||||||
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||||
|
|
||||||
|
import java.io.IOException;
|
||||||
|
import java.io.InputStream;
|
||||||
|
import java.nio.charset.StandardCharsets;
|
||||||
|
import java.util.List;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Holds the line between evidence a run produced and evidence a developer typed.
|
||||||
|
*
|
||||||
|
* <p>The distinction is the whole of the finding this suite exists for. A committed list of
|
||||||
|
* scenarios reads exactly like a manifest and passes exactly the same assertions, so the only thing
|
||||||
|
* that can tell them apart is where the values come from — which is what these tests check.
|
||||||
|
*/
|
||||||
|
class CertifiedEvidenceTest {
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void everyRecordedScenarioIsALineTheCertificationLaneWrote() throws IOException {
|
||||||
|
List<String> manifestLines = manifest();
|
||||||
|
|
||||||
|
assertThat(manifestLines)
|
||||||
|
.as("the certification lane writes this file; nothing else may")
|
||||||
|
.isNotEmpty();
|
||||||
|
assertThat(CertifiedEvidence.recorded())
|
||||||
|
.as("coverage is read from the manifest, not from a list somebody maintained beside it")
|
||||||
|
.containsExactlyElementsOf(
|
||||||
|
manifestLines.stream().map(BrokerCertificationEvidence::fromJson).toList());
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void everyClaimNamesTheImageItRanAgainst() {
|
||||||
|
assertThat(CertifiedEvidence.recorded())
|
||||||
|
.allSatisfy(
|
||||||
|
evidence ->
|
||||||
|
assertThat(evidence.brokerImage())
|
||||||
|
.as("a floating tag makes a certification unrepeatable")
|
||||||
|
.contains(":")
|
||||||
|
.doesNotEndWith(":latest"));
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void everyClaimNamesTheTestThatProducedIt() {
|
||||||
|
assertThat(CertifiedEvidence.recorded())
|
||||||
|
.allSatisfy(evidence -> assertThat(evidence.testId()).contains("#"));
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aScenarioWithNoLineInTheManifestIsAGapRatherThanAnAbsence() {
|
||||||
|
assertThat(CertifiedEvidence.knownGaps("messaging-kafka"))
|
||||||
|
.as("a Kafka producer buffers before it learns a connection exists, so this stays unproven")
|
||||||
|
.contains(NetworkFaultScenario.CONNECTION_REFUSED);
|
||||||
|
assertThat(CertifiedEvidence.knownGaps("messaging-rabbit"))
|
||||||
|
.as("no lane runs a fault scenario against RabbitMQ, so every scenario is a gap")
|
||||||
|
.containsExactlyElementsOf(NetworkFaultScenario.all());
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void anEvidenceLineRoundTripsThroughItsSerialisedForm() {
|
||||||
|
BrokerCertificationEvidence evidence =
|
||||||
|
new BrokerCertificationEvidence(
|
||||||
|
"messaging-kafka",
|
||||||
|
"apache/kafka:4.1.0",
|
||||||
|
NetworkFaultScenario.CONFIRM_TIMEOUT,
|
||||||
|
"SomeIT#someScenario",
|
||||||
|
"AMBIGUOUS",
|
||||||
|
"0123456789abcdef",
|
||||||
|
java.time.Instant.parse("2026-08-15T00:00:00Z"));
|
||||||
|
|
||||||
|
assertThat(BrokerCertificationEvidence.fromJson(evidence.toJson())).isEqualTo(evidence);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aManifestLineMissingAFieldIsRefusedRatherThanPartiallyRead() {
|
||||||
|
assertThatThrownBy(
|
||||||
|
() ->
|
||||||
|
BrokerCertificationEvidence.fromJson(
|
||||||
|
"{\"adapter\":\"messaging-kafka\",\"scenario\":\"confirm-timeout\"}"))
|
||||||
|
.isInstanceOf(IllegalArgumentException.class)
|
||||||
|
.hasMessageContaining("brokerImage");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aManifestLineNamingAScenarioThisReleaseDoesNotDefineIsRefused() {
|
||||||
|
assertThatThrownBy(
|
||||||
|
() ->
|
||||||
|
BrokerCertificationEvidence.fromJson(
|
||||||
|
"{\"adapter\":\"messaging-kafka\",\"brokerImage\":\"apache/kafka:4.1.0\","
|
||||||
|
+ "\"scenario\":\"disk-full\",\"testId\":\"X#y\",\"outcome\":\"AMBIGUOUS\","
|
||||||
|
+ "\"gitCommit\":\"abc\",\"observedAt\":\"2026-08-15T00:00:00Z\"}"))
|
||||||
|
.isInstanceOf(IllegalArgumentException.class)
|
||||||
|
.hasMessageContaining("disk-full");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aValueThatWouldBreakTheManifestIsRefusedWhenTheEvidenceIsBuilt() {
|
||||||
|
assertThatThrownBy(
|
||||||
|
() ->
|
||||||
|
new BrokerCertificationEvidence(
|
||||||
|
"messaging-kafka",
|
||||||
|
"apache/kafka:4.1.0",
|
||||||
|
NetworkFaultScenario.CONFIRM_TIMEOUT,
|
||||||
|
"Some\"IT#someScenario",
|
||||||
|
"AMBIGUOUS",
|
||||||
|
"abc",
|
||||||
|
java.time.Instant.parse("2026-08-15T00:00:00Z")))
|
||||||
|
.as("a quote would truncate the line the release gate reads back")
|
||||||
|
.isInstanceOf(IllegalArgumentException.class);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static List<String> manifest() throws IOException {
|
||||||
|
try (InputStream stream =
|
||||||
|
CertifiedEvidence.class.getResourceAsStream(CertifiedEvidence.MANIFEST_RESOURCE)) {
|
||||||
|
assertThat(stream)
|
||||||
|
.as("%s is missing; no lane has produced evidence", CertifiedEvidence.MANIFEST_RESOURCE)
|
||||||
|
.isNotNull();
|
||||||
|
return new String(stream.readAllBytes(), StandardCharsets.UTF_8)
|
||||||
|
.lines()
|
||||||
|
.map(String::trim)
|
||||||
|
.filter(line -> !line.isEmpty())
|
||||||
|
.toList();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
+29
-3
@@ -37,11 +37,26 @@ class CompatibilityMatrixTest {
|
|||||||
}
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
void theStableSetIsExactlyKafkaAndRabbit() {
|
void theStableSetIsExactlyWhatALaneHasCertified() {
|
||||||
assertThat(CompatibilityMatrix.entries().values())
|
assertThat(CompatibilityMatrix.entries().values())
|
||||||
.filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.STABLE)
|
.filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.STABLE)
|
||||||
.extracting(CompatibilityMatrix.Entry::adapter)
|
.extracting(CompatibilityMatrix.Entry::adapter)
|
||||||
.containsExactlyInAnyOrder("messaging-kafka", "messaging-rabbit");
|
.as("RabbitMQ passes the shared contract, but no fault scenario has been run against it")
|
||||||
|
.containsExactly("messaging-kafka");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aCertificationClaimCannotBeMadeWithoutEvidence() {
|
||||||
|
assertThat(CompatibilityMatrix.entries().values())
|
||||||
|
.allSatisfy(
|
||||||
|
entry ->
|
||||||
|
assertThat(entry.hasLiveBrokerCertification())
|
||||||
|
.as(
|
||||||
|
"%s claims certification, so a lane must have produced evidence",
|
||||||
|
entry.adapter())
|
||||||
|
.isEqualTo(
|
||||||
|
BrokerFailureMatrix.from(CertifiedEvidence.recorded())
|
||||||
|
.hasLiveBrokerCoverage(entry.adapter())));
|
||||||
}
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
@@ -75,7 +90,7 @@ class CompatibilityMatrixTest {
|
|||||||
assertThatThrownBy(
|
assertThatThrownBy(
|
||||||
() ->
|
() ->
|
||||||
new CompatibilityMatrix.Entry(
|
new CompatibilityMatrix.Entry(
|
||||||
"messaging-x", List.of(), CompatibilityMatrix.Tier.STABLE, true, true, true))
|
"messaging-x", List.of(), CompatibilityMatrix.Tier.STABLE, true, true))
|
||||||
.isInstanceOf(IllegalArgumentException.class);
|
.isInstanceOf(IllegalArgumentException.class);
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -99,4 +114,15 @@ class CompatibilityMatrixTest {
|
|||||||
.filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.EXPERIMENTAL)
|
.filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.EXPERIMENTAL)
|
||||||
.allSatisfy(entry -> assertThat(entry.hasLiveBrokerCertification()).isFalse());
|
.allSatisfy(entry -> assertThat(entry.hasLiveBrokerCertification()).isFalse());
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void anAdapterWithoutEvidenceCannotBeCalledStable() {
|
||||||
|
CompatibilityMatrix.Entry undeclared =
|
||||||
|
new CompatibilityMatrix.Entry(
|
||||||
|
"messaging-artemis", List.of("2.42"), CompatibilityMatrix.Tier.STABLE, true, false);
|
||||||
|
|
||||||
|
assertThat(undeclared.hasLiveBrokerCertification())
|
||||||
|
.as("promoting an adapter used to be a boolean an author could set beside the tier")
|
||||||
|
.isFalse();
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+27
-8
@@ -22,14 +22,14 @@ class CrossBrokerContractSuite {
|
|||||||
/**
|
/**
|
||||||
* The matrix built from the evidence this repository actually has.
|
* The matrix built from the evidence this repository actually has.
|
||||||
*
|
*
|
||||||
* <p>It used to be {@code BrokerFailureMatrix.shipped()} — a hard-coded map marking every
|
* <p>A hard-coded map marking every scenario live-broker for both brokers would leave the
|
||||||
* scenario {@code LIVE_BROKER} for both brokers — and the assertions below then compared that map
|
* assertions below comparing that map to itself: the suite passes on a machine with no Docker,
|
||||||
* to itself. This suite passed on a machine with no Docker, and the support matrix it feeds told
|
* and the support matrix it feeds tells adopters that connection-cut and confirm-timeout are
|
||||||
* adopters that connection-cut and confirm-timeout were certified when neither had ever run.
|
* certified when neither has ever run.
|
||||||
*
|
*
|
||||||
* <p>{@link CertifiedEvidence#recorded()} is the committed record of what the container lanes
|
* <p>{@link CertifiedEvidence#recorded()} is the manifest the certification lane wrote, so the
|
||||||
* exercise today. The assertions below now fail when the shipped claim exceeds it, which is the
|
* assertions below fail when the shipped claim exceeds what a run produced — which is the failure
|
||||||
* failure they were written to catch.
|
* they were written to catch.
|
||||||
*/
|
*/
|
||||||
private final BrokerFailureMatrix matrix = BrokerFailureMatrix.from(CertifiedEvidence.recorded());
|
private final BrokerFailureMatrix matrix = BrokerFailureMatrix.from(CertifiedEvidence.recorded());
|
||||||
|
|
||||||
@@ -53,6 +53,25 @@ class CrossBrokerContractSuite {
|
|||||||
.isEqualTo(CertifiedEvidence.knownGaps("messaging-rabbit"));
|
.isEqualTo(CertifiedEvidence.knownGaps("messaging-rabbit"));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void evidenceThatDisagreesWithItsScenarioIsNotCoverage() {
|
||||||
|
BrokerCertificationEvidence contradicting =
|
||||||
|
new BrokerCertificationEvidence(
|
||||||
|
"messaging-rabbit",
|
||||||
|
"rabbitmq:4.3-management",
|
||||||
|
NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE,
|
||||||
|
"RabbitBrokerIT#anUnroutablePublishIsRejectedEvenThoughTheExchangeConfirmedIt",
|
||||||
|
"REJECTED",
|
||||||
|
"repository-local",
|
||||||
|
java.time.Instant.parse("2026-08-15T00:00:00Z"));
|
||||||
|
|
||||||
|
org.assertj.core.api.Assertions.assertThatThrownBy(
|
||||||
|
() -> BrokerFailureMatrix.from(List.of(contradicting)))
|
||||||
|
.as("certifying an adapter for the behaviour it got wrong is worse than no evidence")
|
||||||
|
.isInstanceOf(IllegalArgumentException.class)
|
||||||
|
.hasMessageContaining("AMBIGUOUS");
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
void aScenarioWithNoEvidenceIsNotCovered() {
|
void aScenarioWithNoEvidenceIsNotCovered() {
|
||||||
assertThat(matrix.coverageOf("messaging-kafka", NetworkFaultScenario.CONNECTION_REFUSED))
|
assertThat(matrix.coverageOf("messaging-kafka", NetworkFaultScenario.CONNECTION_REFUSED))
|
||||||
@@ -64,7 +83,7 @@ class CrossBrokerContractSuite {
|
|||||||
void anEvidencedScenarioIsCovered() {
|
void anEvidencedScenarioIsCovered() {
|
||||||
assertThat(
|
assertThat(
|
||||||
matrix.coverageOf("messaging-kafka", NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE))
|
matrix.coverageOf("messaging-kafka", NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE))
|
||||||
.as("KafkaAmbiguityChaosIT exercises this against a container")
|
.as("the certification lane cuts the connection after the write against a container")
|
||||||
.isEqualTo(Coverage.LIVE_BROKER);
|
.isEqualTo(Coverage.LIVE_BROKER);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
+350
@@ -0,0 +1,350 @@
|
|||||||
|
package dev.caskeleton.bootstrap.contract.messaging;
|
||||||
|
|
||||||
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
|
||||||
|
import java.io.IOException;
|
||||||
|
import java.io.UncheckedIOException;
|
||||||
|
import java.nio.file.Files;
|
||||||
|
import java.nio.file.Path;
|
||||||
|
import java.util.ArrayList;
|
||||||
|
import java.util.LinkedHashMap;
|
||||||
|
import java.util.List;
|
||||||
|
import java.util.Map;
|
||||||
|
import java.util.Set;
|
||||||
|
import java.util.TreeSet;
|
||||||
|
import java.util.regex.Matcher;
|
||||||
|
import java.util.regex.Pattern;
|
||||||
|
import java.util.stream.Stream;
|
||||||
|
import org.junit.jupiter.api.DisplayName;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Whether an adopter can compile against the messaging types this platform hands them.
|
||||||
|
*
|
||||||
|
* <p>A Gradle {@code implementation} dependency is not encapsulation. It removes the library from
|
||||||
|
* the consumer's compile classpath, but it does not remove the library's types from this module's
|
||||||
|
* public signatures. When both are true the artifact ships an API nobody can call: the method is
|
||||||
|
* there, the javadoc describes it, and the caller cannot name its parameter or its return type
|
||||||
|
* without guessing which library and which version to add to their own build. Every case below was
|
||||||
|
* exactly that — a Kafka {@code Producer}, a Spring AMQP {@code Message}, a CloudEvent, a
|
||||||
|
* Micrometer {@code MeterRegistry}, an Avro {@code Schema}, a protobuf {@code Parser}, a Reactor
|
||||||
|
* {@code Mono}.
|
||||||
|
*
|
||||||
|
* <p>So the rule is one-directional and mechanical: a vendor library named in a public or protected
|
||||||
|
* signature is declared {@code api}; one used only behind private members stays {@code
|
||||||
|
* implementation}. {@code src/messaging/CLAUDE.md} states it as policy — this holds it to the
|
||||||
|
* source so the two cannot drift.
|
||||||
|
*
|
||||||
|
* <p>The libraries checked are the ones an adopter would otherwise have to reverse-engineer into
|
||||||
|
* their own build: broker clients, codec libraries, the metrics registry, the reactive facade.
|
||||||
|
* Spring Framework and Spring Boot are deliberately out of scope. They appear only inside the
|
||||||
|
* composition boundary, where the container constructs the types rather than an adopter naming
|
||||||
|
* them, and that boundary is where the family policy already confines them.
|
||||||
|
*/
|
||||||
|
class MessagingPublicSurfaceContractTest {
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Package prefix to the Gradle coordinate that supplies it.
|
||||||
|
*
|
||||||
|
* <p>Prefixes rather than exact packages, because a library's types are spread across its own
|
||||||
|
* sub-packages and a consumer needs the whole artifact either way.
|
||||||
|
*/
|
||||||
|
private static final Map<String, String> VENDOR_LIBRARIES =
|
||||||
|
Map.of(
|
||||||
|
"org.apache.kafka", "org.apache.kafka:kafka-clients",
|
||||||
|
"org.springframework.amqp", "org.springframework.amqp:spring-rabbit",
|
||||||
|
"org.apache.avro", "org.apache.avro:avro",
|
||||||
|
"com.google.protobuf", "com.google.protobuf:protobuf-java",
|
||||||
|
"tools.jackson", "tools.jackson.core:jackson-databind",
|
||||||
|
"io.cloudevents", "io.cloudevents:cloudevents-api",
|
||||||
|
"io.micrometer", "io.micrometer:micrometer-core",
|
||||||
|
"reactor", "io.projectreactor:reactor-core",
|
||||||
|
"io.nats", "io.nats:jnats",
|
||||||
|
"org.apache.pulsar", "org.apache.pulsar:pulsar-client");
|
||||||
|
|
||||||
|
private static final Pattern IMPORT = Pattern.compile("(?m)^import\\s+(?:static\\s+)?([^;]+);");
|
||||||
|
|
||||||
|
private static final Pattern TYPE_KEYWORD =
|
||||||
|
Pattern.compile("\\b(class|interface|record|enum)\\b");
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName(
|
||||||
|
"a vendor type in a public signature has its library declared api, not implementation")
|
||||||
|
void vendorTypesInPublicSignaturesAreDeclaredApi() {
|
||||||
|
List<String> hidden = new ArrayList<>();
|
||||||
|
|
||||||
|
for (Path leaf : messagingLeaves()) {
|
||||||
|
String buildScript = read(leaf.resolve("build.gradle"));
|
||||||
|
for (String coordinate : exposedLibraries(leaf)) {
|
||||||
|
if (!declaresAsApi(buildScript, coordinate)) {
|
||||||
|
hidden.add(leaf.getFileName() + " exposes " + coordinate + " without declaring it api");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
assertThat(hidden)
|
||||||
|
.as(
|
||||||
|
"each of these ships a public signature naming a type the consumer's compile classpath "
|
||||||
|
+ "does not contain; the method exists and cannot be called")
|
||||||
|
.isEmpty();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("the scan reaches the leaves it claims to check")
|
||||||
|
void theScanIsNotVacuous() {
|
||||||
|
List<Path> leaves = messagingLeaves();
|
||||||
|
|
||||||
|
assertThat(leaves)
|
||||||
|
.as("a scan that found no leaf would report every violation as absent")
|
||||||
|
.hasSizeGreaterThan(20);
|
||||||
|
assertThat(
|
||||||
|
exposedLibraries(
|
||||||
|
leaves.stream().filter(isNamed("messaging-kafka")).findFirst().orElseThrow()))
|
||||||
|
.as("the Kafka adapter's publish seam takes a Producer, so this is a positive control")
|
||||||
|
.contains("org.apache.kafka:kafka-clients");
|
||||||
|
assertThat(
|
||||||
|
exposedLibraries(
|
||||||
|
leaves.stream().filter(isNamed("messaging-schema-json")).findFirst().orElseThrow()))
|
||||||
|
.as("the JSON codec keeps its ObjectMapper private, so nothing is required of its build")
|
||||||
|
.isEmpty();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("an adopter of the starter does not compile against either broker client")
|
||||||
|
void neitherBrokerSdkReachesAnAdoptersCompileClasspath() {
|
||||||
|
Map<String, List<String>> exported = new LinkedHashMap<>();
|
||||||
|
for (Path leaf : messagingLeaves()) {
|
||||||
|
exported.put(
|
||||||
|
leaf.getFileName().toString(), apiDependenciesOf(read(leaf.resolve("build.gradle"))));
|
||||||
|
}
|
||||||
|
|
||||||
|
Set<String> reachable = apiClosure("messaging-spring-boot-starter", exported);
|
||||||
|
|
||||||
|
assertThat(reachable)
|
||||||
|
.as(
|
||||||
|
"an empty closure would satisfy the assertion below without proving anything; the "
|
||||||
|
+ "metrics registry and the reactive facade are exported on purpose")
|
||||||
|
.contains("io.micrometer:micrometer-core", "io.projectreactor:reactor-core");
|
||||||
|
assertThat(reachable)
|
||||||
|
.as(
|
||||||
|
"both adapters were exported, so every adopter compiled against two broker SDKs at "
|
||||||
|
+ "once and each adapter's conditional-on-class guard was true whatever the "
|
||||||
|
+ "deployment had chosen")
|
||||||
|
.doesNotContain("org.apache.kafka:kafka-clients", "org.springframework.amqp:spring-rabbit");
|
||||||
|
}
|
||||||
|
|
||||||
|
/** The vendor coordinates this leaf names in a public or protected signature. */
|
||||||
|
private static Set<String> exposedLibraries(Path leaf) {
|
||||||
|
Set<String> exposed = new TreeSet<>();
|
||||||
|
for (Path source : productionSources(leaf)) {
|
||||||
|
String text = read(source);
|
||||||
|
String declarations = declarationsOnly(text);
|
||||||
|
for (Map.Entry<String, String> library : VENDOR_LIBRARIES.entrySet()) {
|
||||||
|
if (isNamedInDeclarations(text, declarations, library.getKey())) {
|
||||||
|
exposed.add(library.getValue());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return exposed;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Whether a library's types survive into this file's declarations.
|
||||||
|
*
|
||||||
|
* <p>Two ways a type gets named: imported and used by its simple name, or written out in full.
|
||||||
|
* Both are checked, because the auto-configuration style in this repository uses fully qualified
|
||||||
|
* names for one-off types rather than adding an import.
|
||||||
|
*/
|
||||||
|
private static boolean isNamedInDeclarations(String source, String declarations, String prefix) {
|
||||||
|
if (declarations.contains(prefix + ".")) {
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
Matcher imports = IMPORT.matcher(source);
|
||||||
|
while (imports.find()) {
|
||||||
|
String imported = imports.group(1).trim();
|
||||||
|
if (!imported.startsWith(prefix + ".")) {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
String simpleName = imported.substring(imported.lastIndexOf('.') + 1);
|
||||||
|
if (Pattern.compile("\\b" + Pattern.quote(simpleName) + "\\b").matcher(declarations).find()) {
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Reduces a source file to its declarations: type headers, member signatures, record components.
|
||||||
|
*
|
||||||
|
* <p>Method bodies are dropped, because a vendor type used inside one is an implementation detail
|
||||||
|
* and is exactly the case that may stay {@code implementation}. Field initialisers are dropped
|
||||||
|
* for the same reason. Anything a {@code private} modifier reaches is dropped last: a private
|
||||||
|
* member is not a signature a consumer compiles against.
|
||||||
|
*
|
||||||
|
* <p>A brace walk rather than a parser. It only has to answer "is this text a declaration or a
|
||||||
|
* body", which brace depth settles, and a parser here would be more machinery than the question
|
||||||
|
* deserves.
|
||||||
|
*/
|
||||||
|
private static String declarationsOnly(String source) {
|
||||||
|
String text = stripCommentsAndLiterals(source);
|
||||||
|
StringBuilder kept = new StringBuilder();
|
||||||
|
StringBuilder pending = new StringBuilder();
|
||||||
|
int depth = 0;
|
||||||
|
int bodyDepth = -1;
|
||||||
|
int initializerDepth = -1;
|
||||||
|
|
||||||
|
for (int index = 0; index < text.length(); index++) {
|
||||||
|
char character = text.charAt(index);
|
||||||
|
if (character == '{') {
|
||||||
|
depth++;
|
||||||
|
if (initializerDepth >= 0) {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
if (bodyDepth < 0) {
|
||||||
|
kept.append(pending).append(';');
|
||||||
|
if (!TYPE_KEYWORD.matcher(pending).find() && pending.indexOf("(") >= 0) {
|
||||||
|
bodyDepth = depth;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
pending.setLength(0);
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
if (character == '}') {
|
||||||
|
if (bodyDepth == depth) {
|
||||||
|
bodyDepth = -1;
|
||||||
|
}
|
||||||
|
depth--;
|
||||||
|
pending.setLength(0);
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
if (character == ';') {
|
||||||
|
if (initializerDepth == depth) {
|
||||||
|
initializerDepth = -1;
|
||||||
|
} else if (bodyDepth < 0) {
|
||||||
|
kept.append(pending).append(';');
|
||||||
|
}
|
||||||
|
pending.setLength(0);
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
if (bodyDepth >= 0 || initializerDepth >= 0) {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
if (character == '=' && isAssignment(text, index)) {
|
||||||
|
kept.append(pending).append(';');
|
||||||
|
pending.setLength(0);
|
||||||
|
initializerDepth = depth;
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
pending.append(character);
|
||||||
|
}
|
||||||
|
|
||||||
|
return Stream.of(kept.toString().split(";", -1))
|
||||||
|
.filter(fragment -> !fragment.contains("private "))
|
||||||
|
.filter(fragment -> !fragment.contains("import "))
|
||||||
|
.reduce("", (left, right) -> left + " ; " + right);
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Distinguishes a field initialiser from {@code ==}, {@code <=}, {@code >=} and {@code !=}. */
|
||||||
|
private static boolean isAssignment(String text, int index) {
|
||||||
|
char before = index == 0 ? ' ' : text.charAt(index - 1);
|
||||||
|
char after = index + 1 >= text.length() ? ' ' : text.charAt(index + 1);
|
||||||
|
return before != '=' && before != '<' && before != '>' && before != '!' && after != '=';
|
||||||
|
}
|
||||||
|
|
||||||
|
private static String stripCommentsAndLiterals(String source) {
|
||||||
|
return source
|
||||||
|
.replaceAll("(?s)/\\*.*?\\*/", " ")
|
||||||
|
.replaceAll("(?m)//.*$", " ")
|
||||||
|
.replaceAll("\"\"\"(?s).*?\"\"\"", "\"\"")
|
||||||
|
.replaceAll("\"(\\\\.|[^\"\\\\])*\"", "\"\"")
|
||||||
|
.replaceAll("'(\\\\.|[^'\\\\])*'", "' '");
|
||||||
|
}
|
||||||
|
|
||||||
|
/** The external coordinates a build script exports to its consumers. */
|
||||||
|
private static List<String> apiDependenciesOf(String buildScript) {
|
||||||
|
List<String> exported = new ArrayList<>();
|
||||||
|
Matcher external = Pattern.compile("(?m)^\\s*api\\s+'([^']+)'").matcher(buildScript);
|
||||||
|
while (external.find()) {
|
||||||
|
String coordinate = external.group(1);
|
||||||
|
int lastColon = coordinate.lastIndexOf(':');
|
||||||
|
boolean versioned = lastColon > 0 && coordinate.indexOf(':') != lastColon;
|
||||||
|
exported.add(versioned ? coordinate.substring(0, lastColon) : coordinate);
|
||||||
|
}
|
||||||
|
Matcher projects =
|
||||||
|
Pattern.compile("(?m)^\\s*api\\s+project\\('([^']+)'\\)").matcher(buildScript);
|
||||||
|
while (projects.find()) {
|
||||||
|
String path = projects.group(1);
|
||||||
|
exported.add(path.substring(path.lastIndexOf(':') + 1));
|
||||||
|
}
|
||||||
|
return exported;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Everything a consumer of one leaf ends up compiling against. */
|
||||||
|
private static Set<String> apiClosure(String leaf, Map<String, List<String>> exported) {
|
||||||
|
Set<String> reachable = new TreeSet<>();
|
||||||
|
List<String> pending = new ArrayList<>(exported.getOrDefault(leaf, List.of()));
|
||||||
|
while (!pending.isEmpty()) {
|
||||||
|
String next = pending.remove(0);
|
||||||
|
if (!reachable.add(next)) {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
pending.addAll(exported.getOrDefault(next, List.of()));
|
||||||
|
}
|
||||||
|
return reachable;
|
||||||
|
}
|
||||||
|
|
||||||
|
private static boolean declaresAsApi(String buildScript, String coordinate) {
|
||||||
|
return Pattern.compile("(?m)^\\s*api\\s+'" + Pattern.quote(coordinate) + "(:[^']*)?'")
|
||||||
|
.matcher(buildScript)
|
||||||
|
.find();
|
||||||
|
}
|
||||||
|
|
||||||
|
private static java.util.function.Predicate<Path> isNamed(String leaf) {
|
||||||
|
return path -> path.getFileName().toString().equals(leaf);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static List<Path> messagingLeaves() {
|
||||||
|
Path family = repositoryRoot().resolve("src/messaging");
|
||||||
|
try (Stream<Path> children = Files.list(family)) {
|
||||||
|
return children
|
||||||
|
.filter(Files::isDirectory)
|
||||||
|
.filter(path -> Files.isRegularFile(path.resolve("build.gradle")))
|
||||||
|
.sorted()
|
||||||
|
.toList();
|
||||||
|
} catch (IOException unreadable) {
|
||||||
|
throw new UncheckedIOException(unreadable);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
private static List<Path> productionSources(Path leaf) {
|
||||||
|
Path main = leaf.resolve("src/main/java");
|
||||||
|
if (!Files.isDirectory(main)) {
|
||||||
|
return List.of();
|
||||||
|
}
|
||||||
|
try (Stream<Path> walk = Files.walk(main)) {
|
||||||
|
return walk.filter(path -> path.toString().endsWith(".java")).sorted().toList();
|
||||||
|
} catch (IOException unreadable) {
|
||||||
|
throw new UncheckedIOException(unreadable);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
private static String read(Path path) {
|
||||||
|
try {
|
||||||
|
return Files.readString(path);
|
||||||
|
} catch (IOException unreadable) {
|
||||||
|
throw new UncheckedIOException(unreadable);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
private static Path repositoryRoot() {
|
||||||
|
Path candidate = Path.of("").toAbsolutePath();
|
||||||
|
while (candidate != null
|
||||||
|
&& !Files.isRegularFile(candidate.resolve("src/config/architecture/modules.json"))) {
|
||||||
|
candidate = candidate.getParent();
|
||||||
|
}
|
||||||
|
if (candidate == null) {
|
||||||
|
throw new IllegalStateException("the repository root is not above the working directory");
|
||||||
|
}
|
||||||
|
return candidate;
|
||||||
|
}
|
||||||
|
}
|
||||||
-125
@@ -1,125 +0,0 @@
|
|||||||
package dev.caskeleton.messaging.transport;
|
|
||||||
|
|
||||||
import java.util.Map;
|
|
||||||
import java.util.Objects;
|
|
||||||
import java.util.concurrent.ConcurrentHashMap;
|
|
||||||
import java.util.concurrent.atomic.AtomicInteger;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Bounds in-flight work per destination and across the process.
|
|
||||||
*
|
|
||||||
* <p>Two limits, because one is not enough. A per-destination limit stops a single slow downstream
|
|
||||||
* from consuming every worker, and a global limit stops the sum of well-behaved destinations from
|
|
||||||
* exhausting memory. Without the global bound, adding a destination silently raises the process
|
|
||||||
* ceiling.
|
|
||||||
*
|
|
||||||
* <p>Refusing work is the point. An unbounded in-flight queue does not remove backpressure, it
|
|
||||||
* moves it into the heap, where it surfaces as an out-of-memory error instead of a visible,
|
|
||||||
* recoverable slowdown.
|
|
||||||
*/
|
|
||||||
public final class BackpressureController {
|
|
||||||
|
|
||||||
private final int globalLimit;
|
|
||||||
private final int perDestinationLimit;
|
|
||||||
private final AtomicInteger global = new AtomicInteger();
|
|
||||||
private final Map<String, AtomicInteger> perDestination = new ConcurrentHashMap<>();
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Creates a controller.
|
|
||||||
*
|
|
||||||
* @param globalLimit the process-wide in-flight ceiling
|
|
||||||
* @param perDestinationLimit the per-destination in-flight ceiling
|
|
||||||
*/
|
|
||||||
public BackpressureController(int globalLimit, int perDestinationLimit) {
|
|
||||||
if (globalLimit < 1) {
|
|
||||||
throw new IllegalArgumentException("globalLimit must be at least 1");
|
|
||||||
}
|
|
||||||
if (perDestinationLimit < 1) {
|
|
||||||
throw new IllegalArgumentException("perDestinationLimit must be at least 1");
|
|
||||||
}
|
|
||||||
if (perDestinationLimit > globalLimit) {
|
|
||||||
throw new IllegalArgumentException(
|
|
||||||
"perDestinationLimit cannot exceed the global limit, or the global limit is not a limit");
|
|
||||||
}
|
|
||||||
this.globalLimit = globalLimit;
|
|
||||||
this.perDestinationLimit = perDestinationLimit;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Tries to admit one unit of work.
|
|
||||||
*
|
|
||||||
* @param destination the logical destination
|
|
||||||
* @return true when the work may start
|
|
||||||
*/
|
|
||||||
public boolean tryAcquire(String destination) {
|
|
||||||
Objects.requireNonNull(destination, "destination must not be null");
|
|
||||||
AtomicInteger counter = perDestination.computeIfAbsent(destination, key -> new AtomicInteger());
|
|
||||||
|
|
||||||
if (!increment(counter, perDestinationLimit)) {
|
|
||||||
return false;
|
|
||||||
}
|
|
||||||
if (!increment(global, globalLimit)) {
|
|
||||||
counter.decrementAndGet();
|
|
||||||
return false;
|
|
||||||
}
|
|
||||||
return true;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Releases one unit of work.
|
|
||||||
*
|
|
||||||
* @param destination the logical destination
|
|
||||||
*/
|
|
||||||
public void release(String destination) {
|
|
||||||
Objects.requireNonNull(destination, "destination must not be null");
|
|
||||||
AtomicInteger counter = perDestination.get(destination);
|
|
||||||
if (counter == null) {
|
|
||||||
// A release for a destination that holds nothing. It used to decrement the global counter
|
|
||||||
// anyway, which frees a permit nobody took.
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
int before = counter.getAndUpdate(current -> current > 0 ? current - 1 : current);
|
|
||||||
if (before <= 0) {
|
|
||||||
// Already at zero: a double release. Decrementing the global counter here is how the global
|
|
||||||
// limit stops limiting — it reads below the real in-flight count and admits more work than
|
|
||||||
// the process can carry.
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
global.updateAndGet(current -> current > 0 ? current - 1 : current);
|
|
||||||
// Drop the entry once it reaches 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);
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Returns the process-wide in-flight count.
|
|
||||||
*
|
|
||||||
* @return the global in-flight count
|
|
||||||
*/
|
|
||||||
public int globalInFlight() {
|
|
||||||
return global.get();
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Returns a destination's in-flight count.
|
|
||||||
*
|
|
||||||
* @param destination the logical destination
|
|
||||||
* @return the in-flight count
|
|
||||||
*/
|
|
||||||
public int inFlight(String destination) {
|
|
||||||
AtomicInteger counter = perDestination.get(destination);
|
|
||||||
return counter == null ? 0 : counter.get();
|
|
||||||
}
|
|
||||||
|
|
||||||
private static boolean increment(AtomicInteger counter, int limit) {
|
|
||||||
while (true) {
|
|
||||||
int current = counter.get();
|
|
||||||
if (current >= limit) {
|
|
||||||
return false;
|
|
||||||
}
|
|
||||||
if (counter.compareAndSet(current, current + 1)) {
|
|
||||||
return true;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
+38
-18
@@ -22,7 +22,8 @@ import java.util.concurrent.atomic.AtomicInteger;
|
|||||||
* <p>A drain deadline bounds that wait. Without one, a single leaked lease would pin a revoked
|
* <p>A drain deadline bounds that wait. Without one, a single leaked lease would pin a revoked
|
||||||
* credential open indefinitely, which turns a rotation into a security non-event.
|
* credential open indefinitely, which turns a rotation into a security non-event.
|
||||||
*/
|
*/
|
||||||
public final class DefaultMessagingRuntimeRegistry implements MessagingRuntimeRegistry {
|
public final class DefaultMessagingRuntimeRegistry
|
||||||
|
implements MessagingRuntimeRegistry, AutoCloseable {
|
||||||
|
|
||||||
private static final Duration DEFAULT_DRAIN_DEADLINE = Duration.ofSeconds(30);
|
private static final Duration DEFAULT_DRAIN_DEADLINE = Duration.ofSeconds(30);
|
||||||
|
|
||||||
@@ -91,28 +92,17 @@ public final class DefaultMessagingRuntimeRegistry implements MessagingRuntimeRe
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Closes retired generations whose drain deadline has passed.
|
* Closes retired generations whose own drain deadline has passed.
|
||||||
|
*
|
||||||
|
* <p>Per generation, not per call. A single {@code retiredAt} supplied by the caller and applied
|
||||||
|
* to the whole draining list gives a generation retired thirty seconds ago and one retired a
|
||||||
|
* moment ago the same deadline, and a generation that has already gone idle and closed stays in
|
||||||
|
* the list, counted as draining forever.
|
||||||
*
|
*
|
||||||
* <p>Called by the platform's scheduler. Exposed as a plain method taking the current instant so
|
* <p>Called by the platform's scheduler. Exposed as a plain method taking the current instant so
|
||||||
* that deadline behaviour is testable without sleeping.
|
* that deadline behaviour is testable without sleeping.
|
||||||
*
|
*
|
||||||
* @param now the current instant
|
* @param now the current instant
|
||||||
* @param retiredAt when the generations were retired
|
|
||||||
* @return how many generations were force closed
|
|
||||||
*/
|
|
||||||
public int closeExpiredDraining(Instant now, Instant retiredAt) {
|
|
||||||
return closeExpiredDraining(now);
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Closes retired generations whose own drain deadline has passed.
|
|
||||||
*
|
|
||||||
* <p>Per generation, not per call. The previous signature took one {@code retiredAt} and applied
|
|
||||||
* it to the whole draining list, so a generation retired thirty seconds ago and one retired a
|
|
||||||
* moment ago shared a deadline — and a generation that had already gone idle and closed stayed in
|
|
||||||
* the list, counted as draining forever.
|
|
||||||
*
|
|
||||||
* @param now the current instant
|
|
||||||
* @return how many generations were force closed
|
* @return how many generations were force closed
|
||||||
*/
|
*/
|
||||||
public int closeExpiredDraining(Instant now) {
|
public int closeExpiredDraining(Instant now) {
|
||||||
@@ -135,6 +125,36 @@ public final class DefaultMessagingRuntimeRegistry implements MessagingRuntimeRe
|
|||||||
return closed;
|
return closed;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Closes every generation this registry holds, current and draining.
|
||||||
|
*
|
||||||
|
* <p>Nothing closed the current generation. The registry only ever closed what a rotation had
|
||||||
|
* retired, so a process that shut down without rotating left its broker connections to the JVM's
|
||||||
|
* exit — which drops unflushed producer batches and leaves consumer sessions to time out on the
|
||||||
|
* broker instead of leaving the group.
|
||||||
|
*
|
||||||
|
* <p>Each generation closes exactly once, whichever path reaches it first: a drain that finished
|
||||||
|
* during shutdown must not be closed a second time here, because a second close on a broker
|
||||||
|
* client is where "already closed" exceptions come from during an otherwise clean stop.
|
||||||
|
*/
|
||||||
|
@Override
|
||||||
|
public void close() {
|
||||||
|
List<Generation> pending;
|
||||||
|
synchronized (draining) {
|
||||||
|
pending = List.copyOf(draining);
|
||||||
|
draining.clear();
|
||||||
|
}
|
||||||
|
for (Generation generation : pending) {
|
||||||
|
generation.forceClose();
|
||||||
|
}
|
||||||
|
for (String brokerName : List.copyOf(current.keySet())) {
|
||||||
|
Generation generation = current.remove(brokerName);
|
||||||
|
if (generation != null) {
|
||||||
|
generation.forceClose();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns how many retired generations are still draining.
|
* Returns how many retired generations are still draining.
|
||||||
*
|
*
|
||||||
|
|||||||
-148
@@ -1,148 +0,0 @@
|
|||||||
package dev.caskeleton.messaging.transport;
|
|
||||||
|
|
||||||
import static org.assertj.core.api.Assertions.assertThat;
|
|
||||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
|
||||||
|
|
||||||
import java.time.Duration;
|
|
||||||
import java.time.Instant;
|
|
||||||
import org.junit.jupiter.api.Test;
|
|
||||||
|
|
||||||
class BackpressureAndShutdownTest {
|
|
||||||
|
|
||||||
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
|
|
||||||
|
|
||||||
@Test
|
|
||||||
void aSlowDestinationCannotConsumeEveryWorker() {
|
|
||||||
BackpressureController controller = new BackpressureController(10, 2);
|
|
||||||
|
|
||||||
assertThat(controller.tryAcquire("order-events")).isTrue();
|
|
||||||
assertThat(controller.tryAcquire("order-events")).isTrue();
|
|
||||||
assertThat(controller.tryAcquire("order-events")).isFalse();
|
|
||||||
assertThat(controller.tryAcquire("email-work")).isTrue();
|
|
||||||
}
|
|
||||||
|
|
||||||
@Test
|
|
||||||
void theGlobalLimitBoundsTheSumOfWellBehavedDestinations() {
|
|
||||||
BackpressureController controller = new BackpressureController(2, 2);
|
|
||||||
|
|
||||||
assertThat(controller.tryAcquire("a")).isTrue();
|
|
||||||
assertThat(controller.tryAcquire("b")).isTrue();
|
|
||||||
assertThat(controller.tryAcquire("c")).isFalse();
|
|
||||||
assertThat(controller.globalInFlight()).isEqualTo(2);
|
|
||||||
}
|
|
||||||
|
|
||||||
@Test
|
|
||||||
void aRefusedAcquireDoesNotLeakAPerDestinationSlot() {
|
|
||||||
BackpressureController controller = new BackpressureController(1, 1);
|
|
||||||
controller.tryAcquire("a");
|
|
||||||
|
|
||||||
controller.tryAcquire("b");
|
|
||||||
|
|
||||||
assertThat(controller.inFlight("b")).isZero();
|
|
||||||
}
|
|
||||||
|
|
||||||
@Test
|
|
||||||
void releasingFreesBothCounters() {
|
|
||||||
BackpressureController controller = new BackpressureController(4, 2);
|
|
||||||
controller.tryAcquire("a");
|
|
||||||
|
|
||||||
controller.release("a");
|
|
||||||
|
|
||||||
assertThat(controller.inFlight("a")).isZero();
|
|
||||||
assertThat(controller.globalInFlight()).isZero();
|
|
||||||
}
|
|
||||||
|
|
||||||
@Test
|
|
||||||
void aPerDestinationLimitAboveTheGlobalOneIsRejected() {
|
|
||||||
assertThatThrownBy(() -> new BackpressureController(2, 4))
|
|
||||||
.isInstanceOf(IllegalArgumentException.class);
|
|
||||||
}
|
|
||||||
|
|
||||||
@Test
|
|
||||||
void drainingStopsNewWorkButLetsRunningWorkFinish() {
|
|
||||||
GracefulShutdownCoordinator coordinator =
|
|
||||||
new GracefulShutdownCoordinator(Duration.ofSeconds(30));
|
|
||||||
assertThat(coordinator.tryBeginWork()).isTrue();
|
|
||||||
|
|
||||||
coordinator.beginDrain(NOW);
|
|
||||||
|
|
||||||
assertThat(coordinator.isAcceptingWork()).isFalse();
|
|
||||||
assertThat(coordinator.tryBeginWork()).isFalse();
|
|
||||||
assertThat(coordinator.inFlight()).isEqualTo(1);
|
|
||||||
assertThat(coordinator.isDrained(NOW)).isFalse();
|
|
||||||
|
|
||||||
coordinator.endWork();
|
|
||||||
|
|
||||||
assertThat(coordinator.isDrained(NOW)).isTrue();
|
|
||||||
}
|
|
||||||
|
|
||||||
@Test
|
|
||||||
void noRetryAttemptIsCreatedOnceDrainingBegins() {
|
|
||||||
GracefulShutdownCoordinator coordinator =
|
|
||||||
new GracefulShutdownCoordinator(Duration.ofSeconds(30));
|
|
||||||
|
|
||||||
assertThat(coordinator.mayCreateRetryAttempt()).isTrue();
|
|
||||||
coordinator.beginDrain(NOW);
|
|
||||||
assertThat(coordinator.mayCreateRetryAttempt()).isFalse();
|
|
||||||
}
|
|
||||||
|
|
||||||
@Test
|
|
||||||
void workStillRunningAtTheDeadlineIsAbandonedUnsettled() {
|
|
||||||
GracefulShutdownCoordinator coordinator =
|
|
||||||
new GracefulShutdownCoordinator(Duration.ofSeconds(30));
|
|
||||||
coordinator.tryBeginWork();
|
|
||||||
coordinator.beginDrain(NOW);
|
|
||||||
|
|
||||||
assertThat(coordinator.isDrained(NOW.plusSeconds(29))).isFalse();
|
|
||||||
assertThat(coordinator.isDrained(NOW.plusSeconds(30))).isTrue();
|
|
||||||
assertThat(coordinator.abandonedWorkAtDeadline(NOW.plusSeconds(30))).isTrue();
|
|
||||||
}
|
|
||||||
|
|
||||||
@Test
|
|
||||||
void anIdleCoordinatorIsNotDrainedBeforeShutdownStarts() {
|
|
||||||
GracefulShutdownCoordinator coordinator =
|
|
||||||
new GracefulShutdownCoordinator(Duration.ofSeconds(30));
|
|
||||||
|
|
||||||
assertThat(coordinator.isDrained(NOW)).isFalse();
|
|
||||||
}
|
|
||||||
|
|
||||||
@Test
|
|
||||||
@org.junit.jupiter.api.DisplayName("releasing an unknown destination frees no global permit")
|
|
||||||
void releasingAnUnknownDestinationFreesNoGlobalPermit() {
|
|
||||||
BackpressureController controller = new BackpressureController(2, 2);
|
|
||||||
assertThat(controller.tryAcquire("orders")).isTrue();
|
|
||||||
|
|
||||||
controller.release("something-else");
|
|
||||||
|
|
||||||
assertThat(controller.globalInFlight())
|
|
||||||
.as("a permit nobody took cannot be given back; doing so makes the global limit fiction")
|
|
||||||
.isEqualTo(1);
|
|
||||||
}
|
|
||||||
|
|
||||||
@Test
|
|
||||||
@org.junit.jupiter.api.DisplayName("a double release frees no second global permit")
|
|
||||||
void aDoubleReleaseFreesNoSecondPermit() {
|
|
||||||
BackpressureController controller = new BackpressureController(4, 4);
|
|
||||||
assertThat(controller.tryAcquire("orders")).isTrue();
|
|
||||||
|
|
||||||
controller.release("orders");
|
|
||||||
controller.release("orders");
|
|
||||||
|
|
||||||
assertThat(controller.globalInFlight()).isZero();
|
|
||||||
}
|
|
||||||
|
|
||||||
@Test
|
|
||||||
@org.junit.jupiter.api.DisplayName("a double endWork cannot drive the in-flight count negative")
|
|
||||||
void aDoubleEndWorkCannotGoNegative() {
|
|
||||||
GracefulShutdownCoordinator shutdown =
|
|
||||||
new GracefulShutdownCoordinator(java.time.Duration.ofSeconds(5));
|
|
||||||
assertThat(shutdown.tryBeginWork()).isTrue();
|
|
||||||
|
|
||||||
shutdown.endWork();
|
|
||||||
shutdown.endWork();
|
|
||||||
|
|
||||||
assertThat(shutdown.inFlight())
|
|
||||||
.as("a negative count reports the drain as finished while work is still running")
|
|
||||||
.isZero();
|
|
||||||
}
|
|
||||||
}
|
|
||||||
+75
@@ -0,0 +1,75 @@
|
|||||||
|
package dev.caskeleton.messaging.transport;
|
||||||
|
|
||||||
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
|
||||||
|
import java.time.Duration;
|
||||||
|
import java.time.Instant;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
|
||||||
|
class GracefulShutdownTest {
|
||||||
|
|
||||||
|
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void drainingStopsNewWorkButLetsRunningWorkFinish() {
|
||||||
|
GracefulShutdownCoordinator coordinator =
|
||||||
|
new GracefulShutdownCoordinator(Duration.ofSeconds(30));
|
||||||
|
assertThat(coordinator.tryBeginWork()).isTrue();
|
||||||
|
|
||||||
|
coordinator.beginDrain(NOW);
|
||||||
|
|
||||||
|
assertThat(coordinator.isAcceptingWork()).isFalse();
|
||||||
|
assertThat(coordinator.tryBeginWork()).isFalse();
|
||||||
|
assertThat(coordinator.inFlight()).isEqualTo(1);
|
||||||
|
assertThat(coordinator.isDrained(NOW)).isFalse();
|
||||||
|
|
||||||
|
coordinator.endWork();
|
||||||
|
|
||||||
|
assertThat(coordinator.isDrained(NOW)).isTrue();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void noRetryAttemptIsCreatedOnceDrainingBegins() {
|
||||||
|
GracefulShutdownCoordinator coordinator =
|
||||||
|
new GracefulShutdownCoordinator(Duration.ofSeconds(30));
|
||||||
|
|
||||||
|
assertThat(coordinator.mayCreateRetryAttempt()).isTrue();
|
||||||
|
coordinator.beginDrain(NOW);
|
||||||
|
assertThat(coordinator.mayCreateRetryAttempt()).isFalse();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void workStillRunningAtTheDeadlineIsAbandonedUnsettled() {
|
||||||
|
GracefulShutdownCoordinator coordinator =
|
||||||
|
new GracefulShutdownCoordinator(Duration.ofSeconds(30));
|
||||||
|
coordinator.tryBeginWork();
|
||||||
|
coordinator.beginDrain(NOW);
|
||||||
|
|
||||||
|
assertThat(coordinator.isDrained(NOW.plusSeconds(29))).isFalse();
|
||||||
|
assertThat(coordinator.isDrained(NOW.plusSeconds(30))).isTrue();
|
||||||
|
assertThat(coordinator.abandonedWorkAtDeadline(NOW.plusSeconds(30))).isTrue();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void anIdleCoordinatorIsNotDrainedBeforeShutdownStarts() {
|
||||||
|
GracefulShutdownCoordinator coordinator =
|
||||||
|
new GracefulShutdownCoordinator(Duration.ofSeconds(30));
|
||||||
|
|
||||||
|
assertThat(coordinator.isDrained(NOW)).isFalse();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@org.junit.jupiter.api.DisplayName("a double endWork cannot drive the in-flight count negative")
|
||||||
|
void aDoubleEndWorkCannotGoNegative() {
|
||||||
|
GracefulShutdownCoordinator shutdown =
|
||||||
|
new GracefulShutdownCoordinator(java.time.Duration.ofSeconds(5));
|
||||||
|
assertThat(shutdown.tryBeginWork()).isTrue();
|
||||||
|
|
||||||
|
shutdown.endWork();
|
||||||
|
shutdown.endWork();
|
||||||
|
|
||||||
|
assertThat(shutdown.inFlight())
|
||||||
|
.as("a negative count reports the drain as finished while work is still running")
|
||||||
|
.isZero();
|
||||||
|
}
|
||||||
|
}
|
||||||
+66
@@ -45,6 +45,30 @@ class MessagingRuntimeRegistryTest {
|
|||||||
assertThat(registry.drainingCount()).isZero();
|
assertThat(registry.drainingCount()).isZero();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void closingTheRegistryClosesCurrentAndDrainingGenerationsExactlyOnce() {
|
||||||
|
DefaultMessagingRuntimeRegistry registry =
|
||||||
|
new DefaultMessagingRuntimeRegistry(Duration.ofSeconds(30));
|
||||||
|
CountingRuntime retired = new CountingRuntime("kafka-primary", 1);
|
||||||
|
CountingRuntime current = new CountingRuntime("kafka-primary", 2);
|
||||||
|
|
||||||
|
registry.install(retired);
|
||||||
|
MessagingRuntimeLease leaked = registry.acquire("kafka-primary");
|
||||||
|
registry.install(current, Instant.parse("2026-08-10T00:00:00Z"));
|
||||||
|
|
||||||
|
registry.close();
|
||||||
|
registry.close();
|
||||||
|
|
||||||
|
assertThat(current.closes())
|
||||||
|
.as("a process that shut down without rotating left its connections to JVM exit")
|
||||||
|
.isEqualTo(1);
|
||||||
|
assertThat(retired.closes())
|
||||||
|
.as("a second close on a broker client is where 'already closed' at shutdown comes from")
|
||||||
|
.isEqualTo(1);
|
||||||
|
|
||||||
|
leaked.close();
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
void closingALeaseTwiceDoesNotDoubleRelease() {
|
void closingALeaseTwiceDoesNotDoubleRelease() {
|
||||||
DefaultMessagingRuntimeRegistry registry = new DefaultMessagingRuntimeRegistry();
|
DefaultMessagingRuntimeRegistry registry = new DefaultMessagingRuntimeRegistry();
|
||||||
@@ -232,3 +256,45 @@ final class FakeTransport implements MessagingTransport {
|
|||||||
// Nothing to release.
|
// Nothing to release.
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/** A runtime that counts how many times it was closed. */
|
||||||
|
final class CountingRuntime implements MessagingRuntime {
|
||||||
|
|
||||||
|
private final String brokerName;
|
||||||
|
private final long generation;
|
||||||
|
private int closes;
|
||||||
|
|
||||||
|
CountingRuntime(String brokerName, long generation) {
|
||||||
|
this.brokerName = brokerName;
|
||||||
|
this.generation = generation;
|
||||||
|
}
|
||||||
|
|
||||||
|
int closes() {
|
||||||
|
return closes;
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public String brokerName() {
|
||||||
|
return brokerName;
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public long generation() {
|
||||||
|
return generation;
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public MessagingTransport transport() {
|
||||||
|
return new FakeTransport(brokerName, generation);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public boolean isClosed() {
|
||||||
|
return closes > 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void close() {
|
||||||
|
closes++;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
-28
@@ -56,34 +56,6 @@ class ResourceLeakGateTest {
|
|||||||
.isTrue();
|
.isTrue();
|
||||||
}
|
}
|
||||||
|
|
||||||
@Test
|
|
||||||
void everyAcquiredInFlightSlotIsReleased() {
|
|
||||||
BackpressureController controller = new BackpressureController(8, 4);
|
|
||||||
|
|
||||||
for (int i = 0; i < 1_000; i++) {
|
|
||||||
if (controller.tryAcquire("order-events")) {
|
|
||||||
controller.release("order-events");
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
assertThat(controller.inFlight("order-events")).isZero();
|
|
||||||
assertThat(controller.globalInFlight()).isZero();
|
|
||||||
}
|
|
||||||
|
|
||||||
@Test
|
|
||||||
void aRefusedAcquireLeavesNoSlotBehind() {
|
|
||||||
BackpressureController controller = new BackpressureController(2, 1);
|
|
||||||
controller.tryAcquire("a");
|
|
||||||
controller.tryAcquire("b");
|
|
||||||
|
|
||||||
for (int i = 0; i < 100; i++) {
|
|
||||||
controller.tryAcquire("c");
|
|
||||||
}
|
|
||||||
|
|
||||||
assertThat(controller.inFlight("c")).isZero();
|
|
||||||
assertThat(controller.globalInFlight()).isEqualTo(2);
|
|
||||||
}
|
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
void aDrainAlwaysTerminatesEvenWithStuckWork() {
|
void aDrainAlwaysTerminatesEvenWithStuckWork() {
|
||||||
GracefulShutdownCoordinator coordinator =
|
GracefulShutdownCoordinator coordinator =
|
||||||
|
|||||||
Reference in New Issue
Block a user