review-followup Wave 3 라운드 3(P21): messaging 플랫폼 — Kafka 소비(MessageHandler 하나), API 정리

- 결정 10: consume 계약을 `MessageHandler<T>` 하나로, starter-kafka가 consumer 조립(handler bean이 있으면 켜짐,
  `app.messaging.enabled=false`로 끔). 오프셋은 handler Success(inbox면 트랜잭션 커밋) 뒤 또는 DLQ 쓰기 확인 뒤에만 커밋,
  auto-commit 금지, `read_committed`, 재시도 소진 → DLQ(없으면 멈춤) — Kafka+PG로 왕복·중복 제거·DLQ 검증
- 미사용 API 타입·Blocking/Reactive/Batch facade·reactor api 노출 삭제, `PublishResult` 정적 factory,
  `MessagingCapabilities` → EnumSet, API leaf 병합(core-api+schema-api, admin-api+admin-runtime), starter god config 분해,
  Kafka broker 설정은 starter-kafka로, 등급 용어 정리
- 결함 수정: Retry 응답이 시도 횟수를 세지 않아 partition 정지(P21-new-1), deliveryAttempt 항상 1(P21-new-2)
- 통합: app-bootstrap `MessagingPublicSurfaceContractTest` 기대값을 P21 변경에 맞춤, starter-kafka에 `api kafka-clients`

검증: ./gradlew check architectureCheck verifyDependencyLocks :app-bootstrap:verifyEnvKeys :app-bootstrap:integrationTest
:sample-portfolio:integrationTest :messaging:messaging-spring-boot-starter:integrationTest
:messaging:messaging-reliability-jdbc-postgresql:integrationTest mainCheck --continue 통과(812 task)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-29 13:29:46 +09:00
co-authored by Claude Opus 5.5
parent 36ba0810c8
commit 486d85a603
197 changed files with 3526 additions and 4089 deletions
+18
View File
@@ -469,3 +469,21 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap
| `PostgreSqlNotificationBackgroundPassIntegrationTest.replayMarksAnEventWithNoProjectorFailed` | `src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/.../readiness/` | `ce863643` | S1-#9: `NO_PROJECTOR` 분기 삭제 |
| `ca.release-provenance` 플러그인 | `src/build-logic/src/main/java/dev/caskeleton/buildlogic/release/` | `64a83918` | BUILD-O3-5: sourceRevision은 `ca.java-conventions`, provenance 검증은 루트 태스크 하나 |
| app-bootstrap의 `MessagingCapabilityRegistryContractTest` 위치 | `src/app-bootstrap/src/test/java/.../MessagingCapabilityRegistryContractTest.java` | `64a83918` | 결정 29: messaging leaf 테스트로 이동 |
| `BatchMessageHandler`, `BatchMessageDelivery`, `BatchDeliveryMetadata`, `PauseResumeController`, `ProcessingGuarantee` | `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/` | `423a29c4` | 구현·사용처 0(M-9) |
| `CapabilityRegistry` | `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/CapabilityRegistry.java` | `423a29c4` | 구현·사용처 0(M-9) |
| `DelayedMessagePublisher`, `BlockingMessagePublisher`, `BatchMessagePublisher`, `BatchPublishOptions`, `BatchPublishItemResult`, `BatchPublishResult` | `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/` | `423a29c4` | 구현·사용처 0(M-9), facade 삭제로 구현 0(S7-#9c) |
| `ManualMessageHandler`, `SettlementController` | `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/` | `423a29c4` | 구현·사용처 0(M-9) |
| 예외 13개 `Message{Authentication,BrokerUnavailable,Consumer,DeadLetter,HandlerTimeout,HeaderRejected,PublishAmbiguous,PublishRejected,Redrive,RetryExhausted,Routing,Settlement,SettlementUnknown}Exception` | `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/` | `423a29c4` | 참조 0(S7-#10) |
| `MessagingLifecycle` (+ `MessagingLifecycleTest`) | `src/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingLifecycle.java` | `423a29c4` | 구현 0(M-9). 종료 순서는 `MessagingShutdownLifecycle`이 실제로 수행 |
| `KafkaTopologyInspector`, `KafkaBatchConsumerRegistrar` | `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/` | `423a29c4` | main 참조 0(S7-#10, S7-#2: batch consume은 결정 10 범위 밖) |
| `ReliableMessagePublisher`, `InboxRecord` | `src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/` | `423a29c4` | 참조 0(S7-#10). outbox append는 canonical `OutboxAppendPort` |
| `DefaultBlockingMessagePublisher`, `DefaultReactiveMessagePublisher`, `DefaultBatchMessagePublisher`, `ReactiveMessagePublisher` (+ `BlockingFacadeTest`, `ReactiveFacadeTest`, `BatchPublisherTest`) | `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/` | `423a29c4` | starter 밖 참조 0(S7-#9c) |
| `PublishResults` | `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/PublishResults.java` | `423a29c4` | facade 삭제로 호출자 0(S7-#6b) |
| `MessagingCapabilities`의 읽지 않는 flag 9개(brokerAcknowledgement, replicationOrPersistenceEvidence, perMessageSettlement, batchSettlement, keyedOrdering, replay, brokerTransaction, nativeDeadLetter, topologyManagement) | `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/MessagingCapabilities.java` | `423a29c4` | main 읽기 0(S7-#11) |
| leaf `messaging-schema-api`, `messaging-admin-runtime` (코드는 이동), `messaging-admin-api`(→ `messaging-admin`으로 개명) | `src/messaging/messaging-schema-api`, `src/messaging/messaging-admin-runtime`, `src/messaging/messaging-admin-api` | `423a29c4` | S7-#12 병합 |
| `BrokerSettings`의 Kafka 필드 7개 (starter-kafka `KafkaBrokerSettings`로 이동) | `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/BrokerSettings.java` | `423a29c4` | broker 중립 starter에서 broker 전용 union 제거(S7-#9b) |
| `IdempotentMessageHandler`, `TransactionalMessageAction`, `InboxResult` | `src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/` | `423a29c4` | consume 계약을 `MessageHandler<T>` 하나로(S7-#2, 결정 10). `InboxResult`는 boolean `reserve`로 만들 수 없는 값(CLAIMED_ELSEWHERE)만 남은 enum |
| `TransactionalInboxHandler` (+ starter bean `transactionalInboxHandler`, `InboxOperationsTest.anAlreadyAppliedMessageIsSafeToSettleButAClaimedOneIsNot`) | `src/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/TransactionalInboxHandler.java` | `423a29c4` | `InboxMessageHandler`(MessageHandler 데코레이터)로 대체(S7-#2) |
| untyped `DefaultDeliveryProcessor(Function<MessageEnvelope<EncodedMessage>, HandleResult>, …)` 생성자 | `src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessor.java` | `423a29c4` | typed `MessageHandler` 목록을 받는 형태로 교체(S7-#2) |
| `CapabilityTier` (→ `ApiTier`로 개명), `CompatibilityMatrix.Tier` (→ `SupportGrade`) | `src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/CapabilityTier.java`, `src/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CompatibilityMatrix.java` | `423a29c4` | 등급 용어 정리(S7-#14) |
| `api 'io.projectreactor:reactor-core'`, `testImplementation 'io.projectreactor:reactor-test'` | `src/messaging/messaging-spring-boot-starter/build.gradle` | `423a29c4` | reactive facade 삭제로 노출 이유 소멸(S7-#9c) |
+18
View File
@@ -108,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)`.
@@ -0,0 +1,66 @@
# W3-P21 — messaging 플랫폼: Kafka 소비(결정 10) · API 정리
- worktree: `/home/donghyeon/workspace/chat-gpt-container/codebase/clean-architecture-backend-template/.claude/worktrees/agent-ad50aef2d9d076c6f` (기준 `423a29c4`)
- 커밋(순서대로):
- `4ac809e1` P21 D: messaging 미사용 API 타입·facade·reactor api 노출 삭제
- `0f6f3fbb` P21 W3: PublishResult 정적 factory, MessagingCapabilities를 EnumSet으로
- `409ce47a` P21 W3: messaging API leaf 병합(core-api+schema-api, admin-api+admin-runtime)
- `06bde64f` P21 W3: starter god config 분해, Kafka broker 설정을 starter-kafka로
- `30f0885a` P21 W3: Kafka 소비 지원(결정 10) — MessageHandler 하나로, starter-kafka가 consumer 조립
- `faa40c7e` P21 W3: 등급 용어 정리 — CapabilityTier→ApiTier, CompatibilityMatrix.Tier→SupportGrade
- registry 변경(`src/config/architecture/modules.json`): `messaging-schema-api`·`messaging-admin-runtime` 삭제, `messaging-admin-api` → `messaging-admin`(source `src/messaging/messaging-admin`, edge `messaging-core-api`, `messaging-observability`). 다른 leaf의 `messaging-schema-api` edge는 `messaging-core-api`로, admin 두 edge는 `messaging-admin` 하나로 치환. 새 edge 없음.
- 설정 키·env 키 변경 없음(`verifyEnvKeys` 대상 아님). 설정 prefix 변경 없음. migration 추가 없음.
- lockfile: 재생성한 것 — starter, starter-kafka, adapter:outbound:messaging-kafka, messaging-admin(새), messaging-reliability-jdbc-postgresql. 삭제 — messaging-schema-api, messaging-admin-runtime. 통합 뒤 다시 재생성 권장.
- 문서: `docs/messaging/outbox-inbox.md`에 「소비와 연결」 절 추가, `src/messaging/CLAUDE.md`·`src/adapter/outbound/messaging/CLAUDE.md`의 leaf 이름·reactor 문구 갱신. `docs/capability-status.md`는 고치지 않음(아래 「제거된 코드」 표를 옮겨 적을 것).
- 하지 않은 것(지시대로): 설정 prefix 변경, `Sha256`·`Backoff` 공용화.
## 검증 (마지막 커밋 `faa40c7e` 기준, 전부 `--max-workers=2`)
- messaging 관련 registry leaf 전부(`:adapter:outbound:messaging`, `:adapter:outbound:messaging-kafka`, `:messaging:*` 19개)의 `check`: PASS
- `:messaging:messaging-spring-boot-starter:integrationTest`(Kafka, + PostgreSQL): 6/6 PASS (새 `MessagingKafkaConsumeQualificationTest` 3개 포함)
- `:messaging:messaging-reliability-jdbc-postgresql:integrationTest`: 36/36 PASS
- `:app-bootstrap:integrationTest`: 9/9 PASS
- `architectureCheck`: PASS, `verifyDependencyLocks`: PASS
- mainCheck의 messaging qualification lane `verifyMessagingContracts`: PASS
- `:app-bootstrap:verifyEnvKeys`: 실행 안 함 — env 키·설정 키 변경 없음
## 행 결과
| ID | 결과 | 근거 |
|---|---|---|
| M-9 | 해당 없음(코드 삭제) | `4ac809e1`에서 7개 삭제(main·test 참조 0 확인). 함께 batch/manual consume 쪽 부속 타입 `BatchMessageDelivery`·`BatchDeliveryMetadata`·`SettlementController`도 참조가 이 타입들뿐이라 삭제 |
| S7-#9c | 해당 없음(코드 삭제) | `4ac809e1`: `Default{Blocking,Reactive,Batch}MessagePublisher`·`ReactiveMessagePublisher`와 bean 3개, core-api `BlockingMessagePublisher`·`BatchMessagePublisher`·`BatchPublish{Options,ItemResult,Result}`(구현이 facade뿐), 테스트 3개 삭제. `reactor-core` api·`reactor-test` 삭제, lockfile 재생성(starter, starter-kafka, adapter:outbound:messaging-kafka) |
| S7-#2 | 완료 | `30f0885a`. **계약:** consume 계약은 `MessageHandler<T>` 하나(`destination()` + `handle`, `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java`). `IdempotentMessageHandler`·`TransactionalMessageAction`·`TransactionalInboxHandler`·`InboxResult` 삭제, 대신 `InboxMessageHandler<T> implements MessageHandler<T>`(`src/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java`). untyped `DefaultDeliveryProcessor`는 typed handler용으로 다시 씀(`src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessor.java`). **조립:** core starter `MessagingConsumeConfiguration`→`MessageConsumers`(handler bean이 있을 때만), starter-kafka `KafkaConsumerConfiguration`(transport의 consumer factory = `KafkaPolledRegistration`, `KafkaConsumerLifecycle`이 `transport.register`로 구독). `KafkaMessagingTransport`는 이제 consumer factory와 함께 만들어져 `KAFKA_CONSUMER_NOT_CONFIGURED`가 조립 경로에서 사라짐. 켜고 끄기: handler bean 있으면 켜짐, `app.messaging.enabled=false`면 전부 없음 — 새 설정 키·env 키 없음. **정책(기존 설계서 §19.2·§24·§25·§26.4를 따름, 없던 부분은 가장 작은 안전한 선택):** offset은 contiguous watermark로 `Success` 뒤(inbox destination이면 inbox transaction commit 뒤) 또는 DLQ 기록 확인 뒤에만 commit, `enable.auto.commit=false` 고정(broker 항목이 `true`면 기동 거부), 새 group은 `auto.offset.reset=earliest`, `isolation.level=read_committed`, group은 destination `consumer.group`(없으면 기동 거부 — inbox 식별자와 같음), `Retry`·예외·timeout은 `retry.max-attempts`까지 partition pause 후 재읽기(backoff 최소 1s), 다 쓰면 DLQ 토픽에 원본 record(+failure 헤더)를 쓰고 확인되면 commit — DLQ 없는 destination(at-most-once만 가능, validator가 at-least-once+DLQ 없음을 이미 거부)은 멈춤, `DeadLetter` 결과는 `DeadLetterOrchestrator`로 DLQ 발행 확인 후 ack, `Reject`는 at-most-once에서만 discard·그 밖은 dead letter, handler 없는 message type·decode 실패는 dead letter, `INBOX_TRANSACTIONAL`이면 handler를 inbox로 감싸고 `IdempotentConsumer` bean 없으면 기동 거부, security `access.consumable`에 없는 destination은 기동 거부. **테스트:** Kafka+PostgreSQL Testcontainers `MessagingKafkaConsumeQualificationTest.aPublishedMessageIsConsumedByTheHandlerBeanAndItsOffsetIsCommitted`·`aRedeliveredMessageIsAppliedOnceThroughThePostgresInbox`(같은 messageId 2회 발행 → projection 1행, handler 1회, committed offset 2)·`aMessageItsHandlerKeepsRetryingIsParkedOnTheDeadLetterTopicOnceItsAttemptsAreSpent` PASS(`:messaging:messaging-spring-boot-starter:integrationTest` 6/6). 새 기능이라 FAIL 단계는 조립 부재(컴파일 오류: `MessageHandler.destination()` 없음·consumer 없음). 단위: `DefaultDeliveryProcessorTest` 11, `InboxMessageHandlerTest` 3, `MessagingConsumeConfigurationTest` 4 PASS. **결함 수정(TDD):** `KafkaConsumerRegistrarTest.aDeliveryItsHandlerKeepsRequeueingSpendsTheBudgetAndIsQuarantined` FAIL(`Expecting actual: [] to contain exactly: [10L]`)→PASS, `aReReadDeliveryTellsTheHandlerWhichAttemptItIs` FAIL(`Expecting actual: [1, 1] to contain exactly: [1, 2]`)→PASS — 아래 P21-new-1·2 |
| S7-#6a | 완료 | `0f6f3fbb`: `PublishResult.confirmed/rejected/ambiguous` 정적 factory(`src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishResult.java` 하단). main의 `new PublishResult(` 호출은 factory 안 3곳뿐(Kafka transport·classifier·mapper, `DefaultMessagePublisher` 2곳, `OutboxRelay` 1곳 교체). 테스트 `PublishResultTest.theRejectedFactoryReportsNothingWasTransmittedOrRouted`·`theAmbiguousFactoryReportsTheBrokerMayHoldTheMessage`·`theConfirmedFactoryCarriesAcceptanceAndPositionWithoutAFailure` PASS(새 API라 FAIL 단계는 컴파일 오류). 부수 변화: `DefaultMessagePublisher`의 로컬 거부는 routing `UNKNOWN`→`NOT_APPLICABLE`(보내지 않은 메시지는 라우팅 대상이 아님, Kafka 로컬 거부와 같게) |
| S7-#6b | 해당 없음(코드 삭제) | 직접 생성 2곳이 있던 starter `PublishResults`는 S7-#9c facade 삭제로 호출자 0이 되어 `0f6f3fbb`에서 삭제. main의 `new PublishEvidence(`는 `PublishEvidence` factory 안뿐 |
| S7-#11 | 완료 | `0f6f3fbb`: `MessagingCapabilities(Set<Capability> supported)` + `supports(Capability)`·`of(...)`·`none()`. 읽히던 flag 3개만 남김(`ORDERED_STREAM`—`DefaultRetryDecisionEngine`, `DELAYED_DELIVERY`—같은 곳, `DEDUPLICATED_PUBLISH`—`DefaultMessagePublisher.requireSupportedOptions`). 나머지 9개는 main에서 읽는 곳 0이라 삭제. Kafka 선언은 `MessagingCapabilities.of(ORDERED_STREAM)`(`KafkaMessagingTransport.java` `CAPABILITIES`). 테스트 `DestinationCapabilityTest.aCapabilitySetSupportsExactlyWhatWasNamedAndIgnoresLaterChangesToTheInput` PASS, `RetryDecisionEngineTest` PASS |
| S7-#12 | 완료 | `409ce47a`: `messaging-schema-api` → `messaging-core-api`(패키지 `dev.caskeleton.messaging.schema` 유지), `messaging-admin-api`+`messaging-admin-runtime` → `messaging-admin`(패키지 `admin`·`admin.runtime` 유지). `modules.json`: 두 id 삭제, `messaging-admin-api`→`messaging-admin` 개명, 모든 edge 치환. `messaging-admin`의 edge는 실제 import 기준 `messaging-core-api`, `messaging-observability`(implementation)만 — 선언만 있던 policy·schema-api·transport-spi·security edge 삭제. `architectureCheck` PASS, messaging 전 leaf `check` PASS, lockfile 재생성 |
| S7-#9a | 완료 | `06bde64f`: `MessagingCoreAutoConfiguration`(549줄, bean 28)을 `MessagingValidationConfiguration`(설정 컴파일·검증, bean 10), `MessagingPublishConfiguration`(publish pipeline·runtime·shutdown, bean 11 + helper), `MessagingObservabilityConfiguration`(redactor·cardinality·metrics·endpoint, bean 4)으로 분리. `MessagingCoreAutoConfiguration`은 세 개를 `@Import`하는 진입점(23줄)이라 기존 조립·테스트 그대로. starter `check` PASS |
| S7-#9b | 완료 | `06bde64f`: `BrokerSettings`(core starter)에서 Kafka 필드 7개(`bootstrapServers`, `enableIdempotence`, `acks`, `maxInFlightRequestsPerConnection`, `deliveryTimeout`, `enableAutoCommit`, `consumerGroup`) 삭제. starter-kafka `KafkaBrokerSettings`(`src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerSettings.java`)가 같은 `app.messaging.brokers.<name>` 항목을 `Binder`로 바인딩, `KafkaBrokerCatalog` bean. bootstrap-servers 필수 검증도 core compiler에서 이리로 이동. `MessagingConfigurationKeyValidator`는 `MessagingProviderSelection.PROVIDER_BROKER_SETTINGS`(family→설정 record 클래스 이름)로 family 키를 허용 — record가 classpath에 없으면 neutral 키만. 설정 키·env 키 변경 없음. 테스트 `MessagingConfigurationBindingTest.aKafkaBrokerWithoutAnAddressIsRefusedByTheKafkaStarterNamingTheKey` PASS, 문서 YAML 바인딩 테스트 `theDocumentedConfigurationBindsToTheProfilesThePlatformUses` PASS |
| S7-#14 | 완료 | `faa40c7e`. **패키지·leaf 이름:** 행이 든 불일치(`grpc-policy`의 `grpc.{resilience,streaming}` 패키지 vs leaf `grpc-advanced-resilience/-streaming`)는 S7-#3(`e2397d2f`)에서 leaf가 `grpc-runtime`·`grpc-advanced`로 합쳐지며 사라졌다 — 지금 advanced 쪽 패키지는 `dev.caskeleton.grpc.advanced.{resilience,streaming,…}`로 leaf 이름과 같다(`src/grpc-advanced/grpc-advanced/src/main/java/dev/caskeleton/grpc/advanced/`). grpc-runtime 패키지를 `grpc.runtime.*`로 옮기는 것은 import 전체 변경이라 하지 않음(현황표 수정 방향도 S7-#3 병합 시점 기준). **등급 용어:** 4개가 실은 세 개념이다 — API 표면 단계, 지원(검증) 수준, 증거 종류. messaging에서 "Tier"는 API 표면(M1–M3) 하나로: `CapabilityTier` → `ApiTier`(`src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ApiTier.java`). 지원 수준은 gRPC와 같은 "Grade"로: `CompatibilityMatrix.Tier` → `CompatibilityMatrix.SupportGrade`(record 필드 `tier`→`grade`). `GrpcCapabilityGrade`·`GrpcEvidenceGrade`는 이미 Grade라 유지. vendored messaging과 grpc는 서로 타입을 공유할 수 없어 enum 하나로 합치지 않고 용어만 맞췄다. 설정 키 `destinations.*.tier`와 값 `M1`은 그대로. messaging 전 leaf `check` PASS |
| S7-#10 | 해당 없음(코드 삭제) | `4ac809e1`: 예외 13개(Authentication, BrokerUnavailable, Consumer, DeadLetter, HandlerTimeout, HeaderRejected, PublishAmbiguous, PublishRejected, Redrive, RetryExhausted, Routing, Settlement, SettlementUnknown — 삭제 전 main·test 참조 0), `KafkaTopologyInspector`, `ReliableMessagePublisher`, `InboxRecord` 삭제. `MessageHandler`는 S7-#2 결정으로 유지 |
## 제거된 코드
| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 |
|---|---|---|---|
| `BatchMessageHandler`, `BatchMessageDelivery`, `BatchDeliveryMetadata`, `PauseResumeController`, `ProcessingGuarantee` | `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/` | `423a29c4` | 구현·사용처 0(M-9) |
| `CapabilityRegistry` | `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/CapabilityRegistry.java` | `423a29c4` | 구현·사용처 0(M-9) |
| `DelayedMessagePublisher`, `BlockingMessagePublisher`, `BatchMessagePublisher`, `BatchPublishOptions`, `BatchPublishItemResult`, `BatchPublishResult` | `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/` | `423a29c4` | 구현·사용처 0(M-9), facade 삭제로 구현 0(S7-#9c) |
| `ManualMessageHandler`, `SettlementController` | `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/` | `423a29c4` | 구현·사용처 0(M-9) |
| 예외 13개 `Message{Authentication,BrokerUnavailable,Consumer,DeadLetter,HandlerTimeout,HeaderRejected,PublishAmbiguous,PublishRejected,Redrive,RetryExhausted,Routing,Settlement,SettlementUnknown}Exception` | `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/` | `423a29c4` | 참조 0(S7-#10) |
| `MessagingLifecycle` (+ `MessagingLifecycleTest`) | `src/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingLifecycle.java` | `423a29c4` | 구현 0(M-9). 종료 순서는 `MessagingShutdownLifecycle`이 실제로 수행 |
| `KafkaTopologyInspector`, `KafkaBatchConsumerRegistrar` | `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/` | `423a29c4` | main 참조 0(S7-#10, S7-#2: batch consume은 결정 10 범위 밖) |
| `ReliableMessagePublisher`, `InboxRecord` | `src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/` | `423a29c4` | 참조 0(S7-#10). outbox append는 canonical `OutboxAppendPort` |
| `DefaultBlockingMessagePublisher`, `DefaultReactiveMessagePublisher`, `DefaultBatchMessagePublisher`, `ReactiveMessagePublisher` (+ `BlockingFacadeTest`, `ReactiveFacadeTest`, `BatchPublisherTest`) | `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/` | `423a29c4` | starter 밖 참조 0(S7-#9c) |
| `PublishResults` | `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/PublishResults.java` | `423a29c4` | facade 삭제로 호출자 0(S7-#6b) |
| `MessagingCapabilities`의 읽지 않는 flag 9개(brokerAcknowledgement, replicationOrPersistenceEvidence, perMessageSettlement, batchSettlement, keyedOrdering, replay, brokerTransaction, nativeDeadLetter, topologyManagement) | `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/MessagingCapabilities.java` | `423a29c4` | main 읽기 0(S7-#11) |
| leaf `messaging-schema-api`, `messaging-admin-runtime` (코드는 이동), `messaging-admin-api`(→ `messaging-admin`으로 개명) | `src/messaging/messaging-schema-api`, `src/messaging/messaging-admin-runtime`, `src/messaging/messaging-admin-api` | `423a29c4` | S7-#12 병합 |
| `BrokerSettings`의 Kafka 필드 7개 (starter-kafka `KafkaBrokerSettings`로 이동) | `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/BrokerSettings.java` | `423a29c4` | broker 중립 starter에서 broker 전용 union 제거(S7-#9b) |
| `IdempotentMessageHandler`, `TransactionalMessageAction`, `InboxResult` | `src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/` | `423a29c4` | consume 계약을 `MessageHandler<T>` 하나로(S7-#2, 결정 10). `InboxResult`는 boolean `reserve`로 만들 수 없는 값(CLAIMED_ELSEWHERE)만 남은 enum |
| `TransactionalInboxHandler` (+ starter bean `transactionalInboxHandler`, `InboxOperationsTest.anAlreadyAppliedMessageIsSafeToSettleButAClaimedOneIsNot`) | `src/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/TransactionalInboxHandler.java` | `423a29c4` | `InboxMessageHandler`(MessageHandler 데코레이터)로 대체(S7-#2) |
| untyped `DefaultDeliveryProcessor(Function<MessageEnvelope<EncodedMessage>, HandleResult>, …)` 생성자 | `src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessor.java` | `423a29c4` | typed `MessageHandler` 목록을 받는 형태로 교체(S7-#2) |
| `CapabilityTier` (→ `ApiTier`로 개명), `CompatibilityMatrix.Tier` (→ `SupportGrade`) | `src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/CapabilityTier.java`, `src/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CompatibilityMatrix.java` | `423a29c4` | 등급 용어 정리(S7-#14) |
| `api 'io.projectreactor:reactor-core'`, `testImplementation 'io.projectreactor:reactor-test'` | `src/messaging/messaging-spring-boot-starter/build.gradle` | `423a29c4` | reactive facade 삭제로 노출 이유 소멸(S7-#9c) |
## 새로 발견한 결함
- **P21-new-1** (고침): `KafkaConsumerRegistrar`의 `QueuedSettlement.requeue(delay)`가 시도 횟수를 세지 않았다. 예외·timeout 경로만 `retry.max-attempts`와 quarantine을 적용했고, handler가 `Retry`로 답해 settlement로 requeue하면 같은 record를 무한히 pause-and-seek해 partition이 영원히 멈췄다. 위치: `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java` `QueuedSettlement.requeue` → 이제 `retryOrQuarantine`으로 같은 예산을 쓴다. 테스트 `KafkaConsumerRegistrarTest.aDeliveryItsHandlerKeepsRequeueingSpendsTheBudgetAndIsQuarantined`.
- **P21-new-2** (고침): pause-and-seek로 다시 읽은 delivery의 `DeliveryMetadata.deliveryAttempt`가 항상 1이었다(retry 헤더는 retry-topic hop에서만 바뀜). handler와 `DefaultRetryDecisionEngine`이 몇 번째 시도인지 알 수 없었다. 같은 파일 `dispatch`에서 registrar가 세는 실패 횟수+1과 헤더 값 중 큰 값을 쓴다. 테스트 `KafkaConsumerRegistrarTest.aReReadDeliveryTellsTheHandlerWhichAttemptItIs`.
- **P21-new-3** (고치지 않음, 문서 drift): `src/messaging/CLAUDE.md` 「Public surface 정책」이 `MessagingPublicSurfaceContractTest`가 규칙을 붙든다고 하지만 그 테스트는 저장소에 없다(`grep` 0). W5 문서 정리 대상.
@@ -513,7 +513,7 @@ Wave 3 라운드 1 결과로 받은 4건(2026-09-28, desktop):
| M-7 | Required | consumer poison message가 지연 없이 무한 재시도(partition 영구 정지) | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): `KafkaConsumerRegistrarTest.aFailedHandlerWaitsOutItsBackoffBeforeThePartitionIsReadAgain` FAIL(즉시 resume) → PASS, `aHandlerThatSpendsItsAttemptBudgetIsQuarantinedAndCommittedPast` FAIL("Expecting Optional to contain 11L but was empty") → PASS, `aProductionDestinationWithoutAQuarantineIsRefused` FAIL(거부 없음) → PASS. offset별 실패 횟수, `BackoffCalculator` 지연(최소 1초), `retry.maxAttempts` 도달 시 quarantine 후 commit, quarantine 없으면 backoff로 계속 재시도, production destination에 quarantine이 없으면 생성자에서 `KAFKA_QUARANTINE_REQUIRED`(`KafkaConsumerRegistrar.java:185,695`), `KafkaQuarantinePublisher.unavailable()`을 단일 인스턴스로. 재시도 시각은 주입 가능한 `InstantSource`. 참고: consumer는 아직 starter가 조립하지 않음(결정 10, Wave 3) | - | requeue에 `BackoffCalculator` 지연, 시도 한도 초과 시 DLQ/park. production에서 quarantine이 `unavailable()`이면 기동 거부 |
| M-8a | Consider | 옛 prefix `backend.messaging` 테스트 fixture yml 2개가 남아 있음(어떤 테스트도 로드 안 함) | 남음 | `src/messaging/messaging-spring-boot-starter/src/test/resources/application-valid.yml:2-3`, `src/messaging/messaging-spring-boot-starter/src/test/resources/application-invalid-ordering.yml:7-8`. `git grep "application-valid\|invalid-ordering" -- src/messaging` 0건 | W5 | 두 파일 삭제 |
| M-8b | Consider | kafka-share·stream-bridge 오류 메시지가 거부되는 옛 prefix를 안내, `app.messaging.experimental.*`는 바인딩만 | 해당 없음(코드 삭제) | 「제거된 코드」 표의 `messaging-kafka-share-experimental` leaf, `messaging-spring-cloud-stream-bridge` leaf, `MessagingSettings.Experimental`·`Bridge` 행 | - | - |
| M-9 | Consider | 구현·사용처 없는 messaging API 타입 7개 (known-open L7/L8) | 남음 | `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/BatchMessageHandler.java`, `.../api/destination/CapabilityRegistry.java`, `.../api/publish/DelayedMessagePublisher.java`, `.../api/settlement/ManualMessageHandler.java`, `.../api/delivery/PauseResumeController.java`, `.../api/delivery/ProcessingGuarantee.java`, `src/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingLifecycle.java` (main 참조 0, `git grep`로 확인) | W3 | 7개 파일 삭제 |
| M-9 | Consider | 구현·사용처 없는 messaging API 타입 7개 (known-open L7/L8) | 해당 없음(코드 삭제) | Wave 3 W3-P21 (Wave 3 라운드 3 커밋): `4ac809e1`에서 7개 삭제(main·test 참조 0 확인). 함께 batch/manual consume 쪽 부속 타입 `BatchMessageDelivery`·`BatchDeliveryMetadata`·`SettlementController`도 참조가 이 타입들뿐이라 삭제 | - | 7개 파일 삭제 |
| M-10 | Consider | Rabbit publish sequence 예약이 원자적이지 않음 | 해당 없음(코드 삭제) | 「제거된 코드」 표의 `messaging-rabbit` leaf 행 | - | - |
| M-11 | Consider | outbox CLAIM이 `ordering_key`를 무시해 같은 key의 뒤 row가 먼저 나갈 수 있음 | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): `OutboxPostgresIT.aNewerRowWaitsWhileAnOlderRowWithTheSameOrderingKeyIsUnfinished`(실제 PostgreSQL) — 새 조건을 끈 SQL로 FAIL(같은 key의 뒤 row까지 3건 claim) → PASS. 최소 수정(기동 거부) 대신 claim 제외를 택함: relay는 기동 때 어떤 destination이 outbox로 나가는지 알 수 없다. CLAIM에 "같은 destination·ordering_key의 더 오래된 PENDING/AMBIGUOUS/IN_FLIGHT row가 없을 것" 조건과 `(created_at, message_id)` 순서(`src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/JdbcOutboxRepository.java:113-140`), 새 migration `V1005__messaging_outbox_ordering_key_index.sql`(messaging 예약 대역, `md5(ordering_key)` partial index). `twoRelaysClaimingConcurrently...` fixture는 서로 다른 key로 변경. `leaseBatch`(main 호출자 없음)에는 적용 안 함 | - | ordered destination을 outbox로 내보내는 조합을 기동 때 거부(최소 수정). 순서 보장이 필요하면 같은 key의 더 오래된 미완료 row가 있을 때 claim에서 제외 |
| N-1 | Critical | FAILED_TERMINAL 뒤 재시도가 claim 없이 PROCEED (= Critical #15) | 완료 | `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/idempotency/GrpcIdempotencyInterceptor.java:109-117` (`reclaimFailed` 성공 시에만 PROCEED), `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/ledger/GrpcOperationLedger.java:53`, `src/grpc/grpc-operation-ledger-jpa/src/main/java/dev/caskeleton/grpc/ledger/JpaGrpcOperationLedger.java:92-96`. 공통 계약 `src/grpc/grpc-core-api/src/testFixtures/java/dev/caskeleton/grpc/api/ledger/GrpcOperationLedgerContract.java` (`aFailedClaimIsReclaimedByARetryOfTheSameRequest`, `aFailedClaimCannotBeCommittedWithoutBeingReclaimed`)을 fake(`InMemoryOperationLedgerContractTest`)와 JPA(`JpaGrpcOperationLedgerContractIT`)가 상속. 커밋 `6d27356e` | - | - |
@@ -1008,24 +1008,24 @@ Wave 3 라운드 1 결과로 받은 4건(2026-09-28, desktop):
| S7-#1a | Required | 선택 불가·SDK 없는 messaging leaf(experimental 4, rabbit 2)와 Debezium | 해당 없음(코드 삭제) | `CS:124-130` | - | - |
| S7-#1b | Required | 쓰는 곳 없는 `schema-avro`·`schema-protobuf`·`cloudevents`·`claim-check`가 기본 build에 | 남음 | 4개 leaf 유지(`CS:133` "leaf는 유지"), main 345·199·228·418줄, main 참조 0, 각 leaf에 README 없음 | W5 | Wave 3 방침(이동 대신 라이브러리로 유지)대로 각 leaf README에 "라이브러리 API — 서비스 leaf가 `implementation`으로 받음"과 SDK 의존을 적음 |
| S7-#1c | Required | starter가 쓰지 않는 cloudevents·claim-check edge, 바인딩만 되는 `Experimental`·`Bridge` 설정 | 완료 | `CS:131`, `CS:133`; `src/messaging/messaging-spring-boot-starter/build.gradle:20-37`에 두 leaf 없음, `6d27356e` | - | - |
| S7-#2 | Required | consume 계약 3개, 조립 0 | 남음 | `MessageHandler.java:14`(main 참조 0), `DefaultDeliveryProcessor.java:40-47`(참조 0), `IdempotentMessageHandler.java:21`; `KafkaConsumerRegistrar`(645줄)·`KafkaBatchConsumerRegistrar`(146줄) main 참조 0, 자동 조립 transport는 발행 전용(`KafkaMessagingTransport.java:89` `KAFKA_CONSUMER_NOT_CONFIGURED`) | W3 | 결정(2026-09-25): Kafka 소비 지원 — `MessageHandler<T>` 하나, starter-kafka가 handler bean이 있으면 consumer 조립, 실제 Kafka lane 테스트 |
| S7-#2 | Required | consume 계약 3개, 조립 0 | 완료 | Wave 3 W3-P21 (Wave 3 라운드 3 커밋): `30f0885a`. **계약:** consume 계약은 `MessageHandler<T>` 하나(`destination()` + `handle`, `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java`). `IdempotentMessageHandler`·`TransactionalMessageAction`·`TransactionalInboxHandler`·`InboxResult` 삭제, 대신 `InboxMessageHandler<T> implements MessageHandler<T>`(`src/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java`). untyped `DefaultDeliveryProcessor`는 typed handler용으로 다시 씀(`src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessor.java`). **조립:** core starter `MessagingConsumeConfiguration`→`MessageConsumers`(handler bean이 있을 때만), starter-kafka `KafkaConsumerConfiguration`(transport의 consumer factory = `KafkaPolledRegistration`, `KafkaConsumerLifecycle`이 `transport.register`로 구독). `KafkaMessagingTransport`는 이제 consumer factory와 함께 만들어져 `KAFKA_CONSUMER_NOT_CONFIGURED`가 조립 경로에서 사라짐. 켜고 끄기: handler bean 있으면 켜짐, `app.messaging.enabled=false`면 전부 없음 — 새 설정 키·env 키 없음. **정책(기존 설계서 §19.2·§24·§25·§26.4를 따름, 없던 부분은 가장 작은 안전한 선택):** offset은 contiguous watermark로 `Success` 뒤(inbox destination이면 inbox transaction commit 뒤) 또는 DLQ 기록 확인 뒤에만 commit, `enable.auto.commit=false` 고정(broker 항목이 `true`면 기동 거부), 새 group은 `auto.offset.reset=earliest`, `isolation.level=read_committed`, group은 destination `consumer.group`(없으면 기동 거부 — inbox 식별자와 같음), `Retry`·예외·timeout은 `retry.max-attempts`까지 partition pause 후 재읽기(backoff 최소 1s), 다 쓰면 DLQ 토픽에 원본 record(+failure 헤더)를 쓰고 확인되면 commit — DLQ 없는 destination(at-most-once만 가능, validator가 at-least-once+DLQ 없음을 이미 거부)은 멈춤, `DeadLetter` 결과는 `DeadLetterOrchestrator`로 DLQ 발행 확인 후 ack, `Reject`는 at-most-once에서만 discard·그 밖은 dead letter, handler 없는 message type·decode 실패는 dead letter, `INBOX_TRANSACTIONAL`이면 handler를 inbox로 감싸고 `IdempotentConsumer` bean 없으면 기동 거부, security `access.consumable`에 없는 destination은 기동 거부. **테스트:** Kafka+PostgreSQL Testcontainers `MessagingKafkaConsumeQualificationTest.aPublishedMessageIsConsumedByTheHandlerBeanAndItsOffsetIsCommitted`·`aRedeliveredMessageIsAppliedOnceThroughThePostgresInbox`(같은 messageId 2회 발행 → projection 1행, handler 1회, committed offset 2)·`aMessageItsHandlerKeepsRetryingIsParkedOnTheDeadLetterTopicOnceItsAttemptsAreSpent` PASS(`:messaging:messaging-spring-boot-starter:integrationTest` 6/6). 새 기능이라 FAIL 단계는 조립 부재(컴파일 오류: `MessageHandler.destination()` 없음·consumer 없음). 단위: `DefaultDeliveryProcessorTest` 11, `InboxMessageHandlerTest` 3, `MessagingConsumeConfigurationTest` 4 PASS. **결함 수정(TDD):** `KafkaConsumerRegistrarTest.aDeliveryItsHandlerKeepsRequeueingSpendsTheBudgetAndIsQuarantined` FAIL(`Expecting actual: [] to contain exactly: [10L]`)→PASS, `aReReadDeliveryTellsTheHandlerWhichAttemptItIs` FAIL(`Expecting actual: [1, 1] to contain exactly: [1, 2]`)→PASS — 아래 P21-new-1·2 | - | 결정(2026-09-25): Kafka 소비 지원 — `MessageHandler<T>` 하나, starter-kafka가 handler bean이 있으면 consumer 조립, 실제 Kafka lane 테스트 |
| S7-#3 | Required | grpc 18 leaf를 9 leaf로 | 완료 | Wave 3 W3-P17 (Wave 3 라운드 1 커밋): `e2397d2f`. registry의 `optional-grpc` leaf 18 → 9: `grpc-core-api`, `grpc-runtime`(policy+server+client+discovery+admin), `grpc-contract`(proto-contract+codegen 자리), `grpc-observability`, `grpc-operation-ledger-jpa`, `grpc-spring-boot-starter`, `grpc-testkit`, `grpc-advanced`(bootstrap+edition+streaming+resilience+diagnostics), `grpc-advanced-compat`. 패키지 이름은 그대로(import 변경 없음). settings는 registry 구동(`OptionalArchitectureRegistrySettingsPlugin`)이라 `src/optional-platforms/settings.gradle` 변경 불필요, build-logic 무변경. 새 edge 없음, 미사용 edge 삭제: grpc-client의 io.grpc(leaf 합병으로 소멸), codegen→proto-contract, edition→core-api/proto-contract/bootstrap, testkit→proto-contract/codegen. starter·grpc-advanced·compat는 grpc-runtime의 versionless io.grpc api를 받으므로 `ca.grpc-platform-module`(gRPC BOM)로 전환 — 새 leaf로 lockfile을 재생성할 때 BOM 없이 `Could not find io.grpc:grpc-api:.`로 실패해서다(기존 lockfile 값과 동일하게 해석됨). `GrpcPackageOwnershipTest` leaf 목록 갱신. lockfile은 `-p optional-platforms resolveAndLockAll --write-locks`로 재생성 | - | policy+server+client+discovery+admin → `grpc-runtime`, proto-contract+codegen → `grpc-contract`, advanced 5개 → `grpc-advanced`, 미사용 edge 삭제 |
| S7-#4 | Required | gate·guard·catalog 같은 governance를 운영 코드로 (≈ N-9) | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): 삭제 커밋 `9b296c7c`(P5 D). 상수 gate·guard·catalog·invariant·testkit·문자열 ArchUnit 흉내 삭제(아래 「제거된 코드」). 전부 main 호출자 0이었다. `GrpcRawApiImportRule`·`GrpcApplicationBoundaryRules`는 자기 테스트의 합성 입력만 검사하고 저장소 코드를 검사하지 않아서 테스트로 옮기지 않고 삭제했다(inbound→outbound 규칙은 app-bootstrap ArchUnit `INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`가 이미 검사). `GrpcResolverSafetyPolicy`는 상수 메서드 2개만 삭제. starter의 항상 통과하던 advanced 격리 검사도 함께 제거 `src/grpc/grpc-spring-boot-starter/src/main/java/dev/caskeleton/grpc/boot/GrpcPlatformStartupValidator.java:41`. 문서 갱신: `src/grpc/CLAUDE.md`, `src/grpc-advanced/CLAUDE.md`, `docs/runbooks/grpc-advanced-capabilities.md`, `docs/compatibility/grpc-advanced-support-matrix.md` | - | 상수 gate·catalog·invariant·testkit 삭제, import 규칙은 ArchUnit 테스트로 |
| S7-#5a | Required | `messaging-outbox-jdbc-postgresql`의 Debezium 4개 | 해당 없음(코드 삭제) | `CS:130` | - | - |
| S7-#5b | Required | 한 leaf가 relay 로직·PG repository·admin journal을 함께 가짐 | 완료 | Wave 3 W3-P18 (Wave 3 라운드 2 커밋): **`messaging-reliability`**(stdlib: `OutboxRelay`·`OutboxRelayWorker`·`OutboxRetryScheduler`·`OutboxEnvelopeFactory`·`OutboxCleanupJob`·`OutboxProperties`·`OutboxRelayReport`, `IdempotentConsumer`·`TransactionalInboxHandler`·`InboxCleanupJob`·`InboxOutcome`·`InboxRetentionPolicy`).<br>**`messaging-reliability-jdbc-postgresql`**(`JdbcOutboxRepository`, `JdbcInboxRepository`, `JdbcAdminOperationJournal`, migration `V1001..V1005`·`V1101`, PG IT 3개).<br>**영향:** 옛 두 leaf는 삭제했다. 패키지명은 그대로라 starter 코드는 바뀌지 않았다. CI lane `integration-main.yml`을 새 경로로 바꿨다.<br>**테스트:** `:messaging:messaging-reliability:test` 47, `:messaging:messaging-reliability-jdbc-postgresql:test` 8, integrationTest 36, starter test 87, integrationTest 3 PASS. | - | `messaging-reliability`(stdlib relay·inbox 로직) + `messaging-reliability-jdbc-postgresql`(Jdbc 3종)으로 재분할 |
| S7-#6a | Required | `PublishResult` 7인자 생성자 직접 호출 | 남음 | 11파일 28회 → 5파일 8회(`KafkaMessagingTransport` 1, `KafkaPublishFailureClassifier` 2, `KafkaPublishMapper` 1, `DefaultMessagePublisher` 2, `MS/PublishResults.java` 2). `PublishResult.java:30`에 정적 factory 없음 | W3 | `PublishResult.rejected/ambiguous/confirmed` 정적 factory 추가 후 8곳 교체 |
| S7-#6b | Required | `PublishEvidence.ambiguous()`를 두고 직접 생성 | 남음 | `MS/PublishResults.java:43-47,57-59` `new PublishEvidence(true, MAY_HAVE_BEEN_TRANSMITTED, false, NONE)` 2회 | W3 | `PublishEvidence.ambiguous()` 사용 |
| S7-#6a | Required | `PublishResult` 7인자 생성자 직접 호출 | 완료 | Wave 3 W3-P21 (Wave 3 라운드 3 커밋): `0f6f3fbb`: `PublishResult.confirmed/rejected/ambiguous` 정적 factory(`src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishResult.java` 하단). main의 `new PublishResult(` 호출은 factory 안 3곳뿐(Kafka transport·classifier·mapper, `DefaultMessagePublisher` 2곳, `OutboxRelay` 1곳 교체). 테스트 `PublishResultTest.theRejectedFactoryReportsNothingWasTransmittedOrRouted`·`theAmbiguousFactoryReportsTheBrokerMayHoldTheMessage`·`theConfirmedFactoryCarriesAcceptanceAndPositionWithoutAFailure` PASS(새 API라 FAIL 단계는 컴파일 오류). 부수 변화: `DefaultMessagePublisher`의 로컬 거부는 routing `UNKNOWN`→`NOT_APPLICABLE`(보내지 않은 메시지는 라우팅 대상이 아님, Kafka 로컬 거부와 같게) | - | `PublishResult.rejected/ambiguous/confirmed` 정적 factory 추가 후 8곳 교체 |
| S7-#6b | Required | `PublishEvidence.ambiguous()`를 두고 직접 생성 | 해당 없음(코드 삭제) | Wave 3 W3-P21 (Wave 3 라운드 3 커밋): 직접 생성 2곳이 있던 starter `PublishResults`는 S7-#9c facade 삭제로 호출자 0이 되어 `0f6f3fbb`에서 삭제. main의 `new PublishEvidence(`는 `PublishEvidence` factory 안뿐 | - | `PublishEvidence.ambiguous()` 사용 |
| S7-#6c | Required | `rejectedLocally` 4벌, `PulsarPreSendRejection`·`NatsPreSendRejection` 중복 | 해당 없음(코드 삭제) | rabbit·pulsar·nats 삭제(`CS:124-129`), 남은 것은 `KafkaMessagingTransport.java:200` 1개 | - | - |
| S7-#7 | Required | envelope ↔ canonical header 변환 3벌 | 해당 없음(코드 삭제) | Rabbit mapper·Debezium router 삭제(`CS:128,130`). 남은 Kafka `KafkaHeaderMapper`(쓰기)·`KafkaDeliveryMapper`(읽기) 한 쌍, `RESERVED_HEADER_FORGED`는 `KafkaHeaderMapper.java:92` 한 곳 | - | - |
| S7-#8 | Consider | outbox port·repository 죽은 표면 | 완료 | Wave 3 W3-P18 (Wave 3 라운드 2 커밋): **삭제:** `OutboxRepository`의 `leaseBatch`, 4인자 `claimBatch`, 3인자 `markAmbiguous`(`src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRepository.java:43`, `:57`만 남음). `JdbcOutboxRepository`의 LEASE SQL, `*Unfenced` 4개, `update` helper, 손으로 쓴 JSON(`toJson`/`fromJson`/`escape`/`unescape`).<br>**header 저장:** `jsonb_object(?::text[])`로 쓰고 `jsonb_each_text`로 읽는다(`src/messaging/messaging-reliability-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/JdbcOutboxRepository.java:59`, `:77-78`).<br>**TDD:** `OutboxPostgresIT.aHeaderValueEndingInABackslashRoundTripsWithoutSwallowingTheNextHeader`(`OutboxPostgresIT.java:612`)가 먼저 FAIL했다("map entries not expected: x-path=C:\exports\"") → 수정 후 PASS. integrationTest 36/36.<br>**그대로 둔 것:** purge 오버로드(1차 M-6)는 손대지 않았다. | - | 메서드 7개 삭제, header JSON은 Jackson 또는 `jsonb_each_text` (purge 오버로드는 1차 M-6) |
| S7-#9a | Consider | starter 550줄 god config | 남음 | `MS/MessagingCoreAutoConfiguration.java` 549줄, `@Bean` 28 | W3 | config/validation, publish pipeline, observability 세 configuration으로 분리 |
| S7-#9b | Consider | broker 중립 core starter에 broker 전용 필드 union | 남음 | Rabbit 필드는 삭제(`CS:235`), `MS/BrokerSettings.java:32-44`에 Kafka 전용 필드(`bootstrapServers`, `enableIdempotence`, `acks` 등) 남음 | W3 | Kafka 필드는 starter-kafka가 자기 settings record로 바인딩 |
| S7-#9c | Consider | 외부 사용 0인 Blocking/Reactive/Batch facade와 `reactor-core` api 노출 | 남음 | `MS/Default{Blocking,Reactive,Batch}MessagePublisher.java`, `MS/ReactiveMessagePublisher.java`(합계 398줄) starter 밖 main 참조 0; `src/messaging/messaging-spring-boot-starter/build.gradle:46` `api 'io.projectreactor:reactor-core'` | W3 | facade 삭제(또는 reactor `compileOnly`) |
| S7-#10 | Consider | 미사용 API 타입 (1차 M-9 목록 외) | 남음 | `MessagingException` 서브클래스 24개 중 13개 main 참조 0(Authentication, BrokerUnavailable, Consumer, DeadLetter, HandlerTimeout, HeaderRejected, PublishAmbiguous, PublishRejected, Redrive, RetryExhausted, Routing, Settlement, SettlementUnknown); `MessageHandler`·`KafkaTopologyInspector`·`ReliableMessagePublisher`·`InboxRecord` 참조 0. `RabbitRequestReply`만 삭제로 소멸 | W3 | 삭제(consumer 쪽 타입은 S7-#2 결정에 따름) |
| S7-#11 | Consider | `MessagingCapabilities` 위치 boolean 12개 | 남음 | record boolean 12개, `KafkaMessagingTransport.java:62-64` `new MessagingCapabilities(true, …, true)`; 생성 11곳 → 4곳 | W3 | `EnumSet<Capability>`로, 읽지 않는 flag 삭제 |
| S7-#12 | Consider | messaging API leaf 병합(core-api+schema-api, admin-api+admin-runtime) | 남음 | 두 쌍 모두 별도 leaf(`MJ`). 기본 build messaging leaf 27 → 21(삭제분만) | W3 | 두 쌍 병합 |
| S7-#9a | Consider | starter 550줄 god config | 완료 | Wave 3 W3-P21 (Wave 3 라운드 3 커밋): `06bde64f`: `MessagingCoreAutoConfiguration`(549줄, bean 28)을 `MessagingValidationConfiguration`(설정 컴파일·검증, bean 10), `MessagingPublishConfiguration`(publish pipeline·runtime·shutdown, bean 11 + helper), `MessagingObservabilityConfiguration`(redactor·cardinality·metrics·endpoint, bean 4)으로 분리. `MessagingCoreAutoConfiguration`은 세 개를 `@Import`하는 진입점(23줄)이라 기존 조립·테스트 그대로. starter `check` PASS | - | config/validation, publish pipeline, observability 세 configuration으로 분리 |
| S7-#9b | Consider | broker 중립 core starter에 broker 전용 필드 union | 완료 | Wave 3 W3-P21 (Wave 3 라운드 3 커밋): `06bde64f`: `BrokerSettings`(core starter)에서 Kafka 필드 7개(`bootstrapServers`, `enableIdempotence`, `acks`, `maxInFlightRequestsPerConnection`, `deliveryTimeout`, `enableAutoCommit`, `consumerGroup`) 삭제. starter-kafka `KafkaBrokerSettings`(`src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerSettings.java`)가 같은 `app.messaging.brokers.<name>` 항목을 `Binder`로 바인딩, `KafkaBrokerCatalog` bean. bootstrap-servers 필수 검증도 core compiler에서 이리로 이동. `MessagingConfigurationKeyValidator`는 `MessagingProviderSelection.PROVIDER_BROKER_SETTINGS`(family→설정 record 클래스 이름)로 family 키를 허용 — record가 classpath에 없으면 neutral 키만. 설정 키·env 키 변경 없음. 테스트 `MessagingConfigurationBindingTest.aKafkaBrokerWithoutAnAddressIsRefusedByTheKafkaStarterNamingTheKey` PASS, 문서 YAML 바인딩 테스트 `theDocumentedConfigurationBindsToTheProfilesThePlatformUses` PASS | - | Kafka 필드는 starter-kafka가 자기 settings record로 바인딩 |
| S7-#9c | Consider | 외부 사용 0인 Blocking/Reactive/Batch facade와 `reactor-core` api 노출 | 해당 없음(코드 삭제) | Wave 3 W3-P21 (Wave 3 라운드 3 커밋): `4ac809e1`: `Default{Blocking,Reactive,Batch}MessagePublisher`·`ReactiveMessagePublisher`와 bean 3개, core-api `BlockingMessagePublisher`·`BatchMessagePublisher`·`BatchPublish{Options,ItemResult,Result}`(구현이 facade뿐), 테스트 3개 삭제. `reactor-core` api·`reactor-test` 삭제, lockfile 재생성(starter, starter-kafka, adapter:outbound:messaging-kafka) | - | facade 삭제(또는 reactor `compileOnly`) |
| S7-#10 | Consider | 미사용 API 타입 (1차 M-9 목록 외) | 해당 없음(코드 삭제) | Wave 3 W3-P21 (Wave 3 라운드 3 커밋): `4ac809e1`: 예외 13개(Authentication, BrokerUnavailable, Consumer, DeadLetter, HandlerTimeout, HeaderRejected, PublishAmbiguous, PublishRejected, Redrive, RetryExhausted, Routing, Settlement, SettlementUnknown — 삭제 전 main·test 참조 0), `KafkaTopologyInspector`, `ReliableMessagePublisher`, `InboxRecord` 삭제. `MessageHandler`는 S7-#2 결정으로 유지 | - | 삭제(consumer 쪽 타입은 S7-#2 결정에 따름) |
| S7-#11 | Consider | `MessagingCapabilities` 위치 boolean 12개 | 완료 | Wave 3 W3-P21 (Wave 3 라운드 3 커밋): `0f6f3fbb`: `MessagingCapabilities(Set<Capability> supported)` + `supports(Capability)`·`of(...)`·`none()`. 읽히던 flag 3개만 남김(`ORDERED_STREAM`—`DefaultRetryDecisionEngine`, `DELAYED_DELIVERY`—같은 곳, `DEDUPLICATED_PUBLISH`—`DefaultMessagePublisher.requireSupportedOptions`). 나머지 9개는 main에서 읽는 곳 0이라 삭제. Kafka 선언은 `MessagingCapabilities.of(ORDERED_STREAM)`(`KafkaMessagingTransport.java` `CAPABILITIES`). 테스트 `DestinationCapabilityTest.aCapabilitySetSupportsExactlyWhatWasNamedAndIgnoresLaterChangesToTheInput` PASS, `RetryDecisionEngineTest` PASS | - | `EnumSet<Capability>`로, 읽지 않는 flag 삭제 |
| S7-#12 | Consider | messaging API leaf 병합(core-api+schema-api, admin-api+admin-runtime) | 완료 | Wave 3 W3-P21 (Wave 3 라운드 3 커밋): `409ce47a`: `messaging-schema-api` → `messaging-core-api`(패키지 `dev.caskeleton.messaging.schema` 유지), `messaging-admin-api`+`messaging-admin-runtime` → `messaging-admin`(패키지 `admin`·`admin.runtime` 유지). `modules.json`: 두 id 삭제, `messaging-admin-api`→`messaging-admin` 개명, 모든 edge 치환. `messaging-admin`의 edge는 실제 import 기준 `messaging-core-api`, `messaging-observability`(implementation)만 — 선언만 있던 policy·schema-api·transport-spi·security edge 삭제. `architectureCheck` PASS, messaging 전 leaf `check` PASS, lockfile 재생성 | - | 두 쌍 병합 |
| S7-#13 | Consider | `.proto` regex 파서·Buf 규칙 재구현 | 완료 | Wave 3 W3-P17 (Wave 3 라운드 1 커밋): `e2397d2f`. 소유자 결정 18대로 `GrpcProtoContractValidator`(regex 파서)·`GrpcProtoStyleManifest`·`GrpcProtoRuleViolation`·`grpc-codegen` 전체(Buf 규칙 재구현, codegen manifest, descriptor/consumer fixture) 삭제. `src/grpc/grpc-contract/build.gradle`: `com.google.protobuf` 플러그인(카탈로그 `protobufPlugin = "0.10.0"`, `libs.plugins.protobuf`), protoc·runtime은 `protobufGrpc`(3.25.5, gRPC BOM 1.68.1과 같은 줄) — `libs.protoc`, `libs.protobuf.java.grpc` 추가. 생성 코드는 Spotless target·Checkstyle·Error Prone에서 이 leaf만 제외, SpotBugs(qualityCheck)는 통과. protoc tool locator 설정은 locking 해제(정확 버전 좌표라 lock이 같은 값을 반복). `src/grpc/grpc-contract/buf.yaml`(STANDARD lint, FILE breaking). CI: `.github/workflows/ci-quality-gates.yml` job `grpc-proto-buf`(`bufbuild/buf-action` SHA 고정, `buf lint` + baseline에 모듈이 있으면 `buf breaking`, 없으면 notice 후 skip). 로컬 검증: buf 1.73.0 바이너리를 scratchpad에 받아 `buf lint`·`buf build`·`buf breaking --against '../../../.git#ref=e2397d2f,subdir=src/grpc/grpc-contract'` 모두 exit 0. 테스트 `GrpcContractGeneratedCodeTest`(생성 message wire 왕복·explicit presence, 패키지 disjoint). testkit `GrpcStableReleaseGate.evaluate`의 schema 입력은 `PublishDecision` 대신 `List<String> schemaBreakages`(buf breaking 결과). ADR-GRPC-002를 superseded로 표시, 설계서에 변경 주석. **통합 시 확인 필요:** 새 job은 추가만 했고 `release-gate`의 `needs`에는 넣지 않았다(기존 job 수정 금지 지시) — required로 만들려면 오케스트레이터가 `release-gate.needs`에 `grpc-proto-buf`를 추가해야 한다 | - | 결정(2026-09-25): protobuf Gradle 플러그인(protoc) + Buf(CI)로 전환, 자체 `.proto` 파서·Buf 규칙 재구현 삭제 |
| S7-#14 | Consider | 패키지·leaf 이름 불일치, 등급 용어 4개 | 남음 | `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/{resilience,streaming}`(leaf `grpc-advanced-resilience`/`-streaming`과 이름 겹침); `CapabilityTier`(messaging-policy), `CompatibilityMatrix`(messaging-testkit), `GrpcCapabilityGrade`(grpc-advanced-bootstrap), `GrpcEvidenceGrade`(grpc-testkit) | W3 | S7-#3 병합 때 패키지 = leaf 이름으로 맞추고 등급 용어 하나로 |
| S7-#14 | Consider | 패키지·leaf 이름 불일치, 등급 용어 4개 | 완료 | Wave 3 W3-P21 (Wave 3 라운드 3 커밋): `faa40c7e`. **패키지·leaf 이름:** 행이 든 불일치(`grpc-policy`의 `grpc.{resilience,streaming}` 패키지 vs leaf `grpc-advanced-resilience/-streaming`)는 S7-#3(`e2397d2f`)에서 leaf가 `grpc-runtime`·`grpc-advanced`로 합쳐지며 사라졌다 — 지금 advanced 쪽 패키지는 `dev.caskeleton.grpc.advanced.{resilience,streaming,…}`로 leaf 이름과 같다(`src/grpc-advanced/grpc-advanced/src/main/java/dev/caskeleton/grpc/advanced/`). grpc-runtime 패키지를 `grpc.runtime.*`로 옮기는 것은 import 전체 변경이라 하지 않음(현황표 수정 방향도 S7-#3 병합 시점 기준). **등급 용어:** 4개가 실은 세 개념이다 — API 표면 단계, 지원(검증) 수준, 증거 종류. messaging에서 "Tier"는 API 표면(M1–M3) 하나로: `CapabilityTier` → `ApiTier`(`src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ApiTier.java`). 지원 수준은 gRPC와 같은 "Grade"로: `CompatibilityMatrix.Tier` → `CompatibilityMatrix.SupportGrade`(record 필드 `tier`→`grade`). `GrpcCapabilityGrade`·`GrpcEvidenceGrade`는 이미 Grade라 유지. vendored messaging과 grpc는 서로 타입을 공유할 수 없어 enum 하나로 합치지 않고 용어만 맞췄다. 설정 키 `destinations.*.tier`와 값 `M1`은 그대로. messaging 전 leaf `check` PASS | - | S7-#3 병합 때 패키지 = leaf 이름으로 맞추고 등급 용어 하나로 |
| S7-#15a | Consider | 리뷰 ID 주석 | 남음 | `MSG-INT-003` 9곳 그대로(예: `MS/MessagingCoreAutoConfiguration.java:370,442,480`, `DeclaredDestinationAccess.java:11`, `RegisteredMessageCodecs.java:12`) | W5 | ID 삭제, 이유만 남김 |
| S7-#15b | Consider | 이력 주석·inline FQN | 남음 | "used to/no longer" 58 → 52줄; inline FQN 약 218줄(`KafkaConsumerRegistrar` 34) | W5 | 이력 문장 삭제, OpenRewrite `ShortenFullyQualifiedTypeReferences` |
| S7-#16a | Nit | `dev.caskeleton.messaging.autoconfigure` 패키지가 여러 leaf에 걸침 | 남음 | 3 → 2개 leaf(starter 26파일, starter-kafka 1파일), 원인 package-private `StartupProfileValidation` | W5 | starter-kafka를 자기 패키지로, `StartupProfileValidation`은 public 호출 경로로 |
@@ -1209,3 +1209,6 @@ Wave 1–2 구현 묶음(`P1`–`P13`)이 작업 중 찾은 결함과 통합 검
| P23-new-3 | 발견 | `app-bootstrap/build.gradle` 알림 선택 줄 주석이 persistence-jpa 줄을 함께 풀라고 함(composition이 직접 가져옴). | 완료 | Wave 3 라운드 3 통합: 주석 수정 | - | - |
| ORCH-new-2 | 발견 | `NotificationPayloadAtRestContractTest`가 저장소 소스·migration을 읽지만 test inputs를 선언하지 않아(`notification/build.gradle:98`이 필요 없다고 주장) 파일이 옮겨져도 up-to-date로 건너뜀. P23 worktree에서 통과, main 통합에서 실패(옛 `persistence-jpa` 경로·`build/` 경합 walk). | 남음 | 경로와 walk 범위는 통합 때 수정(`src/main/java`만) | W4 | 읽는 파일을 test `inputs`로 선언(CLAUDE.md build-logic 규칙) |
| ORCH-new-3 | 발견 | `web-advanced` `WebStreamingSoakIT.concurrent arrivals never exceed the node's ceiling`가 부하 중 `expected: 1000 but was: 1001`로 실패, 단독 3회 통과 — 상한을 1 넘는 실제 경합일 수 있다. | 남음 | Wave 3 라운드 3 P27 통합 `ci`(2026-09-29) | W2 | 재현(반복·부하)으로 경합 여부 판정, 경합이면 admission 카운터 수정. P19 |
| P21-new-1 | 발견 | handler가 `Retry`를 답하면 Kafka consumer가 시도 횟수를 세지 않아 partition이 영구히 멈췄다. | 완료 | Wave 3 P21: 예외와 같은 시도 예산·격리 사용 | - | - |
| P21-new-2 | 발견 | 다시 읽은 delivery가 항상 `deliveryAttempt=1`을 보고했다. | 완료 | Wave 3 P21 | - | - |
| P21-new-3 | 발견 | `src/messaging/CLAUDE.md`가 `MessagingPublicSurfaceContractTest`를 인용 — 테스트는 app-bootstrap에 있다(P21은 없다고 보고). 통합 때 이 테스트가 P21 변경(reactive facade 삭제, leaf 병합, starter-kafka 공개 consumer seam)을 반영하지 못해 실패 → 기대값 수정, starter-kafka에 `api kafka-clients` 선언. | 남음 | Wave 3 라운드 3 통합 | W5 | messaging CLAUDE.md의 테스트 위치 문구를 app-bootstrap 경로로 |
@@ -223,18 +223,19 @@ W1·W2 잔여 21행(Wave 2.5)은 P14로 1라운드에서 함께 처리한다. W1
| P24 | 2 | fileserver·object storage 구조 | `D-7d` `D-7e` `D-8a` `D-8b` `D-8c` `S1-#6a` `S1-#6b` `S1-#12` `S1-#13` `S1-#17a` `S1-#17b` `S1-#18b` `S1-lead-4` `S4-#11a` `S4-#11b` `S4-#12` `S4-lead-2` `S5-#10` `S6-lead-5` |
| P25 | 2 | core 죽은 표면 · web · GraphQL · sample 구조(NEW-10d) | `A-2c` `A-4b` `A-5b` `A-5c` `A-10c` `I-5b` `I-6b` `I-8d` `J-7` `J-10d` `K-11b` `X1-#6f` `S1-#15b` `S5-#7a` `S6-#8` `S6-#10a` `S6-#10b` `S6-#10c` `S6-#10d` `S6-#11a` `S6-#13` `NEW-9b` `NEW-10d` `NEW-12` |
| P26 | 2 | HTTP client · JPA 구조 | `E-6b` `H-4b` `H-7a` `S2-#3b` `S3-#2b` `S3-#6` `S3-#7` `S3-#8b` `S3-#10` `S3-lead-5` `S6-#3c` `S6-#3d` |
| P19 | 3 | 3-D 공통 유틸·tenant·context·caller 트랜잭션 guard | `D-8d` `E-3b` `I-1c` `J-12` `X1-지도-caller 트랜잭션 guard` `X1-지도-Backoff 계산식` `X1-#1c` `X1-#4` `X1-#9` `X1-#10b` `X2-P1-4b` `X2-P1-5` `X2-P1-7` `X2-P2-4` `X2-P2-5` `X2-P2-6a` `S1-#11` `S1-lead-2` `S2-lead-3` `S5-lead-3` `P9-new-4` `P9-new-5` |
| P19 | 3 | 3-D 공통 유틸·tenant·context·caller 트랜잭션 guard | `D-8d` `E-3b` `I-1c` `J-12` `X1-지도-caller 트랜잭션 guard` `X1-지도-Backoff 계산식` `X1-#1c` `X1-#4` `X1-#9` `X1-#10b` `X2-P1-4b` `X2-P1-5` `X2-P1-7` `X2-P2-4` `X2-P2-5` `X2-P2-6a` `S1-#11` `S1-lead-2` `S2-lead-3` `S5-lead-3` `P9-new-4` `P9-new-5` `E-6b`(P26 잔여) `P16-new-5` `ORCH-new-3` |
| P21 | 3 | messaging 플랫폼: Kafka 소비(결정 10)·API 정리 | `M-9` `S7-#2` `S7-#6a` `S7-#6b` `S7-#9a` `S7-#9b` `S7-#9c` `S7-#10` `S7-#11` `S7-#12` `S7-#14` |
| P22 | 3 | Redis 구조 · startup rule | `G-4i` `G-6b` `G-7a` `G-7c` `G-7d` `G-7e` `G-8` `X1-지도-lock / lease / fencing` `S1-#15c` `S3-#3a` `S3-#3b` `S3-#4b` `S3-#5` `S3-#9` `S6-#2c` `S6-#3a` |
| P23 | 3 | notification: SES → sesv2(결정 17), `persistence-notification` 추출, SRP | `S1-#4` `S1-#9` `S1-#10b` `S2-#1b` `S2-#6c` `S2-#8a` `S2-#13b` `S4-#3c` `S4-#4b` `S4-#9` `S4-#14b` `S4-#15` `S4-lead-3` `S4-lead-5` |
| P27 | 3 | 빌드 잔여(결정 28·29·31): O3-5 나머지(`ca.release-provenance`·auxiliary → `jvm-test-suite`), messaging 카드 검증 leaf 테스트로, cosign 서명, `INTERNAL_ERROR` retryable=false, persistence-fileserver `ca.api-surface` | `BUILD-결론-1` `BUILD-O3-5` `X1-#7a` `X1-지도-readiness…` `BUILD-계획-C` `P15-new-3` `P16-new-6` |
| P28 | 3 | 로컬 보안 파일시스템 primitive 공용화(보안 민감 재작성, P24에서 분리) + fileserver 잔여 | `S4-lead-2` `P24-new-2` `P25-new-2` `P24-new-3` `S6-#10a` `S1-#6b` `S1-#18b`(결정 32) `S2-#8a` `S2-#13b` `P23-new-1` `P23-new-2` |
| P29 | 4 | 빌드 잔여 2: auxiliary 레인 → Gradle `jvm-test-suite`(P27 중단분, WIP 패치 보관), build-logic 줄 수 판정 | `BUILD-O3-5` `BUILD-결론-1` |
| P20 | 4 | 3-B 설정 prefix `app.*`(결정 16), strict 바인딩 | `X2-P1-3c` `S3-lead-2` `S3-lead-4` `S6-#14` `P11-new-1` |
- [x] 라운드 1: P14 · P15 · P16 · P17 → 통합·검증·커밋 (2026-09-28, `9fdb0af4`·`c4a066df`·라운드 1 마무리 커밋)
- [ ] 라운드 2: P18 · P24 · P25 · P26 → 통합·검증·커밋
- [x] 라운드 2: P18 · P24 · P25 · P26 → 통합·검증·커밋 (2026-09-28~29, `4fb7943b`·`64a83918`·`25de288a`·`423a29c4`)
- [ ] 라운드 3: P19 · P21 · P22 · P23 · P27 · P28 → 통합·검증·커밋 (P23은 P18과 겹치지 않아 라운드 2 자리에서 먼저 시작)
- [ ] 라운드 4: P20 → 통합 → Wave 종료 검증 → 현황표·「제거된 코드」 갱신 → 커밋 `review-followup Wave 3`
- [ ] 라운드 4: P20 · P29 → 통합 → Wave 종료 검증 → 현황표·「제거된 코드」 갱신 → 커밋 `review-followup Wave 3`
## Wave 4 — 테스트 규칙 (시작할 때 상세 Task 추가)
@@ -35,5 +35,5 @@ dependencies {
// 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-schema-api')
testImplementation project(':messaging:messaging-core-api')
}
@@ -45,7 +45,6 @@ io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotatio
io.micrometer:micrometer-commons:1.16.7=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-core:1.16.7=runtimeClasspath,testRuntimeClasspath
io.micrometer:micrometer-observation:1.16.7=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.projectreactor:reactor-core:3.8.7=runtimeClasspath,testRuntimeClasspath
jakarta.activation:jakarta.activation-api:2.1.4=testCompileClasspath,testRuntimeClasspath
jakarta.annotation:jakarta.annotation-api:3.0.0=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
jakarta.xml.bind:jakarta.xml.bind-api:4.0.5=testCompileClasspath,testRuntimeClasspath
@@ -112,7 +111,6 @@ org.ow2.asm:asm-util:9.10.1=spotbugs
org.ow2.asm:asm:9.10.1=spotbugs
org.ow2.asm:asm:9.7.1=testCompileClasspath,testRuntimeClasspath
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
org.reactivestreams:reactive-streams:1.0.4=runtimeClasspath,testRuntimeClasspath
org.reflections:reflections:0.10.2=checkstyle
org.skyscreamer:jsonassert:1.5.3=testCompileClasspath,testRuntimeClasspath
org.slf4j:jul-to-slf4j:2.0.18=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
+2 -2
View File
@@ -23,8 +23,8 @@ Package root: `dev.caskeleton.adapter.outbound.messaging`.
- Allowed dependency edges come only from the module's
`src/config/architecture/modules.json` entry.
- No inbound DTO/controller, persistence repository/entity, bootstrap, or sample dependency.
- The canonical platform bridge may depend only on `messaging-core-api` and
`messaging-schema-api`; do not import `messaging-runtime-core`, transport SPI implementations, or
- The canonical platform bridge may depend only on `messaging-core-api` (which also holds the
`schema` package); do not import `messaging-runtime-core`, transport SPI implementations, or
broker SDK types under `platformbridge/`.
- There is one publication path: `OutboxMessagePublishAdapter` → `IntegrationEventPublishPort` →
the platform bridge. The legacy `KafkaSender` / `MessageBroker` R0 seam and the fail-open
@@ -8,7 +8,6 @@ dependencies {
implementation project(':shared-contract')
implementation project(':adapter:outbound:support')
implementation project(':messaging:messaging-core-api')
implementation project(':messaging:messaging-schema-api')
implementation 'org.springframework.boot:spring-boot-autoconfigure'
implementation 'org.springframework.boot:spring-boot-starter-json'
@@ -96,7 +96,7 @@ class MessagingPublicSurfaceContractTest {
assertThat(leaves)
.as("a scan that found no leaf would report every violation as absent")
.hasSizeGreaterThan(20);
.hasSizeGreaterThan(15);
assertThat(
exposedLibraries(
leaves.stream().filter(isNamed("messaging-kafka")).findFirst().orElseThrow()))
@@ -123,8 +123,8 @@ class MessagingPublicSurfaceContractTest {
assertThat(reachable)
.as(
"an empty closure would satisfy the assertion below without proving anything; the "
+ "metrics registry and the reactive facade are exported on purpose")
.contains("io.micrometer:micrometer-core", "io.projectreactor:reactor-core");
+ "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 "
+16 -54
View File
@@ -169,8 +169,7 @@
"application-core",
"shared-contract",
"adapter-outbound-support",
"messaging-core-api",
"messaging-schema-api"
"messaging-core-api"
]
},
{
@@ -374,21 +373,12 @@
"source_path": "src/messaging/messaging-core-api",
"allowed_dependencies": []
},
{
"id": "messaging-schema-api",
"gradle_path": ":messaging:messaging-schema-api",
"source_path": "src/messaging/messaging-schema-api",
"allowed_dependencies": [
"messaging-core-api"
]
},
{
"id": "messaging-schema-json",
"gradle_path": ":messaging:messaging-schema-json",
"source_path": "src/messaging/messaging-schema-json",
"allowed_dependencies": [
"messaging-core-api",
"messaging-schema-api"
"messaging-core-api"
]
},
{
@@ -396,8 +386,7 @@
"gradle_path": ":messaging:messaging-schema-avro",
"source_path": "src/messaging/messaging-schema-avro",
"allowed_dependencies": [
"messaging-core-api",
"messaging-schema-api"
"messaging-core-api"
]
},
{
@@ -405,8 +394,7 @@
"gradle_path": ":messaging:messaging-schema-protobuf",
"source_path": "src/messaging/messaging-schema-protobuf",
"allowed_dependencies": [
"messaging-core-api",
"messaging-schema-api"
"messaging-core-api"
]
},
{
@@ -414,8 +402,7 @@
"gradle_path": ":messaging:messaging-cloudevents",
"source_path": "src/messaging/messaging-cloudevents",
"allowed_dependencies": [
"messaging-core-api",
"messaging-schema-api"
"messaging-core-api"
]
},
{
@@ -423,8 +410,7 @@
"gradle_path": ":messaging:messaging-policy",
"source_path": "src/messaging/messaging-policy",
"allowed_dependencies": [
"messaging-core-api",
"messaging-schema-api"
"messaging-core-api"
]
},
{
@@ -433,7 +419,6 @@
"source_path": "src/messaging/messaging-transport-spi",
"allowed_dependencies": [
"messaging-core-api",
"messaging-schema-api",
"messaging-policy"
]
},
@@ -443,7 +428,6 @@
"source_path": "src/messaging/messaging-runtime-core",
"allowed_dependencies": [
"messaging-core-api",
"messaging-schema-api",
"messaging-policy",
"messaging-transport-spi",
"messaging-security",
@@ -472,12 +456,11 @@
"source_path": "src/messaging/messaging-kafka",
"allowed_dependencies": [
"messaging-core-api",
"messaging-schema-api",
"messaging-policy",
"messaging-transport-spi",
"messaging-observability",
"messaging-security",
"messaging-admin-api"
"messaging-admin"
]
},
{
@@ -494,8 +477,7 @@
"source_path": "src/messaging/messaging-reliability",
"allowed_dependencies": [
"messaging-core-api",
"messaging-reliability-api",
"messaging-schema-api"
"messaging-reliability-api"
]
},
{
@@ -505,9 +487,8 @@
"allowed_dependencies": [
"messaging-core-api",
"messaging-reliability-api",
"messaging-admin-api",
"messaging-policy",
"messaging-schema-api"
"messaging-admin",
"messaging-policy"
]
},
{
@@ -520,27 +501,12 @@
]
},
{
"id": "messaging-admin-api",
"gradle_path": ":messaging:messaging-admin-api",
"source_path": "src/messaging/messaging-admin-api",
"id": "messaging-admin",
"gradle_path": ":messaging:messaging-admin",
"source_path": "src/messaging/messaging-admin",
"allowed_dependencies": [
"messaging-core-api",
"messaging-policy",
"messaging-schema-api"
]
},
{
"id": "messaging-admin-runtime",
"gradle_path": ":messaging:messaging-admin-runtime",
"source_path": "src/messaging/messaging-admin-runtime",
"allowed_dependencies": [
"messaging-core-api",
"messaging-policy",
"messaging-admin-api",
"messaging-transport-spi",
"messaging-security",
"messaging-observability",
"messaging-schema-api"
"messaging-observability"
]
},
{
@@ -548,8 +514,7 @@
"gradle_path": ":messaging:messaging-spring-boot-starter",
"source_path": "src/messaging/messaging-spring-boot-starter",
"allowed_dependencies": [
"messaging-admin-api",
"messaging-admin-runtime",
"messaging-admin",
"messaging-core-api",
"messaging-observability",
"messaging-policy",
@@ -557,7 +522,6 @@
"messaging-reliability-api",
"messaging-reliability-jdbc-postgresql",
"messaging-runtime-core",
"messaging-schema-api",
"messaging-schema-json",
"messaging-security",
"messaging-transport-spi"
@@ -570,12 +534,11 @@
"allowed_dependencies": [
"messaging-spring-boot-starter",
"messaging-kafka",
"messaging-admin-api",
"messaging-admin",
"messaging-core-api",
"messaging-observability",
"messaging-policy",
"messaging-reliability-api",
"messaging-schema-api",
"messaging-security",
"messaging-transport-spi"
]
@@ -586,7 +549,6 @@
"source_path": "src/messaging/messaging-testkit",
"allowed_dependencies": [
"messaging-core-api",
"messaging-schema-api",
"messaging-policy",
"messaging-transport-spi"
]
+4 -4
View File
@@ -14,9 +14,9 @@ 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`, `reliability` | framework-free 실행 로직 | Micrometer는 `observability`에서만. 나머지는 stdlib |
| `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. 여기서만 |
@@ -35,7 +35,7 @@ JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMES
- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이
숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다.
(`kafka-clients`, `cloudevents-api`, `micrometer-core`, `avro`,
`protobuf-java`, `reactor-core`가 이 규칙으로 `api`다.)
`protobuf-java`가 이 규칙으로 `api`다.)
- 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을
`implementation`으로 내린 것이, JSON codec이 `ObjectMapper`를 private으로만 쓰고 Jackson을
`implementation`으로 둔 것이 그 예다.
@@ -72,7 +72,7 @@ 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는 끝났다(2026-09-28, 소유자 결정 7).** application의 outbox append는 canonical
@@ -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.
//
@@ -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();
}
}
@@ -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()));
}
}
}
@@ -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);
}
@@ -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.
*
@@ -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);
}
@@ -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
}
@@ -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);
}
@@ -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"));
}
}
@@ -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);
}
}
@@ -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);
}
}
@@ -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);
}
}
@@ -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);
}
}
@@ -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);
}
}
@@ -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);
}
}
@@ -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);
}
}
@@ -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);
}
}
@@ -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);
}
}
@@ -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);
}
}
@@ -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);
}
}
@@ -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);
}
}
@@ -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);
}
}
@@ -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);
}
@@ -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");
}
}
}
@@ -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);
}
}
@@ -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);
}
}
@@ -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);
}
@@ -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);
}
@@ -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.
*
@@ -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);
}
@@ -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