Merge branch 'refactor/review-followup': 리뷰 후속 Wave 1–3(보안·정합성·구조)
2026-09-24 리뷰 두 건의 후속 반영. Wave 1(보안·데이터), Wave 2(정합성), Wave 2.5, Wave 3(구조) 완료. 현황표 docs/reviews/2026-09-25-review-followup-status.md: 완료 606 · 해당 없음 133 · 보류 5 · 남음 173(W4 테스트 규칙 63 · W5 문서 110). Wave 3 종료 검증 전부 통과(check · ci · mainCheck · integrationCheck · build-logic · optional-platforms · releaseCheck). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -21,20 +21,16 @@ Application의 canonical integration event를 platform publish pipeline으로
|
||||
producing-service identity다.
|
||||
|
||||
값이 없으면 `IntegrationEventPublishPort` bridge 자체를 만들지 않는다. `spring.application.name`이나
|
||||
현재 process 이름으로 추론하지 않는다. 기존 legacy `OutboxEvent`/realtime 경로는 별도 cutover가
|
||||
끝날 때까지 `app.messaging.broker` 경로를 유지한다.
|
||||
현재 process 이름으로 추론하지 않는다. 모든 발행(outbox relay 포함)이 이 bridge를 지나므로 messaging
|
||||
모듈이 켜진 상태에서 값이 없으면 기동이 거부된다.
|
||||
|
||||
## Outbox canonical transport-only cutover
|
||||
## Outbox
|
||||
|
||||
`APP_OUTBOX_CANONICAL_TRANSPORT_ENABLED` / `ca-skeleton.outbox.canonical-transport-enabled`은
|
||||
기존 `outbox_event` writer/claim/status authority를 유지한 채 canonical row의 **transport만** platform
|
||||
publish path로 보내는 compatibility gate다. 기본값은 `false`이며 `POLLING_V2`를 활성화하지 않는다.
|
||||
|
||||
`true`일 때는 `OutboxAppendPort`가 `ValidatedIntegrationEvent`의 exact envelope bytes와 canonical
|
||||
metadata를 기존 outbox row에 저장하고, claim된 canonical row는 `IntegrationEventPublishPort`로 간다.
|
||||
legacy row는 계속 `MessageBroker`를 사용한다. 따라서 mixed-row compatibility 기간에는 relay가 켜져
|
||||
있다면 `app.messaging.broker`도 계속 필요하며, canonical path를 위해 `IntegrationEventPublishPort`도
|
||||
추가로 필요하다. legacy backlog가 0이라는 별도 증거 없이 broker 요구를 제거하지 않는다.
|
||||
outbox는 canonical 하나다(2026-09-28). 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
|
||||
|
||||
@@ -135,9 +131,10 @@ app:
|
||||
|
||||
## Broker profile
|
||||
|
||||
브로커는 `app.messaging.brokers` 아래에 한 번만 기술한다. `type`이 어느 계열의 설정이 적용되는지
|
||||
결정하며, 다른 계열의 키(Kafka 항목의 `prefetch` 같은)는 무시되지 않고 부팅 실패로 거절된다 —
|
||||
무시하면 그 줄을 쓴 사람은 무언가가 적용됐다고 믿게 된다.
|
||||
브로커는 `app.messaging.brokers` 아래에 한 번만 기술한다. `type`은 `kafka`만 받는다 — transport가
|
||||
있는 계열이 Kafka 하나뿐이다. RabbitMQ 키(`addresses`, `prefetch`, `quorum-queues` 등)와
|
||||
`type: rabbitmq`는 2026-09-25에 설정 모델에서 삭제됐다. 연결할 transport 없이 바인딩만 되던 키라,
|
||||
지금은 무시되지 않고 키 이름을 담아 부팅 실패로 거절된다.
|
||||
|
||||
### Kafka
|
||||
|
||||
@@ -160,32 +157,17 @@ app:
|
||||
authentication-enabled: false # production이면 필수
|
||||
```
|
||||
|
||||
### RabbitMQ
|
||||
|
||||
```yaml
|
||||
app:
|
||||
messaging:
|
||||
brokers:
|
||||
rabbit-primary:
|
||||
type: rabbitmq
|
||||
stable: true
|
||||
production: false
|
||||
addresses: [rabbit-1:5671]
|
||||
publisher-confirms: true # stable에서 필수
|
||||
publisher-returns: true # stable에서 필수
|
||||
mandatory: true # stable에서 필수
|
||||
confirm-timeout: 5s
|
||||
auto-ack: false # 항상 금지
|
||||
prefetch: 16
|
||||
quorum-queues: true # durable work queue 필수
|
||||
tls-enabled: false
|
||||
authentication-enabled: false
|
||||
```
|
||||
|
||||
`production: true`인 브로커는 `tls-enabled`와 `authentication-enabled`가 모두 참이어야 하고,
|
||||
그렇지 않으면 `KafkaProfileValidator` / `RabbitProfileValidator`가 부팅을 거절한다. 위 예시가
|
||||
`production: 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
|
||||
@@ -197,6 +179,8 @@ app:
|
||||
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: []
|
||||
@@ -211,21 +195,37 @@ app:
|
||||
연결 시점에 해석하므로, 설정 덤프나 힙 덤프에서 나오는 것은 이름뿐이다. producer와 consumer는
|
||||
서로 다른 `credential-id`를 써야 하며, 같으면 부팅에 실패한다.
|
||||
|
||||
## Experimental / Optional
|
||||
`SASL_SCRAM`·`USERNAME_PASSWORD`의 사용자 이름은 `CredentialProvider.username(credentialId)`가
|
||||
준다. credential id를 사용자 이름으로 보내지 않는다. 비밀번호와 사용자 이름은 JAAS 문자열에 들어가지
|
||||
않고, 연결이 인증할 때마다 provider에서 읽힌다. 그래서 provider가 만료 시각을 주는 credential은
|
||||
재기동 없이 rotation된다(`security.md`).
|
||||
|
||||
기본값은 전부 `false`다.
|
||||
`MUTUAL_TLS`는 클라이언트 인증서를 key store로 제출한다. `credential-id`는 key store 비밀번호를
|
||||
가리킨다.
|
||||
|
||||
```yaml
|
||||
app:
|
||||
messaging:
|
||||
experimental:
|
||||
kafka-share: false
|
||||
pulsar: false
|
||||
nats: false
|
||||
bridge:
|
||||
spring-cloud-stream: false
|
||||
```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.<broker>`가 없을 때, 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
|
||||
|
||||
@@ -27,8 +27,9 @@
|
||||
`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: 기존 `OutboxPublicationAuthority` fence를 재사용해 writer/relay가
|
||||
동시에 ACTIVE가 되지 않도록. **dual write/publish는 금지** — 한 business fact가 두 durable store와
|
||||
- 단일 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.
|
||||
|
||||
@@ -17,24 +17,22 @@ 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. 기본 비활성
|
||||
|
||||
```yaml
|
||||
messaging.experimental.kafka-share: false
|
||||
messaging.experimental.pulsar: false
|
||||
messaging.experimental.nats: false
|
||||
```
|
||||
|
||||
새 Experimental 어댑터는 자기 활성화 플래그를 가지고 기본값은 `false`다.
|
||||
활성화하지 않으면 validator가 `MessagingCapabilityUnavailableException`을 던진다.
|
||||
Contract Suite가 아직 증명 중인 어댑터가 누군가의 기본 설정 때문에 load-bearing이 되어서는 안 된다.
|
||||
|
||||
### 2. Stable 모듈이 Experimental 모듈에 의존하지 않는다
|
||||
|
||||
Gradle 의존 그래프로 강제된다. `messaging-spring-boot-starter`의 `allowed_dependencies`에
|
||||
`messaging-kafka-share-experimental`, `messaging-pulsar-experimental`,
|
||||
`messaging-nats-experimental`, `messaging-spring-cloud-stream-bridge`가 **없다**.
|
||||
Gradle 의존 그래프로 강제된다. Experimental leaf는 `messaging-spring-boot-starter`의
|
||||
`allowed_dependencies`에 넣지 않는다.
|
||||
|
||||
`verifyCleanArchitectureDependencies`가 위반을 빌드 실패로 만든다.
|
||||
|
||||
@@ -45,45 +43,8 @@ Experimental 어댑터는 브로커의 차이를 `MessagingCapabilities`로 표
|
||||
|
||||
### 4. 없는 기능을 광고하지 않는다
|
||||
|
||||
| 어댑터 | 광고하지 않는 것 | 이유 |
|
||||
|---|---|---|
|
||||
| Kafka Share Group | orderedStream, keyedOrdering, replay, brokerTransaction | 경쟁 소비자 + 개별 ack는 partition 순서를 유지할 수 없다 |
|
||||
| Pulsar | brokerTransaction | Pulsar에 있지만 플랫폼 Contract Suite로 증명되지 않았다 |
|
||||
| Pulsar (Shared) | keyedOrdering | round-robin 분배 |
|
||||
| NATS JetStream | nativeDeadLetter | delivery limit 초과 시 terminate할 뿐 라우팅하지 않는다 |
|
||||
| NATS JetStream | keyedOrdering | subject 기반 모델에 per-key 순서가 없다 |
|
||||
|
||||
`false`인 capability를 요구하는 profile은 startup에서 실패한다.
|
||||
조용히 약화되지 않는다.
|
||||
|
||||
### 5. 명시적 거부
|
||||
|
||||
| 조합 | 결과 |
|
||||
|---|---|
|
||||
| Kafka Share Group + ordering != NONE | 거부 |
|
||||
| Kafka Share Group + pause/resume | `MessagingCapabilityUnavailableException` |
|
||||
| Pulsar Shared + ordering=KEY | 거부 (Key_Shared 필요) |
|
||||
| Pulsar + ordering=DESTINATION | 거부 |
|
||||
| NATS Core + AT_LEAST_ONCE | 거부 (JetStream 필요) |
|
||||
| NATS ordered consumer + 경쟁 워커 > 1 | 거부 |
|
||||
| NATS + ordering=KEY | 거부 |
|
||||
|
||||
## Spring Cloud Stream bridge
|
||||
|
||||
Experimental이 아니라 **Optional**이다. 위험이 다르다.
|
||||
|
||||
Stream은 자체 binder 설정을 소유하므로, binding이 destination profile이 모르는
|
||||
serializer·error handling·acknowledgement mode를 조용히 획득할 수 있다.
|
||||
|
||||
따라서 브리지는 **플랫폼 보장에 의존하지 않는 destination에만** 허용한다.
|
||||
|
||||
```text
|
||||
ordering scope 선언 → 거부
|
||||
retry policy 선언 → 거부
|
||||
dead letter 선언 → 거부
|
||||
```
|
||||
|
||||
이 셋 중 하나라도 필요하면 native adapter를 쓴다. 거기서만 실제로 강제되기 때문이다.
|
||||
Contract Suite로 증명하지 않은 capability는 `MessagingCapabilities`에서 `false`로 둔다.
|
||||
`false`인 capability를 요구하는 profile은 startup에서 실패한다. 조용히 약화되지 않는다.
|
||||
|
||||
## 승격 조건
|
||||
|
||||
|
||||
@@ -3,8 +3,7 @@
|
||||
## 배포 전 체크
|
||||
|
||||
```bash
|
||||
./gradlew verifyCleanArchitectureDependencies --console=plain
|
||||
./gradlew verifyRuntimeModuleMembership --console=plain
|
||||
./gradlew architectureCheck --console=plain
|
||||
./gradlew checkstyleMain --console=plain
|
||||
```
|
||||
|
||||
|
||||
@@ -21,8 +21,8 @@ Flyway version `1000..1999`를 예약해서 애플리케이션의 일반적인
|
||||
classpath:db/migration/messaging
|
||||
```
|
||||
|
||||
현재 순서는 `V1001..V1004`(outbox/admin)와 `V1101`(inbox)이다. starter 테스트가 두 JDBC
|
||||
모듈을 실제 combined classpath로 올려 version 중복과 예약 대역 이탈을 검사한다. 개별 DDL의
|
||||
현재 순서는 `V1001..V1005`(outbox/admin)와 `V1101`(inbox)이고, 모두
|
||||
`messaging-reliability-jdbc-postgresql`에 있다. starter 테스트가 그 모듈을 실제 combined classpath로 올려 version 중복과 예약 대역 이탈을 검사한다. 개별 DDL의
|
||||
의미와 전환 순서는 [migration-guide.md](migration-guide.md)를 따른다.
|
||||
|
||||
## Outbox
|
||||
@@ -39,13 +39,18 @@ COMMIT;
|
||||
### relay
|
||||
|
||||
```text
|
||||
leaseBatch(100, 30s) -- lease로 다중 relay 인스턴스 안전
|
||||
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를 발급하면 "전달됐을 수도 있는 메시지"가 "확실히 두 번째인 메시지"가 되어
|
||||
@@ -61,8 +66,16 @@ 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는 회수되지 않는다.
|
||||
@@ -95,6 +108,24 @@ transactions.inTransaction(() -> {
|
||||
|
||||
별도 transaction으로 예약하면 Inbox가 닫으려던 바로 그 창이 다시 열린다.
|
||||
|
||||
### 소비와 연결 (소유자 결정 10)
|
||||
|
||||
consume 계약은 `MessageHandler<T>` 하나다. 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)가 확인한다.
|
||||
|
||||
### 복합 키
|
||||
|
||||
`PRIMARY KEY (message_id, consumer_id)`.
|
||||
@@ -107,13 +138,14 @@ message_id만으로 중복 제거하면 같은 event를 소비하는 두 번째
|
||||
broker의 최대 redelivery window보다 **길어야** 한다.
|
||||
row를 먼저 지우면 늦게 도착한 redelivery가 두 번 처리된다.
|
||||
|
||||
## Debezium CDC 대안
|
||||
outbox·inbox cleanup job은 한 번에 최대 1,000행씩 지우고, 지운 수가 1,000보다 적으면 멈춘다.
|
||||
repository port에는 개수 제한 없는 삭제 메서드가 없다.
|
||||
|
||||
polling relay 대신 WAL을 읽는다. polling interval과 lease 경합이 사라지지만
|
||||
인프라와 그 자체의 실패 모드가 추가된다.
|
||||
## CDC 대안
|
||||
|
||||
wire contract는 동일하다. `DebeziumOutboxEventRouter`가 polling relay와 같은 reserved header를
|
||||
방출하므로 consumer는 어느 쪽이 발행했는지 구분할 수 없고, 전환은 배포 결정일 뿐 계약 변경이 아니다.
|
||||
relay는 polling 하나뿐이다. Debezium Event Router 매핑(`DebeziumOutboxEventRouter` 등)은 조립하는
|
||||
곳이 없어 2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표). `messaging_outbox`의
|
||||
`routing_key` 컬럼은 남아 있으므로 CDC를 다시 들일 때 그 컬럼을 message key로 쓴다.
|
||||
|
||||
## Claim Check
|
||||
|
||||
|
||||
@@ -49,6 +49,15 @@ full jitter는 `[0, delay]` 균등 분포다. jitter가 없으면 같은 초에
|
||||
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**로 구현한다.
|
||||
|
||||
@@ -36,17 +36,30 @@ 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가 멈춰 있다.
|
||||
|
||||
rotation은 세대 교체다. `DefaultMessagingRuntimeRegistry.install()`이 새 세대를 원자적으로
|
||||
게시하고, 이전 세대는 마지막 lease가 닫힐 때까지 열려 있다가 닫힌다.
|
||||
진행 중인 publish는 시작한 연결에서 confirm을 받는다.
|
||||
Kafka SASL credential은 producer를 다시 만들지 않고 바뀐다. JAAS 설정에는 login module 이름만
|
||||
있고, `KafkaCredentialCallbackHandler`가 연결이 인증할 때마다 `CredentialRuntimeRegistry`에서
|
||||
사용자 이름과 비밀번호를 읽는다. registry는 provider가 준 만료 시각의 rotation lead(기본 30분)
|
||||
안으로 들어오면 새로 가져오므로, 새 연결과 재인증(broker `connections.max.reauth.ms`)이 새 값을
|
||||
쓴다. 만료 시각을 주지 않는 provider의 credential은 캐시된 값을 계속 쓴다.
|
||||
|
||||
drain deadline이 이 대기를 제한한다. 없으면 lease 하나가 새면 폐기된 credential이
|
||||
무기한 열려 있고, rotation이 보안상 무의미해진다.
|
||||
key store·trust store 비밀번호는 예외다. Kafka가 SSL context를 만들 때 한 번 읽으므로 바꾸려면
|
||||
producer를 다시 만들어야 한다(재기동).
|
||||
|
||||
transport 세대 교체(`DefaultMessagingRuntimeRegistry.install()`)는 transport 자체를 바꿀 때 쓴다.
|
||||
새 세대를 원자적으로 게시하고, 이전 세대는 마지막 lease가 닫힐 때까지 열려 있다가 닫힌다.
|
||||
drain deadline이 이 대기를 제한한다.
|
||||
|
||||
## Header
|
||||
|
||||
@@ -66,10 +79,13 @@ logical identity가 호출자 제어가 된다.
|
||||
|
||||
## ACL
|
||||
|
||||
`DestinationAccessValidator`가 broker ACL **이전에** 검사한다.
|
||||
publisher가 broker ACL **이전에** 검사한다(`PUBLISH_FORBIDDEN`).
|
||||
broker ACL 거부는 애플리케이션 컨텍스트가 없는 연결 수준 오류로 도착하므로
|
||||
"어느 모듈이 어디에 publish하려 했는가"가 조사 대상이 된다.
|
||||
|
||||
publish 가능한 destination은 선언된 destination이다. broker에 `app.messaging.security.<broker>`
|
||||
항목이 있으면 그중 `access.publishable`에 적힌 것만 남는다(빈 목록이면 publish 불가).
|
||||
|
||||
## 관측성 누출
|
||||
|
||||
`MessagingRedactor`는 denylist다.
|
||||
|
||||
@@ -4,10 +4,12 @@
|
||||
여기 없는 조합은 지원되지 않는다.
|
||||
|
||||
> **등급은 증거를 따른다.** `CompatibilityMatrix.Entry.hasLiveBrokerCertification()`은 선언된
|
||||
> boolean이 아니라 `CertifiedEvidence`가 가진 레인 증거에서 파생된다. RabbitMQ가 Stable에서 내려온
|
||||
> 이유가 이것이다 — 어댑터는 공유 contract 7개를 통과하고 `RabbitBrokerIT`가 실 컨테이너에서 정상
|
||||
> 경로를 돌리지만, 이 저장소의 Stable 기준인 **장애 시나리오 증거**가 하나도 없다. 레인이 생겨
|
||||
> 증거를 내면 등급은 코드 수정 없이 따라 올라간다.
|
||||
> 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이었다 — 표와
|
||||
@@ -15,8 +17,10 @@
|
||||
> `BrokerFailureMatrix.shipped()` 하드코딩이 아니라 레인이 낸 증거(`BrokerCertificationEvidence`)에서
|
||||
> 나온다. 증거가 없는 조합은 `NOT_COVERED`다 (MSG-014).
|
||||
|
||||
> **모듈 이름과 런타임 편입.** `messaging-outbox-jdbc-postgresql` / `messaging-inbox-jdbc-postgresql`은
|
||||
> 이전에 `-jpa`로 불렸다. 구현은 Spring JDBC이고 SQL은 PostgreSQL 전용(`?::jsonb`,
|
||||
> **모듈 이름과 런타임 편입.** 관계형 신뢰성 구현은 `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).
|
||||
>
|
||||
@@ -29,10 +33,7 @@
|
||||
|
||||
| 브로커 | 등급 | 인증 기준 | Stable 기능 | 제한 |
|
||||
|---|---|---|---|---|
|
||||
| Kafka | Stable | 4.1.x | producer idempotence, consumer group, batch, pause/resume, replay, transaction capability | Share Group은 Experimental |
|
||||
| RabbitMQ | Experimental | 4.3.x | exchange/routing, publisher confirm, mandatory return, manual ACK, quorum queue, retry queue, DLQ | **현재 starter에서 선택 불가** — production `RabbitChannelPublisher`/transport bridge가 없어 `app.messaging.broker=rabbit`은 startup에서 거부된다. 장애 시나리오 증거도 아직 없음 |
|
||||
| Pulsar | Experimental | 4.0 LTS + 4.2 | typed publish/consume, Shared, Key_Shared, schema | transaction 미승격, 기본 비활성 |
|
||||
| NATS JetStream | Experimental | 2.14.x | stream, durable consumer, explicit ACK, dedupe, replay | native DLQ 없음(플랫폼이 대행), 기본 비활성 |
|
||||
| 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 매트릭스
|
||||
@@ -40,27 +41,20 @@
|
||||
`MessagingCapabilities`가 런타임에 선언하는 값이다. `false`인 기능을 요구하는 destination profile은
|
||||
**startup에서 실패**하며, 조용히 약화되지 않는다.
|
||||
|
||||
| Capability | Kafka | Kafka Share | RabbitMQ | Pulsar | NATS JS |
|
||||
|---|---|---|---|---|---|
|
||||
| brokerAcknowledgement | O | O | O | O | O |
|
||||
| replicationOrPersistenceEvidence | O | O | O | O | O |
|
||||
| perMessageSettlement | O | O | O | O | O |
|
||||
| batchSettlement | O | X | X | O | O |
|
||||
| orderedStream | O | **X** | X | X | O |
|
||||
| keyedOrdering | O | **X** | X | Key_Shared만 | X |
|
||||
| replay | O | X | X | O | O |
|
||||
| delayedDelivery | X | X | retry queue로 대행 | O | X |
|
||||
| brokerTransaction | O | X | X | 미승격 | X |
|
||||
| deduplicatedPublish | O | X | X | X | O |
|
||||
| nativeDeadLetter | X | X | O | O | **X** |
|
||||
| topologyManagement | O | X | O | O | O |
|
||||
|
||||
Kafka Share Group이 ordering 전부 `X`인 것은 설계 결정이다. share group은 개별 record를
|
||||
경쟁 소비자에게 나눠주고 개별 ack하므로 partition 순서를 유지할 수 없다. ordered destination을
|
||||
share group에 설정하면 `KafkaShareProfileValidator`가 거부한다.
|
||||
|
||||
NATS JetStream의 `nativeDeadLetter=X`도 마찬가지다. JetStream은 delivery limit 초과 시 메시지를
|
||||
**terminate**할 뿐 어디로도 라우팅하지 않으므로, 플랫폼이 DLQ publish를 직접 수행한다.
|
||||
| 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 |
|
||||
|
||||
## 기능 등급
|
||||
|
||||
@@ -73,8 +67,6 @@ NATS JetStream의 `nativeDeadLetter=X`도 마찬가지다. JetStream은 delivery
|
||||
| Batch / Manual settlement / Pause·Resume / Delayed / Replay 요청 | M2 |
|
||||
| Broker transaction / partition / routing / subscription | M3 |
|
||||
| Replay 실행 / Redrive / offset reset / purge / delete | M4 Admin |
|
||||
| Kafka Share Group, Pulsar, NATS | Experimental |
|
||||
| Spring Cloud Stream bridge | Optional |
|
||||
|
||||
## 무엇이 "Stable"을 증명하는가
|
||||
|
||||
@@ -82,7 +74,7 @@ Stable 등급은 두 가지를 **모두** 통과해야 한다. `CompatibilityMat
|
||||
|
||||
### 1. 공유 Contract Suite (`MessagingAdapterContract`, 7개)
|
||||
|
||||
Kafka와 RabbitMQ가 동일한 7개 테스트를 변경 없이 통과한다. 결정적 하네스를 쓰므로
|
||||
Kafka가 7개 테스트를 변경 없이 통과한다. 결정적 하네스를 쓰므로
|
||||
확인 유실·settlement 유실 같은 장애를 요청 시점에 재현할 수 있다.
|
||||
|
||||
### 2. 실 브로커 인증 (Testcontainers)
|
||||
@@ -92,7 +84,6 @@ Kafka와 RabbitMQ가 동일한 7개 테스트를 변경 없이 통과한다. 결
|
||||
| `KafkaBrokerIT` | `acks=all`이 실제 replication 증거를 만든다 / 잘못된 토픽은 `REJECTED` / 발행-소비 왕복에서 identity 보존 및 contiguous commit |
|
||||
| `KafkaAmbiguityChaosIT` | 브로커를 `docker pause`로 멈춘 상태의 publish가 **`AMBIGUOUS`** 로 보고된다 (broker acceptance 없음, confirmation level `NONE`, 비-retryable) |
|
||||
| `KafkaBrokerCertificationIT` | 인증 레인. Toxiproxy를 broker 앞에 두고 connection cut / confirm 유실 / 지연 / settlement 유실을 각각 주입하고, 통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을 manifest에 쓴다 |
|
||||
| `RabbitBrokerIT` | exchange가 confirm했는데 어떤 큐에도 바인딩되지 않은 publish가 **`REJECTED` + `UNROUTABLE`** 로 보고된다 |
|
||||
| `OutboxPostgresIT` | 롤백된 트랜잭션은 발행 가능한 행을 남기지 않는다 / `SKIP LOCKED` lease가 두 relay를 분리한다 / ambiguous 행이 같은 `messageId`로 재클레임된다 |
|
||||
| `InboxPostgresIT` | 재전달이 side effect를 두 번 적용하지 않는다 / 롤백은 예약도 되돌린다 |
|
||||
|
||||
@@ -137,7 +128,7 @@ delivery timeout으로 나타난다. 이를 `REJECTED`로 보고하는 것은
|
||||
|
||||
1. **Outbox `IN_FLIGHT` 고아 행** — lease 쿼리가 `PENDING`/`AMBIGUOUS`만 클레임 대상으로 봐서,
|
||||
publish 도중 죽은 relay가 남긴 행이 lease 만료 후에도 영영 회수되지 않았다.
|
||||
2. **Rabbit confirm 경합** — transport가 publish *후에* confirm을 등록해서, 연결 스레드에서
|
||||
2. **Rabbit confirm 경합**(2026-09-25에 삭제된 Rabbit transport) — transport가 publish *후에* confirm을 등록해서, 연결 스레드에서
|
||||
confirm이 먼저 도착하면 유실되고 호출자가 무한 대기했다.
|
||||
|
||||
둘 다 인메모리 double이 실제보다 관대해서 통과하고 있었다.
|
||||
@@ -154,21 +145,10 @@ delivery timeout으로 나타난다. 이를 `REJECTED`로 보고하는 것은
|
||||
- DLQ publish 확인 전 source ACK
|
||||
|
||||
|
||||
## R1 compiler status
|
||||
|
||||
`adapter:outbound:messaging`의 contract/catalog/envelope compiler 군은 현재 **의도적으로 미배선**이다.
|
||||
`DISABLED` + 빈 catalog/binding이 zero-resource 상태이며, 이 R1 compiler를 legacy
|
||||
`MessagingConfig`에 연결해 Kafka ACK, wire compatibility, `ACTIVE_READY`, R2 qualification을
|
||||
주장하지 않는다. 코드는 다음 세대 계약을 보존하지만 현재 채택 경로가 아니며, 실제 활성화는 별도 R2
|
||||
composition/cutover에서 명시적으로 이뤄져야 한다.
|
||||
|
||||
|
||||
### Optional mapping / bridge utilities
|
||||
### 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-spring-cloud-stream-bridge`는 현재 `ChannelSend` seam과 publish-evidence 판단을 제공하는
|
||||
framework-neutral bridge contract다. Spring Cloud Stream `StreamBridge` dependency/auto-configuration은
|
||||
제공하지 않으므로 shipped Spring Cloud Stream integration으로 분류하지 않는다.
|
||||
- `messaging-claim-check`도 starter에 편입되지 않는 opt-in utility다.
|
||||
|
||||
+36
-31
@@ -14,25 +14,28 @@ leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이
|
||||
|
||||
| Family | 역할 | 허용 framework |
|
||||
| --- | --- | --- |
|
||||
| `*-api` (`core-api`, `schema-api`, `policy`, `reliability-api`, `admin-api`, `transport-spi`) | 값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging 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-runtime` | framework-free 실행 로직 | Micrometer는 `observability`에서만. 나머지는 stdlib |
|
||||
| `kafka`, `rabbit`, `pulsar-experimental`, `nats-experimental`, `kafka-share-experimental` | broker adapter | 해당 broker client. Spring은 `rabbit`의 `spring-rabbit`처럼 client가 곧 Spring인 경우만 |
|
||||
| `outbox-jdbc-postgresql`, `inbox-jdbc-postgresql` | 관계형 신뢰성 adapter | Spring JDBC / Spring TX. **JPA 아님** — 이름이 곧 계약이다 |
|
||||
| `spring-boot-starter`, `spring-cloud-stream-bridge` | 조립 경계 | Spring Boot autoconfigure. 여기서만 |
|
||||
| `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가 의존하지 않는다 |
|
||||
|
||||
`outbox`/`inbox` leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring JDBC이고 SQL은
|
||||
`?::jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL 전용이다.
|
||||
`jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다. vendor
|
||||
중립 계약은 `messaging-reliability-api`에 있다.
|
||||
신뢰성 기능은 세 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도 같은 모양이었다(S7-#5b). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring
|
||||
JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL
|
||||
전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다.
|
||||
|
||||
## Public surface 정책
|
||||
|
||||
- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이
|
||||
숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다.
|
||||
(`kafka-clients`, `spring-rabbit`, `cloudevents-api`, `micrometer-core`, `avro`,
|
||||
`protobuf-java`, `reactor-core`가 이 규칙으로 `api`다.)
|
||||
(`kafka-clients`, `cloudevents-api`, `micrometer-core`, `avro`,
|
||||
`protobuf-java`가 이 규칙으로 `api`다.)
|
||||
- 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을
|
||||
`implementation`으로 내린 것이, JSON codec이 `ObjectMapper`를 private으로만 쓰고 Jackson을
|
||||
`implementation`으로 둔 것이 그 예다.
|
||||
@@ -45,16 +48,19 @@ leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이
|
||||
|
||||
## Application runtime에 포함되는 기준
|
||||
|
||||
Messaging family는 기본 application이 `messaging-spring-boot-starter`를 dependency로 가지므로 그
|
||||
transitive project graph가 runtime에 포함된다. 이 사실의 SSOT는 Gradle `runtimeClasspath`이며 registry에
|
||||
동일한 membership 목록을 복제하지 않는다. `app.messaging.enabled=false`가 기본값이고 master switch가
|
||||
activation을 결정한다.
|
||||
기본 조립에는 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`로만 끈다.
|
||||
|
||||
experimental transport, 일부 codec/bridge/testkit처럼 starter graph에 들어오지 않는 leaf는 build-only다.
|
||||
일부 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에 도달하는 경로 (MSG-015, canonical bridge 구현 / legacy cutover 잔존)
|
||||
## application이 이 family에 도달하는 경로 (MSG-015, cutover 완료)
|
||||
|
||||
리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한
|
||||
`application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다.
|
||||
@@ -66,25 +72,24 @@ qualification/support 상태를 함께 변경한다.
|
||||
|
||||
bridge는 exact canonical envelope bytes를 다시 serialize하지 않고, destination/access/admission/runtime
|
||||
lease/transport/outcome normalization/observation은 platform 중앙 publish path를 그대로 탄다. bridge
|
||||
package는 `messaging-core-api`와 `messaging-schema-api`만 보며 concrete runtime/transport/Kafka 타입을
|
||||
package는 `messaging-core-api`만 보며 concrete runtime/transport/Kafka 타입을
|
||||
직접 보지 않는다.
|
||||
|
||||
다만 **MSG-015의 전체 cutover가 끝난 것은 아니다.** legacy `OutboxEvent`와 realtime publisher는
|
||||
schema/order/tenant 등 canonical metadata가 부족해 아직 `MessageBroker → KafkaSender` R0 경로를
|
||||
사용한다. 그 metadata를 추측해 platform envelope를 만드는 것은 금지한다. 따라서 legacy outbox
|
||||
storage/relay migration을 별도 change set으로 완료한 뒤에만 R0 seam을 제거한다.
|
||||
**MSG-015 cutover는 끝났다(2026-09-28, 소유자 결정 7).** 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를 발명하지 않는다.
|
||||
만들지 않으며 `spring.application.name`/host/pod 이름에서 identity를 발명하지 않는다. bridge가 없으면
|
||||
relay가 발행할 곳이 없으므로 messaging 모듈이 켜진 상태에서는 기동이 거부된다.
|
||||
|
||||
`ca-skeleton.outbox.canonical-transport-enabled=true`는 bridge 존재만으로 충분하지 않다. Stable
|
||||
composition은 애플리케이션 계약 catalog/schema source를 임의로 만들지 않으므로 adopter가
|
||||
`IntegrationEventEncoderPort`를 명시적으로 제공해야 한다. 저장소의 후보 구현은
|
||||
`JsonSchemaIntegrationEventEncoder`이지만 이를 사용하려면 compiled contract descriptor,
|
||||
`LocalJsonSchemaRegistry`, payload/envelope limits와 key material에 해당하는 application-owned 입력을
|
||||
같이 조립해야 한다. `OutboxCanonicalTransportRequirementValidator`는 publisher 또는 encoder 중 하나라도
|
||||
없으면 startup을 거부한다. 즉 canonical flag가 켜졌는데 정본 encoder가 없는 상태로 성공 기동하는
|
||||
경로는 없다.
|
||||
`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 승격에 필요한 증거
|
||||
|
||||
|
||||
@@ -1,8 +0,0 @@
|
||||
plugins {
|
||||
id 'ca.platform-module'
|
||||
}
|
||||
|
||||
dependencies {
|
||||
api project(':messaging:messaging-core-api')
|
||||
api project(':messaging:messaging-policy')
|
||||
}
|
||||
@@ -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.47.0=checkstyle
|
||||
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:guava:33.6.0-jre=checkstyle
|
||||
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
|
||||
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
|
||||
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
|
||||
commons-beanutils:commons-beanutils:1.11.0=checkstyle
|
||||
commons-collections:commons-collections:3.2.2=checkstyle
|
||||
commons-io:commons-io:2.21.0=spotbugs
|
||||
info.picocli:picocli:4.7.7=checkstyle
|
||||
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
|
||||
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
|
||||
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
|
||||
jaxen:jaxen:2.0.6=spotbugs
|
||||
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
|
||||
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
|
||||
org.antlr:antlr4-runtime:4.13.2=checkstyle
|
||||
org.apache.bcel:bcel:6.12.0=spotbugs
|
||||
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
|
||||
org.apache.commons:commons-text:1.15.0=spotbugs
|
||||
org.apache.commons:commons-text:1.3=checkstyle
|
||||
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
|
||||
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
|
||||
org.apache.logging.log4j:log4j-api:2.25.5=spotbugs
|
||||
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
|
||||
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
|
||||
org.apache.xbean:xbean-reflect:3.7=checkstyle
|
||||
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
|
||||
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
|
||||
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
|
||||
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
|
||||
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
|
||||
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
|
||||
org.dom4j:dom4j:2.2.0=spotbugs
|
||||
org.javassist:javassist:3.28.0-GA=checkstyle
|
||||
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
|
||||
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
|
||||
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit:junit-bom:6.1.0=spotbugs
|
||||
org.mockito:mockito-core:5.20.0=mockitoAgent
|
||||
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
|
||||
org.ow2.asm:asm-analysis:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-commons:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-tree:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-util:9.10.1=spotbugs
|
||||
org.ow2.asm:asm:9.10.1=spotbugs
|
||||
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
|
||||
org.reflections:reflections:0.10.2=checkstyle
|
||||
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.18=checkstyle
|
||||
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
|
||||
empty=compileClasspath,runtimeClasspath
|
||||
@@ -1,12 +0,0 @@
|
||||
plugins {
|
||||
id 'ca.platform-module'
|
||||
}
|
||||
|
||||
dependencies {
|
||||
api project(':messaging:messaging-core-api')
|
||||
api project(':messaging:messaging-policy')
|
||||
api project(':messaging:messaging-admin-api')
|
||||
api project(':messaging:messaging-transport-spi')
|
||||
api project(':messaging:messaging-security')
|
||||
api project(':messaging:messaging-observability')
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
plugins {
|
||||
id 'ca.platform-module'
|
||||
}
|
||||
|
||||
// The admin plane: its contract (package `admin`) and the stdlib services that execute it
|
||||
// (package `admin.runtime`). They were two leaves, and every consumer of the runtime took the
|
||||
// contract too, so the split added a registry entry without separating anything (S7-#12).
|
||||
dependencies {
|
||||
api project(':messaging:messaging-core-api')
|
||||
|
||||
// ReplayService records a MessagingAuditEvent internally; no public signature names it, so
|
||||
// Micrometer does not reach the journal adapters that implement the contract.
|
||||
implementation project(':messaging:messaging-observability')
|
||||
}
|
||||
@@ -4,7 +4,6 @@ plugins {
|
||||
|
||||
dependencies {
|
||||
api project(':messaging:messaging-core-api')
|
||||
api project(':messaging:messaging-schema-api')
|
||||
|
||||
// api, because CloudEventMapper's public signatures return io.cloudevents.CloudEvent.
|
||||
//
|
||||
|
||||
-46
@@ -1,46 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.delivery;
|
||||
|
||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Batch-wide facts about one delivered batch.
|
||||
*
|
||||
* <p>{@code orderingUnit} is what makes a batch safe to hand to an ordered destination. A batch
|
||||
* drawn from two partitions cannot be settled or retried as a unit without reordering one of them,
|
||||
* so an ordered destination requires the batch to name exactly one ordering unit and the runtime
|
||||
* rejects a batch that spans more.
|
||||
*
|
||||
* @param destination the logical destination
|
||||
* @param size the number of deliveries in the batch
|
||||
* @param orderingUnit the single partition or queue the batch was drawn from, when it has one
|
||||
* @param settlableAsBatch whether the broker can settle the whole batch in one operation
|
||||
* @param receivedAt when the consumer assembled the batch
|
||||
*/
|
||||
public record BatchDeliveryMetadata(
|
||||
DestinationName destination,
|
||||
int size,
|
||||
Optional<String> orderingUnit,
|
||||
boolean settlableAsBatch,
|
||||
Instant receivedAt) {
|
||||
|
||||
public BatchDeliveryMetadata {
|
||||
Objects.requireNonNull(destination, "destination must not be null");
|
||||
Objects.requireNonNull(orderingUnit, "orderingUnit must not be null");
|
||||
Objects.requireNonNull(receivedAt, "receivedAt must not be null");
|
||||
if (size < 1) {
|
||||
throw new IllegalArgumentException("a delivered batch has at least one delivery");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether this batch may be handed to a destination with strict ordering.
|
||||
*
|
||||
* @return true when the batch came from exactly one ordering unit
|
||||
*/
|
||||
public boolean isSafeForOrderedDestination() {
|
||||
return orderingUnit.isPresent();
|
||||
}
|
||||
}
|
||||
-29
@@ -1,29 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.delivery;
|
||||
|
||||
import java.util.List;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* A batch of decoded messages handed to a batch handler.
|
||||
*
|
||||
* @param <T> the payload type
|
||||
* @param deliveries the individual deliveries, in broker order
|
||||
* @param metadata batch-wide facts
|
||||
*/
|
||||
public record BatchMessageDelivery<T>(
|
||||
List<MessageDelivery<T>> deliveries, BatchDeliveryMetadata metadata) {
|
||||
|
||||
public BatchMessageDelivery {
|
||||
Objects.requireNonNull(deliveries, "deliveries must not be null");
|
||||
Objects.requireNonNull(metadata, "metadata must not be null");
|
||||
deliveries = List.copyOf(deliveries);
|
||||
if (deliveries.isEmpty()) {
|
||||
throw new IllegalArgumentException("a delivered batch is never empty");
|
||||
}
|
||||
if (deliveries.size() != metadata.size()) {
|
||||
throw new IllegalArgumentException(
|
||||
"metadata size %d does not match %d deliveries"
|
||||
.formatted(metadata.size(), deliveries.size()));
|
||||
}
|
||||
}
|
||||
}
|
||||
-24
@@ -1,24 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.delivery;
|
||||
|
||||
import java.util.concurrent.CompletionStage;
|
||||
|
||||
/**
|
||||
* The M2 batch consume entry point.
|
||||
*
|
||||
* <p>The handler returns one {@link HandleResult} for the whole batch. On a broker that settles
|
||||
* batches atomically the runtime applies that result once; on a broker that settles per message it
|
||||
* applies the same result to each delivery. Either way the handler is not asked to reason about
|
||||
* which settlement mode it is running under.
|
||||
*
|
||||
* @param <T> the payload type
|
||||
*/
|
||||
public interface BatchMessageHandler<T> {
|
||||
|
||||
/**
|
||||
* Handles one delivered batch.
|
||||
*
|
||||
* @param batch the batch to handle
|
||||
* @return a stage completing with the outcome for the whole batch
|
||||
*/
|
||||
CompletionStage<HandleResult> handle(BatchMessageDelivery<T> batch);
|
||||
}
|
||||
+18
-3
@@ -1,18 +1,33 @@
|
||||
package dev.caskeleton.messaging.api.delivery;
|
||||
|
||||
import dev.caskeleton.messaging.api.destination.MessageDestination;
|
||||
import java.util.concurrent.CompletionStage;
|
||||
|
||||
/**
|
||||
* The M1 typed handler implemented by ordinary business code.
|
||||
* The one consume contract, implemented by ordinary business code.
|
||||
*
|
||||
* <p>Handlers state an outcome and never touch broker acknowledgement APIs. Duplicate delivery is a
|
||||
* normal condition, not an error: implementations are expected to be idempotent, or to sit behind
|
||||
* the Inbox.
|
||||
* normal condition, not an error: implementations are expected to be idempotent, or to consume a
|
||||
* destination whose profile declares {@code INBOX_TRANSACTIONAL}, where the platform runs the
|
||||
* handler inside the inbox reservation's transaction.
|
||||
*
|
||||
* <p>Registering an implementation as a bean is what turns consumption on: the broker starter opens
|
||||
* a consumer for every destination at least one handler names. There is no second, batch or manual
|
||||
* settlement contract; the platform settles, after the handler has answered.
|
||||
*
|
||||
* @param <T> the payload type
|
||||
*/
|
||||
public interface MessageHandler<T> {
|
||||
|
||||
/**
|
||||
* The destination, message type and payload type this handler consumes.
|
||||
*
|
||||
* <p>A destination may carry several message types; each type has at most one handler.
|
||||
*
|
||||
* @return what this handler consumes
|
||||
*/
|
||||
MessageDestination<T> destination();
|
||||
|
||||
/**
|
||||
* Handles one delivery.
|
||||
*
|
||||
|
||||
-33
@@ -1,33 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.delivery;
|
||||
|
||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||
import java.util.concurrent.CompletionStage;
|
||||
|
||||
/**
|
||||
* The M2 consumer flow-control entry point.
|
||||
*
|
||||
* <p>Pausing stops new deliveries; it does not abandon the ones already in flight. A paused
|
||||
* consumer stays a member of its group and keeps its assignment, which is the point: leaving the
|
||||
* group to stop consuming would trigger a rebalance and hand the work to another instance that is
|
||||
* just as overloaded.
|
||||
*/
|
||||
public interface PauseResumeController {
|
||||
|
||||
/**
|
||||
* Stops new deliveries for a destination scope.
|
||||
*
|
||||
* @param destination the logical destination
|
||||
* @param scope the partition, queue, or {@code "*"} for every assigned unit
|
||||
* @return a stage completing once no further deliveries will be dispatched
|
||||
*/
|
||||
CompletionStage<Void> pause(DestinationName destination, String scope);
|
||||
|
||||
/**
|
||||
* Resumes deliveries for a destination scope.
|
||||
*
|
||||
* @param destination the logical destination
|
||||
* @param scope the partition, queue, or {@code "*"} for every assigned unit
|
||||
* @return a stage completing once deliveries may flow again
|
||||
*/
|
||||
CompletionStage<Void> resume(DestinationName destination, String scope);
|
||||
}
|
||||
-11
@@ -1,11 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.delivery;
|
||||
|
||||
/** How duplicate processing is neutralised once a message has been delivered. */
|
||||
public enum ProcessingGuarantee {
|
||||
|
||||
/** The handler suppresses duplicate effects using the message id or a business key. */
|
||||
APPLICATION_IDEMPOTENT,
|
||||
|
||||
/** Atomicity holds only inside the transaction scope the broker itself defines. */
|
||||
BROKER_TRANSACTIONAL
|
||||
}
|
||||
-15
@@ -1,15 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.destination;
|
||||
|
||||
/** Resolves the capability snapshot for a logical destination. */
|
||||
public interface CapabilityRegistry {
|
||||
|
||||
/**
|
||||
* Returns the capabilities of a destination.
|
||||
*
|
||||
* @param destination the logical destination
|
||||
* @return the capability snapshot
|
||||
* @throws dev.caskeleton.messaging.api.error.MessagingConfigurationException when the destination
|
||||
* is not registered
|
||||
*/
|
||||
DestinationCapabilities capabilities(DestinationName destination);
|
||||
}
|
||||
+55
-27
@@ -1,5 +1,10 @@
|
||||
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.
|
||||
*
|
||||
@@ -8,32 +13,35 @@ package dev.caskeleton.messaging.api.destination;
|
||||
* capability exception — rather than quietly degrading, because a silently weakened guarantee is
|
||||
* indistinguishable from a working one until the incident.
|
||||
*
|
||||
* @param brokerAcknowledgement the adapter can prove the broker accepted a publish
|
||||
* @param replicationOrPersistenceEvidence the adapter can prove replication or persistence
|
||||
* @param perMessageSettlement individual messages can be settled
|
||||
* @param batchSettlement batches can be settled as a unit
|
||||
* @param orderedStream the destination preserves order inside an ordering unit
|
||||
* @param keyedOrdering order is preserved per key
|
||||
* @param replay historical messages can be re-read
|
||||
* @param delayedDelivery delivery can be scheduled for a future instant
|
||||
* @param brokerTransaction the broker offers a transaction scope
|
||||
* @param deduplicatedPublish the broker suppresses duplicate publishes of a stable id
|
||||
* @param nativeDeadLetter the broker provides dead lettering itself
|
||||
* @param topologyManagement topology can be inspected or created through the adapter
|
||||
* <p>A set of named capabilities rather than a row of positional booleans. The record used to take
|
||||
* twelve booleans in a fixed order, and an adapter declared itself with {@code new
|
||||
* MessagingCapabilities(true, true, …, false, true)} — a line where swapping two arguments changes
|
||||
* a guarantee and still compiles. Only the capabilities the platform reads are named: a flag
|
||||
* nothing consults is a promise nobody checks.
|
||||
*
|
||||
* @param supported the capabilities the adapter can prove
|
||||
*/
|
||||
public record MessagingCapabilities(
|
||||
boolean brokerAcknowledgement,
|
||||
boolean replicationOrPersistenceEvidence,
|
||||
boolean perMessageSettlement,
|
||||
boolean batchSettlement,
|
||||
boolean orderedStream,
|
||||
boolean keyedOrdering,
|
||||
boolean replay,
|
||||
boolean delayedDelivery,
|
||||
boolean brokerTransaction,
|
||||
boolean deduplicatedPublish,
|
||||
boolean nativeDeadLetter,
|
||||
boolean topologyManagement) {
|
||||
public record MessagingCapabilities(Set<Capability> supported) {
|
||||
|
||||
/** One capability the platform consults before relying on it. */
|
||||
public enum Capability {
|
||||
|
||||
/** The destination preserves order inside an ordering unit; required by pause-and-retry. */
|
||||
ORDERED_STREAM,
|
||||
|
||||
/** Delivery can be scheduled for a future instant; required by broker-delayed retry. */
|
||||
DELAYED_DELIVERY,
|
||||
|
||||
/** The broker suppresses duplicate publishes of a stable id; required by publish dedup. */
|
||||
DEDUPLICATED_PUBLISH
|
||||
}
|
||||
|
||||
public MessagingCapabilities {
|
||||
Objects.requireNonNull(supported, "supported must not be null");
|
||||
supported =
|
||||
Collections.unmodifiableSet(
|
||||
supported.isEmpty() ? EnumSet.noneOf(Capability.class) : EnumSet.copyOf(supported));
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a capability set with nothing enabled.
|
||||
@@ -41,7 +49,27 @@ public record MessagingCapabilities(
|
||||
* @return the empty capability set
|
||||
*/
|
||||
public static MessagingCapabilities none() {
|
||||
return new MessagingCapabilities(
|
||||
false, false, false, false, false, false, false, false, false, false, false, false);
|
||||
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"));
|
||||
}
|
||||
}
|
||||
|
||||
-49
@@ -1,49 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/** Broker authentication failed. */
|
||||
public class MessageAuthenticationException extends MessagingException {
|
||||
|
||||
@Serial private static final long serialVersionUID = 1L;
|
||||
|
||||
private static final FailureCategory CATEGORY = FailureCategory.AUTHENTICATION;
|
||||
|
||||
/**
|
||||
* Creates the exception with a stable code and sanitized message.
|
||||
*
|
||||
* @param code the stable failure code
|
||||
* @param sanitizedMessage the operator-facing description
|
||||
*/
|
||||
public MessageAuthenticationException(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 MessageAuthenticationException(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 MessageAuthenticationException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
-49
@@ -1,49 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/** The broker could not be reached. */
|
||||
public class MessageBrokerUnavailableException 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 MessageBrokerUnavailableException(String code, String sanitizedMessage) {
|
||||
super(new FailureDescriptor(CATEGORY, code, true, 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 MessageBrokerUnavailableException(String code, String sanitizedMessage, Throwable cause) {
|
||||
super(
|
||||
new FailureDescriptor(
|
||||
CATEGORY,
|
||||
code,
|
||||
true,
|
||||
sanitizedMessage,
|
||||
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
|
||||
cause);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the exception from an explicit descriptor.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
*/
|
||||
public MessageBrokerUnavailableException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
-49
@@ -1,49 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/** The consumer runtime failed while handling a delivery. */
|
||||
public class MessageConsumerException extends MessagingException {
|
||||
|
||||
@Serial private static final long serialVersionUID = 1L;
|
||||
|
||||
private static final FailureCategory CATEGORY = FailureCategory.PROCESSING_TRANSIENT;
|
||||
|
||||
/**
|
||||
* Creates the exception with a stable code and sanitized message.
|
||||
*
|
||||
* @param code the stable failure code
|
||||
* @param sanitizedMessage the operator-facing description
|
||||
*/
|
||||
public MessageConsumerException(String code, String sanitizedMessage) {
|
||||
super(new FailureDescriptor(CATEGORY, code, true, 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 MessageConsumerException(String code, String sanitizedMessage, Throwable cause) {
|
||||
super(
|
||||
new FailureDescriptor(
|
||||
CATEGORY,
|
||||
code,
|
||||
true,
|
||||
sanitizedMessage,
|
||||
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
|
||||
cause);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the exception from an explicit descriptor.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
*/
|
||||
public MessageConsumerException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
-54
@@ -1,54 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Publishing to the dead letter destination failed.
|
||||
*
|
||||
* <p>The source message stays unsettled. Acknowledging a source whose DLQ publish failed would
|
||||
* destroy the only remaining copy.
|
||||
*/
|
||||
public class MessageDeadLetterException 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 MessageDeadLetterException(String code, String sanitizedMessage) {
|
||||
super(new FailureDescriptor(CATEGORY, code, true, 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 MessageDeadLetterException(String code, String sanitizedMessage, Throwable cause) {
|
||||
super(
|
||||
new FailureDescriptor(
|
||||
CATEGORY,
|
||||
code,
|
||||
true,
|
||||
sanitizedMessage,
|
||||
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
|
||||
cause);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the exception from an explicit descriptor.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
*/
|
||||
public MessageDeadLetterException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
-54
@@ -1,54 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* The handler exceeded its timeout.
|
||||
*
|
||||
* <p>Whether the handler committed a side effect before the deadline is unknown, so the delivery is
|
||||
* recorded as possibly duplicated when it is retried.
|
||||
*/
|
||||
public class MessageHandlerTimeoutException extends MessagingException {
|
||||
|
||||
@Serial private static final long serialVersionUID = 1L;
|
||||
|
||||
private static final FailureCategory CATEGORY = FailureCategory.PROCESSING_TRANSIENT;
|
||||
|
||||
/**
|
||||
* Creates the exception with a stable code and sanitized message.
|
||||
*
|
||||
* @param code the stable failure code
|
||||
* @param sanitizedMessage the operator-facing description
|
||||
*/
|
||||
public MessageHandlerTimeoutException(String code, String sanitizedMessage) {
|
||||
super(new FailureDescriptor(CATEGORY, code, true, 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 MessageHandlerTimeoutException(String code, String sanitizedMessage, Throwable cause) {
|
||||
super(
|
||||
new FailureDescriptor(
|
||||
CATEGORY,
|
||||
code,
|
||||
true,
|
||||
sanitizedMessage,
|
||||
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
|
||||
cause);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the exception from an explicit descriptor.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
*/
|
||||
public MessageHandlerTimeoutException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
-49
@@ -1,49 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/** A header was reserved, secret, or exceeded a limit. */
|
||||
public class MessageHeaderRejectedException 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 MessageHeaderRejectedException(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 MessageHeaderRejectedException(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 MessageHeaderRejectedException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
-54
@@ -1,54 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* The publish outcome could not be determined.
|
||||
*
|
||||
* <p>The broker may hold the message. Republishing is permitted only under the same logical message
|
||||
* id, so that broker deduplication or a downstream Inbox can collapse the duplicate.
|
||||
*/
|
||||
public class MessagePublishAmbiguousException 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 MessagePublishAmbiguousException(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 MessagePublishAmbiguousException(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 MessagePublishAmbiguousException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
-53
@@ -1,53 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* The broker definitively refused the publish.
|
||||
*
|
||||
* <p>The message is known not to be stored, so abandoning this attempt is safe.
|
||||
*/
|
||||
public class MessagePublishRejectedException 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 MessagePublishRejectedException(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 MessagePublishRejectedException(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 MessagePublishRejectedException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
-49
@@ -1,49 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/** A redrive operation failed. */
|
||||
public class MessageRedriveException 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 MessageRedriveException(String code, String sanitizedMessage) {
|
||||
super(new FailureDescriptor(CATEGORY, code, true, 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 MessageRedriveException(String code, String sanitizedMessage, Throwable cause) {
|
||||
super(
|
||||
new FailureDescriptor(
|
||||
CATEGORY,
|
||||
code,
|
||||
true,
|
||||
sanitizedMessage,
|
||||
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
|
||||
cause);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the exception from an explicit descriptor.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
*/
|
||||
public MessageRedriveException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
-49
@@ -1,49 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/** The retry policy's attempt budget was exhausted. */
|
||||
public class MessageRetryExhaustedException 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 MessageRetryExhaustedException(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 MessageRetryExhaustedException(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 MessageRetryExhaustedException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
-49
@@ -1,49 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/** The broker accepted the publish but could not route it. */
|
||||
public class MessageRoutingException 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 MessageRoutingException(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 MessageRoutingException(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 MessageRoutingException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
-49
@@ -1,49 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/** Settlement was refused by the broker. */
|
||||
public class MessageSettlementException 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 MessageSettlementException(String code, String sanitizedMessage) {
|
||||
super(new FailureDescriptor(CATEGORY, code, true, 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 MessageSettlementException(String code, String sanitizedMessage, Throwable cause) {
|
||||
super(
|
||||
new FailureDescriptor(
|
||||
CATEGORY,
|
||||
code,
|
||||
true,
|
||||
sanitizedMessage,
|
||||
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
|
||||
cause);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the exception from an explicit descriptor.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
*/
|
||||
public MessageSettlementException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
-53
@@ -1,53 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.error;
|
||||
|
||||
import java.io.Serial;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Settlement was sent but not confirmed.
|
||||
*
|
||||
* <p>Redelivery is possible. Callers must not treat this as a successful settlement.
|
||||
*/
|
||||
public class MessageSettlementUnknownException 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 MessageSettlementUnknownException(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 MessageSettlementUnknownException(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 MessageSettlementUnknownException(FailureDescriptor failure) {
|
||||
super(failure);
|
||||
}
|
||||
}
|
||||
-25
@@ -1,25 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.publish;
|
||||
|
||||
import java.util.List;
|
||||
import java.util.concurrent.CompletionStage;
|
||||
|
||||
/**
|
||||
* The M2 batch publish entry point.
|
||||
*
|
||||
* <p>A batch is a throughput optimisation, not a transaction. Entries succeed, fail, and go
|
||||
* ambiguous independently, and {@link BatchPublishResult} keeps every entry's outcome against its
|
||||
* submission index so the caller can act per entry. Nothing here rolls back: an adapter that
|
||||
* reported a confirmed entry cannot un-publish it because a later entry was rejected.
|
||||
*/
|
||||
public interface BatchMessagePublisher {
|
||||
|
||||
/**
|
||||
* Publishes a batch of independent requests.
|
||||
*
|
||||
* @param requests the entries to publish, in submission order
|
||||
* @param options the batch-wide options
|
||||
* @return a stage completing with one outcome per submitted entry
|
||||
*/
|
||||
CompletionStage<BatchPublishResult> publish(
|
||||
List<PublishRequest<?>> requests, BatchPublishOptions options);
|
||||
}
|
||||
-27
@@ -1,27 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.publish;
|
||||
|
||||
import dev.caskeleton.messaging.api.MessageId;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* One item's outcome inside a batch publish.
|
||||
*
|
||||
* <p>Kept per index rather than collapsed into a batch-level success flag. A batch is not a
|
||||
* transaction: some items confirm, some are rejected, and some are ambiguous, and the caller has to
|
||||
* be able to act differently on each. A single boolean would force it to re-submit everything,
|
||||
* which duplicates the items that already landed.
|
||||
*
|
||||
* @param index the item's position in the submitted list
|
||||
* @param messageId the item's logical identity
|
||||
* @param result the item's outcome and evidence
|
||||
*/
|
||||
public record BatchPublishItemResult(int index, MessageId messageId, PublishResult result) {
|
||||
|
||||
public BatchPublishItemResult {
|
||||
Objects.requireNonNull(messageId, "messageId must not be null");
|
||||
Objects.requireNonNull(result, "result must not be null");
|
||||
if (index < 0) {
|
||||
throw new IllegalArgumentException("index must not be negative");
|
||||
}
|
||||
}
|
||||
}
|
||||
-42
@@ -1,42 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.publish;
|
||||
|
||||
import java.time.Duration;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Options covering a whole batch publish.
|
||||
*
|
||||
* <p>There is no retry setting. A batch is not a transaction, and retrying the batch would resubmit
|
||||
* entries that already confirmed, so the platform never retries one on the caller's behalf; the
|
||||
* caller resubmits the individual entries it knows are duplicate-safe under their original {@code
|
||||
* messageId}.
|
||||
*
|
||||
* @param timeout the deadline for the whole batch
|
||||
* @param maxBatchSize the largest number of entries accepted in one call
|
||||
* @param stopOnFirstRejection whether to skip remaining entries once one is rejected
|
||||
*/
|
||||
public record BatchPublishOptions(
|
||||
Duration timeout, int maxBatchSize, boolean stopOnFirstRejection) {
|
||||
|
||||
private static final Duration DEFAULT_TIMEOUT = Duration.ofSeconds(30);
|
||||
private static final int DEFAULT_MAX_BATCH_SIZE = 500;
|
||||
|
||||
public BatchPublishOptions {
|
||||
Objects.requireNonNull(timeout, "timeout must not be null");
|
||||
if (timeout.isNegative() || timeout.isZero()) {
|
||||
throw new IllegalArgumentException("batch timeout must be positive");
|
||||
}
|
||||
if (maxBatchSize < 1) {
|
||||
throw new IllegalArgumentException("maxBatchSize must be at least 1");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the defaults: thirty seconds, 500 entries, best-effort completion of every entry.
|
||||
*
|
||||
* @return the default options
|
||||
*/
|
||||
public static BatchPublishOptions defaults() {
|
||||
return new BatchPublishOptions(DEFAULT_TIMEOUT, DEFAULT_MAX_BATCH_SIZE, false);
|
||||
}
|
||||
}
|
||||
-44
@@ -1,44 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.publish;
|
||||
|
||||
import java.time.Duration;
|
||||
import java.util.List;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* The outcome of one batch publish.
|
||||
*
|
||||
* <p>There is no automatic batch retry. Re-submitting a whole batch because part of it failed
|
||||
* duplicates the part that succeeded; the caller re-submits only the items it decides are
|
||||
* duplicate-safe, under their original message ids.
|
||||
*
|
||||
* @param items each item's outcome, in submission order
|
||||
* @param elapsed how long the batch took
|
||||
*/
|
||||
public record BatchPublishResult(List<BatchPublishItemResult> items, Duration elapsed) {
|
||||
|
||||
public BatchPublishResult {
|
||||
Objects.requireNonNull(items, "items must not be null");
|
||||
Objects.requireNonNull(elapsed, "elapsed must not be null");
|
||||
items = List.copyOf(items);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the items with a given completion.
|
||||
*
|
||||
* @param completion the completion to select
|
||||
* @return the matching items
|
||||
*/
|
||||
public List<BatchPublishItemResult> withCompletion(PublishCompletion completion) {
|
||||
return items.stream().filter(item -> item.result().completion() == completion).toList();
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether every item confirmed.
|
||||
*
|
||||
* @return true when nothing was rejected or ambiguous
|
||||
*/
|
||||
public boolean allConfirmed() {
|
||||
return items.stream()
|
||||
.allMatch(item -> item.result().completion() == PublishCompletion.CONFIRMED);
|
||||
}
|
||||
}
|
||||
-30
@@ -1,30 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.publish;
|
||||
|
||||
import dev.caskeleton.messaging.api.MessageEnvelope;
|
||||
import dev.caskeleton.messaging.api.destination.MessageDestination;
|
||||
|
||||
/**
|
||||
* The blocking facade over the asynchronous publisher.
|
||||
*
|
||||
* <p>Offered because most business code is written against a blocking data access layer, and
|
||||
* forcing a {@code CompletionStage} through it produces worse code than a blocking call does. It is
|
||||
* a facade rather than a second implementation: the core stays asynchronous, and this only converts
|
||||
* the lifecycle.
|
||||
*
|
||||
* <p>It respects the publish deadline rather than waiting indefinitely, so a stalled broker
|
||||
* surfaces as a timeout with ambiguous evidence instead of an exhausted thread pool.
|
||||
*/
|
||||
public interface BlockingMessagePublisher {
|
||||
|
||||
/**
|
||||
* Publishes one message and waits for its outcome.
|
||||
*
|
||||
* @param <T> the payload type
|
||||
* @param destination the logical destination
|
||||
* @param message the envelope to publish
|
||||
* @param options per-call options, including the deadline
|
||||
* @return the outcome and its evidence
|
||||
*/
|
||||
<T> PublishResult publish(
|
||||
MessageDestination<T> destination, MessageEnvelope<T> message, PublishOptions options);
|
||||
}
|
||||
-28
@@ -1,28 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.publish;
|
||||
|
||||
import dev.caskeleton.messaging.api.MessageEnvelope;
|
||||
import dev.caskeleton.messaging.api.destination.MessageDestination;
|
||||
import java.time.Instant;
|
||||
import java.util.concurrent.CompletionStage;
|
||||
|
||||
/**
|
||||
* The M2 scheduled-delivery entry point.
|
||||
*
|
||||
* <p>Only destinations whose runtime declares {@code delayedDelivery} accept these calls. A plain
|
||||
* Kafka topic does not: emulating a delay by holding the message in the producer would make the
|
||||
* publisher's own liveness the schedule, so the platform rejects the call instead of pretending.
|
||||
*/
|
||||
public interface DelayedMessagePublisher {
|
||||
|
||||
/**
|
||||
* Publishes a message the broker must not deliver before the given instant.
|
||||
*
|
||||
* @param <T> the payload type
|
||||
* @param destination the logical destination
|
||||
* @param message the envelope to publish
|
||||
* @param deliverAt the earliest delivery time
|
||||
* @return a stage completing with the publish outcome and its evidence
|
||||
*/
|
||||
<T> CompletionStage<PublishResult> publish(
|
||||
MessageDestination<T> destination, MessageEnvelope<T> message, Instant deliverAt);
|
||||
}
|
||||
+64
@@ -100,6 +100,70 @@ public record PublishResult(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 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<BrokerPosition> 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.
|
||||
*
|
||||
* <p>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.
|
||||
*
|
||||
|
||||
-25
@@ -1,25 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.settlement;
|
||||
|
||||
import dev.caskeleton.messaging.api.delivery.MessageDelivery;
|
||||
import java.util.concurrent.CompletionStage;
|
||||
|
||||
/**
|
||||
* The M2 handler that settles its own deliveries.
|
||||
*
|
||||
* <p>Available only to modules granted the advanced capability. A handler that returns without
|
||||
* calling a terminal settlement method is a defect the runtime detects and reports rather than
|
||||
* silently leaving the message in flight.
|
||||
*
|
||||
* @param <T> the payload type
|
||||
*/
|
||||
public interface ManualMessageHandler<T> {
|
||||
|
||||
/**
|
||||
* Handles one delivery, settling it through the supplied controller.
|
||||
*
|
||||
* @param delivery the decoded message and its metadata
|
||||
* @param settlement the settlement handle for this delivery
|
||||
* @return a stage completing when handling has finished
|
||||
*/
|
||||
CompletionStage<Void> handle(MessageDelivery<T> delivery, SettlementController settlement);
|
||||
}
|
||||
-50
@@ -1,50 +0,0 @@
|
||||
package dev.caskeleton.messaging.api.settlement;
|
||||
|
||||
import dev.caskeleton.messaging.api.error.FailureDescriptor;
|
||||
import java.time.Duration;
|
||||
import java.util.concurrent.CompletionStage;
|
||||
|
||||
/**
|
||||
* The M2 manual settlement handle.
|
||||
*
|
||||
* <p>No method here accepts a broker channel, delivery tag, or offset. Manual settlement changes
|
||||
* <em>when</em> the platform settles, never <em>who</em> settles, so the same DLQ-before-ack
|
||||
* ordering and payload limits still apply.
|
||||
*
|
||||
* <p>Exactly one terminal call is permitted per delivery; a second call fails rather than racing
|
||||
* the first.
|
||||
*/
|
||||
public interface SettlementController {
|
||||
|
||||
/**
|
||||
* Acknowledges the message.
|
||||
*
|
||||
* @return a stage completing with the settlement outcome
|
||||
*/
|
||||
CompletionStage<SettlementResult> ack();
|
||||
|
||||
/**
|
||||
* Schedules the message for another attempt.
|
||||
*
|
||||
* @param delay how long to wait before redelivery
|
||||
* @return a stage completing with the settlement outcome
|
||||
*/
|
||||
CompletionStage<SettlementResult> retry(Duration delay);
|
||||
|
||||
/**
|
||||
* Routes the message to the dead letter destination, settling the source only after that publish
|
||||
* is confirmed.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
* @return a stage completing with the settlement outcome
|
||||
*/
|
||||
CompletionStage<SettlementResult> deadLetter(FailureDescriptor failure);
|
||||
|
||||
/**
|
||||
* Discards the message without dead lettering.
|
||||
*
|
||||
* @param failure the sanitized failure description
|
||||
* @return a stage completing with the settlement outcome
|
||||
*/
|
||||
CompletionStage<SettlementResult> reject(FailureDescriptor failure);
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user