refactor(repo)!: 들여온 플랫폼을 src/platforms 아래로 묶는다
문제: src/ 최상위에 계층 폴더와 들여온 제품 폴더(messaging, grpc,
grpc-advanced)와 optional 빌드 폴더(optional-platforms)가 같은 높이로
놓여, 무엇이 이 애플리케이션의 계층인지 폴더만으로 안 보인다.
src/config/에는 빌드 전체 설정과 기능 하나가 주인인 데이터(jpa,
messaging, mongodb)가 섞여 있다.
고른 방법(소유자 결정 2026-11-07, 설계 가-1):
- git mv로 src/platforms/{messaging,grpc,grpc-advanced,optional-build}.
registry source_path 28행만 바꾸고 Gradle 경로(:messaging:*, :grpc:*)는
그대로다. optional 빌드의 이름(optional-platforms)도 그대로다.
- optional 빌드가 한 단계 깊어져, build-logic이 "optional 빌드의 부모 =
주 빌드"로 가정한 네 곳(registry settings, ArchitecturePlugin, 테스트
이미지 catalog, checkstyle·spotbugs 설정)을 MainBuild(위로 올라가며
registry·설정 파일을 찾음)로 바꾼다.
- settings.gradle·build.gradle의 상대 경로, workflow의 -p 값과 경로,
buf 작업 폴더를 고친다. buf breaking은 이동 전 baseline에서도 옛
경로로 비교해 이동 PR에서 건너뛰지 않는다.
- config/jpa, config/messaging, config/mongodb의 데이터를 주인 leaf의
release/로 옮기고 읽는 빌드 줄·테스트·스크립트·문서를 고친다.
- 루트 CLAUDE.md 5절에 최상위 폴더 지도를 한 줄로 적는다.
버린 대안: Gradle 루트를 저장소 루트로(가-3, CI 재편 때 다시 봄),
application-* 묶기(가-2, 파생 서비스 충돌이 큼).
위험·한계: Gradle 문서의 "이름 = 위치" 권고와 한 단계 어긋난다
(:messaging:x가 platforms/messaging/x). 옮긴 폴더를 고쳐 쓰던 파생
서비스는 이름 바뀜 충돌이 날 수 있다(B-52). docs/capability-status.md
「제거된 코드」 표와 docs/work/evidence.md의 옛 경로는 이력이라 두었다.
검증(desktop, 트리 2b3354a4, ~/t1-layout-logs/):
- ./gradlew :ci :verifyDependencyLocks --warning-mode=fail --continue
첫 실행 rc=1: MessagingAuthorityContractTest가 src/messaging을 찾아 실패
→ 경로를 고침. 두 번째 rc=1: messaging-policy
MessagingAdmissionControllerTest.aWaitingCallerIsAdmittedOnceAPermitIsReturned
(2초 대기 경쟁, 부하 7.3에서 한 번 실패, 코드 변경 없는 leaf) → --rerun
3회 모두 통과. 세 번째 rc=0
- -p platforms/optional-build ci rc=0, 두 빌드의 verifyStrictLaneStages
--dry-run rc=0, -p build-logic check rc=0
- :app-bootstrap:documentContractTest
:adapter:outbound:persistence-mongo:mongoDocumentContractTest rc=0
- ./gradlew projects(주 빌드)와 optional 빌드 projects의 프로젝트 목록이
이동 전 트리와 같다(Gradle 경로 불변)
- check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.1
BREAKING CHANGE: src/messaging·src/grpc·src/grpc-advanced·src/optional-platforms가 src/platforms/ 아래로, src/config/{jpa,messaging,mongodb}가 주인 leaf의 release/로 옮겨졌다. optional 빌드는 -p platforms/optional-build로 부른다. docs/upgrade/2026-11-maturity-review.md B-52.
This commit is contained in:
@@ -0,0 +1,175 @@
|
||||
# messaging — local authority for the messaging platform family
|
||||
|
||||
이 문서는 messaging family의 **local authority**다. leaf 목록·gradle path·허용 의존성은
|
||||
`src/config/architecture/modules.json`이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는
|
||||
것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, public surface 정책, Stable 승격에
|
||||
필요한 증거, runtime membership이 비어 있다는 사실의 의미.
|
||||
|
||||
Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 root가 이긴다.
|
||||
|
||||
## Family와 framework 규칙
|
||||
|
||||
leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이름의 접두사**가 아니라 아래 표의
|
||||
역할로 정해진다.
|
||||
|
||||
| Family | 역할 | 허용 framework |
|
||||
| --- | --- | --- |
|
||||
| `*-api` (`core-api` — `api`·`schema` 패키지, `policy`, `reliability-api`, `transport-spi`) | 값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging framework 금지 |
|
||||
| `schema-*` (json/avro/protobuf), `cloudevents` | 인코딩 구현 | 해당 codec 라이브러리만. Spring 금지 |
|
||||
| `runtime-core`, `security`, `observability`, `admin`(계약 `admin` + 실행 `admin.runtime`), `reliability` | framework-free 실행 로직 | Micrometer는 `observability`에서만. 나머지는 stdlib |
|
||||
| `kafka` | broker adapter | 해당 broker client. Spring은 client가 곧 Spring인 경우만 |
|
||||
| `reliability-jdbc-postgresql` | 관계형 신뢰성 adapter (outbox·inbox repository, admin journal) | Spring JDBC / Spring TX. **JPA 아님** — 이름이 곧 계약이다 |
|
||||
| `spring-boot-starter`, `spring-boot-starter-kafka` | 조립 경계 | Spring Boot autoconfigure. 여기서만 |
|
||||
| `testkit` | 테스트 지원 | Testcontainers, JUnit. production leaf가 의존하지 않는다 |
|
||||
|
||||
신뢰성 기능은 세 leaf다. `messaging-reliability-api`가 vendor 중립 port(`OutboxRepository`,
|
||||
`InboxRepository`)를, `messaging-reliability`가 그 port만 보는 relay·consumer 로직(stdlib)을,
|
||||
`messaging-reliability-jdbc-postgresql`이 port의 관계형 구현과 migration(`V1001..V1005`, `V1101`)을
|
||||
갖는다. 예전에는 `outbox-jdbc-postgresql` 하나가 relay 로직과 PG repository와 admin journal을 함께
|
||||
가졌고 inbox도 같은 모양이었다(2026-09-25 리뷰 후속 작업에서 나눴다). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring
|
||||
JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL
|
||||
전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다.
|
||||
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유
|
||||
|
||||
`messaging-admin`(`HmacApprovalVerifier`, `PlanDigest`)과 `messaging-claim-check`
|
||||
(`ClaimCheckIntegrityGuard`)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의
|
||||
`shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 family는 이 애플리케이션의
|
||||
계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치), `messaging:*` leaf는
|
||||
`domain-core`·`application-core`·`shared-contract` 어느 타입에도 의존하지 않는다. 헬퍼 하나 때문에
|
||||
registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는
|
||||
`shared-contract`의 정본과 같은 규칙인지 함께 본다.
|
||||
|
||||
### Publish retryability of authentication and authorization
|
||||
|
||||
이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다.
|
||||
|
||||
- category 기본값: `FailureDescriptor.defaultRetryable(AUTHENTICATION | AUTHORIZATION) = false`. 소비 쪽
|
||||
재시도 엔진(`DefaultRetryDecisionEngine`)은 policy가 category를 따로 정하지 않으면 이 기본값과
|
||||
descriptor의 `retryable`을 둘 다 요구한다. 그래서 인가받지 못한 메시지의 재전달은 지금도 재시도하지 않는다.
|
||||
- publish 거부의 `retryable`: `KafkaPublishFailureClassifier`는 인증·인가 거부에 `retryable = true`를 붙인다.
|
||||
broker가 레코드를 저장하지 않았고, credential 교체나 application보다 늦게 배포된 ACL은 몇 분 동안 모든
|
||||
publish를 거부한 뒤 멈추기 때문이다. `retryable`을 믿는 publisher가 그 몇 분 동안의 레코드를 영구 보류하지
|
||||
않게 하려는 것이다.
|
||||
|
||||
06-01 수정이 이 제품에서 바꾼 것(모두 publish 경로, 소비 경로 동작은 그대로):
|
||||
|
||||
- `KafkaPublishFailureClassifier`: 인증·인가 거부를 `retryable = true`로.
|
||||
- `DefaultMessagePublisher`: runtime이 없을 때의 거부(`PUBLISH_RUNTIME_UNAVAILABLE`)를 `retryable = true`로.
|
||||
- `KafkaMessagingTransport`: 닫힌 transport의 거부(`KAFKA_TRANSPORT_CLOSED`)를 `retryable = true`로.
|
||||
- `MessagingShutdownLifecycle.PHASE`: platform 밖 relay의 순서 테스트가 참조하도록 public.
|
||||
|
||||
버린 대안: vendored 제품은 그대로 두고 application bridge(ACL)가 category를 보고 "인증·인가면 재시도"로
|
||||
번역하는 것. 버린 이유: `retryable`은 이 제품이 "같은 레코드를 나중에 다시 보내면 받아질 수 있나"를 말하는
|
||||
자리다. bridge가 category로 그 판단을 다시 하면 같은 사실을 제품과 bridge가 따로 정하고, 이 제품의
|
||||
`PublishResult`를 읽는 다른 호출자는 bridge와 다른 답을 본다. 대신 이 제품 주석은 소비자 이름(application
|
||||
relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(2026-11-03).
|
||||
|
||||
## Public surface 정책
|
||||
|
||||
- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이
|
||||
숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다.
|
||||
(`kafka-clients`, `cloudevents-api`, `micrometer-core`, `avro`,
|
||||
`protobuf-java`가 이 규칙으로 `api`다.)
|
||||
- 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을
|
||||
`implementation`으로 내린 것이, JSON codec이 `ObjectMapper`를 private으로만 쓰고 Jackson을
|
||||
`implementation`으로 둔 것이 그 예다.
|
||||
- 이 규칙은 문서가 아니라 `MessagingPublicSurfaceContractTest`가 붙들고 있다. leaf의 production
|
||||
source에서 public/protected 시그니처에 등장하는 vendor 라이브러리를 뽑아 그 leaf의
|
||||
`build.gradle`이 `api`로 선언했는지 대조하고, starter의 `api` closure에 broker client 두 개가
|
||||
들어오지 않는 것도 함께 본다. Spring Framework/Boot는 대상이 아니다 — 조립 경계 안에서만
|
||||
등장하고 adopter가 이름 부를 일이 없다.
|
||||
- 새 public 타입은 그 모듈의 계약이다. 삭제·시그니처 변경은 breaking change로 취급한다.
|
||||
|
||||
## Application runtime에 포함되는 기준
|
||||
|
||||
기본 조립에는 Messaging family가 없다. 서비스가 `app-bootstrap/build.gradle`에
|
||||
`runtimeOnly project(':adapter:outbound:messaging-kafka')` 한 줄을 넣으면 그 모듈이 bridge와
|
||||
`messaging-spring-boot-starter`(Kafka transport 포함)의 transitive project graph를 runtime에 싣는다. 이
|
||||
사실의 SSOT는 Gradle `runtimeClasspath`이며 registry에 동일한 membership 목록을 복제하지 않는다.
|
||||
모듈이 있으면 켜지고(`app.messaging.enabled` 기본 `true`), `APP_MESSAGING_ENABLED=false`로만 끈다.
|
||||
|
||||
일부 codec(cloudevents 등)·claim-check·testkit처럼 starter graph에 들어오지 않는 leaf는 build-only다.
|
||||
RabbitMQ·Pulsar·NATS·Kafka Share·Spring Cloud Stream bridge leaf와 Debezium outbox 매핑은
|
||||
2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표).
|
||||
새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy,
|
||||
qualification/support 상태를 함께 변경한다.
|
||||
|
||||
## application이 이 family에 도달하는 경로 (cutover 완료)
|
||||
|
||||
리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한
|
||||
`application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다.
|
||||
|
||||
- application-owned port: `IntegrationEventPublishPort`
|
||||
- bridge: `adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter`
|
||||
- platform boundary: `EncodedMessagePublisher`
|
||||
- central implementation: `DefaultMessagePublisher`
|
||||
|
||||
bridge는 exact canonical envelope bytes를 다시 serialize하지 않고, destination/access/admission/runtime
|
||||
lease/transport/outcome normalization/observation은 platform 중앙 publish path를 그대로 탄다. bridge
|
||||
package는 `messaging-core-api`만 보며 concrete runtime/transport/Kafka 타입을
|
||||
직접 보지 않는다.
|
||||
|
||||
**application bridge cutover는 2026-09-28에 끝났다(2026-09-25 소유자 결정).** application의 outbox append는 canonical
|
||||
`OutboxAppendPort` 하나이고, relay는 claim한 row의 validated event를 이 bridge로만 보낸다. legacy
|
||||
`OutboxEvent`·`LegacyOutboxAppendPort`와 `MessageBroker → KafkaSender` R0 경로(TLS/SASL을 적용하지
|
||||
않던 두 번째 producer)는 삭제했다. 남은 Kafka producer는 platform의 것 하나이고, broker security
|
||||
profile(`KafkaSecurityConfigurer`)을 적용한다.
|
||||
|
||||
canonical bridge의 producer identity는 `app.messaging.producer-id`로 명시한다. 값이 없으면 bridge bean을
|
||||
만들지 않으며 `spring.application.name`/host/pod 이름에서 identity를 발명하지 않는다. bridge가 없으면
|
||||
relay가 발행할 곳이 없으므로 messaging 모듈이 켜진 상태에서는 기동이 거부된다.
|
||||
|
||||
`IntegrationEventEncoderPort`는 템플릿이 제공한다: `adapter:outbound:support`의
|
||||
`JsonIntegrationEventEncoder`가 envelope v1(`shared-contract`의 `contracts/messaging/envelope/v1.schema.json`)
|
||||
안에 payload record를 결정적 JSON으로 싣는다. 계약 catalog는 애플리케이션이 bean으로 등록한
|
||||
`IntegrationEventContractContribution`뿐이고, 선언한 payload schema hash가 classpath의 schema 파일과
|
||||
다르면 기동이 실패한다. payload를 JSON Schema로 매번 검증하려는 서비스는 자기 encoder bean을 두면 된다.
|
||||
|
||||
## Stable 승격에 필요한 증거
|
||||
|
||||
adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/support-matrix.md`가 현재
|
||||
상태를 기록한다):
|
||||
|
||||
1. 실제 broker container를 쓰는 fault 시나리오 lane이 존재하고, 그 lane이
|
||||
`BrokerCertificationEvidence`를 산출한다.
|
||||
2. `NetworkFaultScenario` 전 항목에 대해 evidence가 있거나, 없는 항목이 `knownGaps`로 명시된다.
|
||||
3. capability 선언이 코드에서 파생된다 — `MessagingCapabilities`에 손으로 `true`를 쓰는 것은
|
||||
증거가 아니다.
|
||||
4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은
|
||||
Experimental에서도 금지다.
|
||||
5. unknown failure의 기본값이 `AMBIGUOUS`다. `REJECTED`는 전송이 시작되지 않았다는 typed 증거가
|
||||
있을 때만.
|
||||
|
||||
Stable 문구는 evidence manifest가 존재할 때만 문서에 쓴다.
|
||||
|
||||
증거를 만드는 것은 인증 레인이고, manifest는 그 실행의 출력이다:
|
||||
|
||||
```bash
|
||||
./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence --console=plain
|
||||
```
|
||||
|
||||
레인(`messagingCertificationTest`)은 Toxiproxy를 broker 앞에 두고 장애를 주입하며,
|
||||
통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을
|
||||
`messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl`에 쓴다.
|
||||
게이트는 커밋된 manifest와 이번 실행의 출력을 대조한다 — **manifest를 손으로 고치면 실패하고,
|
||||
레인을 돌리면 manifest가 다시 쓰인다.** 이 레인만은 Docker 가드를 달지 않는다(없으면 실패한다).
|
||||
skip하는 인증 레인은 아무도 켜지 않은 브로커에 대해 성공을 보고하기 때문이며, 그래서 `test`에서는
|
||||
`messaging-certification` 태그로 제외된다.
|
||||
|
||||
## Focused test
|
||||
|
||||
leaf의 `gradle_path`를 registry에서 읽어 파생한다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew <gradle-path>:test --console=plain
|
||||
```
|
||||
|
||||
Family 전체 검증:
|
||||
|
||||
```bash
|
||||
./gradlew verifyCleanArchitectureDependencies --console=plain
|
||||
./gradlew architectureCheck --console=plain
|
||||
./gradlew verifyDependencyLocks --console=plain
|
||||
```
|
||||
@@ -0,0 +1,14 @@
|
||||
plugins {
|
||||
id 'ca.platform-module'
|
||||
}
|
||||
|
||||
// The admin plane: its contract (package `admin`) and the stdlib services that execute it
|
||||
// (package `admin.runtime`). They were two leaves, and every consumer of the runtime took the
|
||||
// contract too, so the split added a registry entry without separating anything (S7-#12).
|
||||
dependencies {
|
||||
api project(':messaging:messaging-core-api')
|
||||
|
||||
// ReplayService records a MessagingAuditEvent internally; no public signature names it, so
|
||||
// Micrometer does not reach the journal adapters that implement the contract.
|
||||
implementation project(':messaging:messaging-observability')
|
||||
}
|
||||
@@ -0,0 +1,89 @@
|
||||
# This is a Gradle generated file for dependency locking.
|
||||
# Manual edits can break the build and are not advised.
|
||||
# This file is expected to be part of source control.
|
||||
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
|
||||
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
|
||||
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
|
||||
com.github.spotbugs:spotbugs:4.10.2=spotbugs
|
||||
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
|
||||
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
|
||||
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
|
||||
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
|
||||
com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs
|
||||
com.google.code.gson:gson:2.13.2=spotbugs
|
||||
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
|
||||
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
|
||||
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:guava:33.6.0-jre=checkstyle
|
||||
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
|
||||
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
|
||||
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
|
||||
commons-beanutils:commons-beanutils:1.11.0=checkstyle
|
||||
commons-collections:commons-collections:3.2.2=checkstyle
|
||||
commons-io:commons-io:2.21.0=spotbugs
|
||||
info.picocli:picocli:4.7.7=checkstyle
|
||||
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
|
||||
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
|
||||
io.micrometer:micrometer-commons:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
io.micrometer:micrometer-core:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
io.micrometer:micrometer-observation:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
|
||||
jaxen:jaxen:2.0.6=spotbugs
|
||||
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
|
||||
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
|
||||
org.antlr:antlr4-runtime:4.13.2=checkstyle
|
||||
org.apache.bcel:bcel:6.12.0=spotbugs
|
||||
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
|
||||
org.apache.commons:commons-text:1.15.0=spotbugs
|
||||
org.apache.commons:commons-text:1.3=checkstyle
|
||||
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
|
||||
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
|
||||
org.apache.logging.log4j:log4j-api:2.25.5=spotbugs
|
||||
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
|
||||
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
|
||||
org.apache.xbean:xbean-reflect:3.7=checkstyle
|
||||
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
|
||||
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
|
||||
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
|
||||
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
|
||||
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
|
||||
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
|
||||
org.dom4j:dom4j:2.2.0=spotbugs
|
||||
org.hdrhistogram:HdrHistogram:2.2.2=runtimeClasspath,testRuntimeClasspath
|
||||
org.javassist:javassist:3.28.0-GA=checkstyle
|
||||
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
|
||||
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit:junit-bom:6.1.0=spotbugs
|
||||
org.latencyutils:LatencyUtils:2.0.3=runtimeClasspath,testRuntimeClasspath
|
||||
org.mockito:mockito-core:5.20.0=mockitoAgent
|
||||
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
|
||||
org.ow2.asm:asm-analysis:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-commons:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-tree:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-util:9.10.1=spotbugs
|
||||
org.ow2.asm:asm:9.10.1=spotbugs
|
||||
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
|
||||
org.reflections:reflections:0.10.2=checkstyle
|
||||
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.18=checkstyle
|
||||
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
|
||||
empty=
|
||||
+45
@@ -0,0 +1,45 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* The approval that authorises a destructive messaging operation.
|
||||
*
|
||||
* <p>Approvals expire. An open-ended approval becomes a standing permission, which is the same
|
||||
* thing as no approval at all — the window is what keeps "we approved a redrive last quarter" from
|
||||
* authorising one today.
|
||||
*
|
||||
* @param ticket the change reference
|
||||
* @param approvedBy the approver's identity
|
||||
* @param approvedAt when the approval was granted
|
||||
* @param validUntil when the approval stops authorising anything
|
||||
*/
|
||||
public record AdminApproval(
|
||||
String ticket, String approvedBy, Instant approvedAt, Instant validUntil) {
|
||||
|
||||
public AdminApproval {
|
||||
Objects.requireNonNull(approvedAt, "approvedAt must not be null");
|
||||
Objects.requireNonNull(validUntil, "validUntil must not be null");
|
||||
if (ticket == null || ticket.isBlank()) {
|
||||
throw new IllegalArgumentException("ticket must not be blank");
|
||||
}
|
||||
if (approvedBy == null || approvedBy.isBlank()) {
|
||||
throw new IllegalArgumentException("approvedBy must not be blank");
|
||||
}
|
||||
if (validUntil.isBefore(approvedAt)) {
|
||||
throw new IllegalArgumentException("an approval cannot expire before it was granted");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether the approval still authorises an operation.
|
||||
*
|
||||
* @param now the current instant
|
||||
* @return true while inside the window
|
||||
*/
|
||||
public boolean isValidAt(Instant now) {
|
||||
Objects.requireNonNull(now, "now must not be null");
|
||||
return !now.isBefore(approvedAt) && now.isBefore(validUntil);
|
||||
}
|
||||
}
|
||||
+93
@@ -0,0 +1,93 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Where a destructive operation records that it started, how far it got, and how it ended.
|
||||
*
|
||||
* <p>The implementation this replaced was a {@code ConcurrentHashMap} registered by the starter as
|
||||
* the default. Two consequences followed, and both are worse than having no store at all because
|
||||
* the map made the platform look protected. A restart forgot every claim, so the same approval
|
||||
* could be executed again by the same process. And two replicas each had their own map, so both
|
||||
* could claim the same approval at the same moment and each believe it was the only one.
|
||||
*
|
||||
* <p>Implementations must therefore be shared and durable, must enforce uniqueness on {@code
|
||||
* (approvalTicket, planDigest)}, and must hand out leases with a monotonic fencing token so a
|
||||
* process that stalled past its lease cannot write over the replica that took over from it.
|
||||
*/
|
||||
public interface AdminOperationJournal {
|
||||
|
||||
/**
|
||||
* Claims an operation, or resumes the previous attempt at it.
|
||||
*
|
||||
* @param approvalTicket the approval authorising the operation
|
||||
* @param planDigest the exact plan
|
||||
* @param operationId this execution's identity
|
||||
* @param leaseOwner the runtime claiming it
|
||||
* @param leaseDuration how long the lease holds before another runtime may take over
|
||||
* @param now the current instant
|
||||
* @return the lease, carrying the point to resume from
|
||||
* @throws dev.caskeleton.messaging.api.error.MessageAuthorizationException when the operation
|
||||
* already completed, or another runtime holds a live lease on it
|
||||
*/
|
||||
AdminOperationLease begin(
|
||||
String approvalTicket,
|
||||
PlanDigest planDigest,
|
||||
String operationId,
|
||||
String leaseOwner,
|
||||
Duration leaseDuration,
|
||||
Instant now);
|
||||
|
||||
/**
|
||||
* Records durable progress and extends the lease.
|
||||
*
|
||||
* @param lease the lease held
|
||||
* @param itemsCompleted how many items are now durably done
|
||||
* @param leaseDuration how much longer to hold the lease
|
||||
* @param now the current instant
|
||||
* @throws dev.caskeleton.messaging.api.error.MessageAuthorizationException when the lease has
|
||||
* been taken over by a newer token
|
||||
*/
|
||||
void checkpoint(
|
||||
AdminOperationLease lease, int itemsCompleted, Duration leaseDuration, Instant now);
|
||||
|
||||
/**
|
||||
* Marks the operation finished. The approval is spent.
|
||||
*
|
||||
* @param lease the lease held
|
||||
* @param itemsCompleted the final count
|
||||
* @param now the current instant
|
||||
*/
|
||||
void complete(AdminOperationLease lease, int itemsCompleted, Instant now);
|
||||
|
||||
/**
|
||||
* Marks the operation failed at its current checkpoint, leaving it resumable.
|
||||
*
|
||||
* @param lease the lease held
|
||||
* @param itemsCompleted how many items are durably done
|
||||
* @param failureCode a sanitised, bounded reason
|
||||
* @param now the current instant
|
||||
*/
|
||||
void fail(AdminOperationLease lease, int itemsCompleted, String failureCode, Instant now);
|
||||
|
||||
/**
|
||||
* Reads the journal entry for an operation.
|
||||
*
|
||||
* @param approvalTicket the approval
|
||||
* @param planDigest the plan
|
||||
* @return the record, when the operation has been journalled
|
||||
*/
|
||||
Optional<AdminOperationRecord> find(String approvalTicket, PlanDigest planDigest);
|
||||
|
||||
/**
|
||||
* Whether this implementation survives a restart and is shared between replicas.
|
||||
*
|
||||
* <p>Declared rather than inferred so the starter can refuse to run a production profile on an
|
||||
* in-memory journal instead of discovering the gap during an incident.
|
||||
*
|
||||
* @return true when the journal is durable and shared
|
||||
*/
|
||||
boolean isDurable();
|
||||
}
|
||||
+55
@@ -0,0 +1,55 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* The right to execute one journalled operation, and the point to resume it from.
|
||||
*
|
||||
* <p>{@code resumeFrom} is the whole reason a lease is handed out rather than a boolean. A retry
|
||||
* after a crash is not a new execution of the approval — it is the same operation continuing, and
|
||||
* treating it as new is what republishes the items the first attempt already moved.
|
||||
*
|
||||
* @param approvalTicket the approval being executed
|
||||
* @param planDigest the plan being executed
|
||||
* @param operationId this execution's identity
|
||||
* @param leaseOwner the runtime holding the lease
|
||||
* @param leaseToken the fencing token; a write from an older token must be refused
|
||||
* @param resumeFrom how many items the previous attempt durably completed
|
||||
*/
|
||||
public record AdminOperationLease(
|
||||
String approvalTicket,
|
||||
PlanDigest planDigest,
|
||||
String operationId,
|
||||
String leaseOwner,
|
||||
long leaseToken,
|
||||
int resumeFrom) {
|
||||
|
||||
/** Validates the lease. */
|
||||
public AdminOperationLease {
|
||||
Objects.requireNonNull(planDigest, "planDigest must not be null");
|
||||
if (approvalTicket == null || approvalTicket.isBlank()) {
|
||||
throw new IllegalArgumentException("approvalTicket must not be blank");
|
||||
}
|
||||
if (operationId == null || operationId.isBlank()) {
|
||||
throw new IllegalArgumentException("operationId must not be blank");
|
||||
}
|
||||
if (leaseOwner == null || leaseOwner.isBlank()) {
|
||||
throw new IllegalArgumentException("leaseOwner must not be blank");
|
||||
}
|
||||
if (leaseToken < 1) {
|
||||
throw new IllegalArgumentException("a lease token starts at one");
|
||||
}
|
||||
if (resumeFrom < 0) {
|
||||
throw new IllegalArgumentException("resumeFrom must not be negative");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether this lease continues an earlier attempt.
|
||||
*
|
||||
* @return true when items were already completed
|
||||
*/
|
||||
public boolean isResumption() {
|
||||
return resumeFrom > 0;
|
||||
}
|
||||
}
|
||||
+63
@@ -0,0 +1,63 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* One row of the destructive-operation journal.
|
||||
*
|
||||
* <p>Keyed by {@code (approvalTicket, planDigest)} rather than by the ticket alone, because the
|
||||
* ticket alone cannot distinguish "this approval already ran" from "this approval is being reused
|
||||
* for a different plan" — and those need opposite answers.
|
||||
*
|
||||
* @param approvalTicket the approval that authorised the operation
|
||||
* @param planDigest the exact plan that was authorised
|
||||
* @param operationId the caller-side identity of this execution
|
||||
* @param state where the operation stands
|
||||
* @param itemsCompleted how many items are durably done
|
||||
* @param leaseOwner which runtime currently holds the lease
|
||||
* @param leaseToken the fencing token, incremented on every takeover
|
||||
* @param leaseExpiresAt when another runtime may take the lease over
|
||||
* @param startedAt when the operation first began
|
||||
* @param finishedAt when it reached a terminal state
|
||||
* @param failureCode the sanitised reason it failed, when it did
|
||||
*/
|
||||
public record AdminOperationRecord(
|
||||
String approvalTicket,
|
||||
PlanDigest planDigest,
|
||||
String operationId,
|
||||
AdminOperationState state,
|
||||
int itemsCompleted,
|
||||
String leaseOwner,
|
||||
long leaseToken,
|
||||
Instant leaseExpiresAt,
|
||||
Instant startedAt,
|
||||
Optional<Instant> finishedAt,
|
||||
Optional<String> failureCode) {
|
||||
|
||||
/** Validates the record. */
|
||||
public AdminOperationRecord {
|
||||
Objects.requireNonNull(planDigest, "planDigest must not be null");
|
||||
Objects.requireNonNull(state, "state must not be null");
|
||||
Objects.requireNonNull(leaseExpiresAt, "leaseExpiresAt must not be null");
|
||||
Objects.requireNonNull(startedAt, "startedAt must not be null");
|
||||
Objects.requireNonNull(finishedAt, "finishedAt must not be null");
|
||||
Objects.requireNonNull(failureCode, "failureCode must not be null");
|
||||
if (approvalTicket == null || approvalTicket.isBlank()) {
|
||||
throw new IllegalArgumentException("approvalTicket must not be blank");
|
||||
}
|
||||
if (operationId == null || operationId.isBlank()) {
|
||||
throw new IllegalArgumentException("operationId must not be blank");
|
||||
}
|
||||
if (leaseOwner == null || leaseOwner.isBlank()) {
|
||||
throw new IllegalArgumentException("leaseOwner must not be blank");
|
||||
}
|
||||
if (itemsCompleted < 0) {
|
||||
throw new IllegalArgumentException("itemsCompleted must not be negative");
|
||||
}
|
||||
if (leaseToken < 1) {
|
||||
throw new IllegalArgumentException("a lease token starts at one");
|
||||
}
|
||||
}
|
||||
}
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
/**
|
||||
* Where a journalled destructive operation stands.
|
||||
*
|
||||
* <p>The store this replaces recorded one fact — "this approval was claimed" — and recorded it
|
||||
* before any work happened. A run that died halfway had consumed its approval, left no record of
|
||||
* how far it got, and offered the operator two equally bad choices: request a fresh approval and
|
||||
* redo work that may already have been done, or leave the operation half-applied.
|
||||
*/
|
||||
public enum AdminOperationState {
|
||||
|
||||
/** Claimed and in progress. A lease is held; the checkpoint says how far it got. */
|
||||
STARTED,
|
||||
|
||||
/** Every item finished. The approval is spent and must not run again. */
|
||||
COMPLETED,
|
||||
|
||||
/** The run stopped before finishing. It may be resumed from its checkpoint under a new lease. */
|
||||
FAILED
|
||||
}
|
||||
+98
@@ -0,0 +1,98 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Everything an issuer signs when granting one destructive operation.
|
||||
*
|
||||
* <p>{@link AdminApproval} carried a ticket, an approver, and a window. Nothing in it said which
|
||||
* operation, on which destination, against which topology, or up to what impact — so the same
|
||||
* approval authorised every plan presented inside the window, and the audit trail recorded a ticket
|
||||
* that proved nothing about what was executed.
|
||||
*
|
||||
* <p>Every field here is part of the signed canonical form, which is what makes the grant
|
||||
* non-transferable: change the target, the topology version, the impact ceiling, or the plan, and
|
||||
* the signature no longer verifies.
|
||||
*
|
||||
* @param approval the ticket, approver, and validity window
|
||||
* @param requestedBy the operator who will execute it, kept separate from the approver
|
||||
* @param operation the destructive operation being authorised
|
||||
* @param source the destination read from
|
||||
* @param target the destination written to, when the operation has one
|
||||
* @param topologyVersion the topology the impact estimate was computed against
|
||||
* @param maxImpact the largest number of messages the approver agreed to
|
||||
* @param planDigest the fingerprint of the exact plan
|
||||
*/
|
||||
public record ApprovalGrant(
|
||||
AdminApproval approval,
|
||||
String requestedBy,
|
||||
DestructiveOperation operation,
|
||||
DestinationName source,
|
||||
Optional<DestinationName> target,
|
||||
String topologyVersion,
|
||||
long maxImpact,
|
||||
PlanDigest planDigest) {
|
||||
|
||||
/** Validates the grant and enforces subject separation. */
|
||||
public ApprovalGrant {
|
||||
Objects.requireNonNull(approval, "approval must not be null");
|
||||
Objects.requireNonNull(operation, "operation must not be null");
|
||||
Objects.requireNonNull(source, "source must not be null");
|
||||
Objects.requireNonNull(target, "target must not be null");
|
||||
Objects.requireNonNull(topologyVersion, "topologyVersion must not be null");
|
||||
Objects.requireNonNull(planDigest, "planDigest must not be null");
|
||||
if (requestedBy == null || requestedBy.isBlank()) {
|
||||
throw new IllegalArgumentException("requestedBy must not be blank");
|
||||
}
|
||||
if (approval.approvedBy().equals(requestedBy)) {
|
||||
// Four-eyes, expressed where it cannot be skipped: an operator approving their own
|
||||
// destructive operation is the control not existing.
|
||||
throw new IllegalArgumentException(
|
||||
"the approver and the operator must be different people; both are " + requestedBy);
|
||||
}
|
||||
if (maxImpact < 0) {
|
||||
throw new IllegalArgumentException("maxImpact must not be negative");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Renders the grant deterministically for signing and verification.
|
||||
*
|
||||
* <p>Every field is length-prefixed rather than delimited. A delimiter can be smuggled into a
|
||||
* ticket or an identity to make two different grants render identically; a length prefix cannot.
|
||||
*
|
||||
* @return the canonical form
|
||||
*/
|
||||
public String canonicalForm() {
|
||||
StringBuilder canonical = new StringBuilder("v1");
|
||||
appendField(canonical, approval.ticket());
|
||||
appendField(canonical, approval.approvedBy());
|
||||
appendField(canonical, requestedBy);
|
||||
appendField(canonical, operation.name());
|
||||
appendField(canonical, source.value());
|
||||
appendField(canonical, target.map(DestinationName::value).orElse(""));
|
||||
appendField(canonical, topologyVersion);
|
||||
appendField(canonical, Long.toString(maxImpact));
|
||||
appendField(canonical, planDigest.value());
|
||||
appendField(canonical, approval.approvedAt().toString());
|
||||
appendField(canonical, approval.validUntil().toString());
|
||||
return canonical.toString();
|
||||
}
|
||||
|
||||
private static void appendField(StringBuilder canonical, String value) {
|
||||
canonical.append(value.length()).append(':').append(value);
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether the grant still authorises anything.
|
||||
*
|
||||
* @param now the current instant
|
||||
* @return true while inside the approval window
|
||||
*/
|
||||
public boolean isValidAt(Instant now) {
|
||||
return approval.isValidAt(now);
|
||||
}
|
||||
}
|
||||
+29
@@ -0,0 +1,29 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import java.time.Instant;
|
||||
|
||||
/**
|
||||
* The only thing that can turn a signed grant into a {@link VerifiedApproval}.
|
||||
*
|
||||
* <p>An implementation must check, at minimum: the issuer's signature over {@link
|
||||
* ApprovalGrant#canonicalForm()}, that the approval window is open at {@code now}, and that the
|
||||
* digest the caller is about to execute is the digest that was signed. Everything else the grant
|
||||
* binds — operation, source, target, topology version, impact ceiling, approver-versus-operator
|
||||
* separation — is inside the canonical form, so a signature check covers them all at once.
|
||||
*/
|
||||
public interface ApprovalVerifier {
|
||||
|
||||
/**
|
||||
* Verifies a signed grant against the plan actually about to run.
|
||||
*
|
||||
* @param grant what the issuer signed
|
||||
* @param signature the issuer's signature over the grant's canonical form
|
||||
* @param executingDigest the digest of the plan the caller is about to execute
|
||||
* @param now the current instant
|
||||
* @return the verified approval
|
||||
* @throws dev.caskeleton.messaging.api.error.MessageAuthorizationException when anything about
|
||||
* the grant, the signature, the window, or the digest does not hold
|
||||
*/
|
||||
VerifiedApproval verify(
|
||||
ApprovalGrant grant, String signature, PlanDigest executingDigest, Instant now);
|
||||
}
|
||||
+95
@@ -0,0 +1,95 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* A redrive plan that a named human has approved.
|
||||
*
|
||||
* <p>Carries {@code loopAcknowledged} separately from the approval itself. Approving a redrive of
|
||||
* 900 parked messages and approving a redrive that will re-fail 400 of them are different
|
||||
* decisions, and the second one needs the approver to have seen the number — so the plan cannot
|
||||
* execute on a loop-risking set unless that was acknowledged explicitly.
|
||||
*
|
||||
* @param plan the plan that was approved
|
||||
* @param approval the approval authorising it
|
||||
* @param loopAcknowledged whether the approver accepted the previously-redriven candidates
|
||||
*/
|
||||
public record ApprovedRedrivePlan(
|
||||
RedrivePlan plan, VerifiedApproval approval, boolean loopAcknowledged) {
|
||||
|
||||
/** Binds the approval to this exact plan at construction. */
|
||||
public ApprovedRedrivePlan {
|
||||
Objects.requireNonNull(plan, "plan must not be null");
|
||||
Objects.requireNonNull(approval, "approval must not be null");
|
||||
if (!approval.grant().planDigest().equals(plan.digest())) {
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_PLAN_MISMATCH",
|
||||
"approval %s was issued for a different plan than the one it is attached to"
|
||||
.formatted(approval.ticket()));
|
||||
}
|
||||
if (approval.grant().operation() != DestructiveOperation.REDRIVE) {
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_OPERATION_MISMATCH",
|
||||
"approval %s authorises %s, not a redrive"
|
||||
.formatted(approval.ticket(), approval.grant().operation()));
|
||||
}
|
||||
if (!approval.grant().source().equals(plan.request().source())
|
||||
|| !approval.grant().target().equals(java.util.Optional.of(plan.request().target()))) {
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_SOURCE_MISMATCH",
|
||||
"approval %s authorises %s to %s, not %s to %s"
|
||||
.formatted(
|
||||
approval.ticket(),
|
||||
approval.grant().source().value(),
|
||||
approval.grant().target().map(DestinationName::value).orElse("(none)"),
|
||||
plan.request().source().value(),
|
||||
plan.request().target().value()));
|
||||
}
|
||||
if (plan.candidates() > approval.grant().maxImpact()) {
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_IMPACT_EXCEEDED",
|
||||
"the plan moves %d messages but the approver agreed to at most %d"
|
||||
.formatted(plan.candidates(), approval.grant().maxImpact()));
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Refuses execution when the approval, the topology, or the loop risk no longer permits it.
|
||||
*
|
||||
* @param now the current instant
|
||||
* @param currentTopologyVersion the topology version at execution time
|
||||
* @throws MessageAuthorizationException when the plan may not execute
|
||||
*/
|
||||
public void requireExecutable(Instant now, String currentTopologyVersion) {
|
||||
Objects.requireNonNull(now, "now must not be null");
|
||||
Objects.requireNonNull(currentTopologyVersion, "currentTopologyVersion must not be null");
|
||||
|
||||
if (!approval.isValidAt(now)) {
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_EXPIRED", "approval %s is not valid at %s".formatted(approval.ticket(), now));
|
||||
}
|
||||
if (!approval.grant().topologyVersion().equals(currentTopologyVersion)) {
|
||||
throw new MessageAuthorizationException(
|
||||
"TOPOLOGY_CHANGED_SINCE_APPROVAL",
|
||||
"approval %s was signed against topology %s but the broker is now at %s"
|
||||
.formatted(
|
||||
approval.ticket(), approval.grant().topologyVersion(), currentTopologyVersion));
|
||||
}
|
||||
if (!plan.topologyVersion().equals(currentTopologyVersion)) {
|
||||
throw new MessageAuthorizationException(
|
||||
"TOPOLOGY_CHANGED_SINCE_APPROVAL",
|
||||
"the plan was approved against topology %s but the broker is now at %s"
|
||||
.formatted(plan.topologyVersion(), currentTopologyVersion));
|
||||
}
|
||||
if (plan.risksALoop() && !loopAcknowledged) {
|
||||
throw new MessageAuthorizationException(
|
||||
"REDRIVE_LOOP_NOT_ACKNOWLEDGED",
|
||||
"%d of the %d candidates already failed a previous redrive; re-running them without "
|
||||
.formatted(plan.alreadyRedrivenCandidates(), plan.candidates())
|
||||
+ "fixing the cause produces a loop that looks like progress");
|
||||
}
|
||||
}
|
||||
}
|
||||
+86
@@ -0,0 +1,86 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* A replay plan that a named human has approved.
|
||||
*
|
||||
* <p>A distinct type from {@link ReplayPlan} rather than a boolean on it. The execute method takes
|
||||
* this type, so an unapproved plan cannot reach it — the authorisation is enforced by the compiler
|
||||
* instead of by a runtime check somebody can forget to write.
|
||||
*
|
||||
* @param plan the plan that was approved
|
||||
* @param approval the approval authorising it
|
||||
*/
|
||||
public record ApprovedReplayPlan(ReplayPlan plan, VerifiedApproval approval) {
|
||||
|
||||
/** Binds the approval to this exact plan at construction. */
|
||||
public ApprovedReplayPlan {
|
||||
Objects.requireNonNull(plan, "plan must not be null");
|
||||
Objects.requireNonNull(approval, "approval must not be null");
|
||||
if (!approval.grant().planDigest().equals(plan.digest())) {
|
||||
// A genuine, verified approval for a different plan. Checking it here means the mismatch
|
||||
// cannot survive to the execute call under any code path.
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_PLAN_MISMATCH",
|
||||
"approval %s was issued for a different plan than the one it is attached to"
|
||||
.formatted(approval.ticket()));
|
||||
}
|
||||
if (approval.grant().operation() != DestructiveOperation.REPLAY) {
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_OPERATION_MISMATCH",
|
||||
"approval %s authorises %s, not a replay"
|
||||
.formatted(approval.ticket(), approval.grant().operation()));
|
||||
}
|
||||
if (!approval.grant().source().equals(plan.request().destination())) {
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_SOURCE_MISMATCH",
|
||||
"approval %s authorises %s, not %s"
|
||||
.formatted(
|
||||
approval.ticket(),
|
||||
approval.grant().source().value(),
|
||||
plan.request().destination().value()));
|
||||
}
|
||||
if (plan.estimatedMessages() > approval.grant().maxImpact()) {
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_IMPACT_EXCEEDED",
|
||||
"the plan moves about %d messages but the approver agreed to at most %d"
|
||||
.formatted(plan.estimatedMessages(), approval.grant().maxImpact()));
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Refuses execution when the approval or the plan no longer applies.
|
||||
*
|
||||
* @param now the current instant
|
||||
* @param currentTopologyVersion the topology version at execution time
|
||||
* @throws MessageAuthorizationException when the approval has expired or the topology moved
|
||||
*/
|
||||
public void requireExecutable(Instant now, String currentTopologyVersion) {
|
||||
Objects.requireNonNull(now, "now must not be null");
|
||||
Objects.requireNonNull(currentTopologyVersion, "currentTopologyVersion must not be null");
|
||||
|
||||
if (!approval.isValidAt(now)) {
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_EXPIRED", "approval %s is not valid at %s".formatted(approval.ticket(), now));
|
||||
}
|
||||
if (!approval.grant().topologyVersion().equals(currentTopologyVersion)) {
|
||||
throw new MessageAuthorizationException(
|
||||
"TOPOLOGY_CHANGED_SINCE_APPROVAL",
|
||||
"approval %s was signed against topology %s but the broker is now at %s"
|
||||
.formatted(
|
||||
approval.ticket(), approval.grant().topologyVersion(), currentTopologyVersion));
|
||||
}
|
||||
if (!plan.topologyVersion().equals(currentTopologyVersion)) {
|
||||
// Every number in the plan was computed against the old topology, so the approver agreed to
|
||||
// an impact estimate that no longer describes what would happen.
|
||||
throw new MessageAuthorizationException(
|
||||
"TOPOLOGY_CHANGED_SINCE_APPROVAL",
|
||||
"the plan was approved against topology %s but the broker is now at %s; the estimated "
|
||||
.formatted(plan.topologyVersion(), currentTopologyVersion)
|
||||
+ "impact no longer applies and the plan must be rebuilt");
|
||||
}
|
||||
}
|
||||
}
|
||||
+46
@@ -0,0 +1,46 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import java.util.Map;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* What the broker actually reports for one destination.
|
||||
*
|
||||
* <p>The counterpart to {@link TopologyManifest}: the manifest is what was declared, this is what
|
||||
* exists. Kept as a separate type rather than reusing the manifest so that a comparison cannot
|
||||
* accidentally compare a manifest with itself and report success.
|
||||
*
|
||||
* @param physicalName the broker-side name
|
||||
* @param partitions the observed partition count
|
||||
* @param replicationFactor the observed replication factor
|
||||
* @param configuration the observed configuration entries
|
||||
* @param exists whether the destination is present at all
|
||||
*/
|
||||
public record DestinationTopology(
|
||||
String physicalName,
|
||||
int partitions,
|
||||
int replicationFactor,
|
||||
Map<String, String> configuration,
|
||||
boolean exists) {
|
||||
|
||||
public DestinationTopology {
|
||||
Objects.requireNonNull(configuration, "configuration must not be null");
|
||||
if (physicalName == null || physicalName.isBlank()) {
|
||||
throw new IllegalArgumentException("physicalName must not be blank");
|
||||
}
|
||||
if (exists && partitions < 1) {
|
||||
throw new IllegalArgumentException("an existing destination has at least one partition");
|
||||
}
|
||||
configuration = Map.copyOf(configuration);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the topology for a destination the broker does not have.
|
||||
*
|
||||
* @param physicalName the broker-side name that was looked up
|
||||
* @return the absent topology
|
||||
*/
|
||||
public static DestinationTopology absent(String physicalName) {
|
||||
return new DestinationTopology(physicalName, 0, 0, Map.of(), false);
|
||||
}
|
||||
}
|
||||
+25
@@ -0,0 +1,25 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
/**
|
||||
* The operations that cannot be undone.
|
||||
*
|
||||
* <p>Enumerated so the guard is exhaustive rather than a list of {@code if} statements that a new
|
||||
* operation can quietly avoid.
|
||||
*/
|
||||
public enum DestructiveOperation {
|
||||
|
||||
/** Re-read a destination from an earlier position. */
|
||||
REPLAY,
|
||||
|
||||
/** Move messages from a dead letter destination back to their source. */
|
||||
REDRIVE,
|
||||
|
||||
/** Move a consumer group's committed position. */
|
||||
OFFSET_RESET,
|
||||
|
||||
/** Discard the contents of a destination. */
|
||||
PURGE,
|
||||
|
||||
/** Remove a destination entirely. */
|
||||
DELETE_DESTINATION
|
||||
}
|
||||
+95
@@ -0,0 +1,95 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* The single gate every destructive messaging operation passes through.
|
||||
*
|
||||
* <p>Four conditions, all required. The caller must hold the admin credential — an application
|
||||
* runtime does not, by construction. The approval must be present and inside its validity window.
|
||||
* And a dry run is always permitted, because the way to make operators plan before they act is to
|
||||
* make planning free.
|
||||
*
|
||||
* <p>Centralised so that adding a new destructive operation means adding an enum constant, not
|
||||
* remembering to re-implement the checks.
|
||||
*/
|
||||
public final class DestructiveOperationGuard {
|
||||
|
||||
private final boolean adminCredentialPresent;
|
||||
|
||||
/**
|
||||
* Creates a guard for a runtime.
|
||||
*
|
||||
* @param adminCredentialPresent whether this runtime holds the admin credential
|
||||
*/
|
||||
public DestructiveOperationGuard(boolean adminCredentialPresent) {
|
||||
this.adminCredentialPresent = adminCredentialPresent;
|
||||
}
|
||||
|
||||
/**
|
||||
* Authorises one destructive operation.
|
||||
*
|
||||
* @param operation the operation
|
||||
* @param destination the destination affected
|
||||
* @param approval the verified approval, when one was supplied
|
||||
* @param dryRun whether this is a plan-only run
|
||||
* @param now the current instant
|
||||
* @throws MessageAuthorizationException when the operation is not authorised
|
||||
*/
|
||||
public void authorize(
|
||||
DestructiveOperation operation,
|
||||
DestinationName destination,
|
||||
Optional<VerifiedApproval> approval,
|
||||
boolean dryRun,
|
||||
Instant now) {
|
||||
Objects.requireNonNull(operation, "operation must not be null");
|
||||
Objects.requireNonNull(destination, "destination must not be null");
|
||||
Objects.requireNonNull(approval, "approval must not be null");
|
||||
Objects.requireNonNull(now, "now must not be null");
|
||||
|
||||
if (dryRun) {
|
||||
return;
|
||||
}
|
||||
if (!adminCredentialPresent) {
|
||||
throw new MessageAuthorizationException(
|
||||
"ADMIN_CREDENTIAL_REQUIRED",
|
||||
operation + " on " + destination.value() + " requires the admin credential");
|
||||
}
|
||||
VerifiedApproval granted =
|
||||
approval.orElseThrow(
|
||||
() ->
|
||||
new MessageAuthorizationException(
|
||||
"APPROVAL_REQUIRED",
|
||||
operation + " on " + destination.value() + " requires an approval"));
|
||||
if (!granted.isValidAt(now)) {
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_EXPIRED", "approval " + granted.ticket() + " is outside its validity window");
|
||||
}
|
||||
if (granted.grant().operation() != operation) {
|
||||
// The approval verified — for something else. A guard that only checks presence and window
|
||||
// lets a verified redrive approval authorise a destination deletion.
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_OPERATION_MISMATCH",
|
||||
"approval "
|
||||
+ granted.ticket()
|
||||
+ " authorises "
|
||||
+ granted.grant().operation()
|
||||
+ ", not "
|
||||
+ operation);
|
||||
}
|
||||
if (!granted.grant().source().equals(destination)) {
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_SOURCE_MISMATCH",
|
||||
"approval "
|
||||
+ granted.ticket()
|
||||
+ " authorises "
|
||||
+ granted.grant().source().value()
|
||||
+ ", not "
|
||||
+ destination.value());
|
||||
}
|
||||
}
|
||||
}
|
||||
+111
@@ -0,0 +1,111 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.security.MessageDigest;
|
||||
import java.time.Instant;
|
||||
import java.util.HexFormat;
|
||||
import java.util.Objects;
|
||||
import javax.crypto.Mac;
|
||||
import javax.crypto.spec.SecretKeySpec;
|
||||
|
||||
/**
|
||||
* Verifies grants with a shared HMAC-SHA256 issuing key.
|
||||
*
|
||||
* <p>A shared secret rather than a public-key signature is a deliberate scope choice: the issuer is
|
||||
* the change-management system operated by the same organisation as the runtime, so key
|
||||
* distribution is already solved and the property that matters — that an operator cannot mint an
|
||||
* approval for themselves — holds as long as the key is not on the operator's machine. A public-key
|
||||
* verifier can be substituted by implementing {@link ApprovalVerifier}; nothing else in the
|
||||
* platform depends on how the signature is produced.
|
||||
*
|
||||
* <p>Comparison is constant-time. A verifier that compares with {@code equals} leaks the signature
|
||||
* one byte at a time to a caller who can retry, which for an offline attacker with unlimited
|
||||
* attempts is the whole secret.
|
||||
*/
|
||||
public final class HmacApprovalVerifier implements ApprovalVerifier {
|
||||
|
||||
private static final String ALGORITHM = "HmacSHA256";
|
||||
|
||||
private final byte[] issuingKey;
|
||||
|
||||
/**
|
||||
* Creates a verifier over the issuing key.
|
||||
*
|
||||
* @param issuingKey the shared secret the approval issuer signs with
|
||||
*/
|
||||
public HmacApprovalVerifier(byte[] issuingKey) {
|
||||
Objects.requireNonNull(issuingKey, "issuingKey must not be null");
|
||||
if (issuingKey.length < 32) {
|
||||
throw new IllegalArgumentException(
|
||||
"the approval issuing key must be at least 256 bits; a shorter key makes the signature"
|
||||
+ " brute-forceable offline");
|
||||
}
|
||||
this.issuingKey = issuingKey.clone();
|
||||
}
|
||||
|
||||
/**
|
||||
* Produces the signature an issuer would attach to a grant.
|
||||
*
|
||||
* <p>Present because the issuer and the verifier must agree on the canonical form exactly, and a
|
||||
* second implementation of that agreement is a second thing to drift. Holding this key is what
|
||||
* makes a caller an issuer — it is not, and must not become, available to the runtime that
|
||||
* executes operations.
|
||||
*
|
||||
* @param grant the grant to sign
|
||||
* @return the hexadecimal signature
|
||||
*/
|
||||
public String sign(ApprovalGrant grant) {
|
||||
Objects.requireNonNull(grant, "grant must not be null");
|
||||
return HexFormat.of().formatHex(mac(grant.canonicalForm()));
|
||||
}
|
||||
|
||||
@Override
|
||||
public VerifiedApproval verify(
|
||||
ApprovalGrant grant, String signature, PlanDigest executingDigest, Instant now) {
|
||||
Objects.requireNonNull(grant, "grant must not be null");
|
||||
Objects.requireNonNull(signature, "signature must not be null");
|
||||
Objects.requireNonNull(executingDigest, "executingDigest must not be null");
|
||||
Objects.requireNonNull(now, "now must not be null");
|
||||
|
||||
if (!grant.planDigest().equals(executingDigest)) {
|
||||
// The signature would verify: this is a genuine approval, for a different plan. Replaying one
|
||||
// approval across plans is the attack the digest binding exists to stop.
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_PLAN_MISMATCH",
|
||||
"approval %s was issued for plan %s but the plan about to execute is %s"
|
||||
.formatted(
|
||||
grant.approval().ticket(), grant.planDigest().value(), executingDigest.value()));
|
||||
}
|
||||
if (!grant.isValidAt(now)) {
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_EXPIRED",
|
||||
"approval %s is not valid at %s".formatted(grant.approval().ticket(), now));
|
||||
}
|
||||
byte[] presented;
|
||||
try {
|
||||
presented = HexFormat.of().parseHex(signature);
|
||||
} catch (IllegalArgumentException malformed) {
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_SIGNATURE_INVALID", "the approval signature is not hexadecimal");
|
||||
}
|
||||
if (!MessageDigest.isEqual(mac(grant.canonicalForm()), presented)) {
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_SIGNATURE_INVALID",
|
||||
("approval %s does not verify against the issuing key; the grant was altered after it"
|
||||
+ " was signed, or it was never issued")
|
||||
.formatted(grant.approval().ticket()));
|
||||
}
|
||||
return VerifiedApproval.of(grant);
|
||||
}
|
||||
|
||||
private byte[] mac(String canonicalForm) {
|
||||
try {
|
||||
Mac mac = Mac.getInstance(ALGORITHM);
|
||||
mac.init(new SecretKeySpec(issuingKey, ALGORITHM));
|
||||
return mac.doFinal(canonicalForm.getBytes(StandardCharsets.UTF_8));
|
||||
} catch (java.security.GeneralSecurityException failure) {
|
||||
throw new IllegalStateException("HMAC-SHA256 is required of every Java runtime", failure);
|
||||
}
|
||||
}
|
||||
}
|
||||
+47
@@ -0,0 +1,47 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.security.MessageDigest;
|
||||
import java.security.NoSuchAlgorithmException;
|
||||
import java.util.HexFormat;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* The fingerprint of exactly what an approver agreed to.
|
||||
*
|
||||
* <p>An approval used to name a ticket and a window and nothing else, so it authorised any plan
|
||||
* presented within that window. The operator who got a redrive of one dead-letter destination
|
||||
* approved could execute a redrive of a different one with the same ticket, and every audit record
|
||||
* would look correct. Binding the signature to this digest is what makes an approval about a plan
|
||||
* rather than about a period of time.
|
||||
*
|
||||
* @param value the lowercase hexadecimal SHA-256 of the plan's canonical form
|
||||
*/
|
||||
public record PlanDigest(String value) {
|
||||
|
||||
/** Validates the digest shape. */
|
||||
public PlanDigest {
|
||||
Objects.requireNonNull(value, "value must not be null");
|
||||
if (!value.matches("[0-9a-f]{64}")) {
|
||||
throw new IllegalArgumentException("a plan digest is 64 lowercase hexadecimal characters");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Digests a plan's canonical form.
|
||||
*
|
||||
* @param canonicalForm the plan rendered deterministically, field by field
|
||||
* @return the digest
|
||||
*/
|
||||
public static PlanDigest ofCanonical(String canonicalForm) {
|
||||
Objects.requireNonNull(canonicalForm, "canonicalForm must not be null");
|
||||
try {
|
||||
byte[] digest =
|
||||
MessageDigest.getInstance("SHA-256")
|
||||
.digest(canonicalForm.getBytes(StandardCharsets.UTF_8));
|
||||
return new PlanDigest(HexFormat.of().formatHex(digest));
|
||||
} catch (NoSuchAlgorithmException impossible) {
|
||||
throw new IllegalStateException("SHA-256 is required of every Java runtime", impossible);
|
||||
}
|
||||
}
|
||||
}
|
||||
+86
@@ -0,0 +1,86 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* What a redrive would do, produced before anything is moved.
|
||||
*
|
||||
* <p>{@code alreadyRedrivenCandidates} is the number that matters most. A message with a non-zero
|
||||
* redrive count has been sent back to its source before and failed again; redriving it a second
|
||||
* time without fixing the cause produces a loop that looks like progress in every dashboard.
|
||||
* Surfacing the count at plan time is what lets an operator notice before starting it.
|
||||
*
|
||||
* @param request the request this plan was built from
|
||||
* @param candidates how many messages are eligible
|
||||
* @param alreadyRedrivenCandidates how many of those have been redriven before
|
||||
* @param plannedAt when the plan was produced
|
||||
* @param topologyVersion the topology the estimate was computed against
|
||||
*/
|
||||
public record RedrivePlan(
|
||||
RedriveRequest request,
|
||||
int candidates,
|
||||
int alreadyRedrivenCandidates,
|
||||
Instant plannedAt,
|
||||
String topologyVersion) {
|
||||
|
||||
public RedrivePlan {
|
||||
Objects.requireNonNull(request, "request must not be null");
|
||||
Objects.requireNonNull(plannedAt, "plannedAt must not be null");
|
||||
if (candidates < 0) {
|
||||
throw new IllegalArgumentException("candidates must not be negative");
|
||||
}
|
||||
if (alreadyRedrivenCandidates < 0 || alreadyRedrivenCandidates > candidates) {
|
||||
throw new IllegalArgumentException(
|
||||
"alreadyRedrivenCandidates must be between 0 and the candidate count");
|
||||
}
|
||||
if (topologyVersion == null || topologyVersion.isBlank()) {
|
||||
throw new IllegalArgumentException("topologyVersion must not be blank");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The fingerprint an approver's signature is bound to.
|
||||
*
|
||||
* <p>Source, target, batch size, and both candidate counts are in it, so an approval for a
|
||||
* redrive of one dead-letter destination cannot be presented for a redrive of another.
|
||||
*
|
||||
* @return the digest of this exact plan
|
||||
*/
|
||||
public PlanDigest digest() {
|
||||
return PlanDigest.ofCanonical(
|
||||
String.join(
|
||||
"|",
|
||||
"REDRIVE",
|
||||
request.redriveId().toString(),
|
||||
request.source().value(),
|
||||
request.target().value(),
|
||||
Integer.toString(request.batchSize()),
|
||||
Integer.toString(candidates),
|
||||
Integer.toString(alreadyRedrivenCandidates),
|
||||
topologyVersion));
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether this redrive would replay messages that already failed a redrive.
|
||||
*
|
||||
* @return true when any candidate has been redriven before
|
||||
*/
|
||||
public boolean risksALoop() {
|
||||
return alreadyRedrivenCandidates > 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a one-line operator-facing summary of the impact.
|
||||
*
|
||||
* @return the sanitized summary
|
||||
*/
|
||||
public String describeImpact() {
|
||||
String loop =
|
||||
risksALoop()
|
||||
? ", %d of which already failed a previous redrive".formatted(alreadyRedrivenCandidates)
|
||||
: "";
|
||||
return "redrive %d messages from %s to %s%s"
|
||||
.formatted(candidates, request.source().value(), request.target().value(), loop);
|
||||
}
|
||||
}
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||
import java.util.Objects;
|
||||
import java.util.UUID;
|
||||
|
||||
/**
|
||||
* A request to move messages from a dead letter destination back to their source.
|
||||
*
|
||||
* <p>The redrive id is a separate identifier from the message id, and both travel with the message.
|
||||
* Reusing the message id as the operation id would make "this message was redriven" and "this
|
||||
* message is a different message" indistinguishable, and an operator could not tell a redrive loop
|
||||
* from ordinary traffic.
|
||||
*
|
||||
* @param redriveId the operation identity
|
||||
* @param source the dead letter destination to drain
|
||||
* @param target the destination to publish back to
|
||||
* @param batchSize how many messages to move per pass
|
||||
* @param dryRun whether to plan without moving anything
|
||||
*/
|
||||
public record RedriveRequest(
|
||||
UUID redriveId, DestinationName source, DestinationName target, int batchSize, boolean dryRun) {
|
||||
|
||||
private static final int MAX_BATCH = 100;
|
||||
|
||||
public RedriveRequest {
|
||||
Objects.requireNonNull(redriveId, "redriveId must not be null");
|
||||
Objects.requireNonNull(source, "source must not be null");
|
||||
Objects.requireNonNull(target, "target must not be null");
|
||||
if (source.equals(target)) {
|
||||
throw new IllegalArgumentException("a redrive cannot target its own source");
|
||||
}
|
||||
if (batchSize < 1 || batchSize > MAX_BATCH) {
|
||||
throw new IllegalArgumentException("redrive batch size must be between 1 and " + MAX_BATCH);
|
||||
}
|
||||
}
|
||||
}
|
||||
+51
@@ -0,0 +1,51 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import java.time.Duration;
|
||||
import java.util.Objects;
|
||||
import java.util.UUID;
|
||||
|
||||
/**
|
||||
* What a redrive actually did.
|
||||
*
|
||||
* <p>{@code stillParked} is not simply {@code candidates - moved}. A message stays parked when its
|
||||
* republish did not confirm, and the redrive deliberately leaves it there rather than settling it —
|
||||
* the DLQ-confirm-before-settle rule applies to a redrive exactly as it does to the original
|
||||
* dead-lettering, because a redrive that settles an unconfirmed republish deletes the last copy.
|
||||
*
|
||||
* @param redriveId the operation identity
|
||||
* @param candidates how many messages were eligible
|
||||
* @param moved how many were republished and settled
|
||||
* @param stillParked how many stayed on the dead letter destination
|
||||
* @param elapsed how long the redrive took
|
||||
* @param dryRun whether nothing was actually moved
|
||||
*/
|
||||
public record RedriveResult(
|
||||
UUID redriveId, int candidates, int moved, int stillParked, Duration elapsed, boolean dryRun) {
|
||||
|
||||
public RedriveResult {
|
||||
Objects.requireNonNull(redriveId, "redriveId must not be null");
|
||||
Objects.requireNonNull(elapsed, "elapsed must not be null");
|
||||
if (candidates < 0 || moved < 0 || stillParked < 0) {
|
||||
throw new IllegalArgumentException("redrive counters must not be negative");
|
||||
}
|
||||
if (moved + stillParked > candidates) {
|
||||
throw new IllegalArgumentException(
|
||||
"a redrive cannot account for more messages than it had candidates");
|
||||
}
|
||||
if (dryRun && moved > 0) {
|
||||
throw new IllegalArgumentException("a dry run must not move anything");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether every candidate was accounted for.
|
||||
*
|
||||
* <p>An unaccounted message is a bug, not a partial success: it was neither republished nor left
|
||||
* parked, which means the redrive lost track of it.
|
||||
*
|
||||
* @return true when moved plus still-parked covers every candidate
|
||||
*/
|
||||
public boolean isFullyAccounted() {
|
||||
return moved + stillParked == candidates;
|
||||
}
|
||||
}
|
||||
+79
@@ -0,0 +1,79 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* What a replay would do, produced before anything is read.
|
||||
*
|
||||
* <p>The plan exists so the estimate can be reviewed. "Replay from yesterday" is a sentence; "this
|
||||
* will re-deliver 4.2 million messages into the live consumer group" is a decision, and the only
|
||||
* moment an operator can make it is before the replay starts.
|
||||
*
|
||||
* <p>{@code topologyVersion} is captured here and re-checked at execution. A plan approved against
|
||||
* one topology and executed against another is estimating a different thing entirely — a partition
|
||||
* count that changed in between invalidates every number in this record.
|
||||
*
|
||||
* @param request the request this plan was built from
|
||||
* @param estimatedMessages how many messages the window covers
|
||||
* @param plannedAt when the plan was produced
|
||||
* @param topologyVersion the topology the estimate was computed against
|
||||
* @param targetsLiveConsumerGroup whether the replay would feed the live group rather than an
|
||||
* isolated one
|
||||
*/
|
||||
public record ReplayPlan(
|
||||
ReplayRequest request,
|
||||
long estimatedMessages,
|
||||
Instant plannedAt,
|
||||
String topologyVersion,
|
||||
boolean targetsLiveConsumerGroup) {
|
||||
|
||||
public ReplayPlan {
|
||||
Objects.requireNonNull(request, "request must not be null");
|
||||
Objects.requireNonNull(plannedAt, "plannedAt must not be null");
|
||||
if (estimatedMessages < 0) {
|
||||
throw new IllegalArgumentException("estimatedMessages must not be negative");
|
||||
}
|
||||
if (topologyVersion == null || topologyVersion.isBlank()) {
|
||||
throw new IllegalArgumentException("topologyVersion must not be blank");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The fingerprint an approver's signature is bound to.
|
||||
*
|
||||
* <p>Every field that changes what would happen is in it. An approval signed over this digest
|
||||
* cannot be presented for a plan that reads a different destination, targets a different consumer
|
||||
* group, starts from a different position, or estimates a different impact.
|
||||
*
|
||||
* @return the digest of this exact plan
|
||||
*/
|
||||
public PlanDigest digest() {
|
||||
return PlanDigest.ofCanonical(
|
||||
String.join(
|
||||
"|",
|
||||
"REPLAY",
|
||||
request.replayId().toString(),
|
||||
request.destination().value(),
|
||||
Boolean.toString(request.isolatedConsumerGroup()),
|
||||
request.from().toString(),
|
||||
request.to().map(Object::toString).orElse(""),
|
||||
Long.toString(estimatedMessages),
|
||||
topologyVersion,
|
||||
Boolean.toString(targetsLiveConsumerGroup)));
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a one-line operator-facing summary of the impact.
|
||||
*
|
||||
* @return the sanitized summary
|
||||
*/
|
||||
public String describeImpact() {
|
||||
return "replay %s from %s: about %d messages into %s"
|
||||
.formatted(
|
||||
request.destination().value(),
|
||||
request.from(),
|
||||
estimatedMessages,
|
||||
targetsLiveConsumerGroup ? "the LIVE consumer group" : "an isolated group");
|
||||
}
|
||||
}
|
||||
+36
@@ -0,0 +1,36 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
import java.util.UUID;
|
||||
|
||||
/**
|
||||
* A request to re-read a destination from an earlier position.
|
||||
*
|
||||
* @param replayId the operation identity
|
||||
* @param destination the destination to replay
|
||||
* @param from the replay start point
|
||||
* @param to the replay end point, when bounded
|
||||
* @param isolatedConsumerGroup whether to replay into a throwaway group
|
||||
* @param dryRun whether to plan without reading anything
|
||||
*/
|
||||
public record ReplayRequest(
|
||||
UUID replayId,
|
||||
DestinationName destination,
|
||||
Instant from,
|
||||
Optional<Instant> to,
|
||||
boolean isolatedConsumerGroup,
|
||||
boolean dryRun) {
|
||||
|
||||
public ReplayRequest {
|
||||
Objects.requireNonNull(replayId, "replayId must not be null");
|
||||
Objects.requireNonNull(destination, "destination must not be null");
|
||||
Objects.requireNonNull(from, "from must not be null");
|
||||
Objects.requireNonNull(to, "to must not be null");
|
||||
if (to.filter(end -> end.isBefore(from)).isPresent()) {
|
||||
throw new IllegalArgumentException("replay window ends before it starts");
|
||||
}
|
||||
}
|
||||
}
|
||||
+49
@@ -0,0 +1,49 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import java.time.Duration;
|
||||
import java.util.Objects;
|
||||
import java.util.UUID;
|
||||
|
||||
/**
|
||||
* What a replay actually did.
|
||||
*
|
||||
* <p>Reports the delivered count against the plan's estimate. They routinely differ — retention may
|
||||
* have expired part of the window, or the stream may have grown while the plan was being approved —
|
||||
* and the difference is the operator's signal that the replay covered something other than what was
|
||||
* approved.
|
||||
*
|
||||
* @param replayId the operation identity
|
||||
* @param estimatedMessages what the plan predicted
|
||||
* @param deliveredMessages what was actually re-delivered
|
||||
* @param elapsed how long the replay took
|
||||
* @param completed whether the whole window was covered
|
||||
* @param dryRun whether nothing was actually read
|
||||
*/
|
||||
public record ReplayResult(
|
||||
UUID replayId,
|
||||
long estimatedMessages,
|
||||
long deliveredMessages,
|
||||
Duration elapsed,
|
||||
boolean completed,
|
||||
boolean dryRun) {
|
||||
|
||||
public ReplayResult {
|
||||
Objects.requireNonNull(replayId, "replayId must not be null");
|
||||
Objects.requireNonNull(elapsed, "elapsed must not be null");
|
||||
if (estimatedMessages < 0 || deliveredMessages < 0) {
|
||||
throw new IllegalArgumentException("replay counters must not be negative");
|
||||
}
|
||||
if (dryRun && deliveredMessages > 0) {
|
||||
throw new IllegalArgumentException("a dry run must not deliver anything");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether the replay covered materially less than was approved.
|
||||
*
|
||||
* @return true when fewer than 90% of the estimated messages were delivered
|
||||
*/
|
||||
public boolean fellShortOfTheEstimate() {
|
||||
return completed && estimatedMessages > 0 && deliveredMessages * 10 < estimatedMessages * 9;
|
||||
}
|
||||
}
|
||||
+82
@@ -0,0 +1,82 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* One discrepancy between a declared topology and what the broker actually has.
|
||||
*
|
||||
* <p>Severity is part of the finding because the two kinds behave differently at startup. A {@link
|
||||
* Severity#BLOCKING} issue means the destination cannot deliver its declared guarantee —
|
||||
* replication factor 1 on a destination promising durability is not a warning, it is a promise the
|
||||
* platform cannot keep — so the context refuses to start. A {@link Severity#ADVISORY} issue is a
|
||||
* drift worth reporting that does not break a guarantee.
|
||||
*
|
||||
* @param destination the logical destination
|
||||
* @param attribute the topology attribute that differs
|
||||
* @param declared what the manifest declared
|
||||
* @param actual what the broker reported
|
||||
* @param severity how the platform should react
|
||||
*/
|
||||
public record TopologyIssue(
|
||||
String destination, String attribute, String declared, String actual, Severity severity) {
|
||||
|
||||
/** How the platform reacts to a topology discrepancy. */
|
||||
public enum Severity {
|
||||
/** The destination cannot deliver a declared guarantee; startup must fail. */
|
||||
BLOCKING,
|
||||
/** Drift worth reporting that does not break a guarantee. */
|
||||
ADVISORY
|
||||
}
|
||||
|
||||
public TopologyIssue {
|
||||
Objects.requireNonNull(severity, "severity must not be null");
|
||||
requireText(destination, "destination");
|
||||
requireText(attribute, "attribute");
|
||||
requireText(declared, "declared");
|
||||
requireText(actual, "actual");
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a blocking issue.
|
||||
*
|
||||
* @param destination the logical destination
|
||||
* @param attribute the differing attribute
|
||||
* @param declared the declared value
|
||||
* @param actual the observed value
|
||||
* @return the issue
|
||||
*/
|
||||
public static TopologyIssue blocking(
|
||||
String destination, String attribute, String declared, String actual) {
|
||||
return new TopologyIssue(destination, attribute, declared, actual, Severity.BLOCKING);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates an advisory issue.
|
||||
*
|
||||
* @param destination the logical destination
|
||||
* @param attribute the differing attribute
|
||||
* @param declared the declared value
|
||||
* @param actual the observed value
|
||||
* @return the issue
|
||||
*/
|
||||
public static TopologyIssue advisory(
|
||||
String destination, String attribute, String declared, String actual) {
|
||||
return new TopologyIssue(destination, attribute, declared, actual, Severity.ADVISORY);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a one-line operator-facing description.
|
||||
*
|
||||
* @return the sanitized description
|
||||
*/
|
||||
public String describe() {
|
||||
return "%s: %s declared %s but the broker has %s"
|
||||
.formatted(destination, attribute, declared, actual);
|
||||
}
|
||||
|
||||
private static void requireText(String value, String field) {
|
||||
if (value == null || value.isBlank()) {
|
||||
throw new IllegalArgumentException(field + " must not be blank");
|
||||
}
|
||||
}
|
||||
}
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
|
||||
|
||||
/**
|
||||
* Whether the application may create broker topology, or only check it.
|
||||
*
|
||||
* <p>{@link #VALIDATE_ONLY} in production, always. An application that auto-creates topology will
|
||||
* auto-create it after a configuration typo too, and the topic it makes is indistinguishable from a
|
||||
* real one — same broker, same client, same metrics — while carrying the broker's default partition
|
||||
* count and replication factor instead of the ones the destination needs. The failure surfaces
|
||||
* weeks later as data loss on a partition that was never replicated.
|
||||
*/
|
||||
public enum TopologyManagementMode {
|
||||
|
||||
/** Compare the declared topology against the broker and fail on a mismatch. */
|
||||
VALIDATE_ONLY,
|
||||
|
||||
/** Create missing topology. Permitted outside production only. */
|
||||
CREATE_IF_MISSING;
|
||||
|
||||
/**
|
||||
* Refuses auto-creation on a production runtime.
|
||||
*
|
||||
* @param production whether this runtime is production
|
||||
* @throws MessagingConfigurationException when auto-creation is configured in production
|
||||
*/
|
||||
public void requireSafeFor(boolean production) {
|
||||
if (production && this == CREATE_IF_MISSING) {
|
||||
throw new MessagingConfigurationException(
|
||||
"AUTO_CREATE_IN_PRODUCTION",
|
||||
"topology auto-creation is not permitted in production: a mistyped destination would be "
|
||||
+ "created with the broker's default partition count and replication factor, and "
|
||||
+ "would look exactly like a correctly provisioned one");
|
||||
}
|
||||
}
|
||||
}
|
||||
+76
@@ -0,0 +1,76 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* The declared shape of a destination's broker topology.
|
||||
*
|
||||
* <p>Production topology is created by infrastructure code and only <em>validated</em> by the
|
||||
* application. An application that creates topology on startup will happily create it in the wrong
|
||||
* place after a configuration mistake, and the resulting topic looks exactly like a real one.
|
||||
*
|
||||
* @param destination the logical destination
|
||||
* @param physicalName the broker-side name
|
||||
* @param partitions the expected partition count, where the broker has partitions
|
||||
* @param replicationFactor the expected replication factor
|
||||
* @param requiredConfiguration configuration entries that must match exactly
|
||||
*/
|
||||
public record TopologyManifest(
|
||||
String destination,
|
||||
String physicalName,
|
||||
int partitions,
|
||||
int replicationFactor,
|
||||
Map<String, String> requiredConfiguration) {
|
||||
|
||||
public TopologyManifest {
|
||||
Objects.requireNonNull(requiredConfiguration, "requiredConfiguration must not be null");
|
||||
if (destination == null || destination.isBlank()) {
|
||||
throw new IllegalArgumentException("destination must not be blank");
|
||||
}
|
||||
if (physicalName == null || physicalName.isBlank()) {
|
||||
throw new IllegalArgumentException("physicalName must not be blank");
|
||||
}
|
||||
if (partitions < 1) {
|
||||
throw new IllegalArgumentException("partitions must be at least 1");
|
||||
}
|
||||
if (replicationFactor < 1) {
|
||||
throw new IllegalArgumentException("replicationFactor must be at least 1");
|
||||
}
|
||||
requiredConfiguration = Map.copyOf(requiredConfiguration);
|
||||
}
|
||||
|
||||
/**
|
||||
* Compares this manifest against what the broker actually reports.
|
||||
*
|
||||
* @param actualPartitions the observed partition count
|
||||
* @param actualReplicationFactor the observed replication factor
|
||||
* @param actualConfiguration the observed configuration
|
||||
* @return the differences, empty when the topology matches
|
||||
*/
|
||||
public List<String> differencesFrom(
|
||||
int actualPartitions, int actualReplicationFactor, Map<String, String> actualConfiguration) {
|
||||
Objects.requireNonNull(actualConfiguration, "actualConfiguration must not be null");
|
||||
List<String> differences = new java.util.ArrayList<>();
|
||||
|
||||
if (actualPartitions != partitions) {
|
||||
differences.add("partitions expected " + partitions + " but found " + actualPartitions);
|
||||
}
|
||||
if (actualReplicationFactor != replicationFactor) {
|
||||
differences.add(
|
||||
"replicationFactor expected "
|
||||
+ replicationFactor
|
||||
+ " but found "
|
||||
+ actualReplicationFactor);
|
||||
}
|
||||
requiredConfiguration.forEach(
|
||||
(key, expected) -> {
|
||||
String actual = actualConfiguration.get(key);
|
||||
if (!expected.equals(actual)) {
|
||||
differences.add(key + " expected " + expected + " but found " + actual);
|
||||
}
|
||||
});
|
||||
return List.copyOf(differences);
|
||||
}
|
||||
}
|
||||
+83
@@ -0,0 +1,83 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
|
||||
import java.util.List;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* The outcome of comparing every declared topology against the broker.
|
||||
*
|
||||
* <p>Reports both severities together rather than failing on the first blocking issue. An operator
|
||||
* fixing a topology wants the whole list — fixing one attribute, redeploying, and discovering the
|
||||
* next one is how a ten-minute fix becomes an afternoon.
|
||||
*
|
||||
* @param issues every discrepancy found
|
||||
* @param destinationsChecked how many destinations were compared
|
||||
*/
|
||||
public record TopologyValidationReport(List<TopologyIssue> issues, int destinationsChecked) {
|
||||
|
||||
public TopologyValidationReport {
|
||||
Objects.requireNonNull(issues, "issues must not be null");
|
||||
if (destinationsChecked < 0) {
|
||||
throw new IllegalArgumentException("destinationsChecked must not be negative");
|
||||
}
|
||||
issues = List.copyOf(issues);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a report with nothing to fix.
|
||||
*
|
||||
* @param destinationsChecked how many destinations were compared
|
||||
* @return the clean report
|
||||
*/
|
||||
public static TopologyValidationReport clean(int destinationsChecked) {
|
||||
return new TopologyValidationReport(List.of(), destinationsChecked);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the issues that must fail startup.
|
||||
*
|
||||
* @return the blocking issues
|
||||
*/
|
||||
public List<TopologyIssue> blocking() {
|
||||
return issues.stream()
|
||||
.filter(issue -> issue.severity() == TopologyIssue.Severity.BLOCKING)
|
||||
.toList();
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the issues worth reporting that do not break a guarantee.
|
||||
*
|
||||
* @return the advisory issues
|
||||
*/
|
||||
public List<TopologyIssue> advisory() {
|
||||
return issues.stream()
|
||||
.filter(issue -> issue.severity() == TopologyIssue.Severity.ADVISORY)
|
||||
.toList();
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether the topology may be used.
|
||||
*
|
||||
* @return true when nothing blocking was found
|
||||
*/
|
||||
public boolean isAcceptable() {
|
||||
return blocking().isEmpty();
|
||||
}
|
||||
|
||||
/**
|
||||
* Fails startup when any blocking issue was found.
|
||||
*
|
||||
* @throws MessagingConfigurationException listing every blocking issue
|
||||
*/
|
||||
public void requireAcceptable() {
|
||||
List<TopologyIssue> blocking = blocking();
|
||||
if (blocking.isEmpty()) {
|
||||
return;
|
||||
}
|
||||
throw new MessagingConfigurationException(
|
||||
"TOPOLOGY_MISMATCH",
|
||||
"the broker topology cannot deliver the declared guarantees: "
|
||||
+ String.join("; ", blocking.stream().map(TopologyIssue::describe).toList()));
|
||||
}
|
||||
}
|
||||
+88
@@ -0,0 +1,88 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* A grant that an {@link ApprovalVerifier} has checked, and that nobody else can manufacture.
|
||||
*
|
||||
* <p>The approved-plan types used to hold a plain {@code AdminApproval} record with a public
|
||||
* constructor, so "this plan was approved" was a claim the caller made about itself. Any code that
|
||||
* could reach the execute method could write {@code new AdminApproval("TICKET-1", "someone", now,
|
||||
* later)} and the platform believed it.
|
||||
*
|
||||
* <p>This class has no public constructor and no public factory. The only way to obtain one is to
|
||||
* present a grant and a signature to a verifier, which is exactly the property the type is for:
|
||||
* holding a {@code VerifiedApproval} is itself the evidence that verification happened.
|
||||
*/
|
||||
public final class VerifiedApproval {
|
||||
|
||||
private final ApprovalGrant grant;
|
||||
|
||||
private VerifiedApproval(ApprovalGrant grant) {
|
||||
this.grant = Objects.requireNonNull(grant, "grant must not be null");
|
||||
}
|
||||
|
||||
/**
|
||||
* Mints a verified approval. Package-private on purpose: only a verifier in this package may call
|
||||
* it, so the type cannot be forged from application or adapter code.
|
||||
*/
|
||||
static VerifiedApproval of(ApprovalGrant grant) {
|
||||
return new VerifiedApproval(grant);
|
||||
}
|
||||
|
||||
/**
|
||||
* The grant that was verified.
|
||||
*
|
||||
* @return the grant
|
||||
*/
|
||||
public ApprovalGrant grant() {
|
||||
return grant;
|
||||
}
|
||||
|
||||
/**
|
||||
* The approval ticket, for audit records and journal keys.
|
||||
*
|
||||
* @return the ticket
|
||||
*/
|
||||
public String ticket() {
|
||||
return grant.approval().ticket();
|
||||
}
|
||||
|
||||
/**
|
||||
* Who approved the operation.
|
||||
*
|
||||
* @return the approver identity
|
||||
*/
|
||||
public String approvedBy() {
|
||||
return grant.approval().approvedBy();
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether the approval window is still open.
|
||||
*
|
||||
* @param now the current instant
|
||||
* @return true while inside the window
|
||||
*/
|
||||
public boolean isValidAt(Instant now) {
|
||||
return grant.isValidAt(now);
|
||||
}
|
||||
|
||||
@Override
|
||||
public boolean equals(Object other) {
|
||||
return other instanceof VerifiedApproval verified && grant.equals(verified.grant);
|
||||
}
|
||||
|
||||
@Override
|
||||
public int hashCode() {
|
||||
return grant.hashCode();
|
||||
}
|
||||
|
||||
@Override
|
||||
public String toString() {
|
||||
// Deliberately not the whole grant: this string reaches logs, and the plan digest plus the
|
||||
// ticket identify the operation without restating who approved what to an audience that has
|
||||
// not been authorised to read it.
|
||||
return "VerifiedApproval[" + ticket() + " " + grant.planDigest().value().substring(0, 12) + "]";
|
||||
}
|
||||
}
|
||||
+33
@@ -0,0 +1,33 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import dev.caskeleton.messaging.admin.DestinationTopology;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Reads the broker's current topology.
|
||||
*
|
||||
* <p>Read-only by construction. The inspector is what the application's own credential uses, and
|
||||
* that credential holds no destructive grant, so the type exposes no way to create, alter, or
|
||||
* delete — an application cannot reach a destructive operation even by mistake because there is no
|
||||
* method to reach.
|
||||
*/
|
||||
public interface BrokerTopologyInspector {
|
||||
|
||||
/**
|
||||
* Describes one destination.
|
||||
*
|
||||
* @param physicalName the broker-side name
|
||||
* @return the observed topology, absent when the broker has no such destination
|
||||
*/
|
||||
Optional<DestinationTopology> describe(String physicalName);
|
||||
|
||||
/**
|
||||
* Returns an opaque version for the broker's current topology.
|
||||
*
|
||||
* <p>Used to invalidate an approved plan whose impact estimate was computed against an earlier
|
||||
* shape. Any value that changes when the topology changes is sufficient; it is never parsed.
|
||||
*
|
||||
* @return the topology version
|
||||
*/
|
||||
String topologyVersion();
|
||||
}
|
||||
+52
@@ -0,0 +1,52 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import dev.caskeleton.messaging.admin.DestinationTopology;
|
||||
import dev.caskeleton.messaging.admin.TopologyIssue;
|
||||
import dev.caskeleton.messaging.admin.TopologyManifest;
|
||||
import dev.caskeleton.messaging.admin.TopologyValidationReport;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Validates every declared topology in one pass and reports the whole result.
|
||||
*
|
||||
* <p>Collects all issues rather than stopping at the first blocking one. An operator fixing a
|
||||
* topology mismatch wants the complete list — discovering the next problem only after a redeploy
|
||||
* turns one fix into a sequence of them, and each redeploy is another restart of a production
|
||||
* service.
|
||||
*/
|
||||
public final class CompositeTopologyValidator {
|
||||
|
||||
private final BrokerTopologyInspector inspector;
|
||||
private final TopologyValidator validator = new TopologyValidator();
|
||||
|
||||
/**
|
||||
* Creates a validator over a broker inspector.
|
||||
*
|
||||
* @param inspector reads the broker's current topology
|
||||
*/
|
||||
public CompositeTopologyValidator(BrokerTopologyInspector inspector) {
|
||||
this.inspector = Objects.requireNonNull(inspector, "inspector must not be null");
|
||||
}
|
||||
|
||||
/**
|
||||
* Compares every manifest against the broker.
|
||||
*
|
||||
* @param manifests the declared topologies
|
||||
* @return the complete report
|
||||
*/
|
||||
public TopologyValidationReport validate(List<TopologyManifest> manifests) {
|
||||
Objects.requireNonNull(manifests, "manifests must not be null");
|
||||
|
||||
List<TopologyIssue> issues = new ArrayList<>();
|
||||
for (TopologyManifest manifest : manifests) {
|
||||
DestinationTopology observed =
|
||||
inspector
|
||||
.describe(manifest.physicalName())
|
||||
.orElseGet(() -> DestinationTopology.absent(manifest.physicalName()));
|
||||
issues.addAll(validator.compare(manifest, observed));
|
||||
}
|
||||
return new TopologyValidationReport(issues, manifests.size());
|
||||
}
|
||||
}
|
||||
+257
@@ -0,0 +1,257 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import dev.caskeleton.messaging.admin.AdminOperationJournal;
|
||||
import dev.caskeleton.messaging.admin.AdminOperationLease;
|
||||
import dev.caskeleton.messaging.admin.ApprovedRedrivePlan;
|
||||
import dev.caskeleton.messaging.admin.ApprovedReplayPlan;
|
||||
import dev.caskeleton.messaging.admin.RedrivePlan;
|
||||
import dev.caskeleton.messaging.admin.RedriveRequest;
|
||||
import dev.caskeleton.messaging.admin.RedriveResult;
|
||||
import dev.caskeleton.messaging.admin.ReplayPlan;
|
||||
import dev.caskeleton.messaging.admin.ReplayRequest;
|
||||
import dev.caskeleton.messaging.admin.ReplayResult;
|
||||
import dev.caskeleton.messaging.admin.TopologyManifest;
|
||||
import dev.caskeleton.messaging.admin.TopologyValidationReport;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.util.List;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
import java.util.function.Supplier;
|
||||
|
||||
/**
|
||||
* Wires plan, approval, and execution together for the non-destructive admin operations.
|
||||
*
|
||||
* <p>Execution runs four checks, in this order, and the order is the point.
|
||||
*
|
||||
* <ol>
|
||||
* <li>The approval is still inside its window.
|
||||
* <li>The topology has not changed since the plan was approved.
|
||||
* <li>The approval has not already been executed.
|
||||
* <li>Only then does anything move.
|
||||
* </ol>
|
||||
*
|
||||
* <p>The journal entry is written <em>before</em> the work rather than after it. Writing it
|
||||
* afterwards leaves a window where a second execution starts while the first is still running,
|
||||
* which is precisely the double-redrive the journal exists to prevent.
|
||||
*
|
||||
* <p>Writing it first used to have a cost the previous store never paid: an operation that died
|
||||
* halfway had consumed its approval and left no record of how far it got. The journal keeps a
|
||||
* checkpoint and hands back a lease that says where to resume, so a retry continues the same
|
||||
* operation instead of either redoing it or requiring a new approval.
|
||||
*/
|
||||
public final class DefaultMessagingAdminService implements MessagingAdminService {
|
||||
|
||||
/**
|
||||
* How long a runtime holds an operation before another may take it over.
|
||||
*
|
||||
* <p>Long enough that a slow batch does not lose its lease mid-flight, short enough that a dead
|
||||
* replica does not park an approval for an hour.
|
||||
*/
|
||||
private static final Duration LEASE_DURATION = Duration.ofMinutes(5);
|
||||
|
||||
private final CompositeTopologyValidator topologyValidator;
|
||||
private final BrokerTopologyInspector inspector;
|
||||
private final AdminOperationJournal journal;
|
||||
private final String leaseOwner;
|
||||
private final ReplayService replayService;
|
||||
private final RedriveService redriveService;
|
||||
private final Supplier<List<TopologyManifest>> manifests;
|
||||
private final ReplayEstimator replayEstimator;
|
||||
private final RedriveEstimator redriveEstimator;
|
||||
private final Supplier<Instant> clock;
|
||||
|
||||
/**
|
||||
* Creates the admin service.
|
||||
*
|
||||
* @param topologyValidator compares declared topology against the broker
|
||||
* @param inspector reads the broker's topology version
|
||||
* @param journal records which approvals have been executed, and how far each got
|
||||
* @param leaseOwner identifies this runtime in the journal's leases
|
||||
* @param replayService performs replays
|
||||
* @param redriveService performs redrives
|
||||
* @param manifests supplies the declared topologies
|
||||
* @param replayEstimator estimates a replay's message count
|
||||
* @param redriveEstimator estimates a redrive's candidates
|
||||
* @param clock supplies the current instant
|
||||
*/
|
||||
public DefaultMessagingAdminService(
|
||||
CompositeTopologyValidator topologyValidator,
|
||||
BrokerTopologyInspector inspector,
|
||||
AdminOperationJournal journal,
|
||||
String leaseOwner,
|
||||
ReplayService replayService,
|
||||
RedriveService redriveService,
|
||||
Supplier<List<TopologyManifest>> manifests,
|
||||
ReplayEstimator replayEstimator,
|
||||
RedriveEstimator redriveEstimator,
|
||||
Supplier<Instant> clock) {
|
||||
this.topologyValidator =
|
||||
Objects.requireNonNull(topologyValidator, "topologyValidator required");
|
||||
this.inspector = Objects.requireNonNull(inspector, "inspector must not be null");
|
||||
this.journal = Objects.requireNonNull(journal, "journal must not be null");
|
||||
if (leaseOwner == null || leaseOwner.isBlank()) {
|
||||
throw new IllegalArgumentException("leaseOwner must not be blank");
|
||||
}
|
||||
this.leaseOwner = leaseOwner;
|
||||
this.replayService = Objects.requireNonNull(replayService, "replayService must not be null");
|
||||
this.redriveService = Objects.requireNonNull(redriveService, "redriveService must not be null");
|
||||
this.manifests = Objects.requireNonNull(manifests, "manifests must not be null");
|
||||
this.replayEstimator = Objects.requireNonNull(replayEstimator, "replayEstimator required");
|
||||
this.redriveEstimator = Objects.requireNonNull(redriveEstimator, "redriveEstimator required");
|
||||
this.clock = Objects.requireNonNull(clock, "clock must not be null");
|
||||
}
|
||||
|
||||
@Override
|
||||
public TopologyValidationReport validateTopology() {
|
||||
return topologyValidator.validate(manifests.get());
|
||||
}
|
||||
|
||||
@Override
|
||||
public ReplayPlan planReplay(ReplayRequest request) {
|
||||
Objects.requireNonNull(request, "request must not be null");
|
||||
return new ReplayPlan(
|
||||
request,
|
||||
replayEstimator.estimate(request),
|
||||
clock.get(),
|
||||
inspector.topologyVersion(),
|
||||
!request.isolatedConsumerGroup());
|
||||
}
|
||||
|
||||
@Override
|
||||
public ReplayResult executeReplay(ApprovedReplayPlan plan) {
|
||||
Objects.requireNonNull(plan, "plan must not be null");
|
||||
Instant now = clock.get();
|
||||
ReplayRequest request = plan.plan().request();
|
||||
|
||||
plan.requireExecutable(now, inspector.topologyVersion());
|
||||
AdminOperationLease lease =
|
||||
journal.begin(
|
||||
plan.approval().ticket(),
|
||||
plan.plan().digest(),
|
||||
request.replayId().toString(),
|
||||
leaseOwner,
|
||||
LEASE_DURATION,
|
||||
now);
|
||||
|
||||
Instant startedAt = clock.get();
|
||||
ReplayReport report;
|
||||
try {
|
||||
report =
|
||||
replayService.replay(
|
||||
request, Optional.of(plan.approval()), plan.approval().approvedBy(), now);
|
||||
} catch (RuntimeException failure) {
|
||||
// The operation stays resumable rather than silently consuming the approval: the journal
|
||||
// entry moves to FAILED at its checkpoint, and a retry takes it over from there.
|
||||
journal.fail(lease, lease.resumeFrom(), failureCodeOf(failure), clock.get());
|
||||
throw failure;
|
||||
}
|
||||
journal.complete(lease, Math.toIntExact(report.replayed()), clock.get());
|
||||
|
||||
return new ReplayResult(
|
||||
request.replayId(),
|
||||
plan.plan().estimatedMessages(),
|
||||
report.replayed(),
|
||||
Duration.between(startedAt, clock.get()),
|
||||
true,
|
||||
report.dryRun());
|
||||
}
|
||||
|
||||
@Override
|
||||
public RedrivePlan planRedrive(RedriveRequest request) {
|
||||
Objects.requireNonNull(request, "request must not be null");
|
||||
RedriveEstimate estimate = redriveEstimator.estimate(request);
|
||||
return new RedrivePlan(
|
||||
request,
|
||||
estimate.candidates(),
|
||||
estimate.alreadyRedriven(),
|
||||
clock.get(),
|
||||
inspector.topologyVersion());
|
||||
}
|
||||
|
||||
@Override
|
||||
public RedriveResult executeRedrive(ApprovedRedrivePlan plan) {
|
||||
Objects.requireNonNull(plan, "plan must not be null");
|
||||
Instant now = clock.get();
|
||||
RedriveRequest request = plan.plan().request();
|
||||
|
||||
plan.requireExecutable(now, inspector.topologyVersion());
|
||||
AdminOperationLease lease =
|
||||
journal.begin(
|
||||
plan.approval().ticket(),
|
||||
plan.plan().digest(),
|
||||
request.redriveId().toString(),
|
||||
leaseOwner,
|
||||
LEASE_DURATION,
|
||||
now);
|
||||
|
||||
Instant startedAt = clock.get();
|
||||
RedriveReport report;
|
||||
try {
|
||||
report =
|
||||
redriveService.redrive(
|
||||
request,
|
||||
Optional.of(plan.approval()),
|
||||
plan.approval().approvedBy(),
|
||||
now,
|
||||
lease.resumeFrom(),
|
||||
completed -> journal.checkpoint(lease, completed, LEASE_DURATION, clock.get()));
|
||||
} catch (RuntimeException failure) {
|
||||
journal.fail(lease, lease.resumeFrom(), failureCodeOf(failure), clock.get());
|
||||
throw failure;
|
||||
}
|
||||
journal.complete(lease, report.moved() + report.failed(), clock.get());
|
||||
|
||||
return new RedriveResult(
|
||||
request.redriveId(),
|
||||
report.candidates(),
|
||||
report.moved(),
|
||||
report.failed(),
|
||||
Duration.between(startedAt, clock.get()),
|
||||
report.dryRun());
|
||||
}
|
||||
|
||||
/**
|
||||
* Reduces a failure to a bounded, sanitised code for the journal.
|
||||
*
|
||||
* <p>The journal is read by operators during incidents and its contents outlive the process. A
|
||||
* raw exception message can carry a destination, a payload fragment, or a credential from a
|
||||
* driver's own error text, so only the platform's own code or the exception's simple name goes
|
||||
* in.
|
||||
*/
|
||||
private static String failureCodeOf(RuntimeException failure) {
|
||||
if (failure instanceof dev.caskeleton.messaging.api.error.MessagingException messaging) {
|
||||
return messaging.failure().code();
|
||||
}
|
||||
return failure.getClass().getSimpleName();
|
||||
}
|
||||
|
||||
/** Estimates how many messages a replay would re-deliver. */
|
||||
@FunctionalInterface
|
||||
public interface ReplayEstimator {
|
||||
|
||||
/**
|
||||
* Estimates a replay's message count without reading anything.
|
||||
*
|
||||
* @param request the replay request
|
||||
* @return the estimated count
|
||||
*/
|
||||
long estimate(ReplayRequest request);
|
||||
}
|
||||
|
||||
/** How many messages a redrive would move, and how many already failed one. */
|
||||
record RedriveEstimate(int candidates, int alreadyRedriven) {}
|
||||
|
||||
/** Estimates a redrive's candidates. */
|
||||
@FunctionalInterface
|
||||
public interface RedriveEstimator {
|
||||
|
||||
/**
|
||||
* Estimates a redrive's candidates without moving anything.
|
||||
*
|
||||
* @param request the redrive request
|
||||
* @return the estimate
|
||||
*/
|
||||
RedriveEstimate estimate(RedriveRequest request);
|
||||
}
|
||||
}
|
||||
+82
@@ -0,0 +1,82 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import dev.caskeleton.messaging.admin.DestructiveOperation;
|
||||
import dev.caskeleton.messaging.admin.VerifiedApproval;
|
||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* The operations that destroy data an application cannot recreate.
|
||||
*
|
||||
* <p>A separate interface from {@link MessagingAdminService}, and no bean for it is ever registered
|
||||
* in an application runtime. The separation is the control: an application that never receives this
|
||||
* type cannot purge a topic even if every other guard is bypassed, because the method does not
|
||||
* exist on anything it holds.
|
||||
*
|
||||
* <p>Each operation takes an {@link Approved} argument rather than an approval parameter, so the
|
||||
* authorisation cannot be forgotten at a call site — there is no way to call these without one.
|
||||
*/
|
||||
public interface DestructiveMessagingAdmin {
|
||||
|
||||
/** An authorised destructive request. */
|
||||
record Approved(
|
||||
DestructiveOperation operation,
|
||||
DestinationName destination,
|
||||
VerifiedApproval approval,
|
||||
long estimatedMessagesAffected) {
|
||||
|
||||
public Approved {
|
||||
Objects.requireNonNull(operation, "operation must not be null");
|
||||
Objects.requireNonNull(destination, "destination must not be null");
|
||||
Objects.requireNonNull(approval, "approval must not be null");
|
||||
if (estimatedMessagesAffected < 0) {
|
||||
throw new IllegalArgumentException("estimatedMessagesAffected must not be negative");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/** What a destructive operation did. */
|
||||
record DestructiveResult(
|
||||
DestructiveOperation operation,
|
||||
DestinationName destination,
|
||||
long messagesAffected,
|
||||
Duration elapsed,
|
||||
Instant executedAt) {
|
||||
|
||||
public DestructiveResult {
|
||||
Objects.requireNonNull(operation, "operation must not be null");
|
||||
Objects.requireNonNull(destination, "destination must not be null");
|
||||
Objects.requireNonNull(elapsed, "elapsed must not be null");
|
||||
Objects.requireNonNull(executedAt, "executedAt must not be null");
|
||||
if (messagesAffected < 0) {
|
||||
throw new IllegalArgumentException("messagesAffected must not be negative");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Moves a consumer group's committed position.
|
||||
*
|
||||
* @param request the authorised request
|
||||
* @return what the reset did
|
||||
*/
|
||||
DestructiveResult resetOffset(Approved request);
|
||||
|
||||
/**
|
||||
* Discards the messages a destination currently holds.
|
||||
*
|
||||
* @param request the authorised request
|
||||
* @return what the purge did
|
||||
*/
|
||||
DestructiveResult purge(Approved request);
|
||||
|
||||
/**
|
||||
* Removes a destination entirely.
|
||||
*
|
||||
* @param request the authorised request
|
||||
* @return what the deletion did
|
||||
*/
|
||||
DestructiveResult deleteDestination(Approved request);
|
||||
}
|
||||
+237
@@ -0,0 +1,237 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import dev.caskeleton.messaging.admin.AdminOperationJournal;
|
||||
import dev.caskeleton.messaging.admin.AdminOperationLease;
|
||||
import dev.caskeleton.messaging.admin.AdminOperationRecord;
|
||||
import dev.caskeleton.messaging.admin.AdminOperationState;
|
||||
import dev.caskeleton.messaging.admin.PlanDigest;
|
||||
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
import java.util.concurrent.ConcurrentHashMap;
|
||||
|
||||
/**
|
||||
* A single-process journal, for tests and for local development.
|
||||
*
|
||||
* <p>It reports {@link #isDurable()} as false, and the starter refuses to run a production profile
|
||||
* on a journal that says so. That declaration is the point of this class existing at all: the
|
||||
* previous in-memory store was registered as the production default and nothing distinguished it
|
||||
* from a shared one, so the gap was invisible until two replicas executed the same approval.
|
||||
*
|
||||
* <p>The semantics are otherwise the real ones — uniqueness on {@code (ticket, digest)}, lease
|
||||
* takeover with a monotonic token, resume from checkpoint — so a test that passes here is testing
|
||||
* the protocol rather than a simplification of it.
|
||||
*/
|
||||
public final class InMemoryAdminOperationJournal implements AdminOperationJournal {
|
||||
|
||||
private final Map<String, AdminOperationRecord> records = new ConcurrentHashMap<>();
|
||||
|
||||
@Override
|
||||
public AdminOperationLease begin(
|
||||
String approvalTicket,
|
||||
PlanDigest planDigest,
|
||||
String operationId,
|
||||
String leaseOwner,
|
||||
Duration leaseDuration,
|
||||
Instant now) {
|
||||
Objects.requireNonNull(leaseDuration, "leaseDuration must not be null");
|
||||
Objects.requireNonNull(now, "now must not be null");
|
||||
AdminOperationRecord claimed =
|
||||
records.compute(
|
||||
key(approvalTicket, planDigest),
|
||||
(ignored, existing) ->
|
||||
claim(
|
||||
existing,
|
||||
approvalTicket,
|
||||
planDigest,
|
||||
operationId,
|
||||
leaseOwner,
|
||||
leaseDuration,
|
||||
now));
|
||||
return new AdminOperationLease(
|
||||
approvalTicket,
|
||||
planDigest,
|
||||
claimed.operationId(),
|
||||
claimed.leaseOwner(),
|
||||
claimed.leaseToken(),
|
||||
claimed.itemsCompleted());
|
||||
}
|
||||
|
||||
private static AdminOperationRecord claim(
|
||||
AdminOperationRecord existing,
|
||||
String approvalTicket,
|
||||
PlanDigest planDigest,
|
||||
String operationId,
|
||||
String leaseOwner,
|
||||
Duration leaseDuration,
|
||||
Instant now) {
|
||||
if (existing == null) {
|
||||
return new AdminOperationRecord(
|
||||
approvalTicket,
|
||||
planDigest,
|
||||
operationId,
|
||||
AdminOperationState.STARTED,
|
||||
0,
|
||||
leaseOwner,
|
||||
1L,
|
||||
now.plus(leaseDuration),
|
||||
now,
|
||||
Optional.empty(),
|
||||
Optional.empty());
|
||||
}
|
||||
if (existing.state() == AdminOperationState.COMPLETED) {
|
||||
throw new MessageAuthorizationException(
|
||||
"APPROVAL_ALREADY_EXECUTED",
|
||||
("approval %s was already executed to completion at %s; an approval authorises one"
|
||||
+ " execution, not a standing permission")
|
||||
.formatted(approvalTicket, existing.finishedAt().orElse(existing.startedAt())));
|
||||
}
|
||||
if (existing.state() == AdminOperationState.STARTED
|
||||
&& now.isBefore(existing.leaseExpiresAt())) {
|
||||
throw new MessageAuthorizationException(
|
||||
"ADMIN_OPERATION_IN_FLIGHT",
|
||||
("approval %s is being executed by %s until at least %s; two runtimes executing one"
|
||||
+ " approval is a duplicate storm, not a faster redrive")
|
||||
.formatted(approvalTicket, existing.leaseOwner(), existing.leaseExpiresAt()));
|
||||
}
|
||||
// Either the previous attempt failed, or its lease expired without a completion. Both resume
|
||||
// from the checkpoint under a new token, which fences the previous holder out.
|
||||
return new AdminOperationRecord(
|
||||
approvalTicket,
|
||||
planDigest,
|
||||
operationId,
|
||||
AdminOperationState.STARTED,
|
||||
existing.itemsCompleted(),
|
||||
leaseOwner,
|
||||
existing.leaseToken() + 1,
|
||||
now.plus(leaseDuration),
|
||||
existing.startedAt(),
|
||||
Optional.empty(),
|
||||
Optional.empty());
|
||||
}
|
||||
|
||||
@Override
|
||||
public void checkpoint(
|
||||
AdminOperationLease lease, int itemsCompleted, Duration leaseDuration, Instant now) {
|
||||
update(
|
||||
lease,
|
||||
current ->
|
||||
new AdminOperationRecord(
|
||||
current.approvalTicket(),
|
||||
current.planDigest(),
|
||||
current.operationId(),
|
||||
AdminOperationState.STARTED,
|
||||
Math.max(current.itemsCompleted(), itemsCompleted),
|
||||
current.leaseOwner(),
|
||||
current.leaseToken(),
|
||||
now.plus(leaseDuration),
|
||||
current.startedAt(),
|
||||
Optional.empty(),
|
||||
Optional.empty()));
|
||||
}
|
||||
|
||||
@Override
|
||||
public void complete(AdminOperationLease lease, int itemsCompleted, Instant now) {
|
||||
update(
|
||||
lease,
|
||||
current ->
|
||||
new AdminOperationRecord(
|
||||
current.approvalTicket(),
|
||||
current.planDigest(),
|
||||
current.operationId(),
|
||||
AdminOperationState.COMPLETED,
|
||||
Math.max(current.itemsCompleted(), itemsCompleted),
|
||||
current.leaseOwner(),
|
||||
current.leaseToken(),
|
||||
current.leaseExpiresAt(),
|
||||
current.startedAt(),
|
||||
Optional.of(now),
|
||||
Optional.empty()));
|
||||
}
|
||||
|
||||
@Override
|
||||
public void fail(AdminOperationLease lease, int itemsCompleted, String failureCode, Instant now) {
|
||||
Objects.requireNonNull(failureCode, "failureCode must not be null");
|
||||
update(
|
||||
lease,
|
||||
current ->
|
||||
new AdminOperationRecord(
|
||||
current.approvalTicket(),
|
||||
current.planDigest(),
|
||||
current.operationId(),
|
||||
AdminOperationState.FAILED,
|
||||
Math.max(current.itemsCompleted(), itemsCompleted),
|
||||
current.leaseOwner(),
|
||||
current.leaseToken(),
|
||||
current.leaseExpiresAt(),
|
||||
current.startedAt(),
|
||||
Optional.of(now),
|
||||
Optional.of(failureCode)));
|
||||
}
|
||||
|
||||
@Override
|
||||
public Optional<AdminOperationRecord> find(String approvalTicket, PlanDigest planDigest) {
|
||||
return Optional.ofNullable(records.get(key(approvalTicket, planDigest)));
|
||||
}
|
||||
|
||||
@Override
|
||||
public boolean isDurable() {
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* How many operations have been journalled.
|
||||
*
|
||||
* @return the record count
|
||||
*/
|
||||
public int size() {
|
||||
return records.size();
|
||||
}
|
||||
|
||||
private void update(
|
||||
AdminOperationLease lease, java.util.function.UnaryOperator<AdminOperationRecord> mutation) {
|
||||
Objects.requireNonNull(lease, "lease must not be null");
|
||||
records.compute(
|
||||
key(lease.approvalTicket(), lease.planDigest()),
|
||||
(ignored, current) -> {
|
||||
if (current == null) {
|
||||
throw new MessageAuthorizationException(
|
||||
"ADMIN_OPERATION_NOT_JOURNALLED",
|
||||
"no journal entry exists for approval " + lease.approvalTicket());
|
||||
}
|
||||
if (current.leaseToken() != lease.leaseToken()) {
|
||||
// The fence. A stalled runtime that wakes up and writes here would otherwise overwrite
|
||||
// the progress of whichever replica took the operation over.
|
||||
throw new MessageAuthorizationException(
|
||||
"ADMIN_OPERATION_LEASE_LOST",
|
||||
("the lease on approval %s moved from token %d to token %d; this runtime no longer"
|
||||
+ " owns the operation")
|
||||
.formatted(lease.approvalTicket(), lease.leaseToken(), current.leaseToken()));
|
||||
}
|
||||
return mutation.apply(current);
|
||||
});
|
||||
}
|
||||
|
||||
private static String key(String approvalTicket, PlanDigest planDigest) {
|
||||
Objects.requireNonNull(planDigest, "planDigest must not be null");
|
||||
// Length-prefixed for the same reason the grant's canonical form is: a ticket containing the
|
||||
// separator must not be able to collide with a different ticket and digest pair.
|
||||
return String.join(
|
||||
"", Integer.toString(approvalTicket.length()), ":", approvalTicket, planDigest.value());
|
||||
}
|
||||
|
||||
/**
|
||||
* Every journalled operation, newest first by start time.
|
||||
*
|
||||
* @return the records
|
||||
*/
|
||||
public List<AdminOperationRecord> records() {
|
||||
return records.values().stream()
|
||||
.sorted(java.util.Comparator.comparing(AdminOperationRecord::startedAt).reversed())
|
||||
.toList();
|
||||
}
|
||||
}
|
||||
+65
@@ -0,0 +1,65 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import dev.caskeleton.messaging.admin.ApprovedRedrivePlan;
|
||||
import dev.caskeleton.messaging.admin.ApprovedReplayPlan;
|
||||
import dev.caskeleton.messaging.admin.RedrivePlan;
|
||||
import dev.caskeleton.messaging.admin.RedriveRequest;
|
||||
import dev.caskeleton.messaging.admin.RedriveResult;
|
||||
import dev.caskeleton.messaging.admin.ReplayPlan;
|
||||
import dev.caskeleton.messaging.admin.ReplayRequest;
|
||||
import dev.caskeleton.messaging.admin.ReplayResult;
|
||||
import dev.caskeleton.messaging.admin.TopologyValidationReport;
|
||||
|
||||
/**
|
||||
* The non-destructive half of the admin plane.
|
||||
*
|
||||
* <p>Every mutating operation is split into plan and execute, and the execute methods take an
|
||||
* {@code Approved*} type. A caller cannot execute something it has not planned, because it has no
|
||||
* way to construct the argument — the plan/approve/execute sequence is enforced by the types rather
|
||||
* than by a runtime check.
|
||||
*
|
||||
* <p>Destructive operations live in {@link DestructiveMessagingAdmin}, a separate interface that an
|
||||
* application runtime never receives a bean for. Splitting them means a compromised handler that
|
||||
* somehow reaches this service still has no method that deletes anything.
|
||||
*/
|
||||
public interface MessagingAdminService {
|
||||
|
||||
/**
|
||||
* Compares every declared topology against the broker.
|
||||
*
|
||||
* @return the discrepancies found
|
||||
*/
|
||||
TopologyValidationReport validateTopology();
|
||||
|
||||
/**
|
||||
* Estimates what a replay would do, without reading anything.
|
||||
*
|
||||
* @param request the replay request
|
||||
* @return the plan, including its impact estimate
|
||||
*/
|
||||
ReplayPlan planReplay(ReplayRequest request);
|
||||
|
||||
/**
|
||||
* Executes an approved replay.
|
||||
*
|
||||
* @param plan the approved plan
|
||||
* @return what the replay actually did
|
||||
*/
|
||||
ReplayResult executeReplay(ApprovedReplayPlan plan);
|
||||
|
||||
/**
|
||||
* Estimates what a redrive would do, without moving anything.
|
||||
*
|
||||
* @param request the redrive request
|
||||
* @return the plan, including how many candidates already failed a redrive
|
||||
*/
|
||||
RedrivePlan planRedrive(RedriveRequest request);
|
||||
|
||||
/**
|
||||
* Executes an approved redrive.
|
||||
*
|
||||
* @param plan the approved plan
|
||||
* @return what the redrive actually did
|
||||
*/
|
||||
RedriveResult executeRedrive(ApprovedRedrivePlan plan);
|
||||
}
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
/**
|
||||
* What one redrive pass did.
|
||||
*
|
||||
* @param candidates how many messages were eligible
|
||||
* @param moved how many were republished and settled
|
||||
* @param failed how many did not confirm and stay parked
|
||||
* @param dryRun whether this was a plan-only run
|
||||
*/
|
||||
public record RedriveReport(int candidates, int moved, int failed, boolean dryRun) {
|
||||
|
||||
public RedriveReport {
|
||||
if (candidates < 0 || moved < 0 || failed < 0) {
|
||||
throw new IllegalArgumentException("redrive counters must not be negative");
|
||||
}
|
||||
}
|
||||
}
|
||||
+210
@@ -0,0 +1,210 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import dev.caskeleton.messaging.admin.DestructiveOperation;
|
||||
import dev.caskeleton.messaging.admin.DestructiveOperationGuard;
|
||||
import dev.caskeleton.messaging.admin.RedriveRequest;
|
||||
import dev.caskeleton.messaging.admin.VerifiedApproval;
|
||||
import dev.caskeleton.messaging.api.MessageId;
|
||||
import dev.caskeleton.messaging.api.publish.PublishCompletion;
|
||||
import dev.caskeleton.messaging.api.publish.PublishResult;
|
||||
import java.time.Instant;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Moves messages from a dead letter destination back to their source.
|
||||
*
|
||||
* <p>A redrive is a publish followed by a settlement, in that order, exactly like dead lettering in
|
||||
* reverse. A message whose republish did not confirm stays in the dead letter destination: losing
|
||||
* it on the way back would be the one outcome worse than leaving it parked.
|
||||
*
|
||||
* <p>The redrive id and a redrive counter travel with each message. Without them a message that
|
||||
* fails again is indistinguishable from a new one, and a redrive loop is invisible until the dead
|
||||
* letter destination is full.
|
||||
*/
|
||||
public final class RedriveService {
|
||||
|
||||
private final DestructiveOperationGuard guard;
|
||||
private final RedriveSource source;
|
||||
private final RedrivePublisher publisher;
|
||||
private final AuditSink audit;
|
||||
|
||||
/**
|
||||
* Creates a redrive service.
|
||||
*
|
||||
* @param guard the destructive operation guard
|
||||
* @param source reads and settles dead letter messages
|
||||
* @param publisher republishes to the target destination
|
||||
* @param audit records the operation
|
||||
*/
|
||||
public RedriveService(
|
||||
DestructiveOperationGuard guard,
|
||||
RedriveSource source,
|
||||
RedrivePublisher publisher,
|
||||
AuditSink audit) {
|
||||
this.guard = Objects.requireNonNull(guard, "guard must not be null");
|
||||
this.source = Objects.requireNonNull(source, "source must not be null");
|
||||
this.publisher = Objects.requireNonNull(publisher, "publisher must not be null");
|
||||
this.audit = Objects.requireNonNull(audit, "audit must not be null");
|
||||
}
|
||||
|
||||
/**
|
||||
* Runs one redrive pass.
|
||||
*
|
||||
* @param request what to move
|
||||
* @param approval the verified approval, when one was supplied
|
||||
* @param subject the operator identity
|
||||
* @param now the current instant
|
||||
* @return what the pass did
|
||||
*/
|
||||
public RedriveReport redrive(
|
||||
RedriveRequest request, Optional<VerifiedApproval> approval, String subject, Instant now) {
|
||||
return redrive(request, approval, subject, now, 0, completed -> {});
|
||||
}
|
||||
|
||||
/**
|
||||
* Runs one redrive pass, resuming a previous attempt and reporting progress as it goes.
|
||||
*
|
||||
* <p>Three things were wrong with running this as a plain loop. A synchronous failure from the
|
||||
* publisher — a broker that refuses the connection rather than the message — propagated out of
|
||||
* the loop, so the remaining candidates were never attempted and the audit record was never
|
||||
* written: the operation left no trace of the items it had already moved. A retry then started
|
||||
* from the first candidate and republished them. And nothing bounded how many times one message
|
||||
* could be redriven.
|
||||
*
|
||||
* @param request what to move
|
||||
* @param approval the verified approval, when one was supplied
|
||||
* @param subject the operator identity
|
||||
* @param now the current instant
|
||||
* @param resumeFrom how many candidates a previous attempt durably moved
|
||||
* @param checkpoint called with the running completed count after each item
|
||||
* @return what the pass did
|
||||
*/
|
||||
public RedriveReport redrive(
|
||||
RedriveRequest request,
|
||||
Optional<VerifiedApproval> approval,
|
||||
String subject,
|
||||
Instant now,
|
||||
int resumeFrom,
|
||||
java.util.function.IntConsumer checkpoint) {
|
||||
Objects.requireNonNull(request, "request must not be null");
|
||||
Objects.requireNonNull(checkpoint, "checkpoint must not be null");
|
||||
if (resumeFrom < 0) {
|
||||
throw new IllegalArgumentException("resumeFrom must not be negative");
|
||||
}
|
||||
guard.authorize(
|
||||
DestructiveOperation.REDRIVE, request.source(), approval, request.dryRun(), now);
|
||||
|
||||
List<MessageId> candidates = source.peek(request.source(), request.batchSize());
|
||||
if (request.dryRun()) {
|
||||
return new RedriveReport(candidates.size(), 0, 0, true);
|
||||
}
|
||||
|
||||
List<MessageId> moved = new ArrayList<>();
|
||||
int failed = 0;
|
||||
int completed = resumeFrom;
|
||||
try {
|
||||
// Everything before resumeFrom was moved and settled by the previous attempt. Re-publishing
|
||||
// it is not a retry, it is a duplicate.
|
||||
for (MessageId messageId :
|
||||
candidates.subList(Math.min(resumeFrom, candidates.size()), candidates.size())) {
|
||||
if (attempt(messageId, request)) {
|
||||
moved.add(messageId);
|
||||
} else {
|
||||
failed++;
|
||||
}
|
||||
completed++;
|
||||
checkpoint.accept(completed);
|
||||
}
|
||||
} finally {
|
||||
// In the finally block on purpose: an operation that dies partway must still leave a record
|
||||
// of what it moved, because that record is what the resumed attempt and the incident review
|
||||
// both read.
|
||||
audit.record(
|
||||
new dev.caskeleton.messaging.observation.MessagingAuditEvent(
|
||||
"REDRIVE",
|
||||
subject,
|
||||
request.source().value(),
|
||||
approval.map(VerifiedApproval::ticket).orElse("dry-run"),
|
||||
now,
|
||||
java.util.Map.of(
|
||||
"redriveId", request.redriveId().toString(),
|
||||
"resumedFrom", Integer.toString(resumeFrom),
|
||||
"moved", Integer.toString(moved.size()),
|
||||
"failed", Integer.toString(failed))));
|
||||
}
|
||||
|
||||
return new RedriveReport(candidates.size(), moved.size(), failed, false);
|
||||
}
|
||||
|
||||
private boolean attempt(MessageId messageId, RedriveRequest request) {
|
||||
PublishResult result;
|
||||
try {
|
||||
result = publisher.republish(messageId, request.target(), request.redriveId());
|
||||
} catch (RuntimeException failure) {
|
||||
// One message that cannot be republished is a failed item, not a failed pass. Letting it
|
||||
// propagate abandoned every candidate behind it.
|
||||
return false;
|
||||
}
|
||||
if (result.completion() != PublishCompletion.CONFIRMED) {
|
||||
return false;
|
||||
}
|
||||
source.settle(request.source(), messageId);
|
||||
return true;
|
||||
}
|
||||
|
||||
/** Reads and settles messages on a dead letter destination. */
|
||||
public interface RedriveSource {
|
||||
|
||||
/**
|
||||
* Returns the next candidates without settling them.
|
||||
*
|
||||
* @param destination the dead letter destination
|
||||
* @param batchSize how many to return
|
||||
* @return the candidate identities
|
||||
*/
|
||||
List<MessageId> peek(
|
||||
dev.caskeleton.messaging.api.destination.DestinationName destination, int batchSize);
|
||||
|
||||
/**
|
||||
* Settles a message that has been successfully republished.
|
||||
*
|
||||
* @param destination the dead letter destination
|
||||
* @param messageId the message identity
|
||||
*/
|
||||
void settle(
|
||||
dev.caskeleton.messaging.api.destination.DestinationName destination, MessageId messageId);
|
||||
}
|
||||
|
||||
/** Republishes a dead lettered message to its target destination. */
|
||||
@FunctionalInterface
|
||||
public interface RedrivePublisher {
|
||||
|
||||
/**
|
||||
* Republishes one message under its original identity.
|
||||
*
|
||||
* @param messageId the message identity
|
||||
* @param target the destination to publish back to
|
||||
* @param redriveId the operation identity stamped on the message
|
||||
* @return the publish outcome
|
||||
*/
|
||||
PublishResult republish(
|
||||
MessageId messageId,
|
||||
dev.caskeleton.messaging.api.destination.DestinationName target,
|
||||
java.util.UUID redriveId);
|
||||
}
|
||||
|
||||
/** Records privileged operations. */
|
||||
@FunctionalInterface
|
||||
public interface AuditSink {
|
||||
|
||||
/**
|
||||
* Records one audit event.
|
||||
*
|
||||
* @param event the event
|
||||
*/
|
||||
void record(dev.caskeleton.messaging.observation.MessagingAuditEvent event);
|
||||
}
|
||||
}
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import java.util.Objects;
|
||||
import java.util.UUID;
|
||||
|
||||
/**
|
||||
* What one replay did.
|
||||
*
|
||||
* @param replayId the operation identity
|
||||
* @param replayed how many messages were re-read
|
||||
* @param dryRun whether this was a plan-only run
|
||||
*/
|
||||
public record ReplayReport(UUID replayId, long replayed, boolean dryRun) {
|
||||
|
||||
public ReplayReport {
|
||||
Objects.requireNonNull(replayId, "replayId must not be null");
|
||||
if (replayed < 0) {
|
||||
throw new IllegalArgumentException("replayed must not be negative");
|
||||
}
|
||||
}
|
||||
}
|
||||
+91
@@ -0,0 +1,91 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import dev.caskeleton.messaging.admin.DestructiveOperation;
|
||||
import dev.caskeleton.messaging.admin.DestructiveOperationGuard;
|
||||
import dev.caskeleton.messaging.admin.ReplayRequest;
|
||||
import dev.caskeleton.messaging.admin.VerifiedApproval;
|
||||
import dev.caskeleton.messaging.observation.MessagingAuditEvent;
|
||||
import java.time.Instant;
|
||||
import java.util.Map;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Re-reads a destination from an earlier position.
|
||||
*
|
||||
* <p>The request carries an {@code isolatedConsumerGroup} intent flag, but a caller-supplied
|
||||
* boolean is not proof that the executor actually created or used an isolated broker group.
|
||||
* Therefore every non-dry-run replay goes through the destructive guard until the runtime can
|
||||
* attest isolation itself. Dry-run remains approval-free because it changes no broker state.
|
||||
*/
|
||||
public final class ReplayService {
|
||||
|
||||
private final DestructiveOperationGuard guard;
|
||||
private final ReplayExecutor executor;
|
||||
private final RedriveService.AuditSink audit;
|
||||
|
||||
/**
|
||||
* Creates a replay service.
|
||||
*
|
||||
* @param guard the destructive operation guard
|
||||
* @param executor performs the replay
|
||||
* @param audit records the operation
|
||||
*/
|
||||
public ReplayService(
|
||||
DestructiveOperationGuard guard, ReplayExecutor executor, RedriveService.AuditSink audit) {
|
||||
this.guard = Objects.requireNonNull(guard, "guard must not be null");
|
||||
this.executor = Objects.requireNonNull(executor, "executor must not be null");
|
||||
this.audit = Objects.requireNonNull(audit, "audit must not be null");
|
||||
}
|
||||
|
||||
/**
|
||||
* Runs one replay.
|
||||
*
|
||||
* @param request what to replay
|
||||
* @param approval the verified approval, when one was supplied
|
||||
* @param subject the operator identity
|
||||
* @param now the current instant
|
||||
* @return what the replay did
|
||||
*/
|
||||
public ReplayReport replay(
|
||||
ReplayRequest request, Optional<VerifiedApproval> approval, String subject, Instant now) {
|
||||
Objects.requireNonNull(request, "request must not be null");
|
||||
Objects.requireNonNull(approval, "approval must not be null");
|
||||
|
||||
guard.authorize(
|
||||
DestructiveOperation.REPLAY, request.destination(), approval, request.dryRun(), now);
|
||||
|
||||
if (request.dryRun()) {
|
||||
return new ReplayReport(request.replayId(), 0, true);
|
||||
}
|
||||
|
||||
long replayed = executor.replay(request);
|
||||
|
||||
audit.record(
|
||||
new MessagingAuditEvent(
|
||||
"REPLAY",
|
||||
subject,
|
||||
request.destination().value(),
|
||||
approval.map(VerifiedApproval::ticket).orElse("dry-run"),
|
||||
now,
|
||||
Map.of(
|
||||
"replayId", request.replayId().toString(),
|
||||
"isolated", Boolean.toString(request.isolatedConsumerGroup()),
|
||||
"replayed", Long.toString(replayed))));
|
||||
|
||||
return new ReplayReport(request.replayId(), replayed, false);
|
||||
}
|
||||
|
||||
/** Performs the replay against a broker. */
|
||||
@FunctionalInterface
|
||||
public interface ReplayExecutor {
|
||||
|
||||
/**
|
||||
* Replays a destination and returns how many messages were re-read.
|
||||
*
|
||||
* @param request the replay request
|
||||
* @return the replayed message count
|
||||
*/
|
||||
long replay(ReplayRequest request);
|
||||
}
|
||||
}
|
||||
+88
@@ -0,0 +1,88 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import dev.caskeleton.messaging.admin.TopologyManifest;
|
||||
import dev.caskeleton.messaging.api.error.MessageTopologyException;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Validates declared topology against what the broker actually has.
|
||||
*
|
||||
* <p>Validate-only, and it fails startup rather than logging. A partition count that silently
|
||||
* differs from the manifest changes the ordering guarantee the destination advertises, and a
|
||||
* missing {@code min.insync.replicas} changes what {@code acks=all} actually means — both are the
|
||||
* kind of drift that is invisible until the incident.
|
||||
*/
|
||||
public final class TopologyValidationRuntime {
|
||||
|
||||
private final TopologyReader reader;
|
||||
|
||||
/**
|
||||
* Creates a validator over a broker reader.
|
||||
*
|
||||
* @param reader reads the observed topology
|
||||
*/
|
||||
public TopologyValidationRuntime(TopologyReader reader) {
|
||||
this.reader = Objects.requireNonNull(reader, "reader must not be null");
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates every manifest, reporting all differences at once.
|
||||
*
|
||||
* @param manifests the declared topology
|
||||
* @throws MessageTopologyException when the broker does not match
|
||||
*/
|
||||
public void validate(List<TopologyManifest> manifests) {
|
||||
Objects.requireNonNull(manifests, "manifests must not be null");
|
||||
List<String> problems = new ArrayList<>();
|
||||
|
||||
for (TopologyManifest manifest : manifests) {
|
||||
ObservedTopology observed = reader.read(manifest.physicalName());
|
||||
if (observed == null) {
|
||||
problems.add(manifest.physicalName() + " does not exist");
|
||||
continue;
|
||||
}
|
||||
manifest
|
||||
.differencesFrom(
|
||||
observed.partitions(), observed.replicationFactor(), observed.configuration())
|
||||
.forEach(difference -> problems.add(manifest.physicalName() + ": " + difference));
|
||||
}
|
||||
|
||||
if (!problems.isEmpty()) {
|
||||
throw new MessageTopologyException(
|
||||
"TOPOLOGY_MISMATCH",
|
||||
"broker topology does not match the manifest: " + String.join("; ", problems));
|
||||
}
|
||||
}
|
||||
|
||||
/** Reads the observed topology for a physical destination. */
|
||||
@FunctionalInterface
|
||||
public interface TopologyReader {
|
||||
|
||||
/**
|
||||
* Reads one destination's topology.
|
||||
*
|
||||
* @param physicalName the broker-side name
|
||||
* @return the observed topology, or null when it does not exist
|
||||
*/
|
||||
ObservedTopology read(String physicalName);
|
||||
}
|
||||
|
||||
/**
|
||||
* What the broker reports for a destination.
|
||||
*
|
||||
* @param partitions the observed partition count
|
||||
* @param replicationFactor the observed replication factor
|
||||
* @param configuration the observed configuration
|
||||
*/
|
||||
public record ObservedTopology(
|
||||
int partitions, int replicationFactor, Map<String, String> configuration) {
|
||||
|
||||
public ObservedTopology {
|
||||
Objects.requireNonNull(configuration, "configuration must not be null");
|
||||
configuration = Map.copyOf(configuration);
|
||||
}
|
||||
}
|
||||
}
|
||||
+91
@@ -0,0 +1,91 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import dev.caskeleton.messaging.admin.DestinationTopology;
|
||||
import dev.caskeleton.messaging.admin.TopologyIssue;
|
||||
import dev.caskeleton.messaging.admin.TopologyManifest;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Compares one declared topology against what the broker reports.
|
||||
*
|
||||
* <p>Which discrepancies block is a judgement encoded here rather than left to configuration.
|
||||
* Replication factor and absence are blocking because a destination that is missing or unreplicated
|
||||
* cannot deliver the durability its profile promises. A partition count that is <em>higher</em>
|
||||
* than declared is advisory rather than blocking: extra partitions do not break durability, and
|
||||
* someone scaling a topic up deliberately should not be met with a refusal to start.
|
||||
*
|
||||
* <p>A partition count that is <em>lower</em> is blocking, because it silently reduces the
|
||||
* concurrency the destination was sized for and, on a keyed topic, changes which key lands where.
|
||||
*/
|
||||
public final class TopologyValidator {
|
||||
|
||||
/**
|
||||
* Compares a manifest against observed topology.
|
||||
*
|
||||
* @param manifest what was declared
|
||||
* @param observed what the broker reports
|
||||
* @return the discrepancies found, empty when they agree
|
||||
*/
|
||||
public List<TopologyIssue> compare(TopologyManifest manifest, DestinationTopology observed) {
|
||||
Objects.requireNonNull(manifest, "manifest must not be null");
|
||||
Objects.requireNonNull(observed, "observed must not be null");
|
||||
|
||||
List<TopologyIssue> issues = new ArrayList<>();
|
||||
String destination = manifest.destination();
|
||||
|
||||
if (!observed.exists()) {
|
||||
issues.add(
|
||||
TopologyIssue.blocking(destination, "existence", manifest.physicalName(), "absent"));
|
||||
return List.copyOf(issues);
|
||||
}
|
||||
|
||||
if (!manifest.physicalName().equals(observed.physicalName())) {
|
||||
issues.add(
|
||||
TopologyIssue.blocking(
|
||||
destination, "physicalName", manifest.physicalName(), observed.physicalName()));
|
||||
}
|
||||
|
||||
if (observed.partitions() < manifest.partitions()) {
|
||||
issues.add(
|
||||
TopologyIssue.blocking(
|
||||
destination,
|
||||
"partitions",
|
||||
Integer.toString(manifest.partitions()),
|
||||
Integer.toString(observed.partitions())));
|
||||
} else if (observed.partitions() > manifest.partitions()) {
|
||||
// Scaling a topic up is a legitimate operation; refusing to start would punish it.
|
||||
issues.add(
|
||||
TopologyIssue.advisory(
|
||||
destination,
|
||||
"partitions",
|
||||
Integer.toString(manifest.partitions()),
|
||||
Integer.toString(observed.partitions())));
|
||||
}
|
||||
|
||||
if (observed.replicationFactor() < manifest.replicationFactor()) {
|
||||
issues.add(
|
||||
TopologyIssue.blocking(
|
||||
destination,
|
||||
"replicationFactor",
|
||||
Integer.toString(manifest.replicationFactor()),
|
||||
Integer.toString(observed.replicationFactor())));
|
||||
}
|
||||
|
||||
for (Map.Entry<String, String> required : manifest.requiredConfiguration().entrySet()) {
|
||||
String actual = observed.configuration().get(required.getKey());
|
||||
if (!required.getValue().equals(actual)) {
|
||||
issues.add(
|
||||
TopologyIssue.blocking(
|
||||
destination,
|
||||
required.getKey(),
|
||||
required.getValue(),
|
||||
actual == null ? "unset" : actual));
|
||||
}
|
||||
}
|
||||
|
||||
return List.copyOf(issues);
|
||||
}
|
||||
}
|
||||
+147
@@ -0,0 +1,147 @@
|
||||
package dev.caskeleton.messaging.admin;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatCode;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
|
||||
import java.time.Instant;
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
import java.util.UUID;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class DestructiveOperationGuardTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
|
||||
private static final DestinationName ORDERS = new DestinationName("order-events");
|
||||
|
||||
private static final HmacApprovalVerifier ISSUER =
|
||||
new HmacApprovalVerifier(
|
||||
"an-issuing-key-of-at-least-32-bytes!".getBytes(java.nio.charset.StandardCharsets.UTF_8));
|
||||
|
||||
private static final VerifiedApproval VALID =
|
||||
verified(DestructiveOperation.REPLAY, ORDERS, NOW.minusSeconds(60), NOW.plusSeconds(3600));
|
||||
|
||||
/**
|
||||
* A grant the issuer signed, verified the way the runtime verifies it.
|
||||
*
|
||||
* <p>The guard used to take a plain {@code AdminApproval} record, which any caller could
|
||||
* construct. Every case below now has to go through a real signature to get an approval object at
|
||||
* all, which is the property the type change was made for.
|
||||
*/
|
||||
private static VerifiedApproval verified(
|
||||
DestructiveOperation operation, DestinationName source, Instant from, Instant until) {
|
||||
PlanDigest digest = PlanDigest.ofCanonical(operation + "|" + source.value());
|
||||
ApprovalGrant grant =
|
||||
new ApprovalGrant(
|
||||
new AdminApproval("CHG-1001", "approver", from, until),
|
||||
"operator",
|
||||
operation,
|
||||
source,
|
||||
Optional.empty(),
|
||||
"v1",
|
||||
Long.MAX_VALUE,
|
||||
digest);
|
||||
return ISSUER.verify(grant, ISSUER.sign(grant), digest, from);
|
||||
}
|
||||
|
||||
@Test
|
||||
void anApplicationRuntimeCannotRedrive() {
|
||||
DestructiveOperationGuard guard = new DestructiveOperationGuard(false);
|
||||
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
guard.authorize(
|
||||
DestructiveOperation.REDRIVE, ORDERS, Optional.of(VALID), false, NOW))
|
||||
.isInstanceOf(MessageAuthorizationException.class)
|
||||
.hasMessageContaining("admin credential");
|
||||
}
|
||||
|
||||
@Test
|
||||
void anAdminRuntimeStillNeedsAnApproval() {
|
||||
DestructiveOperationGuard guard = new DestructiveOperationGuard(true);
|
||||
|
||||
assertThatThrownBy(
|
||||
() -> guard.authorize(DestructiveOperation.PURGE, ORDERS, Optional.empty(), false, NOW))
|
||||
.isInstanceOf(MessageAuthorizationException.class)
|
||||
.hasMessageContaining("approval");
|
||||
}
|
||||
|
||||
@Test
|
||||
void anExpiredApprovalDoesNotAuthorise() {
|
||||
DestructiveOperationGuard guard = new DestructiveOperationGuard(true);
|
||||
VerifiedApproval expired =
|
||||
verified(
|
||||
DestructiveOperation.OFFSET_RESET,
|
||||
ORDERS,
|
||||
NOW.minusSeconds(7200),
|
||||
NOW.minusSeconds(60));
|
||||
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
guard.authorize(
|
||||
DestructiveOperation.OFFSET_RESET, ORDERS, Optional.of(expired), false, NOW))
|
||||
.isInstanceOf(MessageAuthorizationException.class)
|
||||
.hasMessageContaining("validity window");
|
||||
}
|
||||
|
||||
@Test
|
||||
void aDryRunIsAlwaysPermitted() {
|
||||
DestructiveOperationGuard guard = new DestructiveOperationGuard(false);
|
||||
|
||||
assertThatCode(
|
||||
() ->
|
||||
guard.authorize(
|
||||
DestructiveOperation.DELETE_DESTINATION, ORDERS, Optional.empty(), true, NOW))
|
||||
.doesNotThrowAnyException();
|
||||
}
|
||||
|
||||
@Test
|
||||
void anApprovedAdminOperationIsAuthorised() {
|
||||
DestructiveOperationGuard guard = new DestructiveOperationGuard(true);
|
||||
|
||||
assertThatCode(
|
||||
() ->
|
||||
guard.authorize(
|
||||
DestructiveOperation.REPLAY, ORDERS, Optional.of(VALID), false, NOW))
|
||||
.doesNotThrowAnyException();
|
||||
}
|
||||
|
||||
@Test
|
||||
void aRedriveCannotTargetItsOwnSource() {
|
||||
assertThatThrownBy(() -> new RedriveRequest(UUID.randomUUID(), ORDERS, ORDERS, 100, false))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
}
|
||||
|
||||
@Test
|
||||
void aRedriveBatchIsBoundedSoOneOperationCannotFloodTheSource() {
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new RedriveRequest(
|
||||
UUID.randomUUID(), new DestinationName("order-events-dlq"), ORDERS, 101, false))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
}
|
||||
|
||||
@Test
|
||||
void aTopologyManifestReportsEveryDifference() {
|
||||
TopologyManifest manifest =
|
||||
new TopologyManifest(
|
||||
"order-events", "order.events.v1", 6, 3, Map.of("min.insync.replicas", "2"));
|
||||
|
||||
assertThat(manifest.differencesFrom(3, 3, Map.of("min.insync.replicas", "1")))
|
||||
.hasSize(2)
|
||||
.anySatisfy(difference -> assertThat(difference).contains("partitions"))
|
||||
.anySatisfy(difference -> assertThat(difference).contains("min.insync.replicas"));
|
||||
}
|
||||
|
||||
@Test
|
||||
void aMatchingTopologyReportsNoDifferences() {
|
||||
TopologyManifest manifest =
|
||||
new TopologyManifest(
|
||||
"order-events", "order.events.v1", 6, 3, Map.of("min.insync.replicas", "2"));
|
||||
|
||||
assertThat(manifest.differencesFrom(6, 3, Map.of("min.insync.replicas", "2"))).isEmpty();
|
||||
}
|
||||
}
|
||||
+145
@@ -0,0 +1,145 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatCode;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.messaging.admin.AdminOperationLease;
|
||||
import dev.caskeleton.messaging.admin.AdminOperationState;
|
||||
import dev.caskeleton.messaging.admin.PlanDigest;
|
||||
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
/**
|
||||
* The protocol the journal has to implement, proven against the in-memory one.
|
||||
*
|
||||
* <p>What it replaced recorded a single fact — "this approval was claimed" — before any work
|
||||
* happened, in a map. An operation that died halfway had spent its approval, left no record of what
|
||||
* it had already moved, and gave a retry no way to continue: either request a new approval and
|
||||
* republish everything, or leave the redrive half applied.
|
||||
*/
|
||||
class AdminOperationJournalTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-08-10T09:00:00Z");
|
||||
private static final Duration LEASE = Duration.ofMinutes(5);
|
||||
private static final String TICKET = "CHG-1042";
|
||||
private static final PlanDigest DIGEST = PlanDigest.ofCanonical("REDRIVE|orders.v1.dlq|50");
|
||||
private static final PlanDigest OTHER_DIGEST = PlanDigest.ofCanonical("REDRIVE|payments.dlq|50");
|
||||
|
||||
private final InMemoryAdminOperationJournal journal = new InMemoryAdminOperationJournal();
|
||||
|
||||
@Test
|
||||
@DisplayName("two replicas racing for one approval produce exactly one lease")
|
||||
void twoReplicasRacingProduceExactlyOneLease() {
|
||||
journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
|
||||
|
||||
assertThatThrownBy(
|
||||
() -> journal.begin(TICKET, DIGEST, "op-2", "replica-b", LEASE, NOW.plusSeconds(1)))
|
||||
.as("both replicas executing one approval is a duplicate storm, not a faster redrive")
|
||||
.isInstanceOf(MessageAuthorizationException.class)
|
||||
.hasMessageContaining("replica-a");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a completed operation cannot be executed again")
|
||||
void aCompletedOperationCannotBeExecutedAgain() {
|
||||
AdminOperationLease lease = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
|
||||
journal.complete(lease, 50, NOW.plusSeconds(30));
|
||||
|
||||
assertThatThrownBy(
|
||||
() -> journal.begin(TICKET, DIGEST, "op-2", "replica-a", LEASE, NOW.plusSeconds(60)))
|
||||
.as("an arrow-up in the shell must not re-run an approved redrive")
|
||||
.isInstanceOf(MessageAuthorizationException.class)
|
||||
.hasMessageContaining("already executed");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a crashed run resumes from its checkpoint rather than starting over")
|
||||
void aCrashedRunResumesFromItsCheckpoint() {
|
||||
AdminOperationLease first = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
|
||||
journal.checkpoint(first, 30, LEASE, NOW.plusSeconds(10));
|
||||
// No fail() call: this replica died. The lease simply runs out.
|
||||
|
||||
AdminOperationLease resumed =
|
||||
journal.begin(TICKET, DIGEST, "op-1", "replica-b", LEASE, NOW.plus(Duration.ofMinutes(10)));
|
||||
|
||||
assertThat(resumed.resumeFrom())
|
||||
.as("the 30 already moved must not be republished")
|
||||
.isEqualTo(30);
|
||||
assertThat(resumed.leaseToken()).isGreaterThan(first.leaseToken());
|
||||
assertThat(resumed.isResumption()).isTrue();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a failed run stays resumable without waiting for the lease to expire")
|
||||
void aFailedRunStaysResumableImmediately() {
|
||||
AdminOperationLease first = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
|
||||
journal.checkpoint(first, 12, LEASE, NOW.plusSeconds(5));
|
||||
journal.fail(first, 12, "MESSAGE_BROKER_UNAVAILABLE", NOW.plusSeconds(6));
|
||||
|
||||
AdminOperationLease resumed =
|
||||
journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW.plusSeconds(7));
|
||||
|
||||
assertThat(resumed.resumeFrom()).isEqualTo(12);
|
||||
assertThat(journal.find(TICKET, DIGEST))
|
||||
.hasValueSatisfying(
|
||||
record -> assertThat(record.state()).isEqualTo(AdminOperationState.STARTED));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a runtime that lost its lease cannot write over the one that took over")
|
||||
void aRuntimeThatLostItsLeaseCannotWriteOverTheSuccessor() {
|
||||
AdminOperationLease stale = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
|
||||
journal.checkpoint(stale, 30, LEASE, NOW.plusSeconds(10));
|
||||
AdminOperationLease successor =
|
||||
journal.begin(TICKET, DIGEST, "op-1", "replica-b", LEASE, NOW.plus(Duration.ofMinutes(10)));
|
||||
journal.checkpoint(successor, 45, LEASE, NOW.plus(Duration.ofMinutes(11)));
|
||||
|
||||
assertThatThrownBy(() -> journal.complete(stale, 30, NOW.plus(Duration.ofMinutes(12))))
|
||||
.as("a stalled replica waking up must not mark the operation done at its own count")
|
||||
.isInstanceOf(MessageAuthorizationException.class)
|
||||
.hasMessageContaining("no longer owns");
|
||||
|
||||
assertThat(journal.find(TICKET, DIGEST))
|
||||
.hasValueSatisfying(
|
||||
record -> {
|
||||
assertThat(record.itemsCompleted()).isEqualTo(45);
|
||||
assertThat(record.state()).isEqualTo(AdminOperationState.STARTED);
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the same ticket presented for a different plan is a different operation")
|
||||
void theSameTicketForADifferentPlanIsADifferentOperation() {
|
||||
journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
|
||||
|
||||
// Keyed on the ticket alone this would have been refused as a duplicate execution, which reads
|
||||
// as protection but is actually the wrong answer: it is a different plan, and it must be
|
||||
// refused by the approval binding rather than silently treated as the same operation.
|
||||
assertThatCode(() -> journal.begin(TICKET, OTHER_DIGEST, "op-2", "replica-a", LEASE, NOW))
|
||||
.doesNotThrowAnyException();
|
||||
assertThat(journal.size()).isEqualTo(2);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a checkpoint never moves backwards")
|
||||
void aCheckpointNeverMovesBackwards() {
|
||||
AdminOperationLease lease = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
|
||||
journal.checkpoint(lease, 40, LEASE, NOW.plusSeconds(10));
|
||||
journal.checkpoint(lease, 5, LEASE, NOW.plusSeconds(20));
|
||||
|
||||
assertThat(journal.find(TICKET, DIGEST))
|
||||
.hasValueSatisfying(record -> assertThat(record.itemsCompleted()).isEqualTo(40));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the in-memory journal declares itself non-durable")
|
||||
void theInMemoryJournalDeclaresItselfNonDurable() {
|
||||
assertThat(journal.isDurable())
|
||||
.as("the starter refuses a production profile on a journal that says this")
|
||||
.isFalse();
|
||||
}
|
||||
}
|
||||
+243
@@ -0,0 +1,243 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatCode;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.messaging.admin.AdminApproval;
|
||||
import dev.caskeleton.messaging.admin.ApprovalGrant;
|
||||
import dev.caskeleton.messaging.admin.ApprovedRedrivePlan;
|
||||
import dev.caskeleton.messaging.admin.DestructiveOperation;
|
||||
import dev.caskeleton.messaging.admin.HmacApprovalVerifier;
|
||||
import dev.caskeleton.messaging.admin.RedrivePlan;
|
||||
import dev.caskeleton.messaging.admin.RedriveRequest;
|
||||
import dev.caskeleton.messaging.admin.VerifiedApproval;
|
||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.util.Optional;
|
||||
import java.util.UUID;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
/**
|
||||
* Whether "this was approved" is a fact or a claim the caller makes about itself.
|
||||
*
|
||||
* <p>It was a claim. {@code AdminApproval} was a public record and {@code ApprovedRedrivePlan} a
|
||||
* public record over it, so any code that could reach the execute method could write its own
|
||||
* approval and the platform believed it. Nothing bound an approval to an operation, a destination,
|
||||
* a topology version, or an impact ceiling either, so a genuine approval for one redrive authorised
|
||||
* a redrive of anything else inside its window.
|
||||
*/
|
||||
class ApprovalForgeryTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-08-10T09:00:00Z");
|
||||
private static final UUID OPERATION_ID = UUID.fromString("0199aaaa-bbbb-7ccc-8ddd-eeeeffff0000");
|
||||
private static final DestinationName DLQ = new DestinationName("orders.v1.dlq");
|
||||
private static final DestinationName ORDERS = new DestinationName("orders.v1");
|
||||
|
||||
private static final HmacApprovalVerifier ISSUER =
|
||||
new HmacApprovalVerifier(
|
||||
"an-issuing-key-of-at-least-32-bytes!".getBytes(StandardCharsets.UTF_8));
|
||||
|
||||
private static final HmacApprovalVerifier ANOTHER_ISSUER =
|
||||
new HmacApprovalVerifier(
|
||||
"a-different-key-of-at-least-32-bytes".getBytes(StandardCharsets.UTF_8));
|
||||
|
||||
@Test
|
||||
@DisplayName("a verified approval cannot be constructed outside the verifier")
|
||||
void aVerifiedApprovalCannotBeConstructedOutsideTheVerifier() {
|
||||
// Written as a reflection probe because the property is about the type's shape, not its
|
||||
// behaviour: if a public constructor or factory ever appears, every other test here becomes
|
||||
// decorative.
|
||||
assertThat(VerifiedApproval.class.getConstructors())
|
||||
.as("a public constructor would let any caller mint an approval for itself")
|
||||
.isEmpty();
|
||||
assertThat(
|
||||
java.util.Arrays.stream(VerifiedApproval.class.getDeclaredMethods())
|
||||
.filter(method -> java.lang.reflect.Modifier.isStatic(method.getModifiers()))
|
||||
.filter(method -> java.lang.reflect.Modifier.isPublic(method.getModifiers()))
|
||||
.toList())
|
||||
.as("nor may a public static factory")
|
||||
.isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an unsigned or altered grant does not verify")
|
||||
void anAlteredGrantDoesNotVerify() {
|
||||
RedrivePlan plan = plan(50, 0);
|
||||
ApprovalGrant signed = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 50);
|
||||
String signature = ISSUER.sign(signed);
|
||||
|
||||
ApprovalGrant raised = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 5_000);
|
||||
|
||||
assertThatThrownBy(() -> ISSUER.verify(raised, signature, plan.digest(), NOW))
|
||||
.as("raising the impact ceiling after the approver signed it")
|
||||
.isInstanceOf(MessageAuthorizationException.class)
|
||||
.hasMessageContaining("does not verify");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a signature from another issuer does not verify")
|
||||
void aSignatureFromAnotherIssuerDoesNotVerify() {
|
||||
RedrivePlan plan = plan(50, 0);
|
||||
ApprovalGrant granted = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 50);
|
||||
|
||||
assertThatThrownBy(
|
||||
() -> ISSUER.verify(granted, ANOTHER_ISSUER.sign(granted), plan.digest(), NOW))
|
||||
.isInstanceOf(MessageAuthorizationException.class)
|
||||
.hasMessageContaining("does not verify");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an approval for one plan cannot execute another")
|
||||
void anApprovalForOnePlanCannotExecuteAnother() {
|
||||
RedrivePlan approvedPlan = plan(50, 0);
|
||||
RedrivePlan biggerPlan = plan(900, 0);
|
||||
ApprovalGrant granted = grant(approvedPlan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 900);
|
||||
String signature = ISSUER.sign(granted);
|
||||
|
||||
assertThatThrownBy(() -> ISSUER.verify(granted, signature, biggerPlan.digest(), NOW))
|
||||
.as("the approver saw 50 candidates; this plan moves 900")
|
||||
.isInstanceOf(MessageAuthorizationException.class)
|
||||
.hasMessageContaining("was issued for plan");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a verified approval for the wrong source cannot be attached to a plan")
|
||||
void aVerifiedApprovalForTheWrongSourceCannotBeAttached() {
|
||||
RedrivePlan plan = plan(50, 0);
|
||||
// A genuine, correctly-signed approval — for a different dead-letter destination, with this
|
||||
// plan's digest smuggled in. The digest check passes; the source binding is what catches it.
|
||||
ApprovalGrant granted =
|
||||
new ApprovalGrant(
|
||||
approval(),
|
||||
"operator@example.com",
|
||||
DestructiveOperation.REDRIVE,
|
||||
new DestinationName("payments.v1.dlq"),
|
||||
Optional.of(ORDERS),
|
||||
"v1",
|
||||
900,
|
||||
plan.digest());
|
||||
VerifiedApproval verified = ISSUER.verify(granted, ISSUER.sign(granted), plan.digest(), NOW);
|
||||
|
||||
assertThatThrownBy(() -> new ApprovedRedrivePlan(plan, verified, false))
|
||||
.isInstanceOf(MessageAuthorizationException.class)
|
||||
.hasMessageContaining("payments.v1.dlq");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a plan beyond the approved impact ceiling cannot execute")
|
||||
void aPlanBeyondTheApprovedImpactCeilingCannotExecute() {
|
||||
RedrivePlan plan = plan(900, 0);
|
||||
ApprovalGrant granted = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 100);
|
||||
VerifiedApproval verified = ISSUER.verify(granted, ISSUER.sign(granted), plan.digest(), NOW);
|
||||
|
||||
assertThatThrownBy(() -> new ApprovedRedrivePlan(plan, verified, false))
|
||||
.as("the approver agreed to at most 100")
|
||||
.isInstanceOf(MessageAuthorizationException.class)
|
||||
.hasMessageContaining("at most 100");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an approval for a replay cannot authorise a redrive")
|
||||
void anApprovalForAReplayCannotAuthoriseARedrive() {
|
||||
RedrivePlan plan = plan(50, 0);
|
||||
ApprovalGrant granted = grant(plan, DestructiveOperation.REPLAY, DLQ, ORDERS, 900);
|
||||
VerifiedApproval verified = ISSUER.verify(granted, ISSUER.sign(granted), plan.digest(), NOW);
|
||||
|
||||
assertThatThrownBy(() -> new ApprovedRedrivePlan(plan, verified, false))
|
||||
.isInstanceOf(MessageAuthorizationException.class)
|
||||
.hasMessageContaining("authorises REPLAY");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an expired grant does not verify")
|
||||
void anExpiredGrantDoesNotVerify() {
|
||||
RedrivePlan plan = plan(50, 0);
|
||||
ApprovalGrant granted = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 50);
|
||||
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
ISSUER.verify(
|
||||
granted, ISSUER.sign(granted), plan.digest(), NOW.plus(Duration.ofDays(1))))
|
||||
.isInstanceOf(MessageAuthorizationException.class)
|
||||
.hasMessageContaining("not valid at");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the approver and the operator must be different people")
|
||||
void theApproverAndTheOperatorMustBeDifferentPeople() {
|
||||
RedrivePlan plan = plan(50, 0);
|
||||
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new ApprovalGrant(
|
||||
approval(),
|
||||
"ops@example.com",
|
||||
DestructiveOperation.REDRIVE,
|
||||
DLQ,
|
||||
Optional.of(ORDERS),
|
||||
"v1",
|
||||
50,
|
||||
plan.digest()))
|
||||
.as("an operator approving their own destructive operation is the control not existing")
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("destructive admin plans can only carry a verified approval")
|
||||
void destructiveAdminUsesTheUnforgeableApprovalType() {
|
||||
assertThat(
|
||||
java.util.Arrays.stream(DestructiveMessagingAdmin.Approved.class.getRecordComponents())
|
||||
.filter(component -> component.getName().equals("approval"))
|
||||
.findFirst()
|
||||
.orElseThrow()
|
||||
.getType())
|
||||
.isEqualTo(VerifiedApproval.class);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a correctly issued approval executes")
|
||||
void aCorrectlyIssuedApprovalExecutes() {
|
||||
RedrivePlan plan = plan(50, 0);
|
||||
ApprovalGrant granted = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 50);
|
||||
VerifiedApproval verified = ISSUER.verify(granted, ISSUER.sign(granted), plan.digest(), NOW);
|
||||
|
||||
assertThatCode(
|
||||
() -> new ApprovedRedrivePlan(plan, verified, false).requireExecutable(NOW, "v1"))
|
||||
.doesNotThrowAnyException();
|
||||
}
|
||||
|
||||
private static ApprovalGrant grant(
|
||||
RedrivePlan plan,
|
||||
DestructiveOperation operation,
|
||||
DestinationName source,
|
||||
DestinationName target,
|
||||
long maxImpact) {
|
||||
return new ApprovalGrant(
|
||||
approval(),
|
||||
"operator@example.com",
|
||||
operation,
|
||||
source,
|
||||
Optional.of(target),
|
||||
"v1",
|
||||
maxImpact,
|
||||
plan.digest());
|
||||
}
|
||||
|
||||
private static AdminApproval approval() {
|
||||
return new AdminApproval("CHG-1042", "ops@example.com", NOW, NOW.plus(Duration.ofHours(2)));
|
||||
}
|
||||
|
||||
private static RedrivePlan plan(int candidates, int alreadyRedriven) {
|
||||
return new RedrivePlan(
|
||||
new RedriveRequest(OPERATION_ID, DLQ, ORDERS, 50, false),
|
||||
candidates,
|
||||
alreadyRedriven,
|
||||
NOW,
|
||||
"v1");
|
||||
}
|
||||
}
|
||||
+226
@@ -0,0 +1,226 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatCode;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.messaging.admin.AdminApproval;
|
||||
import dev.caskeleton.messaging.admin.ApprovalGrant;
|
||||
import dev.caskeleton.messaging.admin.ApprovedRedrivePlan;
|
||||
import dev.caskeleton.messaging.admin.ApprovedReplayPlan;
|
||||
import dev.caskeleton.messaging.admin.DestructiveOperation;
|
||||
import dev.caskeleton.messaging.admin.HmacApprovalVerifier;
|
||||
import dev.caskeleton.messaging.admin.PlanDigest;
|
||||
import dev.caskeleton.messaging.admin.RedrivePlan;
|
||||
import dev.caskeleton.messaging.admin.RedriveRequest;
|
||||
import dev.caskeleton.messaging.admin.RedriveResult;
|
||||
import dev.caskeleton.messaging.admin.ReplayPlan;
|
||||
import dev.caskeleton.messaging.admin.ReplayRequest;
|
||||
import dev.caskeleton.messaging.admin.ReplayResult;
|
||||
import dev.caskeleton.messaging.admin.VerifiedApproval;
|
||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.util.Optional;
|
||||
import java.util.UUID;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class ApprovedPlanExecutionTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-08-10T09:00:00Z");
|
||||
private static final UUID OPERATION_ID = UUID.fromString("0199aaaa-bbbb-7ccc-8ddd-eeeeffff0000");
|
||||
|
||||
private static final byte[] ISSUING_KEY =
|
||||
"an-issuing-key-of-at-least-32-bytes!".getBytes(java.nio.charset.StandardCharsets.UTF_8);
|
||||
|
||||
private static final HmacApprovalVerifier VERIFIER = new HmacApprovalVerifier(ISSUING_KEY);
|
||||
|
||||
private static AdminApproval approval() {
|
||||
return new AdminApproval("CHG-1042", "ops@example.com", NOW, NOW.plus(Duration.ofHours(2)));
|
||||
}
|
||||
|
||||
/** A grant the issuer signed for exactly this plan, verified the way the runtime verifies it. */
|
||||
static VerifiedApproval verified(
|
||||
PlanDigest digest,
|
||||
DestructiveOperation operation,
|
||||
DestinationName source,
|
||||
Optional<DestinationName> target,
|
||||
String topologyVersion,
|
||||
long maxImpact) {
|
||||
ApprovalGrant grant =
|
||||
new ApprovalGrant(
|
||||
approval(),
|
||||
"operator@example.com",
|
||||
operation,
|
||||
source,
|
||||
target,
|
||||
topologyVersion,
|
||||
maxImpact,
|
||||
digest);
|
||||
return VERIFIER.verify(grant, VERIFIER.sign(grant), digest, NOW);
|
||||
}
|
||||
|
||||
private static VerifiedApproval replayApproval(ReplayPlan plan) {
|
||||
return verified(
|
||||
plan.digest(),
|
||||
DestructiveOperation.REPLAY,
|
||||
plan.request().destination(),
|
||||
Optional.empty(),
|
||||
plan.topologyVersion(),
|
||||
Long.MAX_VALUE);
|
||||
}
|
||||
|
||||
private static VerifiedApproval redriveApproval(RedrivePlan plan) {
|
||||
return verified(
|
||||
plan.digest(),
|
||||
DestructiveOperation.REDRIVE,
|
||||
plan.request().source(),
|
||||
Optional.of(plan.request().target()),
|
||||
plan.topologyVersion(),
|
||||
Long.MAX_VALUE);
|
||||
}
|
||||
|
||||
private static ReplayRequest replayRequest() {
|
||||
return new ReplayRequest(
|
||||
OPERATION_ID,
|
||||
new DestinationName("orders.v1"),
|
||||
NOW.minus(Duration.ofDays(1)),
|
||||
Optional.empty(),
|
||||
true,
|
||||
false);
|
||||
}
|
||||
|
||||
private static ReplayPlan replayPlan(String topologyVersion) {
|
||||
return new ReplayPlan(replayRequest(), 4_200_000, NOW, topologyVersion, false);
|
||||
}
|
||||
|
||||
private static RedriveRequest redriveRequest() {
|
||||
return new RedriveRequest(
|
||||
OPERATION_ID,
|
||||
new DestinationName("orders.v1.dlq"),
|
||||
new DestinationName("orders.v1"),
|
||||
50,
|
||||
false);
|
||||
}
|
||||
|
||||
private static RedrivePlan redrivePlan(int candidates, int alreadyRedriven) {
|
||||
return new RedrivePlan(redriveRequest(), candidates, alreadyRedriven, NOW, "v1");
|
||||
}
|
||||
|
||||
private static ApprovedReplayPlan approvedReplay(String topologyVersion) {
|
||||
ReplayPlan plan = replayPlan(topologyVersion);
|
||||
return new ApprovedReplayPlan(plan, replayApproval(plan));
|
||||
}
|
||||
|
||||
private static ApprovedRedrivePlan approvedRedrive(RedrivePlan plan, boolean loopAcknowledged) {
|
||||
return new ApprovedRedrivePlan(plan, redriveApproval(plan), loopAcknowledged);
|
||||
}
|
||||
|
||||
@Test
|
||||
void anExpiredApprovalCannotExecute() {
|
||||
ApprovedReplayPlan approved = approvedReplay("v1");
|
||||
|
||||
assertThatThrownBy(() -> approved.requireExecutable(NOW.plus(Duration.ofDays(1)), "v1"))
|
||||
.isInstanceOf(MessageAuthorizationException.class)
|
||||
.hasMessageContaining("CHG-1042");
|
||||
}
|
||||
|
||||
@Test
|
||||
void aTopologyChangeSinceApprovalInvalidatesThePlan() {
|
||||
ApprovedReplayPlan approved = approvedReplay("v1");
|
||||
|
||||
assertThatThrownBy(() -> approved.requireExecutable(NOW, "v2"))
|
||||
.as("every number in the plan was computed against the old topology")
|
||||
.isInstanceOf(MessageAuthorizationException.class)
|
||||
// The signed grant carries the topology version too, so the mismatch is now caught against
|
||||
// what the approver actually signed rather than against a field on the plan the caller
|
||||
// handed in.
|
||||
.hasMessageContaining("was signed against topology v1 but the broker is now at v2");
|
||||
}
|
||||
|
||||
@Test
|
||||
void aValidApprovalOnUnchangedTopologyExecutes() {
|
||||
assertThatCode(() -> approvedReplay("v1").requireExecutable(NOW, "v1"))
|
||||
.doesNotThrowAnyException();
|
||||
}
|
||||
|
||||
@Test
|
||||
void aRedriveThatWouldLoopNeedsThatAcknowledgedExplicitly() {
|
||||
ApprovedRedrivePlan approved = approvedRedrive(redrivePlan(900, 400), false);
|
||||
|
||||
assertThatThrownBy(() -> approved.requireExecutable(NOW, "v1"))
|
||||
.isInstanceOf(MessageAuthorizationException.class)
|
||||
.hasMessageContaining("looks like progress");
|
||||
}
|
||||
|
||||
@Test
|
||||
void anAcknowledgedLoopMayProceed() {
|
||||
assertThatCode(() -> approvedRedrive(redrivePlan(900, 400), true).requireExecutable(NOW, "v1"))
|
||||
.doesNotThrowAnyException();
|
||||
}
|
||||
|
||||
@Test
|
||||
void aRedriveWithNoPreviouslyRedrivenCandidatesNeedsNoAcknowledgement() {
|
||||
assertThatCode(() -> approvedRedrive(redrivePlan(900, 0), false).requireExecutable(NOW, "v1"))
|
||||
.doesNotThrowAnyException();
|
||||
}
|
||||
|
||||
@Test
|
||||
void thePlanDescribesItsImpactBeforeAnythingRuns() {
|
||||
assertThat(replayPlan("v1").describeImpact()).contains("4200000").contains("isolated group");
|
||||
assertThat(redrivePlan(900, 400).describeImpact())
|
||||
.contains("already failed a previous redrive");
|
||||
}
|
||||
|
||||
@Test
|
||||
void aReplayIntoTheLiveGroupSaysSoInCapitals() {
|
||||
ReplayPlan live =
|
||||
new ReplayPlan(
|
||||
new ReplayRequest(
|
||||
OPERATION_ID,
|
||||
new DestinationName("orders.v1"),
|
||||
NOW.minus(Duration.ofDays(1)),
|
||||
Optional.empty(),
|
||||
false,
|
||||
false),
|
||||
4_200_000,
|
||||
NOW,
|
||||
"v1",
|
||||
true);
|
||||
|
||||
assertThat(live.describeImpact())
|
||||
.as("re-delivering millions of messages into the live group is the decision to flag")
|
||||
.contains("LIVE consumer group");
|
||||
}
|
||||
|
||||
@Test
|
||||
void aReplayResultFlagsAShortfallAgainstTheApprovedEstimate() {
|
||||
ReplayResult result =
|
||||
new ReplayResult(OPERATION_ID, 1_000_000, 100_000, Duration.ofMinutes(3), true, false);
|
||||
|
||||
assertThat(result.fellShortOfTheEstimate())
|
||||
.as("retention may have expired part of the approved window")
|
||||
.isTrue();
|
||||
}
|
||||
|
||||
@Test
|
||||
void aRedriveResultMustAccountForEveryCandidate() {
|
||||
RedriveResult accounted =
|
||||
new RedriveResult(OPERATION_ID, 100, 80, 20, Duration.ofSeconds(4), false);
|
||||
RedriveResult unaccounted =
|
||||
new RedriveResult(OPERATION_ID, 100, 80, 10, Duration.ofSeconds(4), false);
|
||||
|
||||
assertThat(accounted.isFullyAccounted()).isTrue();
|
||||
assertThat(unaccounted.isFullyAccounted())
|
||||
.as("a message that was neither moved nor left parked has been lost track of")
|
||||
.isFalse();
|
||||
}
|
||||
|
||||
@Test
|
||||
void aDryRunCannotClaimToHaveMovedAnything() {
|
||||
assertThatThrownBy(
|
||||
() -> new RedriveResult(OPERATION_ID, 100, 5, 0, Duration.ofSeconds(1), true))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
}
|
||||
}
|
||||
+212
@@ -0,0 +1,212 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import dev.caskeleton.messaging.admin.AdminApproval;
|
||||
import dev.caskeleton.messaging.admin.ApprovalGrant;
|
||||
import dev.caskeleton.messaging.admin.DestructiveOperation;
|
||||
import dev.caskeleton.messaging.admin.DestructiveOperationGuard;
|
||||
import dev.caskeleton.messaging.admin.HmacApprovalVerifier;
|
||||
import dev.caskeleton.messaging.admin.PlanDigest;
|
||||
import dev.caskeleton.messaging.admin.RedriveRequest;
|
||||
import dev.caskeleton.messaging.admin.VerifiedApproval;
|
||||
import dev.caskeleton.messaging.api.MessageId;
|
||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||
import dev.caskeleton.messaging.api.publish.ConfirmationLevel;
|
||||
import dev.caskeleton.messaging.api.publish.PublishCompletion;
|
||||
import dev.caskeleton.messaging.api.publish.PublishEvidence;
|
||||
import dev.caskeleton.messaging.api.publish.PublishResult;
|
||||
import dev.caskeleton.messaging.api.publish.RoutingOutcome;
|
||||
import dev.caskeleton.messaging.observation.MessagingAuditEvent;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Optional;
|
||||
import java.util.UUID;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
/**
|
||||
* What a redrive does when one message fails, and what it does the second time round.
|
||||
*
|
||||
* <p>The loop had no per-item boundary. A publisher that threw — a broker refusing the connection
|
||||
* rather than the message — propagated straight out, so every candidate behind it was abandoned and
|
||||
* the audit record was never written. The operation left no trace of what it had already moved, and
|
||||
* a retry started again from the first candidate and republished it.
|
||||
*/
|
||||
class RedriveResumptionTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-08-10T09:00:00Z");
|
||||
private static final DestinationName DLQ = new DestinationName("orders.v1.dlq");
|
||||
private static final DestinationName ORDERS = new DestinationName("orders.v1");
|
||||
|
||||
private static final HmacApprovalVerifier ISSUER =
|
||||
new HmacApprovalVerifier(
|
||||
"an-issuing-key-of-at-least-32-bytes!".getBytes(java.nio.charset.StandardCharsets.UTF_8));
|
||||
|
||||
private final RecordingSource source = new RecordingSource();
|
||||
private final RecordingAudit audit = new RecordingAudit();
|
||||
|
||||
@Test
|
||||
@DisplayName("one message that throws does not abandon the ones behind it")
|
||||
void oneThrowingMessageDoesNotAbandonTheRest() {
|
||||
List<MessageId> candidates = ids(4);
|
||||
source.stage(candidates);
|
||||
RedriveService service =
|
||||
service(
|
||||
(messageId, target, redriveId) -> {
|
||||
if (messageId.equals(candidates.get(1))) {
|
||||
throw new IllegalStateException("the broker refused the connection");
|
||||
}
|
||||
return confirmed();
|
||||
});
|
||||
|
||||
RedriveReport report = service.redrive(request(), approval(), "operator", NOW);
|
||||
|
||||
assertThat(report.moved()).isEqualTo(3);
|
||||
assertThat(report.failed())
|
||||
.as("the throwing item is a failed item, not a failed pass")
|
||||
.isEqualTo(1);
|
||||
assertThat(source.settled)
|
||||
.containsExactly(candidates.get(0), candidates.get(2), candidates.get(3));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the audit record is written even when the pass does not finish cleanly")
|
||||
void theAuditRecordIsWrittenEvenOnFailure() {
|
||||
source.stage(ids(2));
|
||||
RedriveService service =
|
||||
service(
|
||||
(messageId, target, redriveId) -> {
|
||||
throw new IllegalStateException("the broker refused the connection");
|
||||
});
|
||||
|
||||
service.redrive(request(), approval(), "operator", NOW);
|
||||
|
||||
assertThat(audit.events)
|
||||
.as("the record of what moved is what the incident review and the resumed run both read")
|
||||
.singleElement()
|
||||
.satisfies(event -> assertThat(event.details()).containsEntry("failed", "2"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a resumed pass does not republish what the first attempt already moved")
|
||||
void aResumedPassDoesNotRepublishWhatWasAlreadyMoved() {
|
||||
List<MessageId> candidates = ids(5);
|
||||
source.stage(candidates);
|
||||
List<MessageId> republished = new ArrayList<>();
|
||||
RedriveService service =
|
||||
service(
|
||||
(messageId, target, redriveId) -> {
|
||||
republished.add(messageId);
|
||||
return confirmed();
|
||||
});
|
||||
|
||||
RedriveReport report =
|
||||
service.redrive(request(), approval(), "operator", NOW, 3, completed -> {});
|
||||
|
||||
assertThat(republished)
|
||||
.as("republishing a settled message is a duplicate, not a retry")
|
||||
.containsExactly(candidates.get(3), candidates.get(4));
|
||||
assertThat(report.moved()).isEqualTo(2);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("progress is reported after each item so a crash resumes near where it stopped")
|
||||
void progressIsReportedAfterEachItem() {
|
||||
source.stage(ids(3));
|
||||
List<Integer> checkpoints = new ArrayList<>();
|
||||
RedriveService service = service((messageId, target, redriveId) -> confirmed());
|
||||
|
||||
service.redrive(request(), approval(), "operator", NOW, 0, checkpoints::add);
|
||||
|
||||
assertThat(checkpoints).containsExactly(1, 2, 3);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("resuming past the end of the batch moves nothing")
|
||||
void resumingPastTheEndOfTheBatchMovesNothing() {
|
||||
source.stage(ids(2));
|
||||
RedriveService service = service((messageId, target, redriveId) -> confirmed());
|
||||
|
||||
RedriveReport report =
|
||||
service.redrive(request(), approval(), "operator", NOW, 10, completed -> {});
|
||||
|
||||
assertThat(report.moved()).isZero();
|
||||
}
|
||||
|
||||
private RedriveService service(RedriveService.RedrivePublisher publisher) {
|
||||
// The guard holds the admin credential and every pass carries a real verified approval: this
|
||||
// test is about the loop, and a gate that refused would prove nothing about it.
|
||||
return new RedriveService(new DestructiveOperationGuard(true), source, publisher, audit);
|
||||
}
|
||||
|
||||
private static Optional<VerifiedApproval> approval() {
|
||||
PlanDigest digest = PlanDigest.ofCanonical("REDRIVE|orders.v1.dlq|orders.v1");
|
||||
ApprovalGrant grant =
|
||||
new ApprovalGrant(
|
||||
new AdminApproval("CHG-1042", "ops@example.com", NOW, NOW.plus(Duration.ofHours(2))),
|
||||
"operator@example.com",
|
||||
DestructiveOperation.REDRIVE,
|
||||
DLQ,
|
||||
Optional.of(ORDERS),
|
||||
"v1",
|
||||
Long.MAX_VALUE,
|
||||
digest);
|
||||
return Optional.of(ISSUER.verify(grant, ISSUER.sign(grant), digest, NOW));
|
||||
}
|
||||
|
||||
private static RedriveRequest request() {
|
||||
return new RedriveRequest(UUID.randomUUID(), DLQ, ORDERS, 50, false);
|
||||
}
|
||||
|
||||
private static PublishResult confirmed() {
|
||||
return new PublishResult(
|
||||
PublishCompletion.CONFIRMED,
|
||||
PublishEvidence.confirmed(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK),
|
||||
RoutingOutcome.ROUTED,
|
||||
Optional.empty(),
|
||||
1,
|
||||
Duration.ofMillis(2),
|
||||
Optional.empty());
|
||||
}
|
||||
|
||||
private static List<MessageId> ids(int count) {
|
||||
List<MessageId> ids = new ArrayList<>();
|
||||
for (int index = 0; index < count; index++) {
|
||||
ids.add(MessageId.newId());
|
||||
}
|
||||
return List.copyOf(ids);
|
||||
}
|
||||
|
||||
private static final class RecordingSource implements RedriveService.RedriveSource {
|
||||
|
||||
private List<MessageId> staged = List.of();
|
||||
private final List<MessageId> settled = new ArrayList<>();
|
||||
|
||||
private void stage(List<MessageId> ids) {
|
||||
staged = List.copyOf(ids);
|
||||
}
|
||||
|
||||
@Override
|
||||
public List<MessageId> peek(DestinationName destination, int batchSize) {
|
||||
return staged;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void settle(DestinationName destination, MessageId messageId) {
|
||||
settled.add(messageId);
|
||||
}
|
||||
}
|
||||
|
||||
private static final class RecordingAudit implements RedriveService.AuditSink {
|
||||
|
||||
private final List<MessagingAuditEvent> events = new ArrayList<>();
|
||||
|
||||
@Override
|
||||
public void record(MessagingAuditEvent event) {
|
||||
events.add(event);
|
||||
}
|
||||
}
|
||||
}
|
||||
+77
@@ -0,0 +1,77 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.messaging.admin.DestructiveOperationGuard;
|
||||
import dev.caskeleton.messaging.admin.ReplayRequest;
|
||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.util.Optional;
|
||||
import java.util.UUID;
|
||||
import java.util.concurrent.atomic.AtomicInteger;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class ReplayServiceTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-09-21T00:00:00Z");
|
||||
private static final DestinationName DESTINATION = new DestinationName("orders.v1");
|
||||
|
||||
@Test
|
||||
void callerClaimedIsolationDoesNotBypassApprovalForARealReplay() {
|
||||
AtomicInteger executions = new AtomicInteger();
|
||||
ReplayService service =
|
||||
new ReplayService(
|
||||
new DestructiveOperationGuard(true),
|
||||
request -> {
|
||||
executions.incrementAndGet();
|
||||
return 1;
|
||||
},
|
||||
event -> {});
|
||||
|
||||
ReplayRequest request =
|
||||
new ReplayRequest(
|
||||
UUID.fromString("0199aaaa-bbbb-7ccc-8ddd-eeeeffff1000"),
|
||||
DESTINATION,
|
||||
NOW.minus(Duration.ofHours(1)),
|
||||
Optional.empty(),
|
||||
true,
|
||||
false);
|
||||
|
||||
assertThatThrownBy(() -> service.replay(request, Optional.empty(), "operator", NOW))
|
||||
.isInstanceOfSatisfying(
|
||||
MessageAuthorizationException.class,
|
||||
failure -> assertThat(failure.failure().code()).isEqualTo("APPROVAL_REQUIRED"));
|
||||
assertThat(executions).hasValue(0);
|
||||
}
|
||||
|
||||
@Test
|
||||
void dryRunRemainsApprovalFreeEvenWhenIsolationIsOnlyAnIntentFlag() {
|
||||
AtomicInteger executions = new AtomicInteger();
|
||||
ReplayService service =
|
||||
new ReplayService(
|
||||
new DestructiveOperationGuard(true),
|
||||
request -> {
|
||||
executions.incrementAndGet();
|
||||
return 1;
|
||||
},
|
||||
event -> {});
|
||||
|
||||
ReplayRequest request =
|
||||
new ReplayRequest(
|
||||
UUID.fromString("0199aaaa-bbbb-7ccc-8ddd-eeeeffff1001"),
|
||||
DESTINATION,
|
||||
NOW.minus(Duration.ofHours(1)),
|
||||
Optional.empty(),
|
||||
true,
|
||||
true);
|
||||
|
||||
ReplayReport report = service.replay(request, Optional.empty(), "operator", NOW);
|
||||
|
||||
assertThat(report.dryRun()).isTrue();
|
||||
assertThat(report.replayed()).isZero();
|
||||
assertThat(executions).hasValue(0);
|
||||
}
|
||||
}
|
||||
+65
@@ -0,0 +1,65 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThatCode;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.messaging.admin.TopologyManifest;
|
||||
import dev.caskeleton.messaging.api.error.MessageTopologyException;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class TopologyValidationRuntimeTest {
|
||||
|
||||
private static final TopologyManifest ORDERS =
|
||||
new TopologyManifest(
|
||||
"order-events", "order.events.v1", 6, 3, Map.of("min.insync.replicas", "2"));
|
||||
|
||||
@Test
|
||||
void aMatchingTopologyValidates() {
|
||||
TopologyValidationRuntime runtime =
|
||||
new TopologyValidationRuntime(
|
||||
name ->
|
||||
new TopologyValidationRuntime.ObservedTopology(
|
||||
6, 3, Map.of("min.insync.replicas", "2")));
|
||||
|
||||
assertThatCode(() -> runtime.validate(List.of(ORDERS))).doesNotThrowAnyException();
|
||||
}
|
||||
|
||||
@Test
|
||||
void aMissingDestinationFailsStartup() {
|
||||
TopologyValidationRuntime runtime = new TopologyValidationRuntime(name -> null);
|
||||
|
||||
assertThatThrownBy(() -> runtime.validate(List.of(ORDERS)))
|
||||
.isInstanceOf(MessageTopologyException.class)
|
||||
.hasMessageContaining("does not exist");
|
||||
}
|
||||
|
||||
@Test
|
||||
void aWeakenedReplicationSettingFailsStartup() {
|
||||
TopologyValidationRuntime runtime =
|
||||
new TopologyValidationRuntime(
|
||||
name ->
|
||||
new TopologyValidationRuntime.ObservedTopology(
|
||||
6, 3, Map.of("min.insync.replicas", "1")));
|
||||
|
||||
assertThatThrownBy(() -> runtime.validate(List.of(ORDERS)))
|
||||
.isInstanceOf(MessageTopologyException.class)
|
||||
.hasMessageContaining("min.insync.replicas");
|
||||
}
|
||||
|
||||
@Test
|
||||
void everyDifferenceIsReportedAtOnce() {
|
||||
TopologyValidationRuntime runtime =
|
||||
new TopologyValidationRuntime(
|
||||
name ->
|
||||
new TopologyValidationRuntime.ObservedTopology(
|
||||
3, 1, Map.of("min.insync.replicas", "1")));
|
||||
|
||||
assertThatThrownBy(() -> runtime.validate(List.of(ORDERS)))
|
||||
.isInstanceOf(MessageTopologyException.class)
|
||||
.hasMessageContaining("partitions")
|
||||
.hasMessageContaining("replicationFactor")
|
||||
.hasMessageContaining("min.insync.replicas");
|
||||
}
|
||||
}
|
||||
+172
@@ -0,0 +1,172 @@
|
||||
package dev.caskeleton.messaging.admin.runtime;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatCode;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.messaging.admin.DestinationTopology;
|
||||
import dev.caskeleton.messaging.admin.TopologyIssue;
|
||||
import dev.caskeleton.messaging.admin.TopologyManagementMode;
|
||||
import dev.caskeleton.messaging.admin.TopologyManifest;
|
||||
import dev.caskeleton.messaging.admin.TopologyValidationReport;
|
||||
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class TopologyValidatorTest {
|
||||
|
||||
private final TopologyValidator validator = new TopologyValidator();
|
||||
|
||||
private static TopologyManifest manifest() {
|
||||
return new TopologyManifest(
|
||||
"orders.v1", "orders-v1", 12, 3, Map.of("min.insync.replicas", "2"));
|
||||
}
|
||||
|
||||
private static DestinationTopology observed(
|
||||
int partitions, int replication, Map<String, String> config) {
|
||||
return new DestinationTopology("orders-v1", partitions, replication, config, true);
|
||||
}
|
||||
|
||||
@Test
|
||||
void anAgreeingTopologyProducesNoIssues() {
|
||||
assertThat(validator.compare(manifest(), observed(12, 3, Map.of("min.insync.replicas", "2"))))
|
||||
.isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
void anAbsentDestinationBlocksStartup() {
|
||||
List<TopologyIssue> issues =
|
||||
validator.compare(manifest(), DestinationTopology.absent("orders-v1"));
|
||||
|
||||
assertThat(issues)
|
||||
.singleElement()
|
||||
.satisfies(
|
||||
issue -> {
|
||||
assertThat(issue.attribute()).isEqualTo("existence");
|
||||
assertThat(issue.severity()).isEqualTo(TopologyIssue.Severity.BLOCKING);
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
void tooFewPartitionsBlocksBecauseKeysWouldLandDifferently() {
|
||||
List<TopologyIssue> issues =
|
||||
validator.compare(manifest(), observed(6, 3, Map.of("min.insync.replicas", "2")));
|
||||
|
||||
assertThat(issues)
|
||||
.singleElement()
|
||||
.satisfies(
|
||||
issue -> assertThat(issue.severity()).isEqualTo(TopologyIssue.Severity.BLOCKING));
|
||||
}
|
||||
|
||||
@Test
|
||||
void extraPartitionsAreAdvisoryBecauseScalingUpIsLegitimate() {
|
||||
List<TopologyIssue> issues =
|
||||
validator.compare(manifest(), observed(24, 3, Map.of("min.insync.replicas", "2")));
|
||||
|
||||
assertThat(issues)
|
||||
.singleElement()
|
||||
.satisfies(
|
||||
issue -> assertThat(issue.severity()).isEqualTo(TopologyIssue.Severity.ADVISORY));
|
||||
}
|
||||
|
||||
@Test
|
||||
void tooLittleReplicationBlocksBecauseDurabilityIsPromised() {
|
||||
List<TopologyIssue> issues =
|
||||
validator.compare(manifest(), observed(12, 1, Map.of("min.insync.replicas", "2")));
|
||||
|
||||
assertThat(issues)
|
||||
.singleElement()
|
||||
.satisfies(
|
||||
issue -> {
|
||||
assertThat(issue.attribute()).isEqualTo("replicationFactor");
|
||||
assertThat(issue.severity()).isEqualTo(TopologyIssue.Severity.BLOCKING);
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
void aMissingRequiredConfigurationEntryBlocks() {
|
||||
List<TopologyIssue> issues = validator.compare(manifest(), observed(12, 3, Map.of()));
|
||||
|
||||
assertThat(issues)
|
||||
.singleElement()
|
||||
.satisfies(issue -> assertThat(issue.actual()).isEqualTo("unset"));
|
||||
}
|
||||
|
||||
@Test
|
||||
void everyIssueIsCollectedRatherThanFailingOnTheFirst() {
|
||||
List<TopologyIssue> issues = validator.compare(manifest(), observed(6, 1, Map.of()));
|
||||
|
||||
assertThat(issues)
|
||||
.as("discovering the next problem only after a redeploy turns one fix into several")
|
||||
.hasSize(3);
|
||||
}
|
||||
|
||||
@Test
|
||||
void aReportRefusesStartupWhenAnythingBlocks() {
|
||||
TopologyValidationReport report =
|
||||
new TopologyValidationReport(
|
||||
validator.compare(manifest(), observed(12, 1, Map.of("min.insync.replicas", "2"))), 1);
|
||||
|
||||
assertThat(report.isAcceptable()).isFalse();
|
||||
assertThatThrownBy(report::requireAcceptable)
|
||||
.isInstanceOf(MessagingConfigurationException.class)
|
||||
.hasMessageContaining("replicationFactor");
|
||||
}
|
||||
|
||||
@Test
|
||||
void anAdvisoryOnlyReportStillStarts() {
|
||||
TopologyValidationReport report =
|
||||
new TopologyValidationReport(
|
||||
validator.compare(manifest(), observed(24, 3, Map.of("min.insync.replicas", "2"))), 1);
|
||||
|
||||
assertThat(report.isAcceptable()).isTrue();
|
||||
assertThat(report.advisory()).hasSize(1);
|
||||
assertThatCode(report::requireAcceptable).doesNotThrowAnyException();
|
||||
}
|
||||
|
||||
@Test
|
||||
void theCompositeValidatorChecksEveryManifest() {
|
||||
CompositeTopologyValidator composite =
|
||||
new CompositeTopologyValidator(
|
||||
new BrokerTopologyInspector() {
|
||||
@Override
|
||||
public Optional<DestinationTopology> describe(String physicalName) {
|
||||
return Optional.empty();
|
||||
}
|
||||
|
||||
@Override
|
||||
public String topologyVersion() {
|
||||
return "v1";
|
||||
}
|
||||
});
|
||||
|
||||
TopologyValidationReport report =
|
||||
composite.validate(
|
||||
List.of(
|
||||
manifest(), new TopologyManifest("payments.v1", "payments-v1", 3, 3, Map.of())));
|
||||
|
||||
assertThat(report.destinationsChecked()).isEqualTo(2);
|
||||
assertThat(report.blocking()).hasSize(2);
|
||||
}
|
||||
|
||||
@Test
|
||||
void autoCreationIsRefusedInProduction() {
|
||||
assertThatThrownBy(() -> TopologyManagementMode.CREATE_IF_MISSING.requireSafeFor(true))
|
||||
.as("a mistyped destination would be created and look exactly like a real one")
|
||||
.isInstanceOf(MessagingConfigurationException.class);
|
||||
}
|
||||
|
||||
@Test
|
||||
void autoCreationIsAllowedOutsideProduction() {
|
||||
assertThatCode(() -> TopologyManagementMode.CREATE_IF_MISSING.requireSafeFor(false))
|
||||
.doesNotThrowAnyException();
|
||||
}
|
||||
|
||||
@Test
|
||||
void validateOnlyIsAlwaysSafe() {
|
||||
assertThatCode(() -> TopologyManagementMode.VALIDATE_ONLY.requireSafeFor(true))
|
||||
.doesNotThrowAnyException();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
plugins {
|
||||
id 'ca.platform-module'
|
||||
}
|
||||
|
||||
dependencies {
|
||||
api project(':messaging:messaging-core-api')
|
||||
api project(':messaging:messaging-reliability-api')
|
||||
}
|
||||
@@ -0,0 +1,84 @@
|
||||
# This is a Gradle generated file for dependency locking.
|
||||
# Manual edits can break the build and are not advised.
|
||||
# This file is expected to be part of source control.
|
||||
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
|
||||
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
|
||||
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
|
||||
com.github.spotbugs:spotbugs:4.10.2=spotbugs
|
||||
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
|
||||
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
|
||||
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
|
||||
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
|
||||
com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs
|
||||
com.google.code.gson:gson:2.13.2=spotbugs
|
||||
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
|
||||
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
|
||||
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:guava:33.6.0-jre=checkstyle
|
||||
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
|
||||
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
|
||||
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
|
||||
commons-beanutils:commons-beanutils:1.11.0=checkstyle
|
||||
commons-collections:commons-collections:3.2.2=checkstyle
|
||||
commons-io:commons-io:2.21.0=spotbugs
|
||||
info.picocli:picocli:4.7.7=checkstyle
|
||||
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
|
||||
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
|
||||
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
|
||||
jaxen:jaxen:2.0.6=spotbugs
|
||||
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
|
||||
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
|
||||
org.antlr:antlr4-runtime:4.13.2=checkstyle
|
||||
org.apache.bcel:bcel:6.12.0=spotbugs
|
||||
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
|
||||
org.apache.commons:commons-text:1.15.0=spotbugs
|
||||
org.apache.commons:commons-text:1.3=checkstyle
|
||||
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
|
||||
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
|
||||
org.apache.logging.log4j:log4j-api:2.25.5=spotbugs
|
||||
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
|
||||
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
|
||||
org.apache.xbean:xbean-reflect:3.7=checkstyle
|
||||
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
|
||||
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
|
||||
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
|
||||
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
|
||||
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
|
||||
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
|
||||
org.dom4j:dom4j:2.2.0=spotbugs
|
||||
org.javassist:javassist:3.28.0-GA=checkstyle
|
||||
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
|
||||
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
|
||||
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit:junit-bom:6.1.0=spotbugs
|
||||
org.mockito:mockito-core:5.20.0=mockitoAgent
|
||||
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
|
||||
org.ow2.asm:asm-analysis:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-commons:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-tree:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-util:9.10.1=spotbugs
|
||||
org.ow2.asm:asm:9.10.1=spotbugs
|
||||
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
|
||||
org.reflections:reflections:0.10.2=checkstyle
|
||||
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.18=checkstyle
|
||||
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
|
||||
empty=compileClasspath,runtimeClasspath
|
||||
+44
@@ -0,0 +1,44 @@
|
||||
package dev.caskeleton.messaging.claimcheck;
|
||||
|
||||
import dev.caskeleton.messaging.api.error.FailureCategory;
|
||||
import dev.caskeleton.messaging.api.error.FailureDescriptor;
|
||||
import dev.caskeleton.messaging.api.error.MessagingException;
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* The stored payload does not match the reference the message carried.
|
||||
*
|
||||
* <p>Not retryable. A digest mismatch means the object at that key is not the object the producer
|
||||
* wrote — the key was reused, the object was overwritten, or something truncated it — and fetching
|
||||
* it again returns the same wrong bytes. Retrying would only delay the dead-letter.
|
||||
*
|
||||
* <p>Deliberately distinct from "the object is gone". An expired claim check is an operational
|
||||
* problem with a known cause and a known fix; a digest mismatch means something wrote data nobody
|
||||
* expected, and the two must not be diagnosed as one.
|
||||
*/
|
||||
public class ClaimCheckIntegrityException extends MessagingException {
|
||||
|
||||
@Serial private static final long serialVersionUID = 1L;
|
||||
|
||||
private static final FailureCategory CATEGORY = FailureCategory.POISON_MESSAGE;
|
||||
|
||||
/**
|
||||
* Creates the exception with a stable code and sanitized message.
|
||||
*
|
||||
* @param code the stable failure code
|
||||
* @param sanitizedMessage the operator-facing description
|
||||
*/
|
||||
public ClaimCheckIntegrityException(String code, String sanitizedMessage) {
|
||||
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the exception from an explicit descriptor.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
*/
|
||||
public ClaimCheckIntegrityException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
+71
@@ -0,0 +1,71 @@
|
||||
package dev.caskeleton.messaging.claimcheck;
|
||||
|
||||
import dev.caskeleton.messaging.api.error.MessageValidationException;
|
||||
import dev.caskeleton.messaging.reliability.ClaimCheckReference;
|
||||
import java.security.MessageDigest;
|
||||
import java.security.NoSuchAlgorithmException;
|
||||
import java.time.Instant;
|
||||
import java.util.HexFormat;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Verifies a fetched claim check payload before it is handed to a codec.
|
||||
*
|
||||
* <p>A claim check turns one message into two systems that can drift. The payload store has its own
|
||||
* retention, its own replication, and its own access control, and none of them are coordinated with
|
||||
* the broker's. So a consumer that fetches bytes and decodes them without checking is trusting
|
||||
* something the message never proved.
|
||||
*
|
||||
* <p>Both checks fail closed. An expired reference is reported before the fetch, because a
|
||||
* not-found from the store is ambiguous between "reaped" and "never written". A digest mismatch is
|
||||
* reported as validation rather than deserialization, because the bytes are not corrupt JSON — they
|
||||
* are the wrong bytes.
|
||||
*/
|
||||
public final class ClaimCheckIntegrityGuard {
|
||||
|
||||
/**
|
||||
* Verifies a payload against its reference.
|
||||
*
|
||||
* @param reference the claim check reference
|
||||
* @param payload the bytes fetched from the store
|
||||
* @param now the current instant
|
||||
* @return the verified payload
|
||||
* @throws MessageValidationException when the reference expired or the digest does not match
|
||||
*/
|
||||
public byte[] verify(ClaimCheckReference reference, byte[] payload, Instant now) {
|
||||
Objects.requireNonNull(reference, "reference must not be null");
|
||||
Objects.requireNonNull(payload, "payload must not be null");
|
||||
Objects.requireNonNull(now, "now must not be null");
|
||||
|
||||
if (reference.isExpired(now)) {
|
||||
throw new MessageValidationException(
|
||||
"CLAIM_CHECK_EXPIRED",
|
||||
"the claim check payload retention expired at " + reference.expiresAt());
|
||||
}
|
||||
if (payload.length != reference.sizeBytes()) {
|
||||
throw new MessageValidationException(
|
||||
"CLAIM_CHECK_SIZE_MISMATCH",
|
||||
"expected " + reference.sizeBytes() + " bytes but read " + payload.length);
|
||||
}
|
||||
String actual = sha256(payload);
|
||||
if (!actual.equals(reference.sha256())) {
|
||||
throw new MessageValidationException(
|
||||
"CLAIM_CHECK_DIGEST_MISMATCH", "the fetched payload does not match its reference digest");
|
||||
}
|
||||
return payload.clone();
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the lowercase hex SHA-256 of a payload.
|
||||
*
|
||||
* @param payload the bytes to digest
|
||||
* @return the digest
|
||||
*/
|
||||
public static String sha256(byte[] payload) {
|
||||
try {
|
||||
return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(payload));
|
||||
} catch (NoSuchAlgorithmException exception) {
|
||||
throw new IllegalStateException("Java runtime does not provide SHA-256", exception);
|
||||
}
|
||||
}
|
||||
}
|
||||
+89
@@ -0,0 +1,89 @@
|
||||
package dev.caskeleton.messaging.claimcheck;
|
||||
|
||||
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
|
||||
import java.time.Duration;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* When a payload is offloaded, and how long the object must outlive the message.
|
||||
*
|
||||
* <p>The retention rule is the one that matters. A claim check object deleted while its message is
|
||||
* still deliverable turns a large message into an undeliverable one — the consumer fetches, gets
|
||||
* nothing, and the message dead-letters for a reason that has nothing to do with the message. So
|
||||
* retention must exceed the broker's own retention plus the full retry and dead-letter window, and
|
||||
* the constructor refuses a configuration where it does not.
|
||||
*
|
||||
* <p>The threshold is separate from the destination's payload limit. Offloading starts well below
|
||||
* the limit, because the limit is where the broker refuses the message and the threshold is where
|
||||
* carrying it inline stops being a good idea.
|
||||
*
|
||||
* @param thresholdBytes the encoded size above which a payload is offloaded
|
||||
* @param retention how long the stored object must remain readable
|
||||
* @param brokerRetention how long the broker keeps the message
|
||||
* @param maxRedeliveryWindow the longest retry and dead-letter path a message can take
|
||||
*/
|
||||
public record ClaimCheckPolicy(
|
||||
int thresholdBytes,
|
||||
Duration retention,
|
||||
Duration brokerRetention,
|
||||
Duration maxRedeliveryWindow) {
|
||||
|
||||
/** The default offload threshold: a quarter of the portable payload limit. */
|
||||
public static final int DEFAULT_THRESHOLD_BYTES = 262_144;
|
||||
|
||||
public ClaimCheckPolicy {
|
||||
Objects.requireNonNull(retention, "retention must not be null");
|
||||
Objects.requireNonNull(brokerRetention, "brokerRetention must not be null");
|
||||
Objects.requireNonNull(maxRedeliveryWindow, "maxRedeliveryWindow must not be null");
|
||||
if (thresholdBytes < 1) {
|
||||
throw new IllegalArgumentException("thresholdBytes must be positive");
|
||||
}
|
||||
requirePositive(retention, "retention");
|
||||
requirePositive(brokerRetention, "brokerRetention");
|
||||
requirePositive(maxRedeliveryWindow, "maxRedeliveryWindow");
|
||||
|
||||
Duration required = brokerRetention.plus(maxRedeliveryWindow);
|
||||
if (retention.compareTo(required) < 0) {
|
||||
throw new MessagingConfigurationException(
|
||||
"CLAIM_CHECK_RETENTION_TOO_SHORT",
|
||||
"claim check retention of %s is below the %s the message can remain deliverable; the "
|
||||
.formatted(retention, required)
|
||||
+ "object would be reaped while a consumer can still be handed its message");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a policy for a broker retaining one day with a one-day retry path.
|
||||
*
|
||||
* @return the default policy
|
||||
*/
|
||||
public static ClaimCheckPolicy defaults() {
|
||||
return new ClaimCheckPolicy(
|
||||
DEFAULT_THRESHOLD_BYTES, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1));
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether a payload of this size is offloaded.
|
||||
*
|
||||
* @param payloadBytes the encoded payload size
|
||||
* @return true when the payload travels by reference
|
||||
*/
|
||||
public boolean shouldOffload(int payloadBytes) {
|
||||
return payloadBytes > thresholdBytes;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the shortest retention this deployment allows.
|
||||
*
|
||||
* @return the minimum safe retention
|
||||
*/
|
||||
public Duration requiredRetention() {
|
||||
return brokerRetention.plus(maxRedeliveryWindow);
|
||||
}
|
||||
|
||||
private static void requirePositive(Duration value, String field) {
|
||||
if (value.isNegative() || value.isZero()) {
|
||||
throw new IllegalArgumentException(field + " must be positive");
|
||||
}
|
||||
}
|
||||
}
|
||||
+91
@@ -0,0 +1,91 @@
|
||||
package dev.caskeleton.messaging.claimcheck;
|
||||
|
||||
import dev.caskeleton.messaging.reliability.ClaimCheckReference;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Decides whether a payload travels inline or by reference, and stores it when it does not.
|
||||
*
|
||||
* <p>The object is written <em>before</em> the message is published, and that order is the whole
|
||||
* design. Publishing first would let a consumer receive a reference to an object that does not
|
||||
* exist yet — a race that is rare in a test and routine under load, because the broker hop is
|
||||
* faster than the object store write.
|
||||
*
|
||||
* <p>Nothing here deletes on failure. If the publish is rejected the object is left behind, and the
|
||||
* retention sweep reclaims it; deleting eagerly would delete the object out from under a publish
|
||||
* that turned out to be ambiguous rather than rejected.
|
||||
*/
|
||||
public final class ClaimCheckPublisher {
|
||||
|
||||
private final ClaimCheckStore store;
|
||||
private final ClaimCheckPolicy policy;
|
||||
|
||||
/**
|
||||
* Creates a claim check publisher.
|
||||
*
|
||||
* @param store the payload store
|
||||
* @param policy the offload threshold and retention
|
||||
*/
|
||||
public ClaimCheckPublisher(ClaimCheckStore store, ClaimCheckPolicy policy) {
|
||||
this.store = Objects.requireNonNull(store, "store must not be null");
|
||||
this.policy = Objects.requireNonNull(policy, "policy must not be null");
|
||||
}
|
||||
|
||||
/**
|
||||
* Offloads a payload when the policy calls for it.
|
||||
*
|
||||
* @param payload the encoded payload bytes
|
||||
* @return the outcome, carrying either the inline payload or the stored reference
|
||||
*/
|
||||
public Offloaded offload(byte[] payload) {
|
||||
Objects.requireNonNull(payload, "payload must not be null");
|
||||
|
||||
if (!policy.shouldOffload(payload.length)) {
|
||||
return new Offloaded(payload.clone(), Optional.empty());
|
||||
}
|
||||
ClaimCheckReference reference = store.put(payload, policy.retention());
|
||||
// The published message carries no payload bytes at all, only the reference. Carrying both
|
||||
// would double the transfer for no benefit and let the two disagree.
|
||||
return new Offloaded(new byte[0], Optional.of(reference));
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the policy this publisher applies.
|
||||
*
|
||||
* @return the claim check policy
|
||||
*/
|
||||
public ClaimCheckPolicy policy() {
|
||||
return policy;
|
||||
}
|
||||
|
||||
/**
|
||||
* What a payload became after the offload decision.
|
||||
*
|
||||
* @param payload the payload to publish, empty when offloaded
|
||||
* @param reference the stored object's reference, present when offloaded
|
||||
*/
|
||||
@SuppressWarnings("ArrayRecordComponent")
|
||||
public record Offloaded(byte[] payload, Optional<ClaimCheckReference> reference) {
|
||||
|
||||
public Offloaded {
|
||||
Objects.requireNonNull(payload, "payload must not be null");
|
||||
Objects.requireNonNull(reference, "reference must not be null");
|
||||
payload = payload.clone();
|
||||
}
|
||||
|
||||
@Override
|
||||
public byte[] payload() {
|
||||
return payload.clone();
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether the payload travels by reference.
|
||||
*
|
||||
* @return true when the payload was offloaded
|
||||
*/
|
||||
public boolean isOffloaded() {
|
||||
return reference.isPresent();
|
||||
}
|
||||
}
|
||||
}
|
||||
+91
@@ -0,0 +1,91 @@
|
||||
package dev.caskeleton.messaging.claimcheck;
|
||||
|
||||
import dev.caskeleton.messaging.api.error.MessageValidationException;
|
||||
import dev.caskeleton.messaging.reliability.ClaimCheckReference;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Fetches an offloaded payload and verifies it before a handler ever sees it.
|
||||
*
|
||||
* <p>Verification is not optional and cannot be skipped by a caller. An object store key is a
|
||||
* string, and a message carrying the wrong one — through a bug, a replay against a rotated bucket,
|
||||
* or a deliberate tamper — fetches bytes that decode perfectly into the wrong object. The digest is
|
||||
* the only thing standing between that and a handler acting on someone else's data.
|
||||
*
|
||||
* <p>Failures are classified rather than merged. An expired reference is an operational problem
|
||||
* whose fix is a retention change; a digest mismatch means something wrote data nobody expected.
|
||||
* Both dead-letter the message, but an operator seeing one code should not have to guess which
|
||||
* happened.
|
||||
*/
|
||||
public final class ClaimCheckResolver {
|
||||
|
||||
private final ClaimCheckStore store;
|
||||
private final ClaimCheckIntegrityGuard guard = new ClaimCheckIntegrityGuard();
|
||||
|
||||
/**
|
||||
* Creates a resolver.
|
||||
*
|
||||
* @param store the payload store
|
||||
*/
|
||||
public ClaimCheckResolver(ClaimCheckStore store) {
|
||||
this.store = Objects.requireNonNull(store, "store must not be null");
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the payload a message carries, fetching it when it travels by reference.
|
||||
*
|
||||
* @param inline the payload bytes the message carried, empty when it travels by reference
|
||||
* @param reference the claim check reference, when the message carried one
|
||||
* @param now the current instant
|
||||
* @return the payload the handler should see
|
||||
* @throws ClaimCheckIntegrityException when the stored object is not the one referenced
|
||||
* @throws MessageValidationException when the reference has expired
|
||||
*/
|
||||
public byte[] resolve(byte[] inline, Optional<ClaimCheckReference> reference, Instant now) {
|
||||
Objects.requireNonNull(inline, "inline must not be null");
|
||||
Objects.requireNonNull(reference, "reference must not be null");
|
||||
Objects.requireNonNull(now, "now must not be null");
|
||||
|
||||
if (reference.isEmpty()) {
|
||||
return inline.clone();
|
||||
}
|
||||
ClaimCheckReference claimCheck = reference.get();
|
||||
|
||||
if (claimCheck.isExpired(now)) {
|
||||
// Checked before fetching. A store that still returns the object past its retention would
|
||||
// otherwise hide a misconfiguration until the day the sweep caught up.
|
||||
throw new MessageValidationException(
|
||||
"CLAIM_CHECK_EXPIRED",
|
||||
"the claim check retention expired at %s; the object may already be reaped"
|
||||
.formatted(claimCheck.expiresAt()));
|
||||
}
|
||||
|
||||
return verify(claimCheck, fetch(claimCheck), now);
|
||||
}
|
||||
|
||||
private byte[] fetch(ClaimCheckReference reference) {
|
||||
byte[] fetched = store.get(reference);
|
||||
if (fetched == null) {
|
||||
throw new MessageValidationException(
|
||||
"CLAIM_CHECK_NOT_FOUND",
|
||||
"no object exists at the referenced key; it was either reaped early or never written");
|
||||
}
|
||||
return fetched;
|
||||
}
|
||||
|
||||
private byte[] verify(ClaimCheckReference reference, byte[] fetched, Instant now) {
|
||||
try {
|
||||
return guard.verify(reference, fetched, now);
|
||||
} catch (MessageValidationException validation) {
|
||||
// A size or digest mismatch is a poison message, not a validation failure to be retried:
|
||||
// fetching the same key again returns the same wrong bytes.
|
||||
if (validation.failure().code().endsWith("_MISMATCH")) {
|
||||
throw new ClaimCheckIntegrityException(
|
||||
validation.failure().code(), validation.failure().sanitizedMessage());
|
||||
}
|
||||
throw validation;
|
||||
}
|
||||
}
|
||||
}
|
||||
+32
@@ -0,0 +1,32 @@
|
||||
package dev.caskeleton.messaging.claimcheck;
|
||||
|
||||
import dev.caskeleton.messaging.reliability.ClaimCheckReference;
|
||||
import java.time.Duration;
|
||||
|
||||
/** Stores and retrieves payloads that are too large to travel through the broker. */
|
||||
public interface ClaimCheckStore {
|
||||
|
||||
/**
|
||||
* Stores a payload and returns its reference.
|
||||
*
|
||||
* @param payload the bytes to store
|
||||
* @param retention how long the object must remain readable
|
||||
* @return the reference to publish in place of the payload
|
||||
*/
|
||||
ClaimCheckReference put(byte[] payload, Duration retention);
|
||||
|
||||
/**
|
||||
* Fetches a payload, verifying it against its reference.
|
||||
*
|
||||
* @param reference the claim check reference
|
||||
* @return the stored bytes
|
||||
*/
|
||||
byte[] get(ClaimCheckReference reference);
|
||||
|
||||
/**
|
||||
* Deletes a stored payload.
|
||||
*
|
||||
* @param reference the claim check reference
|
||||
*/
|
||||
void delete(ClaimCheckReference reference);
|
||||
}
|
||||
+86
@@ -0,0 +1,86 @@
|
||||
package dev.caskeleton.messaging.claimcheck;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatCode;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.messaging.api.error.MessageValidationException;
|
||||
import dev.caskeleton.messaging.reliability.ClaimCheckReference;
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.time.Instant;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class ClaimCheckIntegrityGuardTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
|
||||
private static final byte[] PAYLOAD = "a large document".getBytes(StandardCharsets.UTF_8);
|
||||
|
||||
private final ClaimCheckIntegrityGuard guard = new ClaimCheckIntegrityGuard();
|
||||
|
||||
@Test
|
||||
void acceptsAPayloadMatchingItsReference() {
|
||||
ClaimCheckReference reference =
|
||||
reference(PAYLOAD.length, ClaimCheckIntegrityGuard.sha256(PAYLOAD));
|
||||
|
||||
assertThat(guard.verify(reference, PAYLOAD, NOW)).isEqualTo(PAYLOAD);
|
||||
}
|
||||
|
||||
@Test
|
||||
void rejectsAPayloadWhoseDigestDoesNotMatch() {
|
||||
ClaimCheckReference reference =
|
||||
reference(
|
||||
PAYLOAD.length,
|
||||
ClaimCheckIntegrityGuard.sha256(
|
||||
"a different document".getBytes(StandardCharsets.UTF_8)));
|
||||
|
||||
assertThatThrownBy(() -> guard.verify(reference, PAYLOAD, NOW))
|
||||
.isInstanceOf(MessageValidationException.class)
|
||||
.hasMessageContaining("digest");
|
||||
}
|
||||
|
||||
@Test
|
||||
void rejectsATruncatedPayloadBeforeHashingIt() {
|
||||
ClaimCheckReference reference =
|
||||
reference(PAYLOAD.length + 10, ClaimCheckIntegrityGuard.sha256(PAYLOAD));
|
||||
|
||||
assertThatThrownBy(() -> guard.verify(reference, PAYLOAD, NOW))
|
||||
.isInstanceOf(MessageValidationException.class)
|
||||
.hasMessageContaining("bytes");
|
||||
}
|
||||
|
||||
@Test
|
||||
void rejectsAnExpiredReferenceBeforeTheFetchIsTrusted() {
|
||||
ClaimCheckReference reference =
|
||||
new ClaimCheckReference(
|
||||
"payloads/o-1",
|
||||
PAYLOAD.length,
|
||||
ClaimCheckIntegrityGuard.sha256(PAYLOAD),
|
||||
NOW.minusSeconds(1));
|
||||
|
||||
assertThatThrownBy(() -> guard.verify(reference, PAYLOAD, NOW))
|
||||
.isInstanceOf(MessageValidationException.class)
|
||||
.hasMessageContaining("retention");
|
||||
}
|
||||
|
||||
@Test
|
||||
void aReferenceRequiresALowercaseHexDigest() {
|
||||
assertThatThrownBy(
|
||||
() -> new ClaimCheckReference("payloads/o-1", 5, "NOT-A-DIGEST", NOW.plusSeconds(60)))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
}
|
||||
|
||||
@Test
|
||||
void theVerifiedPayloadIsACopy() {
|
||||
ClaimCheckReference reference =
|
||||
reference(PAYLOAD.length, ClaimCheckIntegrityGuard.sha256(PAYLOAD));
|
||||
|
||||
byte[] verified = guard.verify(reference, PAYLOAD, NOW);
|
||||
verified[0] = 'z';
|
||||
|
||||
assertThatCode(() -> guard.verify(reference, PAYLOAD, NOW)).doesNotThrowAnyException();
|
||||
}
|
||||
|
||||
private static ClaimCheckReference reference(long sizeBytes, String sha256) {
|
||||
return new ClaimCheckReference("payloads/o-1", sizeBytes, sha256, NOW.plusSeconds(3600));
|
||||
}
|
||||
}
|
||||
+168
@@ -0,0 +1,168 @@
|
||||
package dev.caskeleton.messaging.claimcheck;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.messaging.api.error.MessageValidationException;
|
||||
import dev.caskeleton.messaging.reliability.ClaimCheckReference;
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.util.HashMap;
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class ClaimCheckResolverTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
|
||||
private static final byte[] PAYLOAD = "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8);
|
||||
|
||||
/** An in-memory store that can be made to return the wrong bytes on purpose. */
|
||||
private static final class FakeStore implements ClaimCheckStore {
|
||||
|
||||
private final Map<String, byte[]> objects = new HashMap<>();
|
||||
private int puts;
|
||||
|
||||
@Override
|
||||
public ClaimCheckReference put(byte[] payload, Duration retention) {
|
||||
puts++;
|
||||
String key = "claim/" + puts;
|
||||
objects.put(key, payload.clone());
|
||||
return new ClaimCheckReference(
|
||||
key, payload.length, ClaimCheckIntegrityGuard.sha256(payload), NOW.plus(retention));
|
||||
}
|
||||
|
||||
@Override
|
||||
public byte[] get(ClaimCheckReference reference) {
|
||||
return objects.get(reference.storageKey());
|
||||
}
|
||||
|
||||
@Override
|
||||
public void delete(ClaimCheckReference reference) {
|
||||
objects.remove(reference.storageKey());
|
||||
}
|
||||
|
||||
void overwrite(String key, byte[] replacement) {
|
||||
objects.put(key, replacement);
|
||||
}
|
||||
|
||||
int puts() {
|
||||
return puts;
|
||||
}
|
||||
}
|
||||
|
||||
private static byte[] filled(int size) {
|
||||
byte[] payload = new byte[size];
|
||||
java.util.Arrays.fill(payload, (byte) 'x');
|
||||
return payload;
|
||||
}
|
||||
|
||||
@Test
|
||||
void aSmallPayloadTravelsInlineAndIsNeverStored() {
|
||||
FakeStore store = new FakeStore();
|
||||
ClaimCheckPublisher publisher = new ClaimCheckPublisher(store, ClaimCheckPolicy.defaults());
|
||||
|
||||
ClaimCheckPublisher.Offloaded offloaded = publisher.offload(PAYLOAD);
|
||||
|
||||
assertThat(offloaded.isOffloaded()).isFalse();
|
||||
assertThat(store.puts()).isZero();
|
||||
}
|
||||
|
||||
@Test
|
||||
void aLargePayloadIsStoredAndTheMessageCarriesNoBytes() {
|
||||
FakeStore store = new FakeStore();
|
||||
ClaimCheckPublisher publisher = new ClaimCheckPublisher(store, ClaimCheckPolicy.defaults());
|
||||
|
||||
ClaimCheckPublisher.Offloaded offloaded =
|
||||
publisher.offload(filled(ClaimCheckPolicy.DEFAULT_THRESHOLD_BYTES + 1));
|
||||
|
||||
assertThat(offloaded.isOffloaded()).isTrue();
|
||||
assertThat(offloaded.payload().length)
|
||||
.as("carrying both would double the transfer and let the two disagree")
|
||||
.isZero();
|
||||
}
|
||||
|
||||
@Test
|
||||
void anOffloadedPayloadRoundTripsThroughTheStore() {
|
||||
FakeStore store = new FakeStore();
|
||||
ClaimCheckPolicy policy =
|
||||
new ClaimCheckPolicy(8, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1));
|
||||
ClaimCheckPublisher.Offloaded offloaded =
|
||||
new ClaimCheckPublisher(store, policy).offload(PAYLOAD);
|
||||
|
||||
byte[] resolved =
|
||||
new ClaimCheckResolver(store).resolve(offloaded.payload(), offloaded.reference(), NOW);
|
||||
|
||||
assertThat(resolved).isEqualTo(PAYLOAD);
|
||||
}
|
||||
|
||||
@Test
|
||||
void anInlinePayloadIsReturnedWithoutTouchingTheStore() {
|
||||
FakeStore store = new FakeStore();
|
||||
|
||||
byte[] resolved = new ClaimCheckResolver(store).resolve(PAYLOAD, Optional.empty(), NOW);
|
||||
|
||||
assertThat(resolved).isEqualTo(PAYLOAD);
|
||||
}
|
||||
|
||||
@Test
|
||||
void anObjectThatWasSwappedUnderTheReferenceIsAPoisonMessage() {
|
||||
FakeStore store = new FakeStore();
|
||||
ClaimCheckPolicy policy =
|
||||
new ClaimCheckPolicy(8, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1));
|
||||
ClaimCheckPublisher.Offloaded offloaded =
|
||||
new ClaimCheckPublisher(store, policy).offload(PAYLOAD);
|
||||
store.overwrite(
|
||||
offloaded.reference().orElseThrow().storageKey(),
|
||||
"{\"orderId\":\"SOMEONE-ELSE\"}".getBytes(StandardCharsets.UTF_8));
|
||||
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new ClaimCheckResolver(store)
|
||||
.resolve(offloaded.payload(), offloaded.reference(), NOW))
|
||||
.as("the digest is the only thing between a swapped object and the wrong data")
|
||||
.isInstanceOf(ClaimCheckIntegrityException.class);
|
||||
}
|
||||
|
||||
@Test
|
||||
void anIntegrityFailureIsNotRetryableBecauseTheKeyReturnsTheSameBytes() {
|
||||
ClaimCheckIntegrityException failure =
|
||||
new ClaimCheckIntegrityException("CLAIM_CHECK_DIGEST_MISMATCH", "swapped");
|
||||
|
||||
assertThat(failure.failure().retryable()).isFalse();
|
||||
}
|
||||
|
||||
@Test
|
||||
void amissingObjectIsReportedSeparatelyFromASwappedOne() {
|
||||
FakeStore store = new FakeStore();
|
||||
ClaimCheckPolicy policy =
|
||||
new ClaimCheckPolicy(8, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1));
|
||||
ClaimCheckPublisher.Offloaded offloaded =
|
||||
new ClaimCheckPublisher(store, policy).offload(PAYLOAD);
|
||||
store.delete(offloaded.reference().orElseThrow());
|
||||
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new ClaimCheckResolver(store)
|
||||
.resolve(offloaded.payload(), offloaded.reference(), NOW))
|
||||
.isInstanceOf(MessageValidationException.class)
|
||||
.hasMessageContaining("never written");
|
||||
}
|
||||
|
||||
@Test
|
||||
void anExpiredReferenceIsRefusedBeforeTheStoreIsEvenAsked() {
|
||||
FakeStore store = new FakeStore();
|
||||
ClaimCheckReference expired =
|
||||
new ClaimCheckReference(
|
||||
"claim/1",
|
||||
PAYLOAD.length,
|
||||
ClaimCheckIntegrityGuard.sha256(PAYLOAD),
|
||||
NOW.minus(Duration.ofHours(1)));
|
||||
|
||||
assertThatThrownBy(
|
||||
() -> new ClaimCheckResolver(store).resolve(new byte[0], Optional.of(expired), NOW))
|
||||
.isInstanceOf(MessageValidationException.class)
|
||||
.hasMessageContaining("expired");
|
||||
}
|
||||
}
|
||||
+79
@@ -0,0 +1,79 @@
|
||||
package dev.caskeleton.messaging.claimcheck;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatCode;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
|
||||
import java.time.Duration;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class ClaimCheckRetentionValidatorTest {
|
||||
|
||||
@Test
|
||||
void retentionShorterThanTheMessageLifetimeIsRefused() {
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new ClaimCheckPolicy(
|
||||
1024, Duration.ofHours(6), Duration.ofDays(1), Duration.ofDays(1)))
|
||||
.as("the object would be reaped while a consumer can still be handed its message")
|
||||
.isInstanceOf(MessagingConfigurationException.class)
|
||||
.hasMessageContaining("reaped");
|
||||
}
|
||||
|
||||
@Test
|
||||
void retentionCoveringBrokerRetentionPlusTheRetryPathIsAccepted() {
|
||||
assertThatCode(
|
||||
() ->
|
||||
new ClaimCheckPolicy(
|
||||
1024, Duration.ofDays(2), Duration.ofDays(1), Duration.ofDays(1)))
|
||||
.doesNotThrowAnyException();
|
||||
}
|
||||
|
||||
@Test
|
||||
void theRequiredRetentionIsBrokerRetentionPlusTheRedeliveryWindow() {
|
||||
ClaimCheckPolicy policy =
|
||||
new ClaimCheckPolicy(1024, Duration.ofDays(5), Duration.ofDays(2), Duration.ofDays(1));
|
||||
|
||||
assertThat(policy.requiredRetention()).isEqualTo(Duration.ofDays(3));
|
||||
}
|
||||
|
||||
@Test
|
||||
void theDefaultsSatisfyTheirOwnRule() {
|
||||
assertThatCode(ClaimCheckPolicy::defaults).doesNotThrowAnyException();
|
||||
}
|
||||
|
||||
/** The portable payload limit the platform documents, restated here so the two cannot drift. */
|
||||
private static final int PORTABLE_PAYLOAD_LIMIT_BYTES = 1_048_576;
|
||||
|
||||
@Test
|
||||
void theOffloadThresholdSitsWellBelowThePortablePayloadLimit() {
|
||||
assertThat(ClaimCheckPolicy.DEFAULT_THRESHOLD_BYTES)
|
||||
.as(
|
||||
"offloading starts where carrying inline stops being wise, not where the broker refuses")
|
||||
.isLessThan(PORTABLE_PAYLOAD_LIMIT_BYTES);
|
||||
}
|
||||
|
||||
@Test
|
||||
void aPayloadAtTheThresholdStillTravelsInline() {
|
||||
ClaimCheckPolicy policy = ClaimCheckPolicy.defaults();
|
||||
|
||||
assertThat(policy.shouldOffload(ClaimCheckPolicy.DEFAULT_THRESHOLD_BYTES)).isFalse();
|
||||
assertThat(policy.shouldOffload(ClaimCheckPolicy.DEFAULT_THRESHOLD_BYTES + 1)).isTrue();
|
||||
}
|
||||
|
||||
@Test
|
||||
void aNonPositiveDurationIsRefused() {
|
||||
assertThatThrownBy(
|
||||
() -> new ClaimCheckPolicy(1024, Duration.ZERO, Duration.ofDays(1), Duration.ofDays(1)))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
}
|
||||
|
||||
@Test
|
||||
void aNonPositiveThresholdIsRefused() {
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new ClaimCheckPolicy(0, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1)))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,16 @@
|
||||
plugins {
|
||||
id 'ca.platform-module'
|
||||
}
|
||||
|
||||
dependencies {
|
||||
api project(':messaging:messaging-core-api')
|
||||
|
||||
// api, because CloudEventMapper's public signatures return io.cloudevents.CloudEvent.
|
||||
//
|
||||
// Declared `implementation`, the type appeared in this module's public API while the
|
||||
// dependency was hidden from consumers: an adopter calling the documented method could not
|
||||
// name its return type without adding CloudEvents to their own build, and Gradle gave them no
|
||||
// hint why. A type in a public signature is part of the artifact's contract.
|
||||
api libs.cloudevents.api
|
||||
implementation libs.cloudevents.core
|
||||
}
|
||||
@@ -0,0 +1,86 @@
|
||||
# This is a Gradle generated file for dependency locking.
|
||||
# Manual edits can break the build and are not advised.
|
||||
# This file is expected to be part of source control.
|
||||
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
|
||||
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
|
||||
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
|
||||
com.github.spotbugs:spotbugs:4.10.2=spotbugs
|
||||
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
|
||||
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
|
||||
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
|
||||
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
|
||||
com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs
|
||||
com.google.code.gson:gson:2.13.2=spotbugs
|
||||
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
|
||||
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
|
||||
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:guava:33.6.0-jre=checkstyle
|
||||
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
|
||||
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
|
||||
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
|
||||
commons-beanutils:commons-beanutils:1.11.0=checkstyle
|
||||
commons-collections:commons-collections:3.2.2=checkstyle
|
||||
commons-io:commons-io:2.21.0=spotbugs
|
||||
info.picocli:picocli:4.7.7=checkstyle
|
||||
io.cloudevents:cloudevents-api:4.0.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
io.cloudevents:cloudevents-core:4.0.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
|
||||
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
|
||||
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
|
||||
jaxen:jaxen:2.0.6=spotbugs
|
||||
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
|
||||
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
|
||||
org.antlr:antlr4-runtime:4.13.2=checkstyle
|
||||
org.apache.bcel:bcel:6.12.0=spotbugs
|
||||
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
|
||||
org.apache.commons:commons-text:1.15.0=spotbugs
|
||||
org.apache.commons:commons-text:1.3=checkstyle
|
||||
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
|
||||
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
|
||||
org.apache.logging.log4j:log4j-api:2.25.5=spotbugs
|
||||
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
|
||||
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
|
||||
org.apache.xbean:xbean-reflect:3.7=checkstyle
|
||||
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
|
||||
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
|
||||
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
|
||||
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
|
||||
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
|
||||
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
|
||||
org.dom4j:dom4j:2.2.0=spotbugs
|
||||
org.javassist:javassist:3.28.0-GA=checkstyle
|
||||
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
|
||||
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
|
||||
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit:junit-bom:6.1.0=spotbugs
|
||||
org.mockito:mockito-core:5.20.0=mockitoAgent
|
||||
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
|
||||
org.ow2.asm:asm-analysis:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-commons:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-tree:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-util:9.10.1=spotbugs
|
||||
org.ow2.asm:asm:9.10.1=spotbugs
|
||||
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
|
||||
org.reflections:reflections:0.10.2=checkstyle
|
||||
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.18=checkstyle
|
||||
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
|
||||
empty=
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
package dev.caskeleton.messaging.cloudevents;
|
||||
|
||||
/**
|
||||
* The CloudEvents extension attribute names this profile writes.
|
||||
*
|
||||
* <p>CloudEvents requires extension names to be lowercase alphanumeric, which is why these are not
|
||||
* simply the envelope field names.
|
||||
*/
|
||||
public final class CloudEventExtensions {
|
||||
|
||||
/** Carries the envelope's correlation id. */
|
||||
public static final String CORRELATION_ID = "correlationid";
|
||||
|
||||
/** Carries the envelope's causation id. */
|
||||
public static final String CAUSATION_ID = "causationid";
|
||||
|
||||
/** Carries the envelope's schema version. */
|
||||
public static final String SCHEMA_VERSION = "schemaversion";
|
||||
|
||||
/** Carries the envelope's tenant identity. */
|
||||
public static final String TENANT_CONTEXT = "tenantcontext";
|
||||
|
||||
private CloudEventExtensions() {}
|
||||
}
|
||||
+33
@@ -0,0 +1,33 @@
|
||||
package dev.caskeleton.messaging.cloudevents;
|
||||
|
||||
import dev.caskeleton.messaging.api.MessageEnvelope;
|
||||
import dev.caskeleton.messaging.schema.EncodedMessage;
|
||||
import io.cloudevents.CloudEvent;
|
||||
import java.net.URI;
|
||||
|
||||
/**
|
||||
* Maps between the platform envelope and CloudEvents 1.0.2.
|
||||
*
|
||||
* <p>Offered for domain and integration events only. Commands and work items are not forced through
|
||||
* CloudEvents: they are internal contracts where the interoperability the specification buys does
|
||||
* not pay for the attributes it requires.
|
||||
*/
|
||||
public interface CloudEventMapper {
|
||||
|
||||
/**
|
||||
* Converts an envelope to a CloudEvent.
|
||||
*
|
||||
* @param envelope the envelope carrying an already-encoded payload
|
||||
* @param source the event source URI
|
||||
* @return the CloudEvent
|
||||
*/
|
||||
CloudEvent toCloudEvent(MessageEnvelope<?> envelope, URI source);
|
||||
|
||||
/**
|
||||
* Converts a CloudEvent back to an envelope.
|
||||
*
|
||||
* @param event the CloudEvent
|
||||
* @return an envelope whose payload is the still-encoded data
|
||||
*/
|
||||
MessageEnvelope<EncodedMessage> fromCloudEvent(CloudEvent event);
|
||||
}
|
||||
+171
@@ -0,0 +1,171 @@
|
||||
package dev.caskeleton.messaging.cloudevents;
|
||||
|
||||
import dev.caskeleton.messaging.api.CausationId;
|
||||
import dev.caskeleton.messaging.api.ContentType;
|
||||
import dev.caskeleton.messaging.api.CorrelationId;
|
||||
import dev.caskeleton.messaging.api.MessageEnvelope;
|
||||
import dev.caskeleton.messaging.api.MessageId;
|
||||
import dev.caskeleton.messaging.api.MessageType;
|
||||
import dev.caskeleton.messaging.api.ProducerId;
|
||||
import dev.caskeleton.messaging.api.SchemaVersion;
|
||||
import dev.caskeleton.messaging.api.TenantContext;
|
||||
import dev.caskeleton.messaging.api.TraceContext;
|
||||
import dev.caskeleton.messaging.api.error.MessageValidationException;
|
||||
import dev.caskeleton.messaging.api.header.MessageHeaders;
|
||||
import dev.caskeleton.messaging.schema.EncodedMessage;
|
||||
import io.cloudevents.CloudEvent;
|
||||
import io.cloudevents.CloudEventData;
|
||||
import io.cloudevents.core.builder.CloudEventBuilder;
|
||||
import io.cloudevents.core.data.BytesCloudEventData;
|
||||
import java.net.URI;
|
||||
import java.time.Instant;
|
||||
import java.time.OffsetDateTime;
|
||||
import java.time.ZoneOffset;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
import java.util.UUID;
|
||||
|
||||
/**
|
||||
* The CloudEvents 1.0.2 compatible profile.
|
||||
*
|
||||
* <p>Two mapping decisions are deliberate. An event without {@code occurredAt} is rejected rather
|
||||
* than defaulted to the production instant, because {@code time} is read downstream as when the
|
||||
* fact happened, not when the platform got around to serialising it. And an event with no data maps
|
||||
* to an envelope with empty bytes, never to a Kafka null value: a tombstone deletes a key, and
|
||||
* inventing one from an absent CloudEvent payload would turn an empty notification into a deletion.
|
||||
*/
|
||||
public final class DefaultCloudEventMapper implements CloudEventMapper {
|
||||
|
||||
private static final String SPEC_CONTENT_TYPE_FALLBACK = "application/json";
|
||||
|
||||
@Override
|
||||
public CloudEvent toCloudEvent(MessageEnvelope<?> envelope, URI source) {
|
||||
Objects.requireNonNull(envelope, "envelope must not be null");
|
||||
Objects.requireNonNull(source, "source must not be null");
|
||||
|
||||
Instant occurredAt =
|
||||
envelope
|
||||
.occurredAt()
|
||||
.orElseThrow(
|
||||
() ->
|
||||
new MessageValidationException(
|
||||
"CLOUDEVENT_TIME_REQUIRED",
|
||||
"an event mapped to CloudEvents requires occurredAt"));
|
||||
|
||||
CloudEventBuilder builder =
|
||||
CloudEventBuilder.v1()
|
||||
.withId(envelope.messageId().value().toString())
|
||||
.withSource(source)
|
||||
.withType(envelope.messageType().value())
|
||||
.withTime(OffsetDateTime.ofInstant(occurredAt, ZoneOffset.UTC))
|
||||
.withDataContentType(envelope.contentType().value())
|
||||
.withExtension(
|
||||
CloudEventExtensions.SCHEMA_VERSION,
|
||||
Integer.toString(envelope.schemaVersion().value()));
|
||||
|
||||
envelope
|
||||
.correlationId()
|
||||
.ifPresent(
|
||||
value -> builder.withExtension(CloudEventExtensions.CORRELATION_ID, value.value()));
|
||||
envelope
|
||||
.causationId()
|
||||
.ifPresent(
|
||||
value ->
|
||||
builder.withExtension(
|
||||
CloudEventExtensions.CAUSATION_ID, value.value().value().toString()));
|
||||
envelope
|
||||
.tenantContext()
|
||||
.ifPresent(
|
||||
value -> builder.withExtension(CloudEventExtensions.TENANT_CONTEXT, value.tenantId()));
|
||||
|
||||
if (envelope.payload() instanceof EncodedMessage encoded) {
|
||||
encoded
|
||||
.schemaReference()
|
||||
.flatMap(reference -> reference.schemaUri())
|
||||
.ifPresent(builder::withDataSchema);
|
||||
builder.withData(BytesCloudEventData.wrap(encoded.bytes()));
|
||||
} else if (envelope.payload() instanceof byte[] bytes) {
|
||||
builder.withData(BytesCloudEventData.wrap(bytes.clone()));
|
||||
} else {
|
||||
throw new MessageValidationException(
|
||||
"CLOUDEVENT_PAYLOAD_NOT_ENCODED",
|
||||
"CloudEvents mapping requires an already-encoded payload");
|
||||
}
|
||||
|
||||
return builder.build();
|
||||
}
|
||||
|
||||
@Override
|
||||
public MessageEnvelope<EncodedMessage> fromCloudEvent(CloudEvent event) {
|
||||
Objects.requireNonNull(event, "event must not be null");
|
||||
|
||||
OffsetDateTime time = event.getTime();
|
||||
if (time == null) {
|
||||
throw new MessageValidationException(
|
||||
"CLOUDEVENT_TIME_REQUIRED", "a CloudEvent mapped to an envelope requires time");
|
||||
}
|
||||
|
||||
ContentType contentType =
|
||||
new ContentType(
|
||||
Optional.ofNullable(event.getDataContentType()).orElse(SPEC_CONTENT_TYPE_FALLBACK));
|
||||
CloudEventData data = event.getData();
|
||||
byte[] bytes = data == null ? new byte[0] : data.toBytes();
|
||||
|
||||
Instant occurredAt = time.toInstant();
|
||||
return new MessageEnvelope<>(
|
||||
new MessageId(UUID.fromString(event.getId())),
|
||||
new MessageType(event.getType()),
|
||||
new SchemaVersion(intExtension(event, CloudEventExtensions.SCHEMA_VERSION)),
|
||||
occurredAt,
|
||||
Optional.of(occurredAt),
|
||||
new ProducerId(producerFrom(event.getSource())),
|
||||
stringExtension(event, CloudEventExtensions.CORRELATION_ID).map(CorrelationId::new),
|
||||
stringExtension(event, CloudEventExtensions.CAUSATION_ID)
|
||||
.map(value -> new CausationId(new MessageId(UUID.fromString(value)))),
|
||||
contentType,
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
stringExtension(event, CloudEventExtensions.TENANT_CONTEXT).map(TenantContext::new),
|
||||
TraceContext.none(),
|
||||
MessageHeaders.empty(),
|
||||
new EncodedMessage(bytes, contentType, Optional.empty()));
|
||||
}
|
||||
|
||||
private static Optional<String> stringExtension(CloudEvent event, String name) {
|
||||
return Optional.ofNullable(event.getExtension(name)).map(Object::toString);
|
||||
}
|
||||
|
||||
private static int intExtension(CloudEvent event, String name) {
|
||||
return stringExtension(event, name)
|
||||
.map(
|
||||
value -> {
|
||||
try {
|
||||
return Integer.valueOf(value);
|
||||
} catch (NumberFormatException exception) {
|
||||
throw new MessageValidationException(
|
||||
"CLOUDEVENT_SCHEMA_VERSION_INVALID",
|
||||
"schemaversion extension is not an integer",
|
||||
exception);
|
||||
}
|
||||
})
|
||||
.orElseThrow(
|
||||
() ->
|
||||
new MessageValidationException(
|
||||
"CLOUDEVENT_SCHEMA_VERSION_REQUIRED",
|
||||
"schemaversion extension is required by this profile"));
|
||||
}
|
||||
|
||||
/**
|
||||
* Derives a bounded producer id from the source URI.
|
||||
*
|
||||
* <p>The last path or scheme-specific segment is used so that a long URI does not become an
|
||||
* unbounded producer name, which would leak straight into metric tags.
|
||||
*/
|
||||
private static String producerFrom(URI source) {
|
||||
String text = source.toString();
|
||||
int separator = Math.max(text.lastIndexOf('/'), text.lastIndexOf(':'));
|
||||
String candidate =
|
||||
separator >= 0 && separator + 1 < text.length() ? text.substring(separator + 1) : text;
|
||||
return candidate.isBlank() ? "unknown" : candidate;
|
||||
}
|
||||
}
|
||||
+162
@@ -0,0 +1,162 @@
|
||||
package dev.caskeleton.messaging.cloudevents;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.messaging.api.ContentType;
|
||||
import dev.caskeleton.messaging.api.CorrelationId;
|
||||
import dev.caskeleton.messaging.api.MessageEnvelope;
|
||||
import dev.caskeleton.messaging.api.MessageId;
|
||||
import dev.caskeleton.messaging.api.MessageType;
|
||||
import dev.caskeleton.messaging.api.ProducerId;
|
||||
import dev.caskeleton.messaging.api.SchemaVersion;
|
||||
import dev.caskeleton.messaging.api.TenantContext;
|
||||
import dev.caskeleton.messaging.api.TraceContext;
|
||||
import dev.caskeleton.messaging.api.error.MessageValidationException;
|
||||
import dev.caskeleton.messaging.api.header.MessageHeaders;
|
||||
import dev.caskeleton.messaging.schema.EncodedMessage;
|
||||
import io.cloudevents.CloudEvent;
|
||||
import java.net.URI;
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.time.Instant;
|
||||
import java.util.Optional;
|
||||
import java.util.UUID;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class CloudEventMappingTest {
|
||||
|
||||
private static final URI SOURCE = URI.create("urn:service:order-api");
|
||||
|
||||
private final DefaultCloudEventMapper mapper = new DefaultCloudEventMapper();
|
||||
|
||||
@Test
|
||||
void mapsLogicalIdentityAndExtensions() {
|
||||
MessageEnvelope<EncodedMessage> envelope = CloudEventFixture.orderCreatedEnvelope();
|
||||
|
||||
CloudEvent event = mapper.toCloudEvent(envelope, SOURCE);
|
||||
|
||||
assertThat(event.getId()).isEqualTo(envelope.messageId().value().toString());
|
||||
assertThat(event.getType()).isEqualTo("order.created");
|
||||
assertThat(event.getExtension(CloudEventExtensions.SCHEMA_VERSION)).isEqualTo("1");
|
||||
assertThat(event.getSource()).isEqualTo(SOURCE);
|
||||
assertThat(event.getDataContentType()).isEqualTo("application/json");
|
||||
}
|
||||
|
||||
@Test
|
||||
void mapsCorrelationAndTenantAsExtensions() {
|
||||
CloudEvent event = mapper.toCloudEvent(CloudEventFixture.orderCreatedEnvelope(), SOURCE);
|
||||
|
||||
assertThat(event.getExtension(CloudEventExtensions.CORRELATION_ID)).isEqualTo("wf-1");
|
||||
assertThat(event.getExtension(CloudEventExtensions.TENANT_CONTEXT)).isEqualTo("acme");
|
||||
}
|
||||
|
||||
@Test
|
||||
void mapsOccurredAtToEventTime() {
|
||||
CloudEvent event = mapper.toCloudEvent(CloudEventFixture.orderCreatedEnvelope(), SOURCE);
|
||||
|
||||
assertThat(event.getTime()).isNotNull();
|
||||
assertThat(event.getTime().toInstant()).isEqualTo(Instant.parse("2026-08-10T09:15:00Z"));
|
||||
}
|
||||
|
||||
@Test
|
||||
void rejectsAnEventEnvelopeWithoutOccurredAt() {
|
||||
MessageEnvelope<EncodedMessage> withoutOccurredAt =
|
||||
CloudEventFixture.envelope(Optional.empty());
|
||||
|
||||
assertThatThrownBy(() -> mapper.toCloudEvent(withoutOccurredAt, SOURCE))
|
||||
.isInstanceOf(MessageValidationException.class)
|
||||
.hasMessageContaining("occurredAt");
|
||||
}
|
||||
|
||||
@Test
|
||||
void roundTripsBackToAnEnvelopeWithoutInventingATombstone() {
|
||||
MessageEnvelope<EncodedMessage> original = CloudEventFixture.orderCreatedEnvelope();
|
||||
|
||||
MessageEnvelope<EncodedMessage> restored =
|
||||
mapper.fromCloudEvent(mapper.toCloudEvent(original, SOURCE));
|
||||
|
||||
assertThat(restored.messageId()).isEqualTo(original.messageId());
|
||||
assertThat(restored.messageType()).isEqualTo(original.messageType());
|
||||
assertThat(restored.schemaVersion()).isEqualTo(original.schemaVersion());
|
||||
assertThat(restored.correlationId()).contains(new CorrelationId("wf-1"));
|
||||
assertThat(restored.tenantContext()).contains(new TenantContext("acme"));
|
||||
assertThat(restored.payload().bytes()).isEqualTo(original.payload().bytes());
|
||||
}
|
||||
|
||||
@Test
|
||||
void aCloudEventWithNoDataBecomesAnEmptyPayloadNotANullValue() {
|
||||
CloudEvent noData =
|
||||
io.cloudevents.core.builder.CloudEventBuilder.v1()
|
||||
// A v7 id: MessageId enforces the version it documents, so a v4 arriving from a foreign
|
||||
// producer is refused here exactly as it would be on the wire.
|
||||
.withId(dev.caskeleton.messaging.api.MessageId.newId().value().toString())
|
||||
.withSource(SOURCE)
|
||||
.withType("order.created")
|
||||
.withTime(java.time.OffsetDateTime.parse("2026-08-10T09:15:00Z"))
|
||||
.withDataContentType("application/json")
|
||||
.withExtension(CloudEventExtensions.SCHEMA_VERSION, "1")
|
||||
.build();
|
||||
|
||||
MessageEnvelope<EncodedMessage> restored = mapper.fromCloudEvent(noData);
|
||||
|
||||
assertThat(restored.payload()).isNotNull();
|
||||
assertThat(restored.payload().size()).isZero();
|
||||
}
|
||||
|
||||
@Test
|
||||
void rejectsAnUnencodedPayload() {
|
||||
MessageEnvelope<String> unencoded =
|
||||
new MessageEnvelope<>(
|
||||
MessageId.newId(),
|
||||
new MessageType("order.created"),
|
||||
new SchemaVersion(1),
|
||||
Instant.parse("2026-08-10T09:15:00Z"),
|
||||
Optional.of(Instant.parse("2026-08-10T09:15:00Z")),
|
||||
new ProducerId("order-api"),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
ContentType.JSON,
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
TraceContext.none(),
|
||||
MessageHeaders.empty(),
|
||||
"not encoded");
|
||||
|
||||
assertThatThrownBy(() -> mapper.toCloudEvent(unencoded, SOURCE))
|
||||
.isInstanceOf(MessageValidationException.class);
|
||||
}
|
||||
}
|
||||
|
||||
/** Builds CloudEvents mapping fixtures. */
|
||||
final class CloudEventFixture {
|
||||
|
||||
private static final MessageId FIXED_ID =
|
||||
new MessageId(UUID.fromString("0190f4aa-0000-7000-8000-000000000001"));
|
||||
|
||||
private CloudEventFixture() {}
|
||||
|
||||
static MessageEnvelope<EncodedMessage> orderCreatedEnvelope() {
|
||||
return envelope(Optional.of(Instant.parse("2026-08-10T09:15:00Z")));
|
||||
}
|
||||
|
||||
static MessageEnvelope<EncodedMessage> envelope(Optional<Instant> occurredAt) {
|
||||
byte[] payload = "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8);
|
||||
return new MessageEnvelope<>(
|
||||
FIXED_ID,
|
||||
new MessageType("order.created"),
|
||||
new SchemaVersion(1),
|
||||
Instant.parse("2026-08-10T09:15:01Z"),
|
||||
occurredAt,
|
||||
new ProducerId("order-api"),
|
||||
Optional.of(new CorrelationId("wf-1")),
|
||||
Optional.empty(),
|
||||
ContentType.JSON,
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.of(new TenantContext("acme")),
|
||||
TraceContext.none(),
|
||||
MessageHeaders.empty(),
|
||||
new EncodedMessage(payload, ContentType.JSON, Optional.empty()));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,6 @@
|
||||
plugins {
|
||||
id 'ca.platform-module'
|
||||
}
|
||||
|
||||
dependencies {
|
||||
}
|
||||
@@ -0,0 +1,84 @@
|
||||
# This is a Gradle generated file for dependency locking.
|
||||
# Manual edits can break the build and are not advised.
|
||||
# This file is expected to be part of source control.
|
||||
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
|
||||
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
|
||||
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
|
||||
com.github.spotbugs:spotbugs:4.10.2=spotbugs
|
||||
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
|
||||
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
|
||||
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
|
||||
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
|
||||
com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs
|
||||
com.google.code.gson:gson:2.13.2=spotbugs
|
||||
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
|
||||
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
|
||||
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:guava:33.6.0-jre=checkstyle
|
||||
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
|
||||
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
|
||||
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
|
||||
commons-beanutils:commons-beanutils:1.11.0=checkstyle
|
||||
commons-collections:commons-collections:3.2.2=checkstyle
|
||||
commons-io:commons-io:2.21.0=spotbugs
|
||||
info.picocli:picocli:4.7.7=checkstyle
|
||||
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
|
||||
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
|
||||
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
|
||||
jaxen:jaxen:2.0.6=spotbugs
|
||||
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
|
||||
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
|
||||
org.antlr:antlr4-runtime:4.13.2=checkstyle
|
||||
org.apache.bcel:bcel:6.12.0=spotbugs
|
||||
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
|
||||
org.apache.commons:commons-text:1.15.0=spotbugs
|
||||
org.apache.commons:commons-text:1.3=checkstyle
|
||||
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
|
||||
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
|
||||
org.apache.logging.log4j:log4j-api:2.25.5=spotbugs
|
||||
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
|
||||
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
|
||||
org.apache.xbean:xbean-reflect:3.7=checkstyle
|
||||
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
|
||||
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
|
||||
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
|
||||
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
|
||||
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
|
||||
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
|
||||
org.dom4j:dom4j:2.2.0=spotbugs
|
||||
org.javassist:javassist:3.28.0-GA=checkstyle
|
||||
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
|
||||
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
|
||||
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit:junit-bom:6.1.0=spotbugs
|
||||
org.mockito:mockito-core:5.20.0=mockitoAgent
|
||||
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
|
||||
org.ow2.asm:asm-analysis:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-commons:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-tree:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-util:9.10.1=spotbugs
|
||||
org.ow2.asm:asm:9.10.1=spotbugs
|
||||
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
|
||||
org.reflections:reflections:0.10.2=checkstyle
|
||||
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.18=checkstyle
|
||||
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
|
||||
empty=compileClasspath,runtimeClasspath
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
package dev.caskeleton.messaging.api;
|
||||
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Identity of the message that directly caused this one.
|
||||
*
|
||||
* <p>Unlike {@link CorrelationId}, which spans a whole workflow, this points at exactly one
|
||||
* predecessor and forms the causal edge used when reconstructing a flow.
|
||||
*
|
||||
* @param value the predecessor message identity
|
||||
*/
|
||||
public record CausationId(MessageId value) {
|
||||
|
||||
public CausationId {
|
||||
Objects.requireNonNull(value, "causationId value must not be null");
|
||||
}
|
||||
}
|
||||
+46
@@ -0,0 +1,46 @@
|
||||
package dev.caskeleton.messaging.api;
|
||||
|
||||
import java.util.Locale;
|
||||
|
||||
/**
|
||||
* Media type of an encoded payload, resolved through the codec registry.
|
||||
*
|
||||
* @param value the media type, for example {@code application/json}
|
||||
*/
|
||||
public record ContentType(String value) {
|
||||
|
||||
private static final int MAX_LENGTH = 160;
|
||||
|
||||
/** {@code type/subtype} with the optional parameters RFC 9110 allows. */
|
||||
private static final java.util.regex.Pattern MEDIA_TYPE =
|
||||
java.util.regex.Pattern.compile(
|
||||
"[A-Za-z0-9][A-Za-z0-9!#$%&'*+.^_`|~-]*"
|
||||
+ "/[A-Za-z0-9][A-Za-z0-9!#$%&'*+.^_`|~-]*"
|
||||
+ "(;\\s*[A-Za-z0-9!#$%&'*+.^_`|~-]+=[^;\\s]+)*");
|
||||
|
||||
/** The Stable default codec's content type. */
|
||||
public static final ContentType JSON = new ContentType("application/json");
|
||||
|
||||
/** Avro binary content type. */
|
||||
public static final ContentType AVRO = new ContentType("application/avro");
|
||||
|
||||
/** Protobuf binary content type. */
|
||||
public static final ContentType PROTOBUF = new ContentType("application/x-protobuf");
|
||||
|
||||
/** Opaque bytes, only reachable through the M2 raw codec. */
|
||||
public static final ContentType OCTET_STREAM = new ContentType("application/octet-stream");
|
||||
|
||||
public ContentType {
|
||||
if (value == null || value.isBlank() || value.length() > MAX_LENGTH) {
|
||||
throw new IllegalArgumentException("contentType must contain 1 to 160 characters");
|
||||
}
|
||||
// A media type, not merely a string containing a slash. `a/b/c`, `/json` and `text/` all
|
||||
// passed the old check and are all rejected by a broker or a codec registry later, with an
|
||||
// error that names the message rather than the configuration that produced it.
|
||||
if (!MEDIA_TYPE.matcher(value).matches()) {
|
||||
throw new IllegalArgumentException(
|
||||
"contentType must be a type/subtype media type: '" + value + '\'');
|
||||
}
|
||||
value = value.toLowerCase(Locale.ROOT);
|
||||
}
|
||||
}
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
package dev.caskeleton.messaging.api;
|
||||
|
||||
/**
|
||||
* Workflow-scoped correlation value shared by every message of one business flow.
|
||||
*
|
||||
* <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) {
|
||||
|
||||
private static final int MAX_BYTES = 160;
|
||||
|
||||
public CorrelationId {
|
||||
if (value == null || value.isBlank()) {
|
||||
throw new IllegalArgumentException("correlationId must not be blank");
|
||||
}
|
||||
WireSafeText.require(value, "a correlation id", MAX_BYTES);
|
||||
}
|
||||
}
|
||||
+181
@@ -0,0 +1,181 @@
|
||||
package dev.caskeleton.messaging.api;
|
||||
|
||||
import dev.caskeleton.messaging.api.header.MessageHeaders;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* The platform's unit of transfer: identity, provenance, routing intent, and payload.
|
||||
*
|
||||
* <p>The payload is never null. A null Kafka value is a tombstone, which is a distinct
|
||||
* broker-native operation with different retention semantics, so generalising it into "an envelope
|
||||
* with no payload" would silently turn a delete into an event on brokers that have no such concept.
|
||||
*
|
||||
* @param <T> the payload type
|
||||
* @param messageId logical identity, preserved across retry, DLQ, and redrive
|
||||
* @param messageType stable catalog type
|
||||
* @param schemaVersion payload schema revision
|
||||
* @param producedAt instant the platform created this envelope
|
||||
* @param occurredAt instant the business fact occurred; required for events
|
||||
* @param producer logical producing service
|
||||
* @param correlationId workflow correlation
|
||||
* @param causationId directly causing message
|
||||
* @param contentType codec media type
|
||||
* @param partitionKey distribution key
|
||||
* @param orderingKey ordering key
|
||||
* @param tenantContext bounded tenant identity
|
||||
* @param traceContext trace propagation values
|
||||
* @param headers bounded application headers
|
||||
* @param payload the non-null payload
|
||||
*/
|
||||
public record MessageEnvelope<T>(
|
||||
MessageId messageId,
|
||||
MessageType messageType,
|
||||
SchemaVersion schemaVersion,
|
||||
Instant producedAt,
|
||||
Optional<Instant> occurredAt,
|
||||
ProducerId producer,
|
||||
Optional<CorrelationId> correlationId,
|
||||
Optional<CausationId> causationId,
|
||||
ContentType contentType,
|
||||
Optional<String> partitionKey,
|
||||
Optional<String> orderingKey,
|
||||
Optional<TenantContext> tenantContext,
|
||||
TraceContext traceContext,
|
||||
MessageHeaders headers,
|
||||
T payload) {
|
||||
|
||||
public MessageEnvelope {
|
||||
Objects.requireNonNull(messageId, "messageId must not be null");
|
||||
Objects.requireNonNull(messageType, "messageType must not be null");
|
||||
Objects.requireNonNull(schemaVersion, "schemaVersion must not be null");
|
||||
Objects.requireNonNull(producedAt, "producedAt must not be null");
|
||||
Objects.requireNonNull(occurredAt, "occurredAt must not be null");
|
||||
Objects.requireNonNull(producer, "producer must not be null");
|
||||
Objects.requireNonNull(correlationId, "correlationId must not be null");
|
||||
Objects.requireNonNull(causationId, "causationId must not be null");
|
||||
Objects.requireNonNull(contentType, "contentType must not be null");
|
||||
Objects.requireNonNull(partitionKey, "partitionKey must not be null");
|
||||
Objects.requireNonNull(orderingKey, "orderingKey must not be null");
|
||||
Objects.requireNonNull(tenantContext, "tenantContext must not be null");
|
||||
Objects.requireNonNull(traceContext, "traceContext must not be null");
|
||||
Objects.requireNonNull(headers, "headers must not be null");
|
||||
Objects.requireNonNull(payload, "payload must not be null");
|
||||
// Both keys are routing input the caller chooses, and both used to be unbounded strings. A
|
||||
// partition key is hashed by the broker, so an unbounded one is a cost rather than a
|
||||
// correctness problem; an ordering key is carried on the wire by several bindings, so a
|
||||
// control character in it is the same injection primitive as in a header. The bound is the
|
||||
// smallest one every targeted broker accepts.
|
||||
partitionKey.ifPresent(key -> WireSafeText.require(key, "a partition key", MAX_KEY_BYTES));
|
||||
orderingKey.ifPresent(key -> WireSafeText.require(key, "an ordering key", MAX_KEY_BYTES));
|
||||
}
|
||||
|
||||
/** The routing-key bound every targeted broker accepts. */
|
||||
private static final int MAX_KEY_BYTES = 1024;
|
||||
|
||||
/**
|
||||
* Returns a copy of this envelope carrying a different payload representation.
|
||||
*
|
||||
* <p>Encoding, decoding, Claim Check offloading, and DLQ forwarding all need this, and every one
|
||||
* of them must keep {@link #messageId()} intact — which is exactly what this method guarantees by
|
||||
* construction.
|
||||
*
|
||||
* @param <R> the replacement payload type
|
||||
* @param replacement the new payload
|
||||
* @return an envelope with identical identity and metadata
|
||||
*/
|
||||
public <R> MessageEnvelope<R> withPayload(R replacement) {
|
||||
return new MessageEnvelope<>(
|
||||
messageId,
|
||||
messageType,
|
||||
schemaVersion,
|
||||
producedAt,
|
||||
occurredAt,
|
||||
producer,
|
||||
correlationId,
|
||||
causationId,
|
||||
contentType,
|
||||
partitionKey,
|
||||
orderingKey,
|
||||
tenantContext,
|
||||
traceContext,
|
||||
headers,
|
||||
replacement);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a copy of this envelope carrying a different content type.
|
||||
*
|
||||
* @param replacement the new content type
|
||||
* @return an envelope with identical identity and payload
|
||||
*/
|
||||
public MessageEnvelope<T> withContentType(ContentType replacement) {
|
||||
return new MessageEnvelope<>(
|
||||
messageId,
|
||||
messageType,
|
||||
schemaVersion,
|
||||
producedAt,
|
||||
occurredAt,
|
||||
producer,
|
||||
correlationId,
|
||||
causationId,
|
||||
Objects.requireNonNull(replacement, "contentType must not be null"),
|
||||
partitionKey,
|
||||
orderingKey,
|
||||
tenantContext,
|
||||
traceContext,
|
||||
headers,
|
||||
payload);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a copy of this envelope bound to a tenant.
|
||||
*
|
||||
* @param tenant the tenant this message belongs to
|
||||
* @return an envelope with identical identity and payload
|
||||
*/
|
||||
public MessageEnvelope<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.
|
||||
*
|
||||
* @param replacement the new headers
|
||||
* @return an envelope with identical identity and payload
|
||||
*/
|
||||
public MessageEnvelope<T> withHeaders(MessageHeaders replacement) {
|
||||
return new MessageEnvelope<>(
|
||||
messageId,
|
||||
messageType,
|
||||
schemaVersion,
|
||||
producedAt,
|
||||
occurredAt,
|
||||
producer,
|
||||
correlationId,
|
||||
causationId,
|
||||
contentType,
|
||||
partitionKey,
|
||||
orderingKey,
|
||||
tenantContext,
|
||||
traceContext,
|
||||
Objects.requireNonNull(replacement, "headers must not be null"),
|
||||
payload);
|
||||
}
|
||||
}
|
||||
+42
@@ -0,0 +1,42 @@
|
||||
package dev.caskeleton.messaging.api;
|
||||
|
||||
import java.util.Objects;
|
||||
import java.util.UUID;
|
||||
|
||||
/**
|
||||
* Logical identity of a message.
|
||||
*
|
||||
* <p>This value survives publish retry, broker redelivery, retry destinations, dead lettering, and
|
||||
* redrive. A new {@code MessageId} is minted only for a genuinely new business fact or command, so
|
||||
* an Inbox can use it to suppress duplicate side effects.
|
||||
*
|
||||
* @param value the UUIDv7 identity
|
||||
*/
|
||||
public record MessageId(UUID value) {
|
||||
|
||||
/** The UUID version this identity is documented to carry. */
|
||||
private static final int VERSION_7 = 7;
|
||||
|
||||
public MessageId {
|
||||
Objects.requireNonNull(value, "messageId value must not be null");
|
||||
// The type says UUIDv7 and the constructor accepted any UUID, including v4 and the nil UUID.
|
||||
// Version 7 is what makes the identity time-ordered, which is what the outbox index and every
|
||||
// "oldest first" claim depend on; a v4 stored in the same column silently defeats both.
|
||||
if (value.version() != VERSION_7) {
|
||||
throw new IllegalArgumentException(
|
||||
"a message identity is UUIDv7 (time-ordered); this is version " + value.version());
|
||||
}
|
||||
if (value.variant() != 2) {
|
||||
throw new IllegalArgumentException("a message identity must use the RFC 4122 variant");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Mints a new logical message identity.
|
||||
*
|
||||
* @return a fresh time-ordered identity
|
||||
*/
|
||||
public static MessageId newId() {
|
||||
return new MessageId(UuidV7.next());
|
||||
}
|
||||
}
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
package dev.caskeleton.messaging.api;
|
||||
|
||||
/**
|
||||
* Stable catalog name of a message, such as {@code order.created}.
|
||||
*
|
||||
* <p>Java class names are deliberately not usable as a message type: renaming or repackaging a
|
||||
* class must never change the wire contract.
|
||||
*
|
||||
* @param value the catalog name, 1 to 240 UTF-8 bytes and free of control characters
|
||||
*/
|
||||
public record MessageType(String value) {
|
||||
|
||||
private static final int MAX_BYTES = 240;
|
||||
|
||||
public MessageType {
|
||||
if (value == null || value.isBlank()) {
|
||||
throw new IllegalArgumentException("messageType must not be blank");
|
||||
}
|
||||
WireSafeText.require(value, "a message type", MAX_BYTES);
|
||||
}
|
||||
}
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
package dev.caskeleton.messaging.api;
|
||||
|
||||
/**
|
||||
* Logical service identity of the component that produced a message.
|
||||
*
|
||||
* <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.
|
||||
*
|
||||
* @param value the service name, 1 to 120 UTF-8 bytes and free of control characters
|
||||
*/
|
||||
public record ProducerId(String value) {
|
||||
|
||||
private static final int MAX_BYTES = 120;
|
||||
|
||||
public ProducerId {
|
||||
if (value == null || value.isBlank()) {
|
||||
throw new IllegalArgumentException("producerId must not be blank");
|
||||
}
|
||||
WireSafeText.require(value, "a producer id", MAX_BYTES);
|
||||
}
|
||||
}
|
||||
+15
@@ -0,0 +1,15 @@
|
||||
package dev.caskeleton.messaging.api;
|
||||
|
||||
/**
|
||||
* Monotonic schema revision of a {@link MessageType}.
|
||||
*
|
||||
* @param value the revision, starting at 1
|
||||
*/
|
||||
public record SchemaVersion(int value) {
|
||||
|
||||
public SchemaVersion {
|
||||
if (value < 1) {
|
||||
throw new IllegalArgumentException("schemaVersion must be positive");
|
||||
}
|
||||
}
|
||||
}
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
package dev.caskeleton.messaging.api;
|
||||
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
/**
|
||||
* Bounded tenant identity carried with a message.
|
||||
*
|
||||
* <p>The value is deliberately constrained to a short slug. Tenant identity is one of the few
|
||||
* envelope fields that observability code is tempted to use as a metric label, and an unbounded
|
||||
* tenant id turns that into a cardinality explosion.
|
||||
*
|
||||
* @param tenantId the tenant slug
|
||||
*/
|
||||
public record TenantContext(String tenantId) {
|
||||
|
||||
private static final Pattern VALID = Pattern.compile("[a-z0-9][a-z0-9._-]{0,63}");
|
||||
|
||||
public TenantContext {
|
||||
if (tenantId == null || !VALID.matcher(tenantId).matches()) {
|
||||
throw new IllegalArgumentException(
|
||||
"tenantId must match [a-z0-9][a-z0-9._-]{0,63}: " + tenantId);
|
||||
}
|
||||
}
|
||||
}
|
||||
+155
@@ -0,0 +1,155 @@
|
||||
package dev.caskeleton.messaging.api;
|
||||
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
/**
|
||||
* W3C trace propagation values carried with a message.
|
||||
*
|
||||
* <p>The platform creates and propagates these; handlers do not set them. Keeping them on the
|
||||
* envelope rather than only in headers means a trace survives an Outbox round trip through the
|
||||
* database, where broker headers do not exist yet.
|
||||
*
|
||||
* <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 tracestate the {@code tracestate} value when present
|
||||
* @param baggage the {@code baggage} value when present
|
||||
*/
|
||||
public record TraceContext(
|
||||
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 {
|
||||
Objects.requireNonNull(traceparent, "traceparent must not be null");
|
||||
Objects.requireNonNull(tracestate, "tracestate must not be null");
|
||||
Objects.requireNonNull(baggage, "baggage must not be null");
|
||||
traceparent.ifPresent(TraceContext::requireValidTraceparent);
|
||||
tracestate.ifPresent(TraceContext::requireValidTracestate);
|
||||
baggage.ifPresent(TraceContext::requireValidBaggage);
|
||||
if (tracestate.isPresent() && traceparent.isEmpty()) {
|
||||
// A tracestate without a traceparent is vendor state belonging to no trace. Propagating it
|
||||
// hands the next hop a key it will attribute to whatever trace that hop starts.
|
||||
throw new IllegalArgumentException("tracestate must not be present without a traceparent");
|
||||
}
|
||||
}
|
||||
|
||||
private static void requireValidTraceparent(String value) {
|
||||
if (!TRACEPARENT.matcher(value).matches()) {
|
||||
throw new IllegalArgumentException(
|
||||
"traceparent must be version-traceid-spanid-flags in lowercase hex: '" + value + '\'');
|
||||
}
|
||||
String version = value.substring(0, 2);
|
||||
if ("ff".equals(version)) {
|
||||
// The standard reserves ff and requires a receiver to reject it, rather than treat it as a
|
||||
// future version to be forwarded.
|
||||
throw new IllegalArgumentException("traceparent version ff is invalid");
|
||||
}
|
||||
String traceId = value.substring(3, 35);
|
||||
if (ALL_ZERO_TRACE_ID.equals(traceId)) {
|
||||
throw new IllegalArgumentException("traceparent carries an all-zero trace id");
|
||||
}
|
||||
String spanId = value.substring(36, 52);
|
||||
if (ALL_ZERO_SPAN_ID.equals(spanId)) {
|
||||
throw new IllegalArgumentException("traceparent carries an all-zero parent span id");
|
||||
}
|
||||
}
|
||||
|
||||
private static void requireValidTracestate(String value) {
|
||||
int bytes = value.getBytes(StandardCharsets.UTF_8).length;
|
||||
if (bytes > MAX_TRACESTATE_BYTES) {
|
||||
throw new IllegalArgumentException("tracestate exceeds 512 bytes: " + bytes);
|
||||
}
|
||||
String[] members = value.split(",", -1);
|
||||
if (members.length > MAX_TRACESTATE_MEMBERS) {
|
||||
throw new IllegalArgumentException(
|
||||
"tracestate carries more than 32 list members: " + members.length);
|
||||
}
|
||||
for (String member : members) {
|
||||
String trimmed = member.strip();
|
||||
if (trimmed.isEmpty()) {
|
||||
// The grammar permits empty members for forward compatibility; nothing is propagated for
|
||||
// them, so they are dropped by the receiver rather than being an error here.
|
||||
continue;
|
||||
}
|
||||
if (!TRACESTATE_MEMBER.matcher(trimmed).matches()) {
|
||||
throw new IllegalArgumentException("tracestate member is not valid: '" + trimmed + '\'');
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private static void requireValidBaggage(String value) {
|
||||
int bytes = value.getBytes(StandardCharsets.UTF_8).length;
|
||||
if (bytes > MAX_BAGGAGE_BYTES) {
|
||||
throw new IllegalArgumentException("baggage exceeds 8192 bytes: " + bytes);
|
||||
}
|
||||
WireSafeText.requireNoControls(value, "baggage");
|
||||
String[] members = value.split(",", -1);
|
||||
if (members.length > MAX_BAGGAGE_MEMBERS) {
|
||||
throw new IllegalArgumentException("baggage carries more than 64 members: " + members.length);
|
||||
}
|
||||
for (String member : members) {
|
||||
String trimmed = member.strip();
|
||||
int equals = trimmed.indexOf('=');
|
||||
if (equals <= 0 || equals == trimmed.length() - 1) {
|
||||
throw new IllegalArgumentException("baggage member must be key=value: '" + trimmed + '\'');
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a context with no active trace.
|
||||
*
|
||||
* @return an empty trace context
|
||||
*/
|
||||
public static TraceContext none() {
|
||||
return new TraceContext(Optional.empty(), Optional.empty(), Optional.empty());
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a context carrying only a trace parent.
|
||||
*
|
||||
* @param traceparent the {@code traceparent} value
|
||||
* @return a trace context
|
||||
*/
|
||||
public static TraceContext of(String traceparent) {
|
||||
return new TraceContext(Optional.of(traceparent), Optional.empty(), Optional.empty());
|
||||
}
|
||||
}
|
||||
+62
@@ -0,0 +1,62 @@
|
||||
package dev.caskeleton.messaging.api;
|
||||
|
||||
import java.security.SecureRandom;
|
||||
import java.util.UUID;
|
||||
import java.util.concurrent.atomic.AtomicLong;
|
||||
|
||||
/**
|
||||
* Generates RFC 9562 UUIDv7 values.
|
||||
*
|
||||
* <p>The platform needs message identifiers that sort by creation time so that outbox scans, DLQ
|
||||
* listings, and broker partitions stay locality-friendly, while still being globally unique. The 12
|
||||
* bit {@code rand_a} field is used as a monotonic intra-millisecond counter instead of random bits:
|
||||
* two calls in the same millisecond are then still strictly ordered, which is what makes "same
|
||||
* logical message keeps the same id" auditable across a retry.
|
||||
*/
|
||||
public final class UuidV7 {
|
||||
|
||||
private static final SecureRandom RANDOM = new SecureRandom();
|
||||
|
||||
/** Packs the 48-bit millisecond timestamp in the high bits and the 12-bit counter in the low. */
|
||||
private static final AtomicLong STATE = new AtomicLong();
|
||||
|
||||
private static final long COUNTER_BITS = 12L;
|
||||
private static final long COUNTER_MASK = 0xFFFL;
|
||||
private static final long VERSION_7 = 0x7L;
|
||||
private static final long VARIANT_RFC9562 = 0x8000_0000_0000_0000L;
|
||||
private static final long RANDOM_B_MASK = 0x3FFF_FFFF_FFFF_FFFFL;
|
||||
|
||||
private UuidV7() {}
|
||||
|
||||
/**
|
||||
* Returns the next monotonically increasing UUIDv7.
|
||||
*
|
||||
* @return a version 7, variant 2 UUID
|
||||
*/
|
||||
public static UUID next() {
|
||||
long state = STATE.updateAndGet(UuidV7::advance);
|
||||
long timestamp = state >>> COUNTER_BITS;
|
||||
long counter = state & COUNTER_MASK;
|
||||
|
||||
long mostSignificantBits = (timestamp << 16) | (VERSION_7 << COUNTER_BITS) | counter;
|
||||
long leastSignificantBits = (RANDOM.nextLong() & RANDOM_B_MASK) | VARIANT_RFC9562;
|
||||
return new UUID(mostSignificantBits, leastSignificantBits);
|
||||
}
|
||||
|
||||
/**
|
||||
* Advances the packed state.
|
||||
*
|
||||
* <p>When the clock moved forward the counter restarts at zero. Otherwise the packed value is
|
||||
* simply incremented: that bumps the counter and, once the 12-bit counter overflows, carries into
|
||||
* the timestamp field. A backwards clock step therefore never produces a duplicate or a
|
||||
* descending id, it only borrows from the future.
|
||||
*/
|
||||
private static long advance(long previous) {
|
||||
long now = System.currentTimeMillis();
|
||||
long previousTimestamp = previous >>> COUNTER_BITS;
|
||||
if (now > previousTimestamp) {
|
||||
return now << COUNTER_BITS;
|
||||
}
|
||||
return previous + 1;
|
||||
}
|
||||
}
|
||||
+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));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
+36
@@ -0,0 +1,36 @@
|
||||
package dev.caskeleton.messaging.api.delivery;
|
||||
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Runtime context handed to a handler alongside a delivery.
|
||||
*
|
||||
* <p>{@code shutdownRequested} is visible to handlers on purpose: during a graceful drain the
|
||||
* platform stops creating new retry attempts, and a long-running handler that can wind down early
|
||||
* shortens the drain instead of being cancelled at the deadline.
|
||||
*
|
||||
* @param handlerDeadline the instant after which the handler is considered timed out
|
||||
* @param shutdownRequested whether the consumer has begun draining
|
||||
* @param consumerId the stable, low-cardinality consumer identity
|
||||
*/
|
||||
public record DeliveryContext(
|
||||
Instant handlerDeadline, boolean shutdownRequested, String consumerId) {
|
||||
|
||||
public DeliveryContext {
|
||||
Objects.requireNonNull(handlerDeadline, "handlerDeadline must not be null");
|
||||
if (consumerId == null || consumerId.isBlank()) {
|
||||
throw new IllegalArgumentException("consumerId must not be blank");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether the handler deadline has passed.
|
||||
*
|
||||
* @param now the current instant
|
||||
* @return true when the deadline has elapsed
|
||||
*/
|
||||
public boolean isExpired(Instant now) {
|
||||
return !now.isBefore(handlerDeadline);
|
||||
}
|
||||
}
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
package dev.caskeleton.messaging.api.delivery;
|
||||
|
||||
/**
|
||||
* Broker-level delivery guarantee offered by the common contract.
|
||||
*
|
||||
* <p>There is deliberately no {@code EXACTLY_ONCE} constant. No broker delivers exactly-once across
|
||||
* an external side effect; what real systems provide is at-least-once delivery combined with an
|
||||
* idempotent or transactional consumer. Naming a guarantee the platform cannot honour would push
|
||||
* that responsibility out of sight, so the enum stops where the evidence stops.
|
||||
*/
|
||||
public enum DeliveryGuarantee {
|
||||
|
||||
/** Delivery may be lost; duplicate suppression is preferred over durability. */
|
||||
AT_MOST_ONCE,
|
||||
|
||||
/** Redelivery is possible; durability is preferred over duplicate suppression. */
|
||||
AT_LEAST_ONCE
|
||||
}
|
||||
+46
@@ -0,0 +1,46 @@
|
||||
package dev.caskeleton.messaging.api.delivery;
|
||||
|
||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||
import dev.caskeleton.messaging.api.publish.BrokerPosition;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Transport-side facts about one delivery attempt.
|
||||
*
|
||||
* <p>The first delivery is attempt one, not zero. Off-by-one confusion here directly changes how
|
||||
* many times a poison message is replayed before it is parked, so the counting rule is fixed at the
|
||||
* contract rather than left to each adapter.
|
||||
*
|
||||
* @param destination the logical destination
|
||||
* @param deliveryAttempt the attempt number, starting at one
|
||||
* @param redelivered whether the broker flagged this as a redelivery
|
||||
* @param brokerPosition the broker coordinate when available
|
||||
* @param partitionOrQueue the ordering unit when available
|
||||
* @param consumerGroup the consumer group when applicable
|
||||
* @param receivedAt when the consumer received the delivery
|
||||
*/
|
||||
public record DeliveryMetadata(
|
||||
DestinationName destination,
|
||||
int deliveryAttempt,
|
||||
boolean redelivered,
|
||||
Optional<BrokerPosition> brokerPosition,
|
||||
Optional<String> partitionOrQueue,
|
||||
Optional<String> consumerGroup,
|
||||
Instant receivedAt) {
|
||||
|
||||
public DeliveryMetadata {
|
||||
Objects.requireNonNull(destination, "destination must not be null");
|
||||
Objects.requireNonNull(brokerPosition, "brokerPosition must not be null");
|
||||
Objects.requireNonNull(partitionOrQueue, "partitionOrQueue must not be null");
|
||||
Objects.requireNonNull(consumerGroup, "consumerGroup must not be null");
|
||||
Objects.requireNonNull(receivedAt, "receivedAt must not be null");
|
||||
if (deliveryAttempt < 1) {
|
||||
throw new IllegalArgumentException("deliveryAttempt counts the first delivery as 1");
|
||||
}
|
||||
if (deliveryAttempt == 1 && redelivered) {
|
||||
throw new IllegalArgumentException("the first delivery attempt cannot be a redelivery");
|
||||
}
|
||||
}
|
||||
}
|
||||
+14
@@ -0,0 +1,14 @@
|
||||
package dev.caskeleton.messaging.api.delivery;
|
||||
|
||||
/** How a handler's external side effect is protected against redelivery. */
|
||||
public enum ExternalSideEffectGuarantee {
|
||||
|
||||
/** Nothing protects the side effect; only valid where replay is harmless. */
|
||||
NONE,
|
||||
|
||||
/** The handler must make the side effect idempotent itself. */
|
||||
IDEMPOTENCY_REQUIRED,
|
||||
|
||||
/** An Inbox row and the side effect commit inside the same database transaction. */
|
||||
INBOX_TRANSACTIONAL
|
||||
}
|
||||
+60
@@ -0,0 +1,60 @@
|
||||
package dev.caskeleton.messaging.api.delivery;
|
||||
|
||||
import dev.caskeleton.messaging.api.error.FailureDescriptor;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* What an M1 handler decided about a delivery.
|
||||
*
|
||||
* <p>The handler states an intent; the platform performs the settlement. That split is what keeps
|
||||
* "acknowledge only after the handler succeeded" a platform invariant rather than something each
|
||||
* handler has to remember, and it is why no variant here carries a broker acknowledgement handle.
|
||||
*/
|
||||
public sealed interface HandleResult
|
||||
permits HandleResult.Success, HandleResult.Retry, HandleResult.DeadLetter, HandleResult.Reject {
|
||||
|
||||
/** Processing succeeded; the platform may settle the source. */
|
||||
record Success() implements HandleResult {}
|
||||
|
||||
/**
|
||||
* Processing failed in a way that may succeed later.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
*/
|
||||
record Retry(FailureDescriptor failure) implements HandleResult {
|
||||
public Retry {
|
||||
Objects.requireNonNull(failure, "failure must not be null");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Processing failed permanently; route to the dead letter destination.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
*/
|
||||
record DeadLetter(FailureDescriptor failure) implements HandleResult {
|
||||
public DeadLetter {
|
||||
Objects.requireNonNull(failure, "failure must not be null");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Discard the message without dead lettering.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
*/
|
||||
record Reject(FailureDescriptor failure) implements HandleResult {
|
||||
public Reject {
|
||||
Objects.requireNonNull(failure, "failure must not be null");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a successful result.
|
||||
*
|
||||
* @return the success variant
|
||||
*/
|
||||
static HandleResult success() {
|
||||
return new Success();
|
||||
}
|
||||
}
|
||||
+22
@@ -0,0 +1,22 @@
|
||||
package dev.caskeleton.messaging.api.delivery;
|
||||
|
||||
import dev.caskeleton.messaging.api.MessageEnvelope;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* One decoded message handed to a handler.
|
||||
*
|
||||
* @param <T> the payload type
|
||||
* @param message the decoded envelope
|
||||
* @param metadata transport-side delivery facts
|
||||
* @param context runtime context for this attempt
|
||||
*/
|
||||
public record MessageDelivery<T>(
|
||||
MessageEnvelope<T> message, DeliveryMetadata metadata, DeliveryContext context) {
|
||||
|
||||
public MessageDelivery {
|
||||
Objects.requireNonNull(message, "message must not be null");
|
||||
Objects.requireNonNull(metadata, "metadata must not be null");
|
||||
Objects.requireNonNull(context, "context must not be null");
|
||||
}
|
||||
}
|
||||
+60
@@ -0,0 +1,60 @@
|
||||
package dev.caskeleton.messaging.api.delivery;
|
||||
|
||||
import dev.caskeleton.messaging.api.SchemaVersion;
|
||||
import dev.caskeleton.messaging.api.destination.MessageDestination;
|
||||
import java.util.Set;
|
||||
import java.util.concurrent.CompletionStage;
|
||||
|
||||
/**
|
||||
* The one consume contract, implemented by ordinary business code.
|
||||
*
|
||||
* <p>Handlers state an outcome and never touch broker acknowledgement APIs. Duplicate delivery is a
|
||||
* normal condition, not an error: implementations are expected to be idempotent, or to consume a
|
||||
* destination whose profile declares {@code INBOX_TRANSACTIONAL}, where the platform runs the
|
||||
* handler inside the inbox reservation's transaction.
|
||||
*
|
||||
* <p>Registering an implementation as a bean is what turns consumption on: the broker starter opens
|
||||
* a consumer for every destination at least one handler names. There is no second, batch or manual
|
||||
* settlement contract; the platform settles, after the handler has answered.
|
||||
*
|
||||
* @param <T> the payload type
|
||||
*/
|
||||
public interface MessageHandler<T> {
|
||||
|
||||
/**
|
||||
* The destination, message type and payload type this handler consumes.
|
||||
*
|
||||
* <p>A destination may carry several message types; each type has at most one handler.
|
||||
*
|
||||
* @return what this handler consumes
|
||||
*/
|
||||
MessageDestination<T> destination();
|
||||
|
||||
/**
|
||||
* The schema versions of {@link #destination()}'s message type that its payload class reads.
|
||||
*
|
||||
* <p>This declaration is the consumer's whole registration. The platform decodes a delivery only
|
||||
* against a contract — message type and schema version — it knows the payload class for, and it
|
||||
* builds that list from the handler beans: each version here, with the destination's message
|
||||
* type, decodes into the destination's payload class. A service writes no registration code of
|
||||
* its own, so a handler cannot exist while its messages are dead-lettered as undecodable for want
|
||||
* of one.
|
||||
*
|
||||
* <p>A version the handler does not name is still refused ({@code SCHEMA_VERSION_NOT_REGISTERED})
|
||||
* rather than decoded into a class written for another version. A handler that reads a second
|
||||
* version says so here when the producer starts sending it.
|
||||
*
|
||||
* @return the versions this handler reads; version 1 unless it declares otherwise
|
||||
*/
|
||||
default Set<SchemaVersion> schemaVersions() {
|
||||
return Set.of(new SchemaVersion(1));
|
||||
}
|
||||
|
||||
/**
|
||||
* Handles one delivery.
|
||||
*
|
||||
* @param delivery the decoded message and its metadata
|
||||
* @return a stage completing with the handling outcome
|
||||
*/
|
||||
CompletionStage<HandleResult> handle(MessageDelivery<T> delivery);
|
||||
}
|
||||
+23
@@ -0,0 +1,23 @@
|
||||
package dev.caskeleton.messaging.api.delivery;
|
||||
|
||||
/**
|
||||
* The real scope inside which message order is preserved.
|
||||
*
|
||||
* <p>There is deliberately no {@code GLOBAL} constant. Ordering is a property of a partition, a key
|
||||
* mapping, or a single consumer — never of a whole destination — and advertising a global scope
|
||||
* would promise something no partitioned broker can keep.
|
||||
*/
|
||||
public enum OrderingScope {
|
||||
|
||||
/** No order is promised. */
|
||||
NONE,
|
||||
|
||||
/** Order holds across the destination, which requires a single ordering unit. */
|
||||
DESTINATION,
|
||||
|
||||
/** Order holds inside one broker partition. */
|
||||
PARTITION,
|
||||
|
||||
/** Order holds for one key while its mapping to an ordering unit is stable. */
|
||||
KEY
|
||||
}
|
||||
+20
@@ -0,0 +1,20 @@
|
||||
package dev.caskeleton.messaging.api.destination;
|
||||
|
||||
/**
|
||||
* The publish confirmation a destination profile demands.
|
||||
*
|
||||
* <p>This is the requested level. What the broker actually supplied is reported separately as a
|
||||
* confirmation level on the publish evidence, so a profile asking for replication evidence against
|
||||
* an adapter that can only prove a broker ack fails at startup instead of silently downgrading.
|
||||
*/
|
||||
public enum ConfirmationRequirement {
|
||||
|
||||
/** No confirmation is required; only valid for at-most-once profiles. */
|
||||
NONE,
|
||||
|
||||
/** The broker must acknowledge receipt. */
|
||||
BROKER_ACK,
|
||||
|
||||
/** The broker must acknowledge replication or persistence. */
|
||||
REPLICATION_OR_PERSISTENCE_ACK
|
||||
}
|
||||
+26
@@ -0,0 +1,26 @@
|
||||
package dev.caskeleton.messaging.api.destination;
|
||||
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* A capability snapshot bound to one logical destination.
|
||||
*
|
||||
* <p>Capabilities are per destination, not per broker: the same Kafka cluster offers keyed ordering
|
||||
* on a partitioned topic and none on a share group, and the same RabbitMQ node offers native dead
|
||||
* lettering only where the queue was declared with one.
|
||||
*
|
||||
* @param destination the logical destination
|
||||
* @param broker the adapter's broker name
|
||||
* @param capabilities what the adapter can prove for this destination
|
||||
*/
|
||||
public record DestinationCapabilities(
|
||||
DestinationName destination, String broker, MessagingCapabilities capabilities) {
|
||||
|
||||
public DestinationCapabilities {
|
||||
Objects.requireNonNull(destination, "destination must not be null");
|
||||
Objects.requireNonNull(capabilities, "capabilities must not be null");
|
||||
if (broker == null || broker.isBlank()) {
|
||||
throw new IllegalArgumentException("broker must not be blank");
|
||||
}
|
||||
}
|
||||
}
|
||||
+32
@@ -0,0 +1,32 @@
|
||||
package dev.caskeleton.messaging.api.destination;
|
||||
|
||||
/**
|
||||
* The interaction pattern a destination implements.
|
||||
*
|
||||
* <p>This drives validation rather than transport: an event stream may keep ordering and replay, a
|
||||
* work queue may not, and a request-reply destination needs a correlation strategy no other kind
|
||||
* requires.
|
||||
*/
|
||||
public enum DestinationKind {
|
||||
|
||||
/** Point-to-point command delivered to exactly one logical handler. */
|
||||
ASYNC_COMMAND,
|
||||
|
||||
/** Fact published inside one bounded context. */
|
||||
DOMAIN_EVENT,
|
||||
|
||||
/** Fact published across bounded contexts under a stable schema contract. */
|
||||
INTEGRATION_EVENT,
|
||||
|
||||
/** Competing consumers draining a shared backlog. */
|
||||
WORK_QUEUE,
|
||||
|
||||
/** Fan-out to independent subscribers. */
|
||||
PUBLISH_SUBSCRIBE,
|
||||
|
||||
/** Retained, replayable, partitioned log. */
|
||||
EVENT_STREAM,
|
||||
|
||||
/** Correlated request and reply, available only as an M2 capability. */
|
||||
REQUEST_REPLY
|
||||
}
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
package dev.caskeleton.messaging.api.destination;
|
||||
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
/**
|
||||
* Logical name of a destination.
|
||||
*
|
||||
* <p>The pattern excludes {@code :}, {@code /}, and whitespace so that a broker address can never
|
||||
* be smuggled in as a logical name. {@code topic://orders} has to fail here, otherwise the physical
|
||||
* mapping owned by the destination profile could be bypassed from application code.
|
||||
*
|
||||
* @param value the logical name
|
||||
*/
|
||||
public record DestinationName(String value) {
|
||||
|
||||
private static final Pattern VALID = Pattern.compile("[a-z0-9][a-z0-9.-]{0,159}");
|
||||
|
||||
public DestinationName {
|
||||
if (value == null || !VALID.matcher(value).matches()) {
|
||||
throw new IllegalArgumentException(
|
||||
"destination name must match [a-z0-9][a-z0-9.-]{0,159}: " + value);
|
||||
}
|
||||
}
|
||||
}
|
||||
+26
@@ -0,0 +1,26 @@
|
||||
package dev.caskeleton.messaging.api.destination;
|
||||
|
||||
import dev.caskeleton.messaging.api.MessageType;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* The application-facing handle for a destination.
|
||||
*
|
||||
* <p>It carries a logical name, the catalog message type, and the payload class — never a topic,
|
||||
* exchange, queue, or subject. The physical mapping lives in the destination profile, which is what
|
||||
* lets the same code run against Kafka in production and an in-memory harness in tests.
|
||||
*
|
||||
* @param <T> the payload type
|
||||
* @param name the logical destination name
|
||||
* @param messageType the catalog message type
|
||||
* @param payloadType the payload class
|
||||
*/
|
||||
public record MessageDestination<T>(
|
||||
DestinationName name, MessageType messageType, Class<T> payloadType) {
|
||||
|
||||
public MessageDestination {
|
||||
Objects.requireNonNull(name, "destination name must not be null");
|
||||
Objects.requireNonNull(messageType, "destination messageType must not be null");
|
||||
Objects.requireNonNull(payloadType, "destination payloadType must not be null");
|
||||
}
|
||||
}
|
||||
+75
@@ -0,0 +1,75 @@
|
||||
package dev.caskeleton.messaging.api.destination;
|
||||
|
||||
import java.util.Collections;
|
||||
import java.util.EnumSet;
|
||||
import java.util.Objects;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* What a broker adapter can actually prove or do.
|
||||
*
|
||||
* <p>The common API does not assume every broker supports every feature. When a profile asks for
|
||||
* something absent here the platform fails loudly — at startup where possible, otherwise with a
|
||||
* capability exception — rather than quietly degrading, because a silently weakened guarantee is
|
||||
* indistinguishable from a working one until the incident.
|
||||
*
|
||||
* <p>A set of named capabilities rather than a row of positional booleans. The record used to take
|
||||
* twelve booleans in a fixed order, and an adapter declared itself with {@code new
|
||||
* MessagingCapabilities(true, true, …, false, true)} — a line where swapping two arguments changes
|
||||
* a guarantee and still compiles. Only the capabilities the platform reads are named: a flag
|
||||
* nothing consults is a promise nobody checks.
|
||||
*
|
||||
* @param supported the capabilities the adapter can prove
|
||||
*/
|
||||
public record MessagingCapabilities(Set<Capability> supported) {
|
||||
|
||||
/** One capability the platform consults before relying on it. */
|
||||
public enum Capability {
|
||||
|
||||
/** The destination preserves order inside an ordering unit; required by pause-and-retry. */
|
||||
ORDERED_STREAM,
|
||||
|
||||
/** Delivery can be scheduled for a future instant; required by broker-delayed retry. */
|
||||
DELAYED_DELIVERY,
|
||||
|
||||
/** The broker suppresses duplicate publishes of a stable id; required by publish dedup. */
|
||||
DEDUPLICATED_PUBLISH
|
||||
}
|
||||
|
||||
public MessagingCapabilities {
|
||||
Objects.requireNonNull(supported, "supported must not be null");
|
||||
supported =
|
||||
Collections.unmodifiableSet(
|
||||
supported.isEmpty() ? EnumSet.noneOf(Capability.class) : EnumSet.copyOf(supported));
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a capability set with nothing enabled.
|
||||
*
|
||||
* @return the empty capability set
|
||||
*/
|
||||
public static MessagingCapabilities none() {
|
||||
return new MessagingCapabilities(EnumSet.noneOf(Capability.class));
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a capability set holding exactly the named capabilities.
|
||||
*
|
||||
* @param first the first capability
|
||||
* @param rest the remaining capabilities
|
||||
* @return the capability set
|
||||
*/
|
||||
public static MessagingCapabilities of(Capability first, Capability... rest) {
|
||||
return new MessagingCapabilities(EnumSet.of(first, rest));
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether the adapter can prove a capability.
|
||||
*
|
||||
* @param capability the capability to look up
|
||||
* @return true when it is supported
|
||||
*/
|
||||
public boolean supports(Capability capability) {
|
||||
return supported.contains(Objects.requireNonNull(capability, "capability must not be null"));
|
||||
}
|
||||
}
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
/**
|
||||
* The stable classification a retry engine, DLQ router, and dashboard all agree on.
|
||||
*
|
||||
* <p>Categories exist so that retry decisions are made from a declared class of failure rather than
|
||||
* from exception type matching, which drifts every time a client library is upgraded.
|
||||
*/
|
||||
public enum FailureCategory {
|
||||
|
||||
/** Broker or network fault expected to clear on its own. */
|
||||
TRANSIENT_INFRASTRUCTURE,
|
||||
|
||||
/** The broker or a downstream applied backpressure or a quota. */
|
||||
THROTTLED,
|
||||
|
||||
/** The handler failed in a way that may succeed on redelivery. */
|
||||
PROCESSING_TRANSIENT,
|
||||
|
||||
/** The business rejected the message; redelivery cannot help. */
|
||||
PERMANENT_BUSINESS,
|
||||
|
||||
/** The message repeatedly destroys its consumer and must be parked. */
|
||||
POISON_MESSAGE,
|
||||
|
||||
/** The payload could not be decoded against its schema. */
|
||||
DESERIALIZATION,
|
||||
|
||||
/** Broker authentication failed. */
|
||||
AUTHENTICATION,
|
||||
|
||||
/** Broker authorization denied the operation. */
|
||||
AUTHORIZATION,
|
||||
|
||||
/** The outcome could not be determined. */
|
||||
AMBIGUOUS,
|
||||
|
||||
/** The platform or destination is misconfigured. */
|
||||
CONFIGURATION
|
||||
}
|
||||
+88
@@ -0,0 +1,88 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* A sanitized, transportable description of a failure.
|
||||
*
|
||||
* <p>This travels in reserved headers to retry destinations and DLQs, so it deliberately holds no
|
||||
* payload, no stack trace, no credential, and no actual message key. Stack traces belong in secure
|
||||
* log storage; a DLQ is read by more people than the log is.
|
||||
*
|
||||
* @param category the stable classification
|
||||
* @param code a stable, machine-readable code
|
||||
* @param retryable whether automatic retry is permitted
|
||||
* @param sanitizedMessage a short operator-facing description
|
||||
* @param exceptionType the originating exception's simple type name, when known
|
||||
*/
|
||||
public record FailureDescriptor(
|
||||
FailureCategory category,
|
||||
String code,
|
||||
boolean retryable,
|
||||
String sanitizedMessage,
|
||||
Optional<String> exceptionType) {
|
||||
|
||||
private static final int MAX_MESSAGE_LENGTH = 512;
|
||||
private static final int MAX_CODE_LENGTH = 120;
|
||||
|
||||
public FailureDescriptor {
|
||||
Objects.requireNonNull(category, "failure category must not be null");
|
||||
Objects.requireNonNull(exceptionType, "exceptionType must not be null");
|
||||
if (code == null || code.isBlank() || code.length() > MAX_CODE_LENGTH) {
|
||||
throw new IllegalArgumentException("failure code must contain 1 to 120 characters");
|
||||
}
|
||||
if (sanitizedMessage == null) {
|
||||
throw new IllegalArgumentException("sanitizedMessage must not be null");
|
||||
}
|
||||
if (sanitizedMessage.length() > MAX_MESSAGE_LENGTH) {
|
||||
sanitizedMessage = sanitizedMessage.substring(0, MAX_MESSAGE_LENGTH);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Builds a descriptor whose retryability follows the category's default.
|
||||
*
|
||||
* @param category the classification
|
||||
* @param code the stable code
|
||||
* @param sanitizedMessage the operator-facing description
|
||||
* @return a descriptor
|
||||
*/
|
||||
public static FailureDescriptor of(
|
||||
FailureCategory category, String code, String sanitizedMessage) {
|
||||
return new FailureDescriptor(
|
||||
category, code, defaultRetryable(category), sanitizedMessage, Optional.empty());
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether a category is a retry candidate by default.
|
||||
*
|
||||
* <p>Deserialization, authentication, authorization, and configuration failures are never retried
|
||||
* automatically: each of them fails identically on every redelivery, so retrying only multiplies
|
||||
* the load while the message is still poison.
|
||||
*
|
||||
* <p>A default, not a rule every descriptor follows. A publish rejection may carry {@code
|
||||
* retryable = true} with an authentication or authorization category: the broker did not store
|
||||
* the record, and a credential being rotated or an ACL deployed after the application refuses
|
||||
* every publish for a few minutes and then stops (the Kafka publish classifier). The
|
||||
* consumer-side retry engine requires this default as well as the flag unless its policy names
|
||||
* the category, so redelivery of an unauthorised message is still not retried; only a publisher
|
||||
* that reads {@link #retryable()} sees the difference.
|
||||
*
|
||||
* @param category the classification
|
||||
* @return true when automatic retry is allowed by default
|
||||
*/
|
||||
public static boolean defaultRetryable(FailureCategory category) {
|
||||
return switch (category) {
|
||||
case TRANSIENT_INFRASTRUCTURE, THROTTLED, PROCESSING_TRANSIENT -> true;
|
||||
case PERMANENT_BUSINESS,
|
||||
POISON_MESSAGE,
|
||||
DESERIALIZATION,
|
||||
AUTHENTICATION,
|
||||
AUTHORIZATION,
|
||||
AMBIGUOUS,
|
||||
CONFIGURATION ->
|
||||
false;
|
||||
};
|
||||
}
|
||||
}
|
||||
+49
@@ -0,0 +1,49 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/** The broker denied the operation for these credentials. */
|
||||
public class MessageAuthorizationException extends MessagingException {
|
||||
|
||||
@Serial private static final long serialVersionUID = 1L;
|
||||
|
||||
private static final FailureCategory CATEGORY = FailureCategory.AUTHORIZATION;
|
||||
|
||||
/**
|
||||
* Creates the exception with a stable code and sanitized message.
|
||||
*
|
||||
* @param code the stable failure code
|
||||
* @param sanitizedMessage the operator-facing description
|
||||
*/
|
||||
public MessageAuthorizationException(String code, String sanitizedMessage) {
|
||||
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the exception with an originating cause.
|
||||
*
|
||||
* @param code the stable failure code
|
||||
* @param sanitizedMessage the operator-facing description
|
||||
* @param cause the originating throwable
|
||||
*/
|
||||
public MessageAuthorizationException(String code, String sanitizedMessage, Throwable cause) {
|
||||
super(
|
||||
new FailureDescriptor(
|
||||
CATEGORY,
|
||||
code,
|
||||
false,
|
||||
sanitizedMessage,
|
||||
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
|
||||
cause);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the exception from an explicit descriptor.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
*/
|
||||
public MessageAuthorizationException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Admission was refused because the platform is already at its in-flight or buffer ceiling.
|
||||
*
|
||||
* <p>Retryable, and deliberately raised rather than absorbed by an unbounded wait. Blocking the
|
||||
* caller until a slot frees turns producer-side saturation into thread exhaustion in the calling
|
||||
* application, which is a far worse failure than a fast rejection the caller can shed or retry.
|
||||
*
|
||||
* <p>Nothing was transmitted when this is thrown, so the message has no ambiguity: the caller may
|
||||
* resubmit it under the same {@code messageId} without risking a duplicate.
|
||||
*/
|
||||
public class MessageBackpressureException extends MessagingException {
|
||||
|
||||
@Serial private static final long serialVersionUID = 1L;
|
||||
|
||||
private static final FailureCategory CATEGORY = FailureCategory.TRANSIENT_INFRASTRUCTURE;
|
||||
|
||||
/**
|
||||
* Creates the exception with a stable code and sanitized message.
|
||||
*
|
||||
* @param code the stable failure code
|
||||
* @param sanitizedMessage the operator-facing description
|
||||
*/
|
||||
public MessageBackpressureException(String code, String sanitizedMessage) {
|
||||
super(new FailureDescriptor(CATEGORY, code, true, sanitizedMessage, Optional.empty()));
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the exception from an explicit descriptor.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
*/
|
||||
public MessageBackpressureException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
+54
@@ -0,0 +1,54 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* The publish deadline expired before a confirmation arrived.
|
||||
*
|
||||
* <p>A timeout is not a rejection. The bytes may already be replicated, so this is classified as
|
||||
* ambiguous rather than failed.
|
||||
*/
|
||||
public class MessagePublishTimeoutException extends MessagingException {
|
||||
|
||||
@Serial private static final long serialVersionUID = 1L;
|
||||
|
||||
private static final FailureCategory CATEGORY = FailureCategory.AMBIGUOUS;
|
||||
|
||||
/**
|
||||
* Creates the exception with a stable code and sanitized message.
|
||||
*
|
||||
* @param code the stable failure code
|
||||
* @param sanitizedMessage the operator-facing description
|
||||
*/
|
||||
public MessagePublishTimeoutException(String code, String sanitizedMessage) {
|
||||
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the exception with an originating cause.
|
||||
*
|
||||
* @param code the stable failure code
|
||||
* @param sanitizedMessage the operator-facing description
|
||||
* @param cause the originating throwable
|
||||
*/
|
||||
public MessagePublishTimeoutException(String code, String sanitizedMessage, Throwable cause) {
|
||||
super(
|
||||
new FailureDescriptor(
|
||||
CATEGORY,
|
||||
code,
|
||||
false,
|
||||
sanitizedMessage,
|
||||
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
|
||||
cause);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the exception from an explicit descriptor.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
*/
|
||||
public MessagePublishTimeoutException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
+49
@@ -0,0 +1,49 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/** The payload's schema is incompatible with the registered contract. */
|
||||
public class MessageSchemaIncompatibleException extends MessagingException {
|
||||
|
||||
@Serial private static final long serialVersionUID = 1L;
|
||||
|
||||
private static final FailureCategory CATEGORY = FailureCategory.DESERIALIZATION;
|
||||
|
||||
/**
|
||||
* Creates the exception with a stable code and sanitized message.
|
||||
*
|
||||
* @param code the stable failure code
|
||||
* @param sanitizedMessage the operator-facing description
|
||||
*/
|
||||
public MessageSchemaIncompatibleException(String code, String sanitizedMessage) {
|
||||
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the exception with an originating cause.
|
||||
*
|
||||
* @param code the stable failure code
|
||||
* @param sanitizedMessage the operator-facing description
|
||||
* @param cause the originating throwable
|
||||
*/
|
||||
public MessageSchemaIncompatibleException(String code, String sanitizedMessage, Throwable cause) {
|
||||
super(
|
||||
new FailureDescriptor(
|
||||
CATEGORY,
|
||||
code,
|
||||
false,
|
||||
sanitizedMessage,
|
||||
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
|
||||
cause);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the exception from an explicit descriptor.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
*/
|
||||
public MessageSchemaIncompatibleException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
+49
@@ -0,0 +1,49 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/** The payload could not be encoded or decoded. */
|
||||
public class MessageSerializationException extends MessagingException {
|
||||
|
||||
@Serial private static final long serialVersionUID = 1L;
|
||||
|
||||
private static final FailureCategory CATEGORY = FailureCategory.DESERIALIZATION;
|
||||
|
||||
/**
|
||||
* Creates the exception with a stable code and sanitized message.
|
||||
*
|
||||
* @param code the stable failure code
|
||||
* @param sanitizedMessage the operator-facing description
|
||||
*/
|
||||
public MessageSerializationException(String code, String sanitizedMessage) {
|
||||
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the exception with an originating cause.
|
||||
*
|
||||
* @param code the stable failure code
|
||||
* @param sanitizedMessage the operator-facing description
|
||||
* @param cause the originating throwable
|
||||
*/
|
||||
public MessageSerializationException(String code, String sanitizedMessage, Throwable cause) {
|
||||
super(
|
||||
new FailureDescriptor(
|
||||
CATEGORY,
|
||||
code,
|
||||
false,
|
||||
sanitizedMessage,
|
||||
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
|
||||
cause);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the exception from an explicit descriptor.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
*/
|
||||
public MessageSerializationException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user