diff --git a/.github/workflows/integration-main.yml b/.github/workflows/integration-main.yml index 6f8d8366..c69cb539 100644 --- a/.github/workflows/integration-main.yml +++ b/.github/workflows/integration-main.yml @@ -162,6 +162,8 @@ jobs: # and container start-up between lanes. A hosted runner adds cold image pulls (about 5 GB # uncompressed across the PostgreSQL, MongoDB, Kafka, nginx, httpbin and Toxiproxy images) and a # cold Gradle cache; expect 25 to 40 minutes (an estimate, not a measured hosted run). The 240-minute timeout is a ceiling for a hung container, not a budget. + # Since 2026-11-08 messagingCertificationTest and the messaging starter's integrationTest run in the + # messaging-library repository, not here; the measurement above predates that. integration-check: runs-on: ubuntu-latest timeout-minutes: 240 diff --git a/.github/workflows/messaging-certification.yml b/.github/workflows/messaging-certification.yml deleted file mode 100644 index 726ba8e8..00000000 --- a/.github/workflows/messaging-certification.yml +++ /dev/null @@ -1,51 +0,0 @@ -# The messaging platform's broker certification lane. -# -# Separate from ci-quality-gates.yml because it needs a container runtime and several minutes of it. -# The lane deliberately carries no Docker guard: every other container suite in the messaging tree -# skips with a stated reason when Docker is absent, and a certification lane that skipped would -# report success for a broker nobody started — which is the exact claim the evidence exists to rule -# out. -# -# The job runs the evidence gate rather than the lane, and the gate depends on the lane. What it -# proves is not only that the scenarios pass but that the committed manifest -# (messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl) is what this -# run produced, so "certified against a live broker" cannot be restored by editing a file. -name: messaging-certification - -on: - pull_request: - paths: - - "src/platforms/messaging/**" - - ".github/workflows/messaging-certification.yml" - # Every Gradle job here installs its toolchain through this composite action, so a change to - # it changes what this gate runs. - - ".github/actions/setup-gradle-java/action.yml" - schedule: - - cron: "41 4 * * 3" - workflow_dispatch: - -permissions: - contents: read - -env: - # Reuse would hand one scenario the broker another scenario had already faulted. - TESTCONTAINERS_REUSE_ENABLE: "false" - -jobs: - broker-certification: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Certify the Kafka adapter against a real broker - working-directory: src - # GITHUB_SHA is read by the lane and written into every evidence line, because "certified" - # is a claim about one source tree. - run: ./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence --stacktrace - - name: Publish the certification evidence - if: always() - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2 - with: - name: messaging-broker-certification-evidence - path: src/platforms/messaging/messaging-kafka/build/messaging-certification/ - if-no-files-found: warn diff --git a/AGENTS.md b/AGENTS.md index f990d2ef..02339ba8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +17,7 @@ Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버 - Gradle 루트는 `src/`다. leaf 목록·경로·Gradle path·허용 의존의 정본은 registry `src/config/architecture/modules.json`이다. 문서는 leaf 개수를 적지 않는다. - 방향: `app-bootstrap → adapter:inbound:*·adapter:outbound:* → application-core → domain-core`, 실행 모듈 → `shared-contract`. 개별 edge는 registry만 정한다. - 지역 규칙은 작업 파일과 가장 가까운 폴더의 `AGENTS.md`다(leaf, family, `src/build-logic`). 테스트·설정·Docker·문서처럼 폴더를 가로지르는 규칙은 `.claude/rules/`다. -- 저장소 루트와 `src/` 최상위에는 정해진 것만 둔다(허용 목록은 `scripts/check-repo-layout.py`). `src/platforms/*`는 계층이 아닌 들여온 제품, `src/composition/*`는 조립만 한다. +- 저장소 루트와 `src/` 최상위에는 정해진 것만 둔다(허용 목록은 `scripts/check-repo-layout.py`). 계층이 아닌 라이브러리는 이 repo에 두지 않고 별도 repo에서 버전으로 받는다(`docs/work/reference/related-repos.md`). `src/composition/*`는 조립만 한다. - capability는 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 켜고 끈다. 기준은 `docs/manual/10-capabilities.md`. 문서 위치 규칙은 `docs/README.md`. ## 맡은 일 diff --git a/README.md b/README.md index 1f587291..ab6312a6 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ ca-skeleton은 Java 21과 Spring Boot로 만든 Gradle 멀티모듈 백엔드 | `compose/` | `compose.yaml`이 마운트하는 보조 파일(Keycloak realm, Redis ACL, MinIO 초기화) | [compose/redis/acl/README.md](compose/redis/acl/README.md) | | `.github/` | workflow, 공용 action, PR 양식, 의존성 취약점 정책 | [.github/dependency-vulnerability-policy.md](.github/dependency-vulnerability-policy.md) | -`src/` 아래 폴더는 계층 leaf, 조립, 들여온 제품, Gradle 표준 폴더로 나뉜다. leaf는 Gradle 프로젝트 하나이고, leaf 목록·경로·허용 의존은 registry `src/config/architecture/modules.json`이 정한다. +`src/` 아래 폴더는 계층 leaf, 조립, Gradle 표준 폴더로 나뉜다. leaf는 Gradle 프로젝트 하나이고, leaf 목록·경로·허용 의존은 registry `src/config/architecture/modules.json`이 정한다. | 폴더 | 책임 | 기본 조립에 들어가나 | | --- | --- | --- | @@ -27,7 +27,6 @@ ca-skeleton은 Java 21과 Spring Boot로 만든 Gradle 멀티모듈 백엔드 | `adapter/outbound/` | port 뒤의 구현: 영속성(JPA·MongoDB), Redis, 메시징, 알림, 객체 저장소, 파일 서버, HTTP client, identifier, 공용 기반(support) | `support`·`identifier`만 들어간다 | | `composition/` | 조립만 하는 leaf: 서비스 런타임 배선, outbox relay, 멱등성 executor, durable operation, 알림·파일 서버 플랫폼 | `service-runtime`·`outbox-relay`·`idempotency`·`durable-operation`이 들어간다. 뒤의 셋은 필요한 port가 생기기 전에는 아무것도 만들지 않는다 | | `app-bootstrap/` | Spring Boot 진입점과 조립 루트(composition root, 모든 모듈을 엮는 곳) | 들어간다 | -| `platforms/` | 들여온 제품: `messaging`(메시징 플랫폼). gRPC 플랫폼 라이브러리는 2026-11-08에 별도 repo `grpc-library`로 옮겼다([관련 저장소](docs/work/reference/related-repos.md)) | 들어가지 않는다. adapter를 거쳐서만 닿는다 | | `build-logic/`, `config/`, `gradle/` | 빌드 규칙(convention plugin), 빌드 전체 도구 설정과 registry, wrapper와 버전 카탈로그 | 빌드 도구 | 의존은 항상 바깥에서 안으로 흐른다. adapter가 core의 port에 의존하고, core는 adapter를 모른다. diff --git a/docs/README.md b/docs/README.md index 7b84d7f8..db1042f3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -46,7 +46,6 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마 | `fileserver/` | 파일 서버 | | `httpclient/` | 외부 HTTP 호출(HTTP client 플랫폼) | | `jpa/` | JPA·PostgreSQL 영속성 | -| `messaging/` | 메시징 adapter | | `mongodb/` | MongoDB 문서 영속성 | | `mongodb/advanced/` | MongoDB 고급 기능(암호화, 멀티 테넌시, 샤딩). 설정 키가 아니라 라이브러리 API로 켠다 | | `mongodb/runbooks/` | MongoDB 장애 대응 | diff --git a/docs/capability-status.md b/docs/capability-status.md index 241afdf7..d00f37eb 100644 --- a/docs/capability-status.md +++ b/docs/capability-status.md @@ -29,7 +29,7 @@ lanes and CI; it is not a deployment artifact. | --- | --- | --- | --- | --- | --- | | Relational persistence (JPA/PostgreSQL) | `ca-skeleton.persistence-jpa.enabled` / `APP_PERSISTENCE_JPA_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-jpa')`) | yes | Not in the default composition. The one line brings everything — its own `AutoConfiguration.imports` (`PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig`, `JpaStartupAutoConfiguration`), its environment handling (`JpaActivationEnvironmentPostProcessor`, `spring.factories`: readiness `db` while on; with `false` it also excludes Boot's JDBC, Hibernate, Spring Data JPA and Flyway auto-configuration, so no DataSource is bound), the startup guards (Flyway strategy, datasource/OSIV/DDL/pool/TLS/vendor checks, exit codes unchanged) and its settings (`config/module-defaults/persistence-jpa.yml`). `persistence-jpa:PersistenceJpaCapabilityAssemblyTest` proves the module assembles on its own; the `postgresql*IntegrationTest` readiness lanes, run by `integration-main.yml` → `integration-check` (`:integrationCheck`), qualify it against PostgreSQL. `bootRunH2` adds the module to its own classpath only. | | Document persistence (MongoDB) | `ca-skeleton.persistence-mongo.enabled` / `APP_PERSISTENCE_MONGO_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-mongo')`) | yes | On when present; `false` also excludes Boot's Mongo auto-configuration (`MongoCapabilityActivationTest`). The connection-source rule (`SPRING_MONGODB_URI` or the selected profile's `uri-secret`) is checked by the module's own `MongoDefaultsEnvironmentPostProcessor`. Six container lanes (`mongoReplicaSetTest`, `mongoFailoverTest`, …), run by `integration-main.yml` → `integration-check` (`:integrationCheck`) | -| Messaging (Kafka) | `app.messaging.enabled` / `APP_MESSAGING_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:messaging-kafka')`, which brings the application bridge, the legacy `KafkaSender` seam and the vendored platform with its Kafka transport) | Kafka only | On when present (`KafkaCapabilityActivationTest`). `messaging-kafka:messagingCertificationTest` behind `verifyMessagingCertificationEvidence`, run by `messaging-certification.yml`; the starter's `integrationTest` is the live Kafka round trip. Kafka is the only registered broker; the RabbitMQ broker keys were removed (no transport). | +| Messaging (Kafka) | `app.messaging.enabled` / `APP_MESSAGING_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:messaging-kafka')`, which brings the application bridge and the messaging library `dev.cakit.messaging` (messaging-library repo, catalog `messagingLibrary`) with its Kafka transport) | Kafka only | On when present (`KafkaCapabilityActivationTest`). The application's own publish and consume paths run against a live Kafka in `messagingKafkaRelayIntegrationTest` and `messagingInboxRedeliveryIntegrationTest`. The library's broker certification (`verifyMessagingCertificationEvidence`) runs in the messaging-library repo's main stage since 2026-11-08. Kafka is the only registered broker; the RabbitMQ broker keys were removed (no transport). | | Redis capabilities (cache / rate-limit / lease / idempotency) | `app.redis.enabled` / `APP_REDIS_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:cache-redis')`, which brings `redis-runtime`) | yes | `cache-redis:redisContainerContractTest` (Testcontainers Redis, `integrationCheck`); `cache-redis:redisTopologyTest`, run by `redis-sdk-topology.yml`. Not in the default composition. On when present; `false` contributes no Redis bean — no settings, client, connection, thread or health contributor. The module owns its readiness contribution (`RedisReadinessGroupPostProcessor`, `spring.factories`) and its settings (`config/module-defaults/cache-redis.yml`: `app.redis.enabled`, `app.rate-limit.*`, the Redis `ca-skeleton.capabilities.*`). No `app-bootstrap` main source names a Redis type. | | Request idempotency | `APP_IDEMPOTENCY_PROVIDER` (`disabled` \| `redis` \| `postgresql`; a selector, not an on/off key) | yes | yes | Redis and PostgreSQL | One generation: the application `IdempotencyExecutor`, built once by `composition:idempotency` (`IdempotencyAutoConfiguration`) over the one store the selected provider contributes (`cache-redis` or `persistence-jpa`); startup is refused unless exactly one store exists. `app-bootstrap`이 그 모듈을 `runtimeOnly` 한 줄로 받고, 다른 조립은 없다. Redis is covered by the row above. PostgreSQL has `persistence-jpa:postgresqlIdempotencyIntegrationTest`, run by `integration-main.yml` → `integration-check` (`:integrationCheck`). The `postgresql` provider refuses a non-PostgreSQL data source, so `bootRunH2` uses `disabled` or `redis`. Each store comes with its module: `postgresql` needs the persistence-jpa line, `redis` the cache-redis one. | | Transactional outbox relay | `ca-skeleton.outbox.enabled` / `APP_OUTBOX_ENABLED`, `false` (+ `APP_OUTBOX_RELAY_ENABLED`, `false`; persistence-jpa settings) | yes | yes (with the persistence-jpa line; the scheduler also needs the messaging-kafka line) | yes | The store and its settings are persistence-jpa's; the relay (`OutboxConfig`) is application composition in `app-bootstrap` because a driven adapter must not build or call a use case. It turns on only when an `OutboxStorePort` bean exists, and the scheduler only when an `OutboxMessagePublishPort` does (the messaging bridge), each ordered after its contributor by `afterName` — so an environment with no publisher keeps its PENDING rows. The bridge registers no stand-in publisher: a present-and-enabled bridge with a blank broker and no canonical transport is refused at startup. `postgresqlLegacyOutboxConcurrentRelayIntegrationTest` qualifies claim/fencing against PostgreSQL. | diff --git a/docs/design/2026-07-28-messaging-production-capability-design.md b/docs/design/2026-07-28-messaging-production-capability-design.md index 9d5f4759..c99ac18a 100644 --- a/docs/design/2026-07-28-messaging-production-capability-design.md +++ b/docs/design/2026-07-28-messaging-production-capability-design.md @@ -4,7 +4,7 @@ - 상태: 채택 - 작성일: 2026-07-28 - 요약: 메시징을 운영 가능한 capability로 올리는 상세 설계다. -- 현재 정본: `docs/messaging/support-matrix.md` +- 현재 정본: `docs/manual/09-outbox-events.md` # Messaging Production Capability Deep Design diff --git a/docs/design/2026-08-10-messaging-platform-design.md b/docs/design/2026-08-10-messaging-platform-design.md index 2b281b94..a07ae7c6 100644 --- a/docs/design/2026-08-10-messaging-platform-design.md +++ b/docs/design/2026-08-10-messaging-platform-design.md @@ -4,7 +4,7 @@ - 상태: 채택 - 작성일: 2026-08-10 - 요약: 메시지 생성부터 브로커 수락, 소비자 정산까지 증거로 다루는 메시징 플랫폼 설계다. -- 현재 정본: `docs/messaging/support-matrix.md` +- 현재 정본: 없음 — 메시징 플랫폼은 2026-11-08에 별도 repo messaging-library(Maven group dev.cakit.messaging)로 옮겼다. 지금 동작은 그 repo의 docs/messaging/support-matrix.md다 # Messaging Platform 설계서 diff --git a/docs/design/2026-09-18-messaging-platform-bridge-design.md b/docs/design/2026-09-18-messaging-platform-bridge-design.md index 52051b27..12462f20 100644 --- a/docs/design/2026-09-18-messaging-platform-bridge-design.md +++ b/docs/design/2026-09-18-messaging-platform-bridge-design.md @@ -4,7 +4,7 @@ - 상태: 확인 안 함 - 작성일: 2026-09-18 - 요약: 애플리케이션 전용 브로커 이음매를 메시징 플랫폼으로 가는 bridge 하나로 바꾸는 설계다. -- 현재 정본: `docs/messaging/support-matrix.md` +- 현재 정본: `docs/manual/09-outbox-events.md` # Messaging Platform Bridge Design diff --git a/docs/history/packages/messaging/README.md b/docs/history/packages/messaging/README.md index f35c7a44..d96b5b96 100644 --- a/docs/history/packages/messaging/README.md +++ b/docs/history/packages/messaging/README.md @@ -4,7 +4,7 @@ - 상태: 보관 - 작성일: 2026-08-13 - 요약: 메시징 설계 패키지가 처음 납품됐을 때의 안내다. 본문 문서는 docs/design과 docs/history/plans에 있다. -- 현재 정본: `docs/messaging/support-matrix.md` +- 현재 정본: 없음 — 메시징 플랫폼은 2026-11-08에 별도 repo messaging-library(Maven group dev.cakit.messaging)로 옮겼다. 지금 동작은 그 repo의 docs/messaging/support-matrix.md다 > **보존 안내** — 이 파일은 저장소 루트 `messaging-superpowers-package/` 에 있던 납품 패키지의 README다. diff --git a/docs/history/packages/messaging/VALIDATION.md b/docs/history/packages/messaging/VALIDATION.md index 3ccec775..d1a8720b 100644 --- a/docs/history/packages/messaging/VALIDATION.md +++ b/docs/history/packages/messaging/VALIDATION.md @@ -4,7 +4,7 @@ - 상태: 보관 - 작성일: 2026-08-13 - 요약: 메시징 설계 패키지를 받을 때 한 정적 검증 결과다. -- 현재 정본: `docs/messaging/support-matrix.md` +- 현재 정본: 없음 — 메시징 플랫폼은 2026-11-08에 별도 repo messaging-library(Maven group dev.cakit.messaging)로 옮겼다. 지금 동작은 그 repo의 docs/messaging/support-matrix.md다 # Messaging Superpowers 문서 정적 검증 diff --git a/docs/history/plans/2026-07-28-messaging-first-r2-polling-producer.md b/docs/history/plans/2026-07-28-messaging-first-r2-polling-producer.md index 3516ae5a..e2e9c7f7 100644 --- a/docs/history/plans/2026-07-28-messaging-first-r2-polling-producer.md +++ b/docs/history/plans/2026-07-28-messaging-first-r2-polling-producer.md @@ -4,7 +4,7 @@ - 상태: 확인 안 함 - 작성일: 2026-07-28 - 요약: typed 통합 이벤트에서 시작하는 첫 운영 기준 메시징 경로(R2 polling producer)를 만드는 실행 계획이다. -- 현재 정본: `docs/messaging/support-matrix.md` +- 현재 정본: `docs/manual/09-outbox-events.md` # Messaging First R2 Polling Producer Implementation Plan diff --git a/docs/history/plans/2026-08-10-messaging-platform-implementation-plan.md b/docs/history/plans/2026-08-10-messaging-platform-implementation-plan.md index 0ebc3715..326b5052 100644 --- a/docs/history/plans/2026-08-10-messaging-platform-implementation-plan.md +++ b/docs/history/plans/2026-08-10-messaging-platform-implementation-plan.md @@ -4,7 +4,7 @@ - 상태: 확인 안 함 - 작성일: 2026-08-10 - 요약: 메시징 플랫폼(증거 기반 발행, 중복 안전 소비, Kafka·RabbitMQ, outbox·inbox)을 만드는 실행 계획이다. -- 현재 정본: `docs/messaging/support-matrix.md` +- 현재 정본: 없음 — 메시징 플랫폼은 2026-11-08에 별도 repo messaging-library(Maven group dev.cakit.messaging)로 옮겼다. 지금 동작은 그 repo의 docs/messaging/support-matrix.md다 # Messaging Platform Implementation Plan diff --git a/docs/history/plans/2026-09-18-messaging-platform-bridge.md b/docs/history/plans/2026-09-18-messaging-platform-bridge.md index 51c669a2..c19c91f3 100644 --- a/docs/history/plans/2026-09-18-messaging-platform-bridge.md +++ b/docs/history/plans/2026-09-18-messaging-platform-bridge.md @@ -4,7 +4,7 @@ - 상태: 끝남 - 작성일: 2026-09-18 - 요약: 통합 이벤트 발행 경계를 메시징 플랫폼 bridge에 잇는 실행 계획이다. -- 현재 정본: `docs/messaging/support-matrix.md` +- 현재 정본: `docs/manual/09-outbox-events.md` # Messaging Platform Bridge Implementation Plan diff --git a/docs/ledger/estimates.jsonl b/docs/ledger/estimates.jsonl index 8acce5ac..e3638e1b 100644 --- a/docs/ledger/estimates.jsonl +++ b/docs/ledger/estimates.jsonl @@ -2,3 +2,5 @@ {"schema": 1, "kind": "actual", "task": "h3-backend-harness", "recorded_at": "2026-11-07T23:13+09:00", "transcript": "d5a4c736-f1d6-45ab-acbe-8857526585b9", "minutes": 94, "active_minutes": 68, "calls": 270, "output_tokens": 345525, "cache_read_tokens": 132822591, "max_context": 805096, "within": "p30", "result": "done", "commits": ["08f93212", "3c73fc33", "38891071", "c67c7131", "67ecae2c", "37c88fed", "59dff004", "c8db79a7", "d9059806", "7140f279", "93b70b06", "248df518"], "why": "모든 값이 p30보다 작았다. 바꿀 파일 수(약 120, 실제 190여)를 호출 수로 옮겼는데, 이동·참조 수정 수십 파일을 스크립트 한 번으로 묶어 파일당 호출이 거의 없었다. desktop 대기는 예측과 비슷했지만(합친 트리 한 번 27분, 중단한 두 번) 작업 중 시간에서는 빈틈마다 5분으로 잘린다. 다음 예측은 파일 수가 아니라 손으로 판단할 결정 수(이번 약 25)와 desktop 실행 횟수를 근거로 쓴다. 실측은 23:12까지의 세션 기록이고, 뒤의 커밋·PR·보고는 들어 있지 않다"} {"schema": 1, "kind": "estimate", "task": "x2-grpc-library", "recorded_at": "2026-11-08T10:50+09:00", "transcript": "dc504d75-c815-4dfa-98dd-80c224db983f", "started_at": "2026-11-08T10:47:39+09:00", "base": "22df3525", "task_kind": "improve", "size": "large", "minutes": {"p30": 150, "p50": 220, "p80": 330}, "calls": {"p30": 350, "p50": 500, "p80": 750}, "output_tokens": {"p30": 400000, "p50": 600000, "p80": 900000}, "basis": "착수 노트(공유 노트 x2-grpc-library.md, 10:50)에 쓴 값을 옮겼다. 선례 h3-backend-harness 작업 중 68분·호출 270·출력 34.6만(손으로 판단한 결정 약 25, desktop 실행 3회). 이번은 결정 약 35(배치, build-logic 줄이기, 배포·서명·SBOM, buf 정책, testFixtures 사본, workflow 셋, 템플릿 지우기 20여 파일, 하네스)와 desktop 실행이 라이브러리 반복 5~8회 + 템플릿 게이트 묶음 2~3회 + Gitea Actions 실행 2회 이상이라 h3의 세 배 가까이로 봤다"} {"schema": 1, "kind": "actual", "task": "x2-grpc-library", "recorded_at": "2026-11-08T14:02+09:00", "transcript": "dc504d75-c815-4dfa-98dd-80c224db983f", "minutes": 194, "active_minutes": 99, "calls": 330, "output_tokens": 303528, "cache_read_tokens": 136483127, "max_context": 746863, "within": "p30", "result": "done", "commits": ["5e204e6a", "2921f596", "91804ec1", "57988c2e", "grpc-library:76a9244", "grpc-library:414666c", "grpc-library:41d73a1", "grpc-library:239547b", "grpc-library:90306b2", "grpc-library:8d705bc", "grpc-library:ce83f4d", "grpc-library:39d4b6d", "grpc-library:c10f4af"], "why": "모든 값이 p30보다 작았다(작업 중 99분, 벽시계 194분). 예측은 desktop 대기(템플릿 게이트 1회차 약 65분, 라이브러리 반복 6회, 재실행 3회)를 작업 중 시간에 넣었는데, 대기는 빈틈마다 5분으로 잘리고 그동안 문서·라이브러리 일을 같이 했다. 패키지 이름 바꾸기 315파일, SpotBugs 제외 정리, 템플릿 삭제 397파일을 스크립트 몇 번으로 끝내 결정 수(약 35) 대비 호출이 적었다. 다음 예측은 desktop 대기를 시간에서 빼고 결정 수와 실행 횟수만으로 잡는다. 라이브러리 PR #1 병합은 권한 분류기에 막혀 남았다"} +{"schema": 1, "kind": "estimate", "task": "x3-messaging-library", "recorded_at": "2026-11-08T16:00+09:00", "transcript": "462a3688-07fc-4460-a565-62afcf6ae072", "started_at": "2026-11-08T15:55:32+09:00", "base": "2959eff0", "task_kind": "improve", "size": "large", "minutes": {"p30": 140, "p50": 200, "p80": 300}, "calls": {"p30": 420, "p50": 580, "p80": 850}, "output_tokens": {"p30": 450000, "p50": 650000, "p80": 950000}, "basis": "착수 노트(공유 노트 x3-messaging-library.md, 16:00)에 쓴 값을 옮겼다. 선례 x2-grpc-library 1차(만들기~PR) 작업 중 99분·호출 330·출력 30.4만, 결정 약 35. 이번은 결정 약 45로 봤다: gRPC 결정(배치·build-logic·배포·workflow)은 본보기를 따르면 되지만 템플릿에 소비자가 있어 좌표 전환 4 leaf, migration 결합, 계약 테스트 나누기, registry 「허용 라이브러리」 칸(build-logic 변경과 시험), lockfile, Kafka 인증 lane의 runner 실행이 새로 붙는다. desktop 실행은 라이브러리 4~6회 + 템플릿 게이트 묶음 2~3회 + runner 3회 이상. desktop 대기는 시간에서 뺐다(x2 회고)"} +{"schema": 1, "kind": "actual", "task": "x3-messaging-library", "recorded_at": "2026-11-08T22:00+09:00", "transcript": "462a3688-07fc-4460-a565-62afcf6ae072", "minutes": 361, "active_minutes": 110, "calls": 346, "output_tokens": 271613, "cache_read_tokens": 177759293, "max_context": 820126, "within": "p30", "result": "done", "commits": ["77b81811", "5af94155", "7dc5725f", "messaging-library:f593229", "messaging-library:2e9298e", "messaging-library:f076f6a", "messaging-library:2e7e073", "messaging-library:dd19478", "messaging-library:d2bacc6", "messaging-library:31c5178"], "why": "모든 값이 p30보다 작았다(작업 중 110분, 벽시계 361분). 벽시계의 큰 몫은 기다림이었다: 총괄의 PR #1 병합·태그·release(약 50분), 템플릿 게이트 묶음(17:12~20:12, 공유 잠금 대기 포함), 노트북 네트워크 끊김(17:30~21:50). 작업 중 시간은 빈틈마다 5분으로 잘려 그 대기가 거의 빠졌다. 본보기(grpc-library)의 build-logic·workflow·release 스크립트를 복사하고 이름 바꾸기·삭제·SpotBugs 정리를 스크립트로 해 결정 수(약 45) 대비 호출이 적었다. 예측에 없던 일: 구조 리뷰가 찾은 system caller 규칙 결함(MessageHandler가 프로젝트 밖 타입이 됨)과 순서 시험 두 개. 다음 예측은 소비자가 있는 분리면 「리뷰가 찾는 규칙 결함」 1~2건 몫을 더한다"} diff --git a/docs/manual/07-authorization.md b/docs/manual/07-authorization.md index 4f56ff53..df99cb18 100644 --- a/docs/manual/07-authorization.md +++ b/docs/manual/07-authorization.md @@ -105,7 +105,7 @@ client가 같은 이름의 역할을 정의해도 이 서비스 권한이 되지 | 시스템 호출자만 | inbound adapter가 그 클래스에 의존하면 빌드 실패. `@SystemCaller(reason = "...")`를 단 클래스와 그 안에 중첩된 클래스만 예외 | `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`(`ApplicationBoundaryArchitectureTest`) | | 표시 검사 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스는 `..adapter.inbound.messaging..`·`..adapter.inbound.scheduler..`에만 있고, 사용자 전송 타입(controller·JAX-RS·GraphQL·STOMP mapping과 channel interceptor·gRPC·servlet)에 의존하지 않는다 | `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`(같은 파일) | | 전송 → 시스템 호출자 금지 | 사용자 전송 클래스가 `@SystemCaller`나, 그 클래스가 구현·상속하는 프로젝트 타입(작업의 인터페이스 등)에 의존하면 빌드 실패. 중간 클래스를 거쳐도 잡는다. 사용자 전송 클래스는 넷이다. ① 사용자 전송 패키지에 있는 클래스. ② 설정(`@Configuration`·`@AutoConfiguration`) 클래스 자신이 요청 처리기 타입(함수형 `RouterFunction`·`HandlerFunction`, `@RestController`·`@RequestMapping`, servlet·`Filter`·`HandlerInterceptor`, `WebSocketHandler`, GraphQL `DataFetcher`·`RuntimeWiringConfigurer`, gRPC `BindableService`·`ServerInterceptor`, STOMP `ChannelInterceptor`·`ExecutorChannelInterceptor` 등)에 의존하는 것. 요청 처리 코드를 설정에 직접 쓴 경우와 등록만 한 경우가 모두 든다. channel interceptor를 구현한 설정은 프레임마다 자기 메서드가 돈다. interceptor를 `@Bean`으로 내놓는 설정은 route를 등록하는 설정과 같다. 함수형 route나 data fetcher를 람다로 쓰면 그 코드가 설정 클래스의 메서드로 컴파일되어 설정이 곧 endpoint다. 처리 코드를 다른 클래스에 두고 메서드 참조로 등록만 해도(`route().GET("/orders", orders::list)`) 설정은 route builder에 의존한다. 클래스 의존으로는 등록과 처리 코드를 가를 수 없어서 둘 다 사용자 전송으로 센다. ③ 설정 안에 중첩된 클래스 가운데 사용자 전송 타입에 의존하는 것. 중첩된 JAX-RS 자원·`@ServerEndpoint`, `configureClientInboundChannel`에서 등록하는 STOMP channel interceptor(익명 클래스여도, STOMP 헤더를 읽지 않아도)도 여기서 잡힌다. 설정용 타입(`WebMvcConfigurer`·`WebSocketConfigurer`·STOMP broker 설정과 그 registry, CORS 설정, `RequestMethod`)에만 의존하는 중첩 클래스는 설정의 일부로 본다. inbound channel의 thread 수만 정하는 설정도 설정용이다. ④ 그 밖의 클래스 가운데 사용자 전송 타입에 의존하는 것. 사용자 전송 패키지 밖에 둔 channel interceptor가 여기에 든다. 그래서 handler를 bean으로 등록하는 설정은 같은 클래스에서 `WebMvcConfigurer`(설정 필드를 읽는 익명 클래스여도)·CORS 설정·controller bean을 함께 만들어도 걸리지 않는다. 같은 클래스에 "지금 실행" route·data fetcher·interceptor를 쓰거나, route를 등록하거나, 안에 중첩한 endpoint가 작업을 부르면(설정의 메서드를 거쳐 불러도) 걸린다. route·data fetcher·interceptor 등록은 handler bean을 만드는 설정과 다른 설정에 둔다. 설정이 만드는 controller는 controller 자신이 검사받는다 | `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`(같은 파일) | -| 프로젝트 밖 상위 타입 금지 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스(익명·지역 클래스와 예외 제외)는 프로젝트(`dev.caskeleton..`) 밖의 클래스·인터페이스를 상속·구현하지 않는다. `Runnable`은 누구나 의존하는 타입이라, endpoint가 작업을 `Runnable`로 주입받아도 위 규칙이 다른 사용과 구별하지 못하기 때문이다. 메시지 handler의 `MessageHandler`는 프로젝트 타입이라 된다. record·enum은 언어가 붙이는 상위 타입(`Record`, `Enum`과 `Enum`이 구현하는 `Comparable`·`Serializable`·`Constable`)만은 가져도 된다. 그래서 handler 안의 파싱 결과 record, 결과 enum, 독(poison) 메시지 예외, record로 쓴 handler는 통과하고, `Runnable`을 구현한 record는 걸린다 | `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`(같은 파일) | +| 프로젝트 밖 상위 타입 금지 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스(익명·지역 클래스와 예외 제외)는 프로젝트(`dev.caskeleton..`와 소유자의 별도 repo 라이브러리 `dev.cakit..`) 밖의 클래스·인터페이스를 상속·구현하지 않는다. `Runnable`은 누구나 의존하는 타입이라, endpoint가 작업을 `Runnable`로 주입받아도 위 규칙이 다른 사용과 구별하지 못하기 때문이다. 메시지 handler의 `MessageHandler`(메시징 라이브러리 `dev.cakit.messaging`)는 프로젝트 타입으로 쳐서 된다. record·enum은 언어가 붙이는 상위 타입(`Record`, `Enum`과 `Enum`이 구현하는 `Comparable`·`Serializable`·`Constable`)만은 가져도 된다. 그래서 handler 안의 파싱 결과 record, 결과 enum, 독(poison) 메시지 예외, record로 쓴 handler는 통과하고, `Runnable`을 구현한 record는 걸린다 | `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`(같은 파일) | 규칙은 "누가 닿으면 안 되나"가 아니라 "누가 닿아도 되나"를 적는다. 이 성질은 **패키지** 쪽에서만 온다. 패키지는 허용 목록이라, 나중에 새 전송 패키지가 생겨도 따로 고치지 않아도 막힌다. 사용자 전송 **타입** diff --git a/docs/manual/09-outbox-events.md b/docs/manual/09-outbox-events.md index 7ccf0d17..a92db784 100644 --- a/docs/manual/09-outbox-events.md +++ b/docs/manual/09-outbox-events.md @@ -17,8 +17,9 @@ use case ── tx.inWrite ─┬─▶ repository.save(aggregate) ┐ DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공하는 순간이 생긴다. outbox는 그 순간을 없앤다. 대가는 **적어도 한 번** 전달이다 — 소비자는 event id로 중복을 걸러야 한다. -정본: `src/application-core/README.md` 「계약 타입」(이벤트 타입 표), `docs/messaging/outbox-inbox.md`, -`docs/messaging/delivery-guarantees.md`. +정본: `src/application-core/README.md` 「계약 타입」(이벤트 타입 표). 메시징 라이브러리 쪽 정본은 그 repo의 +[outbox-inbox.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/docs/messaging/outbox-inbox.md)와 +[delivery-guarantees.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/docs/messaging/delivery-guarantees.md)다. ## 순서 diff --git a/docs/messaging/configuration-reference.md b/docs/messaging/configuration-reference.md deleted file mode 100644 index 07130a20..00000000 --- a/docs/messaging/configuration-reference.md +++ /dev/null @@ -1,256 +0,0 @@ -# 설정 레퍼런스 - -> **Prefix.** Every property below binds under `app.messaging`, which is the prefix the deployed -> runtime and the `APP_MESSAGING_*` environment variables already use. Earlier revisions of this -> page documented a bare `messaging` prefix and the starter bound `backend.messaging`; neither -> bound what this page describes, so a deployment configured from it changed nothing. A key under -> either of the old prefixes now fails startup with a message naming the key — see -> `MessagingPrefixMigrationValidator`. - -> **이 페이지는 실행된다.** 아래 YAML 블록은 `MessagingConfigurationBindingTest`가 이 파일에서 직접 -> 읽어 컨텍스트에 올린다. 문서가 설명하는 모양이 곧 바인딩되는 모양이라는 뜻이고, 문서를 고치면서 -> 코드를 고치지 않으면 테스트가 깨진다. 이전 판은 destination·broker·security 세 섹션을 설명했지만 -> 어떤 binder도 그것을 읽지 않았다 — 문서대로 설정한 배포는 아무것도 바뀌지 않았고 아무 말도 듣지 -> 못했다 (MSG-008). - -## Application publish bridge identity - -Application의 canonical integration event를 platform publish pipeline으로 보낼 때는 -`app.messaging.producer-id`를 명시한다. 같은 값의 환경변수 이름은 -`APP_MESSAGING_PRODUCER_ID`다. 이 값은 host/pod 이름이 아니라 배포와 무관하게 유지되는 논리적 -producing-service identity다. - -값이 없으면 `IntegrationEventPublishPort` bridge 자체를 만들지 않는다. `spring.application.name`이나 -현재 process 이름으로 추론하지 않는다. 모든 발행(outbox relay 포함)이 이 bridge를 지나므로 messaging -모듈이 켜진 상태에서 값이 없으면 기동이 거부된다. - -## Outbox - -application의 발행 경로는 하나다(2026-09-28): `outbox_event` 표와 `composition:outbox-relay`. vendored -platform의 `messaging_outbox`(`outbox-inbox.md`)는 이 경로에 쓰이지 않는다 — 두 모델의 상태 대응은 -`outbox-inbox.md` 머리의 표에 있다. use case가 `IntegrationEventEncoderPort`로 만든 -`ValidatedIntegrationEvent`를 `OutboxAppendPort`로 append하고, relay는 claim한 row의 exact envelope -bytes를 `IntegrationEventPublishPort`로 보낸다. 예전의 `app.outbox.canonical-transport-enabled` -gate와 legacy `MessageBroker → KafkaSender` 경로는 삭제됐다. 발행할 contract의 logical destination마다 -아래 destination profile을 선언한다(템플릿의 durable operation event는 `durable-operations`). - -## Destination profile - -```yaml -app: - messaging: - destinations: - order-events: - broker: kafka-primary - kind: EVENT_STREAM # ASYNC_COMMAND | DOMAIN_EVENT | INTEGRATION_EVENT - # | WORK_QUEUE | PUBLISH_SUBSCRIBE | EVENT_STREAM | REQUEST_REPLY - tier: M1 # M1 | M2 | M3 - physical: - topic: order.events.v1 - schema: - codec: application/json - compatibility: BACKWARD_TRANSITIVE - message-types: [order.created] - guarantees: - delivery: AT_LEAST_ONCE # AT_MOST_ONCE | AT_LEAST_ONCE - ordering: KEY # NONE | DESTINATION | PARTITION | KEY - external-side-effect: INBOX_TRANSACTIONAL - producer: - confirmation: REPLICATION_OR_PERSISTENCE_ACK - timeout: 5s - mandatory-routing: true - idempotent: true - consumer: - group: order-projection - concurrency: 1 # DESTINATION 순서를 요구하면 1이어야 한다 - max-in-flight-per-ordering-unit: 1 - prefetch: 16 - handler-timeout: 30s - manual-settlement: false - retry: - mode: PAUSE_PARTITION # NONE | INLINE | BLOCKING | PAUSE_PARTITION - # | RETRY_DESTINATION | BROKER_DELAYED - max-attempts: 3 - initial-delay: 200ms - max-delay: 2s - multiplier: 2.0 - jitter: true - ordering-impact: PRESERVE # PRESERVE | ALLOW_REORDER - dlq: - destination: order-events-dlq - max-redrive-count: 1 - payload: - max-bytes: 1048576 - claim-check-threshold-bytes: 1048576 - key-resolver-configured: true - production: false - topology-auto-create: false - order-events-dlq: - broker: kafka-primary - kind: WORK_QUEUE - guarantees: - delivery: AT_MOST_ONCE # terminal DLQ: another DLQ is not required - physical: - topic: order.events.v1.dlt - schema: - message-types: [order.created] -``` - -`dlq.destination`이 가리키는 destination도 선언되어야 한다. 선언되지 않은 이름은 부팅 실패이며, -메시지가 갈 곳 없는 DLQ 설정이 조용히 통과하지 않는다. `retry.destination`과 `dlq.destination`이 -섞여 만드는 순환(A의 retry가 B로, B의 dlq가 A로)도 하나의 그래프로 검사되어 경로와 함께 거절된다. - -## 기본값 - -| 설정 | 기본값 | 근거 | -|---|---:|---| -| logical payload 최대 | 1,048,576 bytes | portability. 초과는 Claim Check | -| global hard 최대 | 8,388,608 bytes | 어떤 destination도 넘을 수 없는 상한 | -| header 총 크기 | 32,768 bytes | | -| header 개수 | 64 | | -| header key | 128 bytes | metric tag 안전 | -| header value | 4,096 bytes | | -| publish timeout | 5s | | -| handler timeout | 30s | | -| graceful shutdown drain | 30s | | -| 일반 destination retry | 0회 | 자동 retry는 opt-in | -| DLQ redrive batch | 100 | 한 번의 작업이 source를 덮치지 않게 | -| Outbox relay batch | 100 | | -| Outbox lease | 30s | | -| Outbox polling | 500ms | | -| metric dimension 상한 | 200 | cardinality 폭발 방지 | - -`schema.codec`은 `application/json`, `schema.compatibility`는 `BACKWARD_TRANSITIVE`, - -> **현재 강제 범위:** `schema.compatibility` 값은 현재 정책 선언이며 runtime/CI에서 schema registry를 -> 조회해 호환성을 차단하지 않는다. Avro 비교기는 독립 utility/test로만 존재한다. 따라서 이 값을 -> 설정했다고 breaking schema가 자동 거부된다고 해석하면 안 된다. 실제 registry gate가 wiring되기 -> 전까지 호환성은 adopter의 schema CI가 소유한다. - -`guarantees.delivery`는 `AT_LEAST_ONCE`, `retry.mode`는 `NONE`이 기본값이다. 자동 retry가 기본으로 -꺼져 있는 이유는 순서를 흐트러뜨리거나 비멱등 side effect를 두 번 실행하는 retry가 눈에 보이는 -실패보다 나쁘기 때문이다. - -## Broker profile - -브로커는 `app.messaging.brokers` 아래에 한 번만 기술한다. `type`은 `kafka`만 받는다 — transport가 -있는 계열이 Kafka 하나뿐이다. RabbitMQ 키(`addresses`, `prefetch`, `quorum-queues` 등)와 -`type: rabbitmq`는 2026-09-25에 설정 모델에서 삭제됐다. 연결할 transport 없이 바인딩만 되던 키라, -지금은 무시되지 않고 키 이름을 담아 부팅 실패로 거절된다. - -### Kafka - -```yaml -app: - messaging: - brokers: - kafka-primary: - type: kafka - stable: true - production: false - bootstrap-servers: [broker-1:9093, broker-2:9093] - enable-idempotence: true # stable에서 필수 - acks: all # stable에서 필수 - max-in-flight-requests-per-connection: 5 # 최대 5 - delivery-timeout: 30s - enable-auto-commit: false # 항상 금지 - consumer-group: order-projection - tls-enabled: false # production이면 필수 - authentication-enabled: false # production이면 필수 -``` - -`production: true`인 Kafka 브로커는 `tls-enabled`와 `authentication-enabled`가 모두 참이어야 하고, -그렇지 않으면 `KafkaProfileValidator`가 부팅을 거절한다. `app.messaging.broker`로 고를 수 있는 값은 -`kafka`뿐이다. 위 예시가 -`production: false`인 것은 이 페이지가 그대로 실행되는 fixture이기 때문이며, 실 배포는 셋 다 참이다. - -Kafka producer는 이 항목 하나로 만든다. `bootstrap-servers`, `acks`, `enable-idempotence`, -`max-in-flight-requests-per-connection`, `delivery-timeout`이 그대로 client 설정이 된다. -`spring.kafka.bootstrap-servers`는 읽지 않는다. type이 `kafka`인 항목이 정확히 하나가 아니면 기동에 -실패한다. `send()`가 metadata를 기다리며 호출 스레드를 막는 시간(`max.block.ms`)은 기본 publish -timeout(5s)이다. - -## 보안 - -```yaml -app: - messaging: - security: - kafka-primary: - producer: { type: SASL_SCRAM, credential-id: kafka-producer } - consumer: { type: SASL_SCRAM, credential-id: kafka-consumer } - # admin은 application runtime에 설정하지 않는다 - hostname-verification: true - # 사설 CA로 서명된 TLS 브로커면(tls-enabled: true일 때만): - # trust-store: { location: /etc/kafka/ca.p12, type: PKCS12, password-credential-id: kafka-truststore } - access: - publishable: [order-events] - consumable: [] - administrable: [] -``` - -키는 `app.messaging.brokers`에 선언된 브로커 이름과 같아야 한다. `tls-enabled`와 `production`은 -브로커 쪽에만 있고 여기에 중복되지 않는다 — 하나의 브로커가 두 곳에서 기술되면 두 값이 어긋나는 -날이 오고, 어느 쪽이 이기는지는 아무도 모른다. - -`credential-id`는 이름일 뿐이고 자격 증명 자체가 아니다. 실제 재료는 `CredentialProvider`가 -연결 시점에 해석하므로, 설정 덤프나 힙 덤프에서 나오는 것은 이름뿐이다. producer와 consumer는 -서로 다른 `credential-id`를 써야 하며, 같으면 부팅에 실패한다. - -`SASL_SCRAM`·`USERNAME_PASSWORD`의 사용자 이름은 `CredentialProvider.username(credentialId)`가 -준다. credential id를 사용자 이름으로 보내지 않는다. 비밀번호와 사용자 이름은 JAAS 문자열에 들어가지 -않고, 연결이 인증할 때마다 provider에서 읽힌다. 그래서 provider가 만료 시각을 주는 credential은 -재기동 없이 rotation된다(`security.md`). - -`MUTUAL_TLS`는 클라이언트 인증서를 key store로 제출한다. `credential-id`는 key store 비밀번호를 -가리킨다. - -```text -producer: - type: MUTUAL_TLS - credential-id: kafka-producer-tls # key store 비밀번호 - key-store: { location: /etc/kafka/producer.p12, type: PKCS12 } -``` - -`trust-store`를 생략하면 JVM 기본 trust store를 쓴다. 사설 CA 브로커는 `trust-store.location` -(PKCS12·JKS·PEM)과, 잠긴 store면 `password-credential-id`를 준다. - -Kafka producer는 이 항목을 실제 클라이언트 설정(`security.protocol`, `sasl.mechanism`, -`sasl.jaas.config`, `sasl.client.callback.handler.class`, `ssl.truststore.*`, `ssl.keystore.*`, -`ssl.enabled.protocols=TLSv1.3,TLSv1.2`, hostname 검증)으로 옮긴다. 평문으로 조용히 넘어가지 -않도록 다음 경우 부팅에 실패한다: 브로커가 `tls-enabled`나 `authentication-enabled`를 켰는데 -`app.messaging.security.`가 없을 때, security 항목은 있는데 `CredentialProvider` bean이 없을 -때, 같은 브로커에 맞는 항목이 둘 이상일 때, provider가 SASL 사용자 이름을 주지 않을 때, -`MUTUAL_TLS`인데 `key-store`가 없거나 `tls-enabled`가 꺼져 있을 때, `trust-store`를 줬는데 -`tls-enabled`가 꺼져 있을 때, store 파일을 열 수 없을 때. - -`access.publishable`은 강제된다. security 항목이 있는 브로커의 destination은 이 목록에 있어야 -publish된다. 목록 밖 publish는 `REJECTED`(`PUBLISH_FORBIDDEN`)이고, 빈 목록이면 아무것도 publish되지 -않는다. - -## Backpressure - -```yaml -app: - messaging: - backpressure: - global-limit: 512 - per-destination-limit: 64 # global-limit 이하여야 한다 -``` - -`per-destination-limit > global-limit`이면 global limit이 limit이 아니게 되므로 부팅에 실패한다. - -## 바인딩되지 않는 키 - -섹션은 바인딩되는데 그 안의 키 하나가 오타인 경우는 접두사 오타와 달리 조용하다 — 섹션은 붙고, -플랫폼은 뜨고, 바꾸러 온 그 설정만 적용되지 않는다. `MessagingConfigurationKeyValidator`가 -`app.messaging.destinations|brokers|security` 아래의 모든 키를 settings 레코드에서 파생한 목록과 -대조하고, 없는 키는 그 키 이름을 담아 부팅을 거절한다. - -허용 키 목록은 이 문서가 아니라 레코드에서 나온다. 문서에 목록을 적으면 필드가 추가된 날 그 -목록이 틀리고, 오타를 잡으라고 만든 검사가 정상 필드를 거절하게 된다. - -환경변수(`APP_MESSAGING_...`)는 이 검사의 대상이 아니다. `APP_MESSAGING_DESTINATIONS_ORDER_EVENTS_ -CONSUMER_PREFETCH`에서 entry 이름과 leaf를 가르는 밑줄은 둘 안에 있는 밑줄과 구별되지 않으므로, -되돌려 쪼개려면 추측해야 한다. 여기서의 추측은 정상 배포를 거절하는 쪽으로 틀리며, 그것은 배포 -매니페스트에 손으로 적어야 하는 변수에서 오타 하나를 놓치는 것보다 나쁘다. diff --git a/docs/messaging/cutover.md b/docs/messaging/cutover.md deleted file mode 100644 index f697177e..00000000 --- a/docs/messaging/cutover.md +++ /dev/null @@ -1,35 +0,0 @@ -# 기존 runtime → 신규 messaging platform cutover (MSG-015) - -## 왜 기계적 매핑이 안 되는가 - -두 outbox 모델의 enum 이름이 겹치는데 의미가 반대다. - -| 모델 | retryable | terminal | -|---|---|---| -| 기존 `OutboxEventStatus` | `FAILED` (`next_attempt_at` 보유) | `DEAD` | -| 신규 `OutboxStatus` | `AMBIGUOUS` | `FAILED`, `EXHAUSTED` | - -이름으로 매핑하면 **확정 거절이 무한 재시도**가 되고 **불확정이 park**된다. 그래서 application은 -자기 어휘(`OutboxPublishOutcome`)만 쓰고, 변환은 bridge adapter가 한다. - -## 지금 반영된 것 - -- `OutboxPublishOutcome` — `CONFIRMED` / `AMBIGUOUS` / `REJECTED_BEFORE_SEND` / - `REJECTED_AFTER_BROKER`. application이 소유하는 canonical 결과 타입이며, "리턴 or throw"만 가능한 - 기존 어댑터를 위해 `OutboxMessagePublishPort.publishForOutcome`의 default가 `CONFIRMED`를 돌려준다. -- `APPLICATION_DOES_NOT_DEPEND_ON_THE_MESSAGING_PLATFORM` ArchUnit 규칙 — application-core가 - `dev.caskeleton.messaging..`를 import하면 빌드가 깨진다. -- 반대 방향(신규 `PublishResult` → application outcome) 매핑 규칙을 테스트로 고정. - -## 남은 것 - -- `messaging-platform-bridge` outbound leaf: validated application event → platform envelope, - `PublishResult` → `OutboxPublishOutcome`. registry에 leaf를 추가하는 변경이라 별도 커밋. -- golden contract 테스트: event/message ID, type, schema revision, partition/order/correlation/ - causation/tenant/trace, payload digest, wire version이 bytes 단위로 보존되는지. -- 단일 publication authority: writer/relay가 동시에 ACTIVE가 되지 않도록 하는 fence. 이 용도로 쓰려던 - outbox V2의 `OutboxPublicationAuthority`는 한 번도 조립되지 않은 채 2026-09-25에 삭제됐으므로 - (`docs/capability-status.md` "제거된 코드") cutover가 자기 fence를 새로 가져야 한다. **dual write/publish는 금지** — 한 business fact가 두 durable store와 - 두 relay로 나가는 상태가 cutover에서 가장 위험하다. -- 첫 cutover 범위는 **transport만** 교체(저장소는 기존 유지). storage migration은 shadow read → - authority switch → old backlog drain 순서로 별도 release. diff --git a/docs/messaging/delivery-guarantees.md b/docs/messaging/delivery-guarantees.md deleted file mode 100644 index d9809328..00000000 --- a/docs/messaging/delivery-guarantees.md +++ /dev/null @@ -1,80 +0,0 @@ -# 전달 보장 - -## 왜 `EXACTLY_ONCE`가 없는가 - -어떤 브로커도 **외부 side effect를 포함한** exactly-once를 제공하지 않는다. -실제로 존재하는 것은 at-least-once 전달 + 멱등하거나 transactional한 consumer의 조합이다. - -플랫폼이 지킬 수 없는 이름을 enum에 두면 그 책임이 눈에 보이지 않는 곳으로 밀려난다. -그래서 `DeliveryGuarantee`는 증거가 끝나는 지점에서 멈춘다. - -```java -public enum DeliveryGuarantee { AT_MOST_ONCE, AT_LEAST_ONCE } -``` - -## Publish 결과는 boolean이 아니다 - -```java -public enum PublishCompletion { CONFIRMED, REJECTED, AMBIGUOUS } -``` - -`REJECTED`와 `AMBIGUOUS`를 하나의 "실패"로 합치면 중복 주문이 만들어진다. -전자는 broker가 저장하지 않았음이 **확정**되어 중복 걱정 없이 다시 보내거나 포기할 수 있고, 후자는 그렇지 않다. - -`REJECTED`가 곧 "포기해도 된다"는 뜻은 아니다. 거부 이유가 그 순간에 속하면(종료 중 -`SHUTTING_DOWN`, permit 대기 초과, `PUBLISH_RUNTIME_UNAVAILABLE`, `KAFKA_TRANSPORT_CLOSED`, Kafka -인증·인가 실패) `failure().retryable()`이 true이고, 호출자는 같은 메시지를 나중에 다시 보내야 한다. -포기해도 되는 것은 `retryable=false`인 거부뿐이다. - -| 상황 | 결과 | -|---|---| -| 로컬 validation 실패 | `REJECTED`, `NOT_TRANSMITTED` | -| broker 명시적 reject / nack | `REJECTED` | -| confirm 수신 | `CONFIRMED` | -| Rabbit confirm + unroutable return | `REJECTED`, `UNROUTABLE` | -| bytes 전송 후 connection loss | `AMBIGUOUS` | -| confirm timeout | `AMBIGUOUS` | -| adapter가 판정 불가 | 보수적으로 `AMBIGUOUS` | - -`PublishResult` 생성자가 이 규칙을 강제한다. `CONFIRMED`인데 broker acceptance가 없거나, -`AMBIGUOUS`인데 confirmation level을 주장하면 **객체 생성 자체가 실패**한다. - -## Ordering - -```java -public enum OrderingScope { NONE, DESTINATION, PARTITION, KEY } -``` - -순서는 partition·key·단일 consumer의 성질이지 destination 전체의 성질이 아니다. -`GLOBAL`이 없는 이유가 이것이다. - -`DestinationProfileValidator`가 다음을 거부한다. - -- `ordering=KEY`인데 key resolver 없음 -- ordered destination인데 `ALLOW_REORDER` retry -- `orderingImpact=PRESERVE`인데 재발행형 retry(`RETRY_DESTINATION`, `BROKER_DELAYED`) -- `ordering=DESTINATION`인데 concurrency > 1 -- ordered destination인데 ordering unit당 in-flight > 1 - -## External side effect - -```java -public enum ExternalSideEffectGuarantee { NONE, IDEMPOTENCY_REQUIRED, INBOX_TRANSACTIONAL } -``` - -`INBOX_TRANSACTIONAL`만이 "DB side effect와 중복 차단이 같은 transaction에서 commit된다"를 의미한다. -Kafka transaction은 **Kafka 안에서만** 원자적이므로 이 값과 함께 설정하면 -`KafkaTransactionProfileValidator`가 거부한다. 두 개의 독립적인 commit을 하나로 착각하게 두지 않기 위해서다. - -## Consumer settlement 순서 - -```text -RECEIVED → DECODING → PROCESSING → HANDLER_SUCCEEDED → SETTLEMENT_SENDING - ├→ SETTLED - └→ SETTLEMENT_UNKNOWN -``` - -- handler는 broker ACK API를 호출하지 않는다. -- `Success` 이후에만 source settlement한다. -- `SETTLEMENT_UNKNOWN`은 성공이 아니다. redelivery 가능성을 의미한다. -- `SettlementResult` 생성자가 `SETTLED`인데 `redeliveryPossible=true`인 조합을 거부한다. diff --git a/docs/messaging/experimental-policy.md b/docs/messaging/experimental-policy.md deleted file mode 100644 index de8f5b1c..00000000 --- a/docs/messaging/experimental-policy.md +++ /dev/null @@ -1,58 +0,0 @@ -# Experimental 정책 - -## Stable과 Experimental의 차이 - -**Stable**은 공통 Contract Suite(`MessagingAdapterContract`)를 변경 없이 통과한 어댑터다. -컴파일되는 어댑터가 아니라, 아래 7가지를 실제로 증명한 어댑터다. - -```text -publishesAndConfirms -returnsAmbiguousWhenConfirmIsLost -redeliversWhenSettlementIsLost -preservesMessageIdAcrossRetryAndDlq -keepsSourceUnsettledWhenDlqPublishFails -rejectsOversizedPayloadBeforeTransport -stopsAcceptingNewWorkDuringShutdown -``` - -**Experimental**은 아직 그 증명이 끝나지 않은 어댑터다. - -현재 Experimental 어댑터는 없다. Kafka Share Group·Pulsar·NATS JetStream(Experimental), RabbitMQ, -Spring Cloud Stream bridge(Optional)는 SDK 없는 seam이거나 선택할 수 없는 상태여서 2026-09-25에 -삭제했다(`docs/capability-status.md` 제거 표). 이 문서는 새 어댑터를 들일 때 지킬 규칙이다. - -## 규칙 - -### 1. 기본 비활성 - -새 Experimental 어댑터는 자기 활성화 플래그를 가지고 기본값은 `false`다. -활성화하지 않으면 validator가 `MessagingCapabilityUnavailableException`을 던진다. -Contract Suite가 아직 증명 중인 어댑터가 누군가의 기본 설정 때문에 load-bearing이 되어서는 안 된다. - -### 2. Stable 모듈이 Experimental 모듈에 의존하지 않는다 - -Gradle 의존 그래프로 강제된다. Experimental leaf는 `messaging-spring-boot-starter`의 -`allowed_dependencies`에 넣지 않는다. - -`verifyCleanArchitectureDependencies`가 위반을 빌드 실패로 만든다. - -### 3. Core 계약을 바꾸지 않는다 - -Experimental 어댑터는 브로커의 차이를 `MessagingCapabilities`로 표현할 뿐, -`messaging-core-api`의 타입을 바꾸지 않는다. - -### 4. 없는 기능을 광고하지 않는다 - -Contract Suite로 증명하지 않은 capability는 `MessagingCapabilities`에서 `false`로 둔다. -`false`인 capability를 요구하는 profile은 startup에서 실패한다. 조용히 약화되지 않는다. - -## 승격 조건 - -Experimental → Stable로 올리려면 전부 필요하다. - -1. `MessagingAdapterContract` 7개 테스트를 변경 없이 통과 -2. 장애 주입(연결 끊김, confirm 유실, settlement 유실) 하에서 통과 -3. 지원 브로커 버전 범위 명시 및 CI 검증 -4. `support-matrix.md`의 capability 표 갱신 -5. ADR 작성 -6. 기본 활성화 여부에 대한 별도 결정 diff --git a/docs/messaging/migration-guide.md b/docs/messaging/migration-guide.md deleted file mode 100644 index 77aae880..00000000 --- a/docs/messaging/migration-guide.md +++ /dev/null @@ -1,126 +0,0 @@ -# 마이그레이션 가이드 - -## 기존 Spring Kafka / Spring AMQP 코드에서 - -### 1. topic 이름을 코드에서 제거한다 - -```java -// before -kafkaTemplate.send("order.events.v1", key, payload); - -// after -publisher.publish(orderEvents, envelope, PublishOptions.defaults()); -``` - -`MessageDestination`은 logical name만 가진다. 물리 매핑은 destination profile이 소유한다. -`DestinationName`의 패턴이 `topic://orders` 같은 값을 거부하므로 우회할 수 없다. - -### 2. boolean 성공 판정을 없앤다 - -```java -// before -try { template.send(...).get(); success(); } -catch (Exception e) { fail(); } // REJECTED와 AMBIGUOUS를 구분하지 못한다 - -// after -PublishResult result = ...; -switch (result.completion()) { - case CONFIRMED -> success(); - case REJECTED -> abandon(); // broker가 저장하지 않음이 확정 - case AMBIGUOUS -> retrySameMessageId(result); // broker가 가지고 있을 수 있음 -} -``` - -이 구분이 없으면 confirm 유실 한 번이 중복 주문 하나가 된다. - -### 3. auto-commit / auto-ack를 끈다 - -```yaml -# Kafka -enable.auto.commit: false -# RabbitMQ -auto-ack: false -``` - -둘 다 validator가 강제로 거부한다. 타이머 기반 commit은 handler가 실행되기도 전에 -메시지를 처리 완료로 표시한다. - -### 4. handler에서 ack 호출을 제거한다 - -```java -// before -@KafkaListener(...) -void handle(ConsumerRecord record, Acknowledgment ack) { - process(record); - ack.acknowledge(); // 실패 시 순서가 애매해진다 -} - -// after -CompletionStage handle(MessageDelivery delivery) { - process(delivery.message().payload()); - return completedFuture(HandleResult.success()); -} -``` - -settlement는 플랫폼이 수행한다. "성공한 뒤에만 ack"가 각 handler의 기억이 아니라 -플랫폼 불변식이 된다. - -### 5. 중복을 정상 상황으로 다룬다 - -at-least-once는 중복을 전제한다. 세 가지 중 하나를 고른다. - -| 방식 | 언제 | -|---|---| -| handler 자체 멱등 | 자연 멱등 연산 (upsert 등) | -| Inbox | DB side effect가 있는 경우 | -| Kafka transaction | Kafka → Kafka 파이프라인만 | - -`ExternalSideEffectGuarantee`에 선언한다. `INBOX_TRANSACTIONAL`과 Kafka transaction을 -동시에 설정하면 거부된다. Kafka transaction은 DB를 포함하지 않는다. - -### 6. 큰 payload는 Claim Check로 - -broker frame 크기를 키우지 않는다. broker 메모리, replication latency, -consumer recovery가 동시에 나빠지고, 유계·검증 가능한 실패가 무계 실패로 바뀐다. - -1 MiB 초과는 외부 저장소로 offload하고 digest를 포함한 참조만 발행한다. - -## DB 마이그레이션 - -```text -V1001__messaging_outbox.sql -V1002__messaging_outbox_lease_fencing.sql -V1003__messaging_admin_operation_journal.sql -V1004__messaging_outbox_canonical_metadata.sql -V1101__messaging_inbox.sql -``` - -Messaging owns Flyway versions `1000..1999`. The starter assembles both JDBC reliability modules, -so their migrations deliberately share `classpath:db/migration/messaging` but must never reuse a -version. Keeping them in this reserved range also prevents collisions with the application's -ordinary `db/migration/postgresql` stream, whose low-numbered versions are independent. - -When adopting outbox/inbox persistence, add `classpath:db/migration/messaging` to the deployment's -Flyway locations together with its normal application migration location. Do not copy or renumber -these files into the application's low-numbered stream; the reserved range is the namespace -boundary. - -Outbox row는 business transaction과 같은 transaction에서 쓴다. -Inbox reservation은 handler side effect와 같은 transaction에서 쓴다. -별도 transaction이면 각 패턴이 닫으려던 창이 그대로 열려 있다. - -## 단계적 전환 - -1. **publish만 전환** — 기존 consumer는 그대로. wire format은 reserved header가 추가될 뿐이다. -2. **Outbox 도입** — publish 유실 창을 닫는다. -3. **consume 전환** — handler를 `MessageHandler`로 옮기고 ack 호출을 제거한다. -4. **Inbox 도입** — 중복 side effect를 닫는다. -5. **retry·DLQ 정책 선언** — 이 시점까지 자동 retry는 0회다. - -각 단계는 독립적으로 배포 가능하고, 되돌릴 수 있다. - -## 되돌릴 수 없는 것 - -- 한 번 발행된 message type의 wire contract -- 이미 retention 안에 있는 메시지의 schema -- redrive된 메시지의 `messageId` (바뀌지 않는다 — 이것이 의도다) diff --git a/docs/messaging/operations.md b/docs/messaging/operations.md deleted file mode 100644 index 5bccc75d..00000000 --- a/docs/messaging/operations.md +++ /dev/null @@ -1,112 +0,0 @@ -# 운영 Runbook - -## 배포 전 체크 - -```bash -./gradlew architectureCheck --console=plain -./gradlew checkstyleMain --console=plain -``` - -destination profile은 startup에서 검증된다. 아래는 **부팅 실패**다. - -- ordered destination + reorder 가능 retry -- `ordering=KEY` + key resolver 없음 -- payload 상한 > 8,388,608 bytes -- DLQ 자기 참조 / retry 자기 참조 -- retry·DLQ 그래프 cycle -- 미등록 retry·DLQ destination -- M1 destination + manual settlement -- `AT_LEAST_ONCE` + confirmation `NONE` -- production profile + topology auto-create -- broker topology가 manifest와 불일치 - -## 증상별 대응 - -### publish가 AMBIGUOUS로 쏟아진다 - -broker confirm 경로 문제다. 실패가 아니다. - -1. `PublishEvidence.transmission`이 `MAY_HAVE_BEEN_TRANSMITTED`인지 확인 -2. Kafka: `delivery.timeout.ms`, ISR 상태, leader election 확인 -3. Rabbit: confirm timeout, channel 상태 확인 -4. Outbox를 쓰고 있다면 `status='AMBIGUOUS'` row가 같은 messageId로 재시도 중이다. **정상이다.** -5. consumer 쪽 Inbox가 중복을 흡수하는지 확인 - -`AMBIGUOUS`를 실패로 취급해 새 messageId로 재발행하지 말 것. 중복이 복구 불가능해진다. - -### DLQ가 비어 있는데 메시지가 사라졌다 - -DLQ publish 실패 시 source는 settlement되지 않는다. 메시지는 source에 남아 재전달된다. - -1. `msg.failure-code`가 `DEAD_LETTER_*`인 로그 확인 -2. DLQ destination이 실제로 존재하는지 (topology validation) -3. DLQ credential에 publish 권한이 있는지 - -### consumer lag이 한 partition에서만 증가한다 - -`ContiguousPartitionOffsetTracker`가 gap에서 멈춘 것이다. 설계된 동작이다. - -commit은 **연속** 완료 offset까지만 전진한다. offset 11이 아직 실행 중이면 -10과 12가 끝나도 watermark는 10에 머문다. 12를 commit하면 consumer가 죽었을 때 11을 잃는다. - -1. 해당 partition의 in-flight를 확인 -2. 느린 handler를 찾는다 (`handlerTimeout` 초과 여부) -3. 필요하면 `PAUSE_PARTITION` retry가 걸려 있는지 확인 - -### 재시도 폭풍 - -`RetryPolicy.jitter=false`인지 확인한다. jitter 없이는 같은 초에 실패한 모든 consumer가 -같은 초에 재시도한다. - -### shutdown이 오래 걸린다 - -`GracefulShutdownCoordinator`가 in-flight를 기다리는 중이다. - -- `inFlight()`가 0이 되면 즉시 종료 -- drain deadline(기본 30초) 초과 시 남은 작업을 **unsettled로 포기**한다 → broker가 재전달 -- draining 시작 후 새 retry attempt는 만들지 않는다 - -## Destructive 작업 - -전부 `DestructiveOperationGuard`를 통과해야 한다. - -| 조건 | 요구 | -|---|---| -| admin credential | application runtime은 보유하지 않음 | -| `AdminApproval` | 유효기간 내 | -| dry-run | 항상 허용 | - -### Replay - -```text -기본: 격리된 consumer group (replay-) -기존 group 대상: 승인 티켓 필수 -``` - -기존 production group으로 replay하는 것은 "다시 읽기"가 아니라 **live consumer를 되감는 것**이다. -그 사이의 모든 것이 재처리된다. - -### Redrive - -```text -dry-run으로 후보 수 확인 -→ 승인 획득 -→ batch 100건 이하로 실행 -→ republish CONFIRMED 인 것만 DLQ에서 settlement -``` - -`redriveId`로 재구동 루프를 추적한다. 같은 메시지가 반복해서 redrive되면 -근본 원인이 해결되지 않은 것이다. - -### Offset reset - -`KafkaOffsetResetExecutor`는 승인 predicate를 **생성자 인자**로 받는다. -승인 소스 없이 조립된 runtime은 물리적으로 reset을 수행할 수 없다. - -## Topology - -production topology는 IaC가 만들고 애플리케이션은 **검증만** 한다. - -`TopologyValidationRuntime`은 모든 불일치를 한 번에 보고하고 startup을 실패시킨다. -partition 수가 다르면 destination이 광고하는 ordering 보장이 달라지고, -`min.insync.replicas`가 없으면 `acks=all`의 의미가 달라진다. diff --git a/docs/messaging/outbox-inbox.md b/docs/messaging/outbox-inbox.md deleted file mode 100644 index 1567cc93..00000000 --- a/docs/messaging/outbox-inbox.md +++ /dev/null @@ -1,192 +0,0 @@ -# Outbox · Inbox - -> **이 문서의 Outbox는 vendored messaging platform의 outbox다**(`messaging_outbox` 표, -> `messaging-reliability`의 `OutboxRelay`). 이 템플릿 application이 쓰는 outbox는 그것이 아니다. -> application은 `outbox_event` 표(`adapter:outbound:persistence-jpa`)에 append하고, relay는 -> `composition:outbox-relay`가 돌린다. 그 동작과 운영은 `docs/manual/09-outbox-events.md`, -> `src/composition/outbox-relay/README.md`, `docs/runbooks/outbox-dead-letter.md`, -> `docs/runbooks/outbox-publish-failed.md`에 있다. platform outbox는 소유자 결정으로 제품 안에 남아 -> 있지만, platform outbox repository bean이 없으면 그 relay는 만들어지지 않는다(리뷰 2026-11-01 06-11). -> -> 두 모델은 같은 이름의 상태가 반대 뜻이다. 이름으로 옮기면 확정 거부는 영원히 재시도되고 응답 없는 -> 메시지는 버려진다. 대응은 아래 표 하나로만 읽는다(`OutboxPublishOutcome` Javadoc과 같은 내용). -> -> | 일어난 일 | application `outbox_event` | platform `messaging_outbox` | -> |---|---|---| -> | broker가 확인했다 | `PUBLISHED` | `PUBLISHED` | -> | 응답이 없었다(저장됐을 수 있음) | `FAILED`(재시도, 예산 안 씀, 끝 없음) | `AMBIGUOUS`(재시도, 예산을 다 쓰면 `EXHAUSTED`) | -> | 지금만 거부됐다(종료·포화·credential) | `FAILED`(재시도, 예산 안 씀, 끝 없음) | `FAILED`(종단) | -> | 확정 거부됐다(같은 payload는 또 거부) | `DEAD`(종단, 수동 처분) | `FAILED`(종단) | -> | publisher가 예외를 던졌고 시도 예산을 다 썼다 | `DEAD`(종단, 수동 처분) | `EXHAUSTED`(종단) | -> | 운영자가 재시도를 멈췄다 | `PARKED`(수동 재개·skip) | 없음 | -> -> **이 템플릿 application의 소비 경로**: application의 `MessageHandler`와 inbox 부품(애플리케이션 -> DataSource 위 `JdbcInboxRepository`, `PlatformTransactionManager` 위 `TransactionRunner`)은 -> `adapter:inbound:messaging`(`src/adapter/inbound/messaging/README.md`)이 둔다. platform starter는 두 -> bean이 있을 때 `IdempotentConsumer`를 만들어 `INBOX_TRANSACTIONAL` destination의 handler를 감싼다. -> 그 leaf는 inbox 마이그레이션(`V1101`)만 자기 history 표로 적용하므로, 아래 "location 추가"는 platform -> outbox를 쓰는 배포의 이야기다. payload decode 목록은 handler bean의 선언으로 만든다. - -## 두 패턴이 각각 무엇을 해결하는가 - -| 패턴 | 해결하는 문제 | 해결하지 않는 문제 | -|---|---|---| -| Transactional Outbox | DB commit과 publish 사이의 창(窓) | 중복 | -| Inbox | 중복 delivery의 side effect | 유실 | - -**둘 다 필요하다.** Outbox만으로는 exactly-once가 되지 않는다. - -## 채택할 때 먼저 적용할 DB migration - -Outbox/Inbox JDBC 모듈의 DDL은 `classpath:db/migration/messaging`에 있다. Messaging은 -Flyway version `1000..1999`를 예약해서 애플리케이션의 일반적인 저번호 migration과 버전이 -겹치지 않게 한다. - -배포에서 이 JDBC 구현을 채택할 때는 기존 Flyway location에 다음 location을 **추가**한다. - -```text -classpath:db/migration/messaging -``` - -현재 순서는 `V1001..V1005`(outbox/admin)와 `V1101`(inbox)이고, 모두 -`messaging-reliability-jdbc-postgresql`에 있다. starter 테스트가 그 모듈을 실제 combined classpath로 올려 version 중복과 예약 대역 이탈을 검사한다. 개별 DDL의 -의미와 전환 순서는 [migration-guide.md](migration-guide.md)를 따른다. - -## Outbox - -business transaction과 **같은 transaction**에서 row를 쓴다. 둘 다 commit되거나 둘 다 안 된다. - -```sql -BEGIN; - UPDATE orders SET status = 'PLACED' WHERE id = ?; - INSERT INTO messaging_outbox (message_id, destination, ...) VALUES (?, ?, ...); -COMMIT; -``` - -### relay - -```text -claimBatch(owner, 100, 30s, now, maxAttempts) -- owner + fencing token으로 다중 relay 인스턴스 안전 -→ publish (messageId 그대로) -→ CONFIRMED → markPublished -→ AMBIGUOUS → markAmbiguous (같은 messageId로 재시도 가능) -→ REJECTED → markFailed -``` - -row 하나의 실패는 그 row에서 끝난다. envelope로 만들 수 없는 row(예약 header `msg.*`를 담은 row -등)는 `FAILED`가 되고, publisher가 예외를 던지면 결과를 모르므로 `AMBIGUOUS`가 된다. 같은 batch의 -나머지 row는 그대로 publish된다. pass 전체가 실패하면(DB 연결 등) WARN 로그를 남기고 -`messaging.outbox.relay.failed.passes` 카운터를 올린다. - -### 핵심 규칙: ambiguous는 같은 messageId로 재시도 - -새 id를 발급하면 "전달됐을 수도 있는 메시지"가 "확실히 두 번째인 메시지"가 되어 -downstream의 어떤 중복 제거도 복구할 수 없다. -failed로 표시하면 broker가 이미 가지고 있을 수 있는 메시지를 잃는다. - -`message_id`를 primary key로 둔 것도 같은 이유다. 어떤 코드 경로도 실수로 새 id를 붙일 수 없다. - -### lease - -```text -status IN ('PENDING','AMBIGUOUS','IN_FLIGHT') - AND (lease_expires_at IS NULL OR lease_expires_at <= now) - AND next_attempt_at <= now - AND attempts < maxAttempts - AND (ordering_key IS NULL - OR 같은 destination·ordering_key의 더 오래된 미완료 row가 없음) -``` - -`ordering_key`가 있는 row는 같은 key의 더 오래된 row가 `PENDING`·`AMBIGUOUS`·`IN_FLIGHT`인 동안 -claim되지 않는다. 이 조건이 없으면 두 relay가 같은 key의 두 row를 나눠 가져가거나, AMBIGUOUS로 -재시도되는 row보다 뒤의 row가 먼저 나간다(`OutboxPostgresIT#aNewerRowWaitsWhileAnOlderRowWithTheSameOrderingKeyIsUnfinished`). -`V1005`의 partial index가 이 확인을 받친다. 더 오래된 row가 `FAILED`·`EXHAUSTED`가 되면 뒤의 row는 -진행한다. - -`IN_FLIGHT`가 목록에 있는 것이 핵심이다. relay가 publish 도중 죽으면 row는 `IN_FLIGHT`로 남는데, -이를 제외하면 그 메시지는 **영원히** 발행되지 않는다 — outbox가 막으려던 바로 그 실패다. 대신 -lease가 만료됐을 때만 회수하므로, 살아 있는 relay가 들고 있는 row는 회수되지 않는다. - -회수는 **같은 `message_id`로** 이루어지고 `lease_token`이 1 증가한다. 새 id를 발급하면 "전달됐을 -수도 있는 메시지"가 "확실히 두 번째"가 되기 때문이다 (위의 AMBIGUOUS 논의와 같은 이유). - -이 문단의 근거는 실제 PostgreSQL 컨테이너 레인이다: - -- `OutboxPostgresIT#anExpiredLeaseBecomesClaimableAgain` — 만료된 lease의 재회수 -- `OutboxPostgresIT#anExpiryReclaimKeepsTheMessageIdAndAdvancesTheToken` — 같은 id, 증가한 token -- `OutboxPostgresIT#aLeasedRowIsInvisibleToASecondRelayInstance` — 살아 있는 lease는 회수 불가 -- `OutboxPostgresIT#aSupersededRelayCannotOverwriteTheOutcomeOfTheOneThatReplacedIt` — fencing - -partial index `ix_messaging_outbox_claimable`이 이 쿼리를 backlog 크기에 비례하게 유지한다. -PUBLISHED row는 retention job이 지울 때까지 쌓이기 때문이다. - -## Inbox - -reservation과 side effect가 **같은 transaction**이어야 한다. - -```java -transactions.inTransaction(() -> { - if (!inbox.reserve(messageId, consumerId, now)) { - return InboxOutcome.duplicate(); // 이미 처리됨 - } - return InboxOutcome.processed(sideEffect.get()); -}); -``` - -별도 transaction으로 예약하면 Inbox가 닫으려던 바로 그 창이 다시 열린다. - -### 소비와 연결 (소유자 결정 10) - -consume 계약은 `MessageHandler` 하나다. handler를 bean으로 등록하면 `messaging-spring-boot-starter-kafka`가 -그 handler가 가리키는 destination마다 Kafka consumer를 연다(`app.messaging.enabled=false`면 없다). - -- destination profile이 `guarantees.external-side-effect: INBOX_TRANSACTIONAL`이면 platform이 handler를 - `InboxMessageHandler`로 감싼다. 예약과 handler의 쓰기가 같은 transaction에서 commit되고, 이미 예약된 - message는 handler를 부르지 않고 `Success`로 settle한다. 이 경우 애플리케이션이 `IdempotentConsumer` - bean(inbox repository + transaction runner)을 둬야 하며, 없으면 기동이 실패한다. -- inbox의 consumer 식별자와 Kafka `group.id`는 destination의 `consumer.group`이다. 없으면 기동이 실패한다. -- offset은 handler가 `Success`로 답하고 (inbox destination이면) 그 transaction이 commit된 뒤에만, 또는 - DLQ 토픽 기록이 확인된 뒤에만 넘어간다. auto-commit은 쓰지 않는다. -- `Retry`·예외·timeout은 `retry.max-attempts`까지 partition을 멈추고 다시 읽으며, 다 쓰면 DLQ 토픽에 - 원본 record를 남기고 넘어간다. DLQ가 없는 destination(at-most-once)은 넘어가지 않고 멈춘다. -- `Reject`는 at-most-once destination에서만 버리고, 그 밖에서는 dead letter로 보낸다. - -실제 왕복·중복 제거·DLQ는 `MessagingKafkaConsumeQualificationTest`(Kafka + PostgreSQL Testcontainers)가 확인한다. -애플리케이션 경로(앱 outbox relay가 발행 → `adapter:inbound:messaging`이 조립한 inbox와 JPA 트랜잭션 → -handler)의 중복 전달·실패 재처리는 `InboxRedeliveryIntegrationTest`(lane -`messagingInboxRedeliveryIntegrationTest`)가 확인한다. 애플리케이션 handler가 쓰기 use case를 부르는 방법 -(`@SystemCaller` handler가 `@SystemInvoked` use case를 직접 만든다)은 `docs/manual/09-outbox-events.md` -「소비」 4단계다. - -### 복합 키 - -`PRIMARY KEY (message_id, consumer_id)`. - -message_id만으로 중복 제거하면 같은 event를 소비하는 두 번째 consumer가 -첫 번째에 의해 억제된다. 각 consumer가 한 번씩 처리해야 한다. - -### retention - -broker의 최대 redelivery window보다 **길어야** 한다. -row를 먼저 지우면 늦게 도착한 redelivery가 두 번 처리된다. - -outbox·inbox cleanup job은 한 번에 최대 1,000행씩 지우고, 지운 수가 1,000보다 적으면 멈춘다. -repository port에는 개수 제한 없는 삭제 메서드가 없다. - -## CDC 대안 - -relay는 polling 하나뿐이다. Debezium Event Router 매핑(`DebeziumOutboxEventRouter` 등)은 조립하는 -곳이 없어 2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표). `messaging_outbox`의 -`routing_key` 컬럼은 남아 있으므로 CDC를 다시 들일 때 그 컬럼을 message key로 쓴다. - -## Claim Check - -1 MiB 초과 payload는 broker 프레임을 키우지 않고 외부 저장소로 offload한다. - -`ClaimCheckReference`는 digest를 **필수**로 가진다. claim check는 메시지를 서로 다른 retention과 -replication을 가진 두 시스템으로 쪼개므로, consumer는 producer가 저장한 바로 그 bytes를 받았음을 -증명할 수 있어야 한다. 그렇지 않으면 잘린 객체와 정상 객체를 구분할 수 없다. - -`ClaimCheckIntegrityGuard`는 fetch 전에 만료를, fetch 후에 크기와 digest를 검사한다. -digest 불일치는 `DESERIALIZATION`이 아니라 **validation** 실패로 분류한다. -bytes가 깨진 JSON인 게 아니라, 틀린 bytes이기 때문이다. diff --git a/docs/messaging/retry-dlq-redrive.md b/docs/messaging/retry-dlq-redrive.md deleted file mode 100644 index 9d64b635..00000000 --- a/docs/messaging/retry-dlq-redrive.md +++ /dev/null @@ -1,112 +0,0 @@ -# Retry · DLQ · Redrive - -## 자동 retry는 opt-in이다 - -일반 destination의 기본값은 **retry 없음**이다. 순서를 깨거나, 멱등하지 않은 side effect를 -증폭시키거나, 이미 throttle된 downstream을 더 때리는 retry는 보이는 실패보다 나쁘다. - -## 결정 순서 - -`DefaultRetryDecisionEngine`은 아래 순서를 위에서 아래로 평가한다. - -```text -1. non-retryable category → parking(DeadLetter) 또는 Reject -2. attempt >= maxAttempts → DeadLetter -3. PRESERVE + ordered + orderedStream capability → PauseAndRetry -4. mode=PAUSE_PARTITION → PauseAndRetry -5. mode=RETRY_DESTINATION + ALLOW_REORDER → PublishToRetryDestination -6. mode=INLINE|BLOCKING → RetryInline -7. mode=BROKER_DELAYED + delayedDelivery capability → PublishToRetryDestination -8. 그 외 → DeadLetter -``` - -**retryability를 attempt 예산보다 먼저** 검사한다. deserialization 실패는 payload가 바뀌지 않으므로 -재시도가 3번 더 실패할 뿐이다. 첫 delivery에서 바로 park한다. - -**순서 보존 전략을 재발행 전략보다 먼저** 검사한다. 둘 다 설정되어 있어도 ordered destination이 -reorder 경로로 흘러내리지 않는다. - -## 기본 non-retryable - -`DESERIALIZATION`, `AUTHENTICATION`, `AUTHORIZATION`, `CONFIGURATION`은 자동 retry하지 않는다. -매 redelivery마다 동일하게 실패하므로 부하만 늘어난다. -destination profile의 `retryableCategories`로 명시적으로 뒤집을 수는 있다. - -## Backoff - -`min(maxDelay, initialDelay * multiplier^(attempt-1))`, 이후 full jitter. - -full jitter는 `[0, delay]` 균등 분포다. jitter가 없으면 같은 초에 실패한 모든 consumer가 -같은 초에 재시도하고, downstream의 회복이 재시도 폭풍으로 즉시 무효화된다. - -## Kafka: pause-and-seek vs retry topic - -| 전략 | 순서 | 언제 | -|---|---|---| -| `PAUSE_PARTITION` | 유지 | ordered destination | -| `RETRY_DESTINATION` | 깨짐 | work queue, `ALLOW_REORDER` 명시 | - -pause-and-seek는 메시지가 로그의 자기 자리를 떠나지 않는다. partition을 멈추고, 기다리고, -같은 offset으로 seek해 재전달한다. 뒤의 메시지도 함께 기다리며 이것이 의도된 동작이다. - -`KafkaConsumerRegistrar`가 handler 실패(예외, settle 없이 끝남, timeout)를 다루는 방식: - -- 재전달은 destination `retry`의 backoff 뒤에 한다. 최소 1초. 0초 재시도는 없다. -- 같은 offset의 실패 횟수가 `retry.maxAttempts`에 닿으면 `KafkaQuarantinePublisher`에 쓰고, - 쓰기가 확인되면 offset을 넘긴다. quarantine이 없으면 backoff로 계속 재시도한다(메시지를 버리지 - 않는다). 그래서 `production` destination은 quarantine 없이 만들 수 없다(`KAFKA_QUARANTINE_REQUIRED`). -- handler timeout이 지나도 handler가 끝날 때까지 partition slot을 잡고 있는다. `CompletableFuture`를 - cancel해도 handler는 멈추지 않으므로, slot을 먼저 풀면 같은 offset이 두 번 동시에 돈다. - -## RabbitMQ: delayed retry queue - -core broker에 per-message delay가 없으므로 **TTL + DLX**로 구현한다. -retry queue의 `x-message-ttl`이 만료되면 `x-dead-letter-exchange`를 통해 work queue로 되돌아간다. - -주의: TTL 만료는 큐 **head**에서 평가된다. 하나의 retry queue에 서로 다른 delay를 섞으면 -독립적으로 만료되지 않는다. - -`basic.nack(requeue=true)`는 사용하지 않는다. delay 없이 큐 head로 되돌리므로 hot loop가 된다. - -## DLQ: publish 확인 후 settlement - -이것이 dead lettering이 데이터 손실이 되지 않게 하는 **유일한** 불변식이다. - -```text -DLQ envelope 생성 (원래 messageId 유지) -→ DLQ publish -→ CONFIRMED 이면 source settlement -→ REJECTED / AMBIGUOUS 이면 source를 settlement하지 않음 -``` - -source를 먼저 ACK하면, DLQ publish가 실패했을 때 메시지의 사본이 **어디에도 남지 않는다**. -broker는 이미 해제했고 DLQ는 받지 못했다. - -AMBIGUOUS DLQ publish는 중복을 만든다. 이것이 의도된 trade다. DLQ는 사람이 읽는 곳이고 -중복은 알아볼 수 있지만, 손실은 복구할 수 없다. - -## DLQ envelope 내용 - -reserved header에만 기록한다. payload에 넣지 않는다. - -```text -msg.failure-category, msg.failure-code, msg.origin-destination, -msg.retry-attempt, msg.first-failure-at, msg.last-failure-at -``` - -stack trace, exception message, secret header, 실제 key는 **넣지 않는다**. -DLQ는 원본 topic보다 오래 보관되고 더 많은 사람이 읽는다. - -## Redrive - -M4 Admin 전용이다. `DestructiveOperationGuard`를 통과해야 한다. - -- admin credential 필요 (application runtime은 보유하지 않는다) -- 유효기간 내 `AdminApproval` 필요 -- dry-run은 항상 허용 (계획이 공짜여야 사람이 계획한다) -- batch 상한 100건 -- source == target 금지 -- `redriveId`는 `messageId`와 별개다. 재구동 루프를 식별하기 위해서다. - -redrive도 **publish → settlement** 순서다. republish가 confirm되지 않은 메시지는 -DLQ에 남는다. diff --git a/docs/messaging/security.md b/docs/messaging/security.md deleted file mode 100644 index 16e8359b..00000000 --- a/docs/messaging/security.md +++ /dev/null @@ -1,112 +0,0 @@ -# Messaging 보안 - -## Credential 분리 - -producer / consumer / admin은 **서로 다른 credential**이다. -`MessageSecurityValidator`가 startup에서 강제한다. - -```text -producer credential == consumer credential → 실패 -admin credential == producer|consumer → 실패 -production 프로필에 admin credential 존재 → 실패 -``` - -마지막 규칙이 "애플리케이션은 topic을 purge할 수 없다"를 **구조적으로** 만든다. -runtime이 admin 자격 증명을 아예 보유하지 않으므로, 침해된 handler가 상승시킬 대상이 없다. - -## Production 필수 조건 - -- TLS 활성 -- TLS hostname verification 활성 -- broker authentication 활성 -- topology auto-create 비활성 - -broker 인증서는 `subjectAltName`에 접속 이름을 가져야 한다. hostname verification은 SAN을 보므로, SAN이 -없는 인증서는 실패하는 것이 맞다. 검사를 끄지 않는다. 키와 인증서는 배포 환경의 PKI가 발급해 실행 때 -마운트하고, repo에 두지 않는다. - -Kafka는 추가로 `enable.idempotence=true`, `acks=all`, -`max.in.flight.requests.per.connection <= 5`, consumer auto-commit 금지. - -RabbitMQ는 추가로 publisher confirm, publisher return, `mandatory=true`, -durable work queue의 quorum queue, consumer auto-ack 금지. - -## Credential은 값이 아니라 참조다 - -`BrokerCredentialProfile`의 어떤 variant도 secret을 담지 않는다. -식별자만 보관하고 connect 시점에 `CredentialProvider`로 해석한다. -heap dump나 설정 출력에서 사용 가능한 credential이 나오지 않는다. - -`CredentialIds`는 `bearer `, `sk-`, `-----begin`, `eyJ` 같은 접두사를 거부한다. -참조가 들어갈 자리에 secret 자체를 붙여넣는 가장 흔한 사고를 막는다. - -SASL(PLAIN·SCRAM) 사용자 이름도 `CredentialProvider.username(credentialId)`가 준다. credential id는 -저장소 안의 참조이지 broker가 아는 사용자 이름이 아니다. provider가 이름을 주지 않으면 기동에 -실패한다. - -key store·trust store는 경로만 설정에 둔다. 비밀번호는 credential id로 provider가 해석한다 -(`configuration-reference.md` 보안 절). - -## Rotation - -`CredentialRotationPlan.isDue()`는 만료 **전에** 참이 된다. -broker가 연결을 거부하기 시작한 시점에는 이미 publish가 실패하고 consumer가 멈춰 있다. - -Kafka SASL credential은 producer를 다시 만들지 않고 바뀐다. JAAS 설정에는 login module 이름만 -있고, `KafkaCredentialCallbackHandler`가 연결이 인증할 때마다 `CredentialRuntimeRegistry`에서 -사용자 이름과 비밀번호를 읽는다. registry는 provider가 준 만료 시각의 rotation lead(기본 30분) -안으로 들어오면 새로 가져오므로, 새 연결과 재인증(broker `connections.max.reauth.ms`)이 새 값을 -쓴다. 만료 시각을 주지 않는 provider의 credential은 캐시된 값을 계속 쓴다. - -key store·trust store 비밀번호는 예외다. Kafka가 SSL context를 만들 때 한 번 읽으므로 바꾸려면 -producer를 다시 만들어야 한다(재기동). - -transport 세대 교체(`DefaultMessagingRuntimeRegistry.install()`)는 transport 자체를 바꿀 때 쓴다. -새 세대를 원자적으로 게시하고, 이전 세대는 마지막 lease가 닫힐 때까지 열려 있다가 닫힌다. -drain deadline이 이 대기를 제한한다. - -## Header - -금지 header는 application·platform 양쪽에서 거부한다. - -```text -Authorization, Proxy-Authorization, Cookie, Set-Cookie, -access_token, refresh_token, api_key, password, client_secret -``` - -credential이 header에 들어가면 broker storage, DLQ dump, 운영 도구에 남는다. -downstream redaction으로는 되돌릴 수 없다. - -예약 header(`msg.*`, `traceparent`, `tracestate`, `baggage`)는 platform만 쓴다. -application이 `msg.id`를 설정할 수 있으면 Inbox 중복 제거와 DLQ 상관관계가 의존하는 -logical identity가 호출자 제어가 된다. - -## ACL - -publisher가 broker ACL **이전에** 검사한다(`PUBLISH_FORBIDDEN`). -broker ACL 거부는 애플리케이션 컨텍스트가 없는 연결 수준 오류로 도착하므로 -"어느 모듈이 어디에 publish하려 했는가"가 조사 대상이 된다. - -publish 가능한 destination은 선언된 destination이다. broker에 `app.messaging.security.` -항목이 있으면 그중 `access.publishable`에 적힌 것만 남는다(빈 목록이면 publish 불가). - -## 관측성 누출 - -`MessagingRedactor`는 denylist다. - -- secret: authorization, cookie, token, password, secret, credential -- per-message identity: messageId, correlationId, causationId, partitionKey, key, offset, deliveryTag, sequence -- payload: payload, body, data -- 예외 상세: exceptionMessage, stackTrace - -identity를 지우는 이유는 두 가지다. bounded metric을 message당 하나의 series로 만들고, -support log를 재식별 표면으로 만들기 때문이다. - -`CardinalityGuard`는 dimension당 값 개수를 상한한다. -cardinality 사고는 점진적이지 않다. 테스트 10건에서는 멀쩡하고 운영에서 백엔드를 죽인다. - -## 감사 - -`MessagingAuditEvent`는 replay, redrive, offset reset, purge, delete를 기록한다. -subject(운영자 identity), approval ticket, 그리고 redactor를 통과한 details만 담는다. -누가 무엇을 했는지 증명하되 payload의 두 번째 사본이 되지 않는다. diff --git a/docs/messaging/support-matrix.md b/docs/messaging/support-matrix.md deleted file mode 100644 index d0325b2e..00000000 --- a/docs/messaging/support-matrix.md +++ /dev/null @@ -1,154 +0,0 @@ -# Messaging 지원 매트릭스 - -플랫폼이 **무엇을 보장하는지**와 **무엇을 보장하지 않는지**를 브로커별로 고정한다. -여기 없는 조합은 지원되지 않는다. - -> **등급은 증거를 따른다.** `CompatibilityMatrix.Entry.hasLiveBrokerCertification()`은 선언된 -> boolean이 아니라 `CertifiedEvidence`가 가진 레인 증거에서 파생된다. 레인이 생겨 증거를 내면 등급은 -> 코드 수정 없이 따라 올라간다. - -> **삭제된 어댑터.** RabbitMQ(선택할 수 없던 validator·설정 모음), Pulsar·NATS JetStream·Kafka Share -> Group(Experimental, SDK 없는 seam), Spring Cloud Stream bridge, Debezium outbox 매핑은 2026-09-25에 -> 삭제했다. 복구 경로는 `docs/capability-status.md`의 제거 표에 있다. - -> **인증 근거.** 이 표의 버전은 이 저장소의 컨테이너 레인이 실제로 실행한 이미지다. 이전 판은 -> Kafka 4.2/4.3을 선언했지만 fixture는 `apache/kafka:4.1.0`, lockfile client는 4.1.1이었다 — 표와 -> 코드 상수가 서로 일치했을 뿐 어느 쪽도 실행된 적이 없었다. 장애 시나리오 커버리지도 마찬가지로 -> `BrokerFailureMatrix.shipped()` 하드코딩이 아니라 레인이 낸 증거(`BrokerCertificationEvidence`)에서 -> 나온다. 증거가 없는 조합은 `NOT_COVERED`다 (MSG-014). - -> **모듈 이름과 런타임 편입.** 관계형 신뢰성 구현은 `messaging-reliability-jdbc-postgresql`, -> 그 port만 보는 relay·consumer 로직은 `messaging-reliability`다(2026-09-28에 -> `messaging-outbox-jdbc-postgresql` / `messaging-inbox-jdbc-postgresql`을 이렇게 나눴다). 그 전에는 -> `-jpa`로 불렸다. 구현은 Spring JDBC이고 SQL은 PostgreSQL 전용(`jsonb`, -> `FOR UPDATE SKIP LOCKED`, `ON CONFLICT`, `TIMESTAMPTZ`)이므로, 그 이름은 쓰지 않는 기술을 -> 광고하고 vendor 중립 port(`messaging-reliability-api`)의 위치를 가렸다 (MSG-023). -> -> `modules.json`은 messaging leaf의 `gradle_path`와 허용 의존성을 관리하지만 -> `runtime_memberships` 필드는 없다. 실제 런타임 편입은 `app-bootstrap`의 Gradle 의존성과 starter / -> auto-configuration 경로가 결정한다. 아래 등급은 "무엇이 증명되었는가"를 말하며 런타임 편입 여부와 -> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/AGENTS.md`가 소유한다. - -## 브로커 등급 - -| 브로커 | 등급 | 인증 기준 | Stable 기능 | 제한 | -|---|---|---|---|---| -| Kafka | Stable | 4.1.x | producer idempotence, consumer group, batch, pause/resume, replay, transaction capability | Share Group 미지원 | -| Artemis/JMS | Extension | 범위 밖 | adapter SPI만 | 별도 ADR + Contract Suite 통과 필요 | - -## Capability 매트릭스 - -`MessagingCapabilities`가 런타임에 선언하는 값이다. `false`인 기능을 요구하는 destination profile은 -**startup에서 실패**하며, 조용히 약화되지 않는다. - -| Capability | Kafka | -|---|---| -| brokerAcknowledgement | O | -| replicationOrPersistenceEvidence | O | -| perMessageSettlement | O | -| batchSettlement | O | -| orderedStream | O | -| keyedOrdering | O | -| replay | O | -| delayedDelivery | X | -| brokerTransaction | O | -| deduplicatedPublish | O | -| nativeDeadLetter | X | -| topologyManagement | O | - -## 기능 등급 - -| 기능 | 등급 | -|---|---| -| Typed Publish·Consume | Stable M1 | -| At-least-once contract | Stable | -| Ambiguous publish 결과 | Stable | -| handler 성공 후 자동 settlement | Stable M1 | -| Batch / Manual settlement / Pause·Resume / Delayed / Replay 요청 | M2 | -| Broker transaction / partition / routing / subscription | M3 | -| Replay 실행 / Redrive / offset reset / purge / delete | M4 Admin | - -## 무엇이 "Stable"을 증명하는가 - -Stable 등급은 두 가지를 **모두** 통과해야 한다. `CompatibilityMatrixTest`가 이 규칙을 강제한다. - -### 1. 공유 Contract Suite (`MessagingAdapterContract`, 7개) - -Kafka가 7개 테스트를 변경 없이 통과한다. 결정적 하네스를 쓰므로 -확인 유실·settlement 유실 같은 장애를 요청 시점에 재현할 수 있다. - -### 2. 실 브로커 인증 (Testcontainers) - -| 스위트 | 무엇을 증명하는가 | -|---|---| -| `KafkaBrokerIT` | `acks=all`이 실제 replication 증거를 만든다 / 잘못된 토픽은 `REJECTED` / 발행-소비 왕복에서 identity 보존 및 contiguous commit | -| `KafkaAmbiguityChaosIT` | 브로커를 `docker pause`로 멈춘 상태의 publish가 **`AMBIGUOUS`** 로 보고된다 (broker acceptance 없음, confirmation level `NONE`, 비-retryable) | -| `KafkaBrokerCertificationIT` | 인증 레인. Toxiproxy를 broker 앞에 두고 connection cut / confirm 유실 / 지연 / settlement 유실을 각각 주입하고, 통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을 manifest에 쓴다 | -| `OutboxPostgresIT` | 롤백된 트랜잭션은 발행 가능한 행을 남기지 않는다 / `SKIP LOCKED` lease가 두 relay를 분리한다 / ambiguous 행이 같은 `messageId`로 재클레임된다 | -| `InboxPostgresIT` | 재전달이 side effect를 두 번 적용하지 않는다 / 롤백은 예약도 되돌린다 | - -Docker가 없으면 `DockerAvailability` 가드로 skip되며, 이 표의 항목은 그때 **검증되지 않은 것**으로 취급한다. -`KafkaBrokerCertificationIT`만 예외다 — 인증 레인은 가드를 달지 않고 Docker가 없으면 실패한다. skip하는 -레인은 아무도 켜지 않은 브로커에 대해 성공을 보고하기 때문이다. 그래서 이 레인은 `test`에서 태그로 -제외되고 `messagingCertificationTest`로만 실행된다. - -### 3. 장애 시나리오 커버리지 (`BrokerFailureMatrix`) - -`NetworkFaultScenario`가 5개 시나리오와 **각각의 기대 결과**를 코드로 고정한다. 기대 결과를 어댑터별로 -두지 않는 것이 핵심이다 — 어댑터마다 다른 답을 허용하면 공유 계약이 존재할 이유가 없다. - -| 시나리오 | 시점 | 기대 결과 | 이유 | -|---|---|---|---| -| `connection-refused` | 전송 전 | `REJECTED` | 바이트가 나가지 않았으므로 broker가 가질 수 없다 | -| `connection-cut-after-write` | 전송 후 | `AMBIGUOUS` | broker가 저장했고 confirm만 유실됐을 수 있다 | -| `confirm-timeout` | 전송 후 | `AMBIGUOUS` | timeout은 부재의 증거가 아니라 증거의 부재다 | -| `settlement-lost` | settlement 중 | `REDELIVERED` | 미settlement 메시지는 재전달이 설계다 | -| `high-latency` | 전송 후 | `AMBIGUOUS` | 판단 시점에는 confirm 유실과 구별할 수 없다 | - -`CrossBrokerContractSuite`가 릴리스 게이트로 이를 강제한다. Stable 어댑터는 5개 전부를 **실 브로커에서** -커버해야 하고, Experimental 어댑터는 `LIVE_BROKER` 커버리지를 주장할 수 없다. 커버리지는 *능력*이 아니라 -*무엇을 실제로 돌렸는지*의 기록이다. - -**증거의 출처.** `CertifiedEvidence`는 더 이상 손으로 쓴 목록이 아니라 -`messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl`을 읽는다. 그 파일은 -`messagingCertificationTest` 레인이 실제 Kafka 컨테이너에 장애를 주입하며 만들어낸 출력이고, -`verifyMessagingCertificationEvidence`가 커밋된 manifest와 이번 실행의 출력을 대조해 다르면 빌드를 -실패시킨다. 즉 **manifest를 손으로 고치면 게이트가 깨지고, 레인을 돌리면 manifest가 다시 쓰인다.** - -오늘 Kafka가 가진 증거는 `connection-cut-after-write` · `confirm-timeout` · `high-latency` · -`settlement-lost` 네 개다. `connection-refused`는 남은 gap이며 그 이유가 있다 — Kafka producer는 연결 -존재 여부를 알기 전에 레코드를 버퍼에 넣으므로, 연결 거부는 전송에 대해 아무것도 증명하지 못하는 -delivery timeout으로 나타난다. 이를 `REJECTED`로 보고하는 것은 이 플랫폼이 금지한 추측이므로, -시나리오는 `CertifiedEvidence.knownGaps`가 이름으로 들고 있는 미커버 항목으로 남는다. - -### 실 브로커가 실제로 잡아낸 결함 - -이 스위트들은 장식이 아니다. 작성 과정에서 결정적 테스트가 통과하는데 실 인프라에서 실패한 -결함을 두 건 잡았다. - -1. **Outbox `IN_FLIGHT` 고아 행** — lease 쿼리가 `PENDING`/`AMBIGUOUS`만 클레임 대상으로 봐서, - publish 도중 죽은 relay가 남긴 행이 lease 만료 후에도 영영 회수되지 않았다. -2. **Rabbit confirm 경합**(2026-09-25에 삭제된 Rabbit transport) — transport가 publish *후에* confirm을 등록해서, 연결 스레드에서 - confirm이 먼저 도착하면 유실되고 호출자가 무한 대기했다. - -둘 다 인메모리 double이 실제보다 관대해서 통과하고 있었다. - -## 명시적 비지원 - -- 공통 `EXACTLY_ONCE` 설정 — `DeliveryGuarantee`에 상수가 존재하지 않는다. -- 전역 순서 — `OrderingScope`에 `GLOBAL`이 존재하지 않는다. -- DB와 broker의 자동 원자 transaction, 기본 XA -- Java native serialization -- 무제한 payload·header, 무한 retry -- 운영 application에서의 topology 파괴 작업 -- 일반 애플리케이션에 raw broker client 반환 -- DLQ publish 확인 전 source ACK - - -### Optional mapping utilities - -- `messaging-cloudevents`는 starter runtime에 자동 편입되지 않는 **opt-in mapping utility**다. - 내부 envelope와 CloudEvent 객체 사이의 제한된 profile mapping을 제공하지만 binary/structured - CloudEvents wire mode 전체를 구현하거나 임의 CloudEvents producer와의 1.0 interoperability를 - 인증하지 않는다. -- `messaging-claim-check`도 starter에 편입되지 않는 opt-in utility다. diff --git a/docs/registries/env-keys.yaml b/docs/registries/env-keys.yaml index fb2a3b8a..8cc899ac 100644 --- a/docs/registries/env-keys.yaml +++ b/docs/registries/env-keys.yaml @@ -2836,7 +2836,7 @@ env_keys: - name: APP_MESSAGING_BROKER # source: messaging multi-broker redesign 2026-06-16 — 활성 broker 하나를 고른다 - # (app.messaging.broker=). 들여온 메시징 플랫폼이 읽는다. 옛 Kafka 전용 APP_MESSAGING_KAFKA_ENABLED를 + # (app.messaging.broker=). 메시징 라이브러리(dev.cakit.messaging)가 읽는다. 옛 Kafka 전용 APP_MESSAGING_KAFKA_ENABLED를 # 대신한다. 애플리케이션 bridge는 이제 읽지 않는다: 읽던 옛 KafkaSender seam은 canonical outbox와 함께 # 지웠다(2026-09-28). type: string diff --git a/docs/upgrade/2026-11-maturity-review.md b/docs/upgrade/2026-11-maturity-review.md index 6196463b..78c51df1 100644 --- a/docs/upgrade/2026-11-maturity-review.md +++ b/docs/upgrade/2026-11-maturity-review.md @@ -162,6 +162,19 @@ PR 단계 trivy 검사(`dependency-vulnerability.yml`의 HIGH·CRITICAL 단계) | B-55 | 삭제: `src/platforms/grpc`, `src/platforms/grpc-advanced`, `src/platforms/optional-build`(두 번째 빌드 `optional-platforms` 전체), registry의 `"build": "optional-grpc"` 9행, workflow job `ci-quality-gates.yml` `optional-platforms`·`grpc-proto-buf`(그리고 `release-gate`의 두 `needs`), `integration-main.yml`의 optional 성능 단계와 job `grpc-optional-platform-integration`, `release.yml` job `grpc-stable-release-gate`(그리고 이미지 job의 `needs` 한 줄), 살아 있는 문서 `docs/compatibility/`(폴더째), `docs/runbooks/grpc-platform-operations.md`·`grpc-advanced-capabilities.md`. 새 자리는 grpc-library repo이고 같은 이름의 파일이 이력째 있다. 기록(`docs/adr/ADR-GRPC-*` 7개, `docs/design/2026-08-30-grpc-platform-adaptation-design.md`)은 본문을 두고 머리 블록 「현재 정본」만 그 repo를 가리키게 했다. 사본이 그 repo에도 있다. 그 repo에서 Maven group과 Java 패키지는 `dev.cakit.grpc`, proto 패키지는 `cakit.grpc.common.v1`이다(템플릿 재사용 체크리스트의 `dev.caskeleton` 바꾸기와 겹치지 않게 다른 이름) | 이 경로를 고친 서비스는 「수정 대 삭제」 충돌이 난다. `project(':grpc:…')`·`project(':grpc-advanced:…')`나 `-p platforms/optional-build`를 쓴 서비스는 빌드가 실패한다 | 쓰지 않았으면 삭제를 그대로 받는다. 썼으면 grpc-library 첫 버전(`1.0.0`, 소유자가 태그를 단 뒤)을 좌표 `dev.cakit.grpc:<모듈>:1.0.0`으로 받고(저장소 선언은 그 repo README 「받는 법」), import를 `dev.caskeleton.grpc` → `dev.cakit.grpc`로 바꾼다 | design-docs `repo-structure/05-library-repos.md` 4·13절, `docs/work/reference/related-repos.md` | | B-56 | 빌드 규칙·카탈로그: build-logic의 `ca.grpc-platform-module`·`ca.optional-architecture-registry` 플러그인과 `MainBuild`(두 번째 빌드에서 주 빌드를 찾던 것)를 지웠다. 도구 설정·테스트 이미지 목록·registry는 Gradle 루트(`src/`)에서만 찾는다. 카탈로그에서 `protobufPlugin`·`protobuf-java-grpc`·`protoc`·plugin `protobuf`를, SpotBugs 제외에서 gRPC 플랫폼 클래스 줄을 지웠다 | 서비스 leaf가 `ca.grpc-platform-module`이나 `libs.protoc`·`libs.protobuf.java.grpc`·`libs.plugins.protobuf`를 쓰면 빌드가 실패한다. `src/` 밖 두 번째 빌드에서 이 build-logic을 쓰던 서비스는 도구 설정을 못 찾는다 | 그 leaf `build.gradle`에서 `io.grpc:grpc-bom` import와 protobuf 플러그인 버전을 직접 적거나, 지운 카탈로그 항목을 서비스 카탈로그에 다시 더한다 | 같은 설계 13.1절 2단계 | +### 3.9 메시징 플랫폼 — 별도 repo `messaging-library`로 옮기고 버전 1.0.0으로 받는다 + +이 절도 위 머리의 범위보다 뒤에 main에 들어간다. 범위: `2959eff0..claude/x3-messaging-library-1aa3fa`(2026-11-08, 같은 +소유자 결정, design-docs `repo-structure/05-library-repos.md` 13.1절 3~5단계). 메시징은 템플릿 adapter 넷이 쓰므로, 라이브러리를 +먼저 `dev.cakit.messaging` 1.0.0으로 Gitea Packages에 배포하고 템플릿이 그 버전을 받게 바꿨다. 코드와 이력은 +https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library 에 있다. 동작은 같다(같은 소스, 패키지 이름만 바뀜). + +| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 | +|---|---|---|---|---| +| B-57 | 삭제: `src/platforms/messaging`(19개 모듈)과 빈 `src/platforms/`, registry의 메시징 19행, workflow `messaging-certification.yml`, 저장소 계약 테스트 `MessagingPublicSurfaceContractTest`(라이브러리 repo로), 살아 있는 문서 `docs/messaging/`(폴더째, 같은 이름으로 라이브러리 repo에), SpotBugs 제외의 메시징 클래스 줄, 카탈로그의 메시징 전용 항목(`avro`, `cloudevents`, `protobuf` 4.33.2와 `protobuf-java`). `check-repo-layout.py` 허용 목록에서 `platforms`를 뺐다. 메시징 기록(`docs/design/2026-08-10-messaging-platform-design.md` 등)은 본문을 두고 머리 블록 「현재 정본」만 고쳤다 | 이 경로를 고친 서비스는 「수정 대 삭제」 충돌. `project(':messaging:…')`를 쓴 자기 leaf는 빌드가 실패한다. `src/platforms/` 아래 자기 폴더를 둔 서비스는 `check-repo-layout.py`가 실패한다 | 메시징 코드를 고쳤으면 그 수정을 messaging-library repo로 보낸다(`docs/work/reference/related-repos.md` 2절). 자기 leaf의 `project(':messaging:<모듈>')`은 B-58처럼 좌표로 바꾼다 | design-docs `repo-structure/05-library-repos.md` 4·13절 | +| B-58 | 받는 법: `src/settings.gradle`에 Gitea Packages 저장소를 `exclusiveContent`(group `dev.cakit`와 그 아래만)로 더했다. 카탈로그에 `messagingLibrary = "1.0.0"`과 모듈 여섯(`libs.messaging.core.api` 등). 쓰는 leaf(`adapter:outbound:messaging`, `adapter:outbound:messaging-kafka`, `adapter:inbound:messaging`, 시험만 `composition:outbox-relay`·`adapter:outbound:persistence-jpa`)가 좌표로 받는다. Java 패키지 `dev.caskeleton.messaging` → `dev.cakit.messaging`, auto-configuration 이름 `dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration`. 그대로인 것: 설정 키 `app.messaging.*`, env 키, Flyway 위치 `db/migration/messaging`과 파일, 표 이름 | 메시징 타입을 import한 자기 코드가 컴파일되지 않는다. `afterName`·`beforeName`으로 플랫폼 root 이름을 적은 자기 auto-configuration은 순서 제약이 조용히 사라진다. 캐시가 빈 빌드(새 기계, 이미지 builder)는 `git.learn.hyeonworks.com`에 닿아야 한다 | import와 이름 문자열의 `dev.caskeleton.messaging`을 `dev.cakit.messaging`으로 바꾼다(템플릿 재사용 체크리스트의 `dev.caskeleton` 바꾸기에 넣지 않는다). merge 뒤 `./gradlew resolveAndLockAll --write-locks`. 빌드 기계가 Gitea에 닿는지 본다(공개 owner라 토큰은 필요 없다) | messaging-library `CHANGELOG.md` 1.0.0 | +| B-59 | registry 칸 둘: 맨 위 `library_groups`(`["dev.cakit"]`)와 행마다 `allowed_libraries`(`group:artifact`). 방향 검사(`verifyModuleDependencyDirection`)가 소유 group 라이브러리의 운영 선언(`runtimeOnly` 포함)과 컴파일에서 보이는 모듈을 그 칸과 대조한다. build-logic `ModuleRegistry`·`VerifyModuleDependencyDirectionTask`가 바뀌었다 | 자기 leaf가 `dev.cakit.*` 모듈을 칸에 적지 않고 쓰면 `verifyCleanArchitectureDependencies`가 「forbidden library dependencies」로 실패한다. registry를 읽는 자기 도구가 모르는 키를 거절하면 실패한다 | 그 leaf 행에 `allowed_libraries`를 적는다(`src/config/architecture/README.md` 「별도 repo 라이브러리」). build-logic을 고쳐 쓴 서비스는 두 파일 병합 충돌을 푼다 | 같은 설계 10.2절 T2(Q11) | + ## 4. DB 마이그레이션 ### 4.1 새 버전과 영향 diff --git a/docs/work/delegate.md b/docs/work/delegate.md index 22e50aa0..e8f10065 100644 --- a/docs/work/delegate.md +++ b/docs/work/delegate.md @@ -54,7 +54,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 | inbound 전송 | `src/adapter/inbound/*`. gRPC 플랫폼 라이브러리는 별도 repo `grpc-library`에서 고친다(`reference/related-repos.md`) | | persistence | `src/adapter/outbound/persistence-*`, 마이그레이션 | | outbound capability | 그 밖의 `src/adapter/outbound/*`, 멱등성 store | -| messaging | `src/platforms/messaging/*`, `src/adapter/outbound/messaging` | +| messaging | `src/adapter/inbound/messaging`, `src/adapter/outbound/messaging*`. 메시징 라이브러리는 별도 repo `messaging-library`에서 고친다(`reference/related-repos.md`) | | bootstrap·build·CI | `src/app-bootstrap`, `src/composition/*`, `src/build-logic`, `src/build.gradle`, `.github/` | | 보안(영역을 가로질러) | 인증·인가 체인, 비밀, 공개 경로 | | 문서 | `docs/` | diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md index 7d4551b2..6f994325 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -76,7 +76,7 @@ | --- | --- | --- | --- | | outbox relay·멱등성 executor 조립 | app-bootstrap이 아니라 별도 `composition:*` 모듈 | 소유자 | 결정 3 | | 새 leaf | `composition:durable-operation`, `adapter:inbound:messaging` 등록 승인 | 위임 | `1101` 15절 | -| edge 없는 복사본 | 템플릿 leaf는 `shared-contract` edge를 더해 정본을 쓴다. vendored(`messaging:*`)와 별도 repo 라이브러리는 복사본을 두고 family `AGENTS.md`(라이브러리는 그 모듈)에 이유 | 위임 | `1101` 15절(01-11) | +| edge 없는 복사본 | 템플릿 leaf는 `shared-contract` edge를 더해 정본을 쓴다. 별도 repo 라이브러리(messaging-library, grpc-library)는 복사본을 두고 그 repo의 모듈 지침에 이유 | 위임 | `1101` 15절(01-11) | | caller 트랜잭션 guard | `persistence-notification`·`persistence-fileserver` → `persistence-jpa` edge, `CallerTransaction` 하나 | 소유자 | 결정 33 | | id 포트 | notification·fileserver id 포트를 domain `IdFactory`로 옮기지 않음(보류) | 소유자 | 결정 34 | | 소비자 없는 필드 | principal tenant, GraphQL Spring Security resolver, 가명화 키 분리는 하지 않음(보류) | 소유자 | 결정 35 | @@ -85,8 +85,8 @@ | `@SystemInvoked` | bean으로 등록돼 있으면 기동 실패, inbound adapter가 직접 부르지 못하게 ArchUnit | 위임 | `1103` 4절(RR-01-02) | | 시스템 호출 경로 | 사용자가 닿는 전송(web·GraphQL·gRPC·WebSocket)만 `@SystemInvoked`에 닿지 못한다. 메시지 소비자·스케줄러는 `@SystemCaller(reason)` 표시로 허용 | 위임 | `1103` 9.1절(RR-01-12), 10절 r5-b | | 배치 규칙 검사 | 저장소 루트와 `src/` 최상위 허용 목록을 `scripts/check-repo-layout.py`로 PR에서 막는다. 리뷰 기준에도 넣는다(매뉴얼 보강 작업) | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 10.3절 | -| `src/` 배치 | 들여온 플랫폼 넷(`messaging`, `grpc`, `grpc-advanced`, optional 빌드)을 `src/platforms/` 아래로 묶는다. registry `source_path`만 바꾸고 Gradle 경로는 그대로 둔다. `build-logic`·`gradle`·`config`는 Gradle 루트 표준이라 남기고, `composition`은 조립 계층이라 옮기지 않는다. `config/`에서 기능 하나가 주인인 데이터 파일은 그 leaf로 보낸다. Gradle 루트를 저장소 루트로 옮길지는 CI 재편 때 다시 본다. gRPC 둘과 optional 빌드는 2026-11-08 별도 repo로 나갔다(아래 「라이브러리 repo」) | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.1절 | -| 라이브러리 repo | 프로젝트 계층이 아닌 라이브러리(메시징, gRPC)는 템플릿에 두지 않는다. 라이브러리마다 별도 repo에서 고치고 Gitea Packages에 버전으로 배포하며, 템플릿은 쓰는 라이브러리만 카탈로그 좌표로 받는다. gRPC가 먼저 `grpc-library`로 옮겼다(2026-11-08, 템플릿 소비자 없음이라 카탈로그 항목도 없음). 목록과 고치는 법은 `related-repos.md` | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.5절, `repo-structure/05-library-repos.md` 15절 | +| `src/` 배치 | 들여온 플랫폼 넷(`messaging`, `grpc`, `grpc-advanced`, optional 빌드)을 `src/platforms/` 아래로 묶는다. registry `source_path`만 바꾸고 Gradle 경로는 그대로 둔다. `build-logic`·`gradle`·`config`는 Gradle 루트 표준이라 남기고, `composition`은 조립 계층이라 옮기지 않는다. `config/`에서 기능 하나가 주인인 데이터 파일은 그 leaf로 보낸다. Gradle 루트를 저장소 루트로 옮길지는 CI 재편 때 다시 본다. 넷 모두 2026-11-08 별도 repo로 나갔고 `src/platforms/`는 지웠다(아래 「라이브러리 repo」) | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.1절 | +| 라이브러리 repo | 프로젝트 계층이 아닌 라이브러리(메시징, gRPC)는 템플릿에 두지 않는다. 라이브러리마다 별도 repo에서 고치고 Gitea Packages에 버전으로 배포하며, 템플릿은 쓰는 라이브러리만 카탈로그 좌표로 받는다. gRPC가 먼저 `grpc-library`로 옮겼다(2026-11-08, 템플릿 소비자 없음이라 카탈로그 항목도 없음). 메시징은 `messaging-library` 1.0.0으로 옮기고 쓰는 leaf가 카탈로그 `messagingLibrary`로 받는다(2026-11-08). 라이브러리 edge는 registry 「허용 라이브러리」 칸(`library_groups`·`allowed_libraries`)이 막는다(설계 Q11 T2). 목록과 고치는 법은 `related-repos.md` | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.5절, `repo-structure/05-library-repos.md` 15절 | | 개발 compose 파일 | 저장소 루트에 `compose.yaml` 하나. 뒷단 서비스는 capability 이름 profile로 고르고, 마운트하는 보조 파일은 `compose/`에 둔다. 테스트 lane fixture는 그 lane을 가진 leaf로 보낸다(compose lane → app-bootstrap `compose-lanes/`, Redis topology → redis-sdk, NFS → fileserver). `docker-compose.dev.yml`은 `dev` 배포 프로필이 뜨는지 보는 lane fixture로 app-bootstrap에 둔다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.3절 | | 인프라 실행 파일 | nginx 설정, Kubernetes PVC job, DB 역할 SQL은 이 repo에서 지우고, 기능이 운영 환경에 요구하는 조건만 그 기능 문서에 적는다. 아무도 쓰지 않는 infra 폴더 파일도 지운다. 지운 목록은 `docs/upgrade/2026-11-maturity-review.md` B-50 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.3절 | | 샘플 모듈 | 샘플 leaf와 샘플 전용 Dockerfile을 폴더째 지운다(지운 경로는 `docs/upgrade/2026-11-maturity-review.md` B-49). 역할은 옮기지 않는다. 샘플 안에만 있던 템플릿 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC)도 함께 지운다. 예시는 매뉴얼과 생성 명령 출력이 맡는다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.2절 | diff --git a/docs/work/reference/defect-patterns.md b/docs/work/reference/defect-patterns.md index f20356fc..c044a80d 100644 --- a/docs/work/reference/defect-patterns.md +++ b/docs/work/reference/defect-patterns.md @@ -121,7 +121,7 @@ | 규칙을 일부러 다르게 둔 타입 | 그 타입의 Javadoc | | 정적 분석 제외 | 제외 항목 옆 이유(`src/config/spotbugs/exclude-test.xml` 등) | | 규칙의 예외 경로 | 이유를 요구하는 표시(`@SystemCaller(reason)`) | -| 복사본을 남긴 이유 | 가까운 `AGENTS.md`(예: `src/platforms/messaging/AGENTS.md`) | +| 복사본을 남긴 이유 | 가까운 `AGENTS.md`. 복사본을 둔 leaf의 `build.gradle`이나 그 폴더의 `AGENTS.md`에 적는다 | | 되돌리기 비싼 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md` | ## 패턴을 더하는 법 diff --git a/docs/work/reference/gates.md b/docs/work/reference/gates.md index ef7224e1..9a623b3e 100644 --- a/docs/work/reference/gates.md +++ b/docs/work/reference/gates.md @@ -190,7 +190,7 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') | | 장치 | 고정하는 것 | 단계 | | --- | --- | --- | | 자원 한계 lane | Tomcat·Jetty 부하·느린 클라이언트·종료, HTTP client 풀·스트리밍·재시도, Hikari 풀 | `performanceCheck` | -| JMH 벤치마크 | `src/platforms/messaging/messaging-kafka/src/jmh`, `src/platforms/messaging/messaging-testkit/src/jmh`, `src/adapter/outbound/httpclient/src/jmh` | 명시 실행 | +| JMH 벤치마크 | `src/adapter/outbound/httpclient/src/jmh`(메시징 벤치마크는 messaging-library repo로 옮겼다) | 명시 실행 | ## 6. 게이트를 믿을 조건 — 거짓 통과 막기 diff --git a/docs/work/reference/related-repos.md b/docs/work/reference/related-repos.md index af907a42..bb8a020f 100644 --- a/docs/work/reference/related-repos.md +++ b/docs/work/reference/related-repos.md @@ -6,34 +6,42 @@ | repo | 무엇 | Maven group | 카탈로그 칸 | 쓰는 leaf | | --- | --- | --- | --- | --- | +| [messaging-library](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library) | 메시징 제품(발행·소비 API, Kafka transport, outbox·inbox, 인증 증거) | `dev.cakit.messaging` | `messagingLibrary` | `adapter:outbound:messaging`(core-api), `adapter:outbound:messaging-kafka`(starter-kafka, `runtimeOnly`), `adapter:inbound:messaging`(core-api, reliability, reliability-api, reliability-jdbc-postgresql). 시험만: `composition:outbox-relay`(starter, `testCompileOnly`), `adapter:outbound:persistence-jpa`(reliability-jdbc-postgresql jar의 migration) | | [grpc-library](https://git.learn.hyeonworks.com/donghyeon.kang/grpc-library) | gRPC 플랫폼(Stable 7, advanced 2) | `dev.cakit.grpc` | 없음(채택 전) | 없음. `adapter:inbound:grpc`는 `io.grpc`를 직접 쓴다. 채택은 별도 결정이다 | -| `messaging-library` | 메시징 제품 | `dev.cakit.messaging` | (옮긴 뒤 `messagingLibrary`) | 아직 `src/platforms/messaging`에 있다. 다음 분리 작업에서 옮긴다 | -고치는 법·게이트·릴리스는 각 repo의 `docs/work/`다. 이 repo의 매뉴얼은 위치만 가리킨다. +- 고치는 법·게이트·릴리스는 각 repo의 `docs/work/`다. 이 repo의 매뉴얼은 위치만 가리킨다. +- 템플릿은 `src/settings.gradle`의 `exclusiveContent` 저장소 하나로 받는다: `dev.cakit` group과 그 아래는 소유자 Gitea Packages에서만, 나머지는 Maven Central에서만 찾는다. 공개 owner라 읽기 토큰은 필요 없다. 이미지 빌드(`src/Dockerfile`의 `verifyDependencyLocks`)도 토큰 없이 Gitea에 닿아야 한다. +- 라이브러리 패키지(`dev.cakit.*`)는 템플릿 재사용 체크리스트의 「`dev.caskeleton`을 새 패키지로 바꾼다」에 들지 않는다. ## 2. 라이브러리를 고칠 때 - 템플릿 안에서 라이브러리 코드를 고치지 않는다. 라이브러리 repo에서 고치고 릴리스한다. -- 템플릿 변경 때문에 라이브러리를 고쳐야 하면 브랜치를 둘 만들고, 템플릿에서 명령 줄로만 끼워 같이 시험한다. +- 템플릿 변경 때문에 라이브러리를 고쳐야 하면 두 repo에 브랜치를 하나씩 만들고, 두 repo를 같은 부모 폴더에 둔다(desktop은 `~/workspace/`). 템플릿에서 명령 줄로만 라이브러리를 끼워 같이 시험한다(composite build: Gradle이 같은 `group:artifact`의 외부 의존성을 끼운 빌드의 프로젝트로 바꿔 끼운다). Gradle 루트가 `src/`라 경로는 두 단계 위다. ```bash - ./gradlew --include-build ../grpc-library <태스크> + ./gradlew --include-build ../../messaging-library <태스크> ``` - 그 상태로 lockfile을 쓰거나 커밋하지 않는다. -- 병합 순서는 하나다: 라이브러리 PR 병합 → 태그·릴리스 → 템플릿 PR에서 버전을 올리고 lockfile을 다시 쓴다 → 템플릿 병합. -- 라이브러리가 끌고 온 취약 의존성은 템플릿에서 먼저 덮어 막고(Boot 버전이나 카탈로그 `pinned-*`), 라이브러리 repo에 수정을 남긴다. + 그 상태로 lockfile을 쓰거나 커밋하지 않는다. 끼운 모듈은 lockfile 밖으로 빠질 수 있다. 끼운 빌드는 자기 카탈로그로 컴파일되므로 라이브러리 repo CI 결과와 다를 수 있다. 최종 판정은 배포한 좌표로 돈 템플릿 게이트다. +- 병합 순서는 하나다: 라이브러리 PR 병합 → 태그·릴리스 → 템플릿 PR에서 버전을 올리고 lockfile을 다시 쓴다 → 템플릿 병합. 끼운 상태로만 통과하는 템플릿 PR은 병합하지 않는다. +- 라이브러리가 끌고 온 취약 의존성은 템플릿에서 먼저 덮어 막고(Boot 버전이나 카탈로그 `pinned-*`. 지금 `pinned-lz4-java`·`pinned-snappy-java`는 메시징 라이브러리의 kafka-clients가 끌고 오는 것을 막는다), 라이브러리 repo에 수정을 남긴다. ## 3. 템플릿이 라이브러리 버전을 올릴 때 -라이브러리를 카탈로그로 받는 leaf가 생긴 뒤의 절차다(지금은 없다). +1. `src/gradle/libs.versions.toml`의 라이브러리 버전 칸(`messagingLibrary`)을 바꾼다. 같은 라이브러리의 모듈은 그 칸 하나로 같이 오른다. +2. desktop에서 `./gradlew resolveAndLockAll --write-locks` 뒤 `verifyDependencyLocks`. lockfile 차이는 그 라이브러리 줄과 그것이 끌고 오는 외부 의존성뿐이어야 한다. +3. 쓰는 leaf의 `check`와 `architectureCheck`, 그 leaf의 lane(메시징: `:adapter:inbound:messaging:messagingInboxRedeliveryIntegrationTest`, `:adapter:outbound:messaging-kafka:messagingKafkaRelayIntegrationTest`, persistence-jpa `test`의 migration 시험). +4. 라이브러리 `CHANGELOG.md`에서 그 사이 버전의 깨지는 변경을 읽는다. MAJOR면 `docs/upgrade/`에 행을 더하고 커밋 제목에 `!`. migration을 더한 버전이면 `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`에 줄을 더한다. +5. 커밋 제목 예: `build(deps): 메시징 라이브러리를 1.1.0으로 올린다`. -1. `src/gradle/libs.versions.toml`의 라이브러리 버전 칸을 바꾼다. -2. desktop에서 `./gradlew resolveAndLockAll --write-locks` 뒤 `verifyDependencyLocks`. -3. 쓰는 leaf의 `check`와 `architectureCheck`, 그 leaf의 lane. -4. 라이브러리 `CHANGELOG.md`에서 그 사이 버전의 깨지는 변경을 읽는다. MAJOR면 `docs/upgrade/`에 행을 더하고 커밋 제목에 `!`. -5. 커밋 제목 예: `build(deps): gRPC 라이브러리를 1.1.0으로 올린다`. +## 4. 경계 검사(registry) -## 4. 받는 법(처음 채택할 때) +라이브러리 모듈은 이 빌드의 프로젝트가 아니어서 `allowed_dependencies`가 보지 못한다. 그래서 registry가 두 칸을 더 가진다(`src/config/architecture/README.md` 「별도 repo 라이브러리」). -`src/settings.gradle`의 저장소 선언에 Gitea Maven 저장소를 `exclusiveContent`로 더한다. `dev.cakit` group은 그 저장소에서만, 나머지는 Maven Central에서만 찾는다. 선언 예는 라이브러리 repo README 「받는 법」이다. 공개 owner라 읽기 토큰은 필요 없다. +- 맨 위 `library_groups`(`["dev.cakit"]`): 다스릴 group 접두사. +- 행마다 `allowed_libraries`: 그 leaf가 쓸 수 있는 `group:artifact`. 운영 선언(`runtimeOnly` 포함)과 컴파일에서 보이는 소유 group 모듈이 모두 이 칸에 있어야 방향 검사가 통과한다. +- 새 라이브러리 모듈을 leaf에 들일 때는 카탈로그 항목, leaf `build.gradle`, 그 행의 `allowed_libraries`를 같은 변경에서 바꾼다. + +## 5. 처음 채택할 때(gRPC 같은 라이브러리) + +`src/settings.gradle`의 저장소 선언은 이미 `dev.cakit`를 덮으니 바꾸지 않는다. 카탈로그에 버전 칸 하나와 쓰는 모듈의 `[libraries]` 항목을 더하고(`version.ref`로 그 칸을 쓴다), 쓰는 leaf의 registry 행에 `allowed_libraries`를 적고, lockfile을 다시 쓴다. 1절 표에 카탈로그 칸과 쓰는 leaf를 적는다. diff --git a/docs/work/reference/review-criteria.md b/docs/work/reference/review-criteria.md index 20e92b6d..41b2ff3c 100644 --- a/docs/work/reference/review-criteria.md +++ b/docs/work/reference/review-criteria.md @@ -101,7 +101,7 @@ | # | 관점 | 볼 곳 | 이런 증거면 결함 | | --- | --- | --- | --- | | 1 | 코드 성숙도 | 바뀐 클래스와 호출자, 예외 경로 | 이름·Javadoc과 다른 동작, 항상 참·거짓인 조건 | -| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `AGENTS.md`, 저장소 루트와 `src/`의 최상위 목록(폴더마다 계층·조립 leaf, Gradle 루트 표준 `build-logic`·`gradle`·`config`, 지도에 적힌 예외 `platforms/`, 저장소 운영 `docs`·`scripts`·`.github` 중 하나인지) | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import, 역할을 한 문장으로 말할 수 없는 최상위 폴더, 같은 역할의 폴더가 같은 높이에 여럿, 지도(`AGENTS.md`)와 `scripts/check-repo-layout.py` 허용 목록에 없는 최상위 항목 | +| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `AGENTS.md`, 저장소 루트와 `src/`의 최상위 목록(폴더마다 계층·조립 leaf, Gradle 루트 표준 `build-logic`·`gradle`·`config`, 저장소 운영 `docs`·`scripts`·`.github` 중 하나인지) | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import, 역할을 한 문장으로 말할 수 없는 최상위 폴더, 같은 역할의 폴더가 같은 높이에 여럿, 지도(`AGENTS.md`)와 `scripts/check-repo-layout.py` 허용 목록에 없는 최상위 항목 | | 3 | 변경 용이성 | 기능 하나를 더하거나 뺄 때 고칠 파일, `scripts/new-feature.sh` 왕복 | 같은 규칙을 여러 곳에서 바꿔야 함 | | 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수, 루트 README만 읽고 구조·매뉴얼·첫 실행을 5분 안에 찾는가(cold-read 결과), 이벤트별 workflow job 수 | 예시·규칙이 여러 갈래이고 고르는 기준이 없음, 같은 Gradle 태스크를 두 단계 이상이 돎(의도한 행렬 제외) | | 5 | 위험 가시성 | 기본값, 설정 검증, 기동 rule, 프로필 허용 목록 | 위험이 기본값 뒤에 숨음, 레지스트리 `required`인데 코드는 빈 값 허용 | @@ -201,15 +201,15 @@ RED가 증거가 되려면: 실패 메시지가 그 결함을 말한다. 머신 - 새 업무 기능은 계층 leaf 안의 패키지가 기본이다(`docs/manual/03-placement.md`). - 템플릿 패키지 목록은 `src/application-core/README.md` 「패키지 소유 (Package ownership)」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다. - capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다. -- 다른 경계(다른 leaf, 다른 빌드, 다른 repo가 될 수 있는 폴더)의 파일을 경로(`../../../`)로 읽는 빌드 스크립트·테스트는 결함 후보다. 그 경계가 옮겨 가면 조용히 깨진다. gRPC 라이브러리를 옮길 때 이런 결합이 다섯 곳 나왔다(design-docs `repo-structure/05-library-repos.md` 4.6절). -- vendored family(`messaging:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `AGENTS.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다. +- 다른 경계(다른 leaf, 다른 빌드, 다른 repo가 될 수 있는 폴더)의 파일을 경로(`../../../`)로 읽는 빌드 스크립트·테스트는 결함 후보다. 그 경계가 옮겨 가면 조용히 깨진다. gRPC·메시징 라이브러리를 옮길 때 이런 결합이 다섯 곳 나왔다(design-docs `repo-structure/05-library-repos.md` 4.6절). 다른 repo의 파일이 필요하면 그 repo가 배포한 artifact에서 읽는다(예: persistence-jpa의 migration 시험이 메시징 라이브러리 jar의 `db/migration/messaging`을 푼다). +- 별도 repo 라이브러리(`dev.cakit.*`)는 템플릿 타입에 의존하지 않는다. 그래서 남는 복사본은 이유를 그 라이브러리 repo의 모듈 지침에 적는다. 템플릿 leaf가 라이브러리 모듈을 쓰면 registry 행의 `allowed_libraries`에 좌표를 적는다. 적지 않은 소유 group 모듈을 선언하거나 컴파일에서 보면 방향 검사가 실패한다. - source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 나눈다. 공유 테스트 코드는 `src/testFixtures/java`다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`). - 마이그레이션은 저장소마다 자기 디렉터리와 history table을 가진다. 번호는 스트림 안의 순번이다. 어딘가에 적용된 파일은 고치지 않는다(`src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`이 해시를 고정한다). - 문서 위치 규칙은 `docs/README.md`가 정본이다. leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼다: -- [ ] `src/config/architecture/modules.json`: ID, `source_path`, `gradle_path`, `allowed_dependencies` +- [ ] `src/config/architecture/modules.json`: ID, `source_path`, `gradle_path`, `allowed_dependencies`, 라이브러리를 쓰면 `allowed_libraries` - [ ] leaf `build.gradle`: `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 하나 - [ ] lockfile(`verifyDependencyLocks`가 통과하게 다시 만든다) - [ ] capability면 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄과 자기 `AutoConfiguration.imports` diff --git a/scripts/check-repo-layout.py b/scripts/check-repo-layout.py index 8c6e3412..28759245 100755 --- a/scripts/check-repo-layout.py +++ b/scripts/check-repo-layout.py @@ -58,7 +58,8 @@ ROOT_ALLOWED = { "testcontainers.properties.example": "Testcontainers 로컬 설정 예", } -# src/ 바로 아래: 계층·조립 leaf, 들여온 제품 묶음, Gradle 루트 표준 폴더와 빌드 파일. +# src/ 바로 아래: 계층·조립 leaf, Gradle 루트 표준 폴더와 빌드 파일. 계층이 아닌 라이브러리(메시징·gRPC)는 +# 2026-11-08에 별도 repo로 나갔다(docs/work/reference/related-repos.md). 그 자리(platforms)는 다시 두지 않는다. SRC_ALLOWED = { # 계층과 조립 "domain-core": "계층", @@ -70,8 +71,6 @@ SRC_ALLOWED = { "adapter": "계층(adapter leaf 묶음)", "composition": "조립(Clean Architecture의 Main)", "app-bootstrap": "조립 루트", - # 들여온 제품 - "platforms": "들여온 제품(messaging). gRPC는 2026-11-08 별도 repo grpc-library로", # Gradle 루트 표준 "build-logic": "빌드 규칙(included build)", "config": "빌드 전체 도구 설정(registry, checkstyle, spotbugs, 테스트 이미지)", diff --git a/scripts/hooks/hooks.py b/scripts/hooks/hooks.py index 1d32adb3..5110ecb4 100644 --- a/scripts/hooks/hooks.py +++ b/scripts/hooks/hooks.py @@ -46,14 +46,17 @@ SKIPPED = "포맷을 건너뛰었다" # --- N1: the layer rules the gates hold, checked on the imports of one edited main source -------------- # Mirrors DomainPurityArchitectureTest (DOMAIN_IS_PURE, DOMAIN_HAS_NO_LOGGER). +# dev.cakit.: the owner's libraries (messaging-library, grpc-library) are reached only through adapters; +# a layer row may not list one in allowed_libraries (registry library_groups, build-logic ArchitecturePlugin). DOMAIN_FORBIDDEN = ("org.springframework.", "jakarta.persistence.", "javax.persistence.", "jakarta.servlet.", "org.hibernate.", "lombok.", "org.slf4j.", "java.util.logging.", "ch.qos.logback.", - "org.apache.logging.log4j.") + "org.apache.logging.log4j.", "dev.cakit.") # Mirrors VerifyApplicationCoreDependencyPurityTask and the application-core AGENTS.md forbidden list. APPLICATION_FORBIDDEN = ("org.springframework.", "org.slf4j.", "ch.qos.logback.", "org.apache.logging.log4j.", "io.micrometer.", "java.util.logging.", "jakarta.persistence.", "javax.persistence.", - "lombok.") -SHARED_FORBIDDEN = ("org.springframework.", "jakarta.", "javax.persistence.", "org.hibernate.", "lombok.") + "lombok.", "dev.cakit.") +SHARED_FORBIDDEN = ("org.springframework.", "jakarta.", "javax.persistence.", "org.hibernate.", "lombok.", + "dev.cakit.") # HARD-STOP 2: an inbound adapter reaching the store. INBOUND_FORBIDDEN = ("org.springframework.data.repository.", "org.springframework.data.jpa.", "org.springframework.data.mongodb.repository.", "jakarta.persistence.", "javax.persistence.") diff --git a/scripts/tests/test_hooks.py b/scripts/tests/test_hooks.py index b5c1fa08..3808a3ea 100644 --- a/scripts/tests/test_hooks.py +++ b/scripts/tests/test_hooks.py @@ -252,6 +252,11 @@ class BoundaryNudgeTest(RepositoryTestCase): self.assertIn("HARD-STOP 1 의심: `domain-core`가 `org.springframework.stereotype.Component`", text) self.assertIn("architectureCheck", text) + def test_an_owned_library_in_the_application_is_flagged(self) -> None: + text = self.nudge("src/application-core", "dev/caskeleton/application/order/Notify.java", + "import dev.cakit.messaging.api.MessageEnvelope;") + self.assertIn("`application-core`가 `dev.cakit.messaging.api.MessageEnvelope`", text) + def test_an_inbound_dto_in_the_application_is_hard_stop_3(self) -> None: text = self.nudge("src/application-core", "dev/caskeleton/application/order/Place.java", "import dev.caskeleton.adapter.inbound.web.order.OrderRequest;") diff --git a/src/adapter/inbound/messaging/AGENTS.md b/src/adapter/inbound/messaging/AGENTS.md index e1637a6e..98d4e137 100644 --- a/src/adapter/inbound/messaging/AGENTS.md +++ b/src/adapter/inbound/messaging/AGENTS.md @@ -2,7 +2,7 @@ - 모듈 ID `adapter-inbound-messaging`, Gradle 경로 `:adapter:inbound:messaging`. registry 정본: `src/config/architecture/modules.json`. -- 책임: 들여온 메시징 플랫폼의 애플리케이션 소비 쪽이다 — 플랫폼이 애플리케이션에서 받아야 하는 +- 책임: 메시징 라이브러리(별도 repo messaging-library, Maven `dev.cakit.messaging`)의 애플리케이션 소비 쪽이다 — 라이브러리가 애플리케이션에서 받아야 하는 inbox 부품(애플리케이션 DataSource 위의 `JdbcInboxRepository`, 그 `PlatformTransactionManager` 위의 `TransactionRunner`, 자기 Flyway stream `MessagingInboxSchemaStream`인 inbox migration)과 애플리케이션의 `MessageHandler` 구현들이다. 핸들러 하나는 전달 하나를 유스케이스 호출 하나로 바꾼다. 핸들러는 그 밖에 @@ -14,7 +14,7 @@ (`docs/manual/09-outbox-events.md` 「소비 — 이벤트를 받는 쪽」 순서 4단계, `docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」, `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`, - `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`). 핸들러는 프로젝트 타입(`MessageHandler`)만 구현하고, + `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`). 핸들러는 프로젝트 타입(메시징 라이브러리의 `MessageHandler`. `dev.cakit..`도 프로젝트 타입으로 친다)만 구현하고, `Runnable`이나 프로젝트 밖의 다른 타입은 구현하지 않는다(`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`). - 시험: 자동 구성과 inbox 동작을 보는 시험. `./gradlew :adapter:inbound:messaging:check`. 실제 Kafka + PostgreSQL 재전달 lane은 `messagingInboxRedeliveryIntegrationTest`다(`:integrationCheck`). diff --git a/src/adapter/inbound/messaging/build.gradle b/src/adapter/inbound/messaging/build.gradle index 1c67b2ba..9eab0546 100644 --- a/src/adapter/inbound/messaging/build.gradle +++ b/src/adapter/inbound/messaging/build.gradle @@ -3,7 +3,7 @@ plugins { id 'ca.spring-config' } -// The application's consume side of the vendored messaging platform (review 2026-11-01 06-08), +// The application's consume side of the messaging library (dev.cakit.messaging, review 2026-11-01 06-08), // selected by one line in a composition root: // // runtimeOnly project(':adapter:inbound:messaging') @@ -29,14 +29,14 @@ base { dependencies { implementation project(':application-core') - implementation project(':messaging:messaging-core-api') - implementation project(':messaging:messaging-reliability') - implementation project(':messaging:messaging-reliability-api') - // JdbcInboxRepository only. The leaf also exports the platform admin journal (api - // messaging-admin), which this leaf has no use for and no registered edge to; the starter puts it - // on the runtime classpath anyway. - implementation(project(':messaging:messaging-reliability-jdbc-postgresql')) { - exclude group: 'dev.caskeleton', module: 'messaging-admin' + implementation libs.messaging.core.api + implementation libs.messaging.reliability + implementation libs.messaging.reliability.api + // JdbcInboxRepository only. The module also exports the library's admin journal (api + // messaging-admin), which this leaf has no use for and no registered library edge to; the starter + // puts it on the runtime classpath anyway. + implementation(libs.messaging.reliability.jdbc.postgresql) { + exclude group: 'dev.cakit.messaging', module: 'messaging-admin' } implementation 'org.springframework.boot:spring-boot-autoconfigure' @@ -76,7 +76,7 @@ configurations { // Test-only edges of the redelivery lane: the publishing side as a composition root selects it // (the Kafka capability, the outbox relay, the JPA outbox over PostgreSQL), the port owner's event -// fixture, and the platform's MessageContracts holder the consumer registers its payload type in. +// fixture, and the library's MessageContracts holder the consumer registers its payload type in. // Test edges are outside the registry gate. dependencies { integrationTestImplementation project(':adapter:outbound:messaging-kafka') @@ -84,8 +84,8 @@ dependencies { integrationTestImplementation project(':adapter:outbound:persistence-jpa') integrationTestImplementation project(':application-core') integrationTestImplementation testFixtures(project(':application-core')) - integrationTestImplementation project(':messaging:messaging-core-api') - integrationTestImplementation project(':messaging:messaging-spring-boot-starter') + integrationTestImplementation libs.messaging.core.api + integrationTestImplementation libs.messaging.spring.boot.starter integrationTestImplementation 'org.springframework:spring-jdbc' integrationTestImplementation 'org.flywaydb:flyway-core' integrationTestImplementation 'org.apache.kafka:kafka-clients' diff --git a/src/adapter/inbound/messaging/gradle.lockfile b/src/adapter/inbound/messaging/gradle.lockfile index cca8539f..feedb258 100644 --- a/src/adapter/inbound/messaging/gradle.lockfile +++ b/src/adapter/inbound/messaging/gradle.lockfile @@ -50,6 +50,20 @@ commons-collections:commons-collections:3.2.2=checkstyle commons-io:commons-io:2.20.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath commons-io:commons-io:2.21.0=spotbugs commons-logging:commons-logging:1.3.6=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-admin:1.0.0=integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-core-api:1.0.0=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-kafka:1.0.0=integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-observability:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-policy:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-reliability-api:1.0.0=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-reliability-jdbc-postgresql:1.0.0=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-reliability:1.0.0=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-runtime-core:1.0.0=integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-schema-json:1.0.0=integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-security:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-spring-boot-starter-kafka:1.0.0=integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-spring-boot-starter:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-transport-spi:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath info.picocli:picocli:4.7.7=checkstyle io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor diff --git a/src/adapter/inbound/messaging/src/integrationTest/java/dev/caskeleton/adapter/inbound/messaging/InboxRedeliveryIntegrationTest.java b/src/adapter/inbound/messaging/src/integrationTest/java/dev/caskeleton/adapter/inbound/messaging/InboxRedeliveryIntegrationTest.java index 527e3fe0..4f4d911b 100644 --- a/src/adapter/inbound/messaging/src/integrationTest/java/dev/caskeleton/adapter/inbound/messaging/InboxRedeliveryIntegrationTest.java +++ b/src/adapter/inbound/messaging/src/integrationTest/java/dev/caskeleton/adapter/inbound/messaging/InboxRedeliveryIntegrationTest.java @@ -3,6 +3,13 @@ package dev.caskeleton.adapter.inbound.messaging; import static org.assertj.core.api.Assertions.assertThat; import static org.awaitility.Awaitility.await; +import dev.cakit.messaging.api.MessageId; +import dev.cakit.messaging.api.MessageType; +import dev.cakit.messaging.api.delivery.HandleResult; +import dev.cakit.messaging.api.delivery.MessageDelivery; +import dev.cakit.messaging.api.delivery.MessageHandler; +import dev.cakit.messaging.api.destination.DestinationName; +import dev.cakit.messaging.api.destination.MessageDestination; import dev.caskeleton.application.capability.Idempotency; import dev.caskeleton.application.capability.RepositoryAccess; import dev.caskeleton.application.capability.UseCaseCapability; @@ -13,13 +20,6 @@ import dev.caskeleton.application.security.SystemCaller; import dev.caskeleton.application.security.SystemInvoked; import dev.caskeleton.application.transaction.TransactionMode; import dev.caskeleton.application.transaction.TransactionPort; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.delivery.HandleResult; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; import java.time.Clock; import java.time.Duration; import java.time.Instant; diff --git a/src/adapter/inbound/messaging/src/main/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfiguration.java b/src/adapter/inbound/messaging/src/main/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfiguration.java index b45d514a..52dae485 100644 --- a/src/adapter/inbound/messaging/src/main/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfiguration.java +++ b/src/adapter/inbound/messaging/src/main/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfiguration.java @@ -1,9 +1,9 @@ package dev.caskeleton.adapter.inbound.messaging; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -import dev.caskeleton.messaging.inbox.IdempotentConsumer; -import dev.caskeleton.messaging.inbox.JdbcInboxRepository; -import dev.caskeleton.messaging.reliability.InboxRepository; +import dev.cakit.messaging.api.delivery.MessageHandler; +import dev.cakit.messaging.inbox.IdempotentConsumer; +import dev.cakit.messaging.inbox.JdbcInboxRepository; +import dev.cakit.messaging.reliability.InboxRepository; import javax.sql.DataSource; import org.springframework.boot.autoconfigure.AutoConfiguration; import org.springframework.boot.autoconfigure.condition.ConditionalOnBean; @@ -43,7 +43,7 @@ import org.springframework.transaction.support.TransactionTemplate; "org.springframework.boot.hibernate.autoconfigure.HibernateJpaAutoConfiguration", "org.springframework.boot.jdbc.autoconfigure.DataSourceTransactionManagerAutoConfiguration" }, - beforeName = "dev.caskeleton.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration") + beforeName = "dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration") @ConditionalOnBean({MessageHandler.class, DataSource.class, PlatformTransactionManager.class}) public class MessagingInboxAutoConfiguration { diff --git a/src/adapter/inbound/messaging/src/test/java/dev/cakit/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java b/src/adapter/inbound/messaging/src/test/java/dev/cakit/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java new file mode 100644 index 00000000..f34ded1b --- /dev/null +++ b/src/adapter/inbound/messaging/src/test/java/dev/cakit/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java @@ -0,0 +1,31 @@ +package dev.cakit.messaging.autoconfigure; + +import dev.cakit.messaging.reliability.InboxRepository; +import org.springframework.boot.autoconfigure.AutoConfiguration; +import org.springframework.boot.autoconfigure.AutoConfigureOrder; +import org.springframework.boot.autoconfigure.condition.ConditionalOnBean; +import org.springframework.context.annotation.Bean; +import org.springframework.core.Ordered; + +/** + * Test stand-in with the exact name of the messaging library's root auto-configuration. + * + *

The library builds its inbox consumer only from an {@link InboxRepository} the application + * provides, so the application's {@code MessagingInboxAutoConfiguration} must run first ({@code + * beforeName}). This stand-in asks to run first itself ({@code HIGHEST_PRECEDENCE}) and records, as + * a bean, whether it saw the repository: it does only if the constraint put the inbox configuration + * ahead of it. The starter is not on this leaf's test classpath, so the name does not collide. + */ +@AutoConfiguration +@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE) +public class MessagingPlatformRootAutoConfiguration { + + /** Present only when the application's inbox repository existed as this root was processed. */ + public record SawTheInbox() {} + + @Bean + @ConditionalOnBean(InboxRepository.class) + SawTheInbox sawTheInbox() { + return new SawTheInbox(); + } +} diff --git a/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfigurationTest.java b/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfigurationTest.java index e5b7ed4f..2a144703 100644 --- a/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfigurationTest.java +++ b/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfigurationTest.java @@ -3,25 +3,25 @@ package dev.caskeleton.adapter.inbound.messaging; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.catchThrowable; -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.ProducerId; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.TraceContext; -import dev.caskeleton.messaging.api.delivery.DeliveryContext; -import dev.caskeleton.messaging.api.delivery.DeliveryMetadata; -import dev.caskeleton.messaging.api.delivery.HandleResult; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.inbox.IdempotentConsumer; -import dev.caskeleton.messaging.inbox.InboxMessageHandler; -import dev.caskeleton.messaging.inbox.JdbcInboxRepository; -import dev.caskeleton.messaging.reliability.InboxRepository; +import dev.cakit.messaging.api.ContentType; +import dev.cakit.messaging.api.MessageEnvelope; +import dev.cakit.messaging.api.MessageId; +import dev.cakit.messaging.api.MessageType; +import dev.cakit.messaging.api.ProducerId; +import dev.cakit.messaging.api.SchemaVersion; +import dev.cakit.messaging.api.TraceContext; +import dev.cakit.messaging.api.delivery.DeliveryContext; +import dev.cakit.messaging.api.delivery.DeliveryMetadata; +import dev.cakit.messaging.api.delivery.HandleResult; +import dev.cakit.messaging.api.delivery.MessageDelivery; +import dev.cakit.messaging.api.delivery.MessageHandler; +import dev.cakit.messaging.api.destination.DestinationName; +import dev.cakit.messaging.api.destination.MessageDestination; +import dev.cakit.messaging.api.header.MessageHeaders; +import dev.cakit.messaging.inbox.IdempotentConsumer; +import dev.cakit.messaging.inbox.InboxMessageHandler; +import dev.cakit.messaging.inbox.JdbcInboxRepository; +import dev.cakit.messaging.reliability.InboxRepository; import java.sql.SQLException; import java.time.Instant; import java.util.ArrayList; @@ -73,6 +73,26 @@ class MessagingInboxAutoConfigurationTest { }); } + @Test + @DisplayName("inbox 조립은 라이브러리 root보다 먼저 돌아 root의 bean 조건이 inbox를 본다") + void theInboxIsAssembledBeforeTheLibraryRootThatNeedsIt() { + // given: a root stand-in that asks to run first and records whether it saw the inbox. + ApplicationContextRunner assembled = + runner.withConfiguration( + AutoConfigurations.of( + dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration.class)); + + // when & then + assembled + .withBean(MessageHandler.class, () -> exampleHandler(new ArrayList<>())) + .run( + context -> + assertThat(context) + .hasSingleBean( + dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration + .SawTheInbox.class)); + } + @Test @DisplayName("소비할 handler가 없으면 inbox를 조립하지 않는다") void withoutAHandlerNothingIsAssembled() { diff --git a/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/SystemInvokedConsumePathTest.java b/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/SystemInvokedConsumePathTest.java index 040d33fd..c684e249 100644 --- a/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/SystemInvokedConsumePathTest.java +++ b/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/SystemInvokedConsumePathTest.java @@ -2,6 +2,24 @@ package dev.caskeleton.adapter.inbound.messaging; import static org.assertj.core.api.Assertions.assertThat; +import dev.cakit.messaging.api.ContentType; +import dev.cakit.messaging.api.MessageEnvelope; +import dev.cakit.messaging.api.MessageId; +import dev.cakit.messaging.api.MessageType; +import dev.cakit.messaging.api.ProducerId; +import dev.cakit.messaging.api.SchemaVersion; +import dev.cakit.messaging.api.TraceContext; +import dev.cakit.messaging.api.delivery.DeliveryContext; +import dev.cakit.messaging.api.delivery.DeliveryMetadata; +import dev.cakit.messaging.api.delivery.HandleResult; +import dev.cakit.messaging.api.delivery.MessageDelivery; +import dev.cakit.messaging.api.delivery.MessageHandler; +import dev.cakit.messaging.api.destination.DestinationName; +import dev.cakit.messaging.api.destination.MessageDestination; +import dev.cakit.messaging.api.header.MessageHeaders; +import dev.cakit.messaging.inbox.IdempotentConsumer; +import dev.cakit.messaging.inbox.InboxMessageHandler; +import dev.cakit.messaging.reliability.InboxRepository; import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException; import dev.caskeleton.application.capability.Idempotency; import dev.caskeleton.application.capability.RepositoryAccess; @@ -12,24 +30,6 @@ import dev.caskeleton.application.transaction.TransactionMode; import dev.caskeleton.application.transaction.TransactionPort; import dev.caskeleton.application.transaction.testkit.DirectTransactionPort; import dev.caskeleton.composition.runtime.authorization.PermissionEnforcementConfig; -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.ProducerId; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.TraceContext; -import dev.caskeleton.messaging.api.delivery.DeliveryContext; -import dev.caskeleton.messaging.api.delivery.DeliveryMetadata; -import dev.caskeleton.messaging.api.delivery.HandleResult; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.inbox.IdempotentConsumer; -import dev.caskeleton.messaging.inbox.InboxMessageHandler; -import dev.caskeleton.messaging.reliability.InboxRepository; import java.time.Instant; import java.util.ArrayList; import java.util.LinkedHashSet; diff --git a/src/adapter/outbound/messaging-kafka/AGENTS.md b/src/adapter/outbound/messaging-kafka/AGENTS.md index 8434332e..c32d6c51 100644 --- a/src/adapter/outbound/messaging-kafka/AGENTS.md +++ b/src/adapter/outbound/messaging-kafka/AGENTS.md @@ -3,10 +3,11 @@ - 모듈 ID `adapter-outbound-messaging-kafka`, Gradle 경로 `:adapter:outbound:messaging-kafka`. registry 정본: `src/config/architecture/modules.json`. - 책임: Kafka 발행 capability를 `runtimeOnly` 한 줄로 만든다. 운영 코드가 없다: - `adapter:outbound:messaging`(애플리케이션의 bridge)과 `messaging:messaging-spring-boot-starter-kafka`(들여온 - 플랫폼과 그 Kafka 전송)를 묶고, 모듈 기본값 `config/module-defaults/messaging.yml`을 싣는다. -- 경계: 여기 코드를 더하지 않는다. 발행 규칙은 bridge(`adapter:outbound:messaging`)에, Kafka 규칙은 들여온 - 제품(`src/platforms/messaging/AGENTS.md`)에 속한다. 여기 클래스를 두면 세 번째 자리가 생긴다. 허용 edge는 + `adapter:outbound:messaging`(애플리케이션의 bridge)과 메시징 라이브러리의 `messaging-spring-boot-starter-kafka`(Kafka + 전송, Maven `dev.cakit.messaging`, 카탈로그 `libs.messaging.spring.boot.starter.kafka`)를 묶고, 모듈 기본값 + `config/module-defaults/messaging.yml`을 싣는다. +- 경계: 여기 코드를 더하지 않는다. 발행 규칙은 bridge(`adapter:outbound:messaging`)에, Kafka 규칙은 메시징 + 라이브러리(messaging-library repo의 [messaging/AGENTS.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/messaging/AGENTS.md))에 속한다. 여기 클래스를 두면 세 번째 자리가 생긴다. 허용 edge는 registry 항목에서만 온다. - 시험: 켜기 시험(`./gradlew :adapter:outbound:messaging-kafka:test`)과 실제 Kafka lane `messagingKafkaRelayIntegrationTest`(relay → bridge → broker record 바이트, `:integrationCheck`). diff --git a/src/adapter/outbound/messaging-kafka/README.md b/src/adapter/outbound/messaging-kafka/README.md index 637372e1..0aceaaaf 100644 --- a/src/adapter/outbound/messaging-kafka/README.md +++ b/src/adapter/outbound/messaging-kafka/README.md @@ -15,7 +15,8 @@ adapter:outbound:messaging-kafka ├─ config/module-defaults/messaging.yml (설정 기본값, support 로더가 읽음) ├─ adapter:outbound:messaging OutboxMessagePublishPort, │ IntegrationEventPublishPort bridge - └─ messaging:messaging-spring-boot-starter-kafka messaging platform + Kafka transport + └─ dev.cakit.messaging:messaging-spring-boot-starter-kafka 메시징 라이브러리 + Kafka transport + (별도 repo messaging-library, 카탈로그 messagingLibrary) ``` | 포트 (application-core) | 구현 | @@ -31,7 +32,8 @@ adapter:outbound:messaging-kafka app-bootstrap은 이 파일을 모른다. - broker 주소는 `APP_MESSAGING_KAFKA_BROKERS` 하나(`app.messaging.brokers.kafka.bootstrap-servers`). `spring.kafka.bootstrap-servers`는 읽지 않는다. 논리 broker 이름은 `kafka` 하나다. Kafka 연결의 - TLS·SASL은 platform의 broker profile이 소유한다(`docs/messaging/configuration-reference.md`). + TLS·SASL은 메시징 라이브러리의 broker profile이 소유한다(그 repo의 + [configuration-reference.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/docs/messaging/configuration-reference.md)). - 발행 경로는 하나다. 옛 `KafkaSender` seam(TLS/SASL 없는 R0 producer)은 outbox를 canonical로 통일하면서 삭제했다(2026-09-28). - 발행할 event의 contract마다 destination을 선언해야 한다(`app.messaging.destinations..jar collided and an application selecting this leaf could not be @@ -45,12 +47,12 @@ dependencies { // canonical events through the platform's EncodedMessagePublisher, which the Kafka starter // provides. runtimeOnly project(':adapter:outbound:messaging') - runtimeOnly project(':messaging:messaging-spring-boot-starter-kafka') + runtimeOnly libs.messaging.spring.boot.starter.kafka // The activation test boots the whole capability and names the ports it must produce. testImplementation project(':adapter:outbound:messaging') testImplementation project(':application-core') - testImplementation project(':messaging:messaging-core-api') + testImplementation libs.messaging.core.api } // Test-only edges of the relay lane: the application relay as the composition root selects it, the diff --git a/src/adapter/outbound/messaging-kafka/gradle.lockfile b/src/adapter/outbound/messaging-kafka/gradle.lockfile index 0c37615d..1f6840c1 100644 --- a/src/adapter/outbound/messaging-kafka/gradle.lockfile +++ b/src/adapter/outbound/messaging-kafka/gradle.lockfile @@ -45,6 +45,20 @@ commons-collections:commons-collections:3.2.2=checkstyle commons-io:commons-io:2.20.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath commons-io:commons-io:2.21.0=spotbugs commons-logging:commons-logging:1.3.6=integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-admin:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-core-api:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-kafka:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-observability:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-policy:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-reliability-api:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-reliability-jdbc-postgresql:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-reliability:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-runtime-core:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-schema-json:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-security:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-spring-boot-starter-kafka:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-spring-boot-starter:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-transport-spi:1.0.0=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath info.picocli:picocli:4.7.7=checkstyle io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor diff --git a/src/adapter/outbound/messaging-kafka/src/integrationTest/java/dev/caskeleton/adapter/outbound/messaging/kafka/relay/ApplicationRelayKafkaIntegrationTest.java b/src/adapter/outbound/messaging-kafka/src/integrationTest/java/dev/caskeleton/adapter/outbound/messaging/kafka/relay/ApplicationRelayKafkaIntegrationTest.java index 2957e18d..d6ee97a3 100644 --- a/src/adapter/outbound/messaging-kafka/src/integrationTest/java/dev/caskeleton/adapter/outbound/messaging/kafka/relay/ApplicationRelayKafkaIntegrationTest.java +++ b/src/adapter/outbound/messaging-kafka/src/integrationTest/java/dev/caskeleton/adapter/outbound/messaging/kafka/relay/ApplicationRelayKafkaIntegrationTest.java @@ -3,6 +3,7 @@ package dev.caskeleton.adapter.outbound.messaging.kafka.relay; import static org.assertj.core.api.Assertions.assertThat; import static org.awaitility.Awaitility.await; +import dev.cakit.messaging.api.MessageId; import dev.caskeleton.application.messaging.event.ValidatedIntegrationEvent; import dev.caskeleton.application.outbox.OutboxAppendPort; import dev.caskeleton.application.outbox.OutboxCompletion; @@ -14,7 +15,6 @@ import dev.caskeleton.application.outbox.testkit.InMemoryOutboxStore; import dev.caskeleton.application.outbox.testkit.OutboxEvents; import dev.caskeleton.application.transaction.TransactionPort; import dev.caskeleton.application.transaction.testkit.DirectTransactionPort; -import dev.caskeleton.messaging.api.MessageId; import java.time.Clock; import java.time.Duration; import java.time.Instant; diff --git a/src/adapter/outbound/messaging-kafka/src/test/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaCapabilityActivationTest.java b/src/adapter/outbound/messaging-kafka/src/test/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaCapabilityActivationTest.java index 0f7b5ae5..27adeec1 100644 --- a/src/adapter/outbound/messaging-kafka/src/test/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaCapabilityActivationTest.java +++ b/src/adapter/outbound/messaging-kafka/src/test/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaCapabilityActivationTest.java @@ -3,10 +3,10 @@ package dev.caskeleton.adapter.outbound.messaging.kafka; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.catchThrowable; +import dev.cakit.messaging.schema.EncodedMessagePublisher; import dev.caskeleton.adapter.outbound.messaging.outbox.OutboxMessagePublishAdapter; import dev.caskeleton.application.messaging.event.IntegrationEventPublishPort; import dev.caskeleton.application.outbox.OutboxMessagePublishPort; -import dev.caskeleton.messaging.schema.EncodedMessagePublisher; import java.util.Arrays; import java.util.List; import org.junit.jupiter.api.Test; @@ -69,7 +69,7 @@ class KafkaCapabilityActivationTest { .map(Class::getName) .filter( name -> - name.startsWith("dev.caskeleton.messaging.") + name.startsWith("dev.cakit.messaging.") || name.startsWith("dev.caskeleton.adapter.outbound.messaging.") || name.startsWith("org.apache.kafka."))) .isEmpty(); diff --git a/src/adapter/outbound/messaging/build.gradle b/src/adapter/outbound/messaging/build.gradle index 6267abee..f9d6c2dc 100644 --- a/src/adapter/outbound/messaging/build.gradle +++ b/src/adapter/outbound/messaging/build.gradle @@ -7,7 +7,7 @@ dependencies { implementation project(':application-core') implementation project(':shared-contract') implementation project(':adapter:outbound:support') - implementation project(':messaging:messaging-core-api') + implementation libs.messaging.core.api implementation 'org.springframework.boot:spring-boot-autoconfigure' implementation 'org.springframework.boot:spring-boot-starter-json' diff --git a/src/adapter/outbound/messaging/gradle.lockfile b/src/adapter/outbound/messaging/gradle.lockfile index ea2f1c52..c4d9d140 100644 --- a/src/adapter/outbound/messaging/gradle.lockfile +++ b/src/adapter/outbound/messaging/gradle.lockfile @@ -37,6 +37,7 @@ commons-beanutils:commons-beanutils:1.11.0=checkstyle commons-collections:commons-collections:3.2.2=checkstyle commons-io:commons-io:2.21.0=spotbugs commons-logging:commons-logging:1.3.6=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-core-api:1.0.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath info.picocli:picocli:4.7.7=checkstyle io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor diff --git a/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingBridgeRootAutoConfiguration.java b/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingBridgeRootAutoConfiguration.java index 863fe1ad..7f7bf1d7 100644 --- a/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingBridgeRootAutoConfiguration.java +++ b/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingBridgeRootAutoConfiguration.java @@ -1,10 +1,10 @@ package dev.caskeleton.adapter.outbound.messaging.autoconfigure; +import dev.cakit.messaging.schema.EncodedMessagePublisher; import dev.caskeleton.adapter.outbound.messaging.MessagingConfig; import dev.caskeleton.adapter.outbound.messaging.MessagingSettings; import dev.caskeleton.adapter.outbound.messaging.platformbridge.PlatformIntegrationEventPublishAdapter; import dev.caskeleton.application.messaging.event.IntegrationEventPublishPort; -import dev.caskeleton.messaging.schema.EncodedMessagePublisher; import org.springframework.boot.autoconfigure.AutoConfiguration; import org.springframework.boot.autoconfigure.condition.ConditionOutcome; import org.springframework.boot.autoconfigure.condition.ConditionalOnBean; @@ -23,14 +23,15 @@ import org.springframework.util.StringUtils; * The one place that decides whether this application publishes to a broker. * *

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

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

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

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

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

The bridge orders itself after that root by name, and Boot sorts auto-configurations - * alphabetically before applying {@code after} constraints — {@code dev.caskeleton.adapter…} comes - * before {@code dev.caskeleton.messaging…}. A stand-in with the same name reproduces that ordering - * without pulling the starter, and a broker, onto this leaf's test classpath. The starter is not on - * that classpath, so the name does not collide. - */ -@AutoConfiguration -public class MessagingPlatformRootAutoConfiguration { - - @Bean - EncodedMessagePublisher encodedMessagePublisher() { - return (destination, message, options) -> { - throw new AssertionError("publisher is not invoked while wiring the bridge"); - }; - } -} diff --git a/src/adapter/outbound/persistence-jpa/AGENTS.md b/src/adapter/outbound/persistence-jpa/AGENTS.md index e8a178c9..639e458e 100644 --- a/src/adapter/outbound/persistence-jpa/AGENTS.md +++ b/src/adapter/outbound/persistence-jpa/AGENTS.md @@ -111,6 +111,7 @@ lock TTL)과 계약 표(트랜잭션 모드, SQLState → 오류 코드, vendor, - `:shared-contract` - `:adapter:outbound:support`(타입 있는 기동 실패, EnvironmentPostProcessor 순서, readiness group, module-defaults 읽기) - Spring Data JPA와 Spring transaction. +- 시험만: 메시징 라이브러리 jar(`dev.cakit.messaging:messaging-reliability-jdbc-postgresql`)를 전용 구성 `messagingMigrations`로 받아 그 `db/migration` 트리를 푼다. migration 시험(`MigrationTrees`)이 같은 Flyway 이력에 들어가는 메시징 migration을 이 leaf의 것과 같은 규칙으로 보기 위해서다. 어떤 classpath에도 올리지 않으므로 registry 방향 검사(운영 구성만 본다) 밖이다. 다른 repo의 파일을 경로로 읽지 않는다. ## 금지 (Forbidden) diff --git a/src/adapter/outbound/persistence-jpa/build.gradle b/src/adapter/outbound/persistence-jpa/build.gradle index 6ef7a85e..a79b738a 100644 --- a/src/adapter/outbound/persistence-jpa/build.gradle +++ b/src/adapter/outbound/persistence-jpa/build.gradle @@ -296,6 +296,34 @@ tasks.named('postgresqlSecurityBaselineIntegrationTest') { // Which JPA lanes block a release is declared by release/release-registry.json (jpaReleaseQualification below). // This leaf declares the lanes and how each runs; it does not own release orchestration. +// The messaging library's migration tree (db/migration/messaging in messaging-reliability-jdbc-postgresql, +// messaging-library repo) runs against the database this leaf owns once the consume side is +// selected, through the same Flyway history, so AppliedMigrationImmutabilityTest and +// MigrationLockWaitTest hold it to the same rules as this leaf's own trees (MigrationTrees). While +// the library lived in this repository they read its source folder by path; now the tree is a +// resource of the published jar, at the version the catalog names (`messagingLibrary`), which is +// exactly what a service applies. Only the jar, not its dependencies, and only to read: the module is +// on no classpath of this leaf, so no test context sees the library. +configurations { + messagingMigrations { + canBeConsumed = false + canBeResolved = true + transitive = false + description = 'The messaging library jar whose db/migration tree the migration tests read.' + } +} +dependencies { + messagingMigrations libs.messaging.reliability.jdbc.postgresql +} +def messagingMigrationDirectory = layout.buildDirectory.dir('library-migrations/messaging-reliability-jdbc-postgresql') +def messagingMigrationTree = tasks.register('messagingMigrationTree', Sync) { + description = 'Extracts the messaging library\'s db/migration tree for the migration tests.' + from({ zipTree(configurations.messagingMigrations.singleFile) }) { + include 'db/migration/**' + } + into messagingMigrationDirectory +} + // The unit lane reads three files that are not Java sources: the release registry and its two // renderings. Without declaring them, Gradle calls the lane up-to-date after a registry demotion or // a workflow edit — so the drift check that exists to catch exactly that edit never runs on it. @@ -321,9 +349,14 @@ tasks.named('test') { .withPropertyName('notificationMigrations') inputs.dir(file('../persistence-fileserver/src/main/resources/db/migration')) .withPropertyName('fileserverMigrations') - // ...and the messaging platform's tree, whose inbox range the consume side applies here. - inputs.dir(file('../../../platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration')) + // ...and the messaging library's tree, whose inbox range the consume side applies here: read out of + // the jar this build receives (messagingMigrationTree above), not from the library's sources. + dependsOn messagingMigrationTree + inputs.dir(messagingMigrationDirectory) + .withPathSensitivity(PathSensitivity.RELATIVE) .withPropertyName('messagingMigrations') + systemProperty 'persistence.migration.messagingTree', + messagingMigrationDirectory.get().dir('db/migration').asFile.absolutePath } // verifyJpaApiSurface — every public type this leaf exposes is a committed decision. diff --git a/src/adapter/outbound/persistence-jpa/gradle.lockfile b/src/adapter/outbound/persistence-jpa/gradle.lockfile index ace35092..f0c903d9 100644 --- a/src/adapter/outbound/persistence-jpa/gradle.lockfile +++ b/src/adapter/outbound/persistence-jpa/gradle.lockfile @@ -54,6 +54,7 @@ commons-collections:commons-collections:3.2.2=checkstyle commons-io:commons-io:2.20.0=jpaPlatformPerformanceTestCompileClasspath,jpaPlatformPerformanceTestRuntimeClasspath,postgresqlIntegrationTestCompileClasspath,postgresqlIntegrationTestRuntimeClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath commons-io:commons-io:2.21.0=spotbugs commons-logging:commons-logging:1.3.6=compileClasspath,jpaPlatformPerformanceTestCompileClasspath,jpaPlatformPerformanceTestRuntimeClasspath,postgresqlIntegrationTestCompileClasspath,postgresqlIntegrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-reliability-jdbc-postgresql:1.0.0=messagingMigrations eu.rekawek.toxiproxy:toxiproxy-java:2.1.11=jpaPlatformPerformanceTestRuntimeClasspath,postgresqlIntegrationTestCompileClasspath,postgresqlIntegrationTestRuntimeClasspath,testRuntimeClasspath eu.rekawek.toxiproxy:toxiproxy-java:2.1.7=testFixturesCompileClasspath,testFixturesRuntimeClasspath info.picocli:picocli:4.7.7=checkstyle diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/MigrationTrees.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/MigrationTrees.java index 018843b1..2c817a73 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/MigrationTrees.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/MigrationTrees.java @@ -28,22 +28,37 @@ final class MigrationTrees { * adapter:outbound:persistence-fileserver}) runs against the same database through the same * Flyway history and was never pinned at all; it is checked here on the same terms. * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{@code gradle/libs.versions.toml} declares {@code archunit-junit5 = { module = "..." }} and - * Gradle exposes it as {@code libs.archunit.junit5}; the alias separators become dots. Parsing - * the file rather than hard-coding the mapping keeps this test honest when an alias is renamed — - * a stale table here would silently stop resolving and report the library as unexported. - */ - private static Map catalogModules() { - Map modules = new LinkedHashMap<>(); - Path catalog = repositoryRoot().resolve("src/gradle/libs.versions.toml"); - if (!Files.isRegularFile(catalog)) { - return modules; - } - Matcher entry = - Pattern.compile("(?m)^([A-Za-z0-9_-]+)\\s*=\\s*\\{[^}]*module\\s*=\\s*\"([^\"]+)\"") - .matcher(read(catalog)); - while (entry.find()) { - modules.put("libs." + entry.group(1).replace('-', '.').replace('_', '.'), entry.group(2)); - } - return modules; - } - - private static java.util.function.Predicate isNamed(String leaf) { - return path -> path.getFileName().toString().equals(leaf); - } - - private static List messagingLeaves() { - Path family = repositoryRoot().resolve("src/platforms/messaging"); - try (Stream children = Files.list(family)) { - return children - .filter(Files::isDirectory) - .filter(path -> Files.isRegularFile(path.resolve("build.gradle"))) - .sorted() - .toList(); - } catch (IOException unreadable) { - throw new UncheckedIOException(unreadable); - } - } - - private static List productionSources(Path leaf) { - Path main = leaf.resolve("src/main/java"); - if (!Files.isDirectory(main)) { - return List.of(); - } - try (Stream walk = Files.walk(main)) { - return walk.filter(path -> path.toString().endsWith(".java")).sorted().toList(); - } catch (IOException unreadable) { - throw new UncheckedIOException(unreadable); - } - } - - private static String read(Path path) { - try { - return Files.readString(path); - } catch (IOException unreadable) { - throw new UncheckedIOException(unreadable); - } - } - - private static Path repositoryRoot() { - // Gradle hands the root only to the lanes that declare the repository files as inputs; the - // plain `test` lane gets none, so a test that reads the repository without a lane tag fails - // here instead of going stale behind an up-to-date check (review 2026-11-01 08-03). - return RepositoryContractResources.fromSystemProperty().repositoryRoot(); - } -} diff --git a/src/build-logic/AGENTS.md b/src/build-logic/AGENTS.md index d5f1fa86..b265e0ed 100644 --- a/src/build-logic/AGENTS.md +++ b/src/build-logic/AGENTS.md @@ -4,7 +4,7 @@ registry, settings, build-logic, 루트 라이프사이클이 정하는 것을 ## 정본 넷 -- `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge. runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 정본은 registry다. 문서는 개수를 적지 않는다. 산문에 적힌 숫자는 leaf가 더해지는 순간 틀린다. 그 숫자를 강제하던 태스크(`verifyDocumentedLeafCount`)는 지웠다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든 지역 문서와 `build.gradle`을 정규식으로 훑는 파서였다. +- `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge, 그리고 별도 repo 라이브러리 edge(맨 위 `library_groups`, 행마다 `allowed_libraries`. 계층 leaf 행은 비워 둔다. 설명은 `src/config/architecture/README.md`). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 정본은 registry다. 문서는 개수를 적지 않는다. 산문에 적힌 숫자는 leaf가 더해지는 순간 틀린다. 그 숫자를 강제하던 태스크(`verifyDocumentedLeafCount`)는 지웠다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든 지역 문서와 `build.gradle`을 정규식으로 훑는 파서였다. - `src/settings.gradle`: `ca.architecture-registry` 설정 플러그인이 registry를 읽어 project를 include·mapping한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은 `verifyCleanArchitectureDependencies`가 답한다. settings에서 죽으면 실행할 수 있는 태스크가 하나도 없다. - `src/build-logic/`: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나(`strictTestLanes`). leaf는 `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다. `ca.architecture`가 아키텍처 검증 태스크를 가진다. 기능별 검사(notification·mongo·messaging·graphql·JPA readiness 등)는 build-logic이 아니라 그 leaf의 테스트다. - `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전·리비전. diff --git a/src/build-logic/README.md b/src/build-logic/README.md index 71cf803e..a409959e 100644 --- a/src/build-logic/README.md +++ b/src/build-logic/README.md @@ -13,7 +13,7 @@ capability를 가진 leaf의 시험이고, 그 시험이 읽는 파일은 그 | `ca.java-conventions` | Java toolchain·컴파일러 기준, 의존성 잠금, Mockito 시험 agent, leaf별 `mainCheck` lifecycle, leaf 버전(릴리스 버전만)과 `sourceRevision`(`JavaConventionsPlugin.sourceRevision`. 루트 `verifyReleaseProvenance`가 검사하는 것도 이것이다) | | `ca.quality-conventions` | Java leaf가 같이 쓰는 Spotless, Checkstyle, Error Prone, SpotBugs·FindSecBugs 배선 | | `ca.java-library` / `ca.spring-library` / `ca.spring-config` | 평범한 라이브러리와 Spring 라이브러리를 위한 Java·품질 규약의 leaf 단위 조합 | -| `ca.platform-module` | 들여온 플랫폼 leaf(`messaging:*`)가 무엇인가: `java-library`. gRPC 플랫폼과 그 BOM 규약(`ca.grpc-platform-module`)은 2026-11-08에 별도 repo `grpc-library`로 옮겼다 | +| `ca.platform-module` | 플랫폼 성격의 Java 라이브러리 leaf(지금 `adapter:outbound:httpclient`)가 무엇인가: `java-library`. 이 규약을 쓰던 메시징·gRPC 플랫폼은 2026-11-08에 별도 repo `messaging-library`·`grpc-library`로 옮겼다(gRPC BOM 규약 `ca.grpc-platform-module`도 함께) | | `ca.strict-test-lane` | 「이름 댄 시험이 돌았고 건너뛴 것이 없다」를 보는 유일한 장치: tag·이름·자기 source set으로 고른 `Test` lane이 아무것도 실행하지 않거나, `requires` 클래스를 빠뜨리거나, (`rejectSkipped`이면) 무엇이든 건너뛰면 실패한다. `performance()` lane은 언제나 건너뛰기를 거절하고 `performance.assertions.enabled=true`로 돈다. 빌드(`-P`, `GRADLE_OPTS`)나 lane이 다른 값을 넣으면 시험이 돌기 전에 실패한다. `mainStage()`는 tag로 고른 lane을 `test`에서 빼 leaf의 `mainCheck`로 옮긴다. `explicitOnly(reason)`는 바깥 입력이 필요한 lane을 모든 묶음 태스크에서 빼고, 묶음 태스크가 그 이유를 출력한다. 시험 source set을 더 두려면 leaf에 Gradle `jvm-test-suite` suite로 선언한다(`testing { suites { … } }`). suite 이름을 딴 lane은 그 suite 자신의 `Test` 태스크를 엄격하게 만들고, `ca.java-conventions`는 모든 suite에 BOM의 JUnit을 준다 | | `ca.strict-lane-stages` (주 빌드의 루트) | lane 장치의 나머지 절반: `verifyStrictLaneStages --dry-run`은 그 빌드의 `explicitOnly`가 아닌 strict lane이 workflow가 실행하는 선언된 단계 어느 것의 태스크 계획에도 없거나, 선언된 단계를 실행하는 workflow가 없으면 실패한다. workflow는 함께 읽고(`WorkflowGradleInvocations.readAll`. 그래서 재사용 workflow는 그것을 부르는 쪽으로 판정한다) `run:` 스크립트는 bash로 파싱한다(`ShellScript`: 따옴표, 주석, heredoc 본문, 치환, 복합 명령을 셸이 읽듯 읽는다. 그래서 heredoc이나 문자열 안의 `cd`는 데이터다). Gradle이 태스크를 하나도 돌리지 않는 명령은 세지 않는다 — `--dry-run`/`-m`(`-qm` 같은 묶음 안도), `-v`/`--version`, `-h`/`-?`/`--help`, `--status`, `--stop`, `--foreground`(`-qv` 같은 묶음 안도) — Gradle이 거절하는 명령도 세지 않는다: 뒤 글자가 값을 받는 짧은 옵션 묶음(`-mx`: 묶음에서는 첫 글자만 값을 받는다), 값을 받지 않는 옵션에 준 값(`-m=yes`). 읽는 방식은 Gradle 9.0의 파서를 따른다. `GradleCommandLineTest`는 옵션 표를 build-logic을 돌리는 Gradle의 `--help`와 맞춘다 — 옵션을 더하는 업그레이드는(9.2가 `--task-graph`를 더하듯) 그 옵션을 자리에 넣기 전까지 실패한다 — 그리고 `--stop`과 `--foreground`를 뺀 태스크 없는 옵션마다 launcher를 돌린다(둘은 Gradle `BuildActionsFactory`에서 빌드가 아니라 daemon 동작을 돌려준다). 어떤 옵션이 값을 받는지는 round 9에 9.0.0으로 탐침했고 다시 돌리지 않는다. 다른 빌드를 위한 명령도 세지 않는다(명령이 시작하는 빌드는 그 step의 `working-directory`, 또는 job이나 workflow의 `defaults.run.working-directory`에서 시작해, 같은 `run:` 셸이 그 앞에서 반드시 돌린 `cd <리터럴 상대 경로>`마다 옮기고 — 혼자 있는 목록이거나 같은 `&&` 목록에서 그 명령 앞에 있을 때 — 그다음 `-p`로 이은 곳이다. 플러그인은 이 빌드 자신의 디렉터리를 `.github/workflows`를 가진 저장소 아래 어디에 있는지로 읽는다). 세지 않는 그 밖의 명령은 모두 세 이유 중 하나를 댄다. **실패해도 step이 실패하지 않을 수 있다**: `\|\| true`, `\|\| :`, `\|\| exit <0 아닌 값>`이 아닌 모든 `\|\|`, `pipefail` 없는 pipe의 왼쪽(`shell: bash`나 최상위 `set -o pipefail`이면 켜진다), `!`, `&`, `if`/`while` 조건, 스크립트의 마지막 명령이 아닌 목록에서 `&&` 앞부분, `set +e` 뒤, `EXIT`나 `ERR` 동작이 상태 0으로 `exit`할 수 있는 `trap` 뒤(`EXIT` trap 안의 맨 `exit`는 상태를 지키지만 `ERR` trap 안에서는 아니다), `continue-on-error`. **돌지 않을 수 있다**: `\|\|` 뒤, 스크립트의 마지막 명령이 아닌 목록에서 `&&` 뒤, `if`/`while`/`for`/`case` 안이나 함수 본문 안, 최상위 `exit`·`exec `·`set -n` 뒤, 다른 곳 — 복합 명령, and-or 목록, 스크립트가 부르는 함수 — 에서 스크립트를 상태 0으로 끝낼 수 있는 것(`exit 0`, `\|\|` 바로 뒤가 아닌 맨 `exit`, `exit "$code"`), 스크립트를 바꿔치는 것, 명령 실행을 멈추는 것(`set -o noexec`) 뒤, `always()`/`success()`/`!cancelled()`가 아닌 `if:` 아래, 누가 또는 무엇이 요청해야만 시작하는 이벤트(`workflow_dispatch`, `repository_dispatch`, `issue_comment`, `types: [labeled]`인 pull request, `workflow_run`, …. `push`, `pull_request`, `pull_request_target`, `merge_group`, `schedule`, `release`는 센다)로만 시작하는 workflow 안, 변경 흐름 트리거가 모두 `paths`나 `paths-ignore` 필터를 가진 workflow 안(그 경로 밖의 변경은 workflow를 시작하지 않는다. 소유자 결정 2026-11-06), 요청이나 경로 필터 없이 릴리스 흐름에서만 시작하는 workflow 안의 `:releaseCheck`가 아닌 단계 — 릴리스 흐름은 `release`, 또는 `tags`/`tags-ignore`가 있고 `branches`/`branches-ignore`가 없는 `push`로, 브랜치 push로는 시작하지 않는다(소유자 결정 2026-11-07. `:releaseCheck`가 태그 전용 단계다) — 센 job 어느 것도 `uses: ./.github/workflows/`로 부르지 않는 재사용(`workflow_call`만 있는) workflow 안, 그리고 그런 `if:`나 `continue-on-error`를 가진 job을 직접 또는 다른 job을 거쳐 `needs`하는 job 안(자기 `if:`가 `always()`나 `!cancelled()`이면 예외). **이 검사가 읽지 않는다**(실패하면 step이 실패하지만, 일부러 거짓 실패로 둔다): `\|\| exit 1`, `\|\| { …; exit 1; }`, `{ }`나 `( )` 안, `$( )`, `bash -c`, 다른 명령의 인자인 `gradlew`(`timeout 60 ./gradlew`), 읽는 쪽이 따라가지 않는 디렉터리 이동 뒤(`cd "$VAR"`, `cd -`, `cd ~`, 절대 경로, `pushd`/`popd`, `builtin cd`, `eval`/`source`, 복합 명령이나 함수 본문 안의 `cd`, `\|\|`로 이은 것, pipe나 background로 돌린 것, 다른 명령과 같은 `&&` 목록에 있는 `cd`의 뒤 줄 — 짐작하지 않는다), `shell:`이 `bash`나 `sh`가 아닌 step, `runs-on`이 Windows runner일 수 있는 job에서 `shell:`이 없는 step(기본 셸이 `pwsh`다. Windows label, `${{ matrix.os }}` 같은 표현식, `linux`나 `macos`가 없는 self-hosted label 집합. Linux·macOS runner의 기본은 `bash -e`, `container:` job의 기본은 `sh -e`이고 둘을 같이 읽는다). step을 실패시키는 `exit` — `exit 1`, `cmd \|\| exit` — 와 부르지 않는 함수, `( )` subshell, `$( )` 안의 `exit`는 그 뒤의 명령이 세지는 것을 막지 않는다. 실패 메시지는 단계 이름을 대지만 그 단계를 실행하지 않는 모든 명령을 그 이유나 그것이 시작하는 다른 빌드와 함께 대고, 단계를 혼자 있는 줄의 `./gradlew`로 돌리라고 말한다. 명령이 `-x`로 뺀 lane은 덮인 것이 아니다 — Gradle이 태스크·프로젝트 이름을 맞추는 방식(약어 포함)으로 맞춘다(`TaskSelectors`, Gradle 내부 `NameMatcher`의 사본). `uses:` step의 `run:` 입력은 명령이 아니다. 계획은 Gradle 자신의 것이다. workflow는 YAML folding을 적용해 `run:` step을 읽는다(review 2026-11-01 08-01, 2026-11-03 RR-06-03/04, 2026-11-04 RR2-04-04, `cd`에 대한 소유자 결정 2026-11-04, round 9의 RR5-02-01/02/03, 2026-11-05 RR6-04-01..06, 2026-11-06 RR7-05-01, 릴리스 흐름에 대한 소유자 결정 2026-11-07) | | `ca.redis-topology-lane` | redis-sdk-topology workflow가 돌리는 Redis topology lane(모드 고르기, `-P` 속성 검증, 모드별 필수 클래스) | diff --git a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistry.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistry.java index 47d2ebb1..f9c6394a 100644 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistry.java +++ b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistry.java @@ -16,29 +16,50 @@ import java.util.List; import java.util.Objects; import java.util.Set; import java.util.TreeSet; +import java.util.regex.Pattern; import tools.jackson.databind.JsonNode; import tools.jackson.databind.ObjectMapper; import tools.jackson.databind.json.JsonMapper; -/** Typed representation of config/architecture/modules.json. */ -public record ModuleRegistry(List modules, File source) { +/** + * Typed representation of config/architecture/modules.json. + * + *

{@code libraryGroups} are the Maven group prefixes of the libraries this repository's owner + * publishes from other repositories (design-docs {@code repo-structure/05-library-repos.md} 10.2절, + * T2). Such a library is not a project, so the project-edge rules cannot see it; a module may depend + * on one only when its row lists the coordinate in {@code allowed_libraries}. Libraries of any other + * group are not governed by the registry. + */ +public record ModuleRegistry(List modules, List libraryGroups, File source) { private static final ObjectMapper JSON = JsonMapper.builder().build(); private static final Set REQUIRED_MODULE_FIELDS = Set.of("id", "gradle_path", "source_path", "allowed_dependencies"); private static final Set REQUIRED_ROOT_FIELDS = Set.of("modules"); + private static final Pattern GROUP = Pattern.compile("[A-Za-z0-9_-]+(\\.[A-Za-z0-9_-]+)*"); + private static final Pattern COORDINATE = + Pattern.compile("([A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*):([A-Za-z0-9_.-]+)"); public ModuleRegistry { modules = List.copyOf(modules); + libraryGroups = List.copyOf(libraryGroups); Objects.requireNonNull(source, "source"); } + /** Whether {@code group} is one of {@code libraryGroups} or below one of them. */ + public static boolean isOwnedGroup(List libraryGroups, String group) { + return group != null + && libraryGroups.stream() + .anyMatch(prefix -> group.equals(prefix) || group.startsWith(prefix + ".")); + } + public record Module( String id, String gradlePath, String sourcePath, File sourceDirectory, String buildName, - List allowedDependencies) { + List allowedDependencies, + List allowedLibraries) { public Module { Objects.requireNonNull(id, "id"); Objects.requireNonNull(gradlePath, "gradlePath"); @@ -46,6 +67,7 @@ public record ModuleRegistry(List modules, File source) { Objects.requireNonNull(sourceDirectory, "sourceDirectory"); Objects.requireNonNull(buildName, "buildName"); allowedDependencies = List.copyOf(allowedDependencies); + allowedLibraries = List.copyOf(allowedLibraries); } } @@ -70,6 +92,17 @@ public record ModuleRegistry(List modules, File source) { "Module registry root is missing " + missingRootFields + ": " + registryFile); } + List libraryGroups = List.of(); + if (root.has("library_groups")) { + libraryGroups = requireStringList(root.get("library_groups"), "library_groups"); + for (String group : libraryGroups) { + if (!GROUP.matcher(group).matches()) { + throw new IllegalStateException( + "Module registry 'library_groups' entry '" + group + "' is not a Maven group."); + } + } + } + JsonNode modulesNode = root.get("modules"); if (modulesNode == null || !modulesNode.isArray() || modulesNode.isEmpty()) { throw new IllegalStateException("Module registry has no modules: " + registryFile); @@ -126,6 +159,35 @@ public record ModuleRegistry(List modules, File source) { throw new IllegalStateException( "Module registry entry '" + id + "' contains duplicate allowed dependencies."); } + List allowedLibraries = + module.has("allowed_libraries") + ? requireStringList(module.get("allowed_libraries"), id, "allowed_libraries") + : List.of(); + for (String library : allowedLibraries) { + var coordinate = COORDINATE.matcher(library); + if (!coordinate.matches()) { + throw new IllegalStateException( + "Module registry entry '" + + id + + "' allows library '" + + library + + "', which is not a group:artifact coordinate."); + } + if (!isOwnedGroup(libraryGroups, coordinate.group(1))) { + throw new IllegalStateException( + "Module registry entry '" + + id + + "' allows library '" + + library + + "' outside the registry's library_groups " + + libraryGroups + + "; only an owned library is listed, any other dependency is not governed here."); + } + } + if (new HashSet<>(allowedLibraries).size() != allowedLibraries.size()) { + throw new IllegalStateException( + "Module registry entry '" + id + "' contains duplicate allowed libraries."); + } if (!ids.add(id)) { throw new IllegalStateException( "Module registry contains duplicate module id '" + id + "'."); @@ -186,10 +248,11 @@ public record ModuleRegistry(List modules, File source) { sourcePath, sourceDirectory, buildName, - allowedDependencies)); + allowedDependencies, + allowedLibraries)); } - return new ModuleRegistry(modules, registryFile); + return new ModuleRegistry(modules, libraryGroups, registryFile); } public Module byId(String id) { @@ -283,6 +346,22 @@ public record ModuleRegistry(List modules, File source) { return value.asText(); } + private static List requireStringList(JsonNode raw, String field) { + if (raw == null || !raw.isArray()) { + throw new IllegalStateException("Module registry '" + field + "' must be a list."); + } + List result = new ArrayList<>(); + for (int index = 0; index < raw.size(); index++) { + JsonNode value = raw.get(index); + if (value == null || !value.isString() || value.asText().isBlank()) { + throw new IllegalStateException( + "Module registry '" + field + "' has a non-string or blank entry at index " + index + "."); + } + result.add(value.asText()); + } + return List.copyOf(result); + } + private static List requireStringList(JsonNode raw, String id, String field) { if (raw == null || !raw.isArray()) { throw new IllegalStateException( diff --git a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java index bb5c9d5e..db5b15a8 100644 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java +++ b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java @@ -13,6 +13,7 @@ import java.util.TreeSet; import org.gradle.api.Plugin; import org.gradle.api.Project; import org.gradle.api.artifacts.Configuration; +import org.gradle.api.artifacts.ExternalModuleDependency; import org.gradle.api.artifacts.ProjectDependency; import org.gradle.api.artifacts.result.ResolvedComponentResult; import org.gradle.api.provider.Provider; @@ -101,6 +102,8 @@ public final class ArchitecturePlugin implements Plugin { } } Set declaredEdges = declaredProjectEdges(owner); + Set declaredLibraries = + declaredLibraryEdges(owner, registry.libraryGroups()); Provider compileClasspathRoot = owner .getConfigurations() @@ -122,6 +125,9 @@ public final class ArchitecturePlugin implements Plugin { task.getModuleName().set(moduleName); task.getAllowedDependencies().set(allowed); task.getDeclaredProjectEdges().set(declaredEdges); + task.getLibraryGroups().set(registry.libraryGroups()); + task.getAllowedLibraries().set(module.allowedLibraries()); + task.getDeclaredLibraryEdges().set(declaredLibraries); task.getCompileClasspathRoot().set(compileClasspathRoot); }); moduleTaskPaths.add(module.gradlePath() + ":verifyModuleDependencyDirection"); @@ -247,6 +253,34 @@ public final class ArchitecturePlugin implements Plugin { return edges; } + /** + * This module's declared dependencies on an owned library ({@code group:artifact}, the group under + * one of the registry's {@code library_groups}), read the same way and from the same production + * configurations as the project edges, {@code runtimeOnly} included. + */ + private static Set declaredLibraryEdges(Project owner, List libraryGroups) { + Set edges = new TreeSet<>(); + if (libraryGroups.isEmpty()) { + return edges; + } + for (String name : PRODUCTION_DECLARATIONS) { + Configuration configuration = owner.getConfigurations().findByName(name); + if (configuration == null) { + continue; + } + configuration + .getDependencies() + .withType(ExternalModuleDependency.class) + .forEach( + dependency -> { + if (ModuleRegistry.isOwnedGroup(libraryGroups, dependency.getGroup())) { + edges.add(dependency.getGroup() + ":" + dependency.getName()); + } + }); + } + return edges; + } + /** * One production configuration's declarations, tagged by kind. * @@ -276,6 +310,16 @@ public final class ArchitecturePlugin implements Plugin { ModuleRegistry registry, List modules) { List violations = new ArrayList<>(); for (ModuleRegistry.Module module : modules) { + // The layers stay free of the owner's libraries by the registry itself, not only because the + // purity check happens to refuse every non-project declaration in them. + if (isPure(module.id()) && !module.allowedLibraries().isEmpty()) { + violations.add( + "'" + + module.id() + + "' is a layer module (domain-core, shared-contract, application-*) and may allow no" + + " library, but allows " + + module.allowedLibraries()); + } for (String dependencyId : module.allowedDependencies()) { if (dependencyId.equals(module.id())) { violations.add("'" + module.id() + "' declares itself as an allowed dependency"); diff --git a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyModuleDependencyDirectionTask.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyModuleDependencyDirectionTask.java index f22bbf98..ba3ee324 100644 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyModuleDependencyDirectionTask.java +++ b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyModuleDependencyDirectionTask.java @@ -1,13 +1,18 @@ package dev.caskeleton.buildlogic.architecture; +import dev.caskeleton.buildlogic.ModuleRegistry; import dev.caskeleton.buildlogic.ResolvedComponents; import java.util.HashSet; +import java.util.List; import java.util.Set; import java.util.TreeSet; import org.gradle.api.DefaultTask; import org.gradle.api.GradleException; +import org.gradle.api.artifacts.ModuleVersionIdentifier; +import org.gradle.api.artifacts.component.ModuleComponentIdentifier; import org.gradle.api.artifacts.component.ProjectComponentIdentifier; import org.gradle.api.artifacts.result.ResolvedComponentResult; +import org.gradle.api.provider.ListProperty; import org.gradle.api.provider.Property; import org.gradle.api.provider.SetProperty; import org.gradle.api.tasks.Input; @@ -31,6 +36,13 @@ import org.gradle.work.DisableCachingByDefault; * configuring. Holding the configurations themselves is what made this task unstorable in the * configuration cache. * + *

Libraries this repository's owner publishes from other repositories (the registry's {@code + * library_groups}) are held to the same rule as projects: a declared or compile-visible module of + * such a group must be listed in the row's {@code allowed_libraries}. Since the messaging library + * left this repository (2026-11-08) its modules are external coordinates, which the project-edge + * check cannot see; this is what still keeps the bridge on {@code messaging-core-api} alone and the + * layers free of the library. + * *

The root task keeps what is genuinely repository-wide — the registry's own consistency, and * whether the set of governed modules matches the set of declared ones — and depends on every one of * these. @@ -50,6 +62,18 @@ public abstract class VerifyModuleDependencyDirectionTask extends DefaultTask { @Input public abstract SetProperty getDeclaredProjectEdges(); + /** The registry's {@code library_groups}: the group prefixes whose libraries are governed. */ + @Input + public abstract ListProperty getLibraryGroups(); + + /** The {@code group:artifact} coordinates this module's registry entry permits. */ + @Input + public abstract SetProperty getAllowedLibraries(); + + /** Owned-library coordinates this module declares in {@code api/implementation/compileOnly/runtimeOnly}. */ + @Input + public abstract SetProperty getDeclaredLibraryEdges(); + /** Root of this module's resolved {@code compileClasspath}. */ @Internal public abstract Property getCompileClasspathRoot(); @@ -59,16 +83,37 @@ public abstract class VerifyModuleDependencyDirectionTask extends DefaultTask { String moduleName = getModuleName().get(); Set allowed = getAllowedDependencies().get(); + List libraryGroups = getLibraryGroups().get(); + // The build this module belongs to, read from the root of its own resolution rather than + // assumed to be ":" — this build may itself run as an included build of another one. + String ownBuild = + getCompileClasspathRoot().get().getId() instanceof ProjectComponentIdentifier own + ? own.getBuild().getBuildPath() + : ":"; Set actual = new HashSet<>(getDeclaredProjectEdges().get()); + Set libraries = new TreeSet<>(getDeclaredLibraryEdges().get()); // Declared edges are not the whole story: an `api(project(...))` two leaves away is visible to - // this module's compiler and is therefore a real edge, whatever this build file says. + // this module's compiler and is therefore a real edge, whatever this build file says. The same + // holds for a library module another library module exports. for (ResolvedComponentResult component : ResolvedComponents.reachableFrom(getCompileClasspathRoot().get())) { - if (component.getId() instanceof ProjectComponentIdentifier project) { + if (component.getId() instanceof ProjectComponentIdentifier project + && !project.getBuild().getBuildPath().equals(ownBuild)) { + // A project of an included build (`--include-build ../../messaging-library`) stands in for + // the coordinate it substitutes, so it is held to allowed_libraries like that coordinate, + // not mistaken for a project edge of this build. + ModuleVersionIdentifier substituted = component.getModuleVersion(); + if (substituted != null && ModuleRegistry.isOwnedGroup(libraryGroups, substituted.getGroup())) { + libraries.add(substituted.getGroup() + ":" + substituted.getName()); + } + } else if (component.getId() instanceof ProjectComponentIdentifier project) { String projectPath = project.getProjectPath().replaceFirst("^:", ""); if (!projectPath.equals(moduleName)) { actual.add(projectPath); } + } else if (component.getId() instanceof ModuleComponentIdentifier library + && ModuleRegistry.isOwnedGroup(libraryGroups, library.getGroup())) { + libraries.add(library.getGroup() + ":" + library.getModule()); } } @@ -85,5 +130,20 @@ public abstract class VerifyModuleDependencyDirectionTask extends DefaultTask { + ".\nDirect and compile-visible production project edges must be explicitly" + " registered."); } + + Set forbiddenLibraries = new TreeSet<>(libraries); + forbiddenLibraries.removeAll(getAllowedLibraries().get()); + if (!forbiddenLibraries.isEmpty()) { + throw new GradleException( + "Module ':" + + moduleName + + "' has forbidden library dependencies " + + forbiddenLibraries + + ". Allowed libraries are " + + new TreeSet<>(getAllowedLibraries().get()) + + ".\nDirect and compile-visible production dependencies on a library of the groups " + + libraryGroups + + " must be listed in the module's allowed_libraries (config/architecture/modules.json)."); + } } } diff --git a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/ModuleRegistryTest.java b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/ModuleRegistryTest.java index 861152da..d80ccbb3 100644 --- a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/ModuleRegistryTest.java +++ b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/ModuleRegistryTest.java @@ -123,6 +123,71 @@ class ModuleRegistryTest { assertTrue(failure.getMessage().contains("'build' field"), failure.getMessage()); } + @Test + void allowedLibrariesAreReadAsCoordinatesOfAnOwnedGroup() { + // given + String json = + registry( + List.of("dev.cakit"), + entryWithLibraries( + "app-bootstrap", + ":app-bootstrap", + "src/alpha", + "[\"dev.cakit.messaging:messaging-core-api\"]"), + entry("example-app", ":example-app", "src/beta")); + + // when + ModuleRegistry parsed = read(json); + + // then + assertEquals(List.of("dev.cakit"), parsed.libraryGroups()); + assertEquals( + List.of("dev.cakit.messaging:messaging-core-api"), + parsed.byId("app-bootstrap").allowedLibraries()); + assertEquals(List.of(), parsed.byId("example-app").allowedLibraries()); + } + + @Test + @DisplayName("allowed_libraries의 좌표가 library_groups 밖 group이면 registry를 읽을 때 거절한다") + void anAllowedLibraryOutsideTheLibraryGroupsIsRefused() { + // given + String json = + registry( + List.of("dev.cakit"), + entryWithLibraries( + "app-bootstrap", ":app-bootstrap", "src/alpha", "[\"org.example:other\"]")); + + // when + IllegalStateException failure = assertThrows(IllegalStateException.class, () -> read(json)); + + // then + assertTrue(failure.getMessage().contains("'app-bootstrap'"), failure.getMessage()); + assertTrue(failure.getMessage().contains("library_groups"), failure.getMessage()); + } + + @Test + @DisplayName("allowed_libraries의 값은 group:artifact 꼴이어야 한다") + void anAllowedLibraryThatIsNotAGroupAndArtifactIsRefused() { + // given + String json = + registry( + List.of("dev.cakit"), + entryWithLibraries( + "app-bootstrap", ":app-bootstrap", "src/alpha", "[\"dev.cakit.messaging\"]")); + + // when + IllegalStateException failure = assertThrows(IllegalStateException.class, () -> read(json)); + + // then + assertTrue(failure.getMessage().contains("group:artifact"), failure.getMessage()); + } + + @Test + void aRegistryWithoutLibraryGroupsGovernsNoLibrary() { + ModuleRegistry parsed = read(valid()); + assertEquals(List.of(), parsed.libraryGroups()); + } + @Test @DisplayName("registry에 없는 디렉터리의 build 스크립트는 찾아내고, 등록된 leaf·루트·다른 빌드·build 산출물은 무시한다") void buildScriptsOutsideTheRegistryAreReported() throws Exception { @@ -188,4 +253,15 @@ class ModuleRegistryTest { private static String registry(String... entries) { return "{\"modules\":[" + String.join(",", entries) + "]}"; } + + private static String registry(List libraryGroups, String... entries) { + String groups = + libraryGroups.stream().map(group -> "\"" + group + "\"").reduce((a, b) -> a + "," + b).orElse(""); + return "{\"library_groups\":[" + groups + "],\"modules\":[" + String.join(",", entries) + "]}"; + } + + private static String entryWithLibraries(String id, String path, String source, String libraries) { + String plain = entry(id, path, source); + return plain.substring(0, plain.length() - 1) + ",\"allowed_libraries\":" + libraries + "}"; + } } diff --git a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/CleanArchitectureResolvedClasspathFunctionalTest.java b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/CleanArchitectureResolvedClasspathFunctionalTest.java index 2543a1ac..b3d52f95 100644 --- a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/CleanArchitectureResolvedClasspathFunctionalTest.java +++ b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/CleanArchitectureResolvedClasspathFunctionalTest.java @@ -107,6 +107,276 @@ class CleanArchitectureResolvedClasspathFunctionalTest { assertThat(result.getOutput()).contains("d/build.gradle").contains("no registry entry"); } + @Test + @DisplayName("소유 group 라이브러리를 runtimeOnly로만 실어도 allowed_libraries에 없으면 방향 게이트가 실패한다") + void aRuntimeOnlyOwnedLibraryMissingFromAllowedLibrariesFailsTheGate( + @TempDir Path temporaryRoot) throws IOException { + // given + Path project = libraryFixture(temporaryRoot, "runtimeOnly 'dev.cakit.demo:demo-starter:1.0.0'", "[]"); + + // when + BuildResult result = runner(project, "verifyCleanArchitectureDependencies").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("Module ':c' has forbidden library dependencies [dev.cakit.demo:demo-starter]") + .contains("allowed_libraries"); + } + + @Test + @DisplayName("소유 group 라이브러리가 api로 내보내 컴파일에 보이는 모듈도 allowed_libraries에 있어야 한다") + void aCompileVisibleOwnedLibraryMustBeListedToo(@TempDir Path temporaryRoot) + throws IOException { + // given: demo-api's POM brings demo-core in compile scope, so c compiles against both. + Path project = + libraryFixture( + temporaryRoot, + "implementation 'dev.cakit.demo:demo-api:1.0.0'", + "[\"dev.cakit.demo:demo-api\"]"); + + // when + BuildResult result = runner(project, "verifyCleanArchitectureDependencies").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("Module ':c' has forbidden library dependencies [dev.cakit.demo:demo-core]"); + } + + @Test + void ownedLibrariesListedInAllowedLibrariesPass(@TempDir Path temporaryRoot) + throws IOException { + // given + Path project = + libraryFixture( + temporaryRoot, + "implementation 'dev.cakit.demo:demo-api:1.0.0'\n" + + " runtimeOnly 'dev.cakit.demo:demo-starter:1.0.0'", + "[\"dev.cakit.demo:demo-api\", \"dev.cakit.demo:demo-core\"," + + " \"dev.cakit.demo:demo-starter\"]"); + + // when + BuildResult result = runner(project, "verifyCleanArchitectureDependencies").build(); + + // then + assertThat(result.getOutput()).contains("BUILD SUCCESSFUL"); + } + + @Test + void aLibraryOutsideTheOwnedGroupsIsNotGoverned(@TempDir Path temporaryRoot) + throws IOException { + // given + Path project = libraryFixture(temporaryRoot, "implementation 'org.example:other:1.0.0'", "[]"); + + // when + BuildResult result = runner(project, "verifyCleanArchitectureDependencies").build(); + + // then + assertThat(result.getOutput()).contains("BUILD SUCCESSFUL"); + } + + @Test + @DisplayName("--include-build로 끼운 라이브러리 모듈은 프로젝트가 아니라 그 좌표로 allowed_libraries와 대조한다") + void aLibrarySubstitutedFromAnIncludedBuildIsCheckedByItsCoordinate(@TempDir Path temporaryRoot) + throws IOException { + // given: the library's own build next to the repository; demo-included exports demo-extra. + Path project = + libraryFixture( + temporaryRoot, + "implementation 'dev.cakit.demo:demo-included:1.0.0'", + "[\"dev.cakit.demo:demo-included\"]"); + Path library = includedLibrary(temporaryRoot); + + // when + BuildResult result = + runner( + project, + "--include-build", + library.toString(), + "verifyCleanArchitectureDependencies") + .buildAndFail(); + + // then: the module the included project exports is named as a library, not a project edge. + assertThat(result.getOutput()) + .contains("Module ':c' has forbidden library dependencies [dev.cakit.demo:demo-extra]") + .doesNotContain("forbidden project dependencies"); + } + + @Test + void anIncludedLibraryWhoseModulesAreAllListedPasses(@TempDir Path temporaryRoot) + throws IOException { + // given + Path project = + libraryFixture( + temporaryRoot, + "implementation 'dev.cakit.demo:demo-included:1.0.0'", + "[\"dev.cakit.demo:demo-included\", \"dev.cakit.demo:demo-extra\"]"); + Path library = includedLibrary(temporaryRoot); + + // when + BuildResult result = + runner( + project, + "--include-build", + library.toString(), + "verifyCleanArchitectureDependencies") + .build(); + + // then + assertThat(result.getOutput()).contains("BUILD SUCCESSFUL"); + } + + @Test + @DisplayName("계층 leaf(domain-core 등) 행에 allowed_libraries를 적으면 registry 위반으로 실패한다") + void aLayerModuleThatAllowsALibraryIsARegistryViolation(@TempDir Path temporaryRoot) + throws IOException { + // given + Path project = temporaryRoot.resolve("repository").resolve("src"); + Files.createDirectories(project.resolve("config/architecture")); + Files.createDirectories(project.resolve("domain-core")); + Files.writeString( + project.resolve("settings.gradle"), "rootProject.name = 'main'\ninclude 'domain-core'\n", UTF_8); + Files.writeString( + project.resolve("build.gradle"), + "plugins { id 'ca.architecture' }\nsubprojects { apply plugin: 'java-library' }\n", + UTF_8); + Files.writeString( + project.resolve("config/architecture/modules.json"), + """ + { + "library_groups": ["dev.cakit"], + "modules": [ + { + "id": "domain-core", + "gradle_path": ":domain-core", + "source_path": "src/domain-core", + "allowed_dependencies": [], + "allowed_libraries": ["dev.cakit.demo:demo-api"] + } + ] + } + """, + UTF_8); + + // when + BuildResult result = runner(project, "verifyCleanArchitectureDependencies").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("'domain-core' is a layer module") + .contains("[dev.cakit.demo:demo-api]"); + } + + /** A library build of two projects in group dev.cakit.demo; demo-included exports demo-extra. */ + private static Path includedLibrary(Path temporaryRoot) throws IOException { + Path library = temporaryRoot.resolve("library"); + Files.createDirectories(library.resolve("demo-included")); + Files.createDirectories(library.resolve("demo-extra")); + Files.writeString( + library.resolve("settings.gradle"), + "rootProject.name = 'library'\ninclude 'demo-included', 'demo-extra'\n", + UTF_8); + Files.writeString( + library.resolve("build.gradle"), + """ + subprojects { + apply plugin: 'java-library' + group = 'dev.cakit.demo' + version = '1.0.0' + } + project(':demo-included') { + dependencies { api project(':demo-extra') } + } + """, + UTF_8); + return library; + } + + /** + * One module {@code c} that declares {@code declaration} against a file repository of POM-only + * modules: {@code dev.cakit.demo:demo-api} (bringing {@code demo-core} in compile scope), + * {@code demo-starter}, and {@code org.example:other}. The direction check reads the resolved + * graph, not the artifacts, so no jar is needed. + */ + private static Path libraryFixture(Path temporaryRoot, String declaration, String cLibraries) + throws IOException { + Path repository = temporaryRoot.resolve("repository"); + Path project = repository.resolve("src"); + Files.createDirectories(project.resolve("config/architecture")); + Files.createDirectories(project.resolve("c")); + Path maven = temporaryRoot.resolve("maven"); + pom(maven, "dev.cakit.demo", "demo-core", ""); + pom( + maven, + "dev.cakit.demo", + "demo-api", + """ + dev.cakit.demodemo-core\ + 1.0.0compile"""); + pom(maven, "dev.cakit.demo", "demo-starter", ""); + pom(maven, "org.example", "other", ""); + + Files.writeString( + project.resolve("settings.gradle"), + """ + rootProject.name = 'main' + include 'c' + """, + UTF_8); + Files.writeString( + project.resolve("build.gradle"), + """ + plugins { id 'ca.architecture' } + subprojects { + apply plugin: 'java-library' + repositories { maven { url = '%s' } } + } + project(':c') { + dependencies { + %s + } + } + """ + .formatted(maven.toUri(), declaration), + UTF_8); + Files.writeString( + project.resolve("config/architecture/modules.json"), + """ + { + "library_groups": ["dev.cakit"], + "modules": [ + { + "id": "c", + "gradle_path": ":c", + "source_path": "src/c", + "allowed_dependencies": [], + "allowed_libraries": %s + } + ] + } + """ + .formatted(cLibraries), + UTF_8); + return project; + } + + private static void pom(Path maven, String group, String artifact, String dependencies) + throws IOException { + Path directory = maven.resolve(group.replace('.', '/')).resolve(artifact).resolve("1.0.0"); + Files.createDirectories(directory); + Files.writeString( + directory.resolve(artifact + "-1.0.0.pom"), + """ + + 4.0.0 + %s%s1.0.0 + pom + %s + + """ + .formatted(group, artifact, dependencies), + UTF_8); + } + private static Path fixture(Path temporaryRoot, boolean allowTransitiveA) throws IOException { Path repository = temporaryRoot.resolve("repository"); Path project = repository.resolve("src"); diff --git a/src/composition/outbox-relay/build.gradle b/src/composition/outbox-relay/build.gradle index 0b9916bd..396b0b03 100644 --- a/src/composition/outbox-relay/build.gradle +++ b/src/composition/outbox-relay/build.gradle @@ -31,10 +31,10 @@ dependencies { testImplementation 'org.springframework.boot:spring-boot-starter-test' // The shutdown-order test runs the real relay over the port owner's shared fake store. testImplementation testFixtures(project(':application-core')) - // The shutdown-order test holds the relay above the platform's admission phase by the platform's - // own constant (MessagingShutdownLifecycle.PHASE), not a copy of its value. Compile-only and - // not transitive: a compile-time constant is inlined, so the platform is not on the test runtime. - testCompileOnly(project(':messaging:messaging-spring-boot-starter')) { + // The shutdown-order test holds the relay above the messaging library's admission phase by the + // library's own constant (MessagingShutdownLifecycle.PHASE), not a copy of its value. Compile-only + // and not transitive: a compile-time constant is inlined, so the library is not on the test runtime. + testCompileOnly(libs.messaging.spring.boot.starter) { transitive = false } testImplementation 'org.mockito:mockito-core' diff --git a/src/composition/outbox-relay/gradle.lockfile b/src/composition/outbox-relay/gradle.lockfile index d96c361c..8daafcda 100644 --- a/src/composition/outbox-relay/gradle.lockfile +++ b/src/composition/outbox-relay/gradle.lockfile @@ -38,6 +38,7 @@ commons-beanutils:commons-beanutils:1.11.0=checkstyle commons-collections:commons-collections:3.2.2=checkstyle commons-io:commons-io:2.21.0=spotbugs commons-logging:commons-logging:1.3.6=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-spring-boot-starter:1.0.0=testCompileClasspath info.picocli:picocli:4.7.7=checkstyle io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor diff --git a/src/composition/outbox-relay/src/test/java/dev/caskeleton/composition/outbox/OutboxRelayShutdownOrderTest.java b/src/composition/outbox-relay/src/test/java/dev/caskeleton/composition/outbox/OutboxRelayShutdownOrderTest.java index 79b6a96c..10eaa274 100644 --- a/src/composition/outbox-relay/src/test/java/dev/caskeleton/composition/outbox/OutboxRelayShutdownOrderTest.java +++ b/src/composition/outbox-relay/src/test/java/dev/caskeleton/composition/outbox/OutboxRelayShutdownOrderTest.java @@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat; import static org.mockito.Mockito.mock; import static org.mockito.Mockito.verifyNoInteractions; +import dev.cakit.messaging.autoconfigure.MessagingShutdownLifecycle; import dev.caskeleton.application.outbox.ClaimedOutboxEvent; import dev.caskeleton.application.outbox.OutboxCompletion; import dev.caskeleton.application.outbox.OutboxEventStatus; @@ -16,7 +17,6 @@ import dev.caskeleton.application.outbox.testkit.InMemoryOutboxStore; import dev.caskeleton.application.outbox.testkit.OutboxEvents; import dev.caskeleton.application.transaction.TransactionPort; import dev.caskeleton.application.transaction.testkit.DirectTransactionPort; -import dev.caskeleton.messaging.autoconfigure.MessagingShutdownLifecycle; import java.time.Clock; import java.time.Instant; import java.util.List; diff --git a/src/config/architecture/README.md b/src/config/architecture/README.md index b494cad8..bc97c7ac 100644 --- a/src/config/architecture/README.md +++ b/src/config/architecture/README.md @@ -4,7 +4,7 @@ 프로젝트 edge를 정확히 적는다. 빈 `allowed_dependencies` 목록에도 뜻이 있다: 그 leaf가 일부러 다른 프로젝트에 기대지 않는다는 뜻이지, registry 항목을 덜 채웠다는 뜻이 아니다. -`domain-core`, `shared-contract`, 들여온 메시징 제품의 `messaging-core-api`가 그 예다. 빈 목록은 +`domain-core`, `shared-contract`가 그 예다. 빈 목록은 분명한 경계이고, 실제 프로젝트 edge를 들여와 리뷰하기 전까지 비어 있어야 한다. 반대로 목록에 적힌 edge는 빌드가 실제로 쓰는 것과 맞아야 한다. 예를 들어 `adapter-outbound-persistence-mongo`의 목록은 `["application-core", "shared-contract"]`이고 `MongoRegistryPermissionParityTest`가 두 방향을 모두 @@ -12,3 +12,21 @@ edge는 빌드가 실제로 쓰는 것과 맞아야 한다. 예를 들어 `adapt 런타임 조립 구성원은 빌드 로직이 해석된 runtime classpath에서 얻는다. 이 registry에 모듈마다 칸으로 다시 적지 않는다. + +## 별도 repo 라이브러리: `library_groups`와 `allowed_libraries` + +소유자가 다른 repo에서 배포하는 라이브러리(메시징 `dev.cakit.messaging`, gRPC `dev.cakit.grpc`)는 이 빌드의 +프로젝트가 아니라 외부 좌표다. 그래서 프로젝트 edge 규칙(`allowed_dependencies`)이 보지 못한다. 그 빈자리를 +두 칸이 메운다(설계 design-docs `repo-structure/05-library-repos.md` 10.2절 T2, 소유자 승인 2026-11-07). + +- 맨 위 `library_groups`: 다스릴 라이브러리의 Maven group 접두사. 지금 `["dev.cakit"]`이다. 이 접두사와 + 같거나 그 아래(`dev.cakit.` 다음) group만 다스린다. 다른 group(Spring, Kafka client 등)은 이 칸과 상관없다. +- 행마다 선택 칸 `allowed_libraries`: 그 leaf가 쓸 수 있는 라이브러리 모듈의 `group:artifact` 목록. 없으면 빈 + 목록과 같다. 값은 `library_groups` 안의 group이어야 하고 겹치면 안 된다(registry를 읽을 때 거절). +- 방향 검사(`verifyModuleDependencyDirection`, `verifyCleanArchitectureDependencies` 아래)는 프로젝트 edge와 같은 + 방식으로 대조한다: 운영 선언(`api`·`implementation`·`compileOnly`·`runtimeOnly`)의 소유 group 좌표와, + `compileClasspath`에서 보이는 소유 group 모듈(라이브러리 모듈이 `api`로 내보낸 것 포함)이 모두 칸에 있어야 + 한다. 시험 구성은 보지 않는다. +- 그래서 지금 지키는 약속 셋이 검사로 남는다: bridge(`adapter-outbound-messaging`)는 `messaging-core-api`만 본다. + Kafka capability(`adapter-outbound-messaging-kafka`)는 starter-kafka를 `runtimeOnly`로만 싣는다. 계층 leaf는 + 칸이 비어 있으니 라이브러리를 쓸 수 없다. diff --git a/src/config/architecture/modules.json b/src/config/architecture/modules.json index 56691b3d..20f07310 100644 --- a/src/config/architecture/modules.json +++ b/src/config/architecture/modules.json @@ -1,4 +1,7 @@ { + "library_groups": [ + "dev.cakit" + ], "modules": [ { "id": "domain-core", @@ -173,11 +176,13 @@ "gradle_path": ":adapter:inbound:messaging", "source_path": "src/adapter/inbound/messaging", "allowed_dependencies": [ - "application-core", - "messaging-core-api", - "messaging-reliability", - "messaging-reliability-api", - "messaging-reliability-jdbc-postgresql" + "application-core" + ], + "allowed_libraries": [ + "dev.cakit.messaging:messaging-core-api", + "dev.cakit.messaging:messaging-reliability", + "dev.cakit.messaging:messaging-reliability-api", + "dev.cakit.messaging:messaging-reliability-jdbc-postgresql" ] }, { @@ -188,8 +193,10 @@ "domain-core", "application-core", "shared-contract", - "adapter-outbound-support", - "messaging-core-api" + "adapter-outbound-support" + ], + "allowed_libraries": [ + "dev.cakit.messaging:messaging-core-api" ] }, { @@ -197,8 +204,10 @@ "gradle_path": ":adapter:outbound:messaging-kafka", "source_path": "src/adapter/outbound/messaging-kafka", "allowed_dependencies": [ - "adapter-outbound-messaging", - "messaging-spring-boot-starter-kafka" + "adapter-outbound-messaging" + ], + "allowed_libraries": [ + "dev.cakit.messaging:messaging-spring-boot-starter-kafka" ] }, { @@ -382,192 +391,6 @@ "composition-service-runtime", "composition-durable-operation" ] - }, - { - "id": "messaging-core-api", - "gradle_path": ":messaging:messaging-core-api", - "source_path": "src/platforms/messaging/messaging-core-api", - "allowed_dependencies": [] - }, - { - "id": "messaging-schema-json", - "gradle_path": ":messaging:messaging-schema-json", - "source_path": "src/platforms/messaging/messaging-schema-json", - "allowed_dependencies": [ - "messaging-core-api" - ] - }, - { - "id": "messaging-schema-avro", - "gradle_path": ":messaging:messaging-schema-avro", - "source_path": "src/platforms/messaging/messaging-schema-avro", - "allowed_dependencies": [ - "messaging-core-api" - ] - }, - { - "id": "messaging-schema-protobuf", - "gradle_path": ":messaging:messaging-schema-protobuf", - "source_path": "src/platforms/messaging/messaging-schema-protobuf", - "allowed_dependencies": [ - "messaging-core-api" - ] - }, - { - "id": "messaging-cloudevents", - "gradle_path": ":messaging:messaging-cloudevents", - "source_path": "src/platforms/messaging/messaging-cloudevents", - "allowed_dependencies": [ - "messaging-core-api" - ] - }, - { - "id": "messaging-policy", - "gradle_path": ":messaging:messaging-policy", - "source_path": "src/platforms/messaging/messaging-policy", - "allowed_dependencies": [ - "messaging-core-api" - ] - }, - { - "id": "messaging-transport-spi", - "gradle_path": ":messaging:messaging-transport-spi", - "source_path": "src/platforms/messaging/messaging-transport-spi", - "allowed_dependencies": [ - "messaging-core-api", - "messaging-policy" - ] - }, - { - "id": "messaging-runtime-core", - "gradle_path": ":messaging:messaging-runtime-core", - "source_path": "src/platforms/messaging/messaging-runtime-core", - "allowed_dependencies": [ - "messaging-core-api", - "messaging-policy", - "messaging-transport-spi", - "messaging-security", - "messaging-observability" - ] - }, - { - "id": "messaging-observability", - "gradle_path": ":messaging:messaging-observability", - "source_path": "src/platforms/messaging/messaging-observability", - "allowed_dependencies": [ - "messaging-core-api" - ] - }, - { - "id": "messaging-security", - "gradle_path": ":messaging:messaging-security", - "source_path": "src/platforms/messaging/messaging-security", - "allowed_dependencies": [ - "messaging-core-api" - ] - }, - { - "id": "messaging-kafka", - "gradle_path": ":messaging:messaging-kafka", - "source_path": "src/platforms/messaging/messaging-kafka", - "allowed_dependencies": [ - "messaging-core-api", - "messaging-policy", - "messaging-transport-spi", - "messaging-observability", - "messaging-security", - "messaging-admin" - ] - }, - { - "id": "messaging-reliability-api", - "gradle_path": ":messaging:messaging-reliability-api", - "source_path": "src/platforms/messaging/messaging-reliability-api", - "allowed_dependencies": [ - "messaging-core-api" - ] - }, - { - "id": "messaging-reliability", - "gradle_path": ":messaging:messaging-reliability", - "source_path": "src/platforms/messaging/messaging-reliability", - "allowed_dependencies": [ - "messaging-core-api", - "messaging-reliability-api" - ] - }, - { - "id": "messaging-reliability-jdbc-postgresql", - "gradle_path": ":messaging:messaging-reliability-jdbc-postgresql", - "source_path": "src/platforms/messaging/messaging-reliability-jdbc-postgresql", - "allowed_dependencies": [ - "messaging-core-api", - "messaging-reliability-api", - "messaging-admin", - "messaging-policy" - ] - }, - { - "id": "messaging-claim-check", - "gradle_path": ":messaging:messaging-claim-check", - "source_path": "src/platforms/messaging/messaging-claim-check", - "allowed_dependencies": [ - "messaging-core-api", - "messaging-reliability-api" - ] - }, - { - "id": "messaging-admin", - "gradle_path": ":messaging:messaging-admin", - "source_path": "src/platforms/messaging/messaging-admin", - "allowed_dependencies": [ - "messaging-core-api", - "messaging-observability" - ] - }, - { - "id": "messaging-spring-boot-starter", - "gradle_path": ":messaging:messaging-spring-boot-starter", - "source_path": "src/platforms/messaging/messaging-spring-boot-starter", - "allowed_dependencies": [ - "messaging-admin", - "messaging-core-api", - "messaging-observability", - "messaging-policy", - "messaging-reliability", - "messaging-reliability-api", - "messaging-reliability-jdbc-postgresql", - "messaging-runtime-core", - "messaging-schema-json", - "messaging-security", - "messaging-transport-spi" - ] - }, - { - "id": "messaging-spring-boot-starter-kafka", - "gradle_path": ":messaging:messaging-spring-boot-starter-kafka", - "source_path": "src/platforms/messaging/messaging-spring-boot-starter-kafka", - "allowed_dependencies": [ - "messaging-spring-boot-starter", - "messaging-kafka", - "messaging-admin", - "messaging-core-api", - "messaging-observability", - "messaging-policy", - "messaging-reliability-api", - "messaging-security", - "messaging-transport-spi" - ] - }, - { - "id": "messaging-testkit", - "gradle_path": ":messaging:messaging-testkit", - "source_path": "src/platforms/messaging/messaging-testkit", - "allowed_dependencies": [ - "messaging-core-api", - "messaging-policy", - "messaging-transport-spi" - ] } ] } diff --git a/src/config/spotbugs/exclude-test.xml b/src/config/spotbugs/exclude-test.xml index cd9764ff..943586fb 100644 --- a/src/config/spotbugs/exclude-test.xml +++ b/src/config/spotbugs/exclude-test.xml @@ -99,9 +99,9 @@ - + @@ -109,10 +109,6 @@ - - - - diff --git a/src/config/spotbugs/exclude.xml b/src/config/spotbugs/exclude.xml index eddd3652..99a0419c 100644 --- a/src/config/spotbugs/exclude.xml +++ b/src/config/spotbugs/exclude.xml @@ -69,27 +69,6 @@ - - - - - - - - - - - - - @@ -182,9 +160,6 @@ - - - @@ -220,7 +195,6 @@ - @@ -234,15 +208,6 @@ - - - - - - - @@ -281,7 +246,7 @@ @@ -290,7 +255,6 @@ - @@ -317,15 +281,6 @@ - - - - - - - @@ -353,7 +308,7 @@ @@ -362,7 +317,6 @@ - @@ -398,13 +352,11 @@ + reconfigured after build() (NotificationJsonMapper). --> - diff --git a/src/gradle/libs.versions.toml b/src/gradle/libs.versions.toml index fd868f6d..946e1013 100644 --- a/src/gradle/libs.versions.toml +++ b/src/gradle/libs.versions.toml @@ -10,7 +10,8 @@ # show them side by side, so two artifacts had quietly reached two versions: # # * spock-core 2.3-groovy-4.0 and 2.4-groovy-5.0 -# * protobuf-java 4.29.3 and 4.33.2 +# * protobuf-java 4.29.3 and 4.33.2 (the 4.33.2 user, the messaging library's protobuf codec, +# moved to its own repository on 2026-11-08) # # Both are kept as separate aliases rather than unified. Unifying them here would change what # resolves, in a change whose whole purpose is that it does not; the aliases make the split @@ -35,14 +36,12 @@ approvaltests = "31.0.0" assertj = "3.27.7" archunit = "1.3.0" -avro = "1.12.0" # AWS SDK v2 BOM coordinate. Imported at MODULE scope by adapter:outbound:objectstorage # and app-bootstrap through `ext.awsSdkVersion`, which reads this key. awsSdk = "2.30.0" # Checkstyle *tool* version (the `checkstyle` extension), not a plugin: Checkstyle is a Gradle # built-in plugin with no coordinate of its own. checkstyle = "13.5.0" -cloudevents = "4.0.1" errorprone = "2.49.0" # The Gradle plugin that runs the checker above. Two different artifacts, two different version # lines, deliberately adjacent so a bump of one is visibly not a bump of the other. @@ -72,12 +71,16 @@ junitPlatform = "1.11.3" logstashLogbackEncoder = "8.0" # Pinned (see `pinned-*` below). CVE-2026-106451, fixed in 1.11.4. Brought by kafka-clients (1.10.1). lz4Java = "1.11.4" +# The messaging library (messaging-library repo, Maven group dev.cakit.messaging), one version for +# every module of it: a release publishes all of them together. Raise it by the procedure in +# docs/work/reference/related-repos.md 3절 (lockfiles rewritten, the leaves' lanes, the CHANGELOG). +messagingLibrary = "1.0.0" okhttp = "4.12.0" # Pinned (see `pinned-*` below). CVE-2025-67030, fixed in 3.6.1 on the 3.x line. Brought by the # Checkstyle tool's doxia (3.3.0). plexusUtils = "3.6.1" -protobuf = "4.33.2" -# The third live protobuf version, and the reason this file now shows all three. adapter:inbound:grpc +# The second live protobuf version (the messaging library's schema codec pins the third, 4.33.2, in its +# own repository since 2026-11-08). adapter:inbound:grpc # imports protobuf-bom at this major to match the gRPC BOM above; it is read through # `ext.protobufVersion`. Keep it at the protobuf-java that grpc-protobuf of that BOM declares: the # protobuf-bom import is what resolves, so a lower number here would run gRPC on an older runtime @@ -114,9 +117,6 @@ uuidCreator = "6.1.1" approvaltests = { module = "com.approvaltests:approvaltests", version.ref = "approvaltests" } assertj-core = { module = "org.assertj:assertj-core", version.ref = "assertj" } archunit-junit5 = { module = "com.tngtech.archunit:archunit-junit5", version.ref = "archunit" } -avro = { module = "org.apache.avro:avro", version.ref = "avro" } -cloudevents-api = { module = "io.cloudevents:cloudevents-api", version.ref = "cloudevents" } -cloudevents-core = { module = "io.cloudevents:cloudevents-core", version.ref = "cloudevents" } errorprone-core = { module = "com.google.errorprone:error_prone_core", version.ref = "errorprone" } findsecbugs-plugin = { module = "com.h3xstream.findsecbugs:findsecbugs-plugin", version.ref = "findsecbugs" } jackson-databind-nullable = { module = "org.openapitools:jackson-databind-nullable", version = "0.2.6" } @@ -129,9 +129,16 @@ json-schema-validator = { module = "com.networknt:json-schema-validator", versio junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junitJupiter" } junit-platform-launcher = { module = "org.junit.platform:junit-platform-launcher", version.ref = "junitPlatform" } logstash-logback-encoder = { module = "net.logstash.logback:logstash-logback-encoder", version.ref = "logstashLogbackEncoder" } +# The messaging library's modules the leaves use. Each leaf's registry row lists the ones it may +# reach in `allowed_libraries` (config/architecture/modules.json). +messaging-core-api = { module = "dev.cakit.messaging:messaging-core-api", version.ref = "messagingLibrary" } +messaging-reliability = { module = "dev.cakit.messaging:messaging-reliability", version.ref = "messagingLibrary" } +messaging-reliability-api = { module = "dev.cakit.messaging:messaging-reliability-api", version.ref = "messagingLibrary" } +messaging-reliability-jdbc-postgresql = { module = "dev.cakit.messaging:messaging-reliability-jdbc-postgresql", version.ref = "messagingLibrary" } +messaging-spring-boot-starter = { module = "dev.cakit.messaging:messaging-spring-boot-starter", version.ref = "messagingLibrary" } +messaging-spring-boot-starter-kafka = { module = "dev.cakit.messaging:messaging-spring-boot-starter-kafka", version.ref = "messagingLibrary" } mockwebserver = { module = "com.squareup.okhttp3:mockwebserver", version.ref = "okhttp" } okhttp-tls = { module = "com.squareup.okhttp3:okhttp-tls", version.ref = "okhttp" } -protobuf-java = { module = "com.google.protobuf:protobuf-java", version.ref = "protobuf" } protobuf-java-legacy = { module = "com.google.protobuf:protobuf-java", version.ref = "protobufLegacy" } resilience4j-bulkhead = { module = "io.github.resilience4j:resilience4j-bulkhead", version.ref = "resilience4j" } resilience4j-circuitbreaker = { module = "io.github.resilience4j:resilience4j-circuitbreaker", version.ref = "resilience4j" } diff --git a/src/platforms/messaging/AGENTS.md b/src/platforms/messaging/AGENTS.md deleted file mode 100644 index 9c68440a..00000000 --- a/src/platforms/messaging/AGENTS.md +++ /dev/null @@ -1,176 +0,0 @@ -# messaging — 메시징 플랫폼 family의 지역 정본 - -이 문서는 messaging family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 -`src/config/architecture/modules.json`이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는 -것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, public surface 정책, Stable 승격에 -필요한 증거, runtime membership이 비어 있다는 사실의 의미. - -루트 `AGENTS.md`와 충돌하면 루트가 이긴다. - -## Family와 framework 규칙 - -leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이름의 접두사**가 아니라 아래 표의 -역할로 정해진다. - -| Family | 역할 | 허용 framework | -| --- | --- | --- | -| `*-api` (`core-api` — `api`·`schema` 패키지, `policy`, `reliability-api`, `transport-spi`) | 값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging framework 금지 | -| `schema-*` (json/avro/protobuf), `cloudevents` | 인코딩 구현 | 해당 codec 라이브러리만. Spring 금지 | -| `runtime-core`, `security`, `observability`, `admin`(계약 `admin` + 실행 `admin.runtime`), `reliability` | framework-free 실행 로직 | Micrometer는 `observability`에서만. 나머지는 stdlib | -| `kafka` | broker adapter | 해당 broker client. Spring은 client가 곧 Spring인 경우만 | -| `reliability-jdbc-postgresql` | 관계형 신뢰성 adapter (outbox·inbox repository, admin journal) | Spring JDBC / Spring TX. **JPA 아님** — 이름이 곧 계약이다 | -| `spring-boot-starter`, `spring-boot-starter-kafka` | 조립 경계 | Spring Boot autoconfigure. 여기서만 | -| `testkit` | 테스트 지원 | Testcontainers, JUnit. production leaf가 의존하지 않는다 | - -신뢰성 기능은 세 leaf다. `messaging-reliability-api`가 vendor 중립 port(`OutboxRepository`, -`InboxRepository`)를, `messaging-reliability`가 그 port만 보는 relay·consumer 로직(stdlib)을, -`messaging-reliability-jdbc-postgresql`이 port의 관계형 구현과 migration(`V1001..V1005`, `V1101`)을 -갖는다. 예전에는 `outbox-jdbc-postgresql` 하나가 relay 로직과 PG repository와 admin journal을 함께 -가졌고 inbox도 같은 모양이었다(2026-09-25 리뷰 후속 작업에서 나눴다). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring -JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL -전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다. - -### 공용 다이제스트 헬퍼를 복사해 두는 이유 - -`messaging-admin`(`HmacApprovalVerifier`, `PlanDigest`)과 `messaging-claim-check` -(`ClaimCheckIntegrityGuard`)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의 -`shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 family는 이 애플리케이션의 -계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치), `messaging:*` leaf는 -`domain-core`·`application-core`·`shared-contract` 어느 타입에도 의존하지 않는다. 헬퍼 하나 때문에 -registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는 -`shared-contract`의 정본과 같은 규칙인지 함께 본다. - -### 인증·인가 거부의 발행 재시도 여부 (Publish retryability of authentication and authorization) - -이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다. - -- category 기본값: `FailureDescriptor.defaultRetryable(AUTHENTICATION | AUTHORIZATION) = false`. 소비 쪽 - 재시도 엔진(`DefaultRetryDecisionEngine`)은 policy가 category를 따로 정하지 않으면 이 기본값과 - descriptor의 `retryable`을 둘 다 요구한다. 그래서 인가받지 못한 메시지의 재전달은 지금도 재시도하지 않는다. -- publish 거부의 `retryable`: `KafkaPublishFailureClassifier`는 인증·인가 거부에 `retryable = true`를 붙인다. - broker가 레코드를 저장하지 않았고, credential 교체나 application보다 늦게 배포된 ACL은 몇 분 동안 모든 - publish를 거부한 뒤 멈추기 때문이다. `retryable`을 믿는 publisher가 그 몇 분 동안의 레코드를 영구 보류하지 - 않게 하려는 것이다. - -다시 시도하면 될 거부를 relay가 즉시 DEAD로 보내던 결함의 수정(2026-11-01 성숙도 리뷰 뒤)이 이 제품에서 바꾼 것(모두 -publish 경로, 소비 경로 동작은 그대로): - -- `KafkaPublishFailureClassifier`: 인증·인가 거부를 `retryable = true`로. -- `DefaultMessagePublisher`: runtime이 없을 때의 거부(`PUBLISH_RUNTIME_UNAVAILABLE`)를 `retryable = true`로. -- `KafkaMessagingTransport`: 닫힌 transport의 거부(`KAFKA_TRANSPORT_CLOSED`)를 `retryable = true`로. -- `MessagingShutdownLifecycle.PHASE`: platform 밖 relay의 순서 테스트가 참조하도록 public. - -버린 대안: vendored 제품은 그대로 두고 application bridge(ACL)가 category를 보고 "인증·인가면 재시도"로 -번역하는 것. 버린 이유: `retryable`은 이 제품이 "같은 레코드를 나중에 다시 보내면 받아질 수 있나"를 말하는 -자리다. bridge가 category로 그 판단을 다시 하면 같은 사실을 제품과 bridge가 따로 정하고, 이 제품의 -`PublishResult`를 읽는 다른 호출자는 bridge와 다른 답을 본다. 대신 이 제품 주석은 소비자 이름(application -relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(2026-11-03). - -## Public surface 정책 - -- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이 - 숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다. - (`kafka-clients`, `cloudevents-api`, `micrometer-core`, `avro`, - `protobuf-java`가 이 규칙으로 `api`다.) -- 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을 - `implementation`으로 내린 것이, JSON codec이 `ObjectMapper`를 private으로만 쓰고 Jackson을 - `implementation`으로 둔 것이 그 예다. -- 이 규칙은 문서가 아니라 `MessagingPublicSurfaceContractTest`가 붙들고 있다. leaf의 production - source에서 public/protected 시그니처에 등장하는 vendor 라이브러리를 뽑아 그 leaf의 - `build.gradle`이 `api`로 선언했는지 대조하고, starter의 `api` closure에 broker client 두 개가 - 들어오지 않는 것도 함께 본다. Spring Framework/Boot는 대상이 아니다 — 조립 경계 안에서만 - 등장하고 adopter가 이름 부를 일이 없다. -- 새 public 타입은 그 모듈의 계약이다. 삭제·시그니처 변경은 breaking change로 취급한다. - -## Application runtime에 포함되는 기준 - -기본 조립에는 Messaging family가 없다. 서비스가 `app-bootstrap/build.gradle`에 -`runtimeOnly project(':adapter:outbound:messaging-kafka')` 한 줄을 넣으면 그 모듈이 bridge와 -`messaging-spring-boot-starter`(Kafka transport 포함)의 transitive project graph를 runtime에 싣는다. 이 -사실의 SSOT는 Gradle `runtimeClasspath`이며 registry에 동일한 membership 목록을 복제하지 않는다. -모듈이 있으면 켜지고(`app.messaging.enabled` 기본 `true`), `APP_MESSAGING_ENABLED=false`로만 끈다. - -일부 codec(cloudevents 등)·claim-check·testkit처럼 starter graph에 들어오지 않는 leaf는 build-only다. -RabbitMQ·Pulsar·NATS·Kafka Share·Spring Cloud Stream bridge leaf와 Debezium outbox 매핑은 -2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표). -새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy, -qualification/support 상태를 함께 변경한다. - -## application이 이 family에 도달하는 경로 (cutover 완료) - -리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한 -`application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다. - -- application-owned port: `IntegrationEventPublishPort` -- bridge: `adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter` -- platform boundary: `EncodedMessagePublisher` -- central implementation: `DefaultMessagePublisher` - -bridge는 exact canonical envelope bytes를 다시 serialize하지 않고, destination/access/admission/runtime -lease/transport/outcome normalization/observation은 platform 중앙 publish path를 그대로 탄다. bridge -package는 `messaging-core-api`만 보며 concrete runtime/transport/Kafka 타입을 -직접 보지 않는다. - -**application bridge cutover는 2026-09-28에 끝났다(2026-09-25 소유자 결정).** application의 outbox append는 canonical -`OutboxAppendPort` 하나이고, relay는 claim한 row의 validated event를 이 bridge로만 보낸다. legacy -`OutboxEvent`·`LegacyOutboxAppendPort`와 `MessageBroker → KafkaSender` R0 경로(TLS/SASL을 적용하지 -않던 두 번째 producer)는 삭제했다. 남은 Kafka producer는 platform의 것 하나이고, broker security -profile(`KafkaSecurityConfigurer`)을 적용한다. - -canonical bridge의 producer identity는 `app.messaging.producer-id`로 명시한다. 값이 없으면 bridge bean을 -만들지 않으며 `spring.application.name`/host/pod 이름에서 identity를 발명하지 않는다. bridge가 없으면 -relay가 발행할 곳이 없으므로 messaging 모듈이 켜진 상태에서는 기동이 거부된다. - -`IntegrationEventEncoderPort`는 템플릿이 제공한다: `adapter:outbound:support`의 -`JsonIntegrationEventEncoder`가 envelope v1(`shared-contract`의 `contracts/messaging/envelope/v1.schema.json`) -안에 payload record를 결정적 JSON으로 싣는다. 계약 catalog는 애플리케이션이 bean으로 등록한 -`IntegrationEventContractContribution`뿐이고, 선언한 payload schema hash가 classpath의 schema 파일과 -다르면 기동이 실패한다. payload를 JSON Schema로 매번 검증하려는 서비스는 자기 encoder bean을 두면 된다. - -## Stable 승격에 필요한 증거 - -adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/support-matrix.md`가 현재 -상태를 기록한다): - -1. 실제 broker container를 쓰는 fault 시나리오 lane이 존재하고, 그 lane이 - `BrokerCertificationEvidence`를 산출한다. -2. `NetworkFaultScenario` 전 항목에 대해 evidence가 있거나, 없는 항목이 `knownGaps`로 명시된다. -3. capability 선언이 코드에서 파생된다 — `MessagingCapabilities`에 손으로 `true`를 쓰는 것은 - 증거가 아니다. -4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은 - Experimental에서도 금지다. -5. unknown failure의 기본값이 `AMBIGUOUS`다. `REJECTED`는 전송이 시작되지 않았다는 typed 증거가 - 있을 때만. - -Stable 문구는 evidence manifest가 존재할 때만 문서에 쓴다. - -증거를 만드는 것은 인증 레인이고, manifest는 그 실행의 출력이다: - -```bash -./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence --console=plain -``` - -레인(`messagingCertificationTest`)은 Toxiproxy를 broker 앞에 두고 장애를 주입하며, -통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을 -`messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl`에 쓴다. -게이트는 커밋된 manifest와 이번 실행의 출력을 대조한다 — **manifest를 손으로 고치면 실패하고, -레인을 돌리면 manifest가 다시 쓰인다.** 이 레인만은 Docker 가드를 달지 않는다(없으면 실패한다). -skip하는 인증 레인은 아무도 켜지 않은 브로커에 대해 성공을 보고하기 때문이며, 그래서 `test`에서는 -`messaging-certification` 태그로 제외된다. - -## Focused test - -leaf의 `gradle_path`를 registry에서 읽어 파생한다. - -```bash -cd src -./gradlew :test --console=plain -``` - -Family 전체 검증: - -```bash -./gradlew verifyCleanArchitectureDependencies --console=plain -./gradlew architectureCheck --console=plain -./gradlew verifyDependencyLocks --console=plain -``` diff --git a/src/platforms/messaging/CLAUDE.md b/src/platforms/messaging/CLAUDE.md deleted file mode 100644 index 43c994c2..00000000 --- a/src/platforms/messaging/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -@AGENTS.md diff --git a/src/platforms/messaging/messaging-admin/build.gradle b/src/platforms/messaging/messaging-admin/build.gradle deleted file mode 100644 index a6b6ce55..00000000 --- a/src/platforms/messaging/messaging-admin/build.gradle +++ /dev/null @@ -1,14 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -// The admin plane: its contract (package `admin`) and the stdlib services that execute it -// (package `admin.runtime`). They were two leaves, and every consumer of the runtime took the -// contract too, so the split added a registry entry without separating anything (S7-#12). -dependencies { - api project(':messaging:messaging-core-api') - - // ReplayService records a MessagingAuditEvent internally; no public signature names it, so - // Micrometer does not reach the journal adapters that implement the contract. - implementation project(':messaging:messaging-observability') -} diff --git a/src/platforms/messaging/messaging-admin/gradle.lockfile b/src/platforms/messaging/messaging-admin/gradle.lockfile deleted file mode 100644 index dcab1d05..00000000 --- a/src/platforms/messaging/messaging-admin/gradle.lockfile +++ /dev/null @@ -1,87 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.21.0=spotbugs -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor -io.micrometer:micrometer-commons:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-core:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-observation:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath -org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.hdrhistogram:HdrHistogram:2.2.2=runtimeClasspath,testRuntimeClasspath -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath -org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.latencyutils:LatencyUtils:2.0.3=runtimeClasspath,testRuntimeClasspath -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminApproval.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminApproval.java deleted file mode 100644 index 8013c77d..00000000 --- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminApproval.java +++ /dev/null @@ -1,45 +0,0 @@ -package dev.caskeleton.messaging.admin; - -import java.time.Instant; -import java.util.Objects; - -/** - * The approval that authorises a destructive messaging operation. - * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The loop had no per-item boundary. A publisher that threw — a broker refusing the connection - * rather than the message — propagated straight out, so every candidate behind it was abandoned and - * the audit record was never written. The operation left no trace of what it had already moved, and - * a retry started again from the first candidate and republished it. - */ -class RedriveResumptionTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:00:00Z"); - private static final DestinationName DLQ = new DestinationName("orders.v1.dlq"); - private static final DestinationName ORDERS = new DestinationName("orders.v1"); - - private static final HmacApprovalVerifier ISSUER = - new HmacApprovalVerifier( - "an-issuing-key-of-at-least-32-bytes!".getBytes(java.nio.charset.StandardCharsets.UTF_8)); - - private final RecordingSource source = new RecordingSource(); - private final RecordingAudit audit = new RecordingAudit(); - - @Test - @DisplayName("one message that throws does not abandon the ones behind it") - void oneThrowingMessageDoesNotAbandonTheRest() { - List candidates = ids(4); - source.stage(candidates); - RedriveService service = - service( - (messageId, target, redriveId) -> { - if (messageId.equals(candidates.get(1))) { - throw new IllegalStateException("the broker refused the connection"); - } - return confirmed(); - }); - - RedriveReport report = service.redrive(request(), approval(), "operator", NOW); - - assertThat(report.moved()).isEqualTo(3); - assertThat(report.failed()) - .as("the throwing item is a failed item, not a failed pass") - .isEqualTo(1); - assertThat(source.settled) - .containsExactly(candidates.get(0), candidates.get(2), candidates.get(3)); - } - - @Test - @DisplayName("the audit record is written even when the pass does not finish cleanly") - void theAuditRecordIsWrittenEvenOnFailure() { - source.stage(ids(2)); - RedriveService service = - service( - (messageId, target, redriveId) -> { - throw new IllegalStateException("the broker refused the connection"); - }); - - service.redrive(request(), approval(), "operator", NOW); - - assertThat(audit.events) - .as("the record of what moved is what the incident review and the resumed run both read") - .singleElement() - .satisfies(event -> assertThat(event.details()).containsEntry("failed", "2")); - } - - @Test - @DisplayName("a resumed pass does not republish what the first attempt already moved") - void aResumedPassDoesNotRepublishWhatWasAlreadyMoved() { - List candidates = ids(5); - source.stage(candidates); - List republished = new ArrayList<>(); - RedriveService service = - service( - (messageId, target, redriveId) -> { - republished.add(messageId); - return confirmed(); - }); - - RedriveReport report = - service.redrive(request(), approval(), "operator", NOW, 3, completed -> {}); - - assertThat(republished) - .as("republishing a settled message is a duplicate, not a retry") - .containsExactly(candidates.get(3), candidates.get(4)); - assertThat(report.moved()).isEqualTo(2); - } - - @Test - @DisplayName("progress is reported after each item so a crash resumes near where it stopped") - void progressIsReportedAfterEachItem() { - source.stage(ids(3)); - List checkpoints = new ArrayList<>(); - RedriveService service = service((messageId, target, redriveId) -> confirmed()); - - service.redrive(request(), approval(), "operator", NOW, 0, checkpoints::add); - - assertThat(checkpoints).containsExactly(1, 2, 3); - } - - @Test - @DisplayName("resuming past the end of the batch moves nothing") - void resumingPastTheEndOfTheBatchMovesNothing() { - source.stage(ids(2)); - RedriveService service = service((messageId, target, redriveId) -> confirmed()); - - RedriveReport report = - service.redrive(request(), approval(), "operator", NOW, 10, completed -> {}); - - assertThat(report.moved()).isZero(); - } - - private RedriveService service(RedriveService.RedrivePublisher publisher) { - // The guard holds the admin credential and every pass carries a real verified approval: this - // test is about the loop, and a gate that refused would prove nothing about it. - return new RedriveService(new DestructiveOperationGuard(true), source, publisher, audit); - } - - private static Optional approval() { - PlanDigest digest = PlanDigest.ofCanonical("REDRIVE|orders.v1.dlq|orders.v1"); - ApprovalGrant grant = - new ApprovalGrant( - new AdminApproval("CHG-1042", "ops@example.com", NOW, NOW.plus(Duration.ofHours(2))), - "operator@example.com", - DestructiveOperation.REDRIVE, - DLQ, - Optional.of(ORDERS), - "v1", - Long.MAX_VALUE, - digest); - return Optional.of(ISSUER.verify(grant, ISSUER.sign(grant), digest, NOW)); - } - - private static RedriveRequest request() { - return new RedriveRequest(UUID.randomUUID(), DLQ, ORDERS, 50, false); - } - - private static PublishResult confirmed() { - return new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK), - RoutingOutcome.ROUTED, - Optional.empty(), - 1, - Duration.ofMillis(2), - Optional.empty()); - } - - private static List ids(int count) { - List ids = new ArrayList<>(); - for (int index = 0; index < count; index++) { - ids.add(MessageId.newId()); - } - return List.copyOf(ids); - } - - private static final class RecordingSource implements RedriveService.RedriveSource { - - private List staged = List.of(); - private final List settled = new ArrayList<>(); - - private void stage(List ids) { - staged = List.copyOf(ids); - } - - @Override - public List peek(DestinationName destination, int batchSize) { - return staged; - } - - @Override - public void settle(DestinationName destination, MessageId messageId) { - settled.add(messageId); - } - } - - private static final class RecordingAudit implements RedriveService.AuditSink { - - private final List events = new ArrayList<>(); - - @Override - public void record(MessagingAuditEvent event) { - events.add(event); - } - } -} diff --git a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ReplayServiceTest.java b/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ReplayServiceTest.java deleted file mode 100644 index 395ec201..00000000 --- a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ReplayServiceTest.java +++ /dev/null @@ -1,77 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.admin.DestructiveOperationGuard; -import dev.caskeleton.messaging.admin.ReplayRequest; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessageAuthorizationException; -import java.time.Duration; -import java.time.Instant; -import java.util.Optional; -import java.util.UUID; -import java.util.concurrent.atomic.AtomicInteger; -import org.junit.jupiter.api.Test; - -class ReplayServiceTest { - - private static final Instant NOW = Instant.parse("2026-09-21T00:00:00Z"); - private static final DestinationName DESTINATION = new DestinationName("orders.v1"); - - @Test - void callerClaimedIsolationDoesNotBypassApprovalForARealReplay() { - AtomicInteger executions = new AtomicInteger(); - ReplayService service = - new ReplayService( - new DestructiveOperationGuard(true), - request -> { - executions.incrementAndGet(); - return 1; - }, - event -> {}); - - ReplayRequest request = - new ReplayRequest( - UUID.fromString("0199aaaa-bbbb-7ccc-8ddd-eeeeffff1000"), - DESTINATION, - NOW.minus(Duration.ofHours(1)), - Optional.empty(), - true, - false); - - assertThatThrownBy(() -> service.replay(request, Optional.empty(), "operator", NOW)) - .isInstanceOfSatisfying( - MessageAuthorizationException.class, - failure -> assertThat(failure.failure().code()).isEqualTo("APPROVAL_REQUIRED")); - assertThat(executions).hasValue(0); - } - - @Test - void dryRunRemainsApprovalFreeEvenWhenIsolationIsOnlyAnIntentFlag() { - AtomicInteger executions = new AtomicInteger(); - ReplayService service = - new ReplayService( - new DestructiveOperationGuard(true), - request -> { - executions.incrementAndGet(); - return 1; - }, - event -> {}); - - ReplayRequest request = - new ReplayRequest( - UUID.fromString("0199aaaa-bbbb-7ccc-8ddd-eeeeffff1001"), - DESTINATION, - NOW.minus(Duration.ofHours(1)), - Optional.empty(), - true, - true); - - ReplayReport report = service.replay(request, Optional.empty(), "operator", NOW); - - assertThat(report.dryRun()).isTrue(); - assertThat(report.replayed()).isZero(); - assertThat(executions).hasValue(0); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntimeTest.java b/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntimeTest.java deleted file mode 100644 index 2927ac29..00000000 --- a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntimeTest.java +++ /dev/null @@ -1,65 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import static org.assertj.core.api.Assertions.assertThatCode; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.admin.TopologyManifest; -import dev.caskeleton.messaging.api.error.MessageTopologyException; -import java.util.List; -import java.util.Map; -import org.junit.jupiter.api.Test; - -class TopologyValidationRuntimeTest { - - private static final TopologyManifest ORDERS = - new TopologyManifest( - "order-events", "order.events.v1", 6, 3, Map.of("min.insync.replicas", "2")); - - @Test - void aMatchingTopologyValidates() { - TopologyValidationRuntime runtime = - new TopologyValidationRuntime( - name -> - new TopologyValidationRuntime.ObservedTopology( - 6, 3, Map.of("min.insync.replicas", "2"))); - - assertThatCode(() -> runtime.validate(List.of(ORDERS))).doesNotThrowAnyException(); - } - - @Test - void aMissingDestinationFailsStartup() { - TopologyValidationRuntime runtime = new TopologyValidationRuntime(name -> null); - - assertThatThrownBy(() -> runtime.validate(List.of(ORDERS))) - .isInstanceOf(MessageTopologyException.class) - .hasMessageContaining("does not exist"); - } - - @Test - void aWeakenedReplicationSettingFailsStartup() { - TopologyValidationRuntime runtime = - new TopologyValidationRuntime( - name -> - new TopologyValidationRuntime.ObservedTopology( - 6, 3, Map.of("min.insync.replicas", "1"))); - - assertThatThrownBy(() -> runtime.validate(List.of(ORDERS))) - .isInstanceOf(MessageTopologyException.class) - .hasMessageContaining("min.insync.replicas"); - } - - @Test - void everyDifferenceIsReportedAtOnce() { - TopologyValidationRuntime runtime = - new TopologyValidationRuntime( - name -> - new TopologyValidationRuntime.ObservedTopology( - 3, 1, Map.of("min.insync.replicas", "1"))); - - assertThatThrownBy(() -> runtime.validate(List.of(ORDERS))) - .isInstanceOf(MessageTopologyException.class) - .hasMessageContaining("partitions") - .hasMessageContaining("replicationFactor") - .hasMessageContaining("min.insync.replicas"); - } -} diff --git a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidatorTest.java b/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidatorTest.java deleted file mode 100644 index a792ddd6..00000000 --- a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidatorTest.java +++ /dev/null @@ -1,172 +0,0 @@ -package dev.caskeleton.messaging.admin.runtime; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatCode; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.admin.DestinationTopology; -import dev.caskeleton.messaging.admin.TopologyIssue; -import dev.caskeleton.messaging.admin.TopologyManagementMode; -import dev.caskeleton.messaging.admin.TopologyManifest; -import dev.caskeleton.messaging.admin.TopologyValidationReport; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.util.List; -import java.util.Map; -import java.util.Optional; -import org.junit.jupiter.api.Test; - -class TopologyValidatorTest { - - private final TopologyValidator validator = new TopologyValidator(); - - private static TopologyManifest manifest() { - return new TopologyManifest( - "orders.v1", "orders-v1", 12, 3, Map.of("min.insync.replicas", "2")); - } - - private static DestinationTopology observed( - int partitions, int replication, Map config) { - return new DestinationTopology("orders-v1", partitions, replication, config, true); - } - - @Test - void anAgreeingTopologyProducesNoIssues() { - assertThat(validator.compare(manifest(), observed(12, 3, Map.of("min.insync.replicas", "2")))) - .isEmpty(); - } - - @Test - void anAbsentDestinationBlocksStartup() { - List issues = - validator.compare(manifest(), DestinationTopology.absent("orders-v1")); - - assertThat(issues) - .singleElement() - .satisfies( - issue -> { - assertThat(issue.attribute()).isEqualTo("existence"); - assertThat(issue.severity()).isEqualTo(TopologyIssue.Severity.BLOCKING); - }); - } - - @Test - void tooFewPartitionsBlocksBecauseKeysWouldLandDifferently() { - List issues = - validator.compare(manifest(), observed(6, 3, Map.of("min.insync.replicas", "2"))); - - assertThat(issues) - .singleElement() - .satisfies( - issue -> assertThat(issue.severity()).isEqualTo(TopologyIssue.Severity.BLOCKING)); - } - - @Test - void extraPartitionsAreAdvisoryBecauseScalingUpIsLegitimate() { - List issues = - validator.compare(manifest(), observed(24, 3, Map.of("min.insync.replicas", "2"))); - - assertThat(issues) - .singleElement() - .satisfies( - issue -> assertThat(issue.severity()).isEqualTo(TopologyIssue.Severity.ADVISORY)); - } - - @Test - void tooLittleReplicationBlocksBecauseDurabilityIsPromised() { - List issues = - validator.compare(manifest(), observed(12, 1, Map.of("min.insync.replicas", "2"))); - - assertThat(issues) - .singleElement() - .satisfies( - issue -> { - assertThat(issue.attribute()).isEqualTo("replicationFactor"); - assertThat(issue.severity()).isEqualTo(TopologyIssue.Severity.BLOCKING); - }); - } - - @Test - void aMissingRequiredConfigurationEntryBlocks() { - List issues = validator.compare(manifest(), observed(12, 3, Map.of())); - - assertThat(issues) - .singleElement() - .satisfies(issue -> assertThat(issue.actual()).isEqualTo("unset")); - } - - @Test - void everyIssueIsCollectedRatherThanFailingOnTheFirst() { - List issues = validator.compare(manifest(), observed(6, 1, Map.of())); - - assertThat(issues) - .as("discovering the next problem only after a redeploy turns one fix into several") - .hasSize(3); - } - - @Test - void aReportRefusesStartupWhenAnythingBlocks() { - TopologyValidationReport report = - new TopologyValidationReport( - validator.compare(manifest(), observed(12, 1, Map.of("min.insync.replicas", "2"))), 1); - - assertThat(report.isAcceptable()).isFalse(); - assertThatThrownBy(report::requireAcceptable) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("replicationFactor"); - } - - @Test - void anAdvisoryOnlyReportStillStarts() { - TopologyValidationReport report = - new TopologyValidationReport( - validator.compare(manifest(), observed(24, 3, Map.of("min.insync.replicas", "2"))), 1); - - assertThat(report.isAcceptable()).isTrue(); - assertThat(report.advisory()).hasSize(1); - assertThatCode(report::requireAcceptable).doesNotThrowAnyException(); - } - - @Test - void theCompositeValidatorChecksEveryManifest() { - CompositeTopologyValidator composite = - new CompositeTopologyValidator( - new BrokerTopologyInspector() { - @Override - public Optional describe(String physicalName) { - return Optional.empty(); - } - - @Override - public String topologyVersion() { - return "v1"; - } - }); - - TopologyValidationReport report = - composite.validate( - List.of( - manifest(), new TopologyManifest("payments.v1", "payments-v1", 3, 3, Map.of()))); - - assertThat(report.destinationsChecked()).isEqualTo(2); - assertThat(report.blocking()).hasSize(2); - } - - @Test - void autoCreationIsRefusedInProduction() { - assertThatThrownBy(() -> TopologyManagementMode.CREATE_IF_MISSING.requireSafeFor(true)) - .as("a mistyped destination would be created and look exactly like a real one") - .isInstanceOf(MessagingConfigurationException.class); - } - - @Test - void autoCreationIsAllowedOutsideProduction() { - assertThatCode(() -> TopologyManagementMode.CREATE_IF_MISSING.requireSafeFor(false)) - .doesNotThrowAnyException(); - } - - @Test - void validateOnlyIsAlwaysSafe() { - assertThatCode(() -> TopologyManagementMode.VALIDATE_ONLY.requireSafeFor(true)) - .doesNotThrowAnyException(); - } -} diff --git a/src/platforms/messaging/messaging-claim-check/build.gradle b/src/platforms/messaging/messaging-claim-check/build.gradle deleted file mode 100644 index a145cc45..00000000 --- a/src/platforms/messaging/messaging-claim-check/build.gradle +++ /dev/null @@ -1,8 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') - api project(':messaging:messaging-reliability-api') -} diff --git a/src/platforms/messaging/messaging-claim-check/gradle.lockfile b/src/platforms/messaging/messaging-claim-check/gradle.lockfile deleted file mode 100644 index d74807c4..00000000 --- a/src/platforms/messaging/messaging-claim-check/gradle.lockfile +++ /dev/null @@ -1,82 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.21.0=spotbugs -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor -javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath -org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath -org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty=compileClasspath,runtimeClasspath diff --git a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityException.java b/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityException.java deleted file mode 100644 index dbc13832..00000000 --- a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityException.java +++ /dev/null @@ -1,44 +0,0 @@ -package dev.caskeleton.messaging.claimcheck; - -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.error.MessagingException; -import java.io.Serial; -import java.util.Optional; - -/** - * The stored payload does not match the reference the message carried. - * - *

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

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

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

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

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

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

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

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

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

Failures are classified rather than merged. An expired reference is an operational problem - * whose fix is a retention change; a digest mismatch means something wrote data nobody expected. - * Both dead-letter the message, but an operator seeing one code should not have to guess which - * happened. - */ -public final class ClaimCheckResolver { - - private final ClaimCheckStore store; - private final ClaimCheckIntegrityGuard guard = new ClaimCheckIntegrityGuard(); - - /** - * Creates a resolver. - * - * @param store the payload store - */ - public ClaimCheckResolver(ClaimCheckStore store) { - this.store = Objects.requireNonNull(store, "store must not be null"); - } - - /** - * Returns the payload a message carries, fetching it when it travels by reference. - * - * @param inline the payload bytes the message carried, empty when it travels by reference - * @param reference the claim check reference, when the message carried one - * @param now the current instant - * @return the payload the handler should see - * @throws ClaimCheckIntegrityException when the stored object is not the one referenced - * @throws MessageValidationException when the reference has expired - */ - public byte[] resolve(byte[] inline, Optional reference, Instant now) { - Objects.requireNonNull(inline, "inline must not be null"); - Objects.requireNonNull(reference, "reference must not be null"); - Objects.requireNonNull(now, "now must not be null"); - - if (reference.isEmpty()) { - return inline.clone(); - } - ClaimCheckReference claimCheck = reference.get(); - - if (claimCheck.isExpired(now)) { - // Checked before fetching. A store that still returns the object past its retention would - // otherwise hide a misconfiguration until the day the sweep caught up. - throw new MessageValidationException( - "CLAIM_CHECK_EXPIRED", - "the claim check retention expired at %s; the object may already be reaped" - .formatted(claimCheck.expiresAt())); - } - - return verify(claimCheck, fetch(claimCheck), now); - } - - private byte[] fetch(ClaimCheckReference reference) { - byte[] fetched = store.get(reference); - if (fetched == null) { - throw new MessageValidationException( - "CLAIM_CHECK_NOT_FOUND", - "no object exists at the referenced key; it was either reaped early or never written"); - } - return fetched; - } - - private byte[] verify(ClaimCheckReference reference, byte[] fetched, Instant now) { - try { - return guard.verify(reference, fetched, now); - } catch (MessageValidationException validation) { - // A size or digest mismatch is a poison message, not a validation failure to be retried: - // fetching the same key again returns the same wrong bytes. - if (validation.failure().code().endsWith("_MISMATCH")) { - throw new ClaimCheckIntegrityException( - validation.failure().code(), validation.failure().sanitizedMessage()); - } - throw validation; - } - } -} diff --git a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckStore.java b/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckStore.java deleted file mode 100644 index 4d10dfe6..00000000 --- a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckStore.java +++ /dev/null @@ -1,32 +0,0 @@ -package dev.caskeleton.messaging.claimcheck; - -import dev.caskeleton.messaging.reliability.ClaimCheckReference; -import java.time.Duration; - -/** Stores and retrieves payloads that are too large to travel through the broker. */ -public interface ClaimCheckStore { - - /** - * Stores a payload and returns its reference. - * - * @param payload the bytes to store - * @param retention how long the object must remain readable - * @return the reference to publish in place of the payload - */ - ClaimCheckReference put(byte[] payload, Duration retention); - - /** - * Fetches a payload, verifying it against its reference. - * - * @param reference the claim check reference - * @return the stored bytes - */ - byte[] get(ClaimCheckReference reference); - - /** - * Deletes a stored payload. - * - * @param reference the claim check reference - */ - void delete(ClaimCheckReference reference); -} diff --git a/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityGuardTest.java b/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityGuardTest.java deleted file mode 100644 index 71a66382..00000000 --- a/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityGuardTest.java +++ /dev/null @@ -1,86 +0,0 @@ -package dev.caskeleton.messaging.claimcheck; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatCode; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.error.MessageValidationException; -import dev.caskeleton.messaging.reliability.ClaimCheckReference; -import java.nio.charset.StandardCharsets; -import java.time.Instant; -import org.junit.jupiter.api.Test; - -class ClaimCheckIntegrityGuardTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - private static final byte[] PAYLOAD = "a large document".getBytes(StandardCharsets.UTF_8); - - private final ClaimCheckIntegrityGuard guard = new ClaimCheckIntegrityGuard(); - - @Test - void acceptsAPayloadMatchingItsReference() { - ClaimCheckReference reference = - reference(PAYLOAD.length, ClaimCheckIntegrityGuard.sha256(PAYLOAD)); - - assertThat(guard.verify(reference, PAYLOAD, NOW)).isEqualTo(PAYLOAD); - } - - @Test - void rejectsAPayloadWhoseDigestDoesNotMatch() { - ClaimCheckReference reference = - reference( - PAYLOAD.length, - ClaimCheckIntegrityGuard.sha256( - "a different document".getBytes(StandardCharsets.UTF_8))); - - assertThatThrownBy(() -> guard.verify(reference, PAYLOAD, NOW)) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("digest"); - } - - @Test - void rejectsATruncatedPayloadBeforeHashingIt() { - ClaimCheckReference reference = - reference(PAYLOAD.length + 10, ClaimCheckIntegrityGuard.sha256(PAYLOAD)); - - assertThatThrownBy(() -> guard.verify(reference, PAYLOAD, NOW)) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("bytes"); - } - - @Test - void rejectsAnExpiredReferenceBeforeTheFetchIsTrusted() { - ClaimCheckReference reference = - new ClaimCheckReference( - "payloads/o-1", - PAYLOAD.length, - ClaimCheckIntegrityGuard.sha256(PAYLOAD), - NOW.minusSeconds(1)); - - assertThatThrownBy(() -> guard.verify(reference, PAYLOAD, NOW)) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("retention"); - } - - @Test - void aReferenceRequiresALowercaseHexDigest() { - assertThatThrownBy( - () -> new ClaimCheckReference("payloads/o-1", 5, "NOT-A-DIGEST", NOW.plusSeconds(60))) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void theVerifiedPayloadIsACopy() { - ClaimCheckReference reference = - reference(PAYLOAD.length, ClaimCheckIntegrityGuard.sha256(PAYLOAD)); - - byte[] verified = guard.verify(reference, PAYLOAD, NOW); - verified[0] = 'z'; - - assertThatCode(() -> guard.verify(reference, PAYLOAD, NOW)).doesNotThrowAnyException(); - } - - private static ClaimCheckReference reference(long sizeBytes, String sha256) { - return new ClaimCheckReference("payloads/o-1", sizeBytes, sha256, NOW.plusSeconds(3600)); - } -} diff --git a/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckResolverTest.java b/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckResolverTest.java deleted file mode 100644 index 73e82044..00000000 --- a/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckResolverTest.java +++ /dev/null @@ -1,168 +0,0 @@ -package dev.caskeleton.messaging.claimcheck; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.error.MessageValidationException; -import dev.caskeleton.messaging.reliability.ClaimCheckReference; -import java.nio.charset.StandardCharsets; -import java.time.Duration; -import java.time.Instant; -import java.util.HashMap; -import java.util.Map; -import java.util.Optional; -import org.junit.jupiter.api.Test; - -class ClaimCheckResolverTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - private static final byte[] PAYLOAD = "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8); - - /** An in-memory store that can be made to return the wrong bytes on purpose. */ - private static final class FakeStore implements ClaimCheckStore { - - private final Map objects = new HashMap<>(); - private int puts; - - @Override - public ClaimCheckReference put(byte[] payload, Duration retention) { - puts++; - String key = "claim/" + puts; - objects.put(key, payload.clone()); - return new ClaimCheckReference( - key, payload.length, ClaimCheckIntegrityGuard.sha256(payload), NOW.plus(retention)); - } - - @Override - public byte[] get(ClaimCheckReference reference) { - return objects.get(reference.storageKey()); - } - - @Override - public void delete(ClaimCheckReference reference) { - objects.remove(reference.storageKey()); - } - - void overwrite(String key, byte[] replacement) { - objects.put(key, replacement); - } - - int puts() { - return puts; - } - } - - private static byte[] filled(int size) { - byte[] payload = new byte[size]; - java.util.Arrays.fill(payload, (byte) 'x'); - return payload; - } - - @Test - void aSmallPayloadTravelsInlineAndIsNeverStored() { - FakeStore store = new FakeStore(); - ClaimCheckPublisher publisher = new ClaimCheckPublisher(store, ClaimCheckPolicy.defaults()); - - ClaimCheckPublisher.Offloaded offloaded = publisher.offload(PAYLOAD); - - assertThat(offloaded.isOffloaded()).isFalse(); - assertThat(store.puts()).isZero(); - } - - @Test - void aLargePayloadIsStoredAndTheMessageCarriesNoBytes() { - FakeStore store = new FakeStore(); - ClaimCheckPublisher publisher = new ClaimCheckPublisher(store, ClaimCheckPolicy.defaults()); - - ClaimCheckPublisher.Offloaded offloaded = - publisher.offload(filled(ClaimCheckPolicy.DEFAULT_THRESHOLD_BYTES + 1)); - - assertThat(offloaded.isOffloaded()).isTrue(); - assertThat(offloaded.payload().length) - .as("carrying both would double the transfer and let the two disagree") - .isZero(); - } - - @Test - void anOffloadedPayloadRoundTripsThroughTheStore() { - FakeStore store = new FakeStore(); - ClaimCheckPolicy policy = - new ClaimCheckPolicy(8, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1)); - ClaimCheckPublisher.Offloaded offloaded = - new ClaimCheckPublisher(store, policy).offload(PAYLOAD); - - byte[] resolved = - new ClaimCheckResolver(store).resolve(offloaded.payload(), offloaded.reference(), NOW); - - assertThat(resolved).isEqualTo(PAYLOAD); - } - - @Test - void anInlinePayloadIsReturnedWithoutTouchingTheStore() { - FakeStore store = new FakeStore(); - - byte[] resolved = new ClaimCheckResolver(store).resolve(PAYLOAD, Optional.empty(), NOW); - - assertThat(resolved).isEqualTo(PAYLOAD); - } - - @Test - void anObjectThatWasSwappedUnderTheReferenceIsAPoisonMessage() { - FakeStore store = new FakeStore(); - ClaimCheckPolicy policy = - new ClaimCheckPolicy(8, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1)); - ClaimCheckPublisher.Offloaded offloaded = - new ClaimCheckPublisher(store, policy).offload(PAYLOAD); - store.overwrite( - offloaded.reference().orElseThrow().storageKey(), - "{\"orderId\":\"SOMEONE-ELSE\"}".getBytes(StandardCharsets.UTF_8)); - - assertThatThrownBy( - () -> - new ClaimCheckResolver(store) - .resolve(offloaded.payload(), offloaded.reference(), NOW)) - .as("the digest is the only thing between a swapped object and the wrong data") - .isInstanceOf(ClaimCheckIntegrityException.class); - } - - @Test - void anIntegrityFailureIsNotRetryableBecauseTheKeyReturnsTheSameBytes() { - ClaimCheckIntegrityException failure = - new ClaimCheckIntegrityException("CLAIM_CHECK_DIGEST_MISMATCH", "swapped"); - - assertThat(failure.failure().retryable()).isFalse(); - } - - @Test - void amissingObjectIsReportedSeparatelyFromASwappedOne() { - FakeStore store = new FakeStore(); - ClaimCheckPolicy policy = - new ClaimCheckPolicy(8, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1)); - ClaimCheckPublisher.Offloaded offloaded = - new ClaimCheckPublisher(store, policy).offload(PAYLOAD); - store.delete(offloaded.reference().orElseThrow()); - - assertThatThrownBy( - () -> - new ClaimCheckResolver(store) - .resolve(offloaded.payload(), offloaded.reference(), NOW)) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("never written"); - } - - @Test - void anExpiredReferenceIsRefusedBeforeTheStoreIsEvenAsked() { - FakeStore store = new FakeStore(); - ClaimCheckReference expired = - new ClaimCheckReference( - "claim/1", - PAYLOAD.length, - ClaimCheckIntegrityGuard.sha256(PAYLOAD), - NOW.minus(Duration.ofHours(1))); - - assertThatThrownBy( - () -> new ClaimCheckResolver(store).resolve(new byte[0], Optional.of(expired), NOW)) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("expired"); - } -} diff --git a/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckRetentionValidatorTest.java b/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckRetentionValidatorTest.java deleted file mode 100644 index 50fc16ac..00000000 --- a/src/platforms/messaging/messaging-claim-check/src/test/java/dev/caskeleton/messaging/claimcheck/ClaimCheckRetentionValidatorTest.java +++ /dev/null @@ -1,79 +0,0 @@ -package dev.caskeleton.messaging.claimcheck; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatCode; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.time.Duration; -import org.junit.jupiter.api.Test; - -class ClaimCheckRetentionValidatorTest { - - @Test - void retentionShorterThanTheMessageLifetimeIsRefused() { - assertThatThrownBy( - () -> - new ClaimCheckPolicy( - 1024, Duration.ofHours(6), Duration.ofDays(1), Duration.ofDays(1))) - .as("the object would be reaped while a consumer can still be handed its message") - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("reaped"); - } - - @Test - void retentionCoveringBrokerRetentionPlusTheRetryPathIsAccepted() { - assertThatCode( - () -> - new ClaimCheckPolicy( - 1024, Duration.ofDays(2), Duration.ofDays(1), Duration.ofDays(1))) - .doesNotThrowAnyException(); - } - - @Test - void theRequiredRetentionIsBrokerRetentionPlusTheRedeliveryWindow() { - ClaimCheckPolicy policy = - new ClaimCheckPolicy(1024, Duration.ofDays(5), Duration.ofDays(2), Duration.ofDays(1)); - - assertThat(policy.requiredRetention()).isEqualTo(Duration.ofDays(3)); - } - - @Test - void theDefaultsSatisfyTheirOwnRule() { - assertThatCode(ClaimCheckPolicy::defaults).doesNotThrowAnyException(); - } - - /** The portable payload limit the platform documents, restated here so the two cannot drift. */ - private static final int PORTABLE_PAYLOAD_LIMIT_BYTES = 1_048_576; - - @Test - void theOffloadThresholdSitsWellBelowThePortablePayloadLimit() { - assertThat(ClaimCheckPolicy.DEFAULT_THRESHOLD_BYTES) - .as( - "offloading starts where carrying inline stops being wise, not where the broker refuses") - .isLessThan(PORTABLE_PAYLOAD_LIMIT_BYTES); - } - - @Test - void aPayloadAtTheThresholdStillTravelsInline() { - ClaimCheckPolicy policy = ClaimCheckPolicy.defaults(); - - assertThat(policy.shouldOffload(ClaimCheckPolicy.DEFAULT_THRESHOLD_BYTES)).isFalse(); - assertThat(policy.shouldOffload(ClaimCheckPolicy.DEFAULT_THRESHOLD_BYTES + 1)).isTrue(); - } - - @Test - void aNonPositiveDurationIsRefused() { - assertThatThrownBy( - () -> new ClaimCheckPolicy(1024, Duration.ZERO, Duration.ofDays(1), Duration.ofDays(1))) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void aNonPositiveThresholdIsRefused() { - assertThatThrownBy( - () -> - new ClaimCheckPolicy(0, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1))) - .isInstanceOf(IllegalArgumentException.class); - } -} diff --git a/src/platforms/messaging/messaging-cloudevents/build.gradle b/src/platforms/messaging/messaging-cloudevents/build.gradle deleted file mode 100644 index 80f04d9c..00000000 --- a/src/platforms/messaging/messaging-cloudevents/build.gradle +++ /dev/null @@ -1,16 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') - - // api, because CloudEventMapper's public signatures return io.cloudevents.CloudEvent. - // - // Declared `implementation`, the type appeared in this module's public API while the - // dependency was hidden from consumers: an adopter calling the documented method could not - // name its return type without adding CloudEvents to their own build, and Gradle gave them no - // hint why. A type in a public signature is part of the artifact's contract. - api libs.cloudevents.api - implementation libs.cloudevents.core -} diff --git a/src/platforms/messaging/messaging-cloudevents/gradle.lockfile b/src/platforms/messaging/messaging-cloudevents/gradle.lockfile deleted file mode 100644 index de8dcaf3..00000000 --- a/src/platforms/messaging/messaging-cloudevents/gradle.lockfile +++ /dev/null @@ -1,84 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.21.0=spotbugs -info.picocli:picocli:4.7.7=checkstyle -io.cloudevents:cloudevents-api:4.0.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.cloudevents:cloudevents-core:4.0.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor -javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath -org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath -org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-cloudevents/src/main/java/dev/caskeleton/messaging/cloudevents/CloudEventExtensions.java b/src/platforms/messaging/messaging-cloudevents/src/main/java/dev/caskeleton/messaging/cloudevents/CloudEventExtensions.java deleted file mode 100644 index a0b5494e..00000000 --- a/src/platforms/messaging/messaging-cloudevents/src/main/java/dev/caskeleton/messaging/cloudevents/CloudEventExtensions.java +++ /dev/null @@ -1,24 +0,0 @@ -package dev.caskeleton.messaging.cloudevents; - -/** - * The CloudEvents extension attribute names this profile writes. - * - *

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

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

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

The last path or scheme-specific segment is used so that a long URI does not become an - * unbounded producer name, which would leak straight into metric tags. - */ - private static String producerFrom(URI source) { - String text = source.toString(); - int separator = Math.max(text.lastIndexOf('/'), text.lastIndexOf(':')); - String candidate = - separator >= 0 && separator + 1 < text.length() ? text.substring(separator + 1) : text; - return candidate.isBlank() ? "unknown" : candidate; - } -} diff --git a/src/platforms/messaging/messaging-cloudevents/src/test/java/dev/caskeleton/messaging/cloudevents/CloudEventMappingTest.java b/src/platforms/messaging/messaging-cloudevents/src/test/java/dev/caskeleton/messaging/cloudevents/CloudEventMappingTest.java deleted file mode 100644 index f82c6da6..00000000 --- a/src/platforms/messaging/messaging-cloudevents/src/test/java/dev/caskeleton/messaging/cloudevents/CloudEventMappingTest.java +++ /dev/null @@ -1,162 +0,0 @@ -package dev.caskeleton.messaging.cloudevents; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.CorrelationId; -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.ProducerId; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.TenantContext; -import dev.caskeleton.messaging.api.TraceContext; -import dev.caskeleton.messaging.api.error.MessageValidationException; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.schema.EncodedMessage; -import io.cloudevents.CloudEvent; -import java.net.URI; -import java.nio.charset.StandardCharsets; -import java.time.Instant; -import java.util.Optional; -import java.util.UUID; -import org.junit.jupiter.api.Test; - -class CloudEventMappingTest { - - private static final URI SOURCE = URI.create("urn:service:order-api"); - - private final DefaultCloudEventMapper mapper = new DefaultCloudEventMapper(); - - @Test - void mapsLogicalIdentityAndExtensions() { - MessageEnvelope envelope = CloudEventFixture.orderCreatedEnvelope(); - - CloudEvent event = mapper.toCloudEvent(envelope, SOURCE); - - assertThat(event.getId()).isEqualTo(envelope.messageId().value().toString()); - assertThat(event.getType()).isEqualTo("order.created"); - assertThat(event.getExtension(CloudEventExtensions.SCHEMA_VERSION)).isEqualTo("1"); - assertThat(event.getSource()).isEqualTo(SOURCE); - assertThat(event.getDataContentType()).isEqualTo("application/json"); - } - - @Test - void mapsCorrelationAndTenantAsExtensions() { - CloudEvent event = mapper.toCloudEvent(CloudEventFixture.orderCreatedEnvelope(), SOURCE); - - assertThat(event.getExtension(CloudEventExtensions.CORRELATION_ID)).isEqualTo("wf-1"); - assertThat(event.getExtension(CloudEventExtensions.TENANT_CONTEXT)).isEqualTo("acme"); - } - - @Test - void mapsOccurredAtToEventTime() { - CloudEvent event = mapper.toCloudEvent(CloudEventFixture.orderCreatedEnvelope(), SOURCE); - - assertThat(event.getTime()).isNotNull(); - assertThat(event.getTime().toInstant()).isEqualTo(Instant.parse("2026-08-10T09:15:00Z")); - } - - @Test - void rejectsAnEventEnvelopeWithoutOccurredAt() { - MessageEnvelope withoutOccurredAt = - CloudEventFixture.envelope(Optional.empty()); - - assertThatThrownBy(() -> mapper.toCloudEvent(withoutOccurredAt, SOURCE)) - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("occurredAt"); - } - - @Test - void roundTripsBackToAnEnvelopeWithoutInventingATombstone() { - MessageEnvelope original = CloudEventFixture.orderCreatedEnvelope(); - - MessageEnvelope restored = - mapper.fromCloudEvent(mapper.toCloudEvent(original, SOURCE)); - - assertThat(restored.messageId()).isEqualTo(original.messageId()); - assertThat(restored.messageType()).isEqualTo(original.messageType()); - assertThat(restored.schemaVersion()).isEqualTo(original.schemaVersion()); - assertThat(restored.correlationId()).contains(new CorrelationId("wf-1")); - assertThat(restored.tenantContext()).contains(new TenantContext("acme")); - assertThat(restored.payload().bytes()).isEqualTo(original.payload().bytes()); - } - - @Test - void aCloudEventWithNoDataBecomesAnEmptyPayloadNotANullValue() { - CloudEvent noData = - io.cloudevents.core.builder.CloudEventBuilder.v1() - // A v7 id: MessageId enforces the version it documents, so a v4 arriving from a foreign - // producer is refused here exactly as it would be on the wire. - .withId(dev.caskeleton.messaging.api.MessageId.newId().value().toString()) - .withSource(SOURCE) - .withType("order.created") - .withTime(java.time.OffsetDateTime.parse("2026-08-10T09:15:00Z")) - .withDataContentType("application/json") - .withExtension(CloudEventExtensions.SCHEMA_VERSION, "1") - .build(); - - MessageEnvelope restored = mapper.fromCloudEvent(noData); - - assertThat(restored.payload()).isNotNull(); - assertThat(restored.payload().size()).isZero(); - } - - @Test - void rejectsAnUnencodedPayload() { - MessageEnvelope unencoded = - new MessageEnvelope<>( - MessageId.newId(), - new MessageType("order.created"), - new SchemaVersion(1), - Instant.parse("2026-08-10T09:15:00Z"), - Optional.of(Instant.parse("2026-08-10T09:15:00Z")), - new ProducerId("order-api"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - "not encoded"); - - assertThatThrownBy(() -> mapper.toCloudEvent(unencoded, SOURCE)) - .isInstanceOf(MessageValidationException.class); - } -} - -/** Builds CloudEvents mapping fixtures. */ -final class CloudEventFixture { - - private static final MessageId FIXED_ID = - new MessageId(UUID.fromString("0190f4aa-0000-7000-8000-000000000001")); - - private CloudEventFixture() {} - - static MessageEnvelope orderCreatedEnvelope() { - return envelope(Optional.of(Instant.parse("2026-08-10T09:15:00Z"))); - } - - static MessageEnvelope envelope(Optional occurredAt) { - byte[] payload = "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8); - return new MessageEnvelope<>( - FIXED_ID, - new MessageType("order.created"), - new SchemaVersion(1), - Instant.parse("2026-08-10T09:15:01Z"), - occurredAt, - new ProducerId("order-api"), - Optional.of(new CorrelationId("wf-1")), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.of(new TenantContext("acme")), - TraceContext.none(), - MessageHeaders.empty(), - new EncodedMessage(payload, ContentType.JSON, Optional.empty())); - } -} diff --git a/src/platforms/messaging/messaging-core-api/build.gradle b/src/platforms/messaging/messaging-core-api/build.gradle deleted file mode 100644 index d202f8bf..00000000 --- a/src/platforms/messaging/messaging-core-api/build.gradle +++ /dev/null @@ -1,6 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { -} diff --git a/src/platforms/messaging/messaging-core-api/gradle.lockfile b/src/platforms/messaging/messaging-core-api/gradle.lockfile deleted file mode 100644 index d74807c4..00000000 --- a/src/platforms/messaging/messaging-core-api/gradle.lockfile +++ /dev/null @@ -1,82 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.21.0=spotbugs -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor -javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath -org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath -org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty=compileClasspath,runtimeClasspath diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/CausationId.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/CausationId.java deleted file mode 100644 index 40e64438..00000000 --- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/CausationId.java +++ /dev/null @@ -1,18 +0,0 @@ -package dev.caskeleton.messaging.api; - -import java.util.Objects; - -/** - * Identity of the message that directly caused this one. - * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Each codec used to serialize into an unbounded buffer and compare the finished length to the - * limit. That check reports an oversized payload; it does not prevent one. The difference only - * shows up for a payload whose serialized form is orders of magnitude larger than the bound, which - * is precisely the case that matters — the consumer is out of heap before the comparison runs. - */ -class BoundedByteSinkTest { - - private static final int MAX = 64; - - @Test - @DisplayName("one byte under, exactly at, and one byte over the limit") - void theLimitIsInclusiveAndTheNextByteIsRefused() { - assertThatCode(() -> fill(MAX - 1)).doesNotThrowAnyException(); - assertThatCode(() -> fill(MAX)).doesNotThrowAnyException(); - - assertThatThrownBy(() -> fill(MAX + 1)) - .isInstanceOf(MessageTooLargeException.class) - .hasMessageContaining("refused at byte 65"); - } - - @Test - @DisplayName("a much larger stream stops at the limit rather than after allocation") - void aMuchLargerStreamStopsAtTheLimit() { - BoundedByteSink sink = BoundedByteSink.of(MAX, "PAYLOAD_TOO_LARGE"); - - assertThatThrownBy( - () -> { - // Ten mebibytes offered one kibibyte at a time. A buffer-then-check codec would have - // held all of it; this refuses the chunk that crosses the bound. - for (int chunk = 0; chunk < 10_240; chunk++) { - sink.write(new byte[1_024], 0, 1_024); - } - }) - .isInstanceOf(MessageTooLargeException.class); - - assertThat(sink.written()) - .as("nothing beyond the bound was ever admitted") - .isLessThanOrEqualTo(MAX); - assertThat(sink.toByteArray()).isEmpty(); - } - - @Test - @DisplayName("a pre-flight size check does not consume the budget") - void aPreFlightCheckDoesNotConsumeTheBudget() { - BoundedByteSink sink = BoundedByteSink.of(MAX, "PAYLOAD_TOO_LARGE"); - - sink.requireFits(MAX); - - assertThat(sink.written()).isZero(); - assertThatCode(() -> sink.write(new byte[MAX], 0, MAX)).doesNotThrowAnyException(); - } - - @Test - @DisplayName("a pre-flight check refuses a size that cannot fit") - void aPreFlightCheckRefusesASizeThatCannotFit() { - BoundedByteSink sink = BoundedByteSink.of(MAX, "AVRO_PAYLOAD_TOO_LARGE"); - - assertThatThrownBy(() -> sink.requireFits(MAX + 1)) - .isInstanceOf(MessageTooLargeException.class) - .asInstanceOf( - org.assertj.core.api.InstanceOfAssertFactories.type(MessageTooLargeException.class)) - .extracting(failure -> failure.failure().code()) - .as("the sink reports the codec's own code, not a generic one") - .isEqualTo("AVRO_PAYLOAD_TOO_LARGE"); - } - - private static byte[] fill(int size) { - BoundedByteSink sink = BoundedByteSink.of(MAX, "PAYLOAD_TOO_LARGE"); - for (int index = 0; index < size; index++) { - sink.write('a'); - } - return sink.toByteArray(); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/RawBytesMessageCodecTest.java b/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/RawBytesMessageCodecTest.java deleted file mode 100644 index 69531deb..00000000 --- a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/RawBytesMessageCodecTest.java +++ /dev/null @@ -1,67 +0,0 @@ -package dev.caskeleton.messaging.schema; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageSerializationException; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import java.util.Optional; -import org.junit.jupiter.api.Test; - -class RawBytesMessageCodecTest { - - private static final MessageType OPAQUE = new MessageType("opaque.blob"); - private static final SchemaVersion V1 = new SchemaVersion(1); - - private final RawBytesMessageCodec codec = new RawBytesMessageCodec(); - - @Test - void roundTripsOpaqueBytes() { - byte[] payload = {1, 2, 3, 4}; - - EncodedMessage encoded = codec.encode(OPAQUE, V1, payload); - - assertThat(codec.decode(OPAQUE, V1, encoded.bytes(), byte[].class)).containsExactly(1, 2, 3, 4); - } - - @Test - void advertisesOpaqueContentTypeAndNoSchemaReference() { - EncodedMessage encoded = codec.encode(OPAQUE, V1, new byte[] {9}); - - assertThat(codec.contentType()).isEqualTo(ContentType.OCTET_STREAM); - assertThat(encoded.schemaReference()).isEmpty(); - } - - @Test - void refusesNonByteArrayPayloads() { - assertThatThrownBy(() -> codec.encode(OPAQUE, V1, "text")) - .isInstanceOf(MessageSerializationException.class); - } - - @Test - void refusesDecodingToAnythingButByteArray() { - assertThatThrownBy(() -> codec.decode(OPAQUE, V1, new byte[] {1}, String.class)) - .isInstanceOf(MessageSerializationException.class); - } - - @Test - void enforcesTheByteLimit() { - RawBytesMessageCodec small = new RawBytesMessageCodec(4); - - assertThatThrownBy(() -> small.encode(OPAQUE, V1, new byte[5])) - .isInstanceOf(MessageTooLargeException.class); - } - - @Test - void encodedMessageDefensivelyCopiesItsBytes() { - byte[] source = {1, 2, 3}; - EncodedMessage encoded = new EncodedMessage(source, ContentType.OCTET_STREAM, Optional.empty()); - - source[0] = 99; - - assertThat(encoded.bytes()).containsExactly(1, 2, 3); - } -} diff --git a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidatorTest.java b/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidatorTest.java deleted file mode 100644 index 7976c059..00000000 --- a/src/platforms/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidatorTest.java +++ /dev/null @@ -1,109 +0,0 @@ -package dev.caskeleton.messaging.schema; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatCode; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageSchemaIncompatibleException; -import java.util.List; -import java.util.Optional; -import org.junit.jupiter.api.Test; - -class SchemaCompatibilityValidatorTest { - - private static final SchemaVersion V1 = new SchemaVersion(1); - private static final SchemaVersion V2 = new SchemaVersion(2); - private static final SchemaVersion V3 = new SchemaVersion(3); - - /** A registry whose history is deliberately oldest-first, as the port documents. */ - private record FixedRegistry(List versions, SchemaCompatibility mode) - implements SchemaRegistry { - - @Override - public Optional lookup(String subject, SchemaVersion version) { - return versions.contains(version) ? Optional.of("{}") : Optional.empty(); - } - - @Override - public List history(String subject) { - return versions; - } - - @Override - public SchemaCompatibility compatibilityOf(String subject) { - return mode; - } - } - - private static SchemaCompatibilityValidator validator(SchemaCompatibility mode) { - return new SchemaCompatibilityValidator(new FixedRegistry(List.of(V1, V2, V3), mode)); - } - - @Test - void aPairwiseModeChecksOnlyTheImmediatePredecessor() { - assertThat(validator(SchemaCompatibility.BACKWARD).versionsToCheck("order.created")) - .containsExactly(V3); - } - - @Test - void aTransitiveModeChecksTheWholeHistoryNewestFirst() { - assertThat(validator(SchemaCompatibility.BACKWARD_TRANSITIVE).versionsToCheck("order.created")) - .as( - "a chain of individually compatible changes can still break a consumer several releases behind") - .containsExactly(V3, V2, V1); - } - - @Test - void anUncheckedModeComparesAgainstNothing() { - assertThat(validator(SchemaCompatibility.NONE_EXPERIMENTAL).versionsToCheck("order.created")) - .isEmpty(); - } - - @Test - void anEmptyHistoryHasNothingToCompareAgainst() { - SchemaCompatibilityValidator validator = - new SchemaCompatibilityValidator( - new FixedRegistry(List.of(), SchemaCompatibility.FULL_TRANSITIVE)); - - assertThat(validator.versionsToCheck("order.created")).isEmpty(); - } - - @Test - void anUncheckedSubjectCannotBackAProductionDestination() { - assertThatThrownBy( - () -> - validator(SchemaCompatibility.NONE_EXPERIMENTAL) - .requireProductionMode("order.created", "orders.v1")) - .isInstanceOf(MessageSchemaIncompatibleException.class) - .hasMessageContaining("orders.v1"); - } - - @Test - void aCheckedSubjectMayBackAProductionDestination() { - assertThatCode( - () -> - validator(SchemaCompatibility.FULL) - .requireProductionMode("order.created", "orders.v1")) - .doesNotThrowAnyException(); - } - - @Test - void fullModeEnforcesBothDirections() { - assertThat(SchemaCompatibilityValidator.checksBackward(SchemaCompatibility.FULL)).isTrue(); - assertThat(SchemaCompatibilityValidator.checksForward(SchemaCompatibility.FULL)).isTrue(); - } - - @Test - void eachOneDirectionalModeEnforcesOnlyItsOwnDirection() { - assertThat(SchemaCompatibilityValidator.checksForward(SchemaCompatibility.BACKWARD)).isFalse(); - assertThat(SchemaCompatibilityValidator.checksBackward(SchemaCompatibility.FORWARD)).isFalse(); - } - - @Test - void theLatestVersionIsTheNewestNotTheFirstListed() { - SchemaRegistry registry = new FixedRegistry(List.of(V1, V2, V3), SchemaCompatibility.FULL); - - assertThat(registry.latest("order.created")).hasValue(V3); - } -} diff --git a/src/platforms/messaging/messaging-kafka/build.gradle b/src/platforms/messaging/messaging-kafka/build.gradle deleted file mode 100644 index 620f1090..00000000 --- a/src/platforms/messaging/messaging-kafka/build.gradle +++ /dev/null @@ -1,119 +0,0 @@ -plugins { - id 'java-test-fixtures' - id 'ca.platform-module' - id 'me.champeau.jmh' -} - -jmh { - jmhVersion = libs.versions.jmh.get() - includeTests = true -} - -testing { - suites { - integrationTest(JvmTestSuite) { - dependencies { - implementation project() - implementation testFixtures(project()) - } - } - } -} -configurations { - integrationTestImplementation.extendsFrom testImplementation - integrationTestRuntimeOnly.extendsFrom testRuntimeOnly -} - -dependencies { - // No spring-kafka. It was declared here and imported by nothing: this adapter drives the plain - // `org.apache.kafka` producer API directly, and a declared library that no source names is a - // resolution, a lock entry and a transitive surface bought for nothing. - api project(':messaging:messaging-core-api') - api project(':messaging:messaging-policy') - api project(':messaging:messaging-transport-spi') - api project(':messaging:messaging-observability') - api project(':messaging:messaging-security') - api project(':messaging:messaging-admin') - - // api: the public constructors and mappers take and return Producer, ProducerRecord and - // RecordMetadata. Hiding the dependency does not hide the types — it only stops a consumer - // from compiling against the API this module documents. - api 'org.apache.kafka:kafka-clients' - - // Test-only. The shared adapter contract is what makes "Stable" mean something, so the Kafka - // adapter runs it rather than asserting its own behaviour in its own terms. - testImplementation project(':messaging:messaging-testkit') - testFixturesImplementation project(':messaging:messaging-testkit') - - // Live-broker certification. The deterministic suite proves the platform's semantics; these - // prove the client actually behaves that way against the version the matrix claims. - integrationTestImplementation 'org.testcontainers:testcontainers-junit-jupiter' - integrationTestImplementation 'org.testcontainers:testcontainers-kafka' - integrationTestImplementation 'org.testcontainers:testcontainers-toxiproxy' - integrationTestImplementation libs.toxiproxy.java -} - -// The certification lane, and the gate that makes its output the only source of a Stable claim. -// -// `CertifiedEvidence` used to be a hand-written list of three scenarios, and every consumer of it — -// the compatibility matrix, the cross-broker release suite, the support matrix document — believed -// it without a container ever starting. The lane below produces that list, and -// `verifyMessagingCertificationEvidence` refuses to pass when the committed manifest claims a -// scenario this run did not prove. Editing the manifest by hand therefore fails the build; running -// the lane rewrites it. -strictTestLanes { - lane('messagingCertificationTest') { - integration() - sourceSet = 'integrationTest' - description = 'Runs the broker fault scenarios against a real Kafka and writes the ' + - 'certification evidence the compatibility matrix reads.' - // Pinned images. A certification claim names the build it was made against, so a - // floating tag would make a red run unattributable and a green one unrepeatable. - // `-PmessagingKafkaImage=` overrides for a one-off run against another version. - systemProperty 'messaging.kafka.image', - (project.findProperty('messagingKafkaImage') ?: testContainerImages['kafka']).toString() - systemProperty 'messaging.toxiproxy.image', - (project.findProperty('messagingToxiproxyImage') - ?: testContainerImages['toxiproxy']).toString() - systemProperty 'messaging.certification.manifest', - project.layout.buildDirectory - .file('messaging-certification/broker-certification-evidence.jsonl') - .get().asFile.absolutePath - // The commit is provenance recorded in the evidence, not an equality key for the - // behavioral claim gate. Re-running the same scenario on a later commit refreshes - // provenance without creating a different scenario identity. - // Read from the environment rather than a `-P` flag so the CI job's command line stays - // the literal grammar the gate matrix lint accepts. - systemProperty 'messaging.certification.commit', - (project.findProperty('certificationCommit') - ?: providers.environmentVariable('GITHUB_SHA').getOrElse('local')) - .toString() - } -} - -// The certification lane writes the scenarios it proved; the committed manifest in messaging-testkit -// may claim no more and no fewer. gitCommit and observedAt are provenance, not claim identity. -tasks.register('verifyMessagingCertificationEvidence') { - group = 'verification' - description = 'Fails when the committed broker certification manifest claims a scenario the certification lane did not produce.' - dependsOn 'messagingCertificationTest' - def produced = layout.buildDirectory.file('messaging-certification/broker-certification-evidence.jsonl') - def committed = rootProject.file('platforms/messaging/messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl') - inputs.file(produced) - inputs.file(committed) - doLast { - def claims = { File file -> - file.readLines('UTF-8').findAll { !it.trim().isEmpty() }.collect { - it.replaceAll(/,"gitCommit":"[^"]*"/, '').replaceAll(/,"observedAt":"[^"]*"/, '') - } as Set - } - def ran = claims(produced.get().asFile) - def shipped = claims(committed) - if (ran != shipped) { - throw new GradleException("the committed certification manifest does not match this run.\n" + - " claimed but not produced: ${shipped - ran}\n produced but not claimed: ${ran - shipped}\n" + - "Copy ${produced.get().asFile} over ${committed} — the manifest is a record of a run.") - } - } -} - diff --git a/src/platforms/messaging/messaging-kafka/gradle.lockfile b/src/platforms/messaging/messaging-kafka/gradle.lockfile deleted file mode 100644 index 88743033..00000000 --- a/src/platforms/messaging/messaging-kafka/gradle.lockfile +++ /dev/null @@ -1,113 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -at.yawk.lz4:lz4-java:1.11.4=integrationTestRuntimeClasspath,jmhRuntimeClasspath,runtimeClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -com.fasterxml.jackson.core:jackson-annotations:2.21=integrationTestCompileClasspath,integrationTestRuntimeClasspath -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -com.github.docker-java:docker-java-api:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath -com.github.docker-java:docker-java-transport-zerodep:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath -com.github.docker-java:docker-java-transport:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -com.github.luben:zstd-jni:1.5.6-10=integrationTestRuntimeClasspath,jmhRuntimeClasspath,runtimeClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-codec:commons-codec:1.19.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.20.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath -commons-io:commons-io:2.21.0=spotbugs -eu.rekawek.toxiproxy:toxiproxy-java:2.1.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -io.micrometer:micrometer-commons:1.16.8=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -io.micrometer:micrometer-core:1.16.8=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -io.micrometer:micrometer-observation:1.16.8=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -javax.inject:javax.inject:1=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -net.java.dev.jna:jna:5.18.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath -net.sf.jopt-simple:jopt-simple:5.0.4=jmh,jmhCompileClasspath,jmhRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-compress:1.28.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.apache.commons:commons-lang3:3.20.0=checkstyle,integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs -org.apache.commons:commons-math3:3.6.1=jmh,jmhCompileClasspath,jmhRuntimeClasspath -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.kafka:kafka-clients:4.1.2=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=integrationTestCompileClasspath,testCompileClasspath,testFixturesCompileClasspath -org.assertj:assertj-core:3.27.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.hdrhistogram:HdrHistogram:2.2.2=integrationTestRuntimeClasspath,jmhRuntimeClasspath,runtimeClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -org.javassist:javassist:3.28.0-GA=checkstyle -org.jetbrains:annotations:17.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,integrationTestAnnotationProcessor,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhAnnotationProcessor,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testFixturesAnnotationProcessor,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=integrationTestRuntimeClasspath,jmhRuntimeClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=integrationTestRuntimeClasspath,jmhRuntimeClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=integrationTestRuntimeClasspath,jmhRuntimeClasspath,testRuntimeClasspath -org.junit:junit-bom:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.latencyutils:LatencyUtils:2.0.3=integrationTestRuntimeClasspath,jmhRuntimeClasspath,runtimeClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -org.mockito:mockito-core:5.20.0=mockitoAgent -org.openjdk.jmh:jmh-core:1.37=jmh,jmhCompileClasspath,jmhRuntimeClasspath -org.openjdk.jmh:jmh-generator-asm:1.37=jmh,jmhCompileClasspath,jmhRuntimeClasspath -org.openjdk.jmh:jmh-generator-bytecode:1.37=jmh,jmhCompileClasspath,jmhRuntimeClasspath -org.openjdk.jmh:jmh-generator-reflection:1.37=jmh,jmhCompileClasspath,jmhRuntimeClasspath -org.opentest4j:opentest4j:1.3.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.0=jmh,jmhCompileClasspath,jmhRuntimeClasspath -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.rnorth.duct-tape:duct-tape:1.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.slf4j:slf4j-api:2.0.20=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,runtimeClasspath,spotbugs,spotbugsSlf4j,testFixturesRuntimeClasspath,testRuntimeClasspath -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.testcontainers:testcontainers-junit-jupiter:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-kafka:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-toxiproxy:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.xerial.snappy:snappy-java:1.1.10.9=integrationTestRuntimeClasspath,jmhRuntimeClasspath,runtimeClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaAmbiguityChaosIT.java b/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaAmbiguityChaosIT.java deleted file mode 100644 index e2787738..00000000 --- a/src/platforms/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaAmbiguityChaosIT.java +++ /dev/null @@ -1,175 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.ProducerId; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.TraceContext; -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.api.publish.ConfirmationLevel; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.api.publish.TransmissionEvidence; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.testkit.DockerAvailability; -import dev.caskeleton.messaging.transport.TransportPublishRequest; -import java.nio.charset.StandardCharsets; -import java.time.Instant; -import java.util.Optional; -import java.util.Properties; -import org.apache.kafka.clients.producer.KafkaProducer; -import org.apache.kafka.clients.producer.Producer; -import org.apache.kafka.clients.producer.ProducerConfig; -import org.apache.kafka.common.serialization.ByteArraySerializer; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.condition.EnabledIf; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; -import org.testcontainers.kafka.KafkaContainer; - -/** - * Proves the platform's hardest guarantee against a live broker: a lost confirmation is reported, - * not guessed. - * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

What is measured is what the adapter does on the calling thread: header mapping, payload - * framing, and the offset bookkeeping that runs per settlement. Those are the costs that scale with - * message rate and that a change to this module can regress. - */ -@BenchmarkMode(Mode.AverageTime) -@OutputTimeUnit(TimeUnit.NANOSECONDS) -@Warmup(iterations = 3, time = 1) -@Measurement(iterations = 5, time = 1) -@Fork(1) -@State(Scope.Benchmark) -public class KafkaPublishBenchmark { - - /** Payload sizes spanning the range a portable destination allows. */ - @Param({"256", "4096", "65536"}) - public int payloadBytes; - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - private static final TopicPartition PARTITION = new TopicPartition("orders.v1", 0); - - private KafkaHeaderMapper headerMapper; - private KafkaPublishFailureClassifier classifier; - private MessageEnvelope envelope; - private ContiguousPartitionOffsetTracker tracker; - - /** Builds the fixtures once so the measured methods allocate only what a publish allocates. */ - @Setup(Level.Trial) - public void setUp() { - headerMapper = new KafkaHeaderMapper(); - classifier = new KafkaPublishFailureClassifier(); - byte[] payload = new byte[payloadBytes]; - java.util.Arrays.fill(payload, (byte) 'x'); - envelope = - new MessageEnvelope<>( - MessageId.newId(), - new MessageType("order.created"), - new SchemaVersion(1), - NOW, - Optional.of(NOW), - new ProducerId("order-api"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - new EncodedMessage(payload, ContentType.JSON, Optional.empty())); - } - - /** Resets the offset tracker per iteration so its cost does not drift with accumulated state. */ - @Setup(Level.Iteration) - public void resetTracker() { - tracker = new ContiguousPartitionOffsetTracker(); - } - - /** - * Measures mapping an envelope's reserved headers onto Kafka headers. - * - * @param blackhole consumes the result - */ - @Benchmark - public void mapHeaders(Blackhole blackhole) { - blackhole.consume(headerMapper.toKafkaHeaders(envelope)); - } - - /** - * Measures classifying a producer timeout, which runs on every ambiguous publish. - * - * @param blackhole consumes the result - */ - @Benchmark - public void classifyTimeout(Blackhole blackhole) { - blackhole.consume( - classifier.classify( - new org.apache.kafka.common.errors.TimeoutException("expired"), Duration.ofMillis(5))); - } - - /** - * Measures the contiguous-offset bookkeeping that runs on every settlement. - * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Identity travels in headers rather than inside the payload so that a consumer can classify, - * route, and dead letter a message it cannot deserialize. A poison payload still has a readable - * {@code msg.id} and {@code msg.type}, which is what makes parking it actionable instead of opaque. - */ -public final class KafkaHeaderMapper { - - /** - * Writes the envelope's reserved and application headers. - * - * @param envelope the envelope being published - * @return Kafka headers - */ - public Headers toKafkaHeaders(MessageEnvelope envelope) { - Objects.requireNonNull(envelope, "envelope must not be null"); - Headers headers = new RecordHeaders(); - - put(headers, ReservedHeaders.MESSAGE_ID, envelope.messageId().value().toString()); - put(headers, ReservedHeaders.MESSAGE_TYPE, envelope.messageType().value()); - put( - headers, - ReservedHeaders.SCHEMA_VERSION, - Integer.toString(envelope.schemaVersion().value())); - put(headers, ReservedHeaders.PRODUCER, envelope.producer().value()); - put(headers, ReservedHeaders.PRODUCED_AT, envelope.producedAt().toString()); - put(headers, ReservedHeaders.CONTENT_TYPE, envelope.contentType().value()); - - envelope - .occurredAt() - .ifPresent(value -> put(headers, ReservedHeaders.OCCURRED_AT, value.toString())); - envelope - .correlationId() - .ifPresent(value -> put(headers, ReservedHeaders.CORRELATION_ID, value.value())); - envelope - .causationId() - .ifPresent( - value -> put(headers, ReservedHeaders.CAUSATION_ID, value.value().value().toString())); - envelope.partitionKey().ifPresent(value -> put(headers, ReservedHeaders.PARTITION_KEY, value)); - envelope.orderingKey().ifPresent(value -> put(headers, ReservedHeaders.ORDERING_KEY, value)); - // Written because the consumer has no other way to learn it: a broker record carries no - // ambient tenant, so a tenant left off the wire is a tenant the consumed envelope does not - // have — and every authorization and partitioning decision downstream reads that field. - envelope - .tenantContext() - .ifPresent(value -> put(headers, ReservedHeaders.TENANT, value.tenantId())); - envelope - .traceContext() - .traceparent() - .ifPresent(value -> put(headers, ReservedHeaders.TRACEPARENT, value)); - envelope - .traceContext() - .tracestate() - .ifPresent(value -> put(headers, ReservedHeaders.TRACESTATE, value)); - envelope - .traceContext() - .baggage() - .ifPresent(value -> put(headers, ReservedHeaders.BAGGAGE, value)); - - // The envelope's own header map is written last and the consumer reads `lastHeader`, so a name - // written here wins over the canonical value above. A row in the outbox carrying `msg.id` - // therefore overwrote the identity that inbox deduplication and the audit trail key on, - // corrupting a different message's dedup state rather than merely its own. - // - // Only names that restate an envelope field are refused. Retry attempt, failure and redrive - // bookkeeping have no envelope field to be read back from, so refusing them would make every - // retry-topic and dead-letter re-publish fail on the guard meant to protect identity. - envelope - .headers() - .asMap() - .forEach( - (name, value) -> { - if (CanonicalEnvelopeHeaders.restatesEnvelopeField(name.value())) { - throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException( - "RESERVED_HEADER_FORGED", - "header '" - + name.value() - + "' restates a value the envelope already carries; the canonical value is" - + " written by the platform and must not be overridable by message content"); - } - put(headers, name.value(), value.value()); - }); - - return headers; - } - - /** - * Reads Kafka headers back into a platform header map. - * - * @param headers the record headers - * @return the platform headers, including reserved names - */ - public MessageHeaders fromKafkaHeaders(Headers headers) { - Objects.requireNonNull(headers, "headers must not be null"); - Map values = new LinkedHashMap<>(); - for (Header header : headers) { - byte[] value = header.value(); - values.put( - new HeaderName(header.key()), - new HeaderValue(value == null ? "" : new String(value, StandardCharsets.UTF_8))); - } - return MessageHeaders.platform(values); - } - - /** - * Reads back the headers a rebuilt envelope keeps. - * - *

Everything except the names that were hoisted into envelope fields: the application's own - * headers, which were dropped entirely and so never survived a broker hop, and the platform's - * retry and redrive bookkeeping, whose loss restarted the attempt counter at one on every - * redelivery and left the retry budget capping nothing. - * - *

The hoisted names are excluded rather than kept alongside their fields, because a duplicate - * that can drift from the field is how the same message ends up with two different ids depending - * on which one the reader trusts. - * - * @param headers the record headers - * @return the headers to carry on the rebuilt envelope - */ - public MessageHeaders carriedForward(Headers headers) { - Objects.requireNonNull(headers, "headers must not be null"); - Map values = new LinkedHashMap<>(); - for (Header header : headers) { - if (CanonicalEnvelopeHeaders.restatesEnvelopeField(header.key())) { - continue; - } - byte[] value = header.value(); - values.put( - new HeaderName(header.key()), - new HeaderValue(value == null ? "" : new String(value, StandardCharsets.UTF_8))); - } - return MessageHeaders.platform(values); - } - - /** - * Reads one header value. - * - * @param headers the record headers - * @param name the header name - * @return the value, or null when absent - */ - public String value(Headers headers, String name) { - Header header = headers.lastHeader(name); - return header == null || header.value() == null - ? null - : new String(header.value(), StandardCharsets.UTF_8); - } - - private static void put(Headers headers, String name, String value) { - headers.add(name, value.getBytes(StandardCharsets.UTF_8)); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransport.java b/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransport.java deleted file mode 100644 index ce84b544..00000000 --- a/src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransport.java +++ /dev/null @@ -1,212 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.destination.DestinationCapabilities; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessagingCapabilities; -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.error.MessagingCapabilityUnavailableException; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.transport.MessagingTransport; -import dev.caskeleton.messaging.transport.TransportConsumerRegistration; -import dev.caskeleton.messaging.transport.TransportConsumerSpec; -import dev.caskeleton.messaging.transport.TransportPublishRequest; -import dev.caskeleton.messaging.transport.TransportPublishResult; -import java.time.Duration; -import java.util.Objects; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import java.util.concurrent.atomic.AtomicBoolean; -import java.util.function.Function; -import org.apache.kafka.clients.producer.Producer; -import org.apache.kafka.clients.producer.ProducerRecord; - -/** - * The Stable Kafka adapter. - * - *

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

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

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

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

Delayed delivery is absent too: Kafka has no broker-side schedule. - */ - private static final MessagingCapabilities CAPABILITIES = - MessagingCapabilities.of(MessagingCapabilities.Capability.ORDERED_STREAM); - - private final String brokerName; - private final long generation; - private final Producer producer; - private final KafkaPublishMapper mapper; - private final KafkaPublishFailureClassifier failures; - private final Function consumerFactory; - private final AtomicBoolean closed = new AtomicBoolean(); - - /** - * Creates a publish-only transport. - * - * @param brokerName the logical broker name - * @param generation the runtime generation - * @param producer the Kafka producer - */ - public KafkaMessagingTransport( - String brokerName, long generation, Producer producer) { - this( - brokerName, - generation, - producer, - spec -> { - throw new MessagingCapabilityUnavailableException( - "KAFKA_CONSUMER_NOT_CONFIGURED", - "this Kafka transport was created without a consumer factory"); - }); - } - - /** - * Creates a transport with a consumer factory. - * - * @param brokerName the logical broker name - * @param generation the runtime generation - * @param producer the Kafka producer - * @param consumerFactory builds a consumer registration for a spec - */ - public KafkaMessagingTransport( - String brokerName, - long generation, - Producer producer, - Function consumerFactory) { - this.brokerName = Objects.requireNonNull(brokerName, "brokerName must not be null"); - this.generation = generation; - this.producer = Objects.requireNonNull(producer, "producer must not be null"); - this.consumerFactory = Objects.requireNonNull(consumerFactory, "consumerFactory is required"); - this.mapper = new KafkaPublishMapper(); - this.failures = new KafkaPublishFailureClassifier(); - } - - /** - * {@inheritDoc} - * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{@code MessageHeaders.application} already refuses reserved names, so business code could - * never forge one. The gap was the platform factory: {@code OutboxEnvelopeFactory} promoted a - * row's arbitrary {@code Map} straight through it, and the mapper then appended - * the result after the canonical headers. - */ - private static MessageEnvelope envelopeWithHeader(String name, String value) { - return envelope(MessageHeaders.platform(Map.of(new HeaderName(name), new HeaderValue(value)))); - } - - private static MessageEnvelope envelopeWithPlatformHeader( - String name, String value) { - return envelope(MessageHeaders.platform(Map.of(new HeaderName(name), new HeaderValue(value)))); - } - - private static MessageEnvelope envelope(MessageHeaders headers) { - return new MessageEnvelope<>( - MessageId.newId(), - new MessageType("order.created"), - new SchemaVersion(1), - Instant.parse("2026-08-15T00:00:00Z"), - Optional.empty(), - new ProducerId("orders"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.empty(), - TraceContext.none(), - headers, - new EncodedMessage( - "{}".getBytes(StandardCharsets.UTF_8), ContentType.JSON, Optional.empty())); - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/testFixtures/java/dev/caskeleton/messaging/kafka/KafkaContractHarness.java b/src/platforms/messaging/messaging-kafka/src/testFixtures/java/dev/caskeleton/messaging/kafka/KafkaContractHarness.java deleted file mode 100644 index 7d056699..00000000 --- a/src/platforms/messaging/messaging-kafka/src/testFixtures/java/dev/caskeleton/messaging/kafka/KafkaContractHarness.java +++ /dev/null @@ -1,370 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.delivery.DeliveryContext; -import dev.caskeleton.messaging.api.delivery.DeliveryGuarantee; -import dev.caskeleton.messaging.api.delivery.DeliveryMetadata; -import dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.delivery.OrderingScope; -import dev.caskeleton.messaging.api.destination.DestinationKind; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.publish.ConfirmationLevel; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishEvidence; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.api.publish.RoutingOutcome; -import dev.caskeleton.messaging.policy.ApiTier; -import dev.caskeleton.messaging.policy.ConsumerPolicy; -import dev.caskeleton.messaging.policy.DeadLetterOrchestrator; -import dev.caskeleton.messaging.policy.DeadLetterPolicy; -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.policy.PayloadPolicy; -import dev.caskeleton.messaging.policy.PhysicalDestination; -import dev.caskeleton.messaging.policy.ProducerPolicy; -import dev.caskeleton.messaging.policy.RetryPolicy; -import dev.caskeleton.messaging.policy.SchemaPolicy; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.schema.SchemaCompatibility; -import dev.caskeleton.messaging.testkit.ContractMessage; -import dev.caskeleton.messaging.testkit.FaultController; -import dev.caskeleton.messaging.testkit.HandleOutcome; -import dev.caskeleton.messaging.testkit.MessagingAdapterHarness; -import dev.caskeleton.messaging.testkit.ObservedDelivery; -import dev.caskeleton.messaging.transport.TransportPublishRequest; -import java.time.Duration; -import java.time.Instant; -import java.util.ArrayDeque; -import java.util.ArrayList; -import java.util.Deque; -import java.util.LinkedHashSet; -import java.util.List; -import java.util.Optional; -import java.util.Set; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import org.apache.kafka.clients.producer.MockProducer; -import org.apache.kafka.clients.producer.Partitioner; -import org.apache.kafka.common.serialization.ByteArraySerializer; - -/** - * Runs the shared adapter contract against the real Kafka publish path. - * - *

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

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

Manual completion is what lets the harness lose a confirmation on demand. The empty cluster - * means {@code MockProducer} assigns partition zero without consulting a partitioner, which is - * why a null partitioner is safe here — the contract never asserts on partitioning. - */ - private final MockProducer producer = - new MockProducer<>( - false, (Partitioner) null, new ByteArraySerializer(), new ByteArraySerializer()); - - private final KafkaMessagingTransport transport = - new KafkaMessagingTransport("kafka-primary", 1, producer); - private final Faults faults = new Faults(); - private final Deque pending = new ArrayDeque<>(); - private final List deadLetters = new ArrayList<>(); - private final Set unsettled = new LinkedHashSet<>(); - private final DeadLetterOrchestrator orchestrator = - new DeadLetterOrchestrator(new HarnessDeadLetterPublisher()); - - private boolean shuttingDown; - - static KafkaContractHarness create() { - return new KafkaContractHarness(); - } - - @Override - public String brokerName() { - return transport.brokerName(); - } - - @Override - public FaultController faults() { - return faults; - } - - @Override - public CompletionStage publish(ContractMessage message) { - CompletionStage stage = - transport - .publish( - new TransportPublishRequest( - profile(), message.envelope(), PublishOptions.defaults())) - .thenApply(result -> result.result()); - - if (faults.consumeRejectPublish()) { - // An invalid topic is definitive: the classifier must report REJECTED, not AMBIGUOUS. - producer.errorNext(new org.apache.kafka.common.errors.InvalidTopicException("no such topic")); - } else if (faults.consumeDropPublishConfirmation()) { - // A delivery timeout proves nothing about what the broker did with the record. - producer.errorNext(new org.apache.kafka.common.errors.TimeoutException("confirm lost")); - } else { - producer.completeNext(); - } - - return stage.thenApply( - result -> { - if (result.completion() == PublishCompletion.CONFIRMED) { - pending.addLast(new Pending(message.messageId(), message.envelope(), 1, false)); - } - return result; - }); - } - - @Override - public List drain(HandleOutcome outcome) { - List batch = new ArrayList<>(pending); - pending.clear(); - - List observed = new ArrayList<>(); - for (Pending delivery : batch) { - boolean settled = - switch (outcome) { - case SUCCESS -> settleAfterSuccess(delivery); - case RETRY -> { - unsettled.add(delivery.messageId()); - redeliver(delivery); - yield false; - } - case DEAD_LETTER -> deadLetter(delivery); - }; - observed.add( - new ObservedDelivery( - delivery.messageId(), delivery.attempt(), delivery.redelivered(), settled)); - } - return List.copyOf(observed); - } - - private boolean settleAfterSuccess(Pending delivery) { - if (faults.consumeDropSettlementConfirmation()) { - unsettled.add(delivery.messageId()); - redeliver(delivery); - return false; - } - unsettled.remove(delivery.messageId()); - return true; - } - - /** - * Routes through the production orchestrator so the publish-then-settle order is the real one. - */ - private boolean deadLetter(Pending delivery) { - boolean[] settled = {false}; - orchestrator - .deadLetter( - profile(), - toDelivery(delivery), - FailureDescriptor.of( - FailureCategory.PERMANENT_BUSINESS, "CONTRACT_FAILURE", "permanent failure"), - () -> { - settled[0] = true; - unsettled.remove(delivery.messageId()); - return CompletableFuture.completedFuture(null); - }) - .toCompletableFuture() - .join(); - - if (!settled[0]) { - unsettled.add(delivery.messageId()); - redeliver(delivery); - } else { - deadLetters.add(delivery.messageId()); - } - return settled[0]; - } - - private void redeliver(Pending delivery) { - pending.addLast( - new Pending(delivery.messageId(), delivery.envelope(), delivery.attempt() + 1, true)); - } - - private MessageDelivery toDelivery(Pending delivery) { - return new MessageDelivery<>( - delivery.envelope(), - new DeliveryMetadata( - SOURCE, - delivery.attempt(), - delivery.redelivered(), - Optional.of(new KafkaPosition("order.events.v1", 0, delivery.attempt())), - Optional.of("order.events.v1-0"), - Optional.of("order-projection"), - Instant.parse("2026-08-10T09:15:00Z")), - new DeliveryContext(Instant.parse("2026-08-10T09:15:30Z"), false, "order-projection")); - } - - @Override - public List deadLettered() { - return List.copyOf(deadLetters); - } - - @Override - public List unsettled() { - return List.copyOf(unsettled); - } - - @Override - public void beginShutdown() { - shuttingDown = true; - transport.close(); - } - - @Override - public boolean isAcceptingWork() { - return !shuttingDown && transport.isAcceptingWork(); - } - - @Override - public void close() { - pending.clear(); - if (!shuttingDown) { - transport.close(); - } - } - - static DestinationProfile profile() { - return new DestinationProfile( - SOURCE, - "kafka-primary", - DestinationKind.EVENT_STREAM, - PhysicalDestination.kafkaTopic("order.events.v1"), - new SchemaPolicy( - ContentType.JSON, - SchemaCompatibility.BACKWARD_TRANSITIVE, - Set.of(new MessageType("order.created"))), - DeliveryGuarantee.AT_LEAST_ONCE, - OrderingScope.NONE, - ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED, - ProducerPolicy.defaults(), - ConsumerPolicy.defaults("order-projection"), - RetryPolicy.none(), - DeadLetterPolicy.to(DEAD_LETTER), - PayloadPolicy.defaults(), - ApiTier.M1, - false, - false, - false); - } - - /** One message waiting to be delivered. */ - private record Pending( - MessageId messageId, - MessageEnvelope envelope, - int attempt, - boolean redelivered) {} - - /** Publishes to the dead letter destination, or fails when the fault is armed. */ - private final class HarnessDeadLetterPublisher implements MessagePublisher { - - @Override - public CompletionStage publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - if (faults.deadLetterPublishFails()) { - return CompletableFuture.completedFuture( - new PublishResult( - PublishCompletion.REJECTED, - PublishEvidence.notTransmitted(), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ZERO, - Optional.of( - FailureDescriptor.of( - FailureCategory.TRANSIENT_INFRASTRUCTURE, - "DLQ_UNAVAILABLE", - "the dead letter topic could not be reached")))); - } - return CompletableFuture.completedFuture( - new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ofMillis(2), - Optional.empty())); - } - } - - /** One-shot fault flags. */ - private static final class Faults implements FaultController { - - private boolean dropPublishConfirmation; - private boolean dropSettlementConfirmation; - private boolean failDeadLetterPublish; - private boolean rejectPublish; - - @Override - public void dropPublishConfirmation() { - dropPublishConfirmation = true; - } - - @Override - public void dropSettlementConfirmation() { - dropSettlementConfirmation = true; - } - - @Override - public void failDeadLetterPublish() { - failDeadLetterPublish = true; - } - - @Override - public void rejectPublish() { - rejectPublish = true; - } - - @Override - public void reset() { - dropPublishConfirmation = false; - dropSettlementConfirmation = false; - failDeadLetterPublish = false; - rejectPublish = false; - } - - boolean consumeDropPublishConfirmation() { - boolean active = dropPublishConfirmation; - dropPublishConfirmation = false; - return active; - } - - boolean consumeDropSettlementConfirmation() { - boolean active = dropSettlementConfirmation; - dropSettlementConfirmation = false; - return active; - } - - boolean consumeRejectPublish() { - boolean active = rejectPublish; - rejectPublish = false; - return active; - } - - boolean deadLetterPublishFails() { - return failDeadLetterPublish; - } - } -} diff --git a/src/platforms/messaging/messaging-kafka/src/testFixtures/java/dev/caskeleton/messaging/kafka/KafkaFixtureProfiles.java b/src/platforms/messaging/messaging-kafka/src/testFixtures/java/dev/caskeleton/messaging/kafka/KafkaFixtureProfiles.java deleted file mode 100644 index f34ab3fa..00000000 --- a/src/platforms/messaging/messaging-kafka/src/testFixtures/java/dev/caskeleton/messaging/kafka/KafkaFixtureProfiles.java +++ /dev/null @@ -1,32 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.policy.PhysicalDestination; - -/** Builds destination profiles that vary only in their physical mapping. */ -final class KafkaFixtureProfiles { - - private KafkaFixtureProfiles() {} - - static DestinationProfile withTopic(String topic) { - DestinationProfile base = KafkaContractHarness.profile(); - return new DestinationProfile( - base.name(), - base.broker(), - base.kind(), - PhysicalDestination.kafkaTopic(topic), - base.schema(), - base.deliveryGuarantee(), - base.orderingScope(), - base.externalSideEffectGuarantee(), - base.producer(), - base.consumer(), - base.retry(), - base.deadLetter(), - base.payload(), - base.tier(), - base.production(), - base.keyResolverConfigured(), - base.topologyAutoCreate()); - } -} diff --git a/src/platforms/messaging/messaging-observability/build.gradle b/src/platforms/messaging/messaging-observability/build.gradle deleted file mode 100644 index b255ee77..00000000 --- a/src/platforms/messaging/messaging-observability/build.gradle +++ /dev/null @@ -1,11 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') - - // api: MessagingMetrics' public constructor takes a MeterRegistry, so wiring it requires - // naming the type. - api 'io.micrometer:micrometer-core' -} diff --git a/src/platforms/messaging/messaging-observability/gradle.lockfile b/src/platforms/messaging/messaging-observability/gradle.lockfile deleted file mode 100644 index dcab1d05..00000000 --- a/src/platforms/messaging/messaging-observability/gradle.lockfile +++ /dev/null @@ -1,87 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.21.0=spotbugs -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor -io.micrometer:micrometer-commons:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-core:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-observation:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath -org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.hdrhistogram:HdrHistogram:2.2.2=runtimeClasspath,testRuntimeClasspath -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath -org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.latencyutils:LatencyUtils:2.0.3=runtimeClasspath,testRuntimeClasspath -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/CardinalityGuard.java b/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/CardinalityGuard.java deleted file mode 100644 index 91567e78..00000000 --- a/src/platforms/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/CardinalityGuard.java +++ /dev/null @@ -1,114 +0,0 @@ -package dev.caskeleton.messaging.observation; - -import java.util.Map; -import java.util.Objects; -import java.util.Set; -import java.util.concurrent.ConcurrentHashMap; - -/** - * Caps how many distinct values a metric dimension may take. - * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Then derivations are excluded. {@code payload.length}, {@code reference.sizeBytes()}, and - * {@code payload.getClass().getSimpleName()} all mention a sensitive word while carrying no - * secret — a size and a type name are exactly what a good diagnostic prints instead of - * the value. Flagging them would train the reader to ignore this test. - * - * @param line one source line, already trimmed - * @return true when the line concatenates a sensitive value - */ - private static boolean leaksASensitiveValue(String line) { - if (line.contains("\"\"\"") || IN_TEXT_BLOCK.get()) { - // A text block is SQL or JSON, not Java code. The scanner replaced ordinary string literals - // and then read the contents of text blocks as if they were expressions, so a column named - // `lease_token` in an UPDATE statement looked like a concatenated credential. - IN_TEXT_BLOCK.set(IN_TEXT_BLOCK.get() != line.contains("\"\"\"")); - return false; - } - String code = STRING_LITERAL.matcher(line).replaceAll("\"\""); - if (!code.contains("+")) { - return false; - } - if (ARITHMETIC.matcher(code).find()) { - // `existing.leaseToken() + 1` is an increment, not a concatenation: a numeric literal on - // either side of the + makes the whole expression arithmetic, and arithmetic cannot put a - // secret into a string. Fencing tokens are incremented all over the reliability code, and - // flagging them taught the reader to ignore this scan. - return false; - } - for (String operand : operandsAdjacentToConcatenation(code)) { - String lower = operand.toLowerCase(Locale.ROOT); - if (SENSITIVE_IDENTIFIERS.stream().noneMatch(lower::contains)) { - continue; - } - if (SAFE_DERIVATION.matcher(operand).find()) { - continue; - } - // A method call is captured with its trailing "()", and the safe-suffix pattern below anchors - // with $. Without stripping the call, `credentialId()` never matched `Id` and the exemption - // was dead for every method in the codebase. Stripping is the fix rather than unanchoring: - // an unanchored `Id` would also exempt `credentialIdentity`, which does carry the value. - String tail = operand.substring(operand.lastIndexOf('.') + 1); - if (tail.endsWith("()")) { - tail = tail.substring(0, tail.length() - 2); - } - // A SCREAMING_CASE constant is a compile-time literal in this codebase, never a runtime - // secret; the only ones matching are limits such as PayloadPolicy.HARD_MAX_BYTES. - if (tail.equals(tail.toUpperCase(Locale.ROOT))) { - continue; - } - // `credentialId` names a credential without being one. An id is what a diagnostic prints so - // that an operator can look the secret up in the store it actually lives in. - if (DESCRIBES_RATHER_THAN_REVEALS.matcher(tail).find()) { - continue; - } - return true; - } - return false; - } - - /** - * Returns the operand tokens on either side of each {@code +} in a line of code. - * - * @param code the line with string literals already blanked - * @return the adjacent operands - */ - private static List operandsAdjacentToConcatenation(String code) { - List operands = new ArrayList<>(); - var matcher = CONCATENATION_OPERAND.matcher(code); - while (matcher.find()) { - if (matcher.group("before") != null) { - operands.add(matcher.group("before")); - } - if (matcher.group("after") != null) { - operands.add(matcher.group("after")); - } - } - return operands; - } - - @Test - void theScanActuallyReachesTheSourceTree() throws IOException { - assertThat(productionSources()) - .as("a scan that finds no files would pass vacuously") - .hasSizeGreaterThan(100); - } - - @Test - void theScanCatchesAValueAppendedAfterThePlus() { - assertThat(leaksASensitiveValue("log.info(\"publishing with \" + password);")) - .as("a detector that never fires proves nothing") - .isTrue(); - } - - @Test - void theScanCatchesAValueAppendedBeforeThePlus() { - assertThat(leaksASensitiveValue("String message = clientSecret + \" was rejected\";")).isTrue(); - } - - @Test - void theScanIgnoresASensitiveWordThatIsOnlyProse() { - assertThat(leaksASensitiveValue("throw new IllegalArgumentException(\"password \" + field);")) - .as("blanking literals is what keeps the scan signal rather than noise") - .isFalse(); - } -} diff --git a/src/platforms/messaging/messaging-policy/build.gradle b/src/platforms/messaging/messaging-policy/build.gradle deleted file mode 100644 index fac7b208..00000000 --- a/src/platforms/messaging/messaging-policy/build.gradle +++ /dev/null @@ -1,7 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') -} diff --git a/src/platforms/messaging/messaging-policy/gradle.lockfile b/src/platforms/messaging/messaging-policy/gradle.lockfile deleted file mode 100644 index d74807c4..00000000 --- a/src/platforms/messaging/messaging-policy/gradle.lockfile +++ /dev/null @@ -1,82 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.21.0=spotbugs -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor -javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath -org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath -org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty=compileClasspath,runtimeClasspath diff --git a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ApiTier.java b/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ApiTier.java deleted file mode 100644 index c48fb243..00000000 --- a/src/platforms/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ApiTier.java +++ /dev/null @@ -1,30 +0,0 @@ -package dev.caskeleton.messaging.policy; - -/** - * The API tier a destination is approved for. - * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Two separate walks — one over retry edges, one over dead-letter edges — each visit alpha - * once and terminate, so both report a clean graph while a poison message circles between the two - * destinations forever. - */ - static List mixedEdgeCycle() { - // alpha retries into beta and parks in its own DLQ; beta dead-letters back into alpha. Each - // single-edge walk visits alpha once and stops, so both report a clean graph. - return List.of( - named("alpha", retryTo("beta"), DeadLetterPolicy.to(new DestinationName("alpha-dlq"))), - named("beta", RetryPolicy.none(), DeadLetterPolicy.to(new DestinationName("alpha"))), - parking("alpha-dlq")); - } - - /** Two destinations dead-lettering into the same place: a diamond, not a cycle. */ - static List sharedDeadLetter() { - return List.of( - named("alpha", RetryPolicy.none(), DeadLetterPolicy.to(new DestinationName("shared-dlq"))), - named("beta", RetryPolicy.none(), DeadLetterPolicy.to(new DestinationName("shared-dlq"))), - parking("shared-dlq")); - } - - static List danglingRetryDestination() { - return List.of( - named("alpha", retryTo("missing"), DeadLetterPolicy.to(new DestinationName("alpha-dlq"))), - parking("alpha-dlq")); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/MessagingAdmissionControllerTest.java b/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/MessagingAdmissionControllerTest.java deleted file mode 100644 index 2306d76e..00000000 --- a/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/MessagingAdmissionControllerTest.java +++ /dev/null @@ -1,233 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.error.MessageBackpressureException; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import java.time.Duration; -import java.util.List; -import java.util.concurrent.atomic.AtomicReference; -import org.junit.jupiter.api.Test; - -class MessagingAdmissionControllerTest { - - private static final String DESTINATION = "order.created"; - private static final String OTHER_DESTINATION = "invoice.issued"; - private static final Duration WAITER_BOUND = Duration.ofSeconds(30); - - private static MessagingAdmissionController controller(int limit) { - return new MessagingAdmissionController( - new PayloadLimitGuard(new PayloadPolicy(1024, 512)), - new InFlightLimiter(limit, Duration.ZERO)); - } - - @Test - void anAdmittedPublishOccupiesAPermitUntilItCompletes() { - MessagingAdmissionController controller = controller(2); - - controller.admit(DESTINATION, 100); - - assertThat(controller.inFlight()).isEqualTo(1); - controller.complete(DESTINATION); - assertThat(controller.inFlight()).isZero(); - } - - @Test - void publishingBeyondTheInFlightLimitIsRefusedRatherThanQueued() { - MessagingAdmissionController controller = controller(1); - controller.admit(DESTINATION, 100); - - assertThatThrownBy(() -> controller.admit(DESTINATION, 100)) - .isInstanceOf(MessageBackpressureException.class) - .hasMessageContaining(DESTINATION); - } - - @Test - void backpressureIsRetryableBecauseNothingWasTransmitted() { - MessagingAdmissionController controller = controller(1); - controller.admit(DESTINATION, 100); - - assertThatThrownBy(() -> controller.admit(DESTINATION, 100)) - .isInstanceOfSatisfying( - MessageBackpressureException.class, - exception -> assertThat(exception.failure().retryable()).isTrue()); - } - - @Test - void anOversizedPayloadIsRejectedWithoutConsumingAPermit() { - MessagingAdmissionController controller = controller(1); - - assertThatThrownBy(() -> controller.admit(DESTINATION, 2048)) - .isInstanceOf(MessageTooLargeException.class); - - assertThat(controller.inFlight()) - .as("a message that can never succeed must not occupy a scarce permit") - .isZero(); - } - - @Test - void shutdownStopsAdmittingNewWorkWithoutRevokingPermitsAlreadyHeld() { - MessagingAdmissionController controller = controller(4); - controller.admit(DESTINATION, 100); - - controller.stopAcceptingNewWork(); - - assertThat(controller.isAcceptingNewWork()).isFalse(); - assertThat(controller.inFlight()).isEqualTo(1); - assertThatThrownBy(() -> controller.admit(DESTINATION, 100)) - .isInstanceOf(MessageBackpressureException.class) - .hasMessageContaining("stopped accepting"); - } - - @Test - void aReleaseWithoutAnAdmitCannotRaiseTheCeiling() { - MessagingAdmissionController controller = controller(1); - - controller.complete(DESTINATION); - controller.complete(DESTINATION); - controller.admit(DESTINATION, 100); - - assertThatThrownBy(() -> controller.admit(DESTINATION, 100)) - .as("unbalanced releases must not hand out more permits than the limit") - .isInstanceOf(MessageBackpressureException.class); - } - - @Test - void oneSlowDestinationCannotOccupyEveryPermit() { - MessagingAdmissionController controller = - new MessagingAdmissionController( - new PayloadLimitGuard(new PayloadPolicy(1024, 512)), - new InFlightLimiter(4, Duration.ZERO), - 2); - - controller.admit(DESTINATION, 100); - controller.admit(DESTINATION, 100); - - assertThatThrownBy(() -> controller.admit(DESTINATION, 100)) - .as("a single slow downstream taking every permit is how one destination stops the others") - .isInstanceOf(MessageBackpressureException.class); - assertThat(controller.inFlight("other.destination")).isZero(); - controller.admit("other.destination", 100); - assertThat(controller.inFlight()).isEqualTo(3); - } - - @Test - void aRefusedAdmissionLeavesNoDestinationSlotBehind() { - MessagingAdmissionController controller = - new MessagingAdmissionController( - new PayloadLimitGuard(new PayloadPolicy(1024, 512)), - new InFlightLimiter(1, Duration.ZERO), - 1); - controller.admit(DESTINATION, 100); - - assertThatThrownBy(() -> controller.admit("other.destination", 100)) - .isInstanceOf(MessageBackpressureException.class); - - assertThat(controller.inFlight("other.destination")) - .as("a slot leaked per refusal shrinks the destination's ceiling until it is zero") - .isZero(); - } - - @Test - void completingReturnsBothTheProcessPermitAndTheDestinationSlot() { - MessagingAdmissionController controller = - new MessagingAdmissionController( - new PayloadLimitGuard(new PayloadPolicy(1024, 512)), - new InFlightLimiter(4, Duration.ZERO), - 2); - controller.admit(DESTINATION, 100); - - controller.complete(DESTINATION); - - assertThat(controller.inFlight()).isZero(); - assertThat(controller.inFlight(DESTINATION)).isZero(); - } - - @Test - void completingAnUnknownDestinationFreesNoProcessPermit() { - MessagingAdmissionController controller = controller(2); - controller.admit(DESTINATION, 100); - - controller.complete("something-else"); - - assertThat(controller.inFlight()) - .as("a permit nobody took cannot be given back; doing so makes the ceiling fiction") - .isEqualTo(1); - } - - @Test - void aSecondCompletionForOnePublishFreesNoSecondPermit() { - MessagingAdmissionController controller = controller(4); - controller.admit(DESTINATION, 100); - - controller.complete(DESTINATION); - controller.complete(DESTINATION); - - assertThat(controller.inFlight()).isZero(); - assertThat(controller.inFlight(DESTINATION)).isZero(); - } - - @Test - void aBatchIsBoundedByCountAndByAggregateBytes() { - PayloadLimitGuard guard = new PayloadLimitGuard(new PayloadPolicy(1024, 512)); - - assertThatThrownBy(() -> guard.checkBatch(DESTINATION, List.of(10, 10, 10), 2, 10_000)) - .isInstanceOf(MessageTooLargeException.class) - .hasMessageContaining("entry limit"); - - assertThatThrownBy(() -> guard.checkBatch(DESTINATION, List.of(1000, 1000), 10, 1500)) - .isInstanceOf(MessageTooLargeException.class) - .hasMessageContaining("byte limit"); - } - - @Test - void aWaitingCallerIsAdmittedOnceAPermitIsReturned() throws InterruptedException { - MessagingAdmissionController controller = - new MessagingAdmissionController( - new PayloadLimitGuard(PayloadPolicy.defaults()), new InFlightLimiter(1, WAITER_BOUND)); - controller.admit(DESTINATION, 100); - AtomicReference refused = new AtomicReference<>(); - // Another destination, so only the process-wide permit is contested. A second publish to - // DESTINATION is refused at once by its own ceiling (equal to the process limit here) and - // never waits. - Thread waiter = - new Thread( - () -> { - try { - controller.admit(OTHER_DESTINATION, 100); - } catch (RuntimeException refusal) { - refused.set(refusal); - } - }); - - waiter.start(); - awaitQueuedOnAPermit(waiter, refused); - controller.complete(DESTINATION); - waiter.join(WAITER_BOUND.toMillis()); - - assertThat(refused.get()).as("the waiter was refused instead of admitted").isNull(); - assertThat(waiter.isAlive()).isFalse(); - assertThat(controller.inFlight()).isEqualTo(1); - assertThat(controller.inFlight(OTHER_DESTINATION)).isEqualTo(1); - } - - /** - * Waits until {@code waiter} is parked in the limiter's bounded wait, so the permit is returned - * to a caller that is already queued rather than to one that has not arrived yet. - */ - private static void awaitQueuedOnAPermit(Thread waiter, AtomicReference refused) - throws InterruptedException { - long deadline = System.nanoTime() + WAITER_BOUND.toNanos(); - while (waiter.getState() != Thread.State.TIMED_WAITING - && waiter.isAlive() - && System.nanoTime() < deadline) { - Thread.sleep(1); - } - assertThat(waiter.getState()) - .as( - "the waiter must be queued on the permit before it is returned (refused: %s)", - refused.get()) - .isEqualTo(Thread.State.TIMED_WAITING); - } -} diff --git a/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/RetryDecisionEngineTest.java b/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/RetryDecisionEngineTest.java deleted file mode 100644 index 6a8dc244..00000000 --- a/src/platforms/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/RetryDecisionEngineTest.java +++ /dev/null @@ -1,258 +0,0 @@ -package dev.caskeleton.messaging.policy; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.delivery.DeliveryMetadata; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessagingCapabilities; -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import java.time.Duration; -import java.time.Instant; -import java.util.Optional; -import java.util.Set; -import org.junit.jupiter.api.Test; - -class RetryDecisionEngineTest { - - private final DefaultRetryDecisionEngine engine = - new DefaultRetryDecisionEngine(new BackoffCalculator(() -> 1.0)); - - @Test - void deserializationFailureGoesDirectlyToParking() { - RetryDecision decision = - engine.decide(RetryContextFixtures.failure(FailureCategory.DESERIALIZATION, 1)); - - assertThat(decision).isInstanceOf(RetryDecision.DeadLetter.class); - } - - @Test - void authenticationAndConfigurationFailuresAreNeverRetried() { - assertThat(engine.decide(RetryContextFixtures.failure(FailureCategory.AUTHENTICATION, 1))) - .isInstanceOf(RetryDecision.DeadLetter.class); - assertThat(engine.decide(RetryContextFixtures.failure(FailureCategory.CONFIGURATION, 1))) - .isInstanceOf(RetryDecision.DeadLetter.class); - assertThat(engine.decide(RetryContextFixtures.failure(FailureCategory.AUTHORIZATION, 1))) - .isInstanceOf(RetryDecision.DeadLetter.class); - } - - @Test - void transientOrderedKafkaFailureUsesPauseStrategy() { - RetryDecision decision = engine.decide(RetryContextFixtures.orderedKafkaTransient(1)); - - assertThat(decision).isInstanceOf(RetryDecision.PauseAndRetry.class); - } - - @Test - void exhaustedAttemptGoesToDeadLetter() { - RetryDecision decision = engine.decide(RetryContextFixtures.transientAtMaximumAttempt()); - - assertThat(decision).isInstanceOf(RetryDecision.DeadLetter.class); - } - - @Test - void unorderedRetryDestinationModeRePublishes() { - RetryDecision decision = engine.decide(RetryContextFixtures.unorderedRetryDestination(1)); - - assertThat(decision) - .isInstanceOfSatisfying( - RetryDecision.PublishToRetryDestination.class, - publish -> - assertThat(publish.destination()) - .isEqualTo(new DestinationName("email-work-retry"))); - } - - @Test - void blockingModeRetriesInline() { - RetryDecision decision = engine.decide(RetryContextFixtures.blockingTransient(1)); - - assertThat(decision).isInstanceOf(RetryDecision.RetryInline.class); - } - - @Test - void backoffGrowsExponentiallyAndIsCappedByMaxDelay() { - BackoffCalculator calculator = new BackoffCalculator(() -> 1.0); - RetryPolicy policy = - new RetryPolicy( - RetryMode.BLOCKING, - 10, - Duration.ofMillis(200), - Duration.ofSeconds(2), - 2.0, - false, - OrderingImpact.PRESERVE, - Set.of(), - Set.of()); - - assertThat(calculator.delayFor(policy, 1)).isEqualTo(Duration.ofMillis(200)); - assertThat(calculator.delayFor(policy, 2)).isEqualTo(Duration.ofMillis(400)); - assertThat(calculator.delayFor(policy, 3)).isEqualTo(Duration.ofMillis(800)); - assertThat(calculator.delayFor(policy, 9)).isEqualTo(Duration.ofSeconds(2)); - } - - @Test - void fullJitterSpreadsRetriesAcrossTheWholeWindow() { - RetryPolicy policy = - new RetryPolicy( - RetryMode.BLOCKING, - 10, - Duration.ofSeconds(1), - Duration.ofSeconds(2), - 2.0, - true, - OrderingImpact.PRESERVE, - Set.of(), - Set.of()); - - assertThat(new BackoffCalculator(() -> 0.0).delayFor(policy, 1)).isEqualTo(Duration.ZERO); - assertThat(new BackoffCalculator(() -> 0.5).delayFor(policy, 1)) - .isEqualTo(Duration.ofMillis(500)); - } - - @Test - void anExplicitProfileOverrideCanMakeACategoryRetryable() { - RetryDecision decision = - engine.decide(RetryContextFixtures.withRetryableOverride(FailureCategory.DESERIALIZATION)); - - assertThat(decision).isInstanceOf(RetryDecision.RetryInline.class); - } - - @Test - void anAtMostOnceDestinationWithoutDlqDiscards() { - RetryDecision decision = engine.decide(RetryContextFixtures.atMostOnceWithoutDlq()); - - assertThat(decision).isInstanceOf(RetryDecision.Reject.class); - } -} - -/** Builds retry contexts for engine tests. */ -final class RetryContextFixtures { - - private RetryContextFixtures() {} - - private static final MessagingCapabilities ORDERED_KAFKA = - MessagingCapabilities.of( - MessagingCapabilities.Capability.ORDERED_STREAM, - MessagingCapabilities.Capability.DEDUPLICATED_PUBLISH); - - private static final MessagingCapabilities PLAIN_QUEUE = MessagingCapabilities.none(); - - static DeliveryMetadata delivery(int attempt) { - return new DeliveryMetadata( - new DestinationName("order-events"), - attempt, - attempt > 1, - Optional.empty(), - Optional.of("order.events.v1-0"), - Optional.of("order-projection"), - Instant.parse("2026-08-10T00:00:00Z")); - } - - static RetryContext failure(FailureCategory category, int attempt) { - return new RetryContext( - DestinationProfileFixtures.kafkaOrdered(pausePolicy()), - delivery(attempt), - FailureDescriptor.of(category, category.name(), "failed"), - ORDERED_KAFKA, - false); - } - - static RetryContext orderedKafkaTransient(int attempt) { - return new RetryContext( - DestinationProfileFixtures.kafkaOrdered(pausePolicy()), - delivery(attempt), - FailureDescriptor.of( - FailureCategory.TRANSIENT_INFRASTRUCTURE, "BROKER_TIMEOUT", "broker timed out"), - ORDERED_KAFKA, - false); - } - - static RetryContext transientAtMaximumAttempt() { - return new RetryContext( - DestinationProfileFixtures.kafkaOrdered(pausePolicy()), - delivery(3), - FailureDescriptor.of( - FailureCategory.TRANSIENT_INFRASTRUCTURE, "BROKER_TIMEOUT", "broker timed out"), - ORDERED_KAFKA, - false); - } - - static RetryContext unorderedRetryDestination(int attempt) { - return new RetryContext( - DestinationProfileFixtures.named( - "email-work", - DestinationProfileFixtures.retryTo("email-work-retry"), - DeadLetterPolicy.to(new DestinationName("email-work-dlq"))), - delivery(attempt), - FailureDescriptor.of( - FailureCategory.PROCESSING_TRANSIENT, "DOWNSTREAM_TIMEOUT", "downstream timed out"), - PLAIN_QUEUE, - false); - } - - static RetryContext blockingTransient(int attempt) { - return new RetryContext( - DestinationProfileFixtures.named( - "email-work", blockingPolicy(), DeadLetterPolicy.to(new DestinationName("email-dlq"))), - delivery(attempt), - FailureDescriptor.of(FailureCategory.THROTTLED, "RATE_LIMITED", "throttled"), - PLAIN_QUEUE, - false); - } - - static RetryContext withRetryableOverride(FailureCategory category) { - RetryPolicy policy = - new RetryPolicy( - RetryMode.BLOCKING, - 3, - Duration.ofMillis(100), - Duration.ofSeconds(1), - 2.0, - false, - OrderingImpact.PRESERVE, - Set.of(category), - Set.of()); - return new RetryContext( - DestinationProfileFixtures.named( - "email-work", policy, DeadLetterPolicy.to(new DestinationName("email-dlq"))), - delivery(1), - FailureDescriptor.of(category, category.name(), "failed"), - PLAIN_QUEUE, - false); - } - - static RetryContext atMostOnceWithoutDlq() { - return new RetryContext( - DestinationProfileFixtures.atMostOnceWithoutDeadLetter(), - delivery(1), - FailureDescriptor.of(FailureCategory.PERMANENT_BUSINESS, "INVALID", "rejected"), - PLAIN_QUEUE, - false); - } - - private static RetryPolicy pausePolicy() { - return new RetryPolicy( - RetryMode.PAUSE_PARTITION, - 3, - Duration.ofMillis(200), - Duration.ofSeconds(2), - 2.0, - false, - OrderingImpact.PRESERVE, - Set.of(), - Set.of()); - } - - private static RetryPolicy blockingPolicy() { - return new RetryPolicy( - RetryMode.BLOCKING, - 5, - Duration.ofMillis(200), - Duration.ofSeconds(2), - 2.0, - false, - OrderingImpact.PRESERVE, - Set.of(), - Set.of()); - } -} diff --git a/src/platforms/messaging/messaging-reliability-api/build.gradle b/src/platforms/messaging/messaging-reliability-api/build.gradle deleted file mode 100644 index fac7b208..00000000 --- a/src/platforms/messaging/messaging-reliability-api/build.gradle +++ /dev/null @@ -1,7 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') -} diff --git a/src/platforms/messaging/messaging-reliability-api/gradle.lockfile b/src/platforms/messaging/messaging-reliability-api/gradle.lockfile deleted file mode 100644 index d74807c4..00000000 --- a/src/platforms/messaging/messaging-reliability-api/gradle.lockfile +++ /dev/null @@ -1,82 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.21.0=spotbugs -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor -javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath -org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath -org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty=compileClasspath,runtimeClasspath diff --git a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/ClaimCheckReference.java b/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/ClaimCheckReference.java deleted file mode 100644 index 1985439f..00000000 --- a/src/platforms/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/ClaimCheckReference.java +++ /dev/null @@ -1,50 +0,0 @@ -package dev.caskeleton.messaging.reliability; - -import java.time.Instant; -import java.util.Objects; -import java.util.regex.Pattern; - -/** - * Points at a payload stored outside the broker. - * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Another relay claimed it after the lease expired. Not an error to throw — the message is - * being handled by somebody else — but never a success either: it is the signal that this - * worker's publish attempt may have produced a duplicate, and it belongs on a metric. - */ - STALE_LEASE -} diff --git a/src/platforms/messaging/messaging-reliability-api/src/test/java/dev/caskeleton/messaging/reliability/OutboxRepositoryApiSafetyTest.java b/src/platforms/messaging/messaging-reliability-api/src/test/java/dev/caskeleton/messaging/reliability/OutboxRepositoryApiSafetyTest.java deleted file mode 100644 index 72c780e1..00000000 --- a/src/platforms/messaging/messaging-reliability-api/src/test/java/dev/caskeleton/messaging/reliability/OutboxRepositoryApiSafetyTest.java +++ /dev/null @@ -1,24 +0,0 @@ -package dev.caskeleton.messaging.reliability; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.MessageId; -import java.lang.reflect.Method; -import java.util.Set; -import org.junit.jupiter.api.Test; - -class OutboxRepositoryApiSafetyTest { - @Test - void outcomeTransitionsDoNotExposeUnfencedMessageIdOverloadsUnderTheSafeNames() { - Set fencedNames = - Set.of("markPublished", "markAmbiguous", "markFailed", "releaseLease"); - - assertThat(OutboxRepository.class.getMethods()) - .filteredOn(method -> fencedNames.contains(method.getName())) - .noneMatch(OutboxRepositoryApiSafetyTest::startsWithMessageId); - } - - private static boolean startsWithMessageId(Method method) { - return method.getParameterCount() > 0 && method.getParameterTypes()[0] == MessageId.class; - } -} diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/build.gradle b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/build.gradle deleted file mode 100644 index f549b2d0..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/build.gradle +++ /dev/null @@ -1,50 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -testing { - suites { - integrationTest(JvmTestSuite) { - dependencies { - implementation project() - } - } - } -} -configurations { - integrationTestImplementation.extendsFrom testImplementation - integrationTestRuntimeOnly.extendsFrom testRuntimeOnly -} - -// The relational implementations of the reliability ports: the outbox repository, the inbox -// repository and the destructive-operation journal. Spring JDBC for the transaction join, and SQL -// that is PostgreSQL's (`jsonb`, `FOR UPDATE SKIP LOCKED`, `ON CONFLICT`, `TIMESTAMPTZ`) — the name -// is the contract. The relay and consumer logic that uses them is messaging-reliability. -dependencies { - api project(':messaging:messaging-core-api') - api project(':messaging:messaging-reliability-api') - - // The destructive-operation journal lives here because it needs exactly what the outbox needs: - // one relational database every replica can see, and a migration lane that already exists. The - // contract it implements belongs to the admin API. - api project(':messaging:messaging-admin') - - implementation 'org.springframework:spring-jdbc' - implementation 'org.springframework:spring-tx' - - // Live-database certification. The reliability patterns are claims about transaction - // boundaries and uniqueness constraints, and only a real database can settle them. - testImplementation project(':messaging:messaging-testkit') - integrationTestImplementation project(':messaging:messaging-testkit') - integrationTestImplementation 'org.testcontainers:testcontainers-postgresql' - integrationTestImplementation 'org.testcontainers:testcontainers-junit-jupiter' - integrationTestImplementation 'org.postgresql:postgresql' -} - -strictTestLanes { - lane('integrationTest') { - integration() - sourceSet = 'integrationTest' - description = 'Runs outbox, inbox and admin-journal contracts against real PostgreSQL.' - } -} diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/gradle.lockfile b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/gradle.lockfile deleted file mode 100644 index b55aa2ae..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/gradle.lockfile +++ /dev/null @@ -1,109 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.fasterxml.jackson.core:jackson-annotations:2.21=integrationTestCompileClasspath,integrationTestRuntimeClasspath -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.github.docker-java:docker-java-api:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath -com.github.docker-java:docker-java-transport-zerodep:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath -com.github.docker-java:docker-java-transport:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-codec:commons-codec:1.19.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.20.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath -commons-io:commons-io:2.21.0=spotbugs -commons-logging:commons-logging:1.3.6=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -io.micrometer:micrometer-commons:1.16.8=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -io.micrometer:micrometer-core:1.16.8=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -io.micrometer:micrometer-observation:1.16.8=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -javax.inject:javax.inject:1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -net.java.dev.jna:jna:5.18.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-compress:1.28.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.apache.commons:commons-lang3:3.20.0=checkstyle,integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=integrationTestCompileClasspath,testCompileClasspath -org.assertj:assertj-core:3.27.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.checkerframework:checker-qual:3.55.1=integrationTestRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.hdrhistogram:HdrHistogram:2.2.2=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -org.javassist:javassist:3.28.0-GA=checkstyle -org.jetbrains:annotations:17.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,integrationTestAnnotationProcessor,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath -org.junit:junit-bom:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.latencyutils:LatencyUtils:2.0.3=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -org.postgresql:postgresql:42.7.14=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.reflections:reflections:0.10.2=checkstyle -org.rnorth.duct-tape:duct-tape:1.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.slf4j:slf4j-api:2.0.20=integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.springframework:spring-beans:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-core:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-jdbc:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-tx:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.testcontainers:testcontainers-database-commons:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-jdbc:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-junit-jupiter:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-postgresql:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/inbox/InboxPostgresIT.java b/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/inbox/InboxPostgresIT.java deleted file mode 100644 index 2ec95ce0..00000000 --- a/src/platforms/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/inbox/InboxPostgresIT.java +++ /dev/null @@ -1,206 +0,0 @@ -package dev.caskeleton.messaging.inbox; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.testkit.DockerAvailability; -import java.io.IOException; -import java.io.InputStream; -import java.nio.charset.StandardCharsets; -import java.sql.Connection; -import java.sql.PreparedStatement; -import java.sql.ResultSet; -import java.sql.SQLException; -import java.sql.Statement; -import java.time.Instant; -import java.util.concurrent.atomic.AtomicInteger; -import javax.sql.DataSource; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.condition.EnabledIf; -import org.postgresql.ds.PGSimpleDataSource; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; -import org.testcontainers.postgresql.PostgreSQLContainer; - -/** - * Certifies the inbox against a real PostgreSQL. - * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

These are hermetic: the refusal happens before any connection is requested, which is also the - * property under test. The mock would fail the test by being touched at all. - */ -class JdbcOutboxTransactionRequirementTest { - - /** A data source that fails the test by being used: the refusal must precede any connection. */ - private final DataSource dataSource = new RefusingDataSource(); - - private final JdbcOutboxRepository repository = new JdbcOutboxRepository(dataSource); - - @AfterEach - void clearTransactionState() { - TransactionSynchronizationManager.clear(); - if (TransactionSynchronizationManager.hasResource(dataSource)) { - TransactionSynchronizationManager.unbindResource(dataSource); - } - } - - @Test - @DisplayName("appending outside a transaction is refused before a connection is opened") - void appendingOutsideATransactionIsRefused() { - assertThatThrownBy(() -> repository.append(record())) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("requires an active transaction"); - } - - @Test - @DisplayName("a read-only transaction is refused") - void aReadOnlyTransactionIsRefused() { - TransactionSynchronizationManager.setActualTransactionActive(true); - TransactionSynchronizationManager.setCurrentTransactionReadOnly(true); - - assertThatThrownBy(() -> repository.append(record())) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("read-only"); - } - - @Test - @DisplayName("a transaction bound to another DataSource is refused") - void aTransactionOnAnotherDataSourceIsRefused() { - TransactionSynchronizationManager.setActualTransactionActive(true); - - assertThatThrownBy(() -> repository.append(record())) - .as("two DataSources means two commits, which is the atomicity this exists to provide") - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("bound to this DataSource"); - } - - @Test - @DisplayName("the refusal names a code an operator can search for") - void theRefusalNamesACode() { - assertThatThrownBy(() -> repository.append(record())) - .isInstanceOfSatisfying( - MessagingConfigurationException.class, - failure -> - assertThat(failure.failure().code()).isEqualTo("OUTBOX_TRANSACTION_REQUIRED")); - } - - private static OutboxRecord record() { - return new OutboxRecord( - MessageId.newId(), - new DestinationName("orders.events"), - new MessageType("order.placed"), - new SchemaVersion(1), - ContentType.JSON, - "{}".getBytes(java.nio.charset.StandardCharsets.UTF_8), - Map.of(), - dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata.none(), - Instant.parse("2026-08-14T00:00:00Z"), - OutboxStatus.PENDING, - 0, - Optional.empty(), - Optional.empty()); - } - - /** Throws if anything asks it for a connection. */ - private static final class RefusingDataSource - extends org.springframework.jdbc.datasource.AbstractDataSource { - - @Override - public java.sql.Connection getConnection() { - throw new AssertionError( - "the refusal must happen before a connection is requested; opening one is the defect"); - } - - @Override - public java.sql.Connection getConnection(String username, String password) { - return getConnection(); - } - } -} diff --git a/src/platforms/messaging/messaging-reliability/build.gradle b/src/platforms/messaging/messaging-reliability/build.gradle deleted file mode 100644 index d2f62103..00000000 --- a/src/platforms/messaging/messaging-reliability/build.gradle +++ /dev/null @@ -1,18 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -// The outbox relay and the inbox consumer logic, framework-free. What they store and claim goes -// through the ports in messaging-reliability-api; the relational implementation of those ports is -// messaging-reliability-jdbc-postgresql. Split so a leaf's name says what it depends on: this one -// is Java stdlib plus the messaging APIs, the other is Spring JDBC and PostgreSQL SQL. -dependencies { - api project(':messaging:messaging-core-api') - api project(':messaging:messaging-reliability-api') - // The relay hands encoded rows to the publisher as EncodedMessage. - - // Test-only. The relay is also driven through the real DefaultMessagePublisher: a fake publisher - // accepted the pre-encoded rows the real one re-encoded and rejected. - testImplementation project(':messaging:messaging-runtime-core') - testImplementation project(':messaging:messaging-policy') -} diff --git a/src/platforms/messaging/messaging-reliability/gradle.lockfile b/src/platforms/messaging/messaging-reliability/gradle.lockfile deleted file mode 100644 index 7feb7385..00000000 --- a/src/platforms/messaging/messaging-reliability/gradle.lockfile +++ /dev/null @@ -1,87 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.21.0=spotbugs -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor -io.micrometer:micrometer-commons:1.16.8=testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-core:1.16.8=testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-observation:1.16.8=testCompileClasspath,testRuntimeClasspath -javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath -org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.hdrhistogram:HdrHistogram:2.2.2=testRuntimeClasspath -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath -org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.latencyutils:LatencyUtils:2.0.3=testRuntimeClasspath -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty=compileClasspath,runtimeClasspath diff --git a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/IdempotentConsumer.java b/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/IdempotentConsumer.java deleted file mode 100644 index 35f2bef6..00000000 --- a/src/platforms/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/IdempotentConsumer.java +++ /dev/null @@ -1,77 +0,0 @@ -package dev.caskeleton.messaging.inbox; - -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.reliability.InboxRepository; -import java.time.Instant; -import java.util.Objects; -import java.util.function.Supplier; - -/** - * Runs a handler's side effect at most once per message and consumer. - * - *

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

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

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

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

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

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

    - *
  • the message was reserved before (a redelivery) — the handler is not called and the result - * is {@code Success}, so the broker settles a message whose work is already done; - *
  • the handler answers {@code Success} — the transaction commits with the reservation; - *
  • the handler answers anything else, throws, or its stage fails — the transaction rolls back, - * the reservation with it, and the answer (or the failure) goes to the platform, which - * retries or dead-letters as it would without an inbox. - *
- * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

A double that accepted every terminal write would let the relay's stale-lease handling look - * correct without ever being exercised. - */ - private boolean owns(OutboxLease lease) { - return lease.owner().equals(owners.get(lease.messageId())) - && Long.valueOf(lease.token()).equals(tokens.get(lease.messageId())) - && rows.get(lease.messageId()) != null - && rows.get(lease.messageId()).status() == OutboxStatus.IN_FLIGHT; - } - - /** Per-row retry clock, mirroring next_attempt_at and the attempt budget in the SQL. */ - private final Map nextAttempts = new LinkedHashMap<>(); - - @Override - public List claimBatch( - String owner, int batchSize, Duration leaseDuration, Instant now, int maxAttempts) { - List claimed = new ArrayList<>(); - for (OutboxLease lease : claimIgnoringBudget(owner, batchSize, leaseDuration, now)) { - Instant nextAttempt = nextAttempts.get(lease.messageId()); - boolean waiting = nextAttempt != null && now.isBefore(nextAttempt); - if (waiting || lease.record().attempts() >= maxAttempts) { - // Put it back exactly as the SQL predicate would have left it: unclaimed. - releaseLeaseUnfenced(lease.messageId()); - continue; - } - claimed.add(lease); - } - return List.copyOf(claimed); - } - - @Override - public OutboxTransitionResult markAmbiguous( - OutboxLease lease, String failureCode, Instant now, Instant nextAttemptAt) { - if (!owns(lease)) { - return OutboxTransitionResult.STALE_LEASE; - } - markAmbiguousUnfenced(lease.messageId(), failureCode); - owners.remove(lease.messageId()); - nextAttempts.put(lease.messageId(), nextAttemptAt); - return OutboxTransitionResult.APPLIED; - } - - @Override - public OutboxTransitionResult markExhausted(OutboxLease lease, String reason, Instant now) { - if (!owns(lease)) { - return OutboxTransitionResult.STALE_LEASE; - } - transition(lease.messageId(), OutboxStatus.EXHAUSTED, Optional.of(reason)); - owners.remove(lease.messageId()); - leases.remove(lease.messageId()); - return OutboxTransitionResult.APPLIED; - } - - @Override - public OutboxTransitionResult markPublished(OutboxLease lease, Instant now) { - if (!owns(lease)) { - return OutboxTransitionResult.STALE_LEASE; - } - transition(lease.messageId(), OutboxStatus.PUBLISHED, Optional.empty()); - owners.remove(lease.messageId()); - return OutboxTransitionResult.APPLIED; - } - - @Override - public OutboxTransitionResult markFailed(OutboxLease lease, String failureCode, Instant now) { - if (!owns(lease)) { - return OutboxTransitionResult.STALE_LEASE; - } - markFailedUnfenced(lease.messageId(), failureCode); - owners.remove(lease.messageId()); - return OutboxTransitionResult.APPLIED; - } - - @Override - public OutboxTransitionResult releaseLease(OutboxLease lease) { - if (!owns(lease)) { - return OutboxTransitionResult.STALE_LEASE; - } - releaseLeaseUnfenced(lease.messageId()); - owners.remove(lease.messageId()); - return OutboxTransitionResult.APPLIED; - } - - private void markAmbiguousUnfenced(MessageId messageId, String failureCode) { - transition(messageId, OutboxStatus.AMBIGUOUS, Optional.of(failureCode)); - leases.remove(messageId); - } - - private void markFailedUnfenced(MessageId messageId, String failureCode) { - transition(messageId, OutboxStatus.FAILED, Optional.of(failureCode)); - } - - private void releaseLeaseUnfenced(MessageId messageId) { - leases.remove(messageId); - } - - @Override - public Optional find(MessageId messageId) { - return Optional.ofNullable(rows.get(messageId)); - } - - @Override - public int purgePublishedBefore(Instant publishedBefore, int limit) { - int before = rows.size(); - rows.values().removeIf(record -> record.status() == OutboxStatus.PUBLISHED); - return Math.min(before - rows.size(), limit); - } - - private void transition(MessageId messageId, OutboxStatus status, Optional failureCode) { - OutboxRecord record = rows.get(messageId); - if (record != null) { - rows.put(messageId, record.withStatus(status, record.attempts() + 1, failureCode)); - } - } -} - -/** A publisher that records what the relay handed it. */ -final class RecordingOutboxPublisher implements MessagePublisher { - - final List publishedIds = new ArrayList<>(); - final List> publishedEnvelopes = new ArrayList<>(); - - private final PublishCompletion completion; - - private RecordingOutboxPublisher(PublishCompletion completion) { - this.completion = completion; - } - - static RecordingOutboxPublisher confirming() { - return new RecordingOutboxPublisher(PublishCompletion.CONFIRMED); - } - - static RecordingOutboxPublisher ambiguous() { - return new RecordingOutboxPublisher(PublishCompletion.AMBIGUOUS); - } - - static RecordingOutboxPublisher rejecting() { - return new RecordingOutboxPublisher(PublishCompletion.REJECTED); - } - - @Override - public CompletionStage publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - publishedIds.add(message.messageId()); - publishedEnvelopes.add(message); - return CompletableFuture.completedFuture(result()); - } - - private PublishResult result() { - return switch (completion) { - case CONFIRMED -> - new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ofMillis(2), - Optional.empty()); - case AMBIGUOUS -> - new PublishResult( - PublishCompletion.AMBIGUOUS, - PublishEvidence.ambiguous(), - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, - Duration.ofSeconds(5), - Optional.of( - FailureDescriptor.of( - FailureCategory.AMBIGUOUS, "CONFIRM_TIMEOUT", "confirm timed out"))); - case REJECTED -> - new PublishResult( - PublishCompletion.REJECTED, - PublishEvidence.notTransmitted(), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ofMillis(1), - Optional.of( - FailureDescriptor.of( - FailureCategory.PERMANENT_BUSINESS, "INVALID_TOPIC", "unknown topic"))); - }; - } -} - -/** The platform's own publisher over a stub transport, registered for the fixture's destination. */ -final class RealPublisher { - - private static final DestinationName ORDERS = new DestinationName("order-events"); - - private RealPublisher() {} - - static DefaultMessagePublisher over(MessagingTransport transport) { - DefaultMessagingRuntimeRegistry runtimes = new DefaultMessagingRuntimeRegistry(); - runtimes.install(new TransportMessagingRuntime("fake", 1, transport)); - // A real codec. Like every codec it refuses a payload that is not its own type, which is what - // an already-encoded row is to it. - MessageCodec raw = new RawBytesMessageCodec(); - return new DefaultMessagePublisher( - DestinationProfileRegistry.of(Map.of(ORDERS, profile())), - new DestinationAccessPolicy(Set.of(ORDERS), Set.of(), Set.of()), - new MessageCodecRegistry() { - @Override - public Optional find(ContentType contentType) { - return Optional.of(raw); - } - - @Override - public MessageCodec defaultCodec() { - return raw; - } - }, - new MessagingAdmissionController( - new PayloadLimitGuard(PayloadPolicy.defaults()), - new InFlightLimiter(4, Duration.ofSeconds(1))), - runtimes, - transport); - } - - private static DestinationProfile profile() { - return new DestinationProfile( - ORDERS, - "fake", - DestinationKind.EVENT_STREAM, - PhysicalDestination.kafkaTopic("order.events.v1"), - new SchemaPolicy( - ContentType.JSON, - SchemaCompatibility.BACKWARD_TRANSITIVE, - Set.of(new MessageType("order.created"))), - DeliveryGuarantee.AT_LEAST_ONCE, - OrderingScope.NONE, - ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED, - ProducerPolicy.defaults(), - ConsumerPolicy.defaults("order-projection"), - RetryPolicy.none(), - DeadLetterPolicy.disabled(), - PayloadPolicy.defaults(), - ApiTier.M1, - false, - false, - false); - } -} - -/** A transport that confirms every publish and keeps the bytes it was handed. */ -final class CapturingTransport implements MessagingTransport { - - private final List payloads = new ArrayList<>(); - - List payloads() { - return List.copyOf(payloads); - } - - @Override - public CompletionStage publish(TransportPublishRequest request) { - payloads.add(request.envelope().payload().bytes()); - return CompletableFuture.completedFuture( - new TransportPublishResult( - new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.BROKER_ACK), - RoutingOutcome.ROUTED, - Optional.empty(), - 1, - Duration.ZERO, - Optional.empty()))); - } - - @Override - public TransportConsumerRegistration register(TransportConsumerSpec spec) { - throw new UnsupportedOperationException("the relay only publishes"); - } - - @Override - public DestinationCapabilities capabilities(DestinationName destination) { - throw new UnsupportedOperationException("the relay asks for no publish option"); - } - - @Override - public String brokerName() { - return "fake"; - } - - @Override - public long generation() { - return 1; - } - - @Override - public void close() {} -} diff --git a/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayWorkerTest.java b/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayWorkerTest.java deleted file mode 100644 index 9f71564c..00000000 --- a/src/platforms/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayWorkerTest.java +++ /dev/null @@ -1,178 +0,0 @@ -package dev.caskeleton.messaging.outbox; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.ProducerId; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.publish.ConfirmationLevel; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishEvidence; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.api.publish.RoutingOutcome; -import dev.caskeleton.messaging.reliability.OutboxRecord; -import dev.caskeleton.messaging.reliability.OutboxStatus; -import java.time.Duration; -import java.util.Optional; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import java.util.concurrent.CountDownLatch; -import java.util.concurrent.TimeUnit; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * Whether anything actually drives the relay. - * - *

The relay, its scheduler and the attempt budget were all constructed by the auto-configuration - * and {@code runOnce} was called by no production code. A business transaction would commit its - * outbox row, report success, and the message would never be published — a silent backlog rather - * than a visible failure. - */ -class OutboxRelayWorkerTest { - - private static final Duration PATIENCE = Duration.ofSeconds(5); - - private final InMemoryOutboxRepository repository = new InMemoryOutboxRepository(); - - @Test - @DisplayName("a started worker publishes the backlog without anyone calling a pass") - void aStartedWorkerPublishesTheBacklog() throws InterruptedException { - OutboxRecord record = OutboxFixtures.pending(); - repository.append(record); - OutboxRelayWorker worker = worker(RecordingOutboxPublisher.confirming()); - - worker.start(); - try { - awaitStatus(record, OutboxStatus.PUBLISHED); - } finally { - worker.stop(PATIENCE); - } - - assertThat(repository.find(record.messageId()).orElseThrow().status()) - .isEqualTo(OutboxStatus.PUBLISHED); - assertThat(worker.completedPasses()).isPositive(); - } - - @Test - @DisplayName("stopping waits for the running pass instead of stranding its claimed rows") - void stoppingWaitsForTheRunningPass() throws InterruptedException { - OutboxRecord record = OutboxFixtures.pending(); - repository.append(record); - // The publish is still in progress when stop() is called, so the row is claimed and IN_FLIGHT - // at that moment: the pass has to be allowed to finish or the lease strands the row. - SlowPublisher publisher = new SlowPublisher(Duration.ofMillis(300)); - OutboxRelayWorker worker = worker(publisher); - - worker.start(); - assertThat(publisher.started.await(PATIENCE.toMillis(), TimeUnit.MILLISECONDS)).isTrue(); - boolean drained = worker.stop(PATIENCE); - - assertThat(drained).isTrue(); - assertThat(repository.find(record.messageId()).orElseThrow().status()) - .as("a pass killed between its claim and its terminal write leaves the row leased") - .isEqualTo(OutboxStatus.PUBLISHED); - } - - @Test - @DisplayName("a pass that throws does not stop every pass after it") - void aFailedPassDoesNotEndTheLoop() throws InterruptedException { - OutboxRelayWorker worker = worker(unreachableDatabase(), new ThrowingPublisher()); - - worker.start(); - try { - long deadline = System.nanoTime() + PATIENCE.toNanos(); - while (worker.completedPasses() < 2 && System.nanoTime() < deadline) { - Thread.sleep(10); - } - } finally { - worker.stop(PATIENCE); - } - - assertThat(worker.completedPasses()) - .as("a scheduled task's own exception cancels every future run of it") - .isGreaterThanOrEqualTo(2); - assertThat(worker.failedPasses()).isPositive(); - } - - private OutboxRelayWorker worker(MessagePublisher publisher) { - return worker(repository, publisher); - } - - /** An outbox whose every call fails, as it does while its database is down. */ - private static dev.caskeleton.messaging.reliability.OutboxRepository unreachableDatabase() { - return (dev.caskeleton.messaging.reliability.OutboxRepository) - java.lang.reflect.Proxy.newProxyInstance( - OutboxRelayWorkerTest.class.getClassLoader(), - new Class[] {dev.caskeleton.messaging.reliability.OutboxRepository.class}, - (proxy, method, arguments) -> { - throw new IllegalStateException("the outbox database is unreachable"); - }); - } - - private static OutboxRelayWorker worker( - dev.caskeleton.messaging.reliability.OutboxRepository outbox, MessagePublisher publisher) { - OutboxRelay relay = - new OutboxRelay( - outbox, - publisher, - new OutboxEnvelopeFactory(new ProducerId("order-api")), - 100, - Duration.ofSeconds(30)); - return new OutboxRelayWorker(relay, OutboxRetryScheduler.standard()); - } - - private void awaitStatus(OutboxRecord record, OutboxStatus expected) throws InterruptedException { - long deadline = System.nanoTime() + PATIENCE.toNanos(); - while (System.nanoTime() < deadline) { - if (repository.find(record.messageId()).map(OutboxRecord::status).orElse(null) == expected) { - return; - } - Thread.sleep(10); - } - } - - /** A publisher that is still publishing when shutdown begins. */ - private static final class SlowPublisher implements MessagePublisher { - - private final CountDownLatch started = new CountDownLatch(1); - - private final Duration duration; - - private SlowPublisher(Duration duration) { - this.duration = duration; - } - - @Override - public CompletionStage publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - started.countDown(); - try { - Thread.sleep(duration.toMillis()); - } catch (InterruptedException interrupted) { - Thread.currentThread().interrupt(); - } - return CompletableFuture.completedFuture( - new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.BROKER_ACK), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ofMillis(1), - Optional.empty())); - } - } - - /** A publisher whose failure reaches the worker as an exception rather than a result. */ - private static final class ThrowingPublisher implements MessagePublisher { - - @Override - public CompletionStage publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - throw new IllegalStateException("the broker connection is gone"); - } - } -} diff --git a/src/platforms/messaging/messaging-runtime-core/build.gradle b/src/platforms/messaging/messaging-runtime-core/build.gradle deleted file mode 100644 index 06c462f0..00000000 --- a/src/platforms/messaging/messaging-runtime-core/build.gradle +++ /dev/null @@ -1,18 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -// The central publish and delivery orchestration. -// -// MessagePublisher was an interface with no implementation anywhere in the new platform: the -// brokers implemented MessagingTransport, the core auto-configuration built dead-letter and facade -// beans on top of a publisher bean that nothing supplied, and admission, security, runtime leases -// and observation existed as beans that no publish path ever called. A starter that filled the gap -// with an application-supplied fake would pass a context test while running none of them. -dependencies { - api project(':messaging:messaging-core-api') - api project(':messaging:messaging-policy') - api project(':messaging:messaging-transport-spi') - api project(':messaging:messaging-security') - api project(':messaging:messaging-observability') -} diff --git a/src/platforms/messaging/messaging-runtime-core/gradle.lockfile b/src/platforms/messaging/messaging-runtime-core/gradle.lockfile deleted file mode 100644 index dcab1d05..00000000 --- a/src/platforms/messaging/messaging-runtime-core/gradle.lockfile +++ /dev/null @@ -1,87 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.21.0=spotbugs -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor -io.micrometer:micrometer-commons:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-core:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-observation:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath -org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.hdrhistogram:HdrHistogram:2.2.2=runtimeClasspath,testRuntimeClasspath -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath -org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.latencyutils:LatencyUtils:2.0.3=runtimeClasspath,testRuntimeClasspath -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DeclaredDestinationAccess.java b/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DeclaredDestinationAccess.java deleted file mode 100644 index 2c6a125d..00000000 --- a/src/platforms/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DeclaredDestinationAccess.java +++ /dev/null @@ -1,48 +0,0 @@ -package dev.caskeleton.messaging.runtime; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.security.DestinationAccessPolicy; -import java.util.Map; -import java.util.Objects; -import java.util.Set; - -/** - * The access policy a deployment gets when it has not written one (MSG-INT-003). - * - *

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

    - *
  • Deny everything and the platform assembles, starts, and refuses every publish — a - * deployment that configured its destinations correctly still cannot send, and the error - * names an access policy nobody knew they had to write. - *
  • Allow everything and the check is decoration. The policy exists because relying on - * broker ACLs alone means an accidental publish surfaces as a generic authorization error at - * runtime, in the adapter, with no record of which application module attempted it. - *
- * - *

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

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

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

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

    - *
  • One terminal call. A delivery is acknowledged, requeued or discarded once. - * Acknowledging after a requeue tells the broker the message is done while a copy is already - * in flight. - *
  • Acknowledge only after success. {@code Success} acknowledges; a handler - * that throws, fails its stage or returns nothing is requeued, not discarded. - *
  • Dead letter before acknowledgement. The source is acknowledged only after - * the dead-letter publish is confirmed; an unconfirmed one requeues, because a duplicate is - * the recoverable half of that choice. - *
  • Discard only where the profile allows it. {@code Reject} discards on an - * {@code AT_MOST_ONCE} destination and is dead-lettered everywhere else (design §19.2). - *
  • Undecodable is not retryable. A message whose type has no handler, or - * whose payload the codec refuses, is dead-lettered rather than retried forever. - *
- * - *

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

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

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

    - *
  • destination and access first, so an unauthorized publish never encodes a payload; - *
  • encoding before admission, because the admission bound is on bytes and the byte count is - * not known until the payload is encoded; - *
  • the runtime lease last before the send, so a rotation cannot swap the transport underneath - * a message that has already been counted against the in-flight limit. - *
- * - *

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

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

The transports accept {@code request.options()} and read nothing from it, so an option this - * destination cannot honour has to be refused here or it is honoured nowhere. A caller asking for - * broker-side deduplication got a publish with no deduplication and no error, and then skipped - * the idempotency it would otherwise have written — which is exactly the case {@code - * PublishDeduplication}'s own javadoc says must be a startup failure rather than a silent no-op. - */ - private void requireSupportedOptions(DestinationProfile profile, PublishOptions options) { - if (options.deduplication().isPresent() - && !transport - .capabilities(profile.name()) - .capabilities() - .supports( - dev.caskeleton.messaging.api.destination.MessagingCapabilities.Capability - .DEDUPLICATED_PUBLISH)) { - throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException( - "PUBLISH_DEDUPLICATION_UNSUPPORTED", - "destination '" - + profile.name().value() - + "' runs on a broker that does not suppress duplicate publishes of a stable id;" - + " the caller must keep its own idempotency rather than believing this request"); - } - } - - /** Records one publish against bounded dimensions: broker, destination, operation, outcome. */ - private void observe(DestinationProfile profile, PublishResult result, long startedAt) { - observation.recordPublish( - dev.caskeleton.messaging.observation.MessagingTags.of( - profile.broker(), - profile.name().value(), - "publish", - result.completion().name().toLowerCase(java.util.Locale.ROOT)), - elapsedSince(startedAt)); - } - - private MessageEnvelope encode(MessageEnvelope message) { - // The outbox relay, dead lettering and the retry topic republish bytes a codec already wrote. - // Encoding them again handed the codec a payload that is not its type, so each such publish was - // REJECTED (or, with a lenient codec, sent the envelope's toString). They go out as they are. - if (message.payload() instanceof EncodedMessage alreadyEncoded) { - MessageEnvelope encoded = message.withPayload(alreadyEncoded); - requireEncodedEnvelope(encoded); - return encoded; - } - MessageCodec codec = codecs.find(message.contentType()).orElseGet(codecs::defaultCodec); - EncodedMessage bytes = - codec.encode(message.messageType(), message.schemaVersion(), message.payload()); - return message.withPayload(bytes); - } - - private CompletionStage rejected(String code, String reason, long startedAt) { - return refused( - new FailureDescriptor(FailureCategory.CONFIGURATION, code, false, reason, Optional.empty()), - startedAt); - } - - private CompletionStage refused(FailureDescriptor failure, long startedAt) { - return CompletableFuture.completedFuture( - PublishResult.rejected(elapsedSince(startedAt), failure)); - } - - private PublishResult ambiguousResult(String code, String reason, long startedAt) { - return PublishResult.ambiguous( - elapsedSince(startedAt), - new FailureDescriptor(FailureCategory.AMBIGUOUS, code, true, reason, Optional.empty())); - } - - /** - * Returns what is left of the caller's deadline. - * - *

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

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

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

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

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

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

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

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

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

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

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

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

{@code MessageCodecRegistry} was an interface with no implementation anywhere — declared, - * consumed by the publisher's constructor, and satisfiable by nothing. That is why the platform - * could not assemble a publisher although every piece around it existed and was tested. - */ -class RegisteredMessageCodecsTest { - - @Test - @DisplayName("the default codec is the one the deployment named") - void theDefaultCodecIsTheOneNamed() { - MessageCodec json = codec(ContentType.JSON); - MessageCodec avro = codec(ContentType.AVRO); - - assertThat(RegisteredMessageCodecs.of(json, avro).defaultCodec()) - .as( - "selecting by iteration order makes the wire format depend on how a map was populated — " - + "a format decision taken by accident") - .isSameAs(json); - } - - @Test - @DisplayName("a registered content type resolves, an unregistered one does not") - void aRegisteredContentTypeResolves() { - RegisteredMessageCodecs codecs = - RegisteredMessageCodecs.of(codec(ContentType.JSON), codec(ContentType.AVRO)); - - assertThat(codecs.find(ContentType.AVRO)).isPresent(); - assertThat(codecs.find(ContentType.PROTOBUF)) - .as("absent rather than falling back: a silent fallback re-encodes somebody's message") - .isEmpty(); - } - - @Test - @DisplayName("raw bytes cannot be the default") - void rawBytesCannotBeTheDefault() { - assertThatThrownBy(() -> RegisteredMessageCodecs.of(codec(ContentType.OCTET_STREAM))) - .as( - "a destination that forgot to declare an encoding would silently skip schema " - + "validation, which turns a missing declaration into a skipped check") - .hasMessageContaining("raw bytes codec must not be the default"); - } - - @Test - @DisplayName("two codecs claiming one content type is a configuration error") - void twoCodecsForOneContentTypeIsRefused() { - assertThatThrownBy( - () -> RegisteredMessageCodecs.of(codec(ContentType.JSON), codec(ContentType.JSON))) - .as( - "whichever won would decide how bytes on the wire are read by a consumer compiled " - + "against the other") - .hasMessageContaining("two codecs claim content type"); - } - - private static MessageCodec codec(ContentType contentType) { - return new MessageCodec() { - @Override - public ContentType contentType() { - return contentType; - } - - @Override - public EncodedMessage encode(MessageType type, SchemaVersion version, Object payload) { - throw new UnsupportedOperationException("registry test; nothing is encoded"); - } - - @Override - public T decode( - MessageType type, SchemaVersion version, byte[] bytes, Class payloadType) { - throw new UnsupportedOperationException("registry test; nothing is decoded"); - } - }; - } -} diff --git a/src/platforms/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/RuntimeFixtures.java b/src/platforms/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/RuntimeFixtures.java deleted file mode 100644 index d341d54f..00000000 --- a/src/platforms/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/RuntimeFixtures.java +++ /dev/null @@ -1,44 +0,0 @@ -package dev.caskeleton.messaging.runtime; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.policy.ApiTier; -import dev.caskeleton.messaging.policy.ConsumerPolicy; -import dev.caskeleton.messaging.policy.DeadLetterPolicy; -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.policy.PayloadPolicy; -import dev.caskeleton.messaging.policy.PhysicalDestination; -import dev.caskeleton.messaging.policy.ProducerPolicy; -import dev.caskeleton.messaging.schema.SchemaCompatibility; -import java.util.Set; - -/** One registered destination, so the pipeline has something real to resolve. */ -final class RuntimeFixtures { - - private RuntimeFixtures() {} - - static DestinationProfile profile(DestinationName name) { - return new DestinationProfile( - name, - "fake", - dev.caskeleton.messaging.api.destination.DestinationKind.EVENT_STREAM, - PhysicalDestination.kafkaTopic("order.events.v1"), - new dev.caskeleton.messaging.policy.SchemaPolicy( - ContentType.JSON, - SchemaCompatibility.BACKWARD_TRANSITIVE, - Set.of(new MessageType("order.created"))), - dev.caskeleton.messaging.api.delivery.DeliveryGuarantee.AT_LEAST_ONCE, - dev.caskeleton.messaging.api.delivery.OrderingScope.NONE, - dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED, - ProducerPolicy.defaults(), - ConsumerPolicy.defaults("order-projection"), - dev.caskeleton.messaging.policy.RetryPolicy.none(), - DeadLetterPolicy.to(new DestinationName("order-events-dlq")), - PayloadPolicy.defaults(), - ApiTier.M1, - false, - false, - false); - } -} diff --git a/src/platforms/messaging/messaging-schema-avro/build.gradle b/src/platforms/messaging/messaging-schema-avro/build.gradle deleted file mode 100644 index b1e8f846..00000000 --- a/src/platforms/messaging/messaging-schema-avro/build.gradle +++ /dev/null @@ -1,12 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') - - // api: AvroMessageCodec's constructors take a registry of org.apache.avro.Schema and - // AvroCompatibilityGate.check takes and compares them. A consumer cannot build that - // registry without naming the type, so hiding the dependency only stops them compiling. - api libs.avro -} diff --git a/src/platforms/messaging/messaging-schema-avro/gradle.lockfile b/src/platforms/messaging/messaging-schema-avro/gradle.lockfile deleted file mode 100644 index d2453d60..00000000 --- a/src/platforms/messaging/messaging-schema-avro/gradle.lockfile +++ /dev/null @@ -1,90 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.fasterxml.jackson.core:jackson-annotations:2.21=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -com.fasterxml.jackson.core:jackson-core:2.21.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -com.fasterxml.jackson.core:jackson-databind:2.21.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -com.fasterxml.jackson:jackson-bom:2.21.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-codec:commons-codec:1.19.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.16.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -commons-io:commons-io:2.21.0=spotbugs -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor -javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.avro:avro:1.12.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-compress:1.26.2=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.apache.commons:commons-lang3:3.20.0=checkstyle,compileClasspath,runtimeClasspath,spotbugs,testCompileClasspath,testRuntimeClasspath -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath -org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath -org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.20=compileClasspath,runtimeClasspath,spotbugs,spotbugsSlf4j,testCompileClasspath,testRuntimeClasspath -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-schema-avro/src/main/java/dev/caskeleton/messaging/schema/avro/AvroCompatibilityGate.java b/src/platforms/messaging/messaging-schema-avro/src/main/java/dev/caskeleton/messaging/schema/avro/AvroCompatibilityGate.java deleted file mode 100644 index 853c33db..00000000 --- a/src/platforms/messaging/messaging-schema-avro/src/main/java/dev/caskeleton/messaging/schema/avro/AvroCompatibilityGate.java +++ /dev/null @@ -1,73 +0,0 @@ -package dev.caskeleton.messaging.schema.avro; - -import dev.caskeleton.messaging.api.error.MessageSchemaIncompatibleException; -import dev.caskeleton.messaging.schema.SchemaCompatibility; -import java.util.List; -import java.util.Objects; -import org.apache.avro.Schema; -import org.apache.avro.SchemaCompatibility.SchemaPairCompatibility; - -/** - * Refuses an Avro schema change that would break the destination's declared compatibility mode. - * - *

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

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

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

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

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

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

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

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

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

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

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

{@code decodeEvolved} is the path every consumer takes when a producer moves ahead a version. - * It checked no size at all, so the bound that made the ordinary decode safe simply did not apply - * to the case it mattered most for. - */ -class AvroRegistryBoundsTest { - - private static final MessageType ORDER_CREATED = new MessageType("order.created"); - private static final SchemaVersion V1 = new SchemaVersion(1); - private static final SchemaVersion V2 = new SchemaVersion(2); - - private static final Schema V1_SCHEMA = - new Schema.Parser() - .parse( - """ - { - "type": "record", - "name": "OrderCreated", - "namespace": "dev.caskeleton.messaging.sample", - "fields": [ - {"name": "orderId", "type": "string"}, - {"name": "note", "type": "string", "default": ""} - ] - } - """); - - private static final Schema V2_SCHEMA = - new Schema.Parser() - .parse( - """ - { - "type": "record", - "name": "OrderCreated", - "namespace": "dev.caskeleton.messaging.sample", - "fields": [ - {"name": "orderId", "type": "string"}, - {"name": "note", "type": "string", "default": ""}, - {"name": "channel", "type": "string", "default": "WEB"} - ] - } - """); - - @Test - @DisplayName("mutating the map after construction does not change what the codec decodes") - void mutatingTheCallersMapAfterConstructionChangesNothing() { - Map versions = new HashMap<>(Map.of(V1, V1_SCHEMA)); - Map> registry = new HashMap<>(); - registry.put(ORDER_CREATED, versions); - AvroMessageCodec codec = new AvroMessageCodec(registry); - - versions.put(V1, V2_SCHEMA); - versions.put(V2, V2_SCHEMA); - registry.put(new MessageType("order.cancelled"), Map.of(V1, V1_SCHEMA)); - - assertThatThrownBy(() -> codec.encode(ORDER_CREATED, V2, record(V2_SCHEMA))) - .as("a version added after construction is not registered") - .isInstanceOf(MessageValidationException.class); - assertThatThrownBy( - () -> codec.encode(new MessageType("order.cancelled"), V1, record(V1_SCHEMA))) - .isInstanceOf(MessageValidationException.class); - assertThatCode(() -> codec.encode(ORDER_CREATED, V1, record(V1_SCHEMA))) - .as("the schema registered at construction is still the one in force") - .doesNotThrowAnyException(); - } - - @Test - @DisplayName("an oversized payload is refused while encoding, not after") - void anOversizedPayloadIsRefusedWhileEncoding() { - AvroMessageCodec codec = new AvroMessageCodec(Map.of(ORDER_CREATED, Map.of(V1, V1_SCHEMA)), 64); - GenericRecord large = record(V1_SCHEMA); - large.put("note", "n".repeat(4_000_000)); - - assertThatThrownBy(() -> codec.encode(ORDER_CREATED, V1, large)) - .isInstanceOf(MessageTooLargeException.class) - .hasMessageContaining("refused at byte"); - } - - @Test - @DisplayName("the evolution decode applies the same bound as the ordinary decode") - void theEvolutionDecodeAppliesTheSameBound() { - AvroMessageCodec codec = - new AvroMessageCodec(Map.of(ORDER_CREATED, Map.of(V1, V1_SCHEMA, V2, V2_SCHEMA)), 32); - - assertThatThrownBy(() -> codec.decodeEvolved(ORDER_CREATED, V1, V2, new byte[4_096])) - .as("decodeEvolved accepted input of any size") - .isInstanceOf(MessageTooLargeException.class); - } - - @Test - @DisplayName("a payload at exactly the limit still encodes") - void aPayloadAtExactlyTheLimitStillEncodes() { - AvroMessageCodec unbounded = new AvroMessageCodec(Map.of(ORDER_CREATED, Map.of(V1, V1_SCHEMA))); - int exact = unbounded.encode(ORDER_CREATED, V1, record(V1_SCHEMA)).bytes().length; - AvroMessageCodec bounded = - new AvroMessageCodec(Map.of(ORDER_CREATED, Map.of(V1, V1_SCHEMA)), exact); - - assertThat(bounded.encode(ORDER_CREATED, V1, record(V1_SCHEMA)).bytes()).hasSize(exact); - - AvroMessageCodec oneShort = - new AvroMessageCodec(Map.of(ORDER_CREATED, Map.of(V1, V1_SCHEMA)), exact - 1); - assertThatThrownBy(() -> oneShort.encode(ORDER_CREATED, V1, record(V1_SCHEMA))) - .isInstanceOf(MessageTooLargeException.class); - } - - private static GenericRecord record(Schema schema) { - GenericRecord record = new GenericData.Record(schema); - record.put("orderId", "o-1"); - record.put("note", ""); - if (schema.getField("channel") != null) { - record.put("channel", "WEB"); - } - return record; - } -} diff --git a/src/platforms/messaging/messaging-schema-avro/src/test/resources/schemas/order.created/v1.avsc b/src/platforms/messaging/messaging-schema-avro/src/test/resources/schemas/order.created/v1.avsc deleted file mode 100644 index 2d12c31e..00000000 --- a/src/platforms/messaging/messaging-schema-avro/src/test/resources/schemas/order.created/v1.avsc +++ /dev/null @@ -1,11 +0,0 @@ -{ - "type": "record", - "name": "OrderCreated", - "namespace": "dev.caskeleton.messaging.sample", - "fields": [ - { "name": "orderId", "type": "string" }, - { "name": "customerId", "type": "string" }, - { "name": "totalMinorUnits", "type": "long" }, - { "name": "currency", "type": "string" } - ] -} diff --git a/src/platforms/messaging/messaging-schema-json/build.gradle b/src/platforms/messaging/messaging-schema-json/build.gradle deleted file mode 100644 index e87b8c57..00000000 --- a/src/platforms/messaging/messaging-schema-json/build.gradle +++ /dev/null @@ -1,9 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') - - implementation 'tools.jackson.core:jackson-databind' -} diff --git a/src/platforms/messaging/messaging-schema-json/gradle.lockfile b/src/platforms/messaging/messaging-schema-json/gradle.lockfile deleted file mode 100644 index 49c04447..00000000 --- a/src/platforms/messaging/messaging-schema-json/gradle.lockfile +++ /dev/null @@ -1,86 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.fasterxml.jackson.core:jackson-annotations:2.21=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.21.0=spotbugs -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor -javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath -org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath -org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -tools.jackson.core:jackson-core:3.1.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -tools.jackson.core:jackson-databind:3.1.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -tools.jackson:jackson-bom:3.1.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -empty= diff --git a/src/platforms/messaging/messaging-schema-json/src/main/java/dev/caskeleton/messaging/schema/json/JacksonMessageCodec.java b/src/platforms/messaging/messaging-schema-json/src/main/java/dev/caskeleton/messaging/schema/json/JacksonMessageCodec.java deleted file mode 100644 index 71fe012f..00000000 --- a/src/platforms/messaging/messaging-schema-json/src/main/java/dev/caskeleton/messaging/schema/json/JacksonMessageCodec.java +++ /dev/null @@ -1,226 +0,0 @@ -package dev.caskeleton.messaging.schema.json; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageSerializationException; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import dev.caskeleton.messaging.api.error.MessageValidationException; -import dev.caskeleton.messaging.schema.BoundedByteSink; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.schema.MessageCodec; -import dev.caskeleton.messaging.schema.MessageContractKey; -import dev.caskeleton.messaging.schema.SchemaReference; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; -import tools.jackson.core.JacksonException; -import tools.jackson.core.StreamReadConstraints; -import tools.jackson.core.StreamReadFeature; -import tools.jackson.core.json.JsonFactory; -import tools.jackson.databind.DeserializationFeature; -import tools.jackson.databind.ObjectMapper; -import tools.jackson.databind.json.JsonMapper; - -/** - * The Stable JSON codec. - * - *

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

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

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

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

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

The budgets are generous on purpose. The regression worth catching here is structural — an - * accidental per-message reflection call, a defensive copy that became a deep copy, a validator - * that started compiling a regex per invocation — and those cost orders of magnitude, not - * percentages. A tight budget would instead catch a busy CI agent. - */ -class PlatformOverheadPerformanceTest { - - private static final MessageType ORDER_CREATED = new MessageType("order.created"); - private static final SchemaVersion V1 = new SchemaVersion(1); - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - private static final int WARMUP = 5_000; - private static final int MEASURED = 50_000; - - /** Generous enough that only a structural regression trips it. */ - private static final Duration ENVELOPE_BUDGET_PER_MESSAGE = Duration.ofNanos(20_000); - - private static final Duration ENCODE_BUDGET_PER_MESSAGE = Duration.ofNanos(50_000); - - record OrderCreated(String orderId, long amount) {} - - @Test - void envelopeConstructionStaysWellUnderItsBudget() { - for (int i = 0; i < WARMUP; i++) { - envelope(new byte[64]); - } - - long startedAt = System.nanoTime(); - for (int i = 0; i < MEASURED; i++) { - envelope(new byte[64]); - } - Duration perMessage = Duration.ofNanos((System.nanoTime() - startedAt) / MEASURED); - - assertThat(perMessage) - .as("envelope construction per message: %s", perMessage) - .isLessThan(ENVELOPE_BUDGET_PER_MESSAGE); - } - - @Test - void jsonEncodingStaysWellUnderItsBudget() { - JacksonMessageCodec codec = - JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class); - OrderCreated payload = new OrderCreated("o-1", 1000); - - for (int i = 0; i < WARMUP; i++) { - codec.encode(ORDER_CREATED, V1, payload); - } - - long startedAt = System.nanoTime(); - for (int i = 0; i < MEASURED; i++) { - codec.encode(ORDER_CREATED, V1, payload); - } - Duration perMessage = Duration.ofNanos((System.nanoTime() - startedAt) / MEASURED); - - assertThat(perMessage) - .as("JSON encode per message: %s", perMessage) - .isLessThan(ENCODE_BUDGET_PER_MESSAGE); - } - - @Test - void aRoundTripDoesNotAllocateAGrowingRetainedSet() { - JacksonMessageCodec codec = - JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class); - OrderCreated payload = new OrderCreated("o-1", 1000); - - for (int i = 0; i < WARMUP; i++) { - byte[] encoded = codec.encode(ORDER_CREATED, V1, payload).bytes(); - codec.decode(ORDER_CREATED, V1, encoded, OrderCreated.class); - } - - Runtime runtime = Runtime.getRuntime(); - System.gc(); - long before = runtime.totalMemory() - runtime.freeMemory(); - - for (int i = 0; i < MEASURED; i++) { - byte[] encoded = codec.encode(ORDER_CREATED, V1, payload).bytes(); - codec.decode(ORDER_CREATED, V1, encoded, OrderCreated.class); - } - - System.gc(); - long after = runtime.totalMemory() - runtime.freeMemory(); - long retainedPerMessage = Math.max(0, after - before) / MEASURED; - - assertThat(retainedPerMessage) - .as( - "the codec must not retain per-message state; retained %d bytes/message", - retainedPerMessage) - .isLessThan(64); - } - - private static MessageEnvelope envelope(byte[] payload) { - return new MessageEnvelope<>( - MessageId.newId(), - ORDER_CREATED, - V1, - NOW, - Optional.of(NOW), - new ProducerId("order-api"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.of("acct-1"), - Optional.of("acct-1"), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - new EncodedMessage(payload, ContentType.JSON, Optional.empty())); - } -} diff --git a/src/platforms/messaging/messaging-schema-protobuf/build.gradle b/src/platforms/messaging/messaging-schema-protobuf/build.gradle deleted file mode 100644 index 58f78aac..00000000 --- a/src/platforms/messaging/messaging-schema-protobuf/build.gradle +++ /dev/null @@ -1,11 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') - - // api: ProtobufMessageContract is a public record over com.google.protobuf.Message and - // Parser, and registering a contract is the first thing a consumer of this codec does. - api libs.protobuf.java -} diff --git a/src/platforms/messaging/messaging-schema-protobuf/gradle.lockfile b/src/platforms/messaging/messaging-schema-protobuf/gradle.lockfile deleted file mode 100644 index af31c973..00000000 --- a/src/platforms/messaging/messaging-schema-protobuf/gradle.lockfile +++ /dev/null @@ -1,82 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.21.0=spotbugs -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor -javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath -org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath -org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-schema-protobuf/src/main/java/dev/caskeleton/messaging/schema/protobuf/ProtobufMessageCodec.java b/src/platforms/messaging/messaging-schema-protobuf/src/main/java/dev/caskeleton/messaging/schema/protobuf/ProtobufMessageCodec.java deleted file mode 100644 index c151c636..00000000 --- a/src/platforms/messaging/messaging-schema-protobuf/src/main/java/dev/caskeleton/messaging/schema/protobuf/ProtobufMessageCodec.java +++ /dev/null @@ -1,146 +0,0 @@ -package dev.caskeleton.messaging.schema.protobuf; - -import com.google.protobuf.InvalidProtocolBufferException; -import com.google.protobuf.Message; -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.error.MessageSerializationException; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import dev.caskeleton.messaging.api.error.MessageValidationException; -import dev.caskeleton.messaging.schema.BoundedByteSink; -import dev.caskeleton.messaging.schema.EncodedMessage; -import dev.caskeleton.messaging.schema.MessageCodec; -import dev.caskeleton.messaging.schema.MessageContractKey; -import dev.caskeleton.messaging.schema.SchemaReference; -import java.io.IOException; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; - -/** - * The optional Protobuf codec. - * - *

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

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

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

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

Descriptors are built at runtime rather than generated by protoc. The properties under test — - * that a reader keyed on tag numbers survives a rename, that an added field decodes as its default, - * and that reusing a tag corrupts the read — are properties of the wire format, so proving them - * without a code-generation step keeps the test honest and the build free of a protoc toolchain. - */ -class ProtobufCompatibilityTest { - - private static final MessageType ORDER_CREATED = new MessageType("order.created"); - private static final SchemaVersion V1 = new SchemaVersion(1); - private static final SchemaVersion V2 = new SchemaVersion(2); - - private static final Descriptor V1_DESCRIPTOR = - descriptor( - "OrderCreatedV1", - field("order_id", 1, FieldDescriptorProto.Type.TYPE_STRING), - field("customer_id", 2, FieldDescriptorProto.Type.TYPE_STRING), - field("total_minor_units", 3, FieldDescriptorProto.Type.TYPE_INT64), - field("currency", 4, FieldDescriptorProto.Type.TYPE_STRING)); - - /** v2 renames tag 4 and appends tag 5: both are wire-compatible changes. */ - private static final Descriptor V2_DESCRIPTOR = - descriptor( - "OrderCreatedV2", - field("order_id", 1, FieldDescriptorProto.Type.TYPE_STRING), - field("customer_id", 2, FieldDescriptorProto.Type.TYPE_STRING), - field("total_minor_units", 3, FieldDescriptorProto.Type.TYPE_INT64), - field("currency_code", 4, FieldDescriptorProto.Type.TYPE_STRING), - field("channel", 5, FieldDescriptorProto.Type.TYPE_STRING)); - - /** The forbidden change: tag 4 is reused for a different type. */ - private static final Descriptor TAG_REUSE_DESCRIPTOR = - descriptor( - "OrderCreatedTagReuse", - field("order_id", 1, FieldDescriptorProto.Type.TYPE_STRING), - field("customer_id", 2, FieldDescriptorProto.Type.TYPE_STRING), - field("total_minor_units", 3, FieldDescriptorProto.Type.TYPE_INT64), - field("discount_minor_units", 4, FieldDescriptorProto.Type.TYPE_INT64)); - - private static FieldDescriptorProto field( - String name, int number, FieldDescriptorProto.Type type) { - return FieldDescriptorProto.newBuilder() - .setName(name) - .setNumber(number) - .setType(type) - .setLabel(FieldDescriptorProto.Label.LABEL_OPTIONAL) - .build(); - } - - private static Descriptor descriptor(String name, FieldDescriptorProto... fields) { - DescriptorProto.Builder message = DescriptorProto.newBuilder().setName(name); - for (FieldDescriptorProto field : fields) { - message.addField(field); - } - FileDescriptorProto file = - FileDescriptorProto.newBuilder() - .setName(name + ".proto") - .setSyntax("proto3") - .setPackage("dev.caskeleton.messaging.sample") - .addMessageType(message) - .build(); - try { - return FileDescriptor.buildFrom(file, new FileDescriptor[0]).getMessageTypes().get(0); - } catch (DescriptorValidationException failure) { - throw new IllegalStateException("could not build the test descriptor", failure); - } - } - - private static ProtobufMessageCodec codec(Descriptor descriptor) { - return codec(descriptor, V1); - } - - private static ProtobufMessageCodec codec(Descriptor descriptor, SchemaVersion version) { - return new ProtobufMessageCodec( - Map.of(new MessageContractKey(ORDER_CREATED, version), contract(descriptor))); - } - - private static ProtobufMessageContract contract(Descriptor descriptor) { - Parser parser = - DynamicMessage.getDefaultInstance(descriptor).getParserForType(); - return new ProtobufMessageContract(DynamicMessage.class, parser); - } - - private static DynamicMessage v1Message() { - return DynamicMessage.newBuilder(V1_DESCRIPTOR) - .setField(V1_DESCRIPTOR.findFieldByNumber(1), "o-1") - .setField(V1_DESCRIPTOR.findFieldByNumber(2), "c-1") - .setField(V1_DESCRIPTOR.findFieldByNumber(3), 12_500L) - .setField(V1_DESCRIPTOR.findFieldByNumber(4), "KRW") - .build(); - } - - @Test - void aRoundTripPreservesEveryField() { - ProtobufMessageCodec codec = codec(V1_DESCRIPTOR); - - EncodedMessage encoded = codec.encode(ORDER_CREATED, V1, v1Message()); - DynamicMessage decoded = codec.decode(ORDER_CREATED, V1, encoded.bytes(), DynamicMessage.class); - - assertThat(decoded.getField(V1_DESCRIPTOR.findFieldByNumber(1))).isEqualTo("o-1"); - assertThat(decoded.getField(V1_DESCRIPTOR.findFieldByNumber(3))).isEqualTo(12_500L); - assertThat(encoded.contentType()).isEqualTo(ContentType.PROTOBUF); - } - - @Test - void renamingAFieldKeepsItsValueBecauseTheTagNumberIsTheContract() throws Exception { - byte[] wire = codec(V1_DESCRIPTOR).encode(ORDER_CREATED, V1, v1Message()).bytes(); - - DynamicMessage asV2 = DynamicMessage.parseFrom(V2_DESCRIPTOR, wire); - - assertThat(asV2.getField(V2_DESCRIPTOR.findFieldByName("currency_code"))) - .as("the name changed, the tag did not, so the value survives") - .isEqualTo("KRW"); - } - - @Test - void anAddedFieldDecodesAsItsDefaultForAnOldWriter() throws Exception { - byte[] wire = codec(V1_DESCRIPTOR).encode(ORDER_CREATED, V1, v1Message()).bytes(); - - DynamicMessage asV2 = DynamicMessage.parseFrom(V2_DESCRIPTOR, wire); - - assertThat(asV2.getField(V2_DESCRIPTOR.findFieldByName("channel"))) - .as("proto3 scalars are optional on the wire, so an absent field is the default") - .isEqualTo(""); - } - - @Test - void aNewWriterIsStillReadableByAnOldReader() throws Exception { - DynamicMessage v2 = - DynamicMessage.newBuilder(V2_DESCRIPTOR) - .setField(V2_DESCRIPTOR.findFieldByNumber(1), "o-2") - .setField(V2_DESCRIPTOR.findFieldByNumber(4), "USD") - .setField(V2_DESCRIPTOR.findFieldByNumber(5), "APP") - .build(); - - DynamicMessage asV1 = DynamicMessage.parseFrom(V1_DESCRIPTOR, v2.toByteArray()); - - assertThat(asV1.getField(V1_DESCRIPTOR.findFieldByNumber(4))).isEqualTo("USD"); - assertThat(asV1.getUnknownFields().hasField(5)) - .as("the unrecognised field is retained, not dropped, so a round trip does not lose it") - .isTrue(); - } - - @Test - void reusingATagNumberCorruptsTheReadWhichIsWhyTagsAreNeverRecycled() throws Exception { - byte[] wire = codec(V1_DESCRIPTOR).encode(ORDER_CREATED, V1, v1Message()).bytes(); - - DynamicMessage reused = DynamicMessage.parseFrom(TAG_REUSE_DESCRIPTOR, wire); - - assertThat(reused.getField(TAG_REUSE_DESCRIPTOR.findFieldByName("discount_minor_units"))) - .as("the string bytes on tag 4 are not a valid int64, so the value is lost entirely") - .isEqualTo(0L); - } - - @Test - void anUnregisteredTypeIsRejectedRatherThanGuessed() { - ProtobufMessageCodec codec = codec(V1_DESCRIPTOR); - - assertThatThrownBy(() -> codec.encode(new MessageType("unknown.event"), V1, v1Message())) - .isInstanceOf(MessageValidationException.class); - } - - @Test - void anUnregisteredVersionIsRejectedRatherThanDecodedWithAnotherVersionsParser() { - ProtobufMessageCodec codec = codec(V1_DESCRIPTOR); - byte[] wire = codec.encode(ORDER_CREATED, V1, v1Message()).bytes(); - - assertThatThrownBy(() -> codec.decode(ORDER_CREATED, V2, wire, DynamicMessage.class)) - .as( - "keyed on the type alone, v2 would have decoded with the v1 parser and kept the v2 label") - .isInstanceOf(MessageValidationException.class) - .hasMessageContaining("order.created v2"); - } - - @Test - void aParserThatDoesNotProduceTheDeclaredClassIsRejectedAtConstruction() { - Parser parser = - DynamicMessage.getDefaultInstance(V1_DESCRIPTOR).getParserForType(); - - assertThatThrownBy(() -> new ProtobufMessageContract(FileDescriptorProto.class, parser)) - .as("the mismatch used to surface as a ClassCastException on a broker thread") - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("produces"); - } - - @Test - void anOversizedPayloadIsRefusedBeforeItIsSerialized() { - ProtobufMessageCodec codec = - new ProtobufMessageCodec( - Map.of(new MessageContractKey(ORDER_CREATED, V1), contract(V1_DESCRIPTOR)), 16); - - assertThatThrownBy(() -> codec.encode(ORDER_CREATED, V1, v1Message())) - .isInstanceOf(MessageTooLargeException.class) - .hasMessageContaining("refused at byte"); - } - - @Test - void aPayloadAtExactlyTheLimitIsAccepted() { - int exact = v1Message().getSerializedSize(); - ProtobufMessageCodec codec = - new ProtobufMessageCodec( - Map.of(new MessageContractKey(ORDER_CREATED, V1), contract(V1_DESCRIPTOR)), exact); - - assertThat(codec.encode(ORDER_CREATED, V1, v1Message()).bytes()).hasSize(exact); - } - - @Test - void aLengthPrefixNoPayloadOfThisSizeCouldHonourIsADecodeFailure() { - ProtobufMessageCodec codec = codec(V1_DESCRIPTOR); - // Tag 1, wire type 2 (length-delimited), then a varint claiming four hundred million bytes - // follow. The whole message is six bytes, so it passes the size limit; what must not happen is - // the parser reserving the claimed length before discovering there is nothing behind it. - byte[] hostile = {0x0A, (byte) 0x80, (byte) 0x88, (byte) 0xDE, (byte) 0xBE, 0x01}; - - assertThatThrownBy(() -> codec.decode(ORDER_CREATED, V1, hostile, DynamicMessage.class)) - .isInstanceOf(MessageSerializationException.class) - .hasMessageContaining("protobuf"); - } - - @Test - void theEncodedMessageCarriesItsSchemaReference() { - EncodedMessage encoded = codec(V1_DESCRIPTOR, V2).encode(ORDER_CREATED, V2, v1Message()); - - assertThat(encoded.schemaReference()) - .hasValueSatisfying(reference -> assertThat(reference.version()).isEqualTo(V2)); - } -} diff --git a/src/platforms/messaging/messaging-schema-protobuf/src/test/proto/order_created_v1.proto b/src/platforms/messaging/messaging-schema-protobuf/src/test/proto/order_created_v1.proto deleted file mode 100644 index d765c5a0..00000000 --- a/src/platforms/messaging/messaging-schema-protobuf/src/test/proto/order_created_v1.proto +++ /dev/null @@ -1,23 +0,0 @@ -syntax = "proto3"; - -package dev.caskeleton.messaging.sample; - -option java_package = "dev.caskeleton.messaging.sample.proto"; -option java_outer_classname = "OrderCreatedV1Proto"; -option java_multiple_files = true; - -// The v1 wire contract for order.created. -// -// Field numbers are the contract, not the field names: renaming `currency` keeps every existing -// consumer working, while reusing tag 4 for something else silently corrupts them. Tags are never -// reused, and removed fields are reserved so that a later edit cannot take the number back. -message OrderCreated { - string order_id = 1; - string customer_id = 2; - int64 total_minor_units = 3; - string currency = 4; - - // v2 adds `channel = 5`. proto3 scalars are always optional on the wire, so an old writer that - // never sets it decodes as the default rather than failing, which is what makes the addition - // backward compatible without any per-field ceremony. -} diff --git a/src/platforms/messaging/messaging-security/build.gradle b/src/platforms/messaging/messaging-security/build.gradle deleted file mode 100644 index fac7b208..00000000 --- a/src/platforms/messaging/messaging-security/build.gradle +++ /dev/null @@ -1,7 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') -} diff --git a/src/platforms/messaging/messaging-security/gradle.lockfile b/src/platforms/messaging/messaging-security/gradle.lockfile deleted file mode 100644 index d74807c4..00000000 --- a/src/platforms/messaging/messaging-security/gradle.lockfile +++ /dev/null @@ -1,82 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.21.0=spotbugs -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor -javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath -org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath -org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty=compileClasspath,runtimeClasspath diff --git a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerAclManifest.java b/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerAclManifest.java deleted file mode 100644 index 87f84796..00000000 --- a/src/platforms/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerAclManifest.java +++ /dev/null @@ -1,141 +0,0 @@ -package dev.caskeleton.messaging.security; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.util.LinkedHashSet; -import java.util.List; -import java.util.Objects; -import java.util.Set; - -/** - * The exact broker permissions a deployment declares it needs. - * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{@code resolve} was get → fetch → put → clear with no synchronization. Two callers rotating - * the same credential both read the same old runtime and both fetched a replacement: one - * replacement was dropped from the map without ever being cleared — a secret left in memory that - * nothing owns — and the loser could clear material the winner was still using. - */ -class CredentialRotationContractTest { - - private static final Instant NOW = Instant.parse("2026-08-14T00:00:00Z"); - - @Test - @DisplayName("a hundred concurrent resolves fetch once and publish one generation") - void concurrentResolvesFetchOnce() throws Exception { - AtomicInteger fetches = new AtomicInteger(); - CredentialRuntimeRegistry registry = registry(fetches); - - ExecutorService pool = Executors.newFixedThreadPool(16); - try { - List> work = - IntStream.range(0, 100) - .>mapToObj( - index -> () -> registry.resolve("kafka-app", NOW)) - .toList(); - List resolved = new java.util.ArrayList<>(); - for (Future future : pool.invokeAll(work)) { - resolved.add(future.get()); - } - - assertThat(fetches) - .as("every caller fetching its own replacement leaves secrets nobody owns") - .hasValue(1); - assertThat(resolved).allSatisfy(runtime -> assertThat(runtime).isSameAs(resolved.get(0))); - } finally { - pool.shutdownNow(); - } - } - - @Test - @DisplayName("the surviving generation still has its material") - void theSurvivingGenerationKeepsItsMaterial() { - CredentialRuntimeRegistry registry = registry(new AtomicInteger()); - - CredentialRuntime resolved = registry.resolve("kafka-app", NOW); - - assertThatCode(resolved::material) - .as("the losing caller used to clear material the winner was still using") - .doesNotThrowAnyException(); - } - - @Test - @DisplayName("only TLS 1.2 and 1.3 are acceptable") - void onlyModernTlsIsAcceptable() { - assertThat(BrokerTlsPolicy.isAcceptable("TLSv1.2")).isTrue(); - assertThat(BrokerTlsPolicy.isAcceptable("TLSv1.3")).isTrue(); - // Each of these passed the denylist: an unrecognised protocol string negotiates whatever the - // JVM defaults to, which is what the policy exists to prevent. - assertThat(BrokerTlsPolicy.isAcceptable("SSL")).isFalse(); - assertThat(BrokerTlsPolicy.isAcceptable("TLSv0.9")).isFalse(); - assertThat(BrokerTlsPolicy.isAcceptable("PLAINTEXT")).isFalse(); - assertThat(BrokerTlsPolicy.isAcceptable("tlsv1.3")).isFalse(); - assertThat(BrokerTlsPolicy.isAcceptable(null)).isFalse(); - } - - private static CredentialRuntimeRegistry registry(AtomicInteger fetches) { - return new CredentialRuntimeRegistry( - new CredentialProvider() { - @Override - public char[] resolve(String credentialId) { - fetches.incrementAndGet(); - return "s3cr3t".toCharArray(); - } - - @Override - public java.util.Optional expiresAt(String credentialId) { - return java.util.Optional.of(NOW.plus(Duration.ofHours(1))); - } - }, - Duration.ofMinutes(5)); - } - - @Test - @DisplayName("an unknown credential id is refused rather than fetched") - void anUnknownCredentialIdIsRefused() { - CredentialRuntimeRegistry registry = registry(new AtomicInteger()); - - assertThatThrownBy(() -> registry.resolve(" ", NOW)) - .isInstanceOf(IllegalArgumentException.class); - } -} diff --git a/src/platforms/messaging/messaging-security/src/test/java/dev/caskeleton/messaging/security/CredentialRuntimeRegistryTest.java b/src/platforms/messaging/messaging-security/src/test/java/dev/caskeleton/messaging/security/CredentialRuntimeRegistryTest.java deleted file mode 100644 index 4fe4914b..00000000 --- a/src/platforms/messaging/messaging-security/src/test/java/dev/caskeleton/messaging/security/CredentialRuntimeRegistryTest.java +++ /dev/null @@ -1,218 +0,0 @@ -package dev.caskeleton.messaging.security; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.time.Duration; -import java.time.Instant; -import java.util.List; -import java.util.Optional; -import java.util.Set; -import java.util.concurrent.atomic.AtomicInteger; -import org.junit.jupiter.api.Test; - -class CredentialRuntimeRegistryTest { - - private static final String CREDENTIAL_ID = "kafka.producer"; - private static final Instant NOW = Instant.parse("2026-08-10T09:00:00Z"); - - /** Hands out a fresh generation on each resolve so rotation is observable. */ - private static final class CountingProvider implements CredentialProvider { - - private final AtomicInteger generation = new AtomicInteger(); - private final Optional expiry; - - private CountingProvider(Optional expiry) { - this.expiry = expiry; - } - - @Override - public char[] resolve(String credentialId) { - return ("generation-" + generation.incrementAndGet()).toCharArray(); - } - - @Override - public Optional expiresAt(String credentialId) { - return expiry; - } - - int resolutions() { - return generation.get(); - } - } - - @Test - void aCredentialIsResolvedOnceAndReusedUntilItIsDue() { - CountingProvider provider = new CountingProvider(Optional.of(NOW.plus(Duration.ofHours(4)))); - CredentialRuntimeRegistry registry = new CredentialRuntimeRegistry(provider); - - registry.resolve(CREDENTIAL_ID, NOW); - registry.resolve(CREDENTIAL_ID, NOW.plus(Duration.ofMinutes(5))); - - assertThat(provider.resolutions()).isEqualTo(1); - } - - @Test - void rotationHappensBeforeExpiryNotAfterIt() { - Instant expiry = NOW.plus(Duration.ofMinutes(20)); - CountingProvider provider = new CountingProvider(Optional.of(expiry)); - CredentialRuntimeRegistry registry = new CredentialRuntimeRegistry(provider); - - registry.resolve(CREDENTIAL_ID, NOW); - registry.resolve(CREDENTIAL_ID, NOW.plus(Duration.ofMinutes(1))); - - assertThat(provider.resolutions()) - .as("waiting for the broker to refuse the connection turns rotation into an outage") - .isEqualTo(2); - } - - @Test - void theSupersededGenerationIsWipedNotJustDropped() { - Instant expiry = NOW.plus(Duration.ofMinutes(20)); - CredentialRuntimeRegistry registry = - new CredentialRuntimeRegistry(new CountingProvider(Optional.of(expiry))); - - CredentialRuntime first = registry.resolve(CREDENTIAL_ID, NOW); - registry.resolve(CREDENTIAL_ID, NOW.plus(Duration.ofMinutes(1))); - - assertThatThrownBy(first::material) - .as("a revoked credential must not stay readable in memory") - .isInstanceOf(IllegalStateException.class); - } - - @Test - void aCredentialWithNoKnownExpiryIsNeverRotatedOnATimer() { - CountingProvider provider = new CountingProvider(Optional.empty()); - CredentialRuntimeRegistry registry = new CredentialRuntimeRegistry(provider); - - registry.resolve(CREDENTIAL_ID, NOW); - registry.resolve(CREDENTIAL_ID, NOW.plus(Duration.ofDays(30))); - - assertThat(provider.resolutions()).isEqualTo(1); - } - - @Test - void materialIsHandedOutAsACopySoOneHolderCannotBlindTheOthers() { - CredentialRuntimeRegistry registry = - new CredentialRuntimeRegistry(new CountingProvider(Optional.empty())); - CredentialRuntime credential = registry.resolve(CREDENTIAL_ID, NOW); - - char[] borrowed = credential.material(); - java.util.Arrays.fill(borrowed, 'x'); - - assertThat(credential.material()).containsExactly("generation-1".toCharArray()); - } - - @Test - void theDescriptionNamesTheCredentialWithoutRevealingIt() { - CredentialRuntimeRegistry registry = - new CredentialRuntimeRegistry(new CountingProvider(Optional.empty())); - - String described = registry.resolve(CREDENTIAL_ID, NOW).toString(); - - assertThat(described).contains(CREDENTIAL_ID).doesNotContain("generation-1"); - } - - @Test - void expiredCredentialsAreReportedForAlerting() { - Instant expiry = NOW.plus(Duration.ofMinutes(5)); - CredentialRuntimeRegistry registry = - new CredentialRuntimeRegistry( - new CountingProvider(Optional.of(expiry)), Duration.ofMinutes(1)); - registry.resolve(CREDENTIAL_ID, NOW); - - assertThat(registry.expired(NOW.plus(Duration.ofMinutes(10)))).containsExactly(CREDENTIAL_ID); - } - - @Test - void clearingTheRegistryWipesEverythingItHeld() { - CredentialRuntimeRegistry registry = - new CredentialRuntimeRegistry(new CountingProvider(Optional.empty())); - CredentialRuntime credential = registry.resolve(CREDENTIAL_ID, NOW); - - registry.clearAll(); - - assertThat(registry.size()).isZero(); - assertThatThrownBy(credential::material).isInstanceOf(IllegalStateException.class); - } - - @Test - void aProductionBrokerCannotRunWithoutTls() { - assertThatThrownBy( - () -> new BrokerTlsPolicy().validate(profile(true, false, true), List.of("TLSv1.3"))) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("plaintext"); - } - - @Test - void tlsWithoutHostnameVerificationIsRefusedEvenThoughItLooksEncrypted() { - assertThatThrownBy( - () -> new BrokerTlsPolicy().validate(profile(true, true, false), List.of("TLSv1.3"))) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("hostname verification"); - } - - @Test - void anObsoleteProtocolVersionIsRefused() { - assertThatThrownBy( - () -> - new BrokerTlsPolicy() - .validate(profile(true, true, true), List.of("TLSv1.3", "TLSv1.1"))) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("TLSv1.1"); - } - - @Test - void anApplicationRuntimeMayNotHoldADestructiveGrant() { - BrokerAclManifest manifest = - new BrokerAclManifest( - "orders-api", - List.of( - new BrokerAclManifest.Grant( - BrokerAclManifest.Operation.WRITE, - BrokerAclManifest.ResourceType.DESTINATION, - "orders.*"), - new BrokerAclManifest.Grant( - BrokerAclManifest.Operation.DELETE, - BrokerAclManifest.ResourceType.DESTINATION, - "orders.*"))); - - assertThatThrownBy(manifest::requireApplicationRuntime) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("DELETE"); - } - - @Test - void aGrantTheBrokerHoldsButNobodyDeclaredIsTheFinding() { - BrokerAclManifest.Grant declared = - new BrokerAclManifest.Grant( - BrokerAclManifest.Operation.WRITE, - BrokerAclManifest.ResourceType.DESTINATION, - "orders.*"); - BrokerAclManifest.Grant extra = - new BrokerAclManifest.Grant( - BrokerAclManifest.Operation.DELETE, - BrokerAclManifest.ResourceType.DESTINATION, - "orders.*"); - BrokerAclManifest manifest = new BrokerAclManifest("orders-api", List.of(declared)); - - assertThat(manifest.undeclared(Set.of(declared, extra))) - .as("a missing grant fails loudly on first use; an extra one waits to be abused") - .containsExactly(extra); - } - - private static BrokerSecurityProfile profile( - boolean production, boolean tls, boolean hostnameVerification) { - BrokerCredentialProfile credential = new BrokerCredentialProfile.SaslScram("kafka.producer"); - return new BrokerSecurityProfile( - "kafka", - production, - tls, - hostnameVerification, - credential, - credential, - Optional.empty(), - DestinationAccessPolicy.denyAll()); - } -} diff --git a/src/platforms/messaging/messaging-security/src/test/java/dev/caskeleton/messaging/security/MessageSecurityValidatorTest.java b/src/platforms/messaging/messaging-security/src/test/java/dev/caskeleton/messaging/security/MessageSecurityValidatorTest.java deleted file mode 100644 index 060fe93a..00000000 --- a/src/platforms/messaging/messaging-security/src/test/java/dev/caskeleton/messaging/security/MessageSecurityValidatorTest.java +++ /dev/null @@ -1,148 +0,0 @@ -package dev.caskeleton.messaging.security; - -import static org.assertj.core.api.Assertions.assertThatCode; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import java.util.Optional; -import java.util.Set; -import org.junit.jupiter.api.Test; - -class MessageSecurityValidatorTest { - - private final MessageSecurityValidator validator = new MessageSecurityValidator(); - - @Test - void productionBrokerWithoutTlsIsRejected() { - BrokerSecurityProfile profile = BrokerSecurityProfileFixtures.productionWithoutTls(); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("TLS"); - } - - @Test - void productionBrokerWithoutHostnameVerificationIsRejected() { - BrokerSecurityProfile profile = BrokerSecurityProfileFixtures.productionWithoutHostnameCheck(); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("hostname"); - } - - @Test - void producerAndConsumerMustUseSeparateCredentials() { - BrokerSecurityProfile profile = BrokerSecurityProfileFixtures.sharedProducerConsumer(); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("separate credentials"); - } - - @Test - void anApplicationRuntimeMustNotHoldAnAdminCredential() { - BrokerSecurityProfile profile = BrokerSecurityProfileFixtures.productionWithAdmin(); - - assertThatThrownBy(() -> validator.validate(profile)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("admin credential"); - } - - @Test - void aCredentialIdThatLooksLikeASecretIsRejected() { - assertThatThrownBy(() -> new BrokerCredentialProfile.OAuth2("bearer abcdef123456")) - .isInstanceOf(IllegalArgumentException.class); - } - - @Test - void accessPolicySeparatesPublishConsumeAndAdminister() { - DestinationName orders = new DestinationName("order-events"); - DestinationAccessPolicy policy = - new DestinationAccessPolicy(Set.of(orders), Set.of(), Set.of()); - - assertThatCode( - () -> { - if (!policy.mayPublish(orders) - || policy.mayConsume(orders) - || policy.mayAdminister(orders)) { - throw new IllegalStateException("access policy roles are not separated"); - } - }) - .doesNotThrowAnyException(); - } - - @Test - void aCoherentProductionProfileValidates() { - assertThatCode(() -> validator.validate(BrokerSecurityProfileFixtures.production())) - .doesNotThrowAnyException(); - } -} - -/** Builds broker security profiles for validator tests. */ -final class BrokerSecurityProfileFixtures { - - private BrokerSecurityProfileFixtures() {} - - static BrokerSecurityProfile production() { - return new BrokerSecurityProfile( - "kafka-primary", - true, - true, - true, - new BrokerCredentialProfile.SaslScram("kafka-producer"), - new BrokerCredentialProfile.SaslScram("kafka-consumer"), - Optional.empty(), - DestinationAccessPolicy.denyAll()); - } - - static BrokerSecurityProfile productionWithoutTls() { - BrokerSecurityProfile base = production(); - return new BrokerSecurityProfile( - base.broker(), - true, - false, - true, - base.producer(), - base.consumer(), - base.admin(), - base.access()); - } - - static BrokerSecurityProfile productionWithoutHostnameCheck() { - BrokerSecurityProfile base = production(); - return new BrokerSecurityProfile( - base.broker(), - true, - true, - false, - base.producer(), - base.consumer(), - base.admin(), - base.access()); - } - - static BrokerSecurityProfile sharedProducerConsumer() { - return new BrokerSecurityProfile( - "kafka-primary", - false, - true, - true, - new BrokerCredentialProfile.SaslScram("kafka-app"), - new BrokerCredentialProfile.SaslScram("kafka-app"), - Optional.empty(), - DestinationAccessPolicy.denyAll()); - } - - static BrokerSecurityProfile productionWithAdmin() { - BrokerSecurityProfile base = production(); - return new BrokerSecurityProfile( - base.broker(), - true, - true, - true, - base.producer(), - base.consumer(), - Optional.of(new BrokerCredentialProfile.SaslScram("kafka-admin")), - base.access()); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter-kafka/build.gradle b/src/platforms/messaging/messaging-spring-boot-starter-kafka/build.gradle deleted file mode 100644 index a985d71f..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter-kafka/build.gradle +++ /dev/null @@ -1,15 +0,0 @@ -plugins { - id 'ca.platform-module' - id 'ca.spring-config' -} - -dependencies { - // Capability artifact: selecting Kafka is a build-time decision. The core starter contains no - // Kafka client classes. - api project(':messaging:messaging-spring-boot-starter') - api project(':messaging:messaging-kafka') - // KafkaConsumerConfiguration's public consumer-factory seam names kafka-clients types. - api 'org.apache.kafka:kafka-clients' - - implementation 'org.springframework.boot:spring-boot-autoconfigure' -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter-kafka/gradle.lockfile b/src/platforms/messaging/messaging-spring-boot-starter-kafka/gradle.lockfile deleted file mode 100644 index 41a36a94..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter-kafka/gradle.lockfile +++ /dev/null @@ -1,107 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -at.yawk.lz4:lz4-java:1.11.4=runtimeClasspath,testRuntimeClasspath -com.fasterxml.jackson.core:jackson-annotations:2.21=runtimeClasspath,testRuntimeClasspath -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.luben:zstd-jni:1.5.6-10=runtimeClasspath,testRuntimeClasspath -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.21.0=spotbugs -commons-logging:commons-logging:1.3.6=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor -io.micrometer:micrometer-commons:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-core:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-observation:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.kafka:kafka-clients:4.1.2=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath -org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.hdrhistogram:HdrHistogram:2.2.2=runtimeClasspath,testRuntimeClasspath -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath -org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.latencyutils:LatencyUtils:2.0.3=runtimeClasspath,testRuntimeClasspath -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.20=runtimeClasspath,spotbugs,spotbugsSlf4j,testRuntimeClasspath -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.springframework.boot:spring-boot-actuator:4.0.9=runtimeClasspath,testRuntimeClasspath -org.springframework.boot:spring-boot-autoconfigure:4.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework.boot:spring-boot-configuration-processor:4.0.9=annotationProcessor -org.springframework.boot:spring-boot:4.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-aop:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-beans:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-context:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-core:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-expression:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-jdbc:7.0.10=runtimeClasspath,testRuntimeClasspath -org.springframework:spring-tx:7.0.10=runtimeClasspath,testRuntimeClasspath -org.xerial.snappy:snappy-java:1.1.10.9=runtimeClasspath,testRuntimeClasspath -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -tools.jackson.core:jackson-core:3.1.7=runtimeClasspath,testRuntimeClasspath -tools.jackson.core:jackson-databind:3.1.7=runtimeClasspath,testRuntimeClasspath -tools.jackson:jackson-bom:3.1.7=runtimeClasspath,testRuntimeClasspath -empty= diff --git a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerCatalog.java b/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerCatalog.java deleted file mode 100644 index 726df06f..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerCatalog.java +++ /dev/null @@ -1,37 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import java.util.LinkedHashMap; -import java.util.Map; -import java.util.Objects; - -/** - * The Kafka client settings of every {@code app.messaging.brokers} entry of type {@code kafka}. - * - * @param brokers the Kafka settings, keyed by logical broker name, in declaration order - */ -public record KafkaBrokerCatalog(Map brokers) { - - public KafkaBrokerCatalog { - brokers = - java.util.Collections.unmodifiableMap( - new LinkedHashMap<>(Objects.requireNonNull(brokers, "brokers must not be null"))); - } - - /** - * The one Kafka broker the producer and the consumers connect to. - * - * @return its logical name and settings - * @throws IllegalStateException unless exactly one Kafka entry is configured - */ - public Map.Entry single() { - if (brokers.size() != 1) { - throw new IllegalStateException( - "app.messaging.broker=kafka needs exactly one app.messaging.brokers. entry with" - + " type kafka and its bootstrap-servers; found " - + brokers.size() - + ". A producer with no broker address defaults to localhost:9092 and fails at the" - + " first publish rather than at startup"); - } - return brokers.entrySet().iterator().next(); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerSettings.java b/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerSettings.java deleted file mode 100644 index 5f380359..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerSettings.java +++ /dev/null @@ -1,86 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import java.time.Duration; -import java.util.LinkedHashMap; -import java.util.List; -import java.util.Locale; -import java.util.Map; -import java.util.Objects; -import org.springframework.boot.context.properties.bind.Bindable; -import org.springframework.boot.context.properties.bind.Binder; -import org.springframework.boot.context.properties.bind.DefaultValue; -import org.springframework.core.env.Environment; - -/** - * The Kafka client part of one {@code app.messaging.brokers.} entry of type {@code kafka}. - * - *

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

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

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

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

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

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

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

No producer or consumer bean is created here. Those need a broker profile the application has - * not declared yet at this point, and a default-constructed producer would connect to {@code - * localhost:9092} — which in a test environment usually succeeds against something. - * - *

Reached only when app.messaging.broker=kafka selected it. The @ConditionalOnClass this used to - * carry could not select: the starter then depended on two broker adapters, each of which exposed - * its client library as `api`, so both conditions were true for every adopter and both providers - * assembled. - */ -@Configuration(proxyBeanMethods = false) -@org.springframework.context.annotation.Import(KafkaConsumerConfiguration.class) -public class KafkaMessagingAutoConfiguration { - - /** - * The two versions {@code BrokerTlsPolicy} accepts. No setting names them, so both are offered. - */ - private static final java.util.List TLS_PROTOCOLS = - java.util.List.of("TLSv1.3", "TLSv1.2"); - - /** - * Returns the Kafka destination profile validator. - * - * @return the validator - */ - @Bean - @ConditionalOnMissingBean - public KafkaProfileValidator kafkaProfileValidator() { - return new KafkaProfileValidator(); - } - - /** - * Runs the Kafka profile validator over every Kafka broker profile, declared or configured. - * - * @param profiles the broker profiles the application declared as beans - * @param compiled the broker profiles compiled from {@code app.messaging.brokers} - * @param validator the Kafka profile validator - * @return the startup validation - */ - @Bean - public StartupProfileValidation - kafkaProfileStartupValidation( - ObjectProvider profiles, - CompiledMessagingConfiguration compiled, - KafkaBrokerCatalog catalog, - KafkaProfileValidator validator) { - return new StartupProfileValidation<>( - () -> - java.util.stream.Stream.concat( - configuredKafkaProfiles(compiled, catalog).stream(), profiles.orderedStream()) - .toList(), - validator::validate); - } - - /** - * The Kafka client settings of every Kafka broker entry, bound by this starter (S7-#9b). - * - * @param environment the resolved environment - * @param compiled the compiled configuration naming the Kafka entries - * @return the catalog - */ - @Bean - @ConditionalOnMissingBean - public KafkaBrokerCatalog kafkaBrokerCatalog( - org.springframework.core.env.Environment environment, - CompiledMessagingConfiguration compiled) { - return new KafkaBrokerCatalog(KafkaBrokerSettings.bindAll(environment, compiled)); - } - - /** - * Returns the Kafka transaction profile validator. - * - * @return the validator - */ - @Bean - @ConditionalOnMissingBean - public KafkaTransactionProfileValidator kafkaTransactionProfileValidator() { - return new KafkaTransactionProfileValidator(); - } - - /** - * Returns the producer failure classifier. - * - * @return the classifier - */ - @Bean - @ConditionalOnMissingBean - public KafkaPublishFailureClassifier kafkaPublishFailureClassifier() { - return new KafkaPublishFailureClassifier(); - } - - /** - * Returns the Kafka client security configurer. - * - * @param credentials the credential runtime registry - * @param tlsPolicy the transport security policy - * @return the configurer - */ - /** - * The security configurer, which exists only when a credential source does. - * - *

It took {@code CredentialRuntimeRegistry} as a required parameter, and that registry is - * created only when the application supplies a {@code CredentialProvider}. Without one the - * context failed on a missing bean naming the registry — an error that describes the platform's - * internals rather than the one thing the operator has to do. The condition moves the failure to - * a place that can say so. - */ - @Bean - @ConditionalOnMissingBean - @org.springframework.boot.autoconfigure.condition.ConditionalOnBean( - CredentialRuntimeRegistry.class) - public KafkaSecurityConfigurer kafkaSecurityConfigurer( - CredentialRuntimeRegistry credentials, BrokerTlsPolicy tlsPolicy) { - return new KafkaSecurityConfigurer(credentials, tlsPolicy); - } - - /** - * The producer this transport publishes through (MSG-INT-003). - * - *

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

Byte-array serializers on purpose: the platform's codec registry decides the wire format, - * and a serializer configured here would be a second encoder disagreeing with it. - * - * @param compiled the broker and security profiles compiled from {@code app.messaging} - * @param declaredSecurity the security profiles the application declared as beans - * @param securityConfigurer the Kafka security configurer, present only with a credential source - * @return the producer, closed with the context - */ - @Bean(destroyMethod = "close") - @ConditionalOnMissingBean - public org.apache.kafka.clients.producer.Producer messagingKafkaProducer( - CompiledMessagingConfiguration compiled, - KafkaBrokerCatalog catalog, - ObjectProvider declaredSecurity, - ObjectProvider securityConfigurer) { - return new org.apache.kafka.clients.producer.KafkaProducer<>( - producerConfig(compiled, catalog, declaredSecurity, securityConfigurer)); - } - - /** The producer's client configuration; package-visible so a test can read what it holds. */ - static java.util.Map producerConfig( - CompiledMessagingConfiguration compiled, - KafkaBrokerCatalog catalog, - ObjectProvider declaredSecurity, - ObjectProvider securityConfigurer) { - KafkaBrokerSettings broker = catalog.single().getValue(); - java.util.Map config = new java.util.HashMap<>(); - config.put( - org.apache.kafka.clients.producer.ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, - String.join(",", broker.bootstrapServers())); - config.put( - org.apache.kafka.clients.producer.ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, - org.apache.kafka.common.serialization.ByteArraySerializer.class); - config.put( - org.apache.kafka.clients.producer.ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, - org.apache.kafka.common.serialization.ByteArraySerializer.class); - // The entry's delivery settings, which KafkaProfileValidator checks (a stable broker must keep - // acks=all and idempotence) and which used to be replaced here by hard-coded values. - config.put(org.apache.kafka.clients.producer.ProducerConfig.ACKS_CONFIG, broker.acks()); - config.put( - org.apache.kafka.clients.producer.ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, - broker.enableIdempotence()); - config.put( - org.apache.kafka.clients.producer.ProducerConfig.MAX_IN_FLIGHT_REQUESTS_PER_CONNECTION, - broker.maxInFlightRequestsPerConnection()); - // Kafka refuses delivery.timeout.ms below linger.ms + request.timeout.ms (5ms + 30s by - // default), which made the documented 30s a startup failure. The request timeout follows a - // short delivery deadline down, and records are not held back to fill a batch. - long delivery = broker.deliveryTimeout().toMillis(); - config.put(org.apache.kafka.clients.producer.ProducerConfig.LINGER_MS_CONFIG, 0); - config.put( - org.apache.kafka.clients.producer.ProducerConfig.REQUEST_TIMEOUT_MS_CONFIG, - Math.toIntExact(Math.min(30_000L, delivery))); - config.put( - org.apache.kafka.clients.producer.ProducerConfig.DELIVERY_TIMEOUT_MS_CONFIG, - Math.toIntExact(delivery)); - // send() blocks the caller while it waits for metadata or buffer space, for Kafka's default - // 60s — before the publish deadline is even applied. Bounded by the default deadline instead. - config.put( - org.apache.kafka.clients.producer.ProducerConfig.MAX_BLOCK_MS_CONFIG, - dev.caskeleton.messaging.api.publish.PublishOptions.defaults().timeout().toMillis()); - config.putAll( - clientSecurity( - compiled, declaredSecurity, securityConfigurer, BrokerSecurityProfile::producer)); - return config; - } - - /** - * A client's security properties, from the one security profile of the Kafka broker. - * - *

{@code KafkaSecurityConfigurer} was a bean nothing called, so a broker that passed the TLS - * and credential checks was reached over plaintext with no authentication. Every case that cannot - * be applied fails startup rather than falling back to that. The producer and the consumers use - * the same rule, each with its own credential. - * - * @param role picks the producer or the consumer credential of the profile - */ - static java.util.Map clientSecurity( - CompiledMessagingConfiguration compiled, - ObjectProvider declaredSecurity, - ObjectProvider securityConfigurer, - java.util.function.Function< - BrokerSecurityProfile, dev.caskeleton.messaging.security.BrokerCredentialProfile> - role) { - java.util.Map kafkaBrokers = new java.util.TreeMap<>(); - compiled.brokers().entrySet().stream() - .filter(entry -> BrokerSettings.KAFKA.equalsIgnoreCase(entry.getValue().type())) - .forEach(entry -> kafkaBrokers.put(entry.getKey(), entry.getValue())); - // The same fallback as the runtime's logical name: bean-declared profiles name the family. - java.util.Set names = - kafkaBrokers.isEmpty() ? java.util.Set.of(BrokerSettings.KAFKA) : kafkaBrokers.keySet(); - java.util.List profiles = - java.util.stream.Stream.concat( - compiled.security().stream(), declaredSecurity.orderedStream()) - .filter(profile -> names.contains(profile.broker())) - .toList(); - - if (profiles.isEmpty()) { - kafkaBrokers.forEach( - (name, broker) -> { - if (broker.tlsEnabled() || broker.authenticationEnabled()) { - throw new IllegalStateException( - "Kafka broker '" - + name - + "' enables TLS or authentication but has no app.messaging.security." - + name - + " entry; a Kafka client cannot apply either without one"); - } - }); - return java.util.Map.of(); - } - if (profiles.size() > 1) { - throw new IllegalStateException( - "a Kafka client has one security posture but " - + profiles.size() - + " security profiles match " - + names); - } - BrokerSecurityProfile profile = profiles.getFirst(); - KafkaSecurityConfigurer configurer = securityConfigurer.getIfAvailable(); - if (configurer == null) { - throw new IllegalStateException( - "app.messaging.security." - + profile.broker() - + " is configured but no CredentialProvider bean exists; a Kafka client cannot" - + " resolve its credential and must not connect without it"); - } - return configurer.configure( - profile, role.apply(profile), TLS_PROTOCOLS, java.time.Instant.now()); - } - - /** - * The Kafka transport the publisher writes through and the consumers subscribe through. - * - *

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

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

{@link #close()} stops dispatching, lets running handlers finish up to the drain deadline, - * commits what they settled and closes the client. Work still running at the deadline is abandoned - * unsettled, so the broker redelivers it rather than the platform pretending it completed. - */ -final class KafkaPolledRegistration implements TransportConsumerRegistration { - - private static final System.Logger LOG = - System.getLogger(KafkaPolledRegistration.class.getName()); - - private static final Duration POLL_TIMEOUT = Duration.ofMillis(200); - - private final String name; - private final KafkaConsumerRegistrar registrar; - private final GracefulShutdownCoordinator drain; - private final ExecutorService handlers; - private final Duration drainDeadline; - private final Thread poller; - private volatile boolean stopping; - - private KafkaPolledRegistration( - TransportConsumerSpec spec, - Map clientConfig, - KafkaQuarantinePublisher quarantine, - Duration drainDeadline) { - this.name = spec.profile().name().value(); - this.drainDeadline = drainDeadline; - String topic = - spec.profile() - .physical() - .topic() - .orElseThrow( - () -> - new IllegalStateException( - "destination '" + name + "' is consumed from Kafka but has no topic")); - this.drain = new GracefulShutdownCoordinator(drainDeadline); - this.handlers = - Executors.newFixedThreadPool( - spec.profile().consumer().concurrency(), - Thread.ofPlatform().name("messaging-kafka-handler-" + name + "-", 0).factory()); - this.registrar = - new KafkaConsumerRegistrar( - spec, - new KafkaConsumer(clientConfig), - handlers, - drain, - POLL_TIMEOUT, - quarantine); - registrar.subscribe(topic); - this.poller = Thread.ofPlatform().name("messaging-kafka-poll-" + name).unstarted(this::loop); - } - - /** - * Opens the client, subscribes and starts polling. - * - * @param spec the destination and the pipeline its deliveries go through - * @param clientConfig the consumer client configuration - * @param quarantine where a record the consumer cannot deliver is parked - * @param drainDeadline how long {@link #close()} lets running handlers finish - * @return the live registration - */ - static KafkaPolledRegistration open( - TransportConsumerSpec spec, - Map clientConfig, - KafkaQuarantinePublisher quarantine, - Duration drainDeadline) { - KafkaPolledRegistration registration = - new KafkaPolledRegistration(spec, clientConfig, quarantine, drainDeadline); - registration.poller.start(); - return registration; - } - - @Override - public CompletionStage pause(String scope) { - return registrar.pause(scope); - } - - @Override - public CompletionStage resume(String scope) { - return registrar.resume(scope); - } - - @Override - public boolean isActive() { - return registrar.isActive() && !stopping; - } - - @Override - public void close() { - Instant startedAt = Instant.now(); - drain.beginDrain(startedAt); - Instant deadline = startedAt.plus(drainDeadline); - while (!drain.isDrained(Instant.now()) && Instant.now().isBefore(deadline)) { - if (!sleep(Duration.ofMillis(50))) { - break; - } - } - stopping = true; - try { - poller.join(POLL_TIMEOUT.toMillis() * 10); - } catch (InterruptedException interrupted) { - Thread.currentThread().interrupt(); - } - handlers.shutdownNow(); - try { - handlers.awaitTermination(1, TimeUnit.SECONDS); - } catch (InterruptedException interrupted) { - Thread.currentThread().interrupt(); - } - } - - private void loop() { - try { - while (!stopping) { - try { - registrar.pollOnce(Instant.now()); - } catch (RuntimeException failure) { - // A failed poll or commit is not a reason to stop consuming for good: nothing past the - // last successful commit is lost, and the next cycle retries it. - LOG.log( - System.Logger.Level.WARNING, - "Kafka consumer for " + name + " failed a poll cycle: " + failure); - sleep(POLL_TIMEOUT); - } - if (!drain.isAcceptingWork()) { - // pollOnce no longer polls once draining begins; it only applies settlements and - // commits. Without a pause the loop would spin. - sleep(Duration.ofMillis(20)); - } - } - } finally { - registrar.close(); - } - } - - private static boolean sleep(Duration duration) { - try { - Thread.sleep(duration.toMillis()); - return true; - } catch (InterruptedException interrupted) { - Thread.currentThread().interrupt(); - return false; - } - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantineTest.java b/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantineTest.java deleted file mode 100644 index 35c6d145..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter-kafka/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantineTest.java +++ /dev/null @@ -1,82 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.header.ReservedHeaders; -import java.nio.charset.StandardCharsets; -import java.time.Duration; -import java.util.List; -import java.util.stream.StreamSupport; -import org.apache.kafka.clients.consumer.ConsumerRecord; -import org.apache.kafka.clients.producer.MockProducer; -import org.apache.kafka.clients.producer.ProducerRecord; -import org.apache.kafka.common.header.Header; -import org.apache.kafka.common.serialization.ByteArraySerializer; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.params.ParameterizedTest; -import org.junit.jupiter.params.provider.EnumSource; - -/** - * The dead-letter copy says which of the two quarantine paths wrote it (review 2026-11-01 06-14, - * re-review round 2 RR-02-16): a record that could not be rebuilt at all and one whose handler - * spent its attempt budget leave different failure-category bytes, so a redrive can tell a message - * that will never decode from one an outage kept failing. - */ -class KafkaDeadLetterQuarantineTest { - - private static final String DEAD_LETTER_TOPIC = "orders.dlq"; - - @ParameterizedTest - @EnumSource( - value = FailureCategory.class, - names = {"DESERIALIZATION", "POISON_MESSAGE"}) - @DisplayName("격리 사본은 원래 header를 지키고 failure-category를 호출자가 준 분류 하나로 쓴다") - void theCopyCarriesTheCategoryTheCallerGaveInPlaceOfAnyEarlierOne(FailureCategory category) { - // given - MockProducer producer = - new MockProducer<>(true, null, new ByteArraySerializer(), new ByteArraySerializer()); - KafkaDeadLetterQuarantine quarantine = - new KafkaDeadLetterQuarantine(producer, DEAD_LETTER_TOPIC, Duration.ofSeconds(1)); - ConsumerRecord record = - new ConsumerRecord<>("orders", 0, 7L, bytes("order-7"), bytes("{\"broken\"")); - record.headers().add("trace-id", bytes("trace-1")); - record.headers().add(ReservedHeaders.FAILURE_CATEGORY, bytes("STALE_FROM_AN_EARLIER_HOP")); - - // when - boolean confirmed = quarantine.quarantine(record, category, new IllegalStateException("x")); - - // then - ProducerRecord copy = producer.history().getFirst(); - assertThat( - List.of( - confirmed, - copy.topic(), - text(copy.value()), - values(copy, "trace-id"), - values(copy, ReservedHeaders.FAILURE_CATEGORY), - values(copy, ReservedHeaders.FAILURE_CODE))) - .containsExactly( - true, - DEAD_LETTER_TOPIC, - "{\"broken\"", - List.of("trace-1"), - List.of(category.name()), - List.of("IllegalStateException")); - } - - private static List values(ProducerRecord record, String header) { - return StreamSupport.stream(record.headers().headers(header).spliterator(), false) - .map(Header::value) - .map(KafkaDeadLetterQuarantineTest::text) - .toList(); - } - - private static byte[] bytes(String value) { - return value.getBytes(StandardCharsets.UTF_8); - } - - private static String text(byte[] value) { - return new String(value, StandardCharsets.UTF_8); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/README.md b/src/platforms/messaging/messaging-spring-boot-starter/README.md deleted file mode 100644 index 2cb6c3e2..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/README.md +++ /dev/null @@ -1,43 +0,0 @@ -# messaging-spring-boot-starter - -## 아티팩트 분리 - -기본 `messaging-spring-boot-starter`는 이제 **broker-neutral core**다. Kafka client를 -production runtime에 직접 넣지 않으며, 브로커 채택은 capability artifact를 composition에 추가하는 -build-time 결정이다. - -```text -messaging-spring-boot-starter -└─ messaging-spring-boot-starter-kafka # Kafka client/transport capability -``` - -- 기본 app-bootstrap은 messaging을 싣지 않는다. 서비스는 `runtimeOnly - project(':adapter:outbound:messaging-kafka')` 한 줄로 Kafka capability를 고르고, 그 모듈이 - `:messaging:messaging-spring-boot-starter-kafka`(와 이 core starter)를 runtime으로 끌어온다. -- starter는 있으면 켜진다(`app.messaging.enabled` 기본 on). `app.messaging.enabled=false`로만 끈다. -- 등록된 broker 계열은 Kafka 하나다. RabbitMQ 설정 키(`type: rabbitmq`, `addresses`, `prefetch` 등)는 - transport 없이 바인딩만 되던 키라 삭제했고, 지금은 키 이름을 담아 기동이 거부된다. -- reliability/admin의 추가 artifact 분리는 별도 구조 개선 여지로 남지만, broker SDK 동시 탑재 문제와 - transport 선택 문제는 core/broker capability 분리로 해소했다. -- legacy R0 outbound bridge도 같은 원칙을 따른다. broker-neutral - `:adapter:outbound:messaging`과 Kafka 전용 `:adapter:outbound:messaging-kafka`가 분리돼 있다. - -## 현재 broker/runtime 지원 범위 - -### Kafka - -Kafka publish runtime은 **Kafka capability artifact를 추가한 composition에서만** 조립된다. -`KafkaMessagingTransport`는 publish runtime으로 설치되지만, `KafkaConsumerRegistrar`는 capability -starter나 app-bootstrap에서 자동 생성하지 않는다. 따라서 현재 자동조립된 transport에 consume -registration을 요청하면 `KAFKA_CONSUMER_NOT_CONFIGURED`로 실패한다. - -consume을 채택하려면 애플리케이션 composition이 별도로 `KafkaConsumerRegistrar`와 handler sink를 -조립해야 한다. leaf 안의 consumer/rebalance/settlement 테스트가 초록이라는 사실은 capability -starter가 consumer runtime까지 자동 제공한다는 뜻이 아니다. - -### RabbitMQ (삭제됨) - -production transport가 없어 선택할 수 없던 `messaging-rabbit`·`messaging-spring-boot-starter-rabbit`는 -2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표). 현재 등록된 broker는 Kafka 하나다. -`app.messaging.brokers..type: rabbitmq` 설정 family는 아직 바인딩·검증되지만 소비하는 transport가 -없다. diff --git a/src/platforms/messaging/messaging-spring-boot-starter/build.gradle b/src/platforms/messaging/messaging-spring-boot-starter/build.gradle deleted file mode 100644 index efed4b94..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/build.gradle +++ /dev/null @@ -1,80 +0,0 @@ -plugins { - id 'ca.platform-module' - id 'ca.spring-config' -} - -// Scopes, not a flat list of `api`. -// -// `api` is the types that genuinely appear in this module's public signatures; everything else is -// `implementation`. Broker transports live in capability starters (messaging-spring-boot-starter-kafka), -// so this starter's compile classpath carries no broker SDK. -testing { - suites { - integrationTest(JvmTestSuite) { - dependencies { - implementation project() - } - } - } -} -configurations { - integrationTestImplementation.extendsFrom testImplementation - integrationTestRuntimeOnly.extendsFrom testRuntimeOnly -} - -dependencies { - // Types an adopter writes against: envelopes, destinations, publish results, profiles, ports. - api project(':messaging:messaging-core-api') - api project(':messaging:messaging-policy') - api project(':messaging:messaging-transport-spi') - api project(':messaging:messaging-observability') - api project(':messaging:messaging-security') - api project(':messaging:messaging-reliability-api') - - // Wired by the auto-configurations and never named in an adopter's source. - implementation project(':messaging:messaging-schema-json') - // The publisher and its collaborators live here. The starter did not depend on it at all, - // which is why MessagingCoreAutoConfiguration consumed a MessagePublisher that nothing in - // reach could produce (MSG-INT-003). - implementation project(':messaging:messaging-runtime-core') - // The relay and consumer logic, and the PostgreSQL stores behind their ports. - implementation project(':messaging:messaging-reliability') - implementation project(':messaging:messaging-reliability-jdbc-postgresql') - implementation project(':messaging:messaging-admin') - - implementation 'org.springframework.boot:spring-boot-autoconfigure' - implementation 'org.springframework.boot:spring-boot-actuator' - - testImplementation 'org.springframework.boot:spring-boot-test' - testImplementation 'org.springframework:spring-test' - // Provider auto-configurations live in capability artifacts. Tests that exercise provider - // selection add it only to the test graph; the production starter remains broker-neutral. - testImplementation project(':messaging:messaging-spring-boot-starter-kafka') - // Test-only, and specifically so the configuration reference can be executed rather than read: - // MessagingConfigurationBindingTest loads the YAML blocks out of the shipped document and boots - // a context on them. Spring Boot 4 treats snakeyaml as optional, so a document-driven test has - // to ask for it; production code does not, and adding it here keeps that asymmetry visible. - testImplementation 'org.yaml:snakeyaml' - // The live round trip. MSG-INT-003's membership rule is that the starter earns - // app-bootstrap membership in the same change that proves a real broker round trip, - // so the proof has to run somewhere — and the starter is where the whole platform - // assembles. - integrationTestImplementation project(':messaging:messaging-spring-boot-starter-kafka') - integrationTestImplementation 'org.testcontainers:testcontainers-junit-jupiter' - integrationTestImplementation 'org.testcontainers:testcontainers-kafka' - // The consume round trip's inbox lane: a real PostgreSQL behind the JDBC inbox, joined to the - // handler's own write by a real transaction manager. - integrationTestImplementation project(':messaging:messaging-reliability') - integrationTestImplementation project(':messaging:messaging-reliability-jdbc-postgresql') - integrationTestImplementation 'org.springframework:spring-jdbc' - integrationTestImplementation 'org.testcontainers:testcontainers-postgresql' - integrationTestImplementation 'org.postgresql:postgresql' -} - -strictTestLanes { - lane('integrationTest') { - integration() - sourceSet = 'integrationTest' - description = 'Runs the assembled messaging starter round trip against real Kafka.' - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/gradle.lockfile b/src/platforms/messaging/messaging-spring-boot-starter/gradle.lockfile deleted file mode 100644 index e0ecae25..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/gradle.lockfile +++ /dev/null @@ -1,127 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -at.yawk.lz4:lz4-java:1.11.4=integrationTestRuntimeClasspath,testRuntimeClasspath -com.fasterxml.jackson.core:jackson-annotations:2.21=integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.github.docker-java:docker-java-api:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath -com.github.docker-java:docker-java-transport-zerodep:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath -com.github.docker-java:docker-java-transport:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.github.luben:zstd-jni:1.5.6-10=integrationTestRuntimeClasspath,testRuntimeClasspath -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-codec:commons-codec:1.19.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.20.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath -commons-io:commons-io:2.21.0=spotbugs -commons-logging:commons-logging:1.3.6=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -io.micrometer:micrometer-commons:1.16.8=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-core:1.16.8=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.micrometer:micrometer-observation:1.16.8=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -javax.inject:javax.inject:1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -net.java.dev.jna:jna:5.18.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-compress:1.28.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.apache.commons:commons-lang3:3.20.0=checkstyle,integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.kafka:kafka-clients:4.1.2=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=integrationTestCompileClasspath,testCompileClasspath -org.assertj:assertj-core:3.27.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.checkerframework:checker-qual:3.55.1=integrationTestRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.hdrhistogram:HdrHistogram:2.2.2=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -org.javassist:javassist:3.28.0-GA=checkstyle -org.jetbrains:annotations:17.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,integrationTestAnnotationProcessor,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath -org.junit:junit-bom:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.latencyutils:LatencyUtils:2.0.3=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -org.postgresql:postgresql:42.7.14=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.reflections:reflections:0.10.2=checkstyle -org.rnorth.duct-tape:duct-tape:1.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.slf4j:slf4j-api:2.0.20=integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs,spotbugsSlf4j,testRuntimeClasspath -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.springframework.boot:spring-boot-actuator:4.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework.boot:spring-boot-autoconfigure:4.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework.boot:spring-boot-configuration-processor:4.0.9=annotationProcessor -org.springframework.boot:spring-boot-test:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework.boot:spring-boot:4.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-aop:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-beans:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-context:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-core:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-expression:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-jdbc:7.0.10=integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -org.springframework:spring-test:7.0.10=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-tx:7.0.10=integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -org.testcontainers:testcontainers-database-commons:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-jdbc:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-junit-jupiter:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-kafka:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers-postgresql:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.testcontainers:testcontainers:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath -org.xerial.snappy:snappy-java:1.1.10.9=integrationTestRuntimeClasspath,testRuntimeClasspath -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -org.yaml:snakeyaml:2.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -tools.jackson.core:jackson-core:3.1.7=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -tools.jackson.core:jackson-databind:3.1.7=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -tools.jackson:jackson-bom:3.1.7=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -empty= diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingKafkaConsumeQualificationTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingKafkaConsumeQualificationTest.java deleted file mode 100644 index 13ad8fcb..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingKafkaConsumeQualificationTest.java +++ /dev/null @@ -1,461 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.ProducerId; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.TraceContext; -import dev.caskeleton.messaging.api.delivery.DeliveryGuarantee; -import dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee; -import dev.caskeleton.messaging.api.delivery.HandleResult; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -import dev.caskeleton.messaging.api.delivery.OrderingScope; -import dev.caskeleton.messaging.api.destination.DestinationKind; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.api.header.ReservedHeaders; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.inbox.IdempotentConsumer; -import dev.caskeleton.messaging.inbox.JdbcInboxRepository; -import dev.caskeleton.messaging.policy.ApiTier; -import dev.caskeleton.messaging.policy.ConsumerPolicy; -import dev.caskeleton.messaging.policy.DeadLetterPolicy; -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.policy.OrderingImpact; -import dev.caskeleton.messaging.policy.PayloadPolicy; -import dev.caskeleton.messaging.policy.PhysicalDestination; -import dev.caskeleton.messaging.policy.ProducerPolicy; -import dev.caskeleton.messaging.policy.RetryMode; -import dev.caskeleton.messaging.policy.RetryPolicy; -import dev.caskeleton.messaging.policy.SchemaPolicy; -import dev.caskeleton.messaging.schema.MessageContractKey; -import dev.caskeleton.messaging.schema.SchemaCompatibility; -import java.io.IOException; -import java.io.InputStream; -import java.nio.charset.StandardCharsets; -import java.time.Duration; -import java.time.Instant; -import java.util.List; -import java.util.Map; -import java.util.Optional; -import java.util.Properties; -import java.util.Set; -import java.util.concurrent.BlockingQueue; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import java.util.concurrent.LinkedBlockingQueue; -import java.util.concurrent.TimeUnit; -import java.util.concurrent.atomic.AtomicInteger; -import java.util.function.Function; -import javax.sql.DataSource; -import org.apache.kafka.clients.admin.Admin; -import org.apache.kafka.clients.admin.AdminClientConfig; -import org.apache.kafka.clients.consumer.ConsumerConfig; -import org.apache.kafka.clients.consumer.ConsumerRecord; -import org.apache.kafka.clients.consumer.KafkaConsumer; -import org.apache.kafka.clients.consumer.OffsetAndMetadata; -import org.apache.kafka.common.TopicPartition; -import org.apache.kafka.common.serialization.ByteArrayDeserializer; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.condition.EnabledIf; -import org.springframework.boot.autoconfigure.AutoConfigurations; -import org.springframework.boot.test.context.runner.ApplicationContextRunner; -import org.springframework.jdbc.core.JdbcTemplate; -import org.springframework.jdbc.datasource.DataSourceTransactionManager; -import org.springframework.jdbc.datasource.DriverManagerDataSource; -import org.springframework.transaction.support.TransactionTemplate; -import org.testcontainers.DockerClientFactory; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; -import org.testcontainers.kafka.KafkaContainer; -import org.testcontainers.postgresql.PostgreSQLContainer; - -/** - * A message published through the assembled platform is consumed by a {@code MessageHandler} bean - * on a real broker (owner decision 10, S7-#2). - * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

{@code tlsEnabled} and {@code production} live here rather than beside the credentials, so a - * broker is described once. They were previously implied by whichever object happened to be - * constructed, which is how a profile can be production in one validator's view and not in - * another's. - * - * @param type the broker family; {@code kafka} is the only one - * @param stable whether this profile claims the Stable guarantees - * @param production whether this profile is used in production - * @param tlsEnabled whether transport encryption is on - * @param authenticationEnabled whether broker authentication is on - */ -public record BrokerSettings( - String type, - @DefaultValue("false") boolean stable, - @DefaultValue("false") boolean production, - @DefaultValue("false") boolean tlsEnabled, - @DefaultValue("false") boolean authenticationEnabled) { - - /** The broker family a Kafka entry declares. */ - public static final String KAFKA = "kafka"; -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/CompiledMessagingConfiguration.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/CompiledMessagingConfiguration.java deleted file mode 100644 index 7b65e6a6..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/CompiledMessagingConfiguration.java +++ /dev/null @@ -1,43 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.policy.DestinationProfile; -import dev.caskeleton.messaging.security.BrokerSecurityProfile; -import java.util.List; -import java.util.Map; -import java.util.Objects; - -/** - * What the documented broker-neutral configuration compiles to. - * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Provider selection is a property, not a classpath accident. Kafka and Rabbit were each - * conditioned on their client class being present, so an application that happened to have both - * libraries — a transitive dependency is enough — assembled both providers and published through - * whichever bean won. Selection now reads {@code app.messaging.broker} against a closed registry, - * and a value outside it is a startup error rather than a context with no provider at all. - * - *

On when present: a missing {@code app.messaging.enabled} means on, because an application that - * put this starter on its classpath chose messaging. {@code app.messaging.enabled=false} means no - * beans, no clients, no threads, and no bound detail namespace. {@code - * MessagingStarterOffContractTest} holds that against a full context including this starter's owned - * imports. Vendor auto-configuration is verified in its own runtime lanes. - */ -@AutoConfiguration -@ConditionalOnProperty( - prefix = MessagingSettings.PREFIX, - name = "enabled", - havingValue = "true", - matchIfMissing = true) -@EnableConfigurationProperties(MessagingSettings.class) -@Import({ - MessagingCoreAutoConfiguration.class, - MessagingProviderSelection.class, - MessagingReliabilityAutoConfiguration.class, - MessagingAdminAutoConfiguration.class -}) -public class MessagingPlatformRootAutoConfiguration {} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPrefixMigrationValidator.java b/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPrefixMigrationValidator.java deleted file mode 100644 index 6db80501..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPrefixMigrationValidator.java +++ /dev/null @@ -1,83 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.util.ArrayList; -import java.util.List; -import java.util.Objects; -import org.springframework.beans.factory.InitializingBean; -import org.springframework.core.env.ConfigurableEnvironment; -import org.springframework.core.env.EnumerablePropertySource; -import org.springframework.core.env.PropertySource; - -/** - * Refuses a configuration written against a prefix this platform no longer binds. - * - *

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

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

Selection used to be {@code @ConditionalOnClass}: a transport assembled because its client - * class was on the classpath, so an application with two client libraries — one transitive - * dependency is enough — assembled both and published through whichever bean won a - * {@code @ConditionalOnMissingBean} race. Nothing failed; the message simply went somewhere nobody - * chose. - * - *

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

    - *
  • a broker id outside the registry — the operator set something the platform cannot honour; - *
  • a registered broker whose client library is absent — a deployment that asked for Kafka and - * shipped without it is told so, instead of starting with no publisher at all; - *
  • a blank broker while messaging is on — the capability switch says yes and nothing says what - * to. - *
- * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The destination, broker and security maps are what the configuration reference has always - * described and nothing bound. Until they existed, a deployment that configured them exactly as - * documented changed no behaviour and produced no error: the profiles the platform actually used - * had to arrive as beans an application wrote in Java, and the documented keys were inert text. - * {@link MessagingConfigurationCompiler} turns them into those same profiles, so the documented - * shape is now the working shape. - * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The producer read {@code spring.kafka.bootstrap-servers} while the compiler required and - * validated {@code app.messaging.brokers..bootstrap-servers}, so a broker was described twice - * and only one description was used. The entry's delivery settings were validated and then replaced - * by hard-coded values. - */ -class KafkaProducerConfigTest { - - private final ApplicationContextRunner runner = - new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingPlatformRootAutoConfiguration.class)) - .withPropertyValues( - "app.messaging.enabled=true", - "app.messaging.broker=kafka", - "app.messaging.brokers.kafka-primary.type=kafka", - // Resolvable names: the client refuses an address it cannot look up at construction. - "app.messaging.brokers.kafka-primary.bootstrap-servers[0]=localhost:9093", - "app.messaging.brokers.kafka-primary.bootstrap-servers[1]=127.0.0.1:9094"); - - @Test - void theProducerConnectsToTheBrokerEntryAddressesNotToSpringKafka() { - runner - .withPropertyValues("spring.kafka.bootstrap-servers=elsewhere:9092") - .run( - context -> - assertThat(producerConfig(context).get("bootstrap.servers")) - .isEqualTo("localhost:9093,127.0.0.1:9094")); - } - - @Test - void theProducerAppliesTheBrokerEntryDeliverySettings() { - runner - .withPropertyValues( - "app.messaging.brokers.kafka-primary.enable-idempotence=false", - "app.messaging.brokers.kafka-primary.acks=1", - "app.messaging.brokers.kafka-primary.max-in-flight-requests-per-connection=3", - "app.messaging.brokers.kafka-primary.delivery-timeout=45s") - .run( - context -> - assertThat(producerConfig(context)) - .extractingByKeys( - "enable.idempotence", - "acks", - "max.in.flight.requests.per.connection", - "delivery.timeout.ms") - .containsExactly(false, "1", 3, 45_000)); - } - - @Test - void theProducerStopsWaitingForMetadataWithinTheDefaultPublishDeadline() { - runner.run( - context -> - assertThat(producerConfig(context).get("max.block.ms")) - .as("the caller's thread waited up to Kafka's own 60s before any deadline applied") - .isEqualTo(PublishOptions.defaults().timeout().toMillis())); - } - - @Test - void aBrokerWithoutAnEntryFailsStartupNamingTheKey() { - new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingPlatformRootAutoConfiguration.class)) - .withPropertyValues( - "app.messaging.enabled=true", - "app.messaging.broker=kafka", - "spring.kafka.bootstrap-servers=localhost:9092") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .rootCause() - .hasMessageContaining("app.messaging.brokers. entry with type kafka")); - } - - private static Map producerConfig(AssertableApplicationContext context) { - return KafkaMessagingAutoConfiguration.producerConfig( - context.getBean(CompiledMessagingConfiguration.class), - context.getBean(KafkaBrokerCatalog.class), - context.getBeanProvider(BrokerSecurityProfile.class), - context.getBeanProvider(KafkaSecurityConfigurer.class)); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java deleted file mode 100644 index cfca0829..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java +++ /dev/null @@ -1,328 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.kafka.KafkaSecurityConfigurer; -import dev.caskeleton.messaging.security.BrokerSecurityProfile; -import dev.caskeleton.messaging.security.CredentialProvider; -import java.time.Instant; -import java.util.List; -import java.util.Map; -import java.util.Optional; -import java.util.concurrent.atomic.AtomicReference; -import javax.security.auth.callback.Callback; -import javax.security.auth.callback.NameCallback; -import javax.security.auth.callback.PasswordCallback; -import org.apache.kafka.common.security.auth.AuthenticateCallbackHandler; -import org.junit.jupiter.api.Test; -import org.springframework.boot.autoconfigure.AutoConfigurations; -import org.springframework.boot.test.context.assertj.AssertableApplicationContext; -import org.springframework.boot.test.context.runner.ApplicationContextRunner; -import org.springframework.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; - -/** - * What the Kafka producer is actually configured with once {@code app.messaging.security} says how. - * - *

The security settings were bound, compiled and validated, and {@code KafkaSecurityConfigurer} - * was a bean nothing called: the producer was built from the bootstrap address, serializers, acks - * and idempotence alone, so a broker that passed the TLS and credential checks was reached over - * plaintext with no authentication. - */ -class KafkaProducerSecurityTest { - - // Assembled through the root, as an application is: the import order it fixes is what lets the - // configurer see the credential registry. - private final ApplicationContextRunner runner = - new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingPlatformRootAutoConfiguration.class)) - .withPropertyValues( - "app.messaging.enabled=true", - "app.messaging.broker=kafka", - "app.messaging.brokers.kafka-primary.type=kafka", - "app.messaging.brokers.kafka-primary.bootstrap-servers[0]=localhost:9092"); - - private static final String[] SCRAM_CREDENTIALS = { - "app.messaging.security.kafka-primary.producer.type=SASL_SCRAM", - "app.messaging.security.kafka-primary.producer.credential-id=kafka-producer", - "app.messaging.security.kafka-primary.consumer.type=SASL_SCRAM", - "app.messaging.security.kafka-primary.consumer.credential-id=kafka-consumer", - }; - - private static final String[] MUTUAL_TLS_CREDENTIALS = { - "app.messaging.brokers.kafka-primary.tls-enabled=true", - "app.messaging.security.kafka-primary.producer.type=MUTUAL_TLS", - "app.messaging.security.kafka-primary.producer.credential-id=kafka-producer-tls", - "app.messaging.security.kafka-primary.producer.key-store.location=/etc/kafka/producer.p12", - "app.messaging.security.kafka-primary.consumer.type=MUTUAL_TLS", - "app.messaging.security.kafka-primary.consumer.credential-id=kafka-consumer-tls", - "app.messaging.security.kafka-primary.consumer.key-store.location=/etc/kafka/consumer.p12", - }; - - @Test - void aTlsBrokerWithScramCredentialsConfiguresTheProducerForSaslSsl() { - runner - .withUserConfiguration(Credentials.class) - .withPropertyValues(SCRAM_CREDENTIALS) - .withPropertyValues( - "app.messaging.brokers.kafka-primary.tls-enabled=true", - "app.messaging.brokers.kafka-primary.authentication-enabled=true") - .run( - context -> - assertThat(producerConfig(context)) - .extractingByKeys( - "security.protocol", - "sasl.mechanism", - "ssl.enabled.protocols", - "ssl.endpoint.identification.algorithm") - .containsExactly("SASL_SSL", "SCRAM-SHA-512", "TLSv1.3,TLSv1.2", "https")); - } - - @Test - void aPlaintextBrokerWithPasswordCredentialsConfiguresTheProducerForSaslPlaintext() { - runner - .withUserConfiguration(Credentials.class) - .withPropertyValues( - "app.messaging.brokers.kafka-primary.authentication-enabled=true", - "app.messaging.security.kafka-primary.producer.type=USERNAME_PASSWORD", - "app.messaging.security.kafka-primary.producer.credential-id=kafka-producer", - "app.messaging.security.kafka-primary.consumer.type=USERNAME_PASSWORD", - "app.messaging.security.kafka-primary.consumer.credential-id=kafka-consumer") - .run( - context -> - assertThat(producerConfig(context)) - .extractingByKeys("security.protocol", "sasl.mechanism") - .containsExactly("SASL_PLAINTEXT", "PLAIN")); - } - - @Test - void theProducerAuthenticatesAsTheUsernameTheProviderReturnsNotAsTheCredentialId() { - runner - .withUserConfiguration(Credentials.class) - .withPropertyValues(SCRAM_CREDENTIALS) - .withPropertyValues("app.messaging.brokers.kafka-primary.tls-enabled=true") - .run( - context -> { - // given - Map config = producerConfig(context); - - // when - Answer answer = authenticate(config); - - // then - assertThat(answer).isEqualTo(new Answer(Credentials.USERNAME, Credentials.SECRET)); - }); - } - - @Test - void aRotatedPasswordReachesTheNextAuthenticationWithoutRebuildingTheProducer() { - runner - .withUserConfiguration(RotatingCredentials.class) - .withPropertyValues(SCRAM_CREDENTIALS) - .withPropertyValues("app.messaging.brokers.kafka-primary.tls-enabled=true") - .run( - context -> { - // given - Map config = producerConfig(context); - RotatingCredentials.CURRENT.set("rotated-secret"); - - // when - Answer answer = authenticate(config); - - // then - assertThat(answer.password()).isEqualTo("rotated-secret"); - }); - } - - @Test - void aPrivateCaTrustStoreReachesTheProducer() { - runner - .withUserConfiguration(Credentials.class, StoreFilesAbsent.class) - .withPropertyValues(SCRAM_CREDENTIALS) - .withPropertyValues( - "app.messaging.brokers.kafka-primary.tls-enabled=true", - "app.messaging.security.kafka-primary.trust-store.location=/etc/kafka/private-ca.p12", - "app.messaging.security.kafka-primary.trust-store.password-credential-id=kafka-trust") - .run( - context -> - assertThat(producerConfig(context)) - .extractingByKeys( - "ssl.truststore.location", "ssl.truststore.type", "ssl.truststore.password") - .containsExactly("/etc/kafka/private-ca.p12", "PKCS12", Credentials.SECRET)); - } - - @Test - void mutualTlsPresentsTheProducerKeyStoreUnlockedByItsCredential() { - runner - .withUserConfiguration(Credentials.class, StoreFilesAbsent.class) - .withPropertyValues(MUTUAL_TLS_CREDENTIALS) - .run( - context -> - assertThat(producerConfig(context)) - .extractingByKeys( - "security.protocol", - "ssl.keystore.location", - "ssl.keystore.type", - "ssl.keystore.password") - .containsExactly( - "SSL", "/etc/kafka/producer.p12", "PKCS12", Credentials.SECRET)); - } - - @Test - void mutualTlsWithoutAKeyStoreFailsStartupNamingTheKey() { - runner - .withUserConfiguration(Credentials.class) - .withPropertyValues(MUTUAL_TLS_CREDENTIALS) - .withPropertyValues("app.messaging.security.kafka-primary.producer.key-store.location=") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .as("a client certificate nobody configured cannot be presented") - .hasMessageContaining( - "app.messaging.security.kafka-primary.producer.key-store: MUTUAL_TLS")); - } - - @Test - void mutualTlsOnABrokerWithoutTlsFailsStartup() { - runner - .withUserConfiguration(Credentials.class) - .withPropertyValues(MUTUAL_TLS_CREDENTIALS) - .withPropertyValues("app.messaging.brokers.kafka-primary.tls-enabled=false") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .as("a certificate only authenticates inside a TLS handshake") - .hasMessageContaining("authenticates with a client certificate but does not")); - } - - @Test - void aBrokerDeclaringTlsWithoutASecurityEntryFailsStartup() { - runner - .withPropertyValues("app.messaging.brokers.kafka-primary.tls-enabled=true") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .as("a producer that cannot apply TLS connected over plaintext instead") - .hasMessageContaining("app.messaging.security.kafka-primary")); - } - - @Test - void aSecurityEntryWithoutACredentialProviderFailsStartup() { - runner - .withPropertyValues(SCRAM_CREDENTIALS) - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .as("a producer that cannot resolve its credential connected without one") - .hasMessageContaining("CredentialProvider")); - } - - private static Map producerConfig(AssertableApplicationContext context) { - return KafkaMessagingAutoConfiguration.producerConfig( - context.getBean(CompiledMessagingConfiguration.class), - context.getBean(KafkaBrokerCatalog.class), - context.getBeanProvider(BrokerSecurityProfile.class), - context.getBeanProvider(KafkaSecurityConfigurer.class)); - } - - /** What a SASL client is told when it asks for a name and a password. */ - private record Answer(String name, String password) {} - - /** - * Authenticates the way Kafka's SASL client does: instantiate the configured handler class, - * configure it with the client's own configuration, then ask it for a name and a password. - */ - private static Answer authenticate(Map config) throws Exception { - assertThat(config).containsKey("sasl.client.callback.handler.class"); - Class type = (Class) config.get("sasl.client.callback.handler.class"); - AuthenticateCallbackHandler handler = - (AuthenticateCallbackHandler) type.getDeclaredConstructor().newInstance(); - handler.configure(config, String.valueOf(config.get("sasl.mechanism")), List.of()); - NameCallback name = new NameCallback("name"); - PasswordCallback password = new PasswordCallback("password", false); - handler.handle(new Callback[] {name, password}); - handler.close(); - return new Answer(name.getName(), new String(password.getPassword())); - } - - /** A credential source that answers every id with the same test principal and secret. */ - @Configuration(proxyBeanMethods = false) - static class Credentials { - - static final String SECRET = "test-only-secret"; - - static final String USERNAME = "svc-orders"; - - @Bean - CredentialProvider credentialProvider() { - return new CredentialProvider() { - @Override - public char[] resolve(String credentialId) { - return SECRET.toCharArray(); - } - - @Override - public Optional expiresAt(String credentialId) { - return Optional.empty(); - } - - @Override - public Optional username(String credentialId) { - return Optional.of(USERNAME); - } - }; - } - } - - /** - * Stands in for the producer when the store paths in a test name no real file. - * - *

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

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

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

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

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

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

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

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

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

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

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

The admission gate and the drain coordinator both existed and neither was driven by anything, - * so a shutdown went straight to destroying beans: publishes in flight, handlers between their side - * effect and their settlement, and no phase in between. - */ -class MessagingShutdownLifecycleTest { - - private static final Instant NOW = Instant.parse("2026-08-15T12:00:00Z"); - - private final MessagingAdmissionController admission = - new MessagingAdmissionController( - new PayloadLimitGuard(PayloadPolicy.defaults()), - new InFlightLimiter(4, Duration.ofMillis(10))); - - private final GracefulShutdownCoordinator drain = - new GracefulShutdownCoordinator(Duration.ofSeconds(30)); - - @Test - @DisplayName("stopping refuses new publishes before waiting for the ones in flight") - void stoppingRefusesNewPublishesFirst() { - MessagingShutdownLifecycle lifecycle = lifecycle(Duration.ofSeconds(30), NOW); - lifecycle.start(); - - lifecycle.stop(); - - assertThatThrownBy(() -> admission.admit("order-events", 16)) - .as("a drain that new work keeps topping up finishes only when the deadline passes") - .isInstanceOf(MessageBackpressureException.class); - assertThat(drain.isAcceptingWork()).isFalse(); - assertThat(lifecycle.isRunning()).isFalse(); - } - - @Test - @DisplayName("a handler that never returns does not hold the process open") - void aLeakedHandlerDoesNotHoldTheProcessOpen() { - // Work that begins and never ends: the drain can only finish by reaching its deadline. - GracefulShutdownCoordinator leaking = new GracefulShutdownCoordinator(Duration.ofMillis(100)); - leaking.tryBeginWork(); - AtomicReference clock = new AtomicReference<>(NOW); - MessagingShutdownLifecycle lifecycle = - new MessagingShutdownLifecycle( - admission, - leaking, - Duration.ofMillis(150), - () -> clock.getAndUpdate(current -> current.plusMillis(100))); - lifecycle.start(); - - lifecycle.stop(); - - assertThat(leaking.inFlight()) - .as("work still running at the deadline is abandoned unsettled, not counted as done") - .isEqualTo(1); - assertThat(leaking.abandonedWorkAtDeadline(clock.get())).isTrue(); - } - - private MessagingShutdownLifecycle lifecycle(Duration drainDeadline, Instant fixed) { - return new MessagingShutdownLifecycle(admission, drain, drainDeadline, () -> fixed); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java b/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java deleted file mode 100644 index e611c070..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java +++ /dev/null @@ -1,255 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.schema.EncodedMessagePublisher; -import java.util.Set; -import java.util.concurrent.CompletionStage; -import java.util.stream.Collectors; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; -import org.springframework.boot.autoconfigure.AutoConfigurations; -import org.springframework.boot.test.context.runner.ApplicationContextRunner; - -/** - * Off means nothing, and on means exactly one transport (MSG-INT-004). - * - *

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

The cases below are the replacement contract. The off case is deliberately checked on bean - * names and live threads rather than on a handful of types: a platform that leaves a scheduler - * running is not off, whatever its bean inventory says. - */ -class MessagingStarterOffContractTest { - - private final ApplicationContextRunner runner = - new ApplicationContextRunner() - .withConfiguration(AutoConfigurations.of(MessagingPlatformRootAutoConfiguration.class)); - - @Test - @DisplayName("present without the switch is on") - void presentWithoutTheSwitchIsOn() { - runner - .withPropertyValues( - "app.messaging.broker=kafka", - "app.messaging.brokers.kafka.type=kafka", - "app.messaging.brokers.kafka.bootstrap-servers[0]=localhost:9092") - .run( - context -> { - assertThat(context).hasNotFailed(); - assertThat(context).hasSingleBean(MessagePublisher.class); - }); - } - - @Test - @DisplayName("with the switch off there are no platform beans") - void offMeansNoBeans() { - runner - .withPropertyValues("app.messaging.enabled=false") - .run( - context -> { - assertThat(context).hasNotFailed(); - - Set platformBeans = - java.util.Arrays.stream(context.getBeanDefinitionNames()) - .filter( - name -> { - Class type = context.getBeanFactory().getType(name, false); - return type != null - && type.getName().startsWith("dev.caskeleton.messaging."); - }) - .collect(Collectors.toSet()); - - assertThat(platformBeans) - .as("off is a structural fact, not a set of individually-conditioned beans") - .isEmpty(); - }); - } - - @Test - @DisplayName("with the switch off no thread is started") - void offMeansNoThreads() { - Set before = liveThreadNames(); - - runner - .withPropertyValues("app.messaging.enabled=false") - .run(context -> assertThat(context).hasNotFailed()); - - assertThat(newMessagingThreadsSince(before)) - .as("a bean that exists but was never started is acceptable; a running thread is not") - .isEmpty(); - } - - @Test - @DisplayName("on with no broker names the property") - void onWithoutABrokerNamesTheProperty() { - runner - .withPropertyValues("app.messaging.enabled=true") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .rootCause() - .hasMessageContaining("app.messaging.broker")); - } - - @Test - @DisplayName("an unregistered broker is refused, and the message lists what is registered") - void anUnregisteredBrokerIsRefused() { - runner - .withPropertyValues("app.messaging.enabled=true", "app.messaging.broker=carrier-pigeon") - .run( - context -> - assertThat(context) - .hasFailed() - .getFailure() - .rootCause() - .hasMessageContaining("registered: [kafka]")); - } - - @Test - @DisplayName("selecting Kafka assembles Kafka") - void selectingKafkaAssemblesOnlyKafka() { - withAPublisher() - .withPropertyValues( - "app.messaging.enabled=true", - "app.messaging.broker=kafka", - "app.messaging.brokers.kafka.type=kafka", - "app.messaging.brokers.kafka.bootstrap-servers[0]=localhost:9092") - .run( - context -> { - assertThat(context).hasNotFailed(); - assertThat(context).hasSingleBean(KafkaMessagingAutoConfiguration.class); - }); - } - - @Test - @DisplayName("MSG-INT-003: a selected transport now assembles a publisher") - void aSelectedTransportAssemblesAPublisher() { - runner - .withPropertyValues( - "app.messaging.enabled=true", - "app.messaging.broker=kafka", - "app.messaging.brokers.kafka.type=kafka", - "app.messaging.brokers.kafka.bootstrap-servers[0]=localhost:9092") - .run( - context -> { - assertThat(context) - .as( - "this asserted the opposite, with the note that C3 would invert it rather" - + " than delete it. Every policy bean was in place and the platform still" - + " could not publish: no configuration produced a MessagePublisher, so" - + " DeadLetterOrchestrator had nothing to depend on." - + " DefaultMessagePublisher existed in messaging-runtime-core the whole" - + " time — the starter did not depend on that leaf.") - .hasNotFailed(); - assertThat(context).hasSingleBean(MessagePublisher.class); - assertThat(context).hasSingleBean(EncodedMessagePublisher.class); - }); - } - - @Test - @DisplayName("a selected publisher uses the Micrometer observation bean when a registry exists") - void selectedPublisherIsObserved() { - runner - .withBean( - io.micrometer.core.instrument.MeterRegistry.class, - io.micrometer.core.instrument.simple.SimpleMeterRegistry::new) - .withPropertyValues( - "app.messaging.enabled=true", - "app.messaging.broker=kafka", - "app.messaging.brokers.kafka.type=kafka", - "app.messaging.brokers.kafka.bootstrap-servers[0]=localhost:9092") - .run( - context -> { - assertThat(context) - .hasSingleBean(dev.caskeleton.messaging.observation.MessagingObservation.class); - Object publisher = context.getBean(MessagePublisher.class); - assertThat(publisher) - .isInstanceOf(dev.caskeleton.messaging.runtime.DefaultMessagePublisher.class); - - try { - java.lang.reflect.Field observation = - publisher.getClass().getDeclaredField("observation"); - observation.setAccessible(true); - assertThat(observation.get(publisher)) - .isSameAs( - context.getBean( - dev.caskeleton.messaging.observation.MessagingObservation.class)); - } catch (ReflectiveOperationException failure) { - throw new LinkageError(failure.getMessage(), failure); - } - }); - } - - @Test - @DisplayName("a selected broker with no address fails at startup, not at the first publish") - void aSelectedBrokerWithNoAddressFailsAtStartup() { - runner - .withPropertyValues("app.messaging.enabled=true", "app.messaging.broker=kafka") - .run( - context -> - assertThat(context) - .as( - "a producer built with no bootstrap servers defaults to localhost:9092 and " - + "fails on the first publish — which is a deployment that starts, " - + "reports healthy, and loses the first message somebody sends") - .hasFailed() - .getFailure() - .rootCause() - .hasMessageContaining("app.messaging.brokers.")); - } - - /** - * The same runner with a publisher supplied by the test. - * - *

Only so the selection cases are about selection. The platform having no production publisher - * of its own is a separate fact with a case of its own above, and letting it fail these two would - * have hidden a defect behind a defect. - */ - private ApplicationContextRunner withAPublisher() { - return runner.withBean( - MessagePublisher.class, - () -> - new MessagePublisher() { - @Override - public CompletionStage publish( - MessageDestination destination, - MessageEnvelope message, - PublishOptions options) { - throw new UnsupportedOperationException("never invoked; this test assembles only"); - } - }); - } - - private static Set liveThreadNames() { - return Thread.getAllStackTraces().keySet().stream() - .filter(Thread::isAlive) - .map(Thread::getName) - .collect(Collectors.toSet()); - } - - private static Set newMessagingThreadsSince(Set before) { - return liveThreadNames().stream() - .filter(name -> !before.contains(name)) - .filter( - name -> { - String lower = name.toLowerCase(java.util.Locale.ROOT); - return lower.contains("kafka") - || lower.contains("messaging") - || lower.contains("outbox"); - }) - .collect(Collectors.toSet()); - } -} diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/resources/application-invalid-ordering.yml b/src/platforms/messaging/messaging-spring-boot-starter/src/test/resources/application-invalid-ordering.yml deleted file mode 100644 index c332eedf..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/resources/application-invalid-ordering.yml +++ /dev/null @@ -1,11 +0,0 @@ -# A configuration the platform must refuse. -# -# The per-destination in-flight limit exceeds the global one, which means the global limit is not -# a limit at all: a single destination could hold more work in flight than the whole process is -# allowed to. The controller rejects this at construction, so the context fails to start rather -# than running with a ceiling that does not bound anything. -backend: - messaging: - backpressure: - global-limit: 64 - per-destination-limit: 512 diff --git a/src/platforms/messaging/messaging-spring-boot-starter/src/test/resources/application-valid.yml b/src/platforms/messaging/messaging-spring-boot-starter/src/test/resources/application-valid.yml deleted file mode 100644 index b1894f08..00000000 --- a/src/platforms/messaging/messaging-spring-boot-starter/src/test/resources/application-valid.yml +++ /dev/null @@ -1,14 +0,0 @@ -# A configuration the platform accepts. -backend: - messaging: - backpressure: - # The per-destination limit stays below the global one; a per-destination limit at or above - # the global limit would let one destination consume every slot in the process. - global-limit: 512 - per-destination-limit: 64 - shutdown: - # The design's default drain budget. Work still running at the deadline is abandoned - # unsettled so the broker redelivers it. - drain-deadline: 30s - admin: - enabled: false diff --git a/src/platforms/messaging/messaging-testkit/build.gradle b/src/platforms/messaging/messaging-testkit/build.gradle deleted file mode 100644 index 0b4b6577..00000000 --- a/src/platforms/messaging/messaging-testkit/build.gradle +++ /dev/null @@ -1,18 +0,0 @@ -plugins { - id 'ca.platform-module' - id 'me.champeau.jmh' -} - -jmh { - jmhVersion = libs.versions.jmh.get() - includeTests = true -} - -dependencies { - api project(':messaging:messaging-core-api') - api project(':messaging:messaging-policy') - api project(':messaging:messaging-transport-spi') - - api 'org.junit.jupiter:junit-jupiter' - api 'org.assertj:assertj-core' -} diff --git a/src/platforms/messaging/messaging-testkit/gradle.lockfile b/src/platforms/messaging/messaging-testkit/gradle.lockfile deleted file mode 100644 index 1894c4f3..00000000 --- a/src/platforms/messaging/messaging-testkit/gradle.lockfile +++ /dev/null @@ -1,89 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,jmhAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,jmhAnnotationProcessor,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,jmhAnnotationProcessor,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,jmhAnnotationProcessor,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,jmhAnnotationProcessor,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.21.0=spotbugs -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -javax.inject:javax.inject:1=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=compileClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -net.sf.jopt-simple:jopt-simple:5.0.4=jmh,jmhCompileClasspath,jmhRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs -org.apache.commons:commons-math3:3.6.1=jmh,jmhCompileClasspath,jmhRuntimeClasspath -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=compileClasspath,jmhCompileClasspath,testCompileClasspath -org.assertj:assertj-core:3.27.7=compileClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,jmhAnnotationProcessor,jmhCompileClasspath,testAnnotationProcessor,testCompileClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=compileClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=jmhRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=compileClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=compileClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=compileClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=jmhRuntimeClasspath,runtimeClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=jmhRuntimeClasspath,testRuntimeClasspath -org.junit:junit-bom:6.0.3=compileClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.mockito:mockito-core:5.20.0=mockitoAgent -org.openjdk.jmh:jmh-core:1.37=jmh,jmhCompileClasspath,jmhRuntimeClasspath -org.openjdk.jmh:jmh-generator-asm:1.37=jmh,jmhCompileClasspath,jmhRuntimeClasspath -org.openjdk.jmh:jmh-generator-bytecode:1.37=jmh,jmhCompileClasspath,jmhRuntimeClasspath -org.openjdk.jmh:jmh-generator-reflection:1.37=jmh,jmhCompileClasspath,jmhRuntimeClasspath -org.opentest4j:opentest4j:1.3.0=compileClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.0=jmh,jmhCompileClasspath,jmhRuntimeClasspath -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty= diff --git a/src/platforms/messaging/messaging-testkit/src/jmh/java/dev/caskeleton/messaging/testkit/EnvelopeCodecBenchmark.java b/src/platforms/messaging/messaging-testkit/src/jmh/java/dev/caskeleton/messaging/testkit/EnvelopeCodecBenchmark.java deleted file mode 100644 index 4a7135d8..00000000 --- a/src/platforms/messaging/messaging-testkit/src/jmh/java/dev/caskeleton/messaging/testkit/EnvelopeCodecBenchmark.java +++ /dev/null @@ -1,126 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.ProducerId; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.TraceContext; -import dev.caskeleton.messaging.api.UuidV7; -import dev.caskeleton.messaging.api.header.HeaderName; -import dev.caskeleton.messaging.api.header.HeaderValue; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import java.time.Instant; -import java.util.LinkedHashMap; -import java.util.Map; -import java.util.Optional; -import java.util.concurrent.TimeUnit; -import org.openjdk.jmh.annotations.Benchmark; -import org.openjdk.jmh.annotations.BenchmarkMode; -import org.openjdk.jmh.annotations.Fork; -import org.openjdk.jmh.annotations.Measurement; -import org.openjdk.jmh.annotations.Mode; -import org.openjdk.jmh.annotations.OutputTimeUnit; -import org.openjdk.jmh.annotations.Scope; -import org.openjdk.jmh.annotations.Setup; -import org.openjdk.jmh.annotations.State; -import org.openjdk.jmh.annotations.Warmup; -import org.openjdk.jmh.infra.Blackhole; - -/** - * Measures the per-message cost the platform adds before any broker is involved. - * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The certification claim is derived from lane evidence rather than declared beside the grade, - * so an adapter cannot be promoted by editing a boolean. - */ -public final class CompatibilityMatrix { - - private CompatibilityMatrix() {} - - /** The support grade an adapter has earned. */ - public enum SupportGrade { - /** Passes the shared adapter contract unchanged. */ - STABLE, - - /** Contract coverage is still being proven; disabled by default. */ - EXPERIMENTAL, - - /** Adapter SPI only; outside the supported set. */ - EXTENSION - } - - /** - * One certified adapter. - * - * @param adapter the module name - * @param brokerVersions the broker versions the adapter is certified against - * @param grade the support grade - * @param runsSharedContract whether the module runs {@link MessagingAdapterContract} - * @param enabledByDefault whether the adapter is active without an explicit opt-in - */ - public record Entry( - String adapter, - List brokerVersions, - SupportGrade grade, - boolean runsSharedContract, - boolean enabledByDefault) { - - /** - * Reports whether a lane has run this adapter against a real broker. - * - *

Read from the evidence rather than declared. As a field it was a boolean an author set - * next to the grade, and an Experimental adapter carried {@code true} while no fault scenario - * had ever been executed against it — the same shape as the coverage matrix that used to assert - * its own constants. - * - * @return true when {@link CertifiedEvidence} has live-broker evidence for this adapter - */ - public boolean hasLiveBrokerCertification() { - return BrokerFailureMatrix.from(CertifiedEvidence.recorded()) - .hasCertificationCoverage(adapter, CertifiedEvidence.approvedGaps(adapter)); - } - - public Entry { - Objects.requireNonNull(grade, "grade must not be null"); - Objects.requireNonNull(brokerVersions, "brokerVersions must not be null"); - if (adapter == null || adapter.isBlank()) { - throw new IllegalArgumentException("adapter must not be blank"); - } - if (brokerVersions.isEmpty()) { - throw new IllegalArgumentException("an adapter must certify at least one broker version"); - } - brokerVersions = List.copyOf(brokerVersions); - } - } - - private static final Map ENTRIES = - Map.of( - "messaging-kafka", - // 4.1 only. The declared 4.2/4.3 were never run: the fixtures pin apache/kafka:4.1.0 and - // the locked client is 4.1.1, so the matrix and the support document agreed with each - // other and with nothing that had executed. A version returns here when a lane runs - // against its image. - new Entry("messaging-kafka", List.of("4.1"), SupportGrade.STABLE, true, true)); - - /** - * Returns every certified adapter. - * - * @return the entries, keyed by module name - */ - public static Map entries() { - return ENTRIES; - } - - /** - * Returns one adapter's entry. - * - * @param adapter the module name - * @return the entry - */ - public static Entry of(String adapter) { - Entry entry = ENTRIES.get(adapter); - if (entry == null) { - throw new IllegalArgumentException("adapter is not in the compatibility matrix: " + adapter); - } - return entry; - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/ContractAssertions.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/ContractAssertions.java deleted file mode 100644 index 2bed0f11..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/ContractAssertions.java +++ /dev/null @@ -1,51 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.publish.ConfirmationLevel; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.api.publish.TransmissionEvidence; - -/** Assertions every adapter's contract run shares. */ -public final class ContractAssertions { - - private ContractAssertions() {} - - /** - * Asserts a publish confirmed with real broker evidence. - * - * @param result the publish outcome - */ - public static void assertConfirmed(PublishResult result) { - assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED); - assertThat(result.evidence().brokerAccepted()).isTrue(); - assertThat(result.evidence().confirmationLevel()).isNotEqualTo(ConfirmationLevel.NONE); - assertThat(result.evidence().transmission()).isEqualTo(TransmissionEvidence.TRANSMITTED); - } - - /** - * Asserts a publish reported ambiguity without claiming any confirmation. - * - * @param result the publish outcome - */ - public static void assertAmbiguous(PublishResult result) { - assertThat(result.completion()).isEqualTo(PublishCompletion.AMBIGUOUS); - assertThat(result.evidence().confirmationLevel()).isEqualTo(ConfirmationLevel.NONE); - assertThat(result.evidence().brokerAccepted()).isFalse(); - assertThat(result.evidence().transmission()) - .isEqualTo(TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED); - assertThat(result.mayHaveBeenStored()).isTrue(); - } - - /** - * Asserts a publish was refused before anything left the process. - * - * @param result the publish outcome - */ - public static void assertRejectedLocally(PublishResult result) { - assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); - assertThat(result.evidence().transmission()).isEqualTo(TransmissionEvidence.NOT_TRANSMITTED); - assertThat(result.failure()).isPresent(); - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/ContractMessage.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/ContractMessage.java deleted file mode 100644 index 7c9239fe..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/ContractMessage.java +++ /dev/null @@ -1,87 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.ProducerId; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.TraceContext; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.schema.EncodedMessage; -import java.nio.charset.StandardCharsets; -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; - -/** - * The standard messages every adapter contract run uses. - * - *

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

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

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

This suite is the platform's actual definition of "supported". A broker is Stable when it - * passes these unchanged — not when it has an adapter that compiles. Each test pins one of the - * guarantees the design refuses to weaken: ambiguity is reported rather than guessed, settlement - * follows handler success, logical identity survives retry and dead lettering, and a source is - * never acknowledged on the strength of a dead letter publish that failed. - */ -public abstract class MessagingAdapterContract { - - /** - * Returns a fresh harness for one test. - * - * @return the adapter harness under test - */ - protected abstract MessagingAdapterHarness harness(); - - @Test - void publishesAndConfirms() { - try (MessagingAdapterHarness harness = harness()) { - PublishResult result = join(harness.publish(ContractMessage.orderCreated())); - - ContractAssertions.assertConfirmed(result); - } - } - - @Test - void returnsAmbiguousWhenConfirmIsLost() { - try (MessagingAdapterHarness harness = harness()) { - harness.faults().dropPublishConfirmation(); - - PublishResult result = join(harness.publish(ContractMessage.orderCreated())); - - ContractAssertions.assertAmbiguous(result); - } - } - - @Test - void redeliversWhenSettlementIsLost() { - try (MessagingAdapterHarness harness = harness()) { - ContractMessage message = ContractMessage.orderCreated(); - join(harness.publish(message)); - harness.faults().dropSettlementConfirmation(); - - List first = harness.drain(HandleOutcome.SUCCESS); - assertThat(first) - .singleElement() - .satisfies( - delivery -> { - assertThat(delivery.messageId()).isEqualTo(message.messageId()); - assertThat(delivery.settled()).isFalse(); - }); - - List second = harness.drain(HandleOutcome.SUCCESS); - assertThat(second) - .singleElement() - .satisfies( - delivery -> { - assertThat(delivery.messageId()).isEqualTo(message.messageId()); - assertThat(delivery.attempt()).isEqualTo(2); - assertThat(delivery.redelivered()).isTrue(); - }); - } - } - - @Test - void preservesMessageIdAcrossRetryAndDlq() { - try (MessagingAdapterHarness harness = harness()) { - ContractMessage message = ContractMessage.orderCreated(); - join(harness.publish(message)); - MessageId original = message.messageId(); - - List retried = harness.drain(HandleOutcome.RETRY); - assertThat(retried) - .singleElement() - .extracting(ObservedDelivery::messageId) - .isEqualTo(original); - - List redelivered = harness.drain(HandleOutcome.DEAD_LETTER); - assertThat(redelivered) - .singleElement() - .extracting(ObservedDelivery::messageId) - .isEqualTo(original); - - assertThat(harness.deadLettered()).containsExactly(original); - } - } - - @Test - void keepsSourceUnsettledWhenDlqPublishFails() { - try (MessagingAdapterHarness harness = harness()) { - ContractMessage message = ContractMessage.orderCreated(); - join(harness.publish(message)); - harness.faults().failDeadLetterPublish(); - - List observed = harness.drain(HandleOutcome.DEAD_LETTER); - - assertThat(observed).singleElement().extracting(ObservedDelivery::settled).isEqualTo(false); - assertThat(harness.deadLettered()).isEmpty(); - assertThat(harness.unsettled()).contains(message.messageId()); - } - } - - @Test - void rejectsOversizedPayloadBeforeTransport() { - try (MessagingAdapterHarness harness = harness()) { - PublishResult result = join(harness.publish(ContractMessage.oversized())); - - ContractAssertions.assertRejectedLocally(result); - } - } - - @Test - void stopsAcceptingNewWorkDuringShutdown() { - try (MessagingAdapterHarness harness = harness()) { - assertThat(harness.isAcceptingWork()).isTrue(); - - harness.beginShutdown(); - - assertThat(harness.isAcceptingWork()).isFalse(); - PublishResult result = join(harness.publish(ContractMessage.orderCreated())); - ContractAssertions.assertRejectedLocally(result); - } - } - - private static PublishResult join(java.util.concurrent.CompletionStage stage) { - return stage.toCompletableFuture().join(); - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/MessagingAdapterHarness.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/MessagingAdapterHarness.java deleted file mode 100644 index a17f10e7..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/MessagingAdapterHarness.java +++ /dev/null @@ -1,73 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.publish.PublishResult; -import java.util.List; -import java.util.concurrent.CompletionStage; - -/** - * The seam each broker adapter implements to run the common contract. - * - *

The harness exposes outcomes, not internals: what the platform decided, what reached the dead - * letter destination, and what is still unsettled. Each broker answers those three questions with - * its own machinery, and the contract only passes if the answers match. - */ -public interface MessagingAdapterHarness extends AutoCloseable { - - /** - * Returns the broker under test. - * - * @return the broker name - */ - String brokerName(); - - /** - * Returns the fault injector for this harness. - * - * @return the fault controller - */ - FaultController faults(); - - /** - * Publishes one contract message. - * - * @param message the message to publish - * @return a stage completing with the outcome and evidence - */ - CompletionStage publish(ContractMessage message); - - /** - * Delivers everything currently pending to a handler that returns the given outcome. - * - * @param outcome what the handler decides for each delivery - * @return what the harness observed, in delivery order - */ - List drain(HandleOutcome outcome); - - /** - * Returns the identities that reached the dead letter destination. - * - * @return dead lettered message identities - */ - List deadLettered(); - - /** - * Returns the identities still unsettled at the source. - * - * @return unsettled message identities - */ - List unsettled(); - - /** Begins a graceful drain. */ - void beginShutdown(); - - /** - * Reports whether the harness still accepts new work. - * - * @return true until shutdown begins - */ - boolean isAcceptingWork(); - - @Override - void close(); -} diff --git a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/NetworkFaultScenario.java b/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/NetworkFaultScenario.java deleted file mode 100644 index 403c954f..00000000 --- a/src/platforms/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/NetworkFaultScenario.java +++ /dev/null @@ -1,151 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import java.time.Duration; -import java.util.Objects; -import java.util.Optional; - -/** - * A named network fault, and the outcome an adapter must report while it is active. - * - *

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

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

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

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

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

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

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

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

This is the contract testing itself. Every broker adapter adds the same nested class over its - * own harness, so a guarantee can only be weakened by editing the contract, where the change is - * visible, rather than by an adapter quietly not implementing it. - */ -class InMemoryHarnessContractTest { - - @Nested - class Contract extends MessagingAdapterContract { - - @Override - protected MessagingAdapterHarness harness() { - return InMemoryMessagingHarness.create(); - } - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/InMemoryMessagingHarness.java b/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/InMemoryMessagingHarness.java deleted file mode 100644 index 9f3c9c0c..00000000 --- a/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/InMemoryMessagingHarness.java +++ /dev/null @@ -1,260 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.publish.ConfirmationLevel; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishEvidence; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.api.publish.RoutingOutcome; -import java.time.Duration; -import java.util.ArrayDeque; -import java.util.ArrayList; -import java.util.Deque; -import java.util.LinkedHashSet; -import java.util.List; -import java.util.Optional; -import java.util.Set; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; - -/** - * A deterministic harness that exists only to prove the contract suite itself is sound. - * - *

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

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

When that publish fails the source stays unsettled and in flight. Acknowledging it here - * would destroy the last copy of a message the dead letter destination never received. - */ - private boolean deadLetter(Pending delivery) { - if (faults.deadLetterPublishFails()) { - unsettled.add(delivery.messageId()); - redeliver(delivery); - return false; - } - deadLetters.add(delivery.messageId()); - unsettled.remove(delivery.messageId()); - return true; - } - - private void redeliver(Pending delivery) { - pending.addLast(new Pending(delivery.messageId(), delivery.attempt() + 1, true)); - } - - @Override - public List deadLettered() { - return List.copyOf(deadLetters); - } - - @Override - public List unsettled() { - return List.copyOf(unsettled); - } - - @Override - public void beginShutdown() { - shuttingDown = true; - } - - @Override - public boolean isAcceptingWork() { - return !shuttingDown; - } - - @Override - public void close() { - pending.clear(); - } - - private static PublishResult rejected(String code, String message) { - return new PublishResult( - PublishCompletion.REJECTED, - PublishEvidence.notTransmitted(), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ZERO, - Optional.of(FailureDescriptor.of(FailureCategory.PERMANENT_BUSINESS, code, message))); - } - - private static CompletionStage completed(PublishResult result) { - return CompletableFuture.completedFuture(result); - } - - /** One message waiting to be delivered. */ - private record Pending(MessageId messageId, int attempt, boolean redelivered) {} - - /** One-shot fault flags, consumed by the operation they target. */ - private static final class Faults implements FaultController { - - private boolean dropPublishConfirmation; - private boolean dropSettlementConfirmation; - private boolean failDeadLetterPublish; - private boolean rejectPublish; - - @Override - public void dropPublishConfirmation() { - dropPublishConfirmation = true; - } - - @Override - public void dropSettlementConfirmation() { - dropSettlementConfirmation = true; - } - - @Override - public void failDeadLetterPublish() { - failDeadLetterPublish = true; - } - - @Override - public void rejectPublish() { - rejectPublish = true; - } - - @Override - public void reset() { - dropPublishConfirmation = false; - dropSettlementConfirmation = false; - failDeadLetterPublish = false; - rejectPublish = false; - } - - boolean consumeDropPublishConfirmation() { - boolean active = dropPublishConfirmation; - dropPublishConfirmation = false; - return active; - } - - boolean consumeDropSettlementConfirmation() { - boolean active = dropSettlementConfirmation; - dropSettlementConfirmation = false; - return active; - } - - boolean consumeRejectPublish() { - boolean active = rejectPublish; - rejectPublish = false; - return active; - } - - boolean deadLetterPublishFails() { - return failDeadLetterPublish; - } - } -} diff --git a/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/MessagingDocumentationContractTest.java b/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/MessagingDocumentationContractTest.java deleted file mode 100644 index cc5755ba..00000000 --- a/src/platforms/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/MessagingDocumentationContractTest.java +++ /dev/null @@ -1,141 +0,0 @@ -package dev.caskeleton.messaging.testkit; - -import static org.assertj.core.api.Assertions.assertThat; - -import java.io.IOException; -import java.nio.file.Files; -import java.nio.file.Path; -import java.util.List; -import org.junit.jupiter.api.Test; - -/** - * Checks that the shipped documentation still describes the code. - * - *

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

The assertions are deliberately narrow: they check the claims a reader would act on, not - * prose. Asserting on wording would make every edit a test failure and the check would be deleted. - */ -class MessagingDocumentationContractTest { - - private static Path docsRoot() { - Path candidate = Path.of("").toAbsolutePath(); - while (candidate != null && !Files.isDirectory(candidate.resolve("docs/messaging"))) { - candidate = candidate.getParent(); - } - if (candidate == null) { - throw new IllegalStateException("could not locate docs/messaging from the test cwd"); - } - return candidate.resolve("docs/messaging"); - } - - private static String read(String name) { - try { - return Files.readString(docsRoot().resolve(name)); - } catch (IOException failure) { - throw new IllegalStateException("could not read " + name, failure); - } - } - - @Test - void everyDocumentTheSupportMatrixPromisesExists() { - List expected = - List.of( - "support-matrix.md", - "delivery-guarantees.md", - "retry-dlq-redrive.md", - "outbox-inbox.md", - "security.md", - "operations.md", - "configuration-reference.md", - "experimental-policy.md", - "migration-guide.md"); - - assertThat(expected) - .allSatisfy(name -> assertThat(Files.exists(docsRoot().resolve(name))).isTrue()); - } - - @Test - void theSupportMatrixNamesExactlyTheAdaptersTheCodeCallsStable() { - String matrix = read("support-matrix.md"); - - CompatibilityMatrix.entries().values().stream() - .filter(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE) - .forEach(entry -> assertThat(matrix).contains(brokerLabel(entry.adapter()))); - } - - @Test - void theSupportMatrixDoesNotCallAnExperimentalAdapterStable() { - String matrix = read("support-matrix.md"); - - CompatibilityMatrix.entries().values().stream() - .filter(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.EXPERIMENTAL) - .forEach( - entry -> - assertThat(matrix) - .as("%s is Experimental in code", entry.adapter()) - .doesNotContain("| %s | Stable".formatted(brokerLabel(entry.adapter())))); - } - - @Test - void theDocumentedKafkaVersionsMatchWhatTheCodeCertifies() { - String matrix = read("support-matrix.md"); - - CompatibilityMatrix.of("messaging-kafka") - .brokerVersions() - .forEach(version -> assertThat(matrix).contains(version)); - } - - @Test - void theUnsupportedListStillNamesTheTwoConstantsThatDoNotExist() { - String matrix = read("support-matrix.md"); - - assertThat(matrix) - .as("a reader must be able to confirm the platform never offers these") - .contains("EXACTLY_ONCE") - .contains("GLOBAL"); - } - - @Test - void noEnumConstantTheDocsDenyActuallyExists() { - assertThat( - java.util.Arrays.stream( - dev.caskeleton.messaging.api.delivery.DeliveryGuarantee.values()) - .map(Enum::name)) - .doesNotContain("EXACTLY_ONCE"); - assertThat( - java.util.Arrays.stream(dev.caskeleton.messaging.api.delivery.OrderingScope.values()) - .map(Enum::name)) - .doesNotContain("GLOBAL"); - } - - @Test - void theExperimentalPolicyStatesThatExperimentalIsOffByDefault() { - assertThat(read("experimental-policy.md")).contains("false"); - } - - @Test - void everyDocumentHasContent() { - assertThat( - List.of( - "support-matrix.md", - "delivery-guarantees.md", - "retry-dlq-redrive.md", - "outbox-inbox.md", - "security.md", - "operations.md", - "configuration-reference.md", - "experimental-policy.md", - "migration-guide.md")) - .allSatisfy(name -> assertThat(read(name).length()).isGreaterThan(500)); - } - - private static String brokerLabel(String adapter) { - return switch (adapter) { - case "messaging-kafka" -> "Kafka"; - default -> adapter; - }; - } -} diff --git a/src/platforms/messaging/messaging-transport-spi/build.gradle b/src/platforms/messaging/messaging-transport-spi/build.gradle deleted file mode 100644 index 55c8be51..00000000 --- a/src/platforms/messaging/messaging-transport-spi/build.gradle +++ /dev/null @@ -1,8 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') - api project(':messaging:messaging-policy') -} diff --git a/src/platforms/messaging/messaging-transport-spi/gradle.lockfile b/src/platforms/messaging/messaging-transport-spi/gradle.lockfile deleted file mode 100644 index d74807c4..00000000 --- a/src/platforms/messaging/messaging-transport-spi/gradle.lockfile +++ /dev/null @@ -1,82 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.21.0=spotbugs -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor -javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath -org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.6.1=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath -org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.20=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.20=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty=compileClasspath,runtimeClasspath diff --git a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/DefaultMessagingRuntimeRegistry.java b/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/DefaultMessagingRuntimeRegistry.java deleted file mode 100644 index 5bdc2dec..00000000 --- a/src/platforms/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/DefaultMessagingRuntimeRegistry.java +++ /dev/null @@ -1,254 +0,0 @@ -package dev.caskeleton.messaging.transport; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.time.Duration; -import java.time.Instant; -import java.util.ArrayList; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.concurrent.ConcurrentHashMap; -import java.util.concurrent.atomic.AtomicBoolean; -import java.util.concurrent.atomic.AtomicInteger; - -/** - * Reference-counted runtime generations with an atomic swap on install. - * - *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Closing twice is as much a defect as never closing: a second close on a real connection pool - * throws, and the exception surfaces from a shutdown hook where nothing handles it. - * - * @return the close count - */ - int closeCount() { - return closeCount; - } - - @Override - public void close() { - closeCount++; - } -} diff --git a/src/settings.gradle b/src/settings.gradle index e93d4112..0d94af53 100644 --- a/src/settings.gradle +++ b/src/settings.gradle @@ -16,6 +16,22 @@ plugins { dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { + // The libraries this repository's owner publishes from their own repositories + // (docs/work/reference/related-repos.md): group dev.cakit and below, from the owner's Gitea + // Packages only, and nothing else from there. A public repository serving a dev.cakit + // artifact of the same name is never asked (dependency confusion), and a slow or absent Gitea + // affects no other dependency. Packages of a public owner are read without a token. + exclusiveContent { + forRepository { + maven { + name = 'cakitPackages' + url = 'https://git.learn.hyeonworks.com/api/packages/donghyeon.kang/maven' + } + } + filter { + includeGroupByRegex 'dev\\.cakit(\\..*)?' + } + } mavenCentral() } } diff --git a/src/shared-contract/AGENTS.md b/src/shared-contract/AGENTS.md index c4d00d91..e427fed1 100644 --- a/src/shared-contract/AGENTS.md +++ b/src/shared-contract/AGENTS.md @@ -27,7 +27,7 @@ tracing 이음매, domain-context 전파)은 [README.md](README.md)에 있다. - 모든 leaf가 복사해 쓰던 표준 라이브러리 도우미(2026-09-25 리뷰 후속으로 여기로 옮겼다): `digest/Sha256`(SHA-256 digest 값과 유일한 `MessageDigest.getInstance("SHA-256")`), `digest/HmacSha256`(서명과 상수 시간 검증), `retry/Backoff`(상한 있는 지수 ceiling. "full jitter"는 - `U[0, ceiling]`이고 다른 뜻이 아니다). 들여온 `messaging:*`와 별도 repo 라이브러리(grpc-library)는 이 모듈에 + `U[0, ceiling]`이고 다른 뜻이 아니다). 별도 repo 라이브러리(messaging-library, grpc-library)는 이 모듈에 의존하지 않고 자기 사본을 둔다. 각 제품의 AGENTS.md(라이브러리는 그 repo)가 이유를 적는다(다른 제품이다. 2026-08-14 메시징 모듈 리뷰 뒤에 정했다). 이 도우미가 필요한 템플릿 leaf는 모두 `shared-contract` edge를 두고 복사하지 않고 쓴다. identifier, persistence-mongo, application-objectstorage, redis-sdk가 바로 이 때문에