From 486d85a60331a9846ca4d8867283606a1d3e62fe Mon Sep 17 00:00:00 2001 From: donghyeon-ka Date: Tue, 29 Sep 2026 13:29:46 +0900 Subject: [PATCH] =?UTF-8?q?review-followup=20Wave=203=20=EB=9D=BC=EC=9A=B4?= =?UTF-8?q?=EB=93=9C=203(P21):=20messaging=20=ED=94=8C=EB=9E=AB=ED=8F=BC?= =?UTF-8?q?=20=E2=80=94=20Kafka=20=EC=86=8C=EB=B9=84(MessageHandler=20?= =?UTF-8?q?=ED=95=98=EB=82=98),=20API=20=EC=A0=95=EB=A6=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 결정 10: consume 계약을 `MessageHandler` 하나로, 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) --- docs/capability-status.md | 18 + docs/messaging/outbox-inbox.md | 18 + .../W3-P21.md | 66 ++ .../2026-09-25-review-followup-status.md | 25 +- .../plans/2026-09-25-review-followup.md | 7 +- .../outbound/messaging-kafka/build.gradle | 2 +- .../outbound/messaging-kafka/gradle.lockfile | 2 - src/adapter/outbound/messaging/CLAUDE.md | 4 +- src/adapter/outbound/messaging/build.gradle | 1 - .../MessagingPublicSurfaceContractTest.java | 6 +- src/config/architecture/modules.json | 70 +-- src/messaging/CLAUDE.md | 8 +- .../messaging-admin-api/build.gradle | 8 - .../messaging-admin-api/gradle.lockfile | 84 --- .../messaging-admin-runtime/build.gradle | 12 - src/messaging/messaging-admin/build.gradle | 14 + .../gradle.lockfile | 0 .../messaging/admin/AdminApproval.java | 0 .../admin/AdminOperationJournal.java | 0 .../messaging/admin/AdminOperationLease.java | 0 .../messaging/admin/AdminOperationRecord.java | 0 .../messaging/admin/AdminOperationState.java | 0 .../messaging/admin/ApprovalGrant.java | 0 .../messaging/admin/ApprovalVerifier.java | 0 .../messaging/admin/ApprovedRedrivePlan.java | 0 .../messaging/admin/ApprovedReplayPlan.java | 0 .../messaging/admin/DestinationTopology.java | 0 .../messaging/admin/DestructiveOperation.java | 0 .../admin/DestructiveOperationGuard.java | 0 .../messaging/admin/HmacApprovalVerifier.java | 0 .../messaging/admin/PlanDigest.java | 0 .../messaging/admin/RedrivePlan.java | 0 .../messaging/admin/RedriveRequest.java | 0 .../messaging/admin/RedriveResult.java | 0 .../messaging/admin/ReplayPlan.java | 0 .../messaging/admin/ReplayRequest.java | 0 .../messaging/admin/ReplayResult.java | 0 .../messaging/admin/TopologyIssue.java | 0 .../admin/TopologyManagementMode.java | 0 .../messaging/admin/TopologyManifest.java | 0 .../admin/TopologyValidationReport.java | 0 .../messaging/admin/VerifiedApproval.java | 0 .../runtime/BrokerTopologyInspector.java | 0 .../runtime/CompositeTopologyValidator.java | 0 .../runtime/DefaultMessagingAdminService.java | 0 .../runtime/DestructiveMessagingAdmin.java | 0 .../InMemoryAdminOperationJournal.java | 0 .../admin/runtime/MessagingAdminService.java | 0 .../admin/runtime/RedriveReport.java | 0 .../admin/runtime/RedriveService.java | 0 .../messaging/admin/runtime/ReplayReport.java | 0 .../admin/runtime/ReplayService.java | 0 .../runtime/TopologyValidationRuntime.java | 0 .../admin/runtime/TopologyValidator.java | 0 .../admin/DestructiveOperationGuardTest.java | 0 .../runtime/AdminOperationJournalTest.java | 0 .../admin/runtime/ApprovalForgeryTest.java | 0 .../runtime/ApprovedPlanExecutionTest.java | 0 .../admin/runtime/RedriveResumptionTest.java | 0 .../admin/runtime/ReplayServiceTest.java | 0 .../TopologyValidationRuntimeTest.java | 0 .../admin/runtime/TopologyValidatorTest.java | 0 .../messaging-cloudevents/build.gradle | 1 - .../api/delivery/BatchDeliveryMetadata.java | 46 -- .../api/delivery/BatchMessageDelivery.java | 29 - .../api/delivery/BatchMessageHandler.java | 24 - .../api/delivery/MessageHandler.java | 21 +- .../api/delivery/PauseResumeController.java | 33 - .../api/delivery/ProcessingGuarantee.java | 11 - .../api/destination/CapabilityRegistry.java | 15 - .../destination/MessagingCapabilities.java | 82 ++- .../error/MessageAuthenticationException.java | 49 -- .../MessageBrokerUnavailableException.java | 49 -- .../api/error/MessageConsumerException.java | 49 -- .../api/error/MessageDeadLetterException.java | 54 -- .../error/MessageHandlerTimeoutException.java | 54 -- .../error/MessageHeaderRejectedException.java | 49 -- .../MessagePublishAmbiguousException.java | 54 -- .../MessagePublishRejectedException.java | 53 -- .../api/error/MessageRedriveException.java | 49 -- .../error/MessageRetryExhaustedException.java | 49 -- .../api/error/MessageRoutingException.java | 49 -- .../api/error/MessageSettlementException.java | 49 -- .../MessageSettlementUnknownException.java | 53 -- .../api/publish/BatchMessagePublisher.java | 25 - .../api/publish/BatchPublishItemResult.java | 27 - .../api/publish/BatchPublishOptions.java | 42 -- .../api/publish/BatchPublishResult.java | 44 -- .../api/publish/BlockingMessagePublisher.java | 30 - .../api/publish/DelayedMessagePublisher.java | 28 - .../messaging/api/publish/PublishResult.java | 64 ++ .../api/settlement/ManualMessageHandler.java | 25 - .../api/settlement/SettlementController.java | 50 -- .../messaging/schema/BoundedByteSink.java | 0 .../messaging/schema/EncodedMessage.java | 0 .../schema/EncodedMessagePublisher.java | 0 .../messaging/schema/MessageCodec.java | 0 .../schema/MessageCodecRegistry.java | 0 .../messaging/schema/MessageContractKey.java | 0 .../schema/RawBytesMessageCodec.java | 0 .../messaging/schema/SchemaCompatibility.java | 0 .../schema/SchemaCompatibilityValidator.java | 0 .../messaging/schema/SchemaReference.java | 0 .../messaging/schema/SchemaRegistry.java | 0 .../DestinationCapabilityTest.java | 21 +- .../api/publish/PublishResultTest.java | 44 ++ .../messaging/schema/BoundedByteSinkTest.java | 0 .../schema/RawBytesMessageCodecTest.java | 0 .../SchemaCompatibilityValidatorTest.java | 0 src/messaging/messaging-kafka/build.gradle | 7 +- .../kafka/KafkaBatchConsumerRegistrar.java | 146 ----- .../kafka/KafkaConsumerRegistrar.java | 72 ++- .../kafka/KafkaMessagingTransport.java | 22 +- .../kafka/KafkaPublishFailureClassifier.java | 21 +- .../messaging/kafka/KafkaPublishMapper.java | 11 +- .../kafka/KafkaTopologyInspector.java | 45 -- .../kafka/KafkaConsumerRegistrarTest.java | 73 +++ .../messaging/kafka/KafkaContractHarness.java | 4 +- src/messaging/messaging-policy/build.gradle | 1 - .../caskeleton/messaging/policy/ApiTier.java | 30 + .../messaging/policy/CapabilityTier.java | 21 - .../policy/DefaultRetryDecisionEngine.java | 13 +- .../messaging/policy/DestinationProfile.java | 2 +- .../policy/DestinationProfileValidator.java | 2 +- .../DestinationProfileValidatorTest.java | 4 +- .../policy/RetryDecisionEngineTest.java | 9 +- .../reliability/IdempotentMessageHandler.java | 33 - .../messaging/reliability/InboxRecord.java | 27 - .../messaging/reliability/InboxResult.java | 45 -- .../reliability/ReliableMessagePublisher.java | 27 - .../TransactionalMessageAction.java | 29 - .../build.gradle | 2 +- .../gradle.lockfile | 5 + .../messaging-reliability/build.gradle | 1 - .../messaging/inbox/InboxMessageHandler.java | 129 ++++ .../inbox/TransactionalInboxHandler.java | 104 ---- .../messaging/outbox/OutboxRelay.java | 20 +- .../inbox/InboxMessageHandlerTest.java | 179 ++++++ .../messaging/inbox/InboxOperationsTest.java | 10 - .../messaging/outbox/OutboxRelayTest.java | 4 +- .../messaging-runtime-core/build.gradle | 1 - .../runtime/DefaultDeliveryProcessor.java | 272 ++++++-- .../runtime/DefaultMessagePublisher.java | 30 +- .../runtime/DefaultDeliveryProcessorTest.java | 341 ++++++++-- .../messaging/runtime/RuntimeFixtures.java | 4 +- .../messaging-schema-api/build.gradle | 7 - .../messaging-schema-api/gradle.lockfile | 84 --- .../messaging-schema-avro/build.gradle | 1 - .../messaging-schema-json/build.gradle | 1 - .../messaging-schema-protobuf/build.gradle | 1 - .../build.gradle | 2 + .../gradle.lockfile | 2 - .../autoconfigure/KafkaBrokerCatalog.java | 37 ++ .../autoconfigure/KafkaBrokerSettings.java | 86 +++ .../KafkaConsumerConfiguration.java | 165 +++++ .../autoconfigure/KafkaConsumerLifecycle.java | 69 ++ .../KafkaDeadLetterQuarantine.java | 65 ++ .../KafkaMessagingAutoConfiguration.java | 105 ++-- .../KafkaPolledRegistration.java | 169 +++++ .../build.gradle | 17 +- .../gradle.lockfile | 12 +- ...essagingKafkaConsumeQualificationTest.java | 460 ++++++++++++++ ...ssagingLiveRoundTripQualificationTest.java | 2 +- .../autoconfigure/BrokerSettings.java | 30 +- .../DefaultBatchMessagePublisher.java | 262 -------- .../DefaultBlockingMessagePublisher.java | 65 -- .../DefaultReactiveMessagePublisher.java | 43 -- .../autoconfigure/DestinationSettings.java | 4 +- .../autoconfigure/MessageConsumers.java | 46 ++ .../MessagingConfigurationCompiler.java | 21 +- .../MessagingConfigurationKeyValidator.java | 33 +- .../MessagingConsumeConfiguration.java | 151 +++++ .../MessagingCoreAutoConfiguration.java | 587 +----------------- .../MessagingObservabilityConfiguration.java | 77 +++ .../MessagingProviderSelection.java | 10 + .../MessagingPublishConfiguration.java | 304 +++++++++ ...MessagingReliabilityAutoConfiguration.java | 16 - .../MessagingValidationConfiguration.java | 194 ++++++ .../autoconfigure/PublishResults.java | 71 --- .../ReactiveMessagePublisher.java | 32 - .../autoconfigure/BatchPublisherTest.java | 328 ---------- .../autoconfigure/BlockingFacadeTest.java | 148 ----- .../KafkaProducerConfigTest.java | 1 + .../KafkaProducerSecurityTest.java | 1 + .../MessagingAutoConfigurationTest.java | 7 +- .../MessagingConfigurationBindingTest.java | 27 +- .../MessagingConsumeConfigurationTest.java | 117 ++++ .../autoconfigure/MessagingEndpointTest.java | 4 +- .../autoconfigure/ReactiveFacadeTest.java | 162 ----- src/messaging/messaging-testkit/build.gradle | 1 - .../testkit/CompatibilityMatrix.java | 20 +- .../testkit/CompatibilityMatrixTest.java | 20 +- .../testkit/CrossBrokerContractSuite.java | 4 +- .../MessagingDocumentationContractTest.java | 4 +- .../messaging-transport-spi/build.gradle | 1 - .../transport/MessagingLifecycle.java | 67 -- .../transport/MessagingLifecycleTest.java | 59 -- 197 files changed, 3526 insertions(+), 4089 deletions(-) create mode 100644 docs/reviews/2026-09-25-review-followup-results/W3-P21.md delete mode 100644 src/messaging/messaging-admin-api/build.gradle delete mode 100644 src/messaging/messaging-admin-api/gradle.lockfile delete mode 100644 src/messaging/messaging-admin-runtime/build.gradle create mode 100644 src/messaging/messaging-admin/build.gradle rename src/messaging/{messaging-admin-runtime => messaging-admin}/gradle.lockfile (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/AdminApproval.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/AdminOperationJournal.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/AdminOperationLease.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/AdminOperationRecord.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/AdminOperationState.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/ApprovalGrant.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/ApprovalVerifier.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/ApprovedRedrivePlan.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/ApprovedReplayPlan.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/DestinationTopology.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperation.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperationGuard.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/HmacApprovalVerifier.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/PlanDigest.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/RedrivePlan.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/RedriveRequest.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/RedriveResult.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/ReplayPlan.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/ReplayRequest.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/ReplayResult.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/TopologyIssue.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/TopologyManagementMode.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/TopologyManifest.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/TopologyValidationReport.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/VerifiedApproval.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/runtime/BrokerTopologyInspector.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/runtime/CompositeTopologyValidator.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/runtime/DefaultMessagingAdminService.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/runtime/DestructiveMessagingAdmin.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/runtime/InMemoryAdminOperationJournal.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/runtime/MessagingAdminService.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveReport.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveService.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/runtime/ReplayReport.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/runtime/ReplayService.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntime.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/main/java/dev/caskeleton/messaging/admin/runtime/TopologyValidator.java (100%) rename src/messaging/{messaging-admin-api => messaging-admin}/src/test/java/dev/caskeleton/messaging/admin/DestructiveOperationGuardTest.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/test/java/dev/caskeleton/messaging/admin/runtime/AdminOperationJournalTest.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovalForgeryTest.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovedPlanExecutionTest.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/test/java/dev/caskeleton/messaging/admin/runtime/RedriveResumptionTest.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/test/java/dev/caskeleton/messaging/admin/runtime/ReplayServiceTest.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntimeTest.java (100%) rename src/messaging/{messaging-admin-runtime => messaging-admin}/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidatorTest.java (100%) delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/BatchDeliveryMetadata.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/BatchMessageDelivery.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/BatchMessageHandler.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/PauseResumeController.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/ProcessingGuarantee.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/CapabilityRegistry.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageAuthenticationException.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageBrokerUnavailableException.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageConsumerException.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageDeadLetterException.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageHandlerTimeoutException.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageHeaderRejectedException.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagePublishAmbiguousException.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagePublishRejectedException.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageRedriveException.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageRetryExhaustedException.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageRoutingException.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSettlementException.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSettlementUnknownException.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BatchMessagePublisher.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BatchPublishItemResult.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BatchPublishOptions.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BatchPublishResult.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BlockingMessagePublisher.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/DelayedMessagePublisher.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/ManualMessageHandler.java delete mode 100644 src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementController.java rename src/messaging/{messaging-schema-api => messaging-core-api}/src/main/java/dev/caskeleton/messaging/schema/BoundedByteSink.java (100%) rename src/messaging/{messaging-schema-api => messaging-core-api}/src/main/java/dev/caskeleton/messaging/schema/EncodedMessage.java (100%) rename src/messaging/{messaging-schema-api => messaging-core-api}/src/main/java/dev/caskeleton/messaging/schema/EncodedMessagePublisher.java (100%) rename src/messaging/{messaging-schema-api => messaging-core-api}/src/main/java/dev/caskeleton/messaging/schema/MessageCodec.java (100%) rename src/messaging/{messaging-schema-api => messaging-core-api}/src/main/java/dev/caskeleton/messaging/schema/MessageCodecRegistry.java (100%) rename src/messaging/{messaging-schema-api => messaging-core-api}/src/main/java/dev/caskeleton/messaging/schema/MessageContractKey.java (100%) rename src/messaging/{messaging-schema-api => messaging-core-api}/src/main/java/dev/caskeleton/messaging/schema/RawBytesMessageCodec.java (100%) rename src/messaging/{messaging-schema-api => messaging-core-api}/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibility.java (100%) rename src/messaging/{messaging-schema-api => messaging-core-api}/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidator.java (100%) rename src/messaging/{messaging-schema-api => messaging-core-api}/src/main/java/dev/caskeleton/messaging/schema/SchemaReference.java (100%) rename src/messaging/{messaging-schema-api => messaging-core-api}/src/main/java/dev/caskeleton/messaging/schema/SchemaRegistry.java (100%) rename src/messaging/{messaging-schema-api => messaging-core-api}/src/test/java/dev/caskeleton/messaging/schema/BoundedByteSinkTest.java (100%) rename src/messaging/{messaging-schema-api => messaging-core-api}/src/test/java/dev/caskeleton/messaging/schema/RawBytesMessageCodecTest.java (100%) rename src/messaging/{messaging-schema-api => messaging-core-api}/src/test/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidatorTest.java (100%) delete mode 100644 src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaBatchConsumerRegistrar.java delete mode 100644 src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTopologyInspector.java create mode 100644 src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ApiTier.java delete mode 100644 src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/CapabilityTier.java delete mode 100644 src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/IdempotentMessageHandler.java delete mode 100644 src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/InboxRecord.java delete mode 100644 src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/InboxResult.java delete mode 100644 src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/ReliableMessagePublisher.java delete mode 100644 src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/TransactionalMessageAction.java create mode 100644 src/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java delete mode 100644 src/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/TransactionalInboxHandler.java create mode 100644 src/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/InboxMessageHandlerTest.java delete mode 100644 src/messaging/messaging-schema-api/build.gradle delete mode 100644 src/messaging/messaging-schema-api/gradle.lockfile create mode 100644 src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerCatalog.java create mode 100644 src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerSettings.java create mode 100644 src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaConsumerConfiguration.java create mode 100644 src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaConsumerLifecycle.java create mode 100644 src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantine.java create mode 100644 src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaPolledRegistration.java create mode 100644 src/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingKafkaConsumeQualificationTest.java delete mode 100644 src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultBatchMessagePublisher.java delete mode 100644 src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultBlockingMessagePublisher.java delete mode 100644 src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultReactiveMessagePublisher.java create mode 100644 src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageConsumers.java create mode 100644 src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfiguration.java create mode 100644 src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingObservabilityConfiguration.java create mode 100644 src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPublishConfiguration.java create mode 100644 src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingValidationConfiguration.java delete mode 100644 src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/PublishResults.java delete mode 100644 src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/ReactiveMessagePublisher.java delete mode 100644 src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/BatchPublisherTest.java delete mode 100644 src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/BlockingFacadeTest.java create mode 100644 src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfigurationTest.java delete mode 100644 src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/ReactiveFacadeTest.java delete mode 100644 src/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingLifecycle.java delete mode 100644 src/messaging/messaging-transport-spi/src/test/java/dev/caskeleton/messaging/transport/MessagingLifecycleTest.java diff --git a/docs/capability-status.md b/docs/capability-status.md index e00a2a3f..a5d2aac8 100644 --- a/docs/capability-status.md +++ b/docs/capability-status.md @@ -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` 하나로(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, 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) | diff --git a/docs/messaging/outbox-inbox.md b/docs/messaging/outbox-inbox.md index d71c30fc..bf68398f 100644 --- a/docs/messaging/outbox-inbox.md +++ b/docs/messaging/outbox-inbox.md @@ -108,6 +108,24 @@ transactions.inTransaction(() -> { 별도 transaction으로 예약하면 Inbox가 닫으려던 바로 그 창이 다시 열린다. +### 소비와 연결 (소유자 결정 10) + +consume 계약은 `MessageHandler` 하나다. handler를 bean으로 등록하면 `messaging-spring-boot-starter-kafka`가 +그 handler가 가리키는 destination마다 Kafka consumer를 연다(`app.messaging.enabled=false`면 없다). + +- destination profile이 `guarantees.external-side-effect: INBOX_TRANSACTIONAL`이면 platform이 handler를 + `InboxMessageHandler`로 감싼다. 예약과 handler의 쓰기가 같은 transaction에서 commit되고, 이미 예약된 + message는 handler를 부르지 않고 `Success`로 settle한다. 이 경우 애플리케이션이 `IdempotentConsumer` + bean(inbox repository + transaction runner)을 둬야 하며, 없으면 기동이 실패한다. +- inbox의 consumer 식별자와 Kafka `group.id`는 destination의 `consumer.group`이다. 없으면 기동이 실패한다. +- offset은 handler가 `Success`로 답하고 (inbox destination이면) 그 transaction이 commit된 뒤에만, 또는 + DLQ 토픽 기록이 확인된 뒤에만 넘어간다. auto-commit은 쓰지 않는다. +- `Retry`·예외·timeout은 `retry.max-attempts`까지 partition을 멈추고 다시 읽으며, 다 쓰면 DLQ 토픽에 + 원본 record를 남기고 넘어간다. DLQ가 없는 destination(at-most-once)은 넘어가지 않고 멈춘다. +- `Reject`는 at-most-once destination에서만 버리고, 그 밖에서는 dead letter로 보낸다. + +실제 왕복·중복 제거·DLQ는 `MessagingKafkaConsumeQualificationTest`(Kafka + PostgreSQL Testcontainers)가 확인한다. + ### 복합 키 `PRIMARY KEY (message_id, consumer_id)`. diff --git a/docs/reviews/2026-09-25-review-followup-results/W3-P21.md b/docs/reviews/2026-09-25-review-followup-results/W3-P21.md new file mode 100644 index 00000000..3ebc3b3a --- /dev/null +++ b/docs/reviews/2026-09-25-review-followup-results/W3-P21.md @@ -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` 하나(`destination()` + `handle`, `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java`). `IdempotentMessageHandler`·`TransactionalMessageAction`·`TransactionalInboxHandler`·`InboxResult` 삭제, 대신 `InboxMessageHandler implements MessageHandler`(`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 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.` 항목을 `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` 하나로(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, 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 문서 정리 대상. diff --git a/docs/reviews/2026-09-25-review-followup-status.md b/docs/reviews/2026-09-25-review-followup-status.md index 3b6508f9..705d91ba 100644 --- a/docs/reviews/2026-09-25-review-followup-status.md +++ b/docs/reviews/2026-09-25-review-followup-status.md @@ -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` 하나, starter-kafka가 handler bean이 있으면 consumer 조립, 실제 Kafka lane 테스트 | +| S7-#2 | Required | consume 계약 3개, 조립 0 | 완료 | Wave 3 W3-P21 (Wave 3 라운드 3 커밋): `30f0885a`. **계약:** consume 계약은 `MessageHandler` 하나(`destination()` + `handle`, `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java`). `IdempotentMessageHandler`·`TransactionalMessageAction`·`TransactionalInboxHandler`·`InboxResult` 삭제, 대신 `InboxMessageHandler implements MessageHandler`(`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` 하나, 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`).
**`messaging-reliability-jdbc-postgresql`**(`JdbcOutboxRepository`, `JdbcInboxRepository`, `JdbcAdminOperationJournal`, migration `V1001..V1005`·`V1101`, PG IT 3개).
**영향:** 옛 두 leaf는 삭제했다. 패키지명은 그대로라 starter 코드는 바뀌지 않았다. CI lane `integration-main.yml`을 새 경로로 바꿨다.
**테스트:** `: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`).
**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`).
**TDD:** `OutboxPostgresIT.aHeaderValueEndingInABackslashRoundTripsWithoutSwallowingTheNextHeader`(`OutboxPostgresIT.java:612`)가 먼저 FAIL했다("map entries not expected: x-path=C:\exports\"") → 수정 후 PASS. integrationTest 36/36.
**그대로 둔 것:** 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`로, 읽지 않는 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.` 항목을 `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 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`로, 읽지 않는 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 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 경로로 | diff --git a/docs/superpowers/plans/2026-09-25-review-followup.md b/docs/superpowers/plans/2026-09-25-review-followup.md index 67ca2fb6..0acb088f 100644 --- a/docs/superpowers/plans/2026-09-25-review-followup.md +++ b/docs/superpowers/plans/2026-09-25-review-followup.md @@ -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 추가) diff --git a/src/adapter/outbound/messaging-kafka/build.gradle b/src/adapter/outbound/messaging-kafka/build.gradle index fc7eafed..c7323e5f 100644 --- a/src/adapter/outbound/messaging-kafka/build.gradle +++ b/src/adapter/outbound/messaging-kafka/build.gradle @@ -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') } diff --git a/src/adapter/outbound/messaging-kafka/gradle.lockfile b/src/adapter/outbound/messaging-kafka/gradle.lockfile index 64aa98cd..7cbc1e5c 100644 --- a/src/adapter/outbound/messaging-kafka/gradle.lockfile +++ b/src/adapter/outbound/messaging-kafka/gradle.lockfile @@ -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 diff --git a/src/adapter/outbound/messaging/CLAUDE.md b/src/adapter/outbound/messaging/CLAUDE.md index 5bd7540d..025499f2 100644 --- a/src/adapter/outbound/messaging/CLAUDE.md +++ b/src/adapter/outbound/messaging/CLAUDE.md @@ -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 diff --git a/src/adapter/outbound/messaging/build.gradle b/src/adapter/outbound/messaging/build.gradle index c5cc2ed0..c7e3fdd7 100644 --- a/src/adapter/outbound/messaging/build.gradle +++ b/src/adapter/outbound/messaging/build.gradle @@ -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' diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingPublicSurfaceContractTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingPublicSurfaceContractTest.java index 8cd6a3cf..00756f7d 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingPublicSurfaceContractTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingPublicSurfaceContractTest.java @@ -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 " diff --git a/src/config/architecture/modules.json b/src/config/architecture/modules.json index 8d887c2e..8c3b06a6 100644 --- a/src/config/architecture/modules.json +++ b/src/config/architecture/modules.json @@ -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" ] diff --git a/src/messaging/CLAUDE.md b/src/messaging/CLAUDE.md index 57e6932e..14c58e87 100644 --- a/src/messaging/CLAUDE.md +++ b/src/messaging/CLAUDE.md @@ -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 diff --git a/src/messaging/messaging-admin-api/build.gradle b/src/messaging/messaging-admin-api/build.gradle deleted file mode 100644 index 55c8be51..00000000 --- a/src/messaging/messaging-admin-api/build.gradle +++ /dev/null @@ -1,8 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') - api project(':messaging:messaging-policy') -} diff --git a/src/messaging/messaging-admin-api/gradle.lockfile b/src/messaging/messaging-admin-api/gradle.lockfile deleted file mode 100644 index e2c95854..00000000 --- a/src/messaging/messaging-admin-api/gradle.lockfile +++ /dev/null @@ -1,84 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.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 diff --git a/src/messaging/messaging-admin-runtime/build.gradle b/src/messaging/messaging-admin-runtime/build.gradle deleted file mode 100644 index feb5781b..00000000 --- a/src/messaging/messaging-admin-runtime/build.gradle +++ /dev/null @@ -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') -} diff --git a/src/messaging/messaging-admin/build.gradle b/src/messaging/messaging-admin/build.gradle new file mode 100644 index 00000000..a6b6ce55 --- /dev/null +++ b/src/messaging/messaging-admin/build.gradle @@ -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') +} diff --git a/src/messaging/messaging-admin-runtime/gradle.lockfile b/src/messaging/messaging-admin/gradle.lockfile similarity index 100% rename from src/messaging/messaging-admin-runtime/gradle.lockfile rename to src/messaging/messaging-admin/gradle.lockfile diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/AdminApproval.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminApproval.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/AdminApproval.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminApproval.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/AdminOperationJournal.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationJournal.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/AdminOperationJournal.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationJournal.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/AdminOperationLease.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationLease.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/AdminOperationLease.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationLease.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/AdminOperationRecord.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationRecord.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/AdminOperationRecord.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationRecord.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/AdminOperationState.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationState.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/AdminOperationState.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationState.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/ApprovalGrant.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovalGrant.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/ApprovalGrant.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovalGrant.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/ApprovalVerifier.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovalVerifier.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/ApprovalVerifier.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovalVerifier.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/ApprovedRedrivePlan.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovedRedrivePlan.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/ApprovedRedrivePlan.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovedRedrivePlan.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/ApprovedReplayPlan.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovedReplayPlan.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/ApprovedReplayPlan.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovedReplayPlan.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/DestinationTopology.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestinationTopology.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/DestinationTopology.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestinationTopology.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperation.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperation.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperation.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperation.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperationGuard.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperationGuard.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperationGuard.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperationGuard.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/HmacApprovalVerifier.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/HmacApprovalVerifier.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/HmacApprovalVerifier.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/HmacApprovalVerifier.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/PlanDigest.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/PlanDigest.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/PlanDigest.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/PlanDigest.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/RedrivePlan.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedrivePlan.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/RedrivePlan.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedrivePlan.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/RedriveRequest.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedriveRequest.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/RedriveRequest.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedriveRequest.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/RedriveResult.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedriveResult.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/RedriveResult.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedriveResult.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/ReplayPlan.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayPlan.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/ReplayPlan.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayPlan.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/ReplayRequest.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayRequest.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/ReplayRequest.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayRequest.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/ReplayResult.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayResult.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/ReplayResult.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayResult.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/TopologyIssue.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyIssue.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/TopologyIssue.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyIssue.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/TopologyManagementMode.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyManagementMode.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/TopologyManagementMode.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyManagementMode.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/TopologyManifest.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyManifest.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/TopologyManifest.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyManifest.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/TopologyValidationReport.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyValidationReport.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/TopologyValidationReport.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyValidationReport.java diff --git a/src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/VerifiedApproval.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/VerifiedApproval.java similarity index 100% rename from src/messaging/messaging-admin-api/src/main/java/dev/caskeleton/messaging/admin/VerifiedApproval.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/VerifiedApproval.java diff --git a/src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/BrokerTopologyInspector.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/BrokerTopologyInspector.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/BrokerTopologyInspector.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/BrokerTopologyInspector.java diff --git a/src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/CompositeTopologyValidator.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/CompositeTopologyValidator.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/CompositeTopologyValidator.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/CompositeTopologyValidator.java diff --git a/src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/DefaultMessagingAdminService.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/DefaultMessagingAdminService.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/DefaultMessagingAdminService.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/DefaultMessagingAdminService.java diff --git a/src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/DestructiveMessagingAdmin.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/DestructiveMessagingAdmin.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/DestructiveMessagingAdmin.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/DestructiveMessagingAdmin.java diff --git a/src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/InMemoryAdminOperationJournal.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/InMemoryAdminOperationJournal.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/InMemoryAdminOperationJournal.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/InMemoryAdminOperationJournal.java diff --git a/src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/MessagingAdminService.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/MessagingAdminService.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/MessagingAdminService.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/MessagingAdminService.java diff --git a/src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveReport.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveReport.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveReport.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveReport.java diff --git a/src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveService.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveService.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveService.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveService.java diff --git a/src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/ReplayReport.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/ReplayReport.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/ReplayReport.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/ReplayReport.java diff --git a/src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/ReplayService.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/ReplayService.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/ReplayService.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/ReplayService.java diff --git a/src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntime.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntime.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntime.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntime.java diff --git a/src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/TopologyValidator.java b/src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/TopologyValidator.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/main/java/dev/caskeleton/messaging/admin/runtime/TopologyValidator.java rename to src/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/TopologyValidator.java diff --git a/src/messaging/messaging-admin-api/src/test/java/dev/caskeleton/messaging/admin/DestructiveOperationGuardTest.java b/src/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/DestructiveOperationGuardTest.java similarity index 100% rename from src/messaging/messaging-admin-api/src/test/java/dev/caskeleton/messaging/admin/DestructiveOperationGuardTest.java rename to src/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/DestructiveOperationGuardTest.java diff --git a/src/messaging/messaging-admin-runtime/src/test/java/dev/caskeleton/messaging/admin/runtime/AdminOperationJournalTest.java b/src/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/AdminOperationJournalTest.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/test/java/dev/caskeleton/messaging/admin/runtime/AdminOperationJournalTest.java rename to src/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/AdminOperationJournalTest.java diff --git a/src/messaging/messaging-admin-runtime/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovalForgeryTest.java b/src/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovalForgeryTest.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovalForgeryTest.java rename to src/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovalForgeryTest.java diff --git a/src/messaging/messaging-admin-runtime/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovedPlanExecutionTest.java b/src/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovedPlanExecutionTest.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovedPlanExecutionTest.java rename to src/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovedPlanExecutionTest.java diff --git a/src/messaging/messaging-admin-runtime/src/test/java/dev/caskeleton/messaging/admin/runtime/RedriveResumptionTest.java b/src/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/RedriveResumptionTest.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/test/java/dev/caskeleton/messaging/admin/runtime/RedriveResumptionTest.java rename to src/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/RedriveResumptionTest.java diff --git a/src/messaging/messaging-admin-runtime/src/test/java/dev/caskeleton/messaging/admin/runtime/ReplayServiceTest.java b/src/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ReplayServiceTest.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/test/java/dev/caskeleton/messaging/admin/runtime/ReplayServiceTest.java rename to src/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ReplayServiceTest.java diff --git a/src/messaging/messaging-admin-runtime/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntimeTest.java b/src/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntimeTest.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntimeTest.java rename to src/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidationRuntimeTest.java diff --git a/src/messaging/messaging-admin-runtime/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidatorTest.java b/src/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidatorTest.java similarity index 100% rename from src/messaging/messaging-admin-runtime/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidatorTest.java rename to src/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/TopologyValidatorTest.java diff --git a/src/messaging/messaging-cloudevents/build.gradle b/src/messaging/messaging-cloudevents/build.gradle index b65cf72d..80f04d9c 100644 --- a/src/messaging/messaging-cloudevents/build.gradle +++ b/src/messaging/messaging-cloudevents/build.gradle @@ -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. // diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/BatchDeliveryMetadata.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/BatchDeliveryMetadata.java deleted file mode 100644 index 61b9ae7e..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/BatchDeliveryMetadata.java +++ /dev/null @@ -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. - * - *

{@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 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(); - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/BatchMessageDelivery.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/BatchMessageDelivery.java deleted file mode 100644 index 54c035c8..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/BatchMessageDelivery.java +++ /dev/null @@ -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 the payload type - * @param deliveries the individual deliveries, in broker order - * @param metadata batch-wide facts - */ -public record BatchMessageDelivery( - List> 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())); - } - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/BatchMessageHandler.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/BatchMessageHandler.java deleted file mode 100644 index 655e920f..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/BatchMessageHandler.java +++ /dev/null @@ -1,24 +0,0 @@ -package dev.caskeleton.messaging.api.delivery; - -import java.util.concurrent.CompletionStage; - -/** - * The M2 batch consume entry point. - * - *

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 the payload type - */ -public interface BatchMessageHandler { - - /** - * Handles one delivered batch. - * - * @param batch the batch to handle - * @return a stage completing with the outcome for the whole batch - */ - CompletionStage handle(BatchMessageDelivery batch); -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java index 4fc54b16..0abdc895 100644 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java +++ b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java @@ -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. * *

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. + * + *

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

A destination may carry several message types; each type has at most one handler. + * + * @return what this handler consumes + */ + MessageDestination destination(); + /** * Handles one delivery. * diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/PauseResumeController.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/PauseResumeController.java deleted file mode 100644 index 5c862382..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/PauseResumeController.java +++ /dev/null @@ -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. - * - *

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 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 resume(DestinationName destination, String scope); -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/ProcessingGuarantee.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/ProcessingGuarantee.java deleted file mode 100644 index f6f537de..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/ProcessingGuarantee.java +++ /dev/null @@ -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 -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/CapabilityRegistry.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/CapabilityRegistry.java deleted file mode 100644 index b4628f5b..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/CapabilityRegistry.java +++ /dev/null @@ -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); -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/MessagingCapabilities.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/MessagingCapabilities.java index fce026ca..44cc6c58 100644 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/MessagingCapabilities.java +++ b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/MessagingCapabilities.java @@ -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 + *

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 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")); } } diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageAuthenticationException.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageAuthenticationException.java deleted file mode 100644 index c7bc1e86..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageAuthenticationException.java +++ /dev/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); - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageBrokerUnavailableException.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageBrokerUnavailableException.java deleted file mode 100644 index 65a96407..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageBrokerUnavailableException.java +++ /dev/null @@ -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); - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageConsumerException.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageConsumerException.java deleted file mode 100644 index 3b3b0953..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageConsumerException.java +++ /dev/null @@ -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); - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageDeadLetterException.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageDeadLetterException.java deleted file mode 100644 index 210acd70..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageDeadLetterException.java +++ /dev/null @@ -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. - * - *

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); - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageHandlerTimeoutException.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageHandlerTimeoutException.java deleted file mode 100644 index 9632b7f8..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageHandlerTimeoutException.java +++ /dev/null @@ -1,54 +0,0 @@ -package dev.caskeleton.messaging.api.error; - -import java.io.Serial; -import java.util.Optional; - -/** - * The handler exceeded its timeout. - * - *

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); - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageHeaderRejectedException.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageHeaderRejectedException.java deleted file mode 100644 index 7730c351..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageHeaderRejectedException.java +++ /dev/null @@ -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); - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagePublishAmbiguousException.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagePublishAmbiguousException.java deleted file mode 100644 index 26af714e..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagePublishAmbiguousException.java +++ /dev/null @@ -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. - * - *

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); - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagePublishRejectedException.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagePublishRejectedException.java deleted file mode 100644 index 6f913b10..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagePublishRejectedException.java +++ /dev/null @@ -1,53 +0,0 @@ -package dev.caskeleton.messaging.api.error; - -import java.io.Serial; -import java.util.Optional; - -/** - * The broker definitively refused the publish. - * - *

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); - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageRedriveException.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageRedriveException.java deleted file mode 100644 index 9d4b6578..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageRedriveException.java +++ /dev/null @@ -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); - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageRetryExhaustedException.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageRetryExhaustedException.java deleted file mode 100644 index 2ffea59a..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageRetryExhaustedException.java +++ /dev/null @@ -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); - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageRoutingException.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageRoutingException.java deleted file mode 100644 index c5ea68fd..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageRoutingException.java +++ /dev/null @@ -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); - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSettlementException.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSettlementException.java deleted file mode 100644 index 63cd72b8..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSettlementException.java +++ /dev/null @@ -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); - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSettlementUnknownException.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSettlementUnknownException.java deleted file mode 100644 index 27072f1a..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSettlementUnknownException.java +++ /dev/null @@ -1,53 +0,0 @@ -package dev.caskeleton.messaging.api.error; - -import java.io.Serial; -import java.util.Optional; - -/** - * Settlement was sent but not confirmed. - * - *

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); - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BatchMessagePublisher.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BatchMessagePublisher.java deleted file mode 100644 index 6a568245..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BatchMessagePublisher.java +++ /dev/null @@ -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. - * - *

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 publish( - List> requests, BatchPublishOptions options); -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BatchPublishItemResult.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BatchPublishItemResult.java deleted file mode 100644 index a275061b..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BatchPublishItemResult.java +++ /dev/null @@ -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. - * - *

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"); - } - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BatchPublishOptions.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BatchPublishOptions.java deleted file mode 100644 index 83614380..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BatchPublishOptions.java +++ /dev/null @@ -1,42 +0,0 @@ -package dev.caskeleton.messaging.api.publish; - -import java.time.Duration; -import java.util.Objects; - -/** - * Options covering a whole batch publish. - * - *

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); - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BatchPublishResult.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BatchPublishResult.java deleted file mode 100644 index 707bee0b..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BatchPublishResult.java +++ /dev/null @@ -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. - * - *

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 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 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); - } -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BlockingMessagePublisher.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BlockingMessagePublisher.java deleted file mode 100644 index 5b81bf88..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/BlockingMessagePublisher.java +++ /dev/null @@ -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. - * - *

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. - * - *

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 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 - */ - PublishResult publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options); -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/DelayedMessagePublisher.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/DelayedMessagePublisher.java deleted file mode 100644 index 9b9749a1..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/DelayedMessagePublisher.java +++ /dev/null @@ -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. - * - *

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 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 - */ - CompletionStage publish( - MessageDestination destination, MessageEnvelope message, Instant deliverAt); -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishResult.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishResult.java index 7449c3a9..3582dd73 100644 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishResult.java +++ b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishResult.java @@ -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 position, + Duration elapsed) { + return new PublishResult( + PublishCompletion.CONFIRMED, + PublishEvidence.confirmed(level), + routing, + position, + 1, + elapsed, + Optional.empty()); + } + + /** + * A publish refused before anything left the process. + * + *

Routing is {@link RoutingOutcome#NOT_APPLICABLE}: nothing reached a broker that could have + * routed it. + * + * @param elapsed wall-clock time spent + * @param failure why it was refused + * @return the rejected result + */ + public static PublishResult rejected(Duration elapsed, FailureDescriptor failure) { + return new PublishResult( + PublishCompletion.REJECTED, + PublishEvidence.notTransmitted(), + RoutingOutcome.NOT_APPLICABLE, + Optional.empty(), + 1, + elapsed, + Optional.of(failure)); + } + + /** + * A publish whose fate is unknown: the broker may or may not hold the message. + * + * @param elapsed wall-clock time spent + * @param failure what made the outcome unknowable + * @return the ambiguous result + */ + public static PublishResult ambiguous(Duration elapsed, FailureDescriptor failure) { + return new PublishResult( + PublishCompletion.AMBIGUOUS, + PublishEvidence.ambiguous(), + RoutingOutcome.UNKNOWN, + Optional.empty(), + 1, + elapsed, + Optional.of(failure)); + } + /** * Reports whether the broker may be holding this message. * diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/ManualMessageHandler.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/ManualMessageHandler.java deleted file mode 100644 index 69f1620c..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/ManualMessageHandler.java +++ /dev/null @@ -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. - * - *

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 the payload type - */ -public interface ManualMessageHandler { - - /** - * 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 handle(MessageDelivery delivery, SettlementController settlement); -} diff --git a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementController.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementController.java deleted file mode 100644 index e17e6b60..00000000 --- a/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementController.java +++ /dev/null @@ -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. - * - *

No method here accepts a broker channel, delivery tag, or offset. Manual settlement changes - * when the platform settles, never who settles, so the same DLQ-before-ack - * ordering and payload limits still apply. - * - *

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 ack(); - - /** - * Schedules the message for another attempt. - * - * @param delay how long to wait before redelivery - * @return a stage completing with the settlement outcome - */ - CompletionStage 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 deadLetter(FailureDescriptor failure); - - /** - * Discards the message without dead lettering. - * - * @param failure the sanitized failure description - * @return a stage completing with the settlement outcome - */ - CompletionStage reject(FailureDescriptor failure); -} diff --git a/src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/BoundedByteSink.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/BoundedByteSink.java similarity index 100% rename from src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/BoundedByteSink.java rename to src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/BoundedByteSink.java diff --git a/src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessage.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessage.java similarity index 100% rename from src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessage.java rename to src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessage.java diff --git a/src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessagePublisher.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessagePublisher.java similarity index 100% rename from src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessagePublisher.java rename to src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessagePublisher.java diff --git a/src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/MessageCodec.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageCodec.java similarity index 100% rename from src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/MessageCodec.java rename to src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageCodec.java diff --git a/src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/MessageCodecRegistry.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageCodecRegistry.java similarity index 100% rename from src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/MessageCodecRegistry.java rename to src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageCodecRegistry.java diff --git a/src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/MessageContractKey.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageContractKey.java similarity index 100% rename from src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/MessageContractKey.java rename to src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageContractKey.java diff --git a/src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/RawBytesMessageCodec.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/RawBytesMessageCodec.java similarity index 100% rename from src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/RawBytesMessageCodec.java rename to src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/RawBytesMessageCodec.java diff --git a/src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibility.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibility.java similarity index 100% rename from src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibility.java rename to src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibility.java diff --git a/src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidator.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidator.java similarity index 100% rename from src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidator.java rename to src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidator.java diff --git a/src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/SchemaReference.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaReference.java similarity index 100% rename from src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/SchemaReference.java rename to src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaReference.java diff --git a/src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/SchemaRegistry.java b/src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaRegistry.java similarity index 100% rename from src/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/SchemaRegistry.java rename to src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaRegistry.java diff --git a/src/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/destination/DestinationCapabilityTest.java b/src/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/destination/DestinationCapabilityTest.java index eaf9e328..da9c2701 100644 --- a/src/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/destination/DestinationCapabilityTest.java +++ b/src/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/destination/DestinationCapabilityTest.java @@ -31,9 +31,24 @@ class DestinationCapabilityTest { void emptyCapabilitySetAdvertisesNothing() { MessagingCapabilities capabilities = MessagingCapabilities.none(); - assertThat(capabilities.brokerAcknowledgement()).isFalse(); - assertThat(capabilities.replay()).isFalse(); - assertThat(capabilities.brokerTransaction()).isFalse(); + assertThat(capabilities.supported()).isEmpty(); + } + + @Test + @org.junit.jupiter.api.DisplayName("이름 붙인 capability만 지원하고 넘긴 집합을 나중에 바꿔도 영향이 없다") + void aCapabilitySetSupportsExactlyWhatWasNamedAndIgnoresLaterChangesToTheInput() { + // given + java.util.Set input = + java.util.EnumSet.of(MessagingCapabilities.Capability.ORDERED_STREAM); + MessagingCapabilities capabilities = new MessagingCapabilities(input); + + // when + input.add(MessagingCapabilities.Capability.DEDUPLICATED_PUBLISH); + + // then + assertThat(capabilities.supports(MessagingCapabilities.Capability.ORDERED_STREAM)).isTrue(); + assertThat(capabilities.supports(MessagingCapabilities.Capability.DEDUPLICATED_PUBLISH)) + .isFalse(); } @Test diff --git a/src/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/publish/PublishResultTest.java b/src/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/publish/PublishResultTest.java index 2e1add5a..122ede7e 100644 --- a/src/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/publish/PublishResultTest.java +++ b/src/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/api/publish/PublishResultTest.java @@ -7,6 +7,7 @@ import dev.caskeleton.messaging.api.error.FailureCategory; import dev.caskeleton.messaging.api.error.FailureDescriptor; import java.time.Duration; import java.util.Optional; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; class PublishResultTest { @@ -239,4 +240,47 @@ class PublishResultTest { Optional.empty())) .isInstanceOf(IllegalArgumentException.class); } + + @Test + @DisplayName("거부 factory는 전송되지 않았고 라우팅 대상이 아닌 결과를 만든다") + void theRejectedFactoryReportsNothingWasTransmittedOrRouted() { + // when + PublishResult result = PublishResult.rejected(Duration.ofMillis(3), AMBIGUOUS_FAILURE); + + // then + assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); + assertThat(result.evidence()).isEqualTo(PublishEvidence.notTransmitted()); + assertThat(result.routingOutcome()).isEqualTo(RoutingOutcome.NOT_APPLICABLE); + assertThat(result.failure()).contains(AMBIGUOUS_FAILURE); + } + + @Test + @DisplayName("모호 factory는 브로커가 메시지를 가졌을 수 있다고 보고한다") + void theAmbiguousFactoryReportsTheBrokerMayHoldTheMessage() { + // when + PublishResult result = PublishResult.ambiguous(Duration.ofMillis(3), AMBIGUOUS_FAILURE); + + // then + assertThat(result.mayHaveBeenStored()).isTrue(); + assertThat(result.evidence()).isEqualTo(PublishEvidence.ambiguous()); + assertThat(result.routingOutcome()).isEqualTo(RoutingOutcome.UNKNOWN); + } + + @Test + @DisplayName("확인 factory는 브로커 수락과 위치를 담고 실패 설명은 없다") + void theConfirmedFactoryCarriesAcceptanceAndPositionWithoutAFailure() { + // when + PublishResult result = + PublishResult.confirmed( + ConfirmationLevel.BROKER_ACK, + RoutingOutcome.NOT_APPLICABLE, + Optional.of(POSITION), + Duration.ofMillis(3)); + + // then + assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED); + assertThat(result.evidence().brokerAccepted()).isTrue(); + assertThat(result.position()).contains(POSITION); + assertThat(result.failure()).isEmpty(); + } } diff --git a/src/messaging/messaging-schema-api/src/test/java/dev/caskeleton/messaging/schema/BoundedByteSinkTest.java b/src/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/BoundedByteSinkTest.java similarity index 100% rename from src/messaging/messaging-schema-api/src/test/java/dev/caskeleton/messaging/schema/BoundedByteSinkTest.java rename to src/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/BoundedByteSinkTest.java diff --git a/src/messaging/messaging-schema-api/src/test/java/dev/caskeleton/messaging/schema/RawBytesMessageCodecTest.java b/src/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/RawBytesMessageCodecTest.java similarity index 100% rename from src/messaging/messaging-schema-api/src/test/java/dev/caskeleton/messaging/schema/RawBytesMessageCodecTest.java rename to src/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/RawBytesMessageCodecTest.java diff --git a/src/messaging/messaging-schema-api/src/test/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidatorTest.java b/src/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidatorTest.java similarity index 100% rename from src/messaging/messaging-schema-api/src/test/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidatorTest.java rename to src/messaging/messaging-core-api/src/test/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidatorTest.java diff --git a/src/messaging/messaging-kafka/build.gradle b/src/messaging/messaging-kafka/build.gradle index 75b48b2e..8f28164f 100644 --- a/src/messaging/messaging-kafka/build.gradle +++ b/src/messaging/messaging-kafka/build.gradle @@ -21,12 +21,11 @@ dependencies { // `org.apache.kafka` producer API directly, and a declared library that no source names is a // resolution, a lock entry and a transitive surface bought for nothing. api project(':messaging:messaging-core-api') - api project(':messaging:messaging-schema-api') api project(':messaging:messaging-policy') api project(':messaging:messaging-transport-spi') api project(':messaging:messaging-observability') api project(':messaging:messaging-security') - api project(':messaging:messaging-admin-api') + api project(':messaging:messaging-admin') // api: the public constructors and mappers take and return Producer, ProducerRecord and // RecordMetadata. Hiding the dependency does not hide the types — it only stops a consumer @@ -38,10 +37,6 @@ dependencies { testImplementation project(':messaging:messaging-testkit') testFixturesImplementation project(':messaging:messaging-testkit') - // Test-only. The topology validator is broker-neutral, so it lives in the admin runtime; the - // live-broker suite is here because only this module has a Kafka container to describe. - testImplementation project(':messaging:messaging-admin-runtime') - // Live-broker certification. The deterministic suite proves the platform's semantics; these // prove the client actually behaves that way against the version the matrix claims. integrationTestImplementation 'org.testcontainers:testcontainers-junit-jupiter' diff --git a/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaBatchConsumerRegistrar.java b/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaBatchConsumerRegistrar.java deleted file mode 100644 index 6ba2dc38..00000000 --- a/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaBatchConsumerRegistrar.java +++ /dev/null @@ -1,146 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import dev.caskeleton.messaging.api.delivery.BatchDeliveryMetadata; -import dev.caskeleton.messaging.api.delivery.OrderingScope; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.policy.DestinationProfile; -import java.time.Instant; -import java.util.ArrayList; -import java.util.LinkedHashMap; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; -import org.apache.kafka.clients.consumer.ConsumerRecord; -import org.apache.kafka.common.TopicPartition; - -/** - * Groups polled records into batches a batch handler can safely settle. - * - *

Batches never span partitions. A poll returns records from every assigned partition at once, - * and handing that mixture to a handler makes the batch unsettleable as a unit: committing the - * highest offset per partition after a partial failure would acknowledge records the handler never - * finished. Splitting by partition first makes each batch exactly one ordering unit, which is also - * what lets an ordered destination use batching at all. - * - *

Batch order within a partition is preserved as Kafka returned it. Re-ordering inside a batch - * would break ordering just as thoroughly as mixing partitions would, and less visibly. - */ -public final class KafkaBatchConsumerRegistrar { - - private final DestinationProfile profile; - private final int maxBatchSize; - - /** - * Creates a batch grouper for a destination. - * - * @param profile the validated destination profile - * @param maxBatchSize the largest batch handed to a handler - */ - public KafkaBatchConsumerRegistrar(DestinationProfile profile, int maxBatchSize) { - this.profile = Objects.requireNonNull(profile, "profile must not be null"); - if (maxBatchSize < 1) { - throw new IllegalArgumentException("maxBatchSize must be at least 1"); - } - this.maxBatchSize = maxBatchSize; - } - - /** - * Splits polled records into per-partition batches. - * - * @param records the records returned by one poll - * @param now the current instant - * @return the batches, each drawn from exactly one partition - */ - public List group(List> records, Instant now) { - Objects.requireNonNull(records, "records must not be null"); - Objects.requireNonNull(now, "now must not be null"); - - Map>> byPartition = new LinkedHashMap<>(); - for (ConsumerRecord record : records) { - byPartition - .computeIfAbsent( - new TopicPartition(record.topic(), record.partition()), key -> new ArrayList<>()) - .add(record); - } - - List batches = new ArrayList<>(); - for (Map.Entry>> entry : - byPartition.entrySet()) { - List> partitionRecords = entry.getValue(); - for (int start = 0; start < partitionRecords.size(); start += maxBatchSize) { - List> slice = - List.copyOf( - partitionRecords.subList( - start, Math.min(start + maxBatchSize, partitionRecords.size()))); - batches.add( - new PartitionBatch(entry.getKey(), slice, metadataFor(entry.getKey(), slice, now))); - } - } - return List.copyOf(batches); - } - - /** - * Refuses batch consumption on a destination whose ordering it cannot honour. - * - *

Destination-wide ordering and batching are incompatible on Kafka: ordering across the whole - * destination requires a single partition, and a single-partition destination gains nothing from - * batching while losing the ability to recover a partial failure. - * - * @throws MessagingConfigurationException when the destination cannot be consumed in batches - */ - public void requireBatchable() { - if (profile.orderingScope() == OrderingScope.DESTINATION) { - throw new MessagingConfigurationException( - "BATCH_ON_DESTINATION_ORDERED", - "destination %s declares destination-wide ordering, which batching cannot preserve " - .formatted(profile.name().value()) - + "across a partial batch failure"); - } - } - - private BatchDeliveryMetadata metadataFor( - TopicPartition partition, List> slice, Instant now) { - return new BatchDeliveryMetadata( - profile.name(), - slice.size(), - Optional.of(partition.toString()), - // Kafka commits an offset per partition, so a single-partition batch is settleable as one. - true, - now); - } - - /** - * One batch drawn from a single partition. - * - * @param partition the partition the batch came from - * @param records the records, in broker order - * @param metadata the batch-wide metadata handed to the handler - */ - public record PartitionBatch( - TopicPartition partition, - List> records, - BatchDeliveryMetadata metadata) { - - public PartitionBatch { - Objects.requireNonNull(partition, "partition must not be null"); - Objects.requireNonNull(metadata, "metadata must not be null"); - records = List.copyOf(records); - if (records.isEmpty()) { - throw new IllegalArgumentException("a batch is never empty"); - } - } - - /** - * Returns the offset to commit once the whole batch succeeds. - * - *

The last record's offset plus one, because Kafka commits the next offset to read. - * Committing the last record's own offset would replay it on every restart. - * - * @return the offset to commit - */ - public long commitOffset() { - return records.get(records.size() - 1).offset() + 1; - } - } -} diff --git a/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java b/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java index 9bfec581..4b85f2fc 100644 --- a/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java +++ b/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java @@ -333,7 +333,8 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati try { handlerPool.execute( () -> { - QueuedSettlement settlement = new QueuedSettlement(partition, record.offset(), epoch); + QueuedSettlement settlement = + new QueuedSettlement(partition, record, record.offset(), epoch); dev.caskeleton.messaging.api.MessageEnvelope< dev.caskeleton.messaging.schema.EncodedMessage> envelope; @@ -346,7 +347,7 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati if (quarantine.quarantine(record, undecodable)) { settlement.acknowledgeAfterQuarantine(); } else { - settlement.requeueAfterFailure(record, undecodable); + settlement.requeueAfterFailure(undecodable); } coordinator.release(partition); shutdown.endWork(); @@ -355,7 +356,13 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati java.util.concurrent.CompletableFuture handler = null; boolean releaseImmediately = true; try { - int attempt = retryMetadataMapper.attemptOf(envelope); + // Pause-and-seek re-reads the same record, so its retry header never moves; the + // count this runtime keeps for the offset is what tells the handler which attempt it + // is. A retry-topic hop carries its count in the header instead. + int attempt = + Math.max( + retryMetadataMapper.attemptOf(envelope), + failures.getOrDefault(new FailedOffset(partition, record.offset()), 0) + 1); TransportDelivery delivery = new TransportDelivery( envelope, @@ -381,8 +388,7 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati java.util.concurrent.CompletableFuture releaseAfterCompletion = timedOutHandler.whenComplete( (ignored, failure) -> { - settlement.requeueAfterFailure( - record, failure == null ? timedOut : failure); + settlement.requeueAfterFailure(failure == null ? timedOut : failure); coordinator.release(partition); shutdown.endWork(); }); @@ -395,12 +401,12 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati if (handler != null) { handler.cancel(true); } - settlement.requeueAfterFailure(record, interrupted); + settlement.requeueAfterFailure(interrupted); } catch (java.util.concurrent.ExecutionException | RuntimeException failure) { // A handler failure is retried, not parked. PARKED completed the offset without any // quarantine or dead-letter write, so a transient database outage silently discarded // every message it touched. - settlement.requeueAfterFailure(record, failure); + settlement.requeueAfterFailure(failure); } finally { if (releaseImmediately) { coordinator.release(partition); @@ -634,13 +640,16 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati implements dev.caskeleton.messaging.transport.TransportSettlement { private final TopicPartition partition; + private final ConsumerRecord record; private final long offset; private final long epoch; private final java.util.concurrent.atomic.AtomicReference terminal = new java.util.concurrent.atomic.AtomicReference<>(); - private QueuedSettlement(TopicPartition partition, long offset, long epoch) { + private QueuedSettlement( + TopicPartition partition, ConsumerRecord record, long offset, long epoch) { this.partition = partition; + this.record = record; this.offset = offset; this.epoch = epoch; } @@ -657,10 +666,23 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati }); } + /** + * A requeue the handler asked for, counted against the same attempt budget as a failure. + * + *

It used to pause and seek with no count, so a handler that kept answering {@code Retry} + * re-read its message forever and its partition never advanced — the retry policy's {@code + * maxAttempts} applied to exceptions only. + */ @Override public CompletionStage requeue( Duration delay) { - return terminalOnce("requeue", () -> enqueueRequeue(delay)); + return terminalOnce( + "requeue", + () -> + retryOrQuarantine( + new IllegalStateException( + "the handler asked for another attempt and the retry budget is spent"), + delay)); } @Override @@ -692,23 +714,41 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati * there is no quarantine it keeps being retried — the offset may not advance past a message * that exists nowhere else — which is why a production destination must have one. */ - private void requeueAfterFailure(ConsumerRecord record, Throwable reason) { - if (terminal.get() != null) { + private void requeueAfterFailure(Throwable reason) { + if (!terminal.compareAndSet(null, "requeue")) { // The handler settled before it failed or before its late completion; that answer stands. return; } + retryOrQuarantine(reason, Duration.ZERO); + } + + /** + * Counts one more attempt, then either parks the record or pauses its partition for a retry. + * + *

The caller has already claimed the terminal slot. Once the attempt budget is spent the + * record is written to quarantine and committed past; when there is no quarantine it keeps + * being retried — the offset may not advance past a message that exists nowhere else. + */ + private dev.caskeleton.messaging.api.settlement.SettlementResult retryOrQuarantine( + Throwable reason, Duration requested) { FailedOffset key = new FailedOffset(partition, offset); int attempt = failures.merge(key, 1, Integer::sum); dev.caskeleton.messaging.policy.RetryPolicy retry = spec.profile().retry(); if (attempt >= retry.maxAttempts() && quarantine.quarantine(record, reason)) { failures.remove(key); - acknowledgeAfterQuarantine(); - return; + settlements.enqueue( + new KafkaSettlementCommand( + partition, offset, KafkaSettlementCommand.Kind.PARKED, epoch)); + return dev.caskeleton.messaging.api.settlement.SettlementResult.settled(); } - if (terminal.compareAndSet(null, "requeue")) { - Duration backoff = BACKOFF.delayFor(retry, attempt); - enqueueRequeue(backoff.compareTo(MIN_RETRY_DELAY) < 0 ? MIN_RETRY_DELAY : backoff); + Duration backoff = BACKOFF.delayFor(retry, attempt); + if (backoff.compareTo(MIN_RETRY_DELAY) < 0) { + backoff = MIN_RETRY_DELAY; } + if (requested != null && backoff.compareTo(requested) < 0) { + backoff = requested; + } + return enqueueRequeue(backoff); } private dev.caskeleton.messaging.api.settlement.SettlementResult enqueueRequeue( diff --git a/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransport.java b/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransport.java index 6f1a3699..e80cff40 100644 --- a/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransport.java +++ b/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransport.java @@ -6,10 +6,7 @@ import dev.caskeleton.messaging.api.destination.MessagingCapabilities; import dev.caskeleton.messaging.api.error.FailureCategory; import dev.caskeleton.messaging.api.error.FailureDescriptor; import dev.caskeleton.messaging.api.error.MessagingCapabilityUnavailableException; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishEvidence; import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.api.publish.RoutingOutcome; import dev.caskeleton.messaging.transport.MessagingTransport; import dev.caskeleton.messaging.transport.TransportConsumerRegistration; import dev.caskeleton.messaging.transport.TransportConsumerSpec; @@ -17,7 +14,6 @@ import dev.caskeleton.messaging.transport.TransportPublishRequest; import dev.caskeleton.messaging.transport.TransportPublishResult; import java.time.Duration; import java.util.Objects; -import java.util.Optional; import java.util.concurrent.CompletableFuture; import java.util.concurrent.CompletionStage; import java.util.concurrent.atomic.AtomicBoolean; @@ -41,7 +37,7 @@ import org.apache.kafka.clients.producer.ProducerRecord; public final class KafkaMessagingTransport implements MessagingTransport { /** - * What this adapter can prove, with deduplicated publish set to false. + * What this adapter can prove, with deduplicated publish absent. * *

It was {@code true}, justified by producer idempotence. Producer idempotence deduplicates * sequence retries within one producer session: the producer id is reassigned on @@ -55,13 +51,10 @@ public final class KafkaMessagingTransport implements MessagingTransport { * build. False makes that request a startup failure instead, which is the whole reason the flag * exists. * - *

The order of these flags is the record's: brokerAcknowledgement, replication evidence, - * per-message settlement, batch settlement, ordered stream, keyed ordering, replay, delayed - * delivery, broker transaction, deduplicated publish, native dead letter, topology management. + *

Delayed delivery is absent too: Kafka has no broker-side schedule. */ private static final MessagingCapabilities CAPABILITIES = - new MessagingCapabilities( - true, true, true, true, true, true, true, false, true, false, false, true); + MessagingCapabilities.of(MessagingCapabilities.Capability.ORDERED_STREAM); private final String brokerName; private final long generation; @@ -199,14 +192,9 @@ public final class KafkaMessagingTransport implements MessagingTransport { private static TransportPublishResult rejectedLocally(String code, String message) { return new TransportPublishResult( - new PublishResult( - PublishCompletion.REJECTED, - PublishEvidence.notTransmitted(), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, + PublishResult.rejected( Duration.ZERO, - Optional.of(FailureDescriptor.of(FailureCategory.PERMANENT_BUSINESS, code, message)))); + FailureDescriptor.of(FailureCategory.PERMANENT_BUSINESS, code, message))); } private static CompletionStage completed(TransportPublishResult result) { diff --git a/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifier.java b/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifier.java index 0d33a587..3436871d 100644 --- a/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifier.java +++ b/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifier.java @@ -2,10 +2,7 @@ package dev.caskeleton.messaging.kafka; import dev.caskeleton.messaging.api.error.FailureCategory; import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishEvidence; import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.api.publish.RoutingOutcome; import java.time.Duration; import java.util.Optional; import org.apache.kafka.common.errors.AuthenticationException; @@ -40,23 +37,9 @@ public final class KafkaPublishFailureClassifier { public PublishResult classify(Throwable error, Duration elapsed) { Throwable cause = unwrap(error); if (isDefinitiveRejection(cause)) { - return new PublishResult( - PublishCompletion.REJECTED, - PublishEvidence.notTransmitted(), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - elapsed, - Optional.of(descriptor(cause, rejectionCategory(cause), false))); + return PublishResult.rejected(elapsed, descriptor(cause, rejectionCategory(cause), false)); } - return new PublishResult( - PublishCompletion.AMBIGUOUS, - PublishEvidence.ambiguous(), - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, - elapsed, - Optional.of(descriptor(cause, FailureCategory.AMBIGUOUS, false))); + return PublishResult.ambiguous(elapsed, descriptor(cause, FailureCategory.AMBIGUOUS, false)); } /** diff --git a/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishMapper.java b/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishMapper.java index 39f98ad1..7c74f137 100644 --- a/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishMapper.java +++ b/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishMapper.java @@ -4,8 +4,6 @@ import dev.caskeleton.messaging.api.MessageEnvelope; import dev.caskeleton.messaging.api.destination.ConfirmationRequirement; import dev.caskeleton.messaging.api.error.MessagingConfigurationException; import dev.caskeleton.messaging.api.publish.ConfirmationLevel; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishEvidence; import dev.caskeleton.messaging.api.publish.PublishResult; import dev.caskeleton.messaging.api.publish.RoutingOutcome; import dev.caskeleton.messaging.policy.DestinationProfile; @@ -99,13 +97,10 @@ public final class KafkaPublishMapper { ? ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK : ConfirmationLevel.BROKER_ACK; - return new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(level), + return PublishResult.confirmed( + level, RoutingOutcome.NOT_APPLICABLE, Optional.of(new KafkaPosition(metadata.topic(), metadata.partition(), metadata.offset())), - 1, - elapsed, - Optional.empty()); + elapsed); } } diff --git a/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTopologyInspector.java b/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTopologyInspector.java deleted file mode 100644 index 195cf296..00000000 --- a/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaTopologyInspector.java +++ /dev/null @@ -1,45 +0,0 @@ -package dev.caskeleton.messaging.kafka; - -import java.util.List; -import java.util.Map; - -/** - * Read-only inspection of Kafka topology. - * - *

Describe and validate only. Creation, deletion, and configuration changes belong to the Admin - * Plane with its own credential: an application runtime that could alter topology is one bad - * deployment away from deleting a topic it merely meant to read. - */ -public interface KafkaTopologyInspector { - - /** - * Returns the partition count for a topic. - * - * @param topic the topic - * @return the number of partitions - */ - int partitionCount(String topic); - - /** - * Returns the replication factor for a topic. - * - * @param topic the topic - * @return the replication factor - */ - short replicationFactor(String topic); - - /** - * Returns the effective topic configuration. - * - * @param topic the topic - * @return the configuration entries - */ - Map configuration(String topic); - - /** - * Returns the topics that exist. - * - * @return the topic names - */ - List topics(); -} diff --git a/src/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java b/src/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java index db4e105f..f5580a52 100644 --- a/src/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java +++ b/src/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java @@ -274,6 +274,72 @@ class KafkaConsumerRegistrarTest { .hasValue(11L); } + @Test + @DisplayName("handler가 요청한 requeue도 시도 횟수를 세어 예산을 쓰면 quarantine 후 commit된다") + void aDeliveryItsHandlerKeepsRequeueingSpendsTheBudgetAndIsQuarantined() { + // given + List quarantined = new ArrayList<>(); + KafkaConsumerRegistrar registrar = + registrar( + KafkaContractHarness.profile(), + this::requeue, + (record, reason) -> quarantined.add(record.offset()), + () -> NOW); + assign(); + addRecord(10); + registrar.pollOnce(NOW); + handlers.runAll(); + + // when + registrar.pollOnce(NOW); + + // then + assertThat(quarantined) + .as("a Retry answer that is never counted is a poison message retried forever") + .containsExactly(10L); + assertThat(registrar.committedOffset(PARTITION)).hasValue(11L); + } + + @Test + @DisplayName("다시 읽힌 delivery는 몇 번째 시도인지 metadata로 handler에 알려진다") + void aReReadDeliveryTellsTheHandlerWhichAttemptItIs() { + // given + Instant start = NOW; + RetryPolicy threeAttempts = + new RetryPolicy( + RetryMode.PAUSE_PARTITION, + 3, + Duration.ofSeconds(1), + Duration.ofSeconds(1), + 1.0, + false, + OrderingImpact.PRESERVE, + java.util.Set.of(), + java.util.Set.of()); + KafkaConsumerRegistrar registrar = + registrar( + profile(Duration.ofSeconds(1), threeAttempts, false), + this::requeue, + KafkaQuarantinePublisher.unavailable(), + () -> start); + assign(); + addRecord(10); + registrar.pollOnce(start); + handlers.runAll(); + registrar.pollOnce(start); + addRecord(10); + + // when + registrar.pollOnce(start.plusSeconds(2)); + handlers.runAll(); + + // then + assertThat(handled) + .extracting(delivery -> delivery.metadata().deliveryAttempt()) + .containsExactly(1, 2); + assertThat(handled.get(1).metadata().redelivered()).isTrue(); + } + @Test void aProductionDestinationWithoutAQuarantineIsRefused() { // given @@ -674,6 +740,13 @@ class KafkaConsumerRegistrarTest { throw new IllegalStateException("the downstream this handler writes to is down"); } + /** Asks for another attempt through the settlement, as the processor does for a Retry answer. */ + private CompletionStage requeue(TransportDelivery delivery) { + handled.add(delivery); + delivery.settlement().requeue(Duration.ZERO).toCompletableFuture().join(); + return CompletableFuture.completedFuture(null); + } + /** Acknowledges inside the handler, as a successful M1 delivery does. */ private CompletionStage settleImmediately(TransportDelivery delivery) { handled.add(delivery); diff --git a/src/messaging/messaging-kafka/src/testFixtures/java/dev/caskeleton/messaging/kafka/KafkaContractHarness.java b/src/messaging/messaging-kafka/src/testFixtures/java/dev/caskeleton/messaging/kafka/KafkaContractHarness.java index fb2e3aeb..7d056699 100644 --- a/src/messaging/messaging-kafka/src/testFixtures/java/dev/caskeleton/messaging/kafka/KafkaContractHarness.java +++ b/src/messaging/messaging-kafka/src/testFixtures/java/dev/caskeleton/messaging/kafka/KafkaContractHarness.java @@ -22,7 +22,7 @@ import dev.caskeleton.messaging.api.publish.PublishEvidence; import dev.caskeleton.messaging.api.publish.PublishOptions; import dev.caskeleton.messaging.api.publish.PublishResult; import dev.caskeleton.messaging.api.publish.RoutingOutcome; -import dev.caskeleton.messaging.policy.CapabilityTier; +import dev.caskeleton.messaging.policy.ApiTier; import dev.caskeleton.messaging.policy.ConsumerPolicy; import dev.caskeleton.messaging.policy.DeadLetterOrchestrator; import dev.caskeleton.messaging.policy.DeadLetterPolicy; @@ -263,7 +263,7 @@ final class KafkaContractHarness implements MessagingAdapterHarness { RetryPolicy.none(), DeadLetterPolicy.to(DEAD_LETTER), PayloadPolicy.defaults(), - CapabilityTier.M1, + ApiTier.M1, false, false, false); diff --git a/src/messaging/messaging-policy/build.gradle b/src/messaging/messaging-policy/build.gradle index f2ca78e0..fac7b208 100644 --- a/src/messaging/messaging-policy/build.gradle +++ b/src/messaging/messaging-policy/build.gradle @@ -4,5 +4,4 @@ plugins { dependencies { api project(':messaging:messaging-core-api') - api project(':messaging:messaging-schema-api') } diff --git a/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ApiTier.java b/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ApiTier.java new file mode 100644 index 00000000..c48fb243 --- /dev/null +++ b/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/ApiTier.java @@ -0,0 +1,30 @@ +package dev.caskeleton.messaging.policy; + +/** + * The API tier a destination is approved for. + * + *

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

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

Recorded on the profile so that the tier boundary is enforced by configuration review rather - * than by whichever handler happens to be wired in. An M1 destination that silently accepted a - * manual settlement handler would move the acknowledge-after-success ordering out of the platform - * and into application code. - */ -public enum CapabilityTier { - - /** Typed publish and handler with platform-owned settlement. */ - M1, - - /** Batch, manual settlement, pause and resume, delayed delivery, replay request. */ - M2, - - /** Broker-native capabilities exposed as typed interfaces. */ - M3 -} diff --git a/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DefaultRetryDecisionEngine.java b/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DefaultRetryDecisionEngine.java index 943d498b..5708bd5c 100644 --- a/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DefaultRetryDecisionEngine.java +++ b/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DefaultRetryDecisionEngine.java @@ -46,7 +46,11 @@ public final class DefaultRetryDecisionEngine implements RetryDecisionEngine { if (policy.orderingImpact() == OrderingImpact.PRESERVE && profile.isOrdered() - && context.capabilities().orderedStream()) { + && context + .capabilities() + .supports( + dev.caskeleton.messaging.api.destination.MessagingCapabilities.Capability + .ORDERED_STREAM)) { return new RetryDecision.PauseAndRetry(delay); } if (policy.mode() == RetryMode.PAUSE_PARTITION) { @@ -61,7 +65,12 @@ public final class DefaultRetryDecisionEngine implements RetryDecisionEngine { if (policy.mode() == RetryMode.INLINE || policy.mode() == RetryMode.BLOCKING) { return new RetryDecision.RetryInline(delay); } - if (policy.mode() == RetryMode.BROKER_DELAYED && context.capabilities().delayedDelivery()) { + if (policy.mode() == RetryMode.BROKER_DELAYED + && context + .capabilities() + .supports( + dev.caskeleton.messaging.api.destination.MessagingCapabilities.Capability + .DELAYED_DELIVERY)) { return new RetryDecision.PublishToRetryDestination( policy.retryDestination().orElse(profile.name()), delay); } diff --git a/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DestinationProfile.java b/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DestinationProfile.java index 69b3938b..11da9cb3 100644 --- a/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DestinationProfile.java +++ b/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DestinationProfile.java @@ -47,7 +47,7 @@ public record DestinationProfile( RetryPolicy retry, DeadLetterPolicy deadLetter, PayloadPolicy payload, - CapabilityTier tier, + ApiTier tier, boolean production, boolean keyResolverConfigured, boolean topologyAutoCreate) { diff --git a/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DestinationProfileValidator.java b/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DestinationProfileValidator.java index 4757611c..b7bebba5 100644 --- a/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DestinationProfileValidator.java +++ b/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/DestinationProfileValidator.java @@ -62,7 +62,7 @@ public final class DestinationProfileValidator { throw new IllegalArgumentException( "ordering scope KEY requires a key resolver for " + profile.name().value()); } - if (profile.tier() == CapabilityTier.M1 && profile.consumer().manualSettlement()) { + if (profile.tier() == ApiTier.M1 && profile.consumer().manualSettlement()) { throw new IllegalArgumentException( "an M1 destination cannot configure manual settlement: " + profile.name().value()); } diff --git a/src/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/DestinationProfileValidatorTest.java b/src/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/DestinationProfileValidatorTest.java index f2c16a98..7beb6be4 100644 --- a/src/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/DestinationProfileValidatorTest.java +++ b/src/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/DestinationProfileValidatorTest.java @@ -188,7 +188,7 @@ final class DestinationProfileFixtures { RetryPolicy.none(), DeadLetterPolicy.to(new DestinationName("order-events-dlq")), PayloadPolicy.defaults(), - CapabilityTier.M1, + ApiTier.M1, false, false, false); @@ -298,7 +298,7 @@ final class DestinationProfileFixtures { base.retry(), base.deadLetter(), base.payload(), - CapabilityTier.M1, + ApiTier.M1, base.production(), base.keyResolverConfigured(), base.topologyAutoCreate()); diff --git a/src/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/RetryDecisionEngineTest.java b/src/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/RetryDecisionEngineTest.java index 53fc29c0..6a8dc244 100644 --- a/src/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/RetryDecisionEngineTest.java +++ b/src/messaging/messaging-policy/src/test/java/dev/caskeleton/messaging/policy/RetryDecisionEngineTest.java @@ -131,12 +131,11 @@ final class RetryContextFixtures { private RetryContextFixtures() {} private static final MessagingCapabilities ORDERED_KAFKA = - new MessagingCapabilities( - true, true, true, true, true, true, true, false, true, true, false, true); + MessagingCapabilities.of( + MessagingCapabilities.Capability.ORDERED_STREAM, + MessagingCapabilities.Capability.DEDUPLICATED_PUBLISH); - private static final MessagingCapabilities PLAIN_QUEUE = - new MessagingCapabilities( - true, true, true, false, false, false, false, false, false, false, true, true); + private static final MessagingCapabilities PLAIN_QUEUE = MessagingCapabilities.none(); static DeliveryMetadata delivery(int attempt) { return new DeliveryMetadata( diff --git a/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/IdempotentMessageHandler.java b/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/IdempotentMessageHandler.java deleted file mode 100644 index 478e6ff6..00000000 --- a/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/IdempotentMessageHandler.java +++ /dev/null @@ -1,33 +0,0 @@ -package dev.caskeleton.messaging.reliability; - -import dev.caskeleton.messaging.api.delivery.HandleResult; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import java.util.concurrent.CompletionStage; - -/** - * Runs a side effect at most once per consumer, whatever the broker redelivers. - * - *

{@code consumerName} is a parameter rather than a property of the message because the same - * message legitimately reaches several independent consumers, and each of them is entitled to apply - * its own effect once. Keying the inbox on the message id alone would let whichever consumer ran - * first suppress all the others. - * - *

A duplicate is not a failure. The handler returns success for a message it has already - * applied, so the broker settles it and stops redelivering; treating it as an error would park a - * message whose work is already done. - * - * @param the payload type - */ -public interface IdempotentMessageHandler { - - /** - * Applies an action once for a given consumer. - * - * @param consumerName the consumer identity the reservation is keyed on - * @param delivery the message being handled - * @param action the effect to apply inside the reservation's transaction - * @return a stage completing with the handler outcome - */ - CompletionStage handleOnce( - String consumerName, MessageDelivery delivery, TransactionalMessageAction action); -} diff --git a/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/InboxRecord.java b/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/InboxRecord.java deleted file mode 100644 index bfa16dc0..00000000 --- a/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/InboxRecord.java +++ /dev/null @@ -1,27 +0,0 @@ -package dev.caskeleton.messaging.reliability; - -import dev.caskeleton.messaging.api.MessageId; -import java.time.Instant; -import java.util.Objects; - -/** - * One row of the consumer inbox. - * - *

Keyed by message id and consumer id, because two independent consumers of the same - * event must each process it once — deduplicating on the message alone would let the first consumer - * suppress the second. - * - * @param messageId the logical message identity - * @param consumerId the consumer's stable identity - * @param processedAt when the side effect committed - */ -public record InboxRecord(MessageId messageId, String consumerId, Instant processedAt) { - - public InboxRecord { - Objects.requireNonNull(messageId, "messageId must not be null"); - Objects.requireNonNull(processedAt, "processedAt must not be null"); - if (consumerId == null || consumerId.isBlank()) { - throw new IllegalArgumentException("consumerId must not be blank"); - } - } -} diff --git a/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/InboxResult.java b/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/InboxResult.java deleted file mode 100644 index 76d0befa..00000000 --- a/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/InboxResult.java +++ /dev/null @@ -1,45 +0,0 @@ -package dev.caskeleton.messaging.reliability; - -/** - * What the inbox decided about one delivery. - * - *

Three outcomes, not two. Collapsing {@link #ALREADY_APPLIED} and {@link #CLAIMED_ELSEWHERE} - * into a single "duplicate" would settle a message whose effect is still only half-written by - * another instance: if that instance then rolls back, the effect is lost and the broker will never - * redeliver, because this instance already acknowledged it. - */ -public enum InboxResult { - - /** No reservation existed; the effect ran inside this transaction. */ - APPLIED(true), - - /** - * A committed reservation already exists, so the effect ran before. - * - *

Settle the message: the work is done and redelivering it achieves nothing. - */ - ALREADY_APPLIED(true), - - /** - * Another instance holds an uncommitted reservation for this message. - * - *

Do not settle. The other transaction may still roll back, and this delivery is the - * only remaining copy that could re-apply the effect. - */ - CLAIMED_ELSEWHERE(false); - - private final boolean safeToSettle; - - InboxResult(boolean safeToSettle) { - this.safeToSettle = safeToSettle; - } - - /** - * Reports whether the source message may be settled on this outcome. - * - * @return true when settling cannot lose the effect - */ - public boolean isSafeToSettle() { - return safeToSettle; - } -} diff --git a/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/ReliableMessagePublisher.java b/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/ReliableMessagePublisher.java deleted file mode 100644 index 9eac6c70..00000000 --- a/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/ReliableMessagePublisher.java +++ /dev/null @@ -1,27 +0,0 @@ -package dev.caskeleton.messaging.reliability; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.destination.MessageDestination; - -/** - * Enrols a message in the caller's database transaction instead of publishing it. - * - *

The return type is {@code void}, and that is the contract. There is no publish outcome to - * report yet: the row is written inside the caller's transaction, so if the transaction rolls back - * the message never existed, and if it commits the relay will publish it later. Handing back a - * {@code PublishResult} here would be a lie about work that has not happened. - * - *

This is the answer to the dual-write problem. Writing to the database and publishing to the - * broker in the same method cannot be made atomic; writing both to the database can. - */ -public interface ReliableMessagePublisher { - - /** - * Stages a message for publication when the current transaction commits. - * - * @param the payload type - * @param destination the logical destination - * @param message the envelope to publish, carrying the identity the relay will preserve - */ - void addToOutbox(MessageDestination destination, MessageEnvelope message); -} diff --git a/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/TransactionalMessageAction.java b/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/TransactionalMessageAction.java deleted file mode 100644 index 5b5b1218..00000000 --- a/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/TransactionalMessageAction.java +++ /dev/null @@ -1,29 +0,0 @@ -package dev.caskeleton.messaging.reliability; - -import dev.caskeleton.messaging.api.delivery.MessageDelivery; - -/** - * The business work that runs inside the same transaction as the inbox reservation. - * - *

Sharing one transaction is the entire mechanism. If the effect committed separately from the - * "I have handled this message" marker, a crash between the two would either replay the effect or - * suppress a message that was never handled — and which of those you get would depend on the order - * the two commits happened to be written in. - * - *

Implementations must not settle the message, publish, or start their own transaction. The - * runtime owns the transaction boundary precisely so that the action cannot accidentally commit - * half of it. - * - * @param the payload type - */ -@FunctionalInterface -public interface TransactionalMessageAction { - - /** - * Applies the side effect for one delivery. - * - * @param delivery the message being handled - * @throws Exception when the effect fails, rolling back both it and the inbox reservation - */ - void apply(MessageDelivery delivery) throws Exception; -} diff --git a/src/messaging/messaging-reliability-jdbc-postgresql/build.gradle b/src/messaging/messaging-reliability-jdbc-postgresql/build.gradle index e6c57bb1..cfa5217b 100644 --- a/src/messaging/messaging-reliability-jdbc-postgresql/build.gradle +++ b/src/messaging/messaging-reliability-jdbc-postgresql/build.gradle @@ -20,7 +20,7 @@ dependencies { // The destructive-operation journal lives here because it needs exactly what the outbox needs: // one relational database every replica can see, and a migration lane that already exists. The // contract it implements belongs to the admin API. - api project(':messaging:messaging-admin-api') + api project(':messaging:messaging-admin') implementation 'org.springframework:spring-jdbc' implementation 'org.springframework:spring-tx' diff --git a/src/messaging/messaging-reliability-jdbc-postgresql/gradle.lockfile b/src/messaging/messaging-reliability-jdbc-postgresql/gradle.lockfile index 865fc312..2eeab5a0 100644 --- a/src/messaging/messaging-reliability-jdbc-postgresql/gradle.lockfile +++ b/src/messaging/messaging-reliability-jdbc-postgresql/gradle.lockfile @@ -39,6 +39,9 @@ commons-logging:commons-logging:1.3.6=compileClasspath,integrationTestCompileCla info.picocli:picocli:4.7.7=checkstyle io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor +io.micrometer:micrometer-commons:1.16.7=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +io.micrometer:micrometer-core:1.16.7=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +io.micrometer:micrometer-observation:1.16.7=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath javax.inject:javax.inject:1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor jaxen:jaxen:2.0.6=spotbugs net.bytebuddy:byte-buddy:1.17.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath @@ -67,6 +70,7 @@ org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle org.codehaus.plexus:plexus-utils:3.3.0=checkstyle org.dom4j:dom4j:2.2.0=spotbugs +org.hdrhistogram:HdrHistogram:2.2.2=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath org.javassist:javassist:3.28.0-GA=checkstyle org.jetbrains:annotations:17.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,integrationTestAnnotationProcessor,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath @@ -79,6 +83,7 @@ org.junit.platform:junit-platform-engine:6.0.3=integrationTestRuntimeClasspath,t org.junit.platform:junit-platform-launcher:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath org.junit:junit-bom:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath org.junit:junit-bom:6.1.0=spotbugs +org.latencyutils:LatencyUtils:2.0.3=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath org.mockito:mockito-core:5.20.0=mockitoAgent org.opentest4j:opentest4j:1.3.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath org.ow2.asm:asm-analysis:9.10.1=spotbugs diff --git a/src/messaging/messaging-reliability/build.gradle b/src/messaging/messaging-reliability/build.gradle index 9c08eb50..d2f62103 100644 --- a/src/messaging/messaging-reliability/build.gradle +++ b/src/messaging/messaging-reliability/build.gradle @@ -10,7 +10,6 @@ dependencies { api project(':messaging:messaging-core-api') api project(':messaging:messaging-reliability-api') // The relay hands encoded rows to the publisher as EncodedMessage. - api project(':messaging:messaging-schema-api') // Test-only. The relay is also driven through the real DefaultMessagePublisher: a fake publisher // accepted the pre-encoded rows the real one re-encoded and rejected. diff --git a/src/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java b/src/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java new file mode 100644 index 00000000..23c230f9 --- /dev/null +++ b/src/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java @@ -0,0 +1,129 @@ +package dev.caskeleton.messaging.inbox; + +import dev.caskeleton.messaging.api.delivery.HandleResult; +import dev.caskeleton.messaging.api.delivery.MessageDelivery; +import dev.caskeleton.messaging.api.delivery.MessageHandler; +import dev.caskeleton.messaging.api.destination.MessageDestination; +import java.time.Instant; +import java.util.Objects; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.CompletionException; +import java.util.concurrent.CompletionStage; +import java.util.function.Supplier; + +/** + * Runs a {@link MessageHandler} at most once per message and consumer, inside the inbox + * reservation's transaction. + * + *

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

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

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

The handler's stage is awaited on the calling thread, inside the transaction. A handler that + * hands its write to another thread writes outside the transaction, and the inbox cannot protect + * that write. + * + * @param the payload type + */ +public final class InboxMessageHandler implements MessageHandler { + + private final MessageHandler delegate; + private final IdempotentConsumer inbox; + private final String consumerName; + private final Supplier clock; + + /** + * Wraps a handler. + * + * @param delegate the business handler + * @param inbox the reservation-and-effect runner + * @param consumerName the consumer identity the reservation is keyed on + * @param clock supplies the reservation instant + */ + public InboxMessageHandler( + MessageHandler delegate, + IdempotentConsumer inbox, + String consumerName, + Supplier clock) { + this.delegate = Objects.requireNonNull(delegate, "delegate must not be null"); + this.inbox = Objects.requireNonNull(inbox, "inbox must not be null"); + this.clock = Objects.requireNonNull(clock, "clock must not be null"); + if (consumerName == null || consumerName.isBlank()) { + throw new IllegalArgumentException("consumerName must not be blank"); + } + this.consumerName = consumerName; + } + + @Override + public MessageDestination destination() { + return delegate.destination(); + } + + @Override + public CompletionStage handle(MessageDelivery delivery) { + Objects.requireNonNull(delivery, "delivery must not be null"); + try { + InboxOutcome outcome = + inbox.runOnce( + delivery.message().messageId(), + consumerName, + clock.get(), + () -> { + HandleResult result = answerOf(delivery); + if (!(result instanceof HandleResult.Success)) { + // Thrown, not returned: the runner rolls back only on a throw, and a reservation + // that commits without its effect suppresses the redelivery that would apply it. + throw new NotAppliedException(result); + } + return result; + }); + return CompletableFuture.completedFuture(outcome.result().orElseGet(HandleResult::success)); + } catch (NotAppliedException notApplied) { + return CompletableFuture.completedFuture(notApplied.result); + } catch (RuntimeException failed) { + return CompletableFuture.failedFuture(failed); + } + } + + private HandleResult answerOf(MessageDelivery delivery) { + CompletionStage stage = delegate.handle(delivery); + if (stage == null) { + throw new IllegalStateException("the handler returned no stage"); + } + try { + HandleResult result = stage.toCompletableFuture().join(); + if (result == null) { + throw new IllegalStateException("the handler returned no result"); + } + return result; + } catch (CompletionException failed) { + throw failed.getCause() instanceof RuntimeException cause ? cause : failed; + } + } + + /** Carries a non-success answer out of the transaction so it rolls back. */ + private static final class NotAppliedException extends RuntimeException { + + private static final long serialVersionUID = 1L; + + @SuppressWarnings("serial") + private final transient HandleResult result; + + private NotAppliedException(HandleResult result) { + super(null, null, false, false); + this.result = result; + } + } +} diff --git a/src/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/TransactionalInboxHandler.java b/src/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/TransactionalInboxHandler.java deleted file mode 100644 index 7195d4ee..00000000 --- a/src/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/TransactionalInboxHandler.java +++ /dev/null @@ -1,104 +0,0 @@ -package dev.caskeleton.messaging.inbox; - -import dev.caskeleton.messaging.api.delivery.HandleResult; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.reliability.IdempotentMessageHandler; -import dev.caskeleton.messaging.reliability.InboxResult; -import dev.caskeleton.messaging.reliability.TransactionalMessageAction; -import java.time.Instant; -import java.util.Objects; -import java.util.Optional; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import java.util.function.Supplier; - -/** - * The JDBC-backed {@link IdempotentMessageHandler}. - * - *

Reservation and effect commit together, in the runner's single transaction. Everything else - * about this class follows from that: it cannot settle the message (settlement is not - * transactional), it cannot publish (the publish would survive a rollback), and it cannot catch and - * swallow the action's exception (the rollback is how the reservation is undone). - * - *

An already-reserved message returns success. Under at-least-once delivery a duplicate is the - * normal case, not an error; reporting failure would send a message whose work is complete to the - * dead-letter queue. - * - * @param the payload type - */ -public final class TransactionalInboxHandler implements IdempotentMessageHandler { - - private final IdempotentConsumer consumer; - private final Supplier clock; - - /** - * Creates a handler. - * - * @param consumer the reservation-and-effect runner - * @param clock supplies the current instant - */ - public TransactionalInboxHandler(IdempotentConsumer consumer, Supplier clock) { - this.consumer = Objects.requireNonNull(consumer, "consumer must not be null"); - this.clock = Objects.requireNonNull(clock, "clock must not be null"); - } - - @Override - public CompletionStage handleOnce( - String consumerName, MessageDelivery delivery, TransactionalMessageAction action) { - Objects.requireNonNull(delivery, "delivery must not be null"); - Objects.requireNonNull(action, "action must not be null"); - if (consumerName == null || consumerName.isBlank()) { - throw new IllegalArgumentException("consumerName must not be blank"); - } - - try { - InboxOutcome outcome = - consumer.runOnce( - delivery.message().messageId(), - consumerName, - clock.get(), - () -> { - try { - action.apply(delivery); - } catch (Exception failure) { - // Wrapped, not swallowed: the transaction runner has to see a throw to roll the - // reservation back along with the effect. - throw new ActionFailedException(failure); - } - return InboxResult.APPLIED; - }); - - return CompletableFuture.completedFuture( - outcome.processed() ? HandleResult.success() : duplicateIsSuccess()); - } catch (ActionFailedException failure) { - return CompletableFuture.completedFuture(retryable(failure.getCause())); - } - } - - private static HandleResult duplicateIsSuccess() { - // The effect already ran in an earlier delivery. Settling is correct; redelivering is not. - return HandleResult.success(); - } - - private static HandleResult retryable(Throwable cause) { - return new HandleResult.Retry( - new FailureDescriptor( - FailureCategory.TRANSIENT_INFRASTRUCTURE, - "INBOX_ACTION_FAILED", - true, - "the transactional action failed and its reservation was rolled back", - Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName()))); - } - - /** Carries the action's checked exception out through the transaction runner. */ - private static final class ActionFailedException extends RuntimeException { - - private static final long serialVersionUID = 1L; - - private ActionFailedException(Throwable cause) { - super(cause); - } - } -} diff --git a/src/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelay.java b/src/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelay.java index 566f93c8..ae4c3bb6 100644 --- a/src/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelay.java +++ b/src/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelay.java @@ -6,11 +6,8 @@ import dev.caskeleton.messaging.api.error.FailureCategory; import dev.caskeleton.messaging.api.error.FailureDescriptor; import dev.caskeleton.messaging.api.error.MessagingException; import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishEvidence; import dev.caskeleton.messaging.api.publish.PublishOptions; import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.api.publish.RoutingOutcome; import dev.caskeleton.messaging.reliability.OutboxLease; import dev.caskeleton.messaging.reliability.OutboxRecord; import dev.caskeleton.messaging.reliability.OutboxRepository; @@ -20,7 +17,6 @@ import java.time.Duration; import java.time.Instant; import java.util.List; import java.util.Objects; -import java.util.Optional; /** * Publishes outbox rows, treating an unknown outcome as retryable rather than final. @@ -254,18 +250,12 @@ public final class OutboxRelay { } catch (RuntimeException unknown) { // An exception says nothing about whether the broker took the message, so the row is retried // under the same id like any other unknown outcome — not failed, not left IN_FLIGHT. - return new PublishResult( - PublishCompletion.AMBIGUOUS, - PublishEvidence.ambiguous(), - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, + return PublishResult.ambiguous( Duration.ZERO, - Optional.of( - FailureDescriptor.of( - FailureCategory.AMBIGUOUS, - "PUBLISH_OUTCOME_UNKNOWN", - "the publisher threw " + unknown.getClass().getSimpleName()))); + FailureDescriptor.of( + FailureCategory.AMBIGUOUS, + "PUBLISH_OUTCOME_UNKNOWN", + "the publisher threw " + unknown.getClass().getSimpleName())); } } diff --git a/src/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/InboxMessageHandlerTest.java b/src/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/InboxMessageHandlerTest.java new file mode 100644 index 00000000..2b672054 --- /dev/null +++ b/src/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/InboxMessageHandlerTest.java @@ -0,0 +1,179 @@ +package dev.caskeleton.messaging.inbox; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.messaging.api.ContentType; +import dev.caskeleton.messaging.api.MessageEnvelope; +import dev.caskeleton.messaging.api.MessageId; +import dev.caskeleton.messaging.api.MessageType; +import dev.caskeleton.messaging.api.ProducerId; +import dev.caskeleton.messaging.api.SchemaVersion; +import dev.caskeleton.messaging.api.TraceContext; +import dev.caskeleton.messaging.api.delivery.DeliveryContext; +import dev.caskeleton.messaging.api.delivery.DeliveryMetadata; +import dev.caskeleton.messaging.api.delivery.HandleResult; +import dev.caskeleton.messaging.api.delivery.MessageDelivery; +import dev.caskeleton.messaging.api.delivery.MessageHandler; +import dev.caskeleton.messaging.api.destination.DestinationName; +import dev.caskeleton.messaging.api.destination.MessageDestination; +import dev.caskeleton.messaging.api.error.FailureCategory; +import dev.caskeleton.messaging.api.error.FailureDescriptor; +import dev.caskeleton.messaging.api.header.MessageHeaders; +import dev.caskeleton.messaging.reliability.InboxRepository; +import java.time.Instant; +import java.util.ArrayList; +import java.util.LinkedHashSet; +import java.util.List; +import java.util.Optional; +import java.util.Set; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.CompletionStage; +import java.util.function.Function; +import java.util.function.Supplier; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +/** The inbox is a {@code MessageHandler} wrapping the business handler in one transaction. */ +class InboxMessageHandlerTest { + + private static final Instant NOW = Instant.parse("2026-08-14T00:00:00Z"); + private static final DestinationName ORDERS = new DestinationName("order-events"); + + private final RollbackInbox inbox = new RollbackInbox(); + private final List effects = new ArrayList<>(); + + @Test + @DisplayName("같은 메시지가 다시 배달되면 handler를 부르지 않고 Success로 답한다") + void aRedeliveredMessageIsAnsweredWithSuccessWithoutCallingTheHandler() { + // given + MessageDelivery delivery = delivery(MessageId.newId()); + MessageHandler handler = wrap(ignored -> HandleResult.success()); + handler.handle(delivery).toCompletableFuture().join(); + + // when + HandleResult redelivered = handler.handle(delivery).toCompletableFuture().join(); + + // then + assertThat(redelivered).isInstanceOf(HandleResult.Success.class); + assertThat(effects).hasSize(1); + } + + @Test + @DisplayName("handler가 Retry로 답하면 예약이 롤백되어 다음 배달에서 다시 처리된다") + void aRetryAnswerRollsTheReservationBackSoTheNextDeliveryIsProcessed() { + // given + MessageDelivery delivery = delivery(MessageId.newId()); + List answers = + new ArrayList<>(List.of(new HandleResult.Retry(failure()), HandleResult.success())); + MessageHandler handler = wrap(ignored -> answers.removeFirst()); + HandleResult first = handler.handle(delivery).toCompletableFuture().join(); + + // when + HandleResult second = handler.handle(delivery).toCompletableFuture().join(); + + // then + assertThat(first).isInstanceOf(HandleResult.Retry.class); + assertThat(second).isInstanceOf(HandleResult.Success.class); + assertThat(effects).hasSize(2); + assertThat(inbox.reserved).hasSize(1); + } + + @Test + @DisplayName("handler가 예외를 던지면 예약이 롤백되고 실패한 stage로 전달된다") + void aThrowingHandlerRollsTheReservationBackAndFailsTheStage() { + // given + MessageHandler handler = + wrap( + ignored -> { + throw new IllegalStateException("database down"); + }); + + // when + CompletableFuture stage = + handler.handle(delivery(MessageId.newId())).toCompletableFuture(); + + // then + assertThat(stage).isCompletedExceptionally(); + assertThat(inbox.reserved).isEmpty(); + } + + private MessageHandler wrap(Function, HandleResult> body) { + MessageHandler business = + new MessageHandler<>() { + @Override + public MessageDestination destination() { + return new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class); + } + + @Override + public CompletionStage handle(MessageDelivery delivery) { + effects.add(delivery.message().payload()); + return CompletableFuture.completedFuture(body.apply(delivery)); + } + }; + return new InboxMessageHandler<>( + business, new IdempotentConsumer(inbox, inbox), "order-projection", () -> NOW); + } + + private static MessageDelivery delivery(MessageId id) { + return new MessageDelivery<>( + new MessageEnvelope<>( + id, + new MessageType("order.created"), + new SchemaVersion(1), + NOW, + Optional.empty(), + new ProducerId("orders"), + Optional.empty(), + Optional.empty(), + ContentType.JSON, + Optional.empty(), + Optional.empty(), + Optional.empty(), + TraceContext.none(), + MessageHeaders.empty(), + "o-1"), + new DeliveryMetadata( + ORDERS, 1, false, Optional.empty(), Optional.empty(), Optional.empty(), NOW), + new DeliveryContext(NOW.plusSeconds(30), false, "order-projection")); + } + + private static FailureDescriptor failure() { + return FailureDescriptor.of( + FailureCategory.PROCESSING_TRANSIENT, "DOWNSTREAM_BUSY", "try again later"); + } + + /** An inbox whose reservations disappear when the transaction around them throws. */ + private static final class RollbackInbox + implements InboxRepository, IdempotentConsumer.TransactionRunner { + + private final Set reserved = new LinkedHashSet<>(); + + @Override + public T inTransaction(Supplier work) { + Set before = new LinkedHashSet<>(reserved); + try { + return work.get(); + } catch (RuntimeException rolledBack) { + reserved.clear(); + reserved.addAll(before); + throw rolledBack; + } + } + + @Override + public boolean reserve(MessageId messageId, String consumerId, Instant now) { + return reserved.add(messageId.value() + "|" + consumerId); + } + + @Override + public boolean isProcessed(MessageId messageId, String consumerId) { + return reserved.contains(messageId.value() + "|" + consumerId); + } + + @Override + public int purgeProcessedBefore(Instant processedBefore, int limit) { + return 0; + } + } +} diff --git a/src/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/InboxOperationsTest.java b/src/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/InboxOperationsTest.java index b8228346..d019b694 100644 --- a/src/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/InboxOperationsTest.java +++ b/src/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/inbox/InboxOperationsTest.java @@ -7,7 +7,6 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy; import dev.caskeleton.messaging.api.MessageId; import dev.caskeleton.messaging.api.error.MessagingConfigurationException; import dev.caskeleton.messaging.reliability.InboxRepository; -import dev.caskeleton.messaging.reliability.InboxResult; import java.time.Duration; import java.time.Instant; import java.util.ArrayList; @@ -139,15 +138,6 @@ class InboxOperationsTest { assertThat(redelivery.result()).isEmpty(); } - @Test - void anAlreadyAppliedMessageIsSafeToSettleButAClaimedOneIsNot() { - assertThat(InboxResult.APPLIED.isSafeToSettle()).isTrue(); - assertThat(InboxResult.ALREADY_APPLIED.isSafeToSettle()).isTrue(); - assertThat(InboxResult.CLAIMED_ELSEWHERE.isSafeToSettle()) - .as("the other transaction may still roll back, and this is the last copy") - .isFalse(); - } - /** Runs the work inline; the real runner opens a database transaction. */ private static final class DirectRunner implements IdempotentConsumer.TransactionRunner { diff --git a/src/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayTest.java b/src/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayTest.java index fdc8591c..62d45f81 100644 --- a/src/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayTest.java +++ b/src/messaging/messaging-reliability/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayTest.java @@ -24,7 +24,7 @@ import dev.caskeleton.messaging.api.publish.PublishEvidence; import dev.caskeleton.messaging.api.publish.PublishOptions; import dev.caskeleton.messaging.api.publish.PublishResult; import dev.caskeleton.messaging.api.publish.RoutingOutcome; -import dev.caskeleton.messaging.policy.CapabilityTier; +import dev.caskeleton.messaging.policy.ApiTier; import dev.caskeleton.messaging.policy.ConsumerPolicy; import dev.caskeleton.messaging.policy.DeadLetterPolicy; import dev.caskeleton.messaging.policy.DestinationProfile; @@ -630,7 +630,7 @@ final class RealPublisher { RetryPolicy.none(), DeadLetterPolicy.disabled(), PayloadPolicy.defaults(), - CapabilityTier.M1, + ApiTier.M1, false, false, false); diff --git a/src/messaging/messaging-runtime-core/build.gradle b/src/messaging/messaging-runtime-core/build.gradle index 5fb68290..06c462f0 100644 --- a/src/messaging/messaging-runtime-core/build.gradle +++ b/src/messaging/messaging-runtime-core/build.gradle @@ -11,7 +11,6 @@ plugins { // with an application-supplied fake would pass a context test while running none of them. dependencies { api project(':messaging:messaging-core-api') - api project(':messaging:messaging-schema-api') api project(':messaging:messaging-policy') api project(':messaging:messaging-transport-spi') api project(':messaging:messaging-security') diff --git a/src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessor.java b/src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessor.java index 7c9dfd76..4f1169db 100644 --- a/src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessor.java +++ b/src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessor.java @@ -1,110 +1,255 @@ package dev.caskeleton.messaging.runtime; import dev.caskeleton.messaging.api.MessageEnvelope; +import dev.caskeleton.messaging.api.MessageType; +import dev.caskeleton.messaging.api.delivery.DeliveryContext; +import dev.caskeleton.messaging.api.delivery.DeliveryGuarantee; import dev.caskeleton.messaging.api.delivery.HandleResult; +import dev.caskeleton.messaging.api.delivery.MessageDelivery; +import dev.caskeleton.messaging.api.delivery.MessageHandler; import dev.caskeleton.messaging.api.error.FailureCategory; import dev.caskeleton.messaging.api.error.FailureDescriptor; import dev.caskeleton.messaging.api.publish.PublishCompletion; import dev.caskeleton.messaging.api.settlement.SettlementResult; +import dev.caskeleton.messaging.policy.DestinationProfile; import dev.caskeleton.messaging.schema.EncodedMessage; +import dev.caskeleton.messaging.schema.MessageCodec; +import dev.caskeleton.messaging.schema.MessageCodecRegistry; import dev.caskeleton.messaging.transport.TransportDelivery; import java.time.Duration; +import java.time.InstantSource; +import java.util.HashMap; +import java.util.List; +import java.util.Map; import java.util.Objects; import java.util.Optional; import java.util.concurrent.CompletableFuture; import java.util.concurrent.CompletionStage; import java.util.concurrent.atomic.AtomicBoolean; -import java.util.function.Function; +import java.util.function.Supplier; /** - * Turns one handler outcome into exactly one broker settlement. + * Turns one still-encoded delivery into a typed {@link MessageHandler} call and exactly one broker + * settlement. * - *

Nothing connected {@code HandleResult} to a settlement. Each broker adapter decided for itself - * what a retry or a dead-letter meant, so "the platform decides when and in what order the - * settlement happens" — the comment on {@code TransportSettlement} — described a decision nobody - * made in one place. + *

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

Two rules are enforced here rather than left to each adapter: + *

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

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

How many times a requeued delivery comes back, and what happens when the attempts run out, is + * the transport's retry policy — {@code requeue} is a request, and the Kafka consumer counts it. */ public final class DefaultDeliveryProcessor { - private final Function, HandleResult> handler; - + private final DestinationProfile profile; + private final Map> handlers; + private final MessageCodecRegistry codecs; private final DeadLetterPublisher deadLetters; + private final String consumerId; + private final InstantSource clock; - private final Duration retryDelay; - + /** + * Creates a processor for one destination. + * + * @param profile the destination being consumed + * @param handlers the handlers for that destination, at most one per message type + * @param codecs decodes payloads by content type + * @param deadLetters publishes a delivery to the destination's dead-letter destination + * @param consumerId the stable, low-cardinality consumer identity handlers see + * @param clock the clock handler deadlines are measured on + */ public DefaultDeliveryProcessor( - Function, HandleResult> handler, + DestinationProfile profile, + List> handlers, + MessageCodecRegistry codecs, DeadLetterPublisher deadLetters, - Duration retryDelay) { - this.handler = Objects.requireNonNull(handler, "handler must not be null"); + String consumerId, + InstantSource clock) { + this.profile = Objects.requireNonNull(profile, "profile must not be null"); + this.codecs = Objects.requireNonNull(codecs, "codecs must not be null"); this.deadLetters = Objects.requireNonNull(deadLetters, "deadLetters must not be null"); - this.retryDelay = Objects.requireNonNull(retryDelay, "retryDelay must not be null"); - if (retryDelay.isNegative()) { - throw new IllegalArgumentException("a retry delay must not be negative"); + this.clock = Objects.requireNonNull(clock, "clock must not be null"); + if (consumerId == null || consumerId.isBlank()) { + throw new IllegalArgumentException("consumerId must not be blank"); } + this.consumerId = consumerId; + Map> byType = new HashMap<>(); + for (MessageHandler handler : Objects.requireNonNull(handlers, "handlers")) { + if (!handler.destination().name().equals(profile.name())) { + throw new IllegalArgumentException( + "handler for " + + handler.destination().name().value() + + " cannot consume " + + profile.name().value()); + } + if (byType.put(handler.destination().messageType(), handler) != null) { + throw new IllegalArgumentException( + "destination " + + profile.name().value() + + " has two handlers for " + + handler.destination().messageType().value() + + "; which one runs would depend on bean order"); + } + } + if (byType.isEmpty()) { + throw new IllegalArgumentException("a processor needs at least one handler"); + } + this.handlers = Map.copyOf(byType); } /** * Handles one delivery and settles it once. * - * @return a stage completing with the settlement the broker performed + * @param delivery the still-encoded delivery + * @return a stage completing once the settlement call has returned */ - public CompletionStage process(TransportDelivery delivery) { + public CompletionStage process(TransportDelivery delivery) { Objects.requireNonNull(delivery, "delivery must not be null"); OneShotSettlement settlement = new OneShotSettlement(delivery); - HandleResult result; - try { - result = handler.apply(delivery.envelope()); - } catch (RuntimeException handlerFailed) { - // A handler that threw is a retry, not a discard. Treating an exception as "this message is - // undeliverable" is how a transient bug in one consumer silently drops a day of traffic — - // and it is exactly what the Rabbit consumer did by folding handler exceptions into its - // deserialization-failure path. - return settlement.requeue(retryDelay); + MessageEnvelope envelope = delivery.envelope(); + MessageHandler handler = handlers.get(envelope.messageType()); + if (handler == null) { + return deadLetter( + delivery, + settlement, + FailureDescriptor.of( + FailureCategory.DESERIALIZATION, + "NO_HANDLER_FOR_MESSAGE_TYPE", + "no handler is registered for this message type on this destination")); } - if (result == null) { - return settlement.requeue(retryDelay); + return dispatch(handler, delivery, settlement); + } + + private CompletionStage dispatch( + MessageHandler handler, TransportDelivery delivery, OneShotSettlement settlement) { + MessageEnvelope envelope = delivery.envelope(); + T payload; + try { + MessageCodec codec = + codecs + .find(envelope.contentType()) + .orElseThrow( + () -> + new IllegalStateException( + "no codec for content type " + envelope.contentType().value())); + payload = + codec.decode( + envelope.messageType(), + envelope.schemaVersion(), + envelope.payload(), + handler.destination().payloadType()); + } catch (RuntimeException undecodable) { + return deadLetter( + delivery, + settlement, + new FailureDescriptor( + FailureCategory.DESERIALIZATION, + "PAYLOAD_UNDECODABLE", + false, + "the payload could not be decoded into the handler's type", + Optional.of(undecodable.getClass().getSimpleName()))); } + Duration timeout = profile.consumer().handlerTimeout(); + MessageDelivery typed = + new MessageDelivery<>( + envelope.withPayload(payload), + delivery.metadata(), + new DeliveryContext(clock.instant().plus(timeout), false, consumerId)); + + CompletionStage outcome; + try { + outcome = handler.handle(typed); + } catch (RuntimeException handlerFailed) { + // A handler that threw is a retry, not a discard. Treating an exception as "this message is + // undeliverable" is how a transient bug in one consumer silently drops a day of traffic. + return settlement.requeue(); + } + if (outcome == null) { + return settlement.requeue(); + } + return outcome + .handle( + (result, failure) -> + failure == null ? Optional.ofNullable(result) : Optional.empty()) + .thenCompose( + result -> + result.isEmpty() + ? settlement.requeue() + : settle(result.get(), delivery, settlement)); + } + + private CompletionStage settle( + HandleResult result, TransportDelivery delivery, OneShotSettlement settlement) { return switch (result) { case HandleResult.Success ignored -> settlement.acknowledge(); - case HandleResult.Retry ignored -> settlement.requeue(retryDelay); - case HandleResult.Reject ignored -> settlement.discard(); + case HandleResult.Retry ignored -> settlement.requeue(); + case HandleResult.Reject reject -> + profile.deliveryGuarantee() == DeliveryGuarantee.AT_MOST_ONCE + ? settlement.discard() + // Discarding on an at-least-once destination would drop a message the profile + // promised to deliver, so the rejection is kept where someone can look at it. + : deadLetter(delivery, settlement, reject.failure()); case HandleResult.DeadLetter deadLetter -> - deadLetters - .publish(delivery.envelope(), deadLetter.failure()) - .thenCompose( - completion -> - completion == PublishCompletion.CONFIRMED - // Confirmed: the message exists somewhere else, so removing it here is - // safe. - ? settlement.acknowledge() - // Not confirmed — rejected or ambiguous. Requeueing risks a duplicate; - // acknowledging loses the message outright, and a duplicate is the - // recoverable half of that choice. - : settlement.requeue(retryDelay)); + deadLetter(delivery, settlement, deadLetter.failure()); }; } + private CompletionStage deadLetter( + TransportDelivery delivery, OneShotSettlement settlement, FailureDescriptor failure) { + if (!profile.deadLetter().enabled()) { + // Nowhere to put it. Requeueing keeps the only copy; the transport's retry budget decides + // whether the partition then parks it or keeps it. + return settlement.requeue(); + } + MessageDelivery encoded = + new MessageDelivery<>( + delivery.envelope(), + delivery.metadata(), + new DeliveryContext(clock.instant(), false, consumerId)); + CompletionStage published; + try { + published = deadLetters.publish(encoded, failure); + } catch (RuntimeException publishFailed) { + return settlement.requeue(); + } + return published + .handle((completion, error) -> error == null && completion == PublishCompletion.CONFIRMED) + .thenCompose(confirmed -> confirmed ? settlement.acknowledge() : settlement.requeue()); + } + /** Publishes a delivery that cannot be handled to its dead-letter destination. */ @FunctionalInterface public interface DeadLetterPublisher { - /** Publishes and reports what the broker confirmed. */ + /** + * Publishes and reports what the broker confirmed. + * + * @param delivery the delivery, still encoded + * @param failure why it is being dead-lettered + * @return a stage completing with the publish completion + */ CompletionStage publish( - MessageEnvelope envelope, FailureDescriptor failure); + MessageDelivery delivery, FailureDescriptor failure); } /** A settlement that can be used once. */ @@ -118,20 +263,21 @@ public final class DefaultDeliveryProcessor { this.delivery = delivery; } - private CompletionStage acknowledge() { + private CompletionStage acknowledge() { return once("acknowledge", () -> delivery.settlement().acknowledge()); } - private CompletionStage requeue(Duration delay) { - return once("requeue", () -> delivery.settlement().requeue(delay)); + private CompletionStage requeue() { + // The delay is the transport's retry policy; zero asks for "as soon as that policy allows". + return once("requeue", () -> delivery.settlement().requeue(Duration.ZERO)); } - private CompletionStage discard() { + private CompletionStage discard() { return once("discard", () -> delivery.settlement().discard()); } - private CompletionStage once( - String what, java.util.function.Supplier> call) { + private CompletionStage once( + String what, Supplier> call) { if (!settled.compareAndSet(false, true)) { return CompletableFuture.failedFuture( new IllegalStateException( @@ -139,17 +285,7 @@ public final class DefaultDeliveryProcessor { + what + " would tell the broker something the first call already contradicted")); } - return call.get(); + return call.get().thenApply(ignored -> null); } } - - /** A descriptor for a handler that returned nothing, kept out of the hot path. */ - static FailureDescriptor missingResult() { - return new FailureDescriptor( - FailureCategory.PROCESSING_TRANSIENT, - "HANDLER_RETURNED_NOTHING", - true, - "the handler returned no result, which is treated as a retry rather than a discard", - Optional.empty()); - } } diff --git a/src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java b/src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java index 46c75462..0f6d9e29 100644 --- a/src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java +++ b/src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java @@ -5,11 +5,8 @@ import dev.caskeleton.messaging.api.destination.MessageDestination; import dev.caskeleton.messaging.api.error.FailureCategory; import dev.caskeleton.messaging.api.error.FailureDescriptor; import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishEvidence; import dev.caskeleton.messaging.api.publish.PublishOptions; import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.api.publish.RoutingOutcome; import dev.caskeleton.messaging.policy.DestinationProfile; import dev.caskeleton.messaging.policy.MessagingAdmissionController; import dev.caskeleton.messaging.schema.EncodedMessage; @@ -288,7 +285,12 @@ public final class DefaultMessagePublisher implements MessagePublisher, EncodedM */ private void requireSupportedOptions(DestinationProfile profile, PublishOptions options) { if (options.deduplication().isPresent() - && !transport.capabilities(profile.name()).capabilities().deduplicatedPublish()) { + && !transport + .capabilities(profile.name()) + .capabilities() + .supports( + dev.caskeleton.messaging.api.destination.MessagingCapabilities.Capability + .DEDUPLICATED_PUBLISH)) { throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException( "PUBLISH_DEDUPLICATION_UNSUPPORTED", "destination '" @@ -332,27 +334,13 @@ public final class DefaultMessagePublisher implements MessagePublisher, EncodedM private CompletionStage refused(FailureDescriptor failure, long startedAt) { return CompletableFuture.completedFuture( - new PublishResult( - PublishCompletion.REJECTED, - PublishEvidence.notTransmitted(), - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, - elapsedSince(startedAt), - Optional.of(failure))); + PublishResult.rejected(elapsedSince(startedAt), failure)); } private PublishResult ambiguousResult(String code, String reason, long startedAt) { - return new PublishResult( - PublishCompletion.AMBIGUOUS, - PublishEvidence.ambiguous(), - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, + return PublishResult.ambiguous( elapsedSince(startedAt), - Optional.of( - new FailureDescriptor( - FailureCategory.AMBIGUOUS, code, true, reason, Optional.empty()))); + new FailureDescriptor(FailureCategory.AMBIGUOUS, code, true, reason, Optional.empty())); } /** diff --git a/src/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessorTest.java b/src/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessorTest.java index 9b2d007b..8cff2f21 100644 --- a/src/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessorTest.java +++ b/src/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessorTest.java @@ -1,6 +1,7 @@ package dev.caskeleton.messaging.runtime; import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.messaging.api.ContentType; import dev.caskeleton.messaging.api.MessageEnvelope; @@ -9,123 +10,318 @@ import dev.caskeleton.messaging.api.MessageType; import dev.caskeleton.messaging.api.ProducerId; import dev.caskeleton.messaging.api.SchemaVersion; import dev.caskeleton.messaging.api.TraceContext; +import dev.caskeleton.messaging.api.delivery.DeliveryGuarantee; import dev.caskeleton.messaging.api.delivery.DeliveryMetadata; import dev.caskeleton.messaging.api.delivery.HandleResult; +import dev.caskeleton.messaging.api.delivery.MessageDelivery; +import dev.caskeleton.messaging.api.delivery.MessageHandler; +import dev.caskeleton.messaging.api.destination.DestinationName; +import dev.caskeleton.messaging.api.destination.MessageDestination; import dev.caskeleton.messaging.api.error.FailureCategory; import dev.caskeleton.messaging.api.error.FailureDescriptor; import dev.caskeleton.messaging.api.header.MessageHeaders; import dev.caskeleton.messaging.api.publish.PublishCompletion; import dev.caskeleton.messaging.api.settlement.SettlementResult; +import dev.caskeleton.messaging.policy.DeadLetterPolicy; +import dev.caskeleton.messaging.policy.DestinationProfile; import dev.caskeleton.messaging.schema.EncodedMessage; +import dev.caskeleton.messaging.schema.MessageCodec; import dev.caskeleton.messaging.transport.TransportDelivery; import dev.caskeleton.messaging.transport.TransportSettlement; import java.nio.charset.StandardCharsets; import java.time.Duration; import java.time.Instant; +import java.time.InstantSource; import java.util.ArrayList; import java.util.List; import java.util.Optional; import java.util.concurrent.CompletableFuture; import java.util.concurrent.CompletionStage; +import java.util.function.Function; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; /** - * One handler outcome, one settlement. + * One typed handler, one outcome, one settlement. * - *

Nothing turned a {@code HandleResult} into a settlement: each broker adapter decided for - * itself, and the Rabbit consumer folded handler exceptions into its deserialization-failure path - * and discarded them. + *

The processor took an untyped function and nothing assembled it; the typed {@code + * MessageHandler} had no caller (S7-#2). These tests hold the settlement rules on the one contract + * that is left. */ class DefaultDeliveryProcessorTest { + private static final DestinationName ORDERS = new DestinationName("order-events"); + private static final MessageType CREATED = new MessageType("order.created"); + private static final Instant NOW = Instant.parse("2026-08-14T00:00:00Z"); + private final RecordingSettlement settlement = new RecordingSettlement(); @Test - @DisplayName("success acknowledges once") - void successAcknowledgesOnce() { - process(envelope -> new HandleResult.Success(), confirmedDeadLetters()); + @DisplayName("성공하면 handler가 decode된 payload를 받고 한 번 acknowledge된다") + void aSuccessfulHandlerReceivesTheDecodedPayloadAndIsAcknowledgedOnce() { + // given + List received = new ArrayList<>(); + MessageHandler handler = + handler( + delivery -> { + received.add(delivery.message().payload()); + return HandleResult.success(); + }); + // when + process(handler, confirmedDeadLetters(), RuntimeFixtures.profile(ORDERS)); + + // then + assertThat(received).containsExactly("{\"orderId\":\"o-1\"}"); assertThat(settlement.calls()).containsExactly("acknowledge"); } @Test - @DisplayName("retry requeues with the configured delay") - void retryRequeues() { - process(envelope -> new HandleResult.Retry(failure()), confirmedDeadLetters()); + @DisplayName("Retry 결과는 requeue된다") + void aRetryResultIsRequeued() { + // when + process( + handler(delivery -> new HandleResult.Retry(failure())), + confirmedDeadLetters(), + RuntimeFixtures.profile(ORDERS)); + // then assertThat(settlement.calls()).containsExactly("requeue"); } @Test - @DisplayName("a handler that throws is retried, not discarded") - void aThrowingHandlerIsRetried() { + @DisplayName("예외를 던진 handler는 버려지지 않고 requeue된다") + void aThrowingHandlerIsRequeuedNotDiscarded() { + // when process( - envelope -> { - throw new IllegalStateException("a bug in the projection"); - }, - confirmedDeadLetters()); + handler( + delivery -> { + throw new IllegalStateException("a bug in the projection"); + }), + confirmedDeadLetters(), + RuntimeFixtures.profile(ORDERS)); - assertThat(settlement.calls()) - .as("treating an exception as undeliverable drops a day of traffic over a transient bug") - .containsExactly("requeue"); + // then + assertThat(settlement.calls()).containsExactly("requeue"); } @Test - @DisplayName("a dead letter is published before the source is acknowledged") - void aDeadLetterIsPublishedBeforeAcknowledgement() { + @DisplayName("실패로 끝난 stage를 돌려준 handler는 requeue된다") + void aHandlerWhoseStageFailsIsRequeued() { + // given + MessageHandler handler = + new StringHandler( + delivery -> { + throw new UnsupportedOperationException("unused"); + }) { + @Override + public CompletionStage handle(MessageDelivery delivery) { + return CompletableFuture.failedFuture(new IllegalStateException("database down")); + } + }; + + // when + process(handler, confirmedDeadLetters(), RuntimeFixtures.profile(ORDERS)); + + // then + assertThat(settlement.calls()).containsExactly("requeue"); + } + + @Test + @DisplayName("dead letter는 발행이 확인된 뒤에 source를 acknowledge한다") + void aDeadLetterIsPublishedBeforeTheSourceIsAcknowledged() { + // given List order = new ArrayList<>(); DefaultDeliveryProcessor.DeadLetterPublisher publisher = - (envelope, failure) -> { + (delivery, failure) -> { order.add("dead-letter published"); return CompletableFuture.completedFuture(PublishCompletion.CONFIRMED); }; settlement.recordInto(order); - process(envelope -> new HandleResult.DeadLetter(failure()), publisher); + // when + process( + handler(delivery -> new HandleResult.DeadLetter(failure())), + publisher, + RuntimeFixtures.profile(ORDERS)); + // then assertThat(order).containsExactly("dead-letter published", "acknowledge"); } @Test - @DisplayName("an unconfirmed dead letter requeues rather than acknowledging") - void anUnconfirmedDeadLetterRequeues() { + @DisplayName("확인되지 않은 dead letter는 acknowledge하지 않고 requeue한다") + void anUnconfirmedDeadLetterIsRequeued() { + // when process( - envelope -> new HandleResult.DeadLetter(failure()), - (envelope, failure) -> CompletableFuture.completedFuture(PublishCompletion.AMBIGUOUS)); + handler(delivery -> new HandleResult.DeadLetter(failure())), + (delivery, failure) -> CompletableFuture.completedFuture(PublishCompletion.AMBIGUOUS), + RuntimeFixtures.profile(ORDERS)); - assertThat(settlement.calls()) - .as("acknowledging loses the message outright; a duplicate is the recoverable half") - .containsExactly("requeue"); + // then + assertThat(settlement.calls()).containsExactly("requeue"); } @Test - @DisplayName("a rejected message is discarded") - void aRejectedMessageIsDiscarded() { - process(envelope -> new HandleResult.Reject(failure()), confirmedDeadLetters()); + @DisplayName("at-least-once destination의 Reject는 버리지 않고 dead letter로 보낸다") + void aRejectOnAnAtLeastOnceDestinationIsDeadLetteredNotDiscarded() { + // given + List deadLettered = new ArrayList<>(); + // when + process( + handler(delivery -> new HandleResult.Reject(failure())), + (delivery, failure) -> { + deadLettered.add(failure); + return CompletableFuture.completedFuture(PublishCompletion.CONFIRMED); + }, + RuntimeFixtures.profile(ORDERS)); + + // then + assertThat(deadLettered).containsExactly(failure()); + assertThat(settlement.calls()).containsExactly("acknowledge"); + } + + @Test + @DisplayName("at-most-once destination의 Reject는 discard된다") + void aRejectOnAnAtMostOnceDestinationIsDiscarded() { + // when + process( + handler(delivery -> new HandleResult.Reject(failure())), + confirmedDeadLetters(), + atMostOnce(RuntimeFixtures.profile(ORDERS))); + + // then assertThat(settlement.calls()).containsExactly("discard"); } @Test - @DisplayName("a handler returning nothing is retried") - void aHandlerReturningNothingIsRetried() { - process(envelope -> null, confirmedDeadLetters()); + @DisplayName("handler가 없는 message type은 재시도하지 않고 dead letter로 보낸다") + void aMessageTypeWithNoHandlerIsDeadLetteredInsteadOfRetried() { + // given + List codes = new ArrayList<>(); + MessageHandler otherType = + new StringHandler( + new MessageDestination<>(ORDERS, new MessageType("order.cancelled"), String.class), + delivery -> HandleResult.success()); + // when + process( + otherType, + (delivery, failure) -> { + codes.add(failure.code()); + return CompletableFuture.completedFuture(PublishCompletion.CONFIRMED); + }, + RuntimeFixtures.profile(ORDERS)); + + // then + assertThat(codes).containsExactly("NO_HANDLER_FOR_MESSAGE_TYPE"); + assertThat(settlement.calls()).containsExactly("acknowledge"); + } + + @Test + @DisplayName("dead letter destination이 없으면 dead letter 대신 requeue해 유일한 사본을 지킨다") + void withoutADeadLetterDestinationADeadLetterIsRequeuedToKeepTheOnlyCopy() { + // when + process( + handler(delivery -> new HandleResult.DeadLetter(failure())), + confirmedDeadLetters(), + withoutDeadLetter(RuntimeFixtures.profile(ORDERS))); + + // then assertThat(settlement.calls()).containsExactly("requeue"); } + @Test + @DisplayName("한 message type에 handler가 둘이면 processor를 만들 수 없다") + void twoHandlersForOneMessageTypeAreRefused() { + // given + List> twice = + List.of(handler(delivery -> HandleResult.success()), handler(delivery -> null)); + + // when + Throwable thrown = + catchThrowable( + () -> + new DefaultDeliveryProcessor( + RuntimeFixtures.profile(ORDERS), + twice, + RegisteredMessageCodecs.of(new Utf8Codec()), + confirmedDeadLetters(), + "order-projection", + InstantSource.fixed(NOW))); + + // then + assertThat(thrown) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("two handlers for order.created"); + } + private void process( - java.util.function.Function, HandleResult> handler, - DefaultDeliveryProcessor.DeadLetterPublisher deadLetters) { - new DefaultDeliveryProcessor(handler, deadLetters, Duration.ofSeconds(5)) + MessageHandler handler, + DefaultDeliveryProcessor.DeadLetterPublisher deadLetters, + DestinationProfile profile) { + new DefaultDeliveryProcessor( + profile, + List.of(handler), + RegisteredMessageCodecs.of(new Utf8Codec()), + deadLetters, + "order-projection", + InstantSource.fixed(NOW)) .process(new TransportDelivery(envelope(), metadata(), settlement)) .toCompletableFuture() .join(); } + private static MessageHandler handler( + Function, HandleResult> body) { + return new StringHandler(body); + } + private static DefaultDeliveryProcessor.DeadLetterPublisher confirmedDeadLetters() { - return (envelope, failure) -> CompletableFuture.completedFuture(PublishCompletion.CONFIRMED); + return (delivery, failure) -> CompletableFuture.completedFuture(PublishCompletion.CONFIRMED); + } + + private static DestinationProfile atMostOnce(DestinationProfile base) { + return new DestinationProfile( + base.name(), + base.broker(), + base.kind(), + base.physical(), + base.schema(), + DeliveryGuarantee.AT_MOST_ONCE, + base.orderingScope(), + base.externalSideEffectGuarantee(), + base.producer(), + base.consumer(), + base.retry(), + base.deadLetter(), + base.payload(), + base.tier(), + base.production(), + base.keyResolverConfigured(), + base.topologyAutoCreate()); + } + + private static DestinationProfile withoutDeadLetter(DestinationProfile base) { + return new DestinationProfile( + base.name(), + base.broker(), + base.kind(), + base.physical(), + base.schema(), + base.deliveryGuarantee(), + base.orderingScope(), + base.externalSideEffectGuarantee(), + base.producer(), + base.consumer(), + base.retry(), + DeadLetterPolicy.disabled(), + base.payload(), + base.tier(), + base.production(), + base.keyResolverConfigured(), + base.topologyAutoCreate()); } private static FailureDescriptor failure() { @@ -139,21 +335,15 @@ class DefaultDeliveryProcessorTest { private static DeliveryMetadata metadata() { return new DeliveryMetadata( - new dev.caskeleton.messaging.api.destination.DestinationName("order-events"), - 1, - false, - Optional.empty(), - Optional.empty(), - Optional.of("order-projection"), - Instant.parse("2026-08-14T00:00:00Z")); + ORDERS, 1, false, Optional.empty(), Optional.empty(), Optional.of("order-projection"), NOW); } private static MessageEnvelope envelope() { return new MessageEnvelope<>( MessageId.newId(), - new MessageType("order.created"), + CREATED, new SchemaVersion(1), - Instant.parse("2026-08-14T00:00:00Z"), + NOW, Optional.empty(), new ProducerId("orders"), Optional.empty(), @@ -165,7 +355,58 @@ class DefaultDeliveryProcessorTest { TraceContext.none(), MessageHeaders.empty(), new EncodedMessage( - "{}".getBytes(StandardCharsets.UTF_8), ContentType.JSON, Optional.empty())); + "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), + ContentType.JSON, + Optional.empty())); + } + + /** A handler for {@code order.created} whose body is a function. */ + private static class StringHandler implements MessageHandler { + + private final MessageDestination destination; + private final Function, HandleResult> body; + + StringHandler(Function, HandleResult> body) { + this(new MessageDestination<>(ORDERS, CREATED, String.class), body); + } + + StringHandler( + MessageDestination destination, + Function, HandleResult> body) { + this.destination = destination; + this.body = body; + } + + @Override + public MessageDestination destination() { + return destination; + } + + @Override + public CompletionStage handle(MessageDelivery delivery) { + return CompletableFuture.completedFuture(body.apply(delivery)); + } + } + + /** Decodes JSON bytes to the raw string, which is all these tests need. */ + private static final class Utf8Codec implements MessageCodec { + + @Override + public ContentType contentType() { + return ContentType.JSON; + } + + @Override + public EncodedMessage encode(MessageType type, SchemaVersion version, Object payload) { + return new EncodedMessage( + payload.toString().getBytes(StandardCharsets.UTF_8), ContentType.JSON, Optional.empty()); + } + + @Override + public T decode( + MessageType type, SchemaVersion version, byte[] encoded, Class payloadType) { + return payloadType.cast(new String(encoded, StandardCharsets.UTF_8)); + } } /** Records which terminal call the processor made, and in what order. */ diff --git a/src/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/RuntimeFixtures.java b/src/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/RuntimeFixtures.java index 6509b885..d341d54f 100644 --- a/src/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/RuntimeFixtures.java +++ b/src/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/RuntimeFixtures.java @@ -3,7 +3,7 @@ package dev.caskeleton.messaging.runtime; import dev.caskeleton.messaging.api.ContentType; import dev.caskeleton.messaging.api.MessageType; import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.policy.CapabilityTier; +import dev.caskeleton.messaging.policy.ApiTier; import dev.caskeleton.messaging.policy.ConsumerPolicy; import dev.caskeleton.messaging.policy.DeadLetterPolicy; import dev.caskeleton.messaging.policy.DestinationProfile; @@ -36,7 +36,7 @@ final class RuntimeFixtures { dev.caskeleton.messaging.policy.RetryPolicy.none(), DeadLetterPolicy.to(new DestinationName("order-events-dlq")), PayloadPolicy.defaults(), - CapabilityTier.M1, + ApiTier.M1, false, false, false); diff --git a/src/messaging/messaging-schema-api/build.gradle b/src/messaging/messaging-schema-api/build.gradle deleted file mode 100644 index fac7b208..00000000 --- a/src/messaging/messaging-schema-api/build.gradle +++ /dev/null @@ -1,7 +0,0 @@ -plugins { - id 'ca.platform-module' -} - -dependencies { - api project(':messaging:messaging-core-api') -} diff --git a/src/messaging/messaging-schema-api/gradle.lockfile b/src/messaging/messaging-schema-api/gradle.lockfile deleted file mode 100644 index e2c95854..00000000 --- a/src/messaging/messaging-schema-api/gradle.lockfile +++ /dev/null @@ -1,84 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.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 diff --git a/src/messaging/messaging-schema-avro/build.gradle b/src/messaging/messaging-schema-avro/build.gradle index 4044538f..b1e8f846 100644 --- a/src/messaging/messaging-schema-avro/build.gradle +++ b/src/messaging/messaging-schema-avro/build.gradle @@ -4,7 +4,6 @@ plugins { dependencies { api project(':messaging:messaging-core-api') - api project(':messaging:messaging-schema-api') // api: AvroMessageCodec's constructors take a registry of org.apache.avro.Schema and // AvroCompatibilityGate.check takes and compares them. A consumer cannot build that diff --git a/src/messaging/messaging-schema-json/build.gradle b/src/messaging/messaging-schema-json/build.gradle index aebe0fe5..e87b8c57 100644 --- a/src/messaging/messaging-schema-json/build.gradle +++ b/src/messaging/messaging-schema-json/build.gradle @@ -4,7 +4,6 @@ plugins { dependencies { api project(':messaging:messaging-core-api') - api project(':messaging:messaging-schema-api') implementation 'tools.jackson.core:jackson-databind' } diff --git a/src/messaging/messaging-schema-protobuf/build.gradle b/src/messaging/messaging-schema-protobuf/build.gradle index 3c431b43..58f78aac 100644 --- a/src/messaging/messaging-schema-protobuf/build.gradle +++ b/src/messaging/messaging-schema-protobuf/build.gradle @@ -4,7 +4,6 @@ plugins { dependencies { api project(':messaging:messaging-core-api') - api project(':messaging:messaging-schema-api') // api: ProtobufMessageContract is a public record over com.google.protobuf.Message and // Parser, and registering a contract is the first thing a consumer of this codec does. diff --git a/src/messaging/messaging-spring-boot-starter-kafka/build.gradle b/src/messaging/messaging-spring-boot-starter-kafka/build.gradle index 9333a84b..a985d71f 100644 --- a/src/messaging/messaging-spring-boot-starter-kafka/build.gradle +++ b/src/messaging/messaging-spring-boot-starter-kafka/build.gradle @@ -8,6 +8,8 @@ dependencies { // Kafka client classes. api project(':messaging:messaging-spring-boot-starter') api project(':messaging:messaging-kafka') + // KafkaConsumerConfiguration's public consumer-factory seam names kafka-clients types. + api 'org.apache.kafka:kafka-clients' implementation 'org.springframework.boot:spring-boot-autoconfigure' } diff --git a/src/messaging/messaging-spring-boot-starter-kafka/gradle.lockfile b/src/messaging/messaging-spring-boot-starter-kafka/gradle.lockfile index ffc42112..3e1b642d 100644 --- a/src/messaging/messaging-spring-boot-starter-kafka/gradle.lockfile +++ b/src/messaging/messaging-spring-boot-starter-kafka/gradle.lockfile @@ -39,7 +39,6 @@ io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotatio io.micrometer:micrometer-commons:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath io.micrometer:micrometer-core:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath io.micrometer:micrometer-observation:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.projectreactor:reactor-core:3.8.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor jaxen:jaxen:2.0.6=spotbugs net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath @@ -87,7 +86,6 @@ 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.reactivestreams:reactive-streams:1.0.4=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath org.reflections:reflections:0.10.2=checkstyle org.slf4j:slf4j-api:2.0.18=runtimeClasspath,spotbugs,spotbugsSlf4j,testRuntimeClasspath org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j diff --git a/src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerCatalog.java b/src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerCatalog.java new file mode 100644 index 00000000..726df06f --- /dev/null +++ b/src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerCatalog.java @@ -0,0 +1,37 @@ +package dev.caskeleton.messaging.autoconfigure; + +import java.util.LinkedHashMap; +import java.util.Map; +import java.util.Objects; + +/** + * The Kafka client settings of every {@code app.messaging.brokers} entry of type {@code kafka}. + * + * @param brokers the Kafka settings, keyed by logical broker name, in declaration order + */ +public record KafkaBrokerCatalog(Map brokers) { + + public KafkaBrokerCatalog { + brokers = + java.util.Collections.unmodifiableMap( + new LinkedHashMap<>(Objects.requireNonNull(brokers, "brokers must not be null"))); + } + + /** + * The one Kafka broker the producer and the consumers connect to. + * + * @return its logical name and settings + * @throws IllegalStateException unless exactly one Kafka entry is configured + */ + public Map.Entry single() { + if (brokers.size() != 1) { + throw new IllegalStateException( + "app.messaging.broker=kafka needs exactly one app.messaging.brokers. entry with" + + " type kafka and its bootstrap-servers; found " + + brokers.size() + + ". A producer with no broker address defaults to localhost:9092 and fails at the" + + " first publish rather than at startup"); + } + return brokers.entrySet().iterator().next(); + } +} diff --git a/src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerSettings.java b/src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerSettings.java new file mode 100644 index 00000000..5f380359 --- /dev/null +++ b/src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaBrokerSettings.java @@ -0,0 +1,86 @@ +package dev.caskeleton.messaging.autoconfigure; + +import java.time.Duration; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Locale; +import java.util.Map; +import java.util.Objects; +import org.springframework.boot.context.properties.bind.Bindable; +import org.springframework.boot.context.properties.bind.Binder; +import org.springframework.boot.context.properties.bind.DefaultValue; +import org.springframework.core.env.Environment; + +/** + * The Kafka client part of one {@code app.messaging.brokers.} entry of type {@code kafka}. + * + *

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

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

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

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

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

It answers {@code true} only once the broker has acknowledged the copy. The consumer commits + * past the source offset on that answer, so an unconfirmed write must say {@code false} and leave + * the source to be read again. + */ +final class KafkaDeadLetterQuarantine implements KafkaQuarantinePublisher { + + private final Producer producer; + private final String topic; + private final Duration timeout; + + KafkaDeadLetterQuarantine(Producer producer, String topic, Duration timeout) { + this.producer = Objects.requireNonNull(producer, "producer must not be null"); + this.topic = Objects.requireNonNull(topic, "topic must not be null"); + this.timeout = Objects.requireNonNull(timeout, "timeout must not be null"); + } + + @Override + public boolean quarantine(ConsumerRecord record, Throwable reason) { + RecordHeaders headers = new RecordHeaders(record.headers().toArray()); + headers.remove(ReservedHeaders.FAILURE_CATEGORY); + headers.remove(ReservedHeaders.FAILURE_CODE); + headers.add(ReservedHeaders.FAILURE_CATEGORY, bytes("POISON_MESSAGE")); + headers.add( + ReservedHeaders.FAILURE_CODE, + bytes(reason == null ? "UNKNOWN" : reason.getClass().getSimpleName())); + try { + producer + .send(new ProducerRecord<>(topic, null, record.key(), record.value(), headers)) + .get(timeout.toMillis(), TimeUnit.MILLISECONDS); + return true; + } catch (InterruptedException interrupted) { + Thread.currentThread().interrupt(); + return false; + } catch (ExecutionException | TimeoutException | RuntimeException notConfirmed) { + return false; + } + } + + private static byte[] bytes(String value) { + return value.getBytes(StandardCharsets.UTF_8); + } +} diff --git a/src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java b/src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java index 49a1ccb8..05eadb6b 100644 --- a/src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java +++ b/src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java @@ -30,6 +30,7 @@ import org.springframework.context.annotation.Configuration; * assembled. */ @Configuration(proxyBeanMethods = false) +@org.springframework.context.annotation.Import(KafkaConsumerConfiguration.class) public class KafkaMessagingAutoConfiguration { /** @@ -62,15 +63,31 @@ public class KafkaMessagingAutoConfiguration { kafkaProfileStartupValidation( ObjectProvider profiles, CompiledMessagingConfiguration compiled, + KafkaBrokerCatalog catalog, KafkaProfileValidator validator) { return new StartupProfileValidation<>( () -> java.util.stream.Stream.concat( - configuredKafkaProfiles(compiled).stream(), profiles.orderedStream()) + configuredKafkaProfiles(compiled, catalog).stream(), profiles.orderedStream()) .toList(), validator::validate); } + /** + * The Kafka client settings of every Kafka broker entry, bound by this starter (S7-#9b). + * + * @param environment the resolved environment + * @param compiled the compiled configuration naming the Kafka entries + * @return the catalog + */ + @Bean + @ConditionalOnMissingBean + public KafkaBrokerCatalog kafkaBrokerCatalog( + org.springframework.core.env.Environment environment, + CompiledMessagingConfiguration compiled) { + return new KafkaBrokerCatalog(KafkaBrokerSettings.bindAll(environment, compiled)); + } + /** * Returns the Kafka transaction profile validator. * @@ -138,18 +155,20 @@ public class KafkaMessagingAutoConfiguration { @ConditionalOnMissingBean public org.apache.kafka.clients.producer.Producer messagingKafkaProducer( CompiledMessagingConfiguration compiled, + KafkaBrokerCatalog catalog, ObjectProvider declaredSecurity, ObjectProvider securityConfigurer) { return new org.apache.kafka.clients.producer.KafkaProducer<>( - producerConfig(compiled, declaredSecurity, securityConfigurer)); + producerConfig(compiled, catalog, declaredSecurity, securityConfigurer)); } /** The producer's client configuration; package-visible so a test can read what it holds. */ static java.util.Map producerConfig( CompiledMessagingConfiguration compiled, + KafkaBrokerCatalog catalog, ObjectProvider declaredSecurity, ObjectProvider securityConfigurer) { - BrokerSettings broker = kafkaBroker(compiled); + KafkaBrokerSettings broker = catalog.single().getValue(); java.util.Map config = new java.util.HashMap<>(); config.put( org.apache.kafka.clients.producer.ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, @@ -185,38 +204,29 @@ public class KafkaMessagingAutoConfiguration { config.put( org.apache.kafka.clients.producer.ProducerConfig.MAX_BLOCK_MS_CONFIG, dev.caskeleton.messaging.api.publish.PublishOptions.defaults().timeout().toMillis()); - config.putAll(producerSecurity(compiled, declaredSecurity, securityConfigurer)); + config.putAll( + clientSecurity( + compiled, declaredSecurity, securityConfigurer, BrokerSecurityProfile::producer)); return config; } - /** The one Kafka broker entry the producer connects to. */ - private static BrokerSettings kafkaBroker(CompiledMessagingConfiguration compiled) { - java.util.List kafka = - compiled.brokers().values().stream() - .filter(broker -> BrokerSettings.KAFKA.equalsIgnoreCase(broker.type())) - .toList(); - if (kafka.size() != 1) { - throw new IllegalStateException( - "app.messaging.broker=kafka needs exactly one app.messaging.brokers. entry with" - + " type kafka and its bootstrap-servers; found " - + kafka.size() - + ". A producer with no broker address defaults to localhost:9092 and fails at the" - + " first publish rather than at startup"); - } - return kafka.getFirst(); - } - /** - * The producer's security properties, from the one security profile of the Kafka broker. + * A client's security properties, from the one security profile of the Kafka broker. * *

{@code KafkaSecurityConfigurer} was a bean nothing called, so a broker that passed the TLS * and credential checks was reached over plaintext with no authentication. Every case that cannot - * be applied fails startup rather than falling back to that. + * be applied fails startup rather than falling back to that. The producer and the consumers use + * the same rule, each with its own credential. + * + * @param role picks the producer or the consumer credential of the profile */ - private static java.util.Map producerSecurity( + static java.util.Map clientSecurity( CompiledMessagingConfiguration compiled, ObjectProvider declaredSecurity, - ObjectProvider securityConfigurer) { + ObjectProvider securityConfigurer, + java.util.function.Function< + BrokerSecurityProfile, dev.caskeleton.messaging.security.BrokerCredentialProfile> + role) { java.util.Map kafkaBrokers = new java.util.TreeMap<>(); compiled.brokers().entrySet().stream() .filter(entry -> BrokerSettings.KAFKA.equalsIgnoreCase(entry.getValue().type())) @@ -239,14 +249,14 @@ public class KafkaMessagingAutoConfiguration { + name + "' enables TLS or authentication but has no app.messaging.security." + name - + " entry; the producer cannot apply either without one"); + + " entry; a Kafka client cannot apply either without one"); } }); return java.util.Map.of(); } if (profiles.size() > 1) { throw new IllegalStateException( - "the Kafka producer has one security posture but " + "a Kafka client has one security posture but " + profiles.size() + " security profiles match " + names); @@ -257,50 +267,53 @@ public class KafkaMessagingAutoConfiguration { throw new IllegalStateException( "app.messaging.security." + profile.broker() - + " is configured but no CredentialProvider bean exists; the producer cannot" + + " is configured but no CredentialProvider bean exists; a Kafka client cannot" + " resolve its credential and must not connect without it"); } return configurer.configure( - profile, profile.producer(), TLS_PROTOCOLS, java.time.Instant.now()); + profile, role.apply(profile), TLS_PROTOCOLS, java.time.Instant.now()); } /** - * The Kafka transport the publisher writes through. + * The Kafka transport the publisher writes through and the consumers subscribe through. + * + *

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

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

{@link #close()} stops dispatching, lets running handlers finish up to the drain deadline, + * commits what they settled and closes the client. Work still running at the deadline is abandoned + * unsettled, so the broker redelivers it rather than the platform pretending it completed. + */ +final class KafkaPolledRegistration implements TransportConsumerRegistration { + + private static final System.Logger LOG = + System.getLogger(KafkaPolledRegistration.class.getName()); + + private static final Duration POLL_TIMEOUT = Duration.ofMillis(200); + + private final String name; + private final KafkaConsumerRegistrar registrar; + private final GracefulShutdownCoordinator drain; + private final ExecutorService handlers; + private final Duration drainDeadline; + private final Thread poller; + private volatile boolean stopping; + + private KafkaPolledRegistration( + TransportConsumerSpec spec, + Map clientConfig, + KafkaQuarantinePublisher quarantine, + Duration drainDeadline) { + this.name = spec.profile().name().value(); + this.drainDeadline = drainDeadline; + String topic = + spec.profile() + .physical() + .topic() + .orElseThrow( + () -> + new IllegalStateException( + "destination '" + name + "' is consumed from Kafka but has no topic")); + this.drain = new GracefulShutdownCoordinator(drainDeadline); + this.handlers = + Executors.newFixedThreadPool( + spec.profile().consumer().concurrency(), + Thread.ofPlatform().name("messaging-kafka-handler-" + name + "-", 0).factory()); + this.registrar = + new KafkaConsumerRegistrar( + spec, + new KafkaConsumer(clientConfig), + handlers, + drain, + POLL_TIMEOUT, + quarantine); + registrar.subscribe(topic); + this.poller = Thread.ofPlatform().name("messaging-kafka-poll-" + name).unstarted(this::loop); + } + + /** + * Opens the client, subscribes and starts polling. + * + * @param spec the destination and the pipeline its deliveries go through + * @param clientConfig the consumer client configuration + * @param quarantine where a record the consumer cannot deliver is parked + * @param drainDeadline how long {@link #close()} lets running handlers finish + * @return the live registration + */ + static KafkaPolledRegistration open( + TransportConsumerSpec spec, + Map clientConfig, + KafkaQuarantinePublisher quarantine, + Duration drainDeadline) { + KafkaPolledRegistration registration = + new KafkaPolledRegistration(spec, clientConfig, quarantine, drainDeadline); + registration.poller.start(); + return registration; + } + + @Override + public CompletionStage pause(String scope) { + return registrar.pause(scope); + } + + @Override + public CompletionStage resume(String scope) { + return registrar.resume(scope); + } + + @Override + public boolean isActive() { + return registrar.isActive() && !stopping; + } + + @Override + public void close() { + Instant startedAt = Instant.now(); + drain.beginDrain(startedAt); + Instant deadline = startedAt.plus(drainDeadline); + while (!drain.isDrained(Instant.now()) && Instant.now().isBefore(deadline)) { + if (!sleep(Duration.ofMillis(50))) { + break; + } + } + stopping = true; + try { + poller.join(POLL_TIMEOUT.toMillis() * 10); + } catch (InterruptedException interrupted) { + Thread.currentThread().interrupt(); + } + handlers.shutdownNow(); + try { + handlers.awaitTermination(1, TimeUnit.SECONDS); + } catch (InterruptedException interrupted) { + Thread.currentThread().interrupt(); + } + } + + private void loop() { + try { + while (!stopping) { + try { + registrar.pollOnce(Instant.now()); + } catch (RuntimeException failure) { + // A failed poll or commit is not a reason to stop consuming for good: nothing past the + // last successful commit is lost, and the next cycle retries it. + LOG.log( + System.Logger.Level.WARNING, + "Kafka consumer for " + name + " failed a poll cycle: " + failure); + sleep(POLL_TIMEOUT); + } + if (!drain.isAcceptingWork()) { + // pollOnce no longer polls once draining begins; it only applies settlements and + // commits. Without a pause the loop would spin. + sleep(Duration.ofMillis(20)); + } + } + } finally { + registrar.close(); + } + } + + private static boolean sleep(Duration duration) { + try { + Thread.sleep(duration.toMillis()); + return true; + } catch (InterruptedException interrupted) { + Thread.currentThread().interrupt(); + return false; + } + } +} diff --git a/src/messaging/messaging-spring-boot-starter/build.gradle b/src/messaging/messaging-spring-boot-starter/build.gradle index 88f47178..7f3f7811 100644 --- a/src/messaging/messaging-spring-boot-starter/build.gradle +++ b/src/messaging/messaging-spring-boot-starter/build.gradle @@ -18,7 +18,6 @@ auxiliarySourceSets { dependencies { // Types an adopter writes against: envelopes, destinations, publish results, profiles, ports. api project(':messaging:messaging-core-api') - api project(':messaging:messaging-schema-api') api project(':messaging:messaging-policy') api project(':messaging:messaging-transport-spi') api project(':messaging:messaging-observability') @@ -34,18 +33,11 @@ dependencies { // The relay and consumer logic, and the PostgreSQL stores behind their ports. implementation project(':messaging:messaging-reliability') implementation project(':messaging:messaging-reliability-jdbc-postgresql') - implementation project(':messaging:messaging-admin-api') - implementation project(':messaging:messaging-admin-runtime') + implementation project(':messaging:messaging-admin') implementation 'org.springframework.boot:spring-boot-autoconfigure' implementation 'org.springframework.boot:spring-boot-actuator' - // The Reactor facade lives here, not in core-api: the core contract stays CompletionStage so - // that a service which does not use Reactor never inherits it. api, because - // ReactiveMessagePublisher returns Mono — a facade whose return type an adopter cannot name - // is a facade they cannot call. - api 'io.projectreactor:reactor-core' - testImplementation 'io.projectreactor:reactor-test' testImplementation 'org.springframework.boot:spring-boot-test' testImplementation 'org.springframework:spring-test' // Provider auto-configurations live in capability artifacts. Tests that exercise provider @@ -63,6 +55,13 @@ dependencies { integrationTestImplementation project(':messaging:messaging-spring-boot-starter-kafka') integrationTestImplementation 'org.testcontainers:testcontainers-junit-jupiter' integrationTestImplementation 'org.testcontainers:testcontainers-kafka' + // The consume round trip's inbox lane: a real PostgreSQL behind the JDBC inbox, joined to the + // handler's own write by a real transaction manager. + integrationTestImplementation project(':messaging:messaging-reliability') + integrationTestImplementation project(':messaging:messaging-reliability-jdbc-postgresql') + integrationTestImplementation 'org.springframework:spring-jdbc' + integrationTestImplementation 'org.testcontainers:testcontainers-postgresql' + integrationTestImplementation 'org.postgresql:postgresql' } strictTestLanes { diff --git a/src/messaging/messaging-spring-boot-starter/gradle.lockfile b/src/messaging/messaging-spring-boot-starter/gradle.lockfile index d606cfcf..d178e837 100644 --- a/src/messaging/messaging-spring-boot-starter/gradle.lockfile +++ b/src/messaging/messaging-spring-boot-starter/gradle.lockfile @@ -44,8 +44,6 @@ io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,integrationTe io.micrometer:micrometer-commons:1.16.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath io.micrometer:micrometer-core:1.16.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath io.micrometer:micrometer-observation:1.16.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.projectreactor:reactor-core:3.8.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -io.projectreactor:reactor-test:3.8.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath javax.inject:javax.inject:1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor jaxen:jaxen:2.0.6=spotbugs net.bytebuddy:byte-buddy:1.17.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath @@ -69,6 +67,7 @@ org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle org.apache.xbean:xbean-reflect:3.7=checkstyle org.apiguardian:apiguardian-api:1.1.2=integrationTestCompileClasspath,testCompileClasspath org.assertj:assertj-core:3.27.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath +org.checkerframework:checker-qual:3.55.1=integrationTestRuntimeClasspath org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle @@ -96,7 +95,7 @@ org.ow2.asm:asm-tree:9.10.1=spotbugs org.ow2.asm:asm-util:9.10.1=spotbugs org.ow2.asm:asm:9.10.1=spotbugs org.pcollections:pcollections:4.0.1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor -org.reactivestreams:reactive-streams:1.0.4=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +org.postgresql:postgresql:42.7.13=integrationTestCompileClasspath,integrationTestRuntimeClasspath org.reflections:reflections:0.10.2=checkstyle org.rnorth.duct-tape:duct-tape:1.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath org.slf4j:slf4j-api:2.0.18=integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs,spotbugsSlf4j,testRuntimeClasspath @@ -112,11 +111,14 @@ org.springframework:spring-beans:7.0.9=compileClasspath,integrationTestCompileCl org.springframework:spring-context:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath org.springframework:spring-core:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath org.springframework:spring-expression:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-jdbc:7.0.9=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +org.springframework:spring-jdbc:7.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath org.springframework:spring-test:7.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath -org.springframework:spring-tx:7.0.9=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +org.springframework:spring-tx:7.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath +org.testcontainers:testcontainers-database-commons:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath +org.testcontainers:testcontainers-jdbc:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath org.testcontainers:testcontainers-junit-jupiter:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath org.testcontainers:testcontainers-kafka:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath +org.testcontainers:testcontainers-postgresql:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath org.testcontainers:testcontainers:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath org.xerial.snappy:snappy-java:1.1.10.7=integrationTestRuntimeClasspath,testRuntimeClasspath org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs diff --git a/src/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingKafkaConsumeQualificationTest.java b/src/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingKafkaConsumeQualificationTest.java new file mode 100644 index 00000000..7083bc63 --- /dev/null +++ b/src/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingKafkaConsumeQualificationTest.java @@ -0,0 +1,460 @@ +package dev.caskeleton.messaging.autoconfigure; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.messaging.api.ContentType; +import dev.caskeleton.messaging.api.MessageEnvelope; +import dev.caskeleton.messaging.api.MessageId; +import dev.caskeleton.messaging.api.MessageType; +import dev.caskeleton.messaging.api.ProducerId; +import dev.caskeleton.messaging.api.SchemaVersion; +import dev.caskeleton.messaging.api.TraceContext; +import dev.caskeleton.messaging.api.delivery.DeliveryGuarantee; +import dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee; +import dev.caskeleton.messaging.api.delivery.HandleResult; +import dev.caskeleton.messaging.api.delivery.MessageDelivery; +import dev.caskeleton.messaging.api.delivery.MessageHandler; +import dev.caskeleton.messaging.api.delivery.OrderingScope; +import dev.caskeleton.messaging.api.destination.DestinationKind; +import dev.caskeleton.messaging.api.destination.DestinationName; +import dev.caskeleton.messaging.api.destination.MessageDestination; +import dev.caskeleton.messaging.api.error.FailureCategory; +import dev.caskeleton.messaging.api.error.FailureDescriptor; +import dev.caskeleton.messaging.api.header.MessageHeaders; +import dev.caskeleton.messaging.api.header.ReservedHeaders; +import dev.caskeleton.messaging.api.publish.MessagePublisher; +import dev.caskeleton.messaging.api.publish.PublishCompletion; +import dev.caskeleton.messaging.api.publish.PublishOptions; +import dev.caskeleton.messaging.inbox.IdempotentConsumer; +import dev.caskeleton.messaging.inbox.JdbcInboxRepository; +import dev.caskeleton.messaging.policy.ApiTier; +import dev.caskeleton.messaging.policy.ConsumerPolicy; +import dev.caskeleton.messaging.policy.DeadLetterPolicy; +import dev.caskeleton.messaging.policy.DestinationProfile; +import dev.caskeleton.messaging.policy.OrderingImpact; +import dev.caskeleton.messaging.policy.PayloadPolicy; +import dev.caskeleton.messaging.policy.PhysicalDestination; +import dev.caskeleton.messaging.policy.ProducerPolicy; +import dev.caskeleton.messaging.policy.RetryMode; +import dev.caskeleton.messaging.policy.RetryPolicy; +import dev.caskeleton.messaging.policy.SchemaPolicy; +import dev.caskeleton.messaging.schema.MessageContractKey; +import dev.caskeleton.messaging.schema.SchemaCompatibility; +import java.io.IOException; +import java.io.InputStream; +import java.nio.charset.StandardCharsets; +import java.time.Duration; +import java.time.Instant; +import java.util.List; +import java.util.Map; +import java.util.Optional; +import java.util.Properties; +import java.util.Set; +import java.util.concurrent.BlockingQueue; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.CompletionStage; +import java.util.concurrent.LinkedBlockingQueue; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.function.Function; +import javax.sql.DataSource; +import org.apache.kafka.clients.admin.Admin; +import org.apache.kafka.clients.admin.AdminClientConfig; +import org.apache.kafka.clients.consumer.ConsumerConfig; +import org.apache.kafka.clients.consumer.ConsumerRecord; +import org.apache.kafka.clients.consumer.KafkaConsumer; +import org.apache.kafka.clients.consumer.OffsetAndMetadata; +import org.apache.kafka.common.TopicPartition; +import org.apache.kafka.common.serialization.ByteArrayDeserializer; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.condition.EnabledIf; +import org.springframework.boot.autoconfigure.AutoConfigurations; +import org.springframework.boot.test.context.runner.ApplicationContextRunner; +import org.springframework.jdbc.core.JdbcTemplate; +import org.springframework.jdbc.datasource.DataSourceTransactionManager; +import org.springframework.jdbc.datasource.DriverManagerDataSource; +import org.springframework.transaction.support.TransactionTemplate; +import org.testcontainers.DockerClientFactory; +import org.testcontainers.junit.jupiter.Container; +import org.testcontainers.junit.jupiter.Testcontainers; +import org.testcontainers.kafka.KafkaContainer; +import org.testcontainers.postgresql.PostgreSQLContainer; + +/** + * A message published through the assembled platform is consumed by a {@code MessageHandler} bean + * on a real broker (owner decision 10, S7-#2). + * + *

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

Kafka is the one broker family this platform has a transport for, so the record carries only - * Kafka fields. RabbitMQ fields used to live here too and bound with no transport behind them: a - * deployment could configure a RabbitMQ broker that nothing would ever connect to. + *

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

{@code tlsEnabled} and {@code production} live here rather than beside the credentials, so a * broker is described once. They were previously implied by whichever object happened to be @@ -21,27 +23,13 @@ import org.springframework.boot.context.properties.bind.DefaultValue; * @param production whether this profile is used in production * @param tlsEnabled whether transport encryption is on * @param authenticationEnabled whether broker authentication is on - * @param bootstrapServers Kafka broker addresses - * @param enableIdempotence Kafka producer duplicate suppression on internal retry - * @param acks the Kafka acknowledgement level - * @param maxInFlightRequestsPerConnection the Kafka in-flight request ceiling - * @param deliveryTimeout the Kafka producer delivery deadline - * @param enableAutoCommit whether the Kafka consumer commits offsets on a timer - * @param consumerGroup the Kafka consumer group */ public record BrokerSettings( String type, @DefaultValue("false") boolean stable, @DefaultValue("false") boolean production, @DefaultValue("false") boolean tlsEnabled, - @DefaultValue("false") boolean authenticationEnabled, - @DefaultValue List bootstrapServers, - @DefaultValue("true") boolean enableIdempotence, - @DefaultValue("all") String acks, - @DefaultValue("5") int maxInFlightRequestsPerConnection, - @DefaultValue("30s") Duration deliveryTimeout, - @DefaultValue("false") boolean enableAutoCommit, - @DefaultValue("") String consumerGroup) { + @DefaultValue("false") boolean authenticationEnabled) { /** The broker family a Kafka entry declares. */ public static final String KAFKA = "kafka"; diff --git a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultBatchMessagePublisher.java b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultBatchMessagePublisher.java deleted file mode 100644 index c45124d2..00000000 --- a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultBatchMessagePublisher.java +++ /dev/null @@ -1,262 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import dev.caskeleton.messaging.api.publish.BatchMessagePublisher; -import dev.caskeleton.messaging.api.publish.BatchPublishItemResult; -import dev.caskeleton.messaging.api.publish.BatchPublishOptions; -import dev.caskeleton.messaging.api.publish.BatchPublishResult; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishRequest; -import java.time.Duration; -import java.time.Instant; -import java.util.ArrayList; -import java.util.List; -import java.util.Objects; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import java.util.function.Supplier; - -/** - * Fans a batch out over the single-message publisher and keeps every entry's outcome. - * - *

Entries are submitted concurrently and awaited together, because a batch's value is the - * overlap: submitting serially would make a 500-entry batch take 500 round trips, which is slower - * than the loop the caller was trying to avoid. - * - *

A failed entry never fails the batch. Each entry's exception is converted into that entry's - * result, so an oversized message at index 7 does not hide the outcomes of the other 499 — the - * caller needs to know exactly which entries to resubmit, and a thrown exception tells it nothing. - * - *

{@code stopOnFirstRejection} short-circuits the submission, not the awaiting. Entries - * already in flight when the first rejection arrives cannot be recalled, so they are still awaited - * and reported; pretending otherwise would leave the caller unsure whether they landed. - */ -public final class DefaultBatchMessagePublisher implements BatchMessagePublisher, AutoCloseable { - - private final MessagePublisher publisher; - private final Supplier clock; - private final java.util.concurrent.ScheduledExecutorService deadlines; - - /** - * Creates a batch publisher over the single-message publisher. - * - * @param publisher the platform publisher - * @param clock supplies the current instant - */ - public DefaultBatchMessagePublisher(MessagePublisher publisher, Supplier clock) { - this( - publisher, - clock, - java.util.concurrent.Executors.newSingleThreadScheduledExecutor( - runnable -> { - Thread thread = new Thread(runnable, "messaging-batch-deadline"); - thread.setDaemon(true); - return thread; - })); - } - - DefaultBatchMessagePublisher( - MessagePublisher publisher, - Supplier clock, - java.util.concurrent.ScheduledExecutorService deadlines) { - this.publisher = Objects.requireNonNull(publisher, "publisher must not be null"); - this.clock = Objects.requireNonNull(clock, "clock must not be null"); - this.deadlines = Objects.requireNonNull(deadlines, "deadlines must not be null"); - } - - @Override - public CompletionStage publish( - List> requests, BatchPublishOptions options) { - Objects.requireNonNull(requests, "requests must not be null"); - Objects.requireNonNull(options, "options must not be null"); - - if (requests.size() > options.maxBatchSize()) { - throw new MessageTooLargeException( - "BATCH_COUNT_EXCEEDED", - "batch of %d entries exceeds the %d entry limit" - .formatted(requests.size(), options.maxBatchSize())); - } - - Instant startedAt = clock.get(); - List> pending = new ArrayList<>(requests.size()); - // Index and message id per slot, so an entry still outstanding at the deadline can still be - // reported against the input position it came from. - List placeholders = new ArrayList<>(requests.size()); - - for (int index = 0; index < requests.size(); index++) { - placeholders.add(outstanding(index, requests.get(index).message().messageId())); - if (options.stopOnFirstRejection() && anyRejected(pending)) { - // Every remaining index still gets a result. Breaking out shortened the result list, so a - // caller could not tell "not submitted" from "result lost" — and those need opposite - // actions. - pending.add( - CompletableFuture.completedFuture( - notSubmitted(index, requests.get(index).message().messageId(), startedAt))); - continue; - } - CompletableFuture submitted = submit(requests.get(index), index); - pending.add(submitted); - if (options.stopOnFirstRejection()) { - // Sequential under stop-on-first-rejection: waiting for this entry's outcome is the only - // way the flag can mean anything. The previous loop only saw a rejection that had already - // resolved, which for an asynchronous broker is never — so every remaining entry was - // submitted anyway and the option did nothing. - awaitQuietly(submitted, remaining(startedAt, options.timeout())); - } - } - - CompletableFuture completed = new CompletableFuture<>(); - CompletableFuture all = - CompletableFuture.allOf(pending.toArray(CompletableFuture[]::new)); - // The returned stage is deliberately dropped: `completed` is what the caller holds, and this - // callback's only job is to fill it in. Nothing downstream observes the intermediate stage. - CompletableFuture ignoredCompletion = - all.whenComplete( - (ignored, failure) -> - completed.complete( - new BatchPublishResult( - resolveAll(pending, placeholders), - Duration.between(startedAt, clock.get())))); - assert ignoredCompletion != null; - - // The whole-batch deadline the options document. It was never read, so a publisher that never - // completed left the caller's stage pending forever — a timeout that exists only in the - // javadoc. - // Same for the scheduled future: cancelling it early would only save a no-op, and the task - // checks `isDone` before completing anything. - java.util.concurrent.ScheduledFuture ignoredDeadline = - deadlines.schedule( - () -> { - if (!completed.isDone()) { - completed.complete( - new BatchPublishResult( - resolveAll(pending, placeholders), - Duration.between(startedAt, clock.get()))); - } - }, - options.timeout().toMillis(), - java.util.concurrent.TimeUnit.MILLISECONDS); - assert ignoredDeadline != null; - return completed; - } - - @Override - public void close() { - deadlines.shutdownNow(); - } - - private boolean anyRejected(List> pending) { - return pending.stream() - .anyMatch( - future -> - future.isDone() - && !future.isCompletedExceptionally() - && future.join().result().completion() == PublishCompletion.REJECTED); - } - - private void awaitQuietly(CompletableFuture future, Duration budget) { - if (budget.isNegative() || budget.isZero()) { - return; - } - try { - future.get(budget.toMillis(), java.util.concurrent.TimeUnit.MILLISECONDS); - } catch (InterruptedException interrupted) { - Thread.currentThread().interrupt(); - } catch (java.util.concurrent.ExecutionException - | java.util.concurrent.TimeoutException other) { - // Both are outcomes the result already carries; nothing to add here. - } - } - - private Duration remaining(Instant startedAt, Duration timeout) { - return timeout.minus(Duration.between(startedAt, clock.get())); - } - - /** - * An entry the batch never submitted because an earlier one was rejected. - * - *

Distinct from a failure: nothing was sent, so the caller may submit it unchanged. - */ - private BatchPublishItemResult notSubmitted( - int index, dev.caskeleton.messaging.api.MessageId messageId, Instant startedAt) { - return new BatchPublishItemResult( - index, - messageId, - new dev.caskeleton.messaging.api.publish.PublishResult( - PublishCompletion.REJECTED, - dev.caskeleton.messaging.api.publish.PublishEvidence.notTransmitted(), - dev.caskeleton.messaging.api.publish.RoutingOutcome.UNKNOWN, - java.util.Optional.empty(), - 1, - Duration.between(startedAt, clock.get()), - java.util.Optional.of( - dev.caskeleton.messaging.api.error.FailureDescriptor.of( - dev.caskeleton.messaging.api.error.FailureCategory.CONFIGURATION, - "NOT_SUBMITTED_AFTER_REJECTION", - "an earlier entry was rejected and this batch stops on the first rejection")))); - } - - private List resolveAll( - List> pending, - List placeholders) { - List resolved = new ArrayList<>(pending.size()); - for (int index = 0; index < pending.size(); index++) { - CompletableFuture future = pending.get(index); - resolved.add( - future.isDone() && !future.isCompletedExceptionally() - ? future.join() - : placeholders.get(index)); - } - return List.copyOf(resolved); - } - - /** An entry still outstanding when the deadline arrived is ambiguous, never a success. */ - private BatchPublishItemResult outstanding( - int index, dev.caskeleton.messaging.api.MessageId messageId) { - return new BatchPublishItemResult( - index, - messageId, - new dev.caskeleton.messaging.api.publish.PublishResult( - PublishCompletion.AMBIGUOUS, - dev.caskeleton.messaging.api.publish.PublishEvidence.ambiguous(), - dev.caskeleton.messaging.api.publish.RoutingOutcome.UNKNOWN, - java.util.Optional.empty(), - 1, - Duration.ZERO, - java.util.Optional.of( - dev.caskeleton.messaging.api.error.FailureDescriptor.of( - dev.caskeleton.messaging.api.error.FailureCategory.AMBIGUOUS, - "BATCH_DEADLINE_EXCEEDED", - "the batch deadline elapsed before this entry produced evidence")))); - } - - private CompletableFuture submit( - PublishRequest request, int index) { - @SuppressWarnings("unchecked") - PublishRequest typed = (PublishRequest) request; - MessageDestination destination = typed.destination(); - MessageEnvelope message = typed.message(); - - try { - return publisher - .publish(destination, message, typed.options()) - .toCompletableFuture() - .handle( - (result, failure) -> - new BatchPublishItemResult( - index, - message.messageId(), - failure == null ? result : PublishResults.from(failure))) - .toCompletableFuture(); - } catch (RuntimeException synchronousFailure) { - // A publisher that validates eagerly throws instead of returning a failed stage. Converting - // it here keeps the "one result per index" contract that the caller resubmits from. - return CompletableFuture.completedFuture( - new BatchPublishItemResult( - index, message.messageId(), PublishResults.from(synchronousFailure))); - } - } -} diff --git a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultBlockingMessagePublisher.java b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultBlockingMessagePublisher.java deleted file mode 100644 index 9931b917..00000000 --- a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultBlockingMessagePublisher.java +++ /dev/null @@ -1,65 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.error.MessagePublishTimeoutException; -import dev.caskeleton.messaging.api.publish.BlockingMessagePublisher; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import java.util.Objects; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.ExecutionException; -import java.util.concurrent.TimeUnit; -import java.util.concurrent.TimeoutException; - -/** - * Converts the asynchronous publish lifecycle into a blocking call. - * - *

Three details make this safe rather than a thread-pool trap. The wait is bounded by the call's - * own deadline. A timeout is reported as {@link MessagePublishTimeoutException}, which the error - * model classifies as ambiguous — the broker may still hold the message, and the caller must not - * treat it as a failed send. And an interrupt restores the thread's interrupt flag instead of - * swallowing it, so a shutdown that interrupts a blocked publisher still unwinds. - */ -public final class DefaultBlockingMessagePublisher implements BlockingMessagePublisher { - - private final MessagePublisher delegate; - - /** - * Creates a blocking facade. - * - * @param delegate the asynchronous publisher - */ - public DefaultBlockingMessagePublisher(MessagePublisher delegate) { - this.delegate = Objects.requireNonNull(delegate, "delegate must not be null"); - } - - @Override - public PublishResult publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - Objects.requireNonNull(options, "options must not be null"); - CompletableFuture future = - delegate.publish(destination, message, options).toCompletableFuture(); - try { - return future.get(options.timeout().toMillis(), TimeUnit.MILLISECONDS); - } catch (TimeoutException exception) { - future.cancel(true); - throw new MessagePublishTimeoutException( - "PUBLISH_TIMEOUT", - "no publish outcome within " + options.timeout() + "; the broker may hold the message", - exception); - } catch (InterruptedException exception) { - Thread.currentThread().interrupt(); - future.cancel(true); - throw new MessagePublishTimeoutException( - "PUBLISH_INTERRUPTED", "the publishing thread was interrupted", exception); - } catch (ExecutionException exception) { - Throwable cause = exception.getCause(); - if (cause instanceof RuntimeException runtime) { - throw runtime; - } - throw new IllegalStateException("publish failed", cause); - } - } -} diff --git a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultReactiveMessagePublisher.java b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultReactiveMessagePublisher.java deleted file mode 100644 index 5c3a25be..00000000 --- a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultReactiveMessagePublisher.java +++ /dev/null @@ -1,43 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import java.util.Objects; -import reactor.core.publisher.Mono; - -/** - * Converts the asynchronous publish lifecycle into a cold, cancellable {@code Mono}. - * - *

{@code Mono.fromCompletionStage} with a supplier is used deliberately: the eager overload - * would start the publish when the {@code Mono} is assembled rather than when it is subscribed, - * which makes a request never sent by an unsubscribed pipeline indistinguishable from one that was. - */ -public final class DefaultReactiveMessagePublisher implements ReactiveMessagePublisher { - - private final MessagePublisher delegate; - - /** - * Creates a Reactor facade. - * - * @param delegate the asynchronous publisher - */ - public DefaultReactiveMessagePublisher(MessagePublisher delegate) { - this.delegate = Objects.requireNonNull(delegate, "delegate must not be null"); - } - - @Override - public Mono publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(message, "message must not be null"); - Objects.requireNonNull(options, "options must not be null"); - // publish() is not purely asynchronous: admission may wait for a permit and the Kafka producer - // may wait for metadata before the stage exists. Subscribing on a Netty event loop would pin - // that loop for the wait, so the call runs on the bounded elastic pool instead. - return Mono.fromCompletionStage(() -> delegate.publish(destination, message, options)) - .subscribeOn(reactor.core.scheduler.Schedulers.boundedElastic()); - } -} diff --git a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DestinationSettings.java b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DestinationSettings.java index 35304c7b..8184d6ac 100644 --- a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DestinationSettings.java +++ b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DestinationSettings.java @@ -5,7 +5,7 @@ import dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee; import dev.caskeleton.messaging.api.delivery.OrderingScope; import dev.caskeleton.messaging.api.destination.ConfirmationRequirement; import dev.caskeleton.messaging.api.destination.DestinationKind; -import dev.caskeleton.messaging.policy.CapabilityTier; +import dev.caskeleton.messaging.policy.ApiTier; import dev.caskeleton.messaging.policy.OrderingImpact; import dev.caskeleton.messaging.policy.RetryMode; import dev.caskeleton.messaging.schema.SchemaCompatibility; @@ -48,7 +48,7 @@ import org.springframework.boot.context.properties.bind.DefaultValue; public record DestinationSettings( String broker, DestinationKind kind, - @DefaultValue("M1") CapabilityTier tier, + @DefaultValue("M1") ApiTier tier, @DefaultValue Physical physical, @DefaultValue Schema schema, @DefaultValue Guarantees guarantees, diff --git a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageConsumers.java b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageConsumers.java new file mode 100644 index 00000000..332baa53 --- /dev/null +++ b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageConsumers.java @@ -0,0 +1,46 @@ +package dev.caskeleton.messaging.autoconfigure; + +import dev.caskeleton.messaging.policy.DestinationProfile; +import dev.caskeleton.messaging.transport.TransportDelivery; +import java.util.List; +import java.util.Objects; +import java.util.concurrent.CompletionStage; +import java.util.function.Function; + +/** + * The destinations this application consumes, each with the broker-neutral pipeline its deliveries + * go through. + * + *

Built by {@link MessagingConsumeConfiguration} from the {@code MessageHandler} beans; a broker + * starter opens one consumer per entry and hands every delivery to its {@link Consumer#sink()}. The + * split keeps decoding, inbox, dead-lettering and settlement rules out of each broker starter. + * + * @param consumers one entry per consumed destination + */ +public record MessageConsumers(List consumers) { + + public MessageConsumers { + consumers = List.copyOf(Objects.requireNonNull(consumers, "consumers must not be null")); + } + + /** + * One consumed destination. + * + * @param profile the destination profile + * @param group the consumer group, which is also the inbox consumer identity + * @param sink the pipeline each still-encoded delivery goes through + */ + public record Consumer( + DestinationProfile profile, + String group, + Function> sink) { + + public Consumer { + Objects.requireNonNull(profile, "profile must not be null"); + Objects.requireNonNull(sink, "sink must not be null"); + if (group == null || group.isBlank()) { + throw new IllegalArgumentException("group must not be blank"); + } + } + } +} diff --git a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java index 876b3901..2a24d32b 100644 --- a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java +++ b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java @@ -93,20 +93,13 @@ public final class MessagingConfigurationCompiler { } private static void validateBrokerSettings(String name, BrokerSettings broker) { - switch (familyOf(name, broker)) { - case BrokerSettings.KAFKA -> { - if (broker.bootstrapServers().isEmpty()) { - throw configurationError( - key("brokers", name, "bootstrap-servers"), - "a Kafka broker needs at least one address; a client with none defaults to " - + "localhost:9092 and fails at the first publish rather than at startup"); - } - } - default -> - throw configurationError( - key("brokers", name, "type"), - "'%s' is not a broker family this platform has a transport for; use '%s'" - .formatted(broker.type(), BrokerSettings.KAFKA)); + // Only the family is checked here. Its client settings — addresses, acks — belong to the + // family's starter, which binds and validates them when it builds the client. + if (!MessagingProviderSelection.registeredBrokerIds().contains(familyOf(name, broker))) { + throw configurationError( + key("brokers", name, "type"), + "'%s' is not a broker family this platform has a transport for; use one of %s" + .formatted(broker.type(), MessagingProviderSelection.registeredBrokerIds())); } } diff --git a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationKeyValidator.java b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationKeyValidator.java index b5c534a2..56c5b676 100644 --- a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationKeyValidator.java +++ b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationKeyValidator.java @@ -5,6 +5,7 @@ import java.lang.reflect.RecordComponent; import java.util.ArrayList; import java.util.LinkedHashSet; import java.util.List; +import java.util.Locale; import java.util.Map; import java.util.Objects; import java.util.Set; @@ -12,6 +13,7 @@ import org.springframework.beans.factory.InitializingBean; import org.springframework.core.env.ConfigurableEnvironment; import org.springframework.core.env.EnumerablePropertySource; import org.springframework.core.env.PropertySource; +import org.springframework.util.ClassUtils; /** * Refuses a key inside the platform's own configuration sections that nothing binds. @@ -68,12 +70,14 @@ public final class MessagingConfigurationKeyValidator implements InitializingBea List rejected = new ArrayList<>(); sections.forEach( (section, shape) -> { - Set legal = leafPaths(shape); + Set common = leafPaths(shape); for (String key : keysUnder(MessagingSettings.PREFIX + '.' + section + '.')) { Entry entry = split(key, MessagingSettings.PREFIX + '.' + section + '.'); if (entry.leaf().isEmpty()) { continue; } + Set legal = + "brokers".equals(section) ? brokerLeafPaths(entry.name(), common) : common; if (!legal.contains(entry.leaf())) { rejected.add( "%s binds nothing; %s entries accept %s" @@ -99,6 +103,33 @@ public final class MessagingConfigurationKeyValidator implements InitializingBea + (rejected.size() > 10 ? " (and " + (rejected.size() - 10) + " more)" : "")); } + /** + * The keys a broker entry accepts: the neutral ones, plus its family's own when the family's + * starter is on the classpath. + * + *

A family whose settings record is absent accepts only the neutral keys. Its client keys bind + * nothing in that deployment — there is no transport to hand them to — and {@link + * MessagingProviderSelection} refuses a selected family whose starter is missing anyway. + */ + private Set brokerLeafPaths(String brokerName, Set common) { + String type = + environment.getProperty(MessagingSettings.PREFIX + ".brokers." + brokerName + ".type", ""); + String shapeName = + MessagingProviderSelection.PROVIDER_BROKER_SETTINGS.get( + type.trim().toLowerCase(Locale.ROOT)); + if (shapeName == null + || !ClassUtils.isPresent( + shapeName, MessagingConfigurationKeyValidator.class.getClassLoader())) { + return common; + } + Set legal = new LinkedHashSet<>(common); + legal.addAll( + leafPaths( + ClassUtils.resolveClassName( + shapeName, MessagingConfigurationKeyValidator.class.getClassLoader()))); + return legal; + } + /** One configuration key split into the map entry it configures and the leaf inside it. */ private record Entry(String name, String leaf) {} diff --git a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfiguration.java b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfiguration.java new file mode 100644 index 00000000..0dc88797 --- /dev/null +++ b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfiguration.java @@ -0,0 +1,151 @@ +package dev.caskeleton.messaging.autoconfigure; + +import dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee; +import dev.caskeleton.messaging.api.delivery.MessageHandler; +import dev.caskeleton.messaging.api.destination.DestinationName; +import dev.caskeleton.messaging.api.error.MessagingConfigurationException; +import dev.caskeleton.messaging.inbox.IdempotentConsumer; +import dev.caskeleton.messaging.inbox.InboxMessageHandler; +import dev.caskeleton.messaging.policy.DeadLetterOrchestrator; +import dev.caskeleton.messaging.policy.DestinationProfile; +import dev.caskeleton.messaging.runtime.DefaultDeliveryProcessor; +import dev.caskeleton.messaging.schema.MessageCodecRegistry; +import dev.caskeleton.messaging.security.BrokerSecurityProfile; +import dev.caskeleton.messaging.security.DestinationAccessPolicy; +import java.time.Instant; +import java.time.InstantSource; +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.concurrent.CompletableFuture; +import java.util.stream.Stream; +import org.springframework.beans.factory.ObjectProvider; +import org.springframework.boot.autoconfigure.condition.ConditionalOnBean; +import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; + +/** + * The broker-neutral consume pipeline, assembled from the application's {@link MessageHandler} + * beans (owner decision 10, S7-#2). + * + *

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

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

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

It was one 550-line class with 28 beans (S7-#9a). It is now the entry point that imports the + * three parts, plus the consume pipeline (S7-#2), so an adopter or a test that names this class + * still gets the whole core. * - *

The M2 and M3 surfaces are deliberately not auto-configured. Manual settlement, native - * capabilities, and the Admin Plane are opt-in beans with their own credentials, so a service - * cannot acquire them by adding the starter to its classpath. + * @see MessagingValidationConfiguration + * @see MessagingPublishConfiguration + * @see MessagingObservabilityConfiguration + * @see MessagingConsumeConfiguration */ @Configuration(proxyBeanMethods = false) @EnableConfigurationProperties(MessagingSettings.class) -public class MessagingCoreAutoConfiguration { - - /** - * Fails the context when a production broker profile has no credential source. - * - *

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

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

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

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

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

Configured profiles and bean-declared ones are merged before validation, not after, because - * the rules that matter most across a registry — a dead letter destination that exists, a retry - * graph with no cycle — are questions about the whole set. Validating the two halves separately - * would pass a deployment whose configured destination dead-letters into a bean-declared one that - * points back. - * - * @param profiles the profiles the application declared as beans - * @param compiled the profiles compiled from configuration - * @return the validated registry - */ - @Bean - @ConditionalOnMissingBean - public ValidatedDestinationRegistry validatedDestinationRegistry( - ObjectProvider profiles, CompiledMessagingConfiguration compiled) { - List registered = - java.util.stream.Stream.concat(compiled.destinations().stream(), profiles.orderedStream()) - .toList(); - new DestinationProfileValidator().validateAll(registered); - return new ValidatedDestinationRegistry(registered); - } - - /** - * Returns the destination profile validator. - * - * @return the validator - */ - @Bean - @ConditionalOnMissingBean - public DestinationProfileValidator destinationProfileValidator() { - return new DestinationProfileValidator(); - } - - /** - * Returns the broker security validator. - * - * @return the validator - */ - @Bean - @ConditionalOnMissingBean - public MessageSecurityValidator messageSecurityValidator() { - return new MessageSecurityValidator(); - } - - /** - * Returns the retry decision engine. - * - * @return the engine - */ - @Bean - @ConditionalOnMissingBean - public RetryDecisionEngine retryDecisionEngine() { - return new DefaultRetryDecisionEngine(new BackoffCalculator()); - } - - /** - * Returns the dead letter orchestrator. - * - * @param publisher the platform publisher - * @return the orchestrator - */ - @Bean - @ConditionalOnMissingBean - public DeadLetterOrchestrator deadLetterOrchestrator(MessagePublisher publisher) { - return new DeadLetterOrchestrator(publisher); - } - - /** - * Returns the runtime registry used for credential and topology rotation. - * - * @param properties the bound configuration - * @return the registry - */ - @Bean - @ConditionalOnMissingBean - public MessagingRuntimeRegistry messagingRuntimeRegistry(MessagingSettings properties) { - return new DefaultMessagingRuntimeRegistry(properties.getShutdown().getDrainDeadline()); - } - - /** - * Returns the graceful shutdown coordinator. - * - * @param properties the bound configuration - * @return the coordinator - */ - @Bean - @ConditionalOnMissingBean - public GracefulShutdownCoordinator gracefulShutdownCoordinator(MessagingSettings properties) { - return new GracefulShutdownCoordinator(properties.getShutdown().getDrainDeadline()); - } - - /** - * Runs the security validator over every broker security profile, declared or configured. - * - * @param profiles the security profiles the application declared as beans - * @param compiled the security profiles compiled from configuration - * @param validator the security validator - * @return the startup validation - */ - @Bean - public StartupProfileValidation - brokerSecurityStartupValidation( - ObjectProvider profiles, - CompiledMessagingConfiguration compiled, - MessageSecurityValidator validator) { - return new StartupProfileValidation<>( - () -> - java.util.stream.Stream.concat(compiled.security().stream(), profiles.orderedStream()) - .toList(), - validator::validate); - } - - /** - * Drives the shutdown phases the admission gate and the drain coordinator only implemented. - * - * @param admission the publish admission gate - * @param drain the in-flight work coordinator - * @param properties the bound configuration supplying the drain deadline - * @return the lifecycle - */ - @Bean - @ConditionalOnMissingBean - public MessagingShutdownLifecycle messagingShutdownLifecycle( - dev.caskeleton.messaging.policy.MessagingAdmissionController admission, - GracefulShutdownCoordinator drain, - MessagingSettings properties) { - return new MessagingShutdownLifecycle( - admission, drain, properties.getShutdown().getDrainDeadline()); - } - - /** - * Returns the diagnostic redactor. - * - * @return the redactor - */ - @Bean - @ConditionalOnMissingBean - public MessagingRedactor messagingRedactor() { - return new MessagingRedactor(); - } - - /** - * Returns the metric cardinality guard. - * - * @return the guard - */ - @Bean - @ConditionalOnMissingBean - public CardinalityGuard cardinalityGuard() { - return new CardinalityGuard(); - } - - /** - * Binds the platform observation seam to Micrometer when a registry is available. - * - *

Narrow tests and non-observed adopters may omit Micrometer entirely. A normal Boot runtime - * with Actuator contributes a registry, in which case publish outcomes must not fall back to the - * no-op observation constructor. - * - * @param registry the Micrometer registry - * @param guard the bounded-cardinality guard - * @param redactor the diagnostics redactor - * @return the messaging metrics binding - */ - @Bean - @ConditionalOnBean(io.micrometer.core.instrument.MeterRegistry.class) - @ConditionalOnMissingBean(dev.caskeleton.messaging.observation.MessagingObservation.class) - public dev.caskeleton.messaging.observation.MessagingObservation messagingObservation( - io.micrometer.core.instrument.MeterRegistry registry, - CardinalityGuard guard, - MessagingRedactor redactor) { - return new dev.caskeleton.messaging.observation.MessagingMetrics(registry, guard, redactor); - } - - /** - * Returns the blocking publish facade. - * - * @param publisher the asynchronous publisher - * @return the blocking facade - */ - @Bean - @ConditionalOnMissingBean - public BlockingMessagePublisher blockingMessagePublisher(MessagePublisher publisher) { - return new DefaultBlockingMessagePublisher(publisher); - } - - /** - * Returns the Reactor publish facade. - * - * @param publisher the asynchronous publisher - * @return the Reactor facade - */ - @Bean - @ConditionalOnMissingBean - public ReactiveMessagePublisher reactiveMessagePublisher(MessagePublisher publisher) { - return new DefaultReactiveMessagePublisher(publisher); - } - - /** - * Returns the M2 batch publish facade. - * - * @param publisher the asynchronous publisher - * @return the batch publisher - */ - @Bean - @ConditionalOnMissingBean - public BatchMessagePublisher batchMessagePublisher(MessagePublisher publisher) { - return new DefaultBatchMessagePublisher(publisher, Instant::now); - } - - /** - * Returns the credential runtime registry, when the application supplied a credential provider. - * - *

Conditional on the provider because there is no safe default: a registry with no source - * would resolve nothing, and the adapters would connect with whatever their client's defaults - * are. - * - * @param provider the application's credential source - * @return the credential runtime registry - */ - @Bean - @ConditionalOnBean(CredentialProvider.class) - @ConditionalOnMissingBean - public CredentialRuntimeRegistry credentialRuntimeRegistry(CredentialProvider provider) { - return new CredentialRuntimeRegistry(provider); - } - - /** - * Returns the transport security policy. - * - * @return the TLS policy - */ - @Bean - @ConditionalOnMissingBean - public BrokerTlsPolicy brokerTlsPolicy() { - return new BrokerTlsPolicy(); - } - - /** - * Returns the read-only actuator endpoint. - * - * @param registry the validated destination registry - * @param admission the gate every publish passes through - * @return the endpoint - */ - @Bean - @ConditionalOnMissingBean - public MessagingEndpoint messagingEndpoint( - ValidatedDestinationRegistry registry, - dev.caskeleton.messaging.policy.MessagingAdmissionController admission) { - return new MessagingEndpoint(registry, admission); - } - - /** - * The codec registry, which had no implementation anywhere (MSG-INT-003). - * - *

The message contracts come from the deployment — a {@code Map} of message type and schema - * version to payload class — and default to empty, which means no message type can be - * encoded and every publish is refused at preparation. That is fail-closed on purpose: a codec - * that accepted an unregistered type would serialise whatever object it was handed and put bytes - * on a topic that consumers compiled against a different shape will read. - * - * @param contracts the declared message contracts, if the deployment registered any - * @return the registry, defaulting to JSON - */ - @Bean - @ConditionalOnMissingBean(dev.caskeleton.messaging.schema.MessageCodecRegistry.class) - public dev.caskeleton.messaging.runtime.RegisteredMessageCodecs messagingCodecs( - ObjectProvider contracts) { - return dev.caskeleton.messaging.runtime.RegisteredMessageCodecs.of( - dev.caskeleton.messaging.schema.json.JacksonMessageCodec.of( - contracts.getIfAvailable(MessageContracts::none).byKey())); - } - - /** - * The destination profiles the publisher resolves against, from the validated registry. - * - * @param destinations the validated registry - * @return the profile registry - */ - @Bean - @ConditionalOnMissingBean - public dev.caskeleton.messaging.runtime.DestinationProfileRegistry messagingDestinationProfiles( - ValidatedDestinationRegistry destinations) { - return dev.caskeleton.messaging.runtime.DestinationProfileRegistry.of(destinations.all()); - } - - /** - * What this deployment may publish to. - * - *

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

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

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

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

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

Narrow tests and non-observed adopters may omit Micrometer entirely. A normal Boot runtime + * with Actuator contributes a registry, in which case publish outcomes must not fall back to the + * no-op observation constructor. + * + * @param registry the Micrometer registry + * @param guard the bounded-cardinality guard + * @param redactor the diagnostics redactor + * @return the messaging metrics binding + */ + @Bean + @ConditionalOnBean(io.micrometer.core.instrument.MeterRegistry.class) + @ConditionalOnMissingBean(dev.caskeleton.messaging.observation.MessagingObservation.class) + public dev.caskeleton.messaging.observation.MessagingObservation messagingObservation( + io.micrometer.core.instrument.MeterRegistry registry, + CardinalityGuard guard, + MessagingRedactor redactor) { + return new dev.caskeleton.messaging.observation.MessagingMetrics(registry, guard, redactor); + } + + /** + * Returns the read-only actuator endpoint. + * + * @param registry the validated destination registry + * @param admission the gate every publish passes through + * @return the endpoint + */ + @Bean + @ConditionalOnMissingBean + public MessagingEndpoint messagingEndpoint( + ValidatedDestinationRegistry registry, + dev.caskeleton.messaging.policy.MessagingAdmissionController admission) { + return new MessagingEndpoint(registry, admission); + } +} diff --git a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProviderSelection.java b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProviderSelection.java index 91cf33bb..b7a248fb 100644 --- a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProviderSelection.java +++ b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProviderSelection.java @@ -45,6 +45,16 @@ public class MessagingProviderSelection { static final Map PROVIDER_CONFIGURATIONS = Map.of("kafka", "dev.caskeleton.messaging.autoconfigure.KafkaMessagingAutoConfiguration"); + /** + * Broker id to the record its starter binds the family's own keys of an {@code + * app.messaging.brokers.} entry into. + * + *

Named rather than referenced for the same reason as {@link #PROVIDER_CONFIGURATIONS}: this + * starter is broker-neutral and cannot see the class. The key validator loads it when present. + */ + static final Map PROVIDER_BROKER_SETTINGS = + Map.of("kafka", "dev.caskeleton.messaging.autoconfigure.KafkaBrokerSettings"); + /** Broker id to the starter a deployment adds to its build to obtain that transport. */ static final Map PROVIDER_STARTERS = Map.of("kafka", "messaging-spring-boot-starter-kafka"); diff --git a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPublishConfiguration.java b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPublishConfiguration.java new file mode 100644 index 00000000..79995f1b --- /dev/null +++ b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPublishConfiguration.java @@ -0,0 +1,304 @@ +package dev.caskeleton.messaging.autoconfigure; + +import dev.caskeleton.messaging.api.publish.MessagePublisher; +import dev.caskeleton.messaging.policy.BackoffCalculator; +import dev.caskeleton.messaging.policy.DeadLetterOrchestrator; +import dev.caskeleton.messaging.policy.DefaultRetryDecisionEngine; +import dev.caskeleton.messaging.policy.RetryDecisionEngine; +import dev.caskeleton.messaging.transport.DefaultMessagingRuntimeRegistry; +import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator; +import dev.caskeleton.messaging.transport.MessagingRuntimeRegistry; +import org.springframework.beans.factory.ObjectProvider; +import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; + +/** + * The publish pipeline: codecs, destination access, admission, the publisher, the runtime it + * publishes through, and the shutdown order that drains it. + * + *

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

The message contracts come from the deployment — a {@code Map} of message type and schema + * version to payload class — and default to empty, which means no message type can be + * encoded and every publish is refused at preparation. That is fail-closed on purpose: a codec + * that accepted an unregistered type would serialise whatever object it was handed and put bytes + * on a topic that consumers compiled against a different shape will read. + * + * @param contracts the declared message contracts, if the deployment registered any + * @return the registry, defaulting to JSON + */ + @Bean + @ConditionalOnMissingBean(dev.caskeleton.messaging.schema.MessageCodecRegistry.class) + public dev.caskeleton.messaging.runtime.RegisteredMessageCodecs messagingCodecs( + ObjectProvider contracts) { + return dev.caskeleton.messaging.runtime.RegisteredMessageCodecs.of( + dev.caskeleton.messaging.schema.json.JacksonMessageCodec.of( + contracts.getIfAvailable(MessageContracts::none).byKey())); + } + + /** + * The destination profiles the publisher resolves against, from the validated registry. + * + * @param destinations the validated registry + * @return the profile registry + */ + @Bean + @ConditionalOnMissingBean + public dev.caskeleton.messaging.runtime.DestinationProfileRegistry messagingDestinationProfiles( + ValidatedDestinationRegistry destinations) { + return dev.caskeleton.messaging.runtime.DestinationProfileRegistry.of(destinations.all()); + } + + /** + * What this deployment may publish to. + * + *

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

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

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

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

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

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

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

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

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

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

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

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

Conditional on the provider because there is no safe default: a registry with no source + * would resolve nothing, and the adapters would connect with whatever their client's defaults + * are. + * + * @param provider the application's credential source + * @return the credential runtime registry + */ + @Bean + @ConditionalOnBean(CredentialProvider.class) + @ConditionalOnMissingBean + public CredentialRuntimeRegistry credentialRuntimeRegistry(CredentialProvider provider) { + return new CredentialRuntimeRegistry(provider); + } + + /** + * Returns the transport security policy. + * + * @return the TLS policy + */ + @Bean + @ConditionalOnMissingBean + public BrokerTlsPolicy brokerTlsPolicy() { + return new BrokerTlsPolicy(); + } +} diff --git a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/PublishResults.java b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/PublishResults.java deleted file mode 100644 index 4dd0178d..00000000 --- a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/PublishResults.java +++ /dev/null @@ -1,71 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.error.MessagingException; -import dev.caskeleton.messaging.api.publish.ConfirmationLevel; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishEvidence; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.api.publish.RoutingOutcome; -import dev.caskeleton.messaging.api.publish.TransmissionEvidence; -import java.time.Duration; -import java.util.Optional; -import java.util.concurrent.CompletionException; - -/** - * Converts an exception that escaped a publish into a result the caller can act on. - * - *

A {@link MessagingException} already carries a sanitized descriptor, including whether it is - * retryable, so its own classification is used. Anything else is reported {@code AMBIGUOUS}: an - * unrecognised exception proves nothing about whether the message reached the broker, and the - * conservative reading is the one that does not turn a lost confirmation into a duplicate. - */ -final class PublishResults { - - private PublishResults() {} - - /** - * Converts a failure into a publish result. - * - * @param failure the exception that escaped the publish - * @return the equivalent result - */ - static PublishResult from(Throwable failure) { - Throwable cause = failure instanceof CompletionException ? failure.getCause() : failure; - - if (cause instanceof MessagingException messagingFailure) { - FailureDescriptor descriptor = messagingFailure.failure(); - boolean transmitted = descriptor.category() == FailureCategory.AMBIGUOUS; - return new PublishResult( - transmitted ? PublishCompletion.AMBIGUOUS : PublishCompletion.REJECTED, - transmitted - ? new PublishEvidence( - true, - TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED, - false, - ConfirmationLevel.NONE) - : PublishEvidence.notTransmitted(), - transmitted ? RoutingOutcome.UNKNOWN : RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ZERO, - Optional.of(descriptor)); - } - - return new PublishResult( - PublishCompletion.AMBIGUOUS, - new PublishEvidence( - true, TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED, false, ConfirmationLevel.NONE), - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, - Duration.ZERO, - Optional.of( - FailureDescriptor.of( - FailureCategory.AMBIGUOUS, - "UNCLASSIFIED_PUBLISH_FAILURE", - "the publish failed with an unrecognised error: " - + (cause == null ? "unknown" : cause.getClass().getSimpleName())))); - } -} diff --git a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/ReactiveMessagePublisher.java b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/ReactiveMessagePublisher.java deleted file mode 100644 index f59bdf12..00000000 --- a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/ReactiveMessagePublisher.java +++ /dev/null @@ -1,32 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import reactor.core.publisher.Mono; - -/** - * The Reactor facade over the asynchronous publisher. - * - *

Lives in the starter rather than the core so that {@code messaging-core-api} never depends on - * Reactor. A service that does not use Reactor should not inherit it through a messaging contract. - * - *

The returned {@code Mono} is cold and cancellable: nothing is published until it is - * subscribed, and cancelling the subscription cancels the underlying stage rather than leaving an - * orphaned publish in flight. - */ -public interface ReactiveMessagePublisher { - - /** - * Publishes one message. - * - * @param the payload type - * @param destination the logical destination - * @param message the envelope to publish - * @param options per-call options - * @return a cold {@code Mono} emitting the outcome and its evidence - */ - Mono publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options); -} diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/BatchPublisherTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/BatchPublisherTest.java deleted file mode 100644 index ee8855af..00000000 --- a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/BatchPublisherTest.java +++ /dev/null @@ -1,328 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.ProducerId; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.TraceContext; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.error.MessageTooLargeException; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.api.publish.BatchPublishOptions; -import dev.caskeleton.messaging.api.publish.BatchPublishResult; -import dev.caskeleton.messaging.api.publish.ConfirmationLevel; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishEvidence; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishRequest; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.api.publish.RoutingOutcome; -import dev.caskeleton.messaging.api.publish.TransmissionEvidence; -import java.time.Duration; -import java.time.Instant; -import java.util.ArrayList; -import java.util.List; -import java.util.Optional; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import org.junit.jupiter.api.Test; - -class BatchPublisherTest { - - private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - - private static PublishResult rejected() { - return new PublishResult( - PublishCompletion.REJECTED, - PublishEvidence.notTransmitted(), - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, - Duration.ZERO, - Optional.of( - dev.caskeleton.messaging.api.error.FailureDescriptor.of( - dev.caskeleton.messaging.api.error.FailureCategory.PERMANENT_BUSINESS, - "BROKER_REJECTED", - "the broker refused the message"))); - } - - private static PublishResult confirmed() { - return new PublishResult( - PublishCompletion.CONFIRMED, - new PublishEvidence( - true, - TransmissionEvidence.TRANSMITTED, - true, - ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK), - RoutingOutcome.ROUTED, - Optional.empty(), - 1, - Duration.ZERO, - Optional.empty()); - } - - /** Publishes according to a per-index script, so partial failures are reproducible. */ - private static MessagePublisher scripted(List script, List calls) { - return new MessagePublisher() { - private int index; - - @Override - public CompletionStage publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - int current = index++; - calls.add(current); - return switch (script.get(current)) { - case CONFIRM -> CompletableFuture.completedFuture(confirmed()); - case FAIL_ASYNC -> - CompletableFuture.failedFuture( - new MessageTooLargeException("PAYLOAD_LIMIT_EXCEEDED", "too large")); - case THROW_SYNC -> - throw new MessageTooLargeException("PAYLOAD_LIMIT_EXCEEDED", "too large"); - }; - } - }; - } - - private enum Outcome { - CONFIRM, - FAIL_ASYNC, - THROW_SYNC - } - - private static PublishRequest request() { - MessageDestination destination = - new MessageDestination<>( - new DestinationName("orders.v1"), new MessageType("order.created"), String.class); - MessageEnvelope envelope = - new MessageEnvelope<>( - MessageId.newId(), - new MessageType("order.created"), - new SchemaVersion(1), - NOW, - Optional.of(NOW), - new ProducerId("order-api"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - "{}"); - return PublishRequest.of(destination, envelope); - } - - private static List> requests(int count) { - List> requests = new ArrayList<>(); - for (int index = 0; index < count; index++) { - requests.add(request()); - } - return requests; - } - - private static BatchPublishResult publish(List script, BatchPublishOptions options) { - List calls = new ArrayList<>(); - return new DefaultBatchMessagePublisher(scripted(script, calls), () -> NOW) - .publish(requests(script.size()), options) - .toCompletableFuture() - .join(); - } - - @Test - void closingTheBatchPublisherStopsItsDeadlineScheduler() { - var deadlines = new java.util.concurrent.ScheduledThreadPoolExecutor(1); - var publisher = - new DefaultBatchMessagePublisher( - scripted(List.of(Outcome.CONFIRM), new ArrayList<>()), () -> NOW, deadlines); - - publisher.close(); - - assertThat(deadlines.isShutdown()).isTrue(); - } - - @Test - void everyEntryGetsItsOwnResultKeyedByIndex() { - BatchPublishResult result = - publish( - List.of(Outcome.CONFIRM, Outcome.CONFIRM, Outcome.CONFIRM), - BatchPublishOptions.defaults()); - - assertThat(result.items()).hasSize(3); - assertThat(result.items()).extracting(item -> item.index()).containsExactly(0, 1, 2); - assertThat(result.allConfirmed()).isTrue(); - } - - @Test - void oneFailedEntryDoesNotHideTheOthers() { - BatchPublishResult result = - publish( - List.of(Outcome.CONFIRM, Outcome.FAIL_ASYNC, Outcome.CONFIRM), - BatchPublishOptions.defaults()); - - assertThat(result.withCompletion(PublishCompletion.CONFIRMED)).hasSize(2); - assertThat(result.withCompletion(PublishCompletion.REJECTED)) - .as("the caller needs to know exactly which entries to resubmit") - .hasSize(1); - } - - @Test - void aSynchronousFailureStillProducesAnEntryResult() { - BatchPublishResult result = - publish(List.of(Outcome.THROW_SYNC, Outcome.CONFIRM), BatchPublishOptions.defaults()); - - assertThat(result.items()).hasSize(2); - assertThat(result.items().get(0).result().completion()).isEqualTo(PublishCompletion.REJECTED); - } - - @Test - void aRejectedEntryKeepsItsSanitizedFailureCode() { - BatchPublishResult result = - publish(List.of(Outcome.FAIL_ASYNC), BatchPublishOptions.defaults()); - - assertThat(result.items().get(0).result().failure()) - .hasValueSatisfying( - failure -> assertThat(failure.code()).isEqualTo("PAYLOAD_LIMIT_EXCEEDED")); - } - - @Test - void aBatchLargerThanItsLimitIsRefusedBeforeAnythingIsPublished() { - List calls = new ArrayList<>(); - DefaultBatchMessagePublisher publisher = - new DefaultBatchMessagePublisher(scripted(List.of(Outcome.CONFIRM), calls), () -> NOW); - - assertThatThrownBy( - () -> - publisher.publish( - requests(5), new BatchPublishOptions(Duration.ofSeconds(5), 2, false))) - .isInstanceOf(MessageTooLargeException.class); - assertThat(calls).isEmpty(); - } - - @Test - void stopOnFirstRejectionSkipsTheRemainingSubmissions() { - List calls = new ArrayList<>(); - BatchPublishResult result = - new DefaultBatchMessagePublisher( - scripted( - List.of(Outcome.CONFIRM, Outcome.THROW_SYNC, Outcome.CONFIRM, Outcome.CONFIRM), - calls), - () -> NOW) - .publish(requests(4), new BatchPublishOptions(Duration.ofSeconds(5), 100, true)) - .toCompletableFuture() - .join(); - - assertThat(calls).containsExactly(0, 1); - assertThat(result.items()) - .as("truncating the list left the caller unable to tell 'not submitted' from 'lost'") - .hasSize(4); - assertThat(result.items().get(3).result().failure().orElseThrow().code()) - .isEqualTo("NOT_SUBMITTED_AFTER_REJECTION"); - } - - @Test - @org.junit.jupiter.api.DisplayName( - "the batch deadline completes outstanding entries as ambiguous") - void theBatchDeadlineCompletesOutstandingEntries() { - BatchPublishResult result = - new DefaultBatchMessagePublisher( - new MessagePublisher() { - @Override - public CompletionStage publish( - MessageDestination destination, - MessageEnvelope message, - PublishOptions options) { - return new CompletableFuture<>(); - } - }, - () -> NOW) - .publish(requests(2), new BatchPublishOptions(Duration.ofMillis(50), 100, false)) - .toCompletableFuture() - .join(); - - assertThat(result.items()) - .as("options.timeout() was never read, so a publisher that never completes hung forever") - .hasSize(2); - assertThat(result.items()) - .allSatisfy( - item -> - assertThat(item.result().completion()) - .isEqualTo(dev.caskeleton.messaging.api.publish.PublishCompletion.AMBIGUOUS)); - } - - @Test - @org.junit.jupiter.api.DisplayName("a delayed rejection still stops the entries after it") - void aDelayedRejectionStopsLaterEntries() { - List calls = new ArrayList<>(); - java.util.concurrent.CompletableFuture - delayed = new java.util.concurrent.CompletableFuture<>(); - - BatchPublishResult result = - new DefaultBatchMessagePublisher( - new MessagePublisher() { - @Override - public CompletionStage publish( - MessageDestination destination, - MessageEnvelope message, - PublishOptions options) { - int index = calls.size(); - calls.add(index); - if (index == 0) { - // Resolves only after the publisher returns, which is what an asynchronous - // broker rejection looks like. The old loop only saw an already-completed - // failure, so every later entry was submitted anyway. - // Completed on another thread so the rejection lands after this method - // returns — the shape an asynchronous broker rejection actually has. - new Thread(() -> delayed.complete(rejected())).start(); - return delayed; - } - return CompletableFuture.completedFuture(confirmed()); - } - }, - () -> NOW) - .publish(requests(3), new BatchPublishOptions(Duration.ofSeconds(2), 100, true)) - .toCompletableFuture() - .join(); - - assertThat(calls).containsExactly(0); - assertThat(result.items()).hasSize(3); - assertThat(result.items().get(2).result().failure().orElseThrow().code()) - .isEqualTo("NOT_SUBMITTED_AFTER_REJECTION"); - } - - @Test - void withoutStopOnFirstRejectionEveryEntryIsAttempted() { - List calls = new ArrayList<>(); - new DefaultBatchMessagePublisher( - scripted(List.of(Outcome.THROW_SYNC, Outcome.CONFIRM, Outcome.CONFIRM), calls), - () -> NOW) - .publish(requests(3), BatchPublishOptions.defaults()) - .toCompletableFuture() - .join(); - - assertThat(calls).containsExactly(0, 1, 2); - } - - @Test - void aBatchIsNotATransactionSoConfirmedEntriesStayConfirmed() { - BatchPublishResult result = - publish(List.of(Outcome.CONFIRM, Outcome.FAIL_ASYNC), BatchPublishOptions.defaults()); - - assertThat(result.items().get(0).result().completion()) - .as("nothing can un-publish an entry the broker already confirmed") - .isEqualTo(PublishCompletion.CONFIRMED); - assertThat(result.allConfirmed()).isFalse(); - } - - @Test - void theDefaultOptionsAttemptEveryEntry() { - assertThat(BatchPublishOptions.defaults().stopOnFirstRejection()).isFalse(); - } -} diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/BlockingFacadeTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/BlockingFacadeTest.java deleted file mode 100644 index 0b60b6e5..00000000 --- a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/BlockingFacadeTest.java +++ /dev/null @@ -1,148 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.ProducerId; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.TraceContext; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.error.FailureCategory; -import dev.caskeleton.messaging.api.error.FailureDescriptor; -import dev.caskeleton.messaging.api.error.MessagePublishTimeoutException; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.api.publish.BatchPublishItemResult; -import dev.caskeleton.messaging.api.publish.BatchPublishResult; -import dev.caskeleton.messaging.api.publish.BlockingMessagePublisher; -import dev.caskeleton.messaging.api.publish.ConfirmationLevel; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishEvidence; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.api.publish.RoutingOutcome; -import java.time.Duration; -import java.time.Instant; -import java.util.List; -import java.util.Optional; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import org.junit.jupiter.api.Test; - -class BlockingFacadeTest { - - private static final MessageDestination ORDERS = - new MessageDestination<>( - new DestinationName("order-events"), new MessageType("order.created"), String.class); - - @Test - void aConfirmedPublishIsReturnedDirectly() { - BlockingMessagePublisher publisher = - new DefaultBlockingMessagePublisher( - new MessagePublisher() { - @Override - public CompletionStage publish( - MessageDestination destination, - MessageEnvelope message, - PublishOptions options) { - return CompletableFuture.completedFuture(confirmed()); - } - }); - - PublishResult result = publisher.publish(ORDERS, envelope(), PublishOptions.defaults()); - - assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED); - } - - @Test - void aStalledPublishTimesOutAsAmbiguousRatherThanBlockingForever() { - MessagePublisher stalled = - new MessagePublisher() { - @Override - public CompletionStage publish( - MessageDestination destination, - MessageEnvelope message, - PublishOptions options) { - return new CompletableFuture<>(); - } - }; - PublishOptions shortDeadline = - new PublishOptions( - Duration.ofMillis(50), - dev.caskeleton.messaging.api.destination.ConfirmationRequirement - .REPLICATION_OR_PERSISTENCE_ACK, - Optional.empty()); - - assertThatThrownBy( - () -> - new DefaultBlockingMessagePublisher(stalled) - .publish(ORDERS, envelope(), shortDeadline)) - .isInstanceOf(MessagePublishTimeoutException.class) - .satisfies( - thrown -> - assertThat(((MessagePublishTimeoutException) thrown).category()) - .isEqualTo(FailureCategory.AMBIGUOUS)); - } - - @Test - void aBatchKeepsPerItemOutcomes() { - BatchPublishResult batch = - new BatchPublishResult( - List.of( - new BatchPublishItemResult(0, MessageId.newId(), confirmed()), - new BatchPublishItemResult(1, MessageId.newId(), ambiguous())), - Duration.ofMillis(20)); - - assertThat(batch.allConfirmed()).isFalse(); - assertThat(batch.withCompletion(PublishCompletion.CONFIRMED)).hasSize(1); - assertThat(batch.withCompletion(PublishCompletion.AMBIGUOUS)).hasSize(1); - } - - private static MessageEnvelope envelope() { - return new MessageEnvelope<>( - MessageId.newId(), - new MessageType("order.created"), - new SchemaVersion(1), - Instant.parse("2026-08-10T09:15:00Z"), - Optional.of(Instant.parse("2026-08-10T09:15:00Z")), - new ProducerId("order-api"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - "payload"); - } - - private static PublishResult confirmed() { - return new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ofMillis(3), - Optional.empty()); - } - - private static PublishResult ambiguous() { - return new PublishResult( - PublishCompletion.AMBIGUOUS, - PublishEvidence.ambiguous(), - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, - Duration.ofSeconds(5), - Optional.of( - FailureDescriptor.of( - FailureCategory.AMBIGUOUS, "CONFIRM_TIMEOUT", "confirm timed out"))); - } -} diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerConfigTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerConfigTest.java index 643a088a..0340c8aa 100644 --- a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerConfigTest.java +++ b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerConfigTest.java @@ -90,6 +90,7 @@ class KafkaProducerConfigTest { private static Map producerConfig(AssertableApplicationContext context) { return KafkaMessagingAutoConfiguration.producerConfig( context.getBean(CompiledMessagingConfiguration.class), + context.getBean(KafkaBrokerCatalog.class), context.getBeanProvider(BrokerSecurityProfile.class), context.getBeanProvider(KafkaSecurityConfigurer.class)); } diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java index 98c4bde3..cfca0829 100644 --- a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java +++ b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java @@ -228,6 +228,7 @@ class KafkaProducerSecurityTest { private static Map producerConfig(AssertableApplicationContext context) { return KafkaMessagingAutoConfiguration.producerConfig( context.getBean(CompiledMessagingConfiguration.class), + context.getBean(KafkaBrokerCatalog.class), context.getBeanProvider(BrokerSecurityProfile.class), context.getBeanProvider(KafkaSecurityConfigurer.class)); } diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingAutoConfigurationTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingAutoConfigurationTest.java index 0d4708c6..d3c02ea6 100644 --- a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingAutoConfigurationTest.java +++ b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingAutoConfigurationTest.java @@ -11,11 +11,10 @@ import dev.caskeleton.messaging.api.delivery.OrderingScope; import dev.caskeleton.messaging.api.destination.DestinationKind; import dev.caskeleton.messaging.api.destination.DestinationName; import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.publish.BlockingMessagePublisher; import dev.caskeleton.messaging.api.publish.MessagePublisher; import dev.caskeleton.messaging.api.publish.PublishOptions; import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.policy.CapabilityTier; +import dev.caskeleton.messaging.policy.ApiTier; import dev.caskeleton.messaging.policy.ConsumerPolicy; import dev.caskeleton.messaging.policy.DeadLetterPolicy; import dev.caskeleton.messaging.policy.DestinationProfile; @@ -49,8 +48,6 @@ class MessagingAutoConfigurationTest { context -> assertThat(context) .hasSingleBean(ValidatedDestinationRegistry.class) - .hasSingleBean(BlockingMessagePublisher.class) - .hasSingleBean(ReactiveMessagePublisher.class) .hasSingleBean(MessagingAdmissionController.class) .hasSingleBean(GracefulShutdownCoordinator.class)); } @@ -300,7 +297,7 @@ class MessagingAutoConfigurationTest { retry, DeadLetterPolicy.to(new DestinationName("order-events-dlq")), PayloadPolicy.defaults(), - CapabilityTier.M1, + ApiTier.M1, false, false, false); diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationBindingTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationBindingTest.java index c3239aa2..f365f6e1 100644 --- a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationBindingTest.java +++ b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationBindingTest.java @@ -68,8 +68,11 @@ class MessagingConfigurationBindingTest { CompiledMessagingConfiguration compiled = context.getBean(CompiledMessagingConfiguration.class); assertThat(compiled.brokers()).containsOnlyKeys("kafka-primary"); - BrokerSettings kafka = compiled.brokers().get("kafka-primary"); - assertThat(kafka.type()).isEqualTo(BrokerSettings.KAFKA); + assertThat(compiled.brokers().get("kafka-primary").type()) + .isEqualTo(BrokerSettings.KAFKA); + KafkaBrokerSettings kafka = + KafkaBrokerSettings.bindAll(context.getEnvironment(), compiled) + .get("kafka-primary"); assertThat(kafka.bootstrapServers()) .containsExactly("broker-1:9093", "broker-2:9093"); assertThat(kafka.enableAutoCommit()).isFalse(); @@ -253,6 +256,26 @@ class MessagingConfigurationBindingTest { .hasMessageContaining("TRUST_ME")); } + @Test + @org.junit.jupiter.api.DisplayName("주소가 없는 Kafka broker는 Kafka starter가 그 키를 이름으로 대며 기동을 거부한다") + void aKafkaBrokerWithoutAnAddressIsRefusedByTheKafkaStarterNamingTheKey() { + // given + ApplicationContextRunner kafka = + runner + .withConfiguration(AutoConfigurations.of(KafkaMessagingAutoConfiguration.class)) + .withPropertyValues("app.messaging.brokers.kafka-primary.type=kafka"); + + // when + kafka.run( + context -> + // then + assertThat(context) + .hasFailed() + .getFailure() + .rootCause() + .hasMessageContaining("app.messaging.brokers.kafka-primary.bootstrap-servers")); + } + @Test void aProductionKafkaBrokerWithoutTransportSecurityFailsStartup() { runner diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfigurationTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfigurationTest.java new file mode 100644 index 00000000..b8471f83 --- /dev/null +++ b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfigurationTest.java @@ -0,0 +1,117 @@ +package dev.caskeleton.messaging.autoconfigure; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.messaging.api.MessageType; +import dev.caskeleton.messaging.api.delivery.HandleResult; +import dev.caskeleton.messaging.api.delivery.MessageDelivery; +import dev.caskeleton.messaging.api.delivery.MessageHandler; +import dev.caskeleton.messaging.api.destination.DestinationName; +import dev.caskeleton.messaging.api.destination.MessageDestination; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.CompletionStage; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.springframework.boot.autoconfigure.AutoConfigurations; +import org.springframework.boot.test.context.runner.ApplicationContextRunner; + +/** The consume pipeline turns on with a handler bean and refuses what it cannot honour. */ +class MessagingConsumeConfigurationTest { + + private final ApplicationContextRunner runner = + new ApplicationContextRunner() + .withConfiguration(AutoConfigurations.of(MessagingCoreAutoConfiguration.class)) + .withUserConfiguration(MessagingAutoConfigurationTest.PublisherConfiguration.class) + .withPropertyValues( + "app.messaging.brokers.kafka-primary.type=kafka", + "app.messaging.brokers.kafka-primary.bootstrap-servers[0]=broker-1:9093", + "app.messaging.destinations.order-events.broker=kafka-primary", + "app.messaging.destinations.order-events.kind=EVENT_STREAM", + "app.messaging.destinations.order-events.physical.topic=order.events.v1", + "app.messaging.destinations.order-events.schema.message-types[0]=order.created", + "app.messaging.destinations.order-events.guarantees.delivery=AT_MOST_ONCE"); + + @Test + @DisplayName("handler bean이 없으면 consumer를 만들지 않는다") + void withoutAHandlerBeanNoConsumerIsAssembled() { + // when + runner.run( + context -> + // then + assertThat(context).hasNotFailed().doesNotHaveBean(MessageConsumers.class)); + } + + @Test + @DisplayName("handler bean이 있으면 그 destination의 consumer가 group과 함께 조립된다") + void aHandlerBeanAssemblesAConsumerForItsDestinationWithItsGroup() { + // when + runner + .withPropertyValues("app.messaging.destinations.order-events.consumer.group=projection") + .withBean("ordersHandler", MessageHandler.class, MessagingConsumeConfigurationTest::handler) + .run( + context -> { + // then + assertThat(context).hasNotFailed(); + assertThat(context.getBean(MessageConsumers.class).consumers()) + .singleElement() + .satisfies( + consumer -> { + assertThat(consumer.profile().name().value()).isEqualTo("order-events"); + assertThat(consumer.group()).isEqualTo("projection"); + }); + }); + } + + @Test + @DisplayName("consumer.group이 없는 destination을 소비하는 handler는 기동을 거부한다") + void aHandlerForADestinationWithoutAConsumerGroupFailsStartup() { + // when + runner + .withBean("ordersHandler", MessageHandler.class, MessagingConsumeConfigurationTest::handler) + .run( + context -> + // then + assertThat(context) + .hasFailed() + .getFailure() + .rootCause() + .hasMessageContaining("order-events") + .hasMessageContaining("consumer.group")); + } + + @Test + @DisplayName("INBOX_TRANSACTIONAL destination에 IdempotentConsumer가 없으면 기동을 거부한다") + void anInboxDestinationWithoutAnIdempotentConsumerFailsStartup() { + // when + runner + .withPropertyValues( + "app.messaging.destinations.order-events.consumer.group=projection", + "app.messaging.destinations.order-events.guarantees.external-side-effect=" + + "INBOX_TRANSACTIONAL") + .withBean("ordersHandler", MessageHandler.class, MessagingConsumeConfigurationTest::handler) + .run( + context -> + // then + assertThat(context) + .hasFailed() + .getFailure() + .rootCause() + .hasMessageContaining("INBOX_TRANSACTIONAL") + .hasMessageContaining("IdempotentConsumer")); + } + + private static MessageHandler handler() { + return new MessageHandler<>() { + @Override + public MessageDestination destination() { + return new MessageDestination<>( + new DestinationName("order-events"), new MessageType("order.created"), String.class); + } + + @Override + public CompletionStage handle(MessageDelivery delivery) { + return CompletableFuture.completedFuture(HandleResult.success()); + } + }; + } +} diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpointTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpointTest.java index d69b9f2d..75c1bfaa 100644 --- a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpointTest.java +++ b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpointTest.java @@ -9,7 +9,7 @@ import dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee; import dev.caskeleton.messaging.api.delivery.OrderingScope; import dev.caskeleton.messaging.api.destination.DestinationKind; import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.policy.CapabilityTier; +import dev.caskeleton.messaging.policy.ApiTier; import dev.caskeleton.messaging.policy.ConsumerPolicy; import dev.caskeleton.messaging.policy.DeadLetterPolicy; import dev.caskeleton.messaging.policy.DestinationProfile; @@ -47,7 +47,7 @@ class MessagingEndpointTest { RetryPolicy.none(), DeadLetterPolicy.to(new DestinationName("orders.v1.dlq")), PayloadPolicy.defaults(), - CapabilityTier.M1, + ApiTier.M1, true, true, false); diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/ReactiveFacadeTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/ReactiveFacadeTest.java deleted file mode 100644 index 91e82fe9..00000000 --- a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/ReactiveFacadeTest.java +++ /dev/null @@ -1,162 +0,0 @@ -package dev.caskeleton.messaging.autoconfigure; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.api.ContentType; -import dev.caskeleton.messaging.api.MessageEnvelope; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.ProducerId; -import dev.caskeleton.messaging.api.SchemaVersion; -import dev.caskeleton.messaging.api.TraceContext; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; -import dev.caskeleton.messaging.api.header.MessageHeaders; -import dev.caskeleton.messaging.api.publish.ConfirmationLevel; -import dev.caskeleton.messaging.api.publish.MessagePublisher; -import dev.caskeleton.messaging.api.publish.PublishCompletion; -import dev.caskeleton.messaging.api.publish.PublishEvidence; -import dev.caskeleton.messaging.api.publish.PublishOptions; -import dev.caskeleton.messaging.api.publish.PublishResult; -import dev.caskeleton.messaging.api.publish.RoutingOutcome; -import java.time.Duration; -import java.time.Instant; -import java.util.Optional; -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.CompletionStage; -import java.util.concurrent.atomic.AtomicInteger; -import org.junit.jupiter.api.Test; -import reactor.core.publisher.Mono; -import reactor.test.StepVerifier; - -class ReactiveFacadeTest { - - private static final MessageDestination ORDERS = - new MessageDestination<>( - new DestinationName("order-events"), new MessageType("order.created"), String.class); - - private final AtomicInteger publishes = new AtomicInteger(); - - @Test - void nothingIsPublishedUntilTheMonoIsSubscribed() { - ReactiveMessagePublisher publisher = new DefaultReactiveMessagePublisher(counting()); - - Mono mono = publisher.publish(ORDERS, envelope(), PublishOptions.defaults()); - - assertThat(publishes.get()).as("assembly must not publish").isZero(); - - mono.block(); - - assertThat(publishes.get()).isEqualTo(1); - } - - @Test - void eachSubscriptionPublishesOnce() { - ReactiveMessagePublisher publisher = new DefaultReactiveMessagePublisher(counting()); - - Mono mono = publisher.publish(ORDERS, envelope(), PublishOptions.defaults()); - mono.block(); - mono.block(); - - assertThat(publishes.get()).isEqualTo(2); - } - - @Test - void theOutcomeIsEmittedAndTheMonoCompletes() { - ReactiveMessagePublisher publisher = new DefaultReactiveMessagePublisher(counting()); - - StepVerifier.create(publisher.publish(ORDERS, envelope(), PublishOptions.defaults())) - .assertNext( - result -> assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED)) - .verifyComplete(); - } - - @Test - void aFailedPublishPropagatesAsAnErrorSignal() { - MessagePublisher failing = - new MessagePublisher() { - @Override - public CompletionStage publish( - MessageDestination destination, - MessageEnvelope message, - PublishOptions options) { - return CompletableFuture.failedFuture(new IllegalStateException("broker down")); - } - }; - - StepVerifier.create( - new DefaultReactiveMessagePublisher(failing) - .publish(ORDERS, envelope(), PublishOptions.defaults())) - .expectErrorMessage("broker down") - .verify(); - } - - @Test - void theBlockingPublishRunsOffTheSubscribingThread() { - // given - java.util.concurrent.atomic.AtomicReference publishedOn = - new java.util.concurrent.atomic.AtomicReference<>(); - MessagePublisher recording = - new MessagePublisher() { - @Override - public CompletionStage publish( - MessageDestination destination, - MessageEnvelope message, - PublishOptions options) { - publishedOn.set(Thread.currentThread()); - return CompletableFuture.completedFuture(confirmed()); - } - }; - - // when - new DefaultReactiveMessagePublisher(recording) - .publish(ORDERS, envelope(), PublishOptions.defaults()) - .block(); - - // then - assertThat(publishedOn.get()) - .as("admission and the producer's metadata wait block; an event loop must not pay for it") - .isNotSameAs(Thread.currentThread()); - } - - private MessagePublisher counting() { - return new MessagePublisher() { - @Override - public CompletionStage publish( - MessageDestination destination, MessageEnvelope message, PublishOptions options) { - publishes.incrementAndGet(); - return CompletableFuture.completedFuture(confirmed()); - } - }; - } - - private static PublishResult confirmed() { - return new PublishResult( - PublishCompletion.CONFIRMED, - PublishEvidence.confirmed(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ofMillis(2), - Optional.empty()); - } - - private static MessageEnvelope envelope() { - return new MessageEnvelope<>( - MessageId.newId(), - new MessageType("order.created"), - new SchemaVersion(1), - Instant.parse("2026-08-10T09:15:00Z"), - Optional.of(Instant.parse("2026-08-10T09:15:00Z")), - new ProducerId("order-api"), - Optional.empty(), - Optional.empty(), - ContentType.JSON, - Optional.empty(), - Optional.empty(), - Optional.empty(), - TraceContext.none(), - MessageHeaders.empty(), - "payload"); - } -} diff --git a/src/messaging/messaging-testkit/build.gradle b/src/messaging/messaging-testkit/build.gradle index a7492ce5..0b4b6577 100644 --- a/src/messaging/messaging-testkit/build.gradle +++ b/src/messaging/messaging-testkit/build.gradle @@ -10,7 +10,6 @@ jmh { dependencies { api project(':messaging:messaging-core-api') - api project(':messaging:messaging-schema-api') api project(':messaging:messaging-policy') api project(':messaging:messaging-transport-spi') diff --git a/src/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CompatibilityMatrix.java b/src/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CompatibilityMatrix.java index 42d42710..482d9b41 100644 --- a/src/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CompatibilityMatrix.java +++ b/src/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CompatibilityMatrix.java @@ -5,22 +5,22 @@ import java.util.Map; import java.util.Objects; /** - * The certified broker versions and support tier for every adapter. + * The certified broker versions and support grade for every adapter. * *

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

The certification claim is derived from lane evidence rather than declared beside the tier, so - * an adapter cannot be promoted by editing a boolean. + *

The certification claim is derived from lane evidence rather than declared beside the grade, + * so an adapter cannot be promoted by editing a boolean. */ public final class CompatibilityMatrix { private CompatibilityMatrix() {} - /** The support tier an adapter has earned. */ - public enum Tier { + /** The support grade an adapter has earned. */ + public enum SupportGrade { /** Passes the shared adapter contract unchanged. */ STABLE, @@ -36,14 +36,14 @@ public final class CompatibilityMatrix { * * @param adapter the module name * @param brokerVersions the broker versions the adapter is certified against - * @param tier the support tier + * @param grade the support grade * @param runsSharedContract whether the module runs {@link MessagingAdapterContract} * @param enabledByDefault whether the adapter is active without an explicit opt-in */ public record Entry( String adapter, List brokerVersions, - Tier tier, + SupportGrade grade, boolean runsSharedContract, boolean enabledByDefault) { @@ -51,7 +51,7 @@ public final class CompatibilityMatrix { * Reports whether a lane has run this adapter against a real broker. * *

Read from the evidence rather than declared. As a field it was a boolean an author set - * next to the tier, and an Experimental adapter carried {@code true} while no fault scenario + * next to the grade, and an Experimental adapter carried {@code true} while no fault scenario * had ever been executed against it — the same shape as the coverage matrix that used to assert * its own constants. * @@ -63,7 +63,7 @@ public final class CompatibilityMatrix { } public Entry { - Objects.requireNonNull(tier, "tier must not be null"); + Objects.requireNonNull(grade, "grade must not be null"); Objects.requireNonNull(brokerVersions, "brokerVersions must not be null"); if (adapter == null || adapter.isBlank()) { throw new IllegalArgumentException("adapter must not be blank"); @@ -82,7 +82,7 @@ public final class CompatibilityMatrix { // the locked client is 4.1.1, so the matrix and the support document agreed with each // other and with nothing that had executed. A version returns here when a lane runs // against its image. - new Entry("messaging-kafka", List.of("4.1"), Tier.STABLE, true, true)); + new Entry("messaging-kafka", List.of("4.1"), SupportGrade.STABLE, true, true)); /** * Returns every certified adapter. diff --git a/src/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CompatibilityMatrixTest.java b/src/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CompatibilityMatrixTest.java index 7cccaf21..2bff244f 100644 --- a/src/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CompatibilityMatrixTest.java +++ b/src/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CompatibilityMatrixTest.java @@ -23,7 +23,7 @@ class CompatibilityMatrixTest { @Test void everyStableAdapterRunsTheSharedContract() { assertThat(CompatibilityMatrix.entries().values()) - .filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.STABLE) + .filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE) .isNotEmpty() .allSatisfy(entry -> assertThat(entry.runsSharedContract()).isTrue()); } @@ -31,14 +31,14 @@ class CompatibilityMatrixTest { @Test void noExperimentalAdapterIsEnabledByDefault() { assertThat(CompatibilityMatrix.entries().values()) - .filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.EXPERIMENTAL) + .filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.EXPERIMENTAL) .allSatisfy(entry -> assertThat(entry.enabledByDefault()).isFalse()); } @Test void theStableSetIsExactlyWhatALaneHasCertified() { assertThat(CompatibilityMatrix.entries().values()) - .filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.STABLE) + .filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE) .extracting(CompatibilityMatrix.Entry::adapter) .containsExactly("messaging-kafka"); } @@ -59,7 +59,7 @@ class CompatibilityMatrixTest { @Test void everyStableAdapterHasOnlyExplicitlyApprovedEvidenceGaps() { assertThat(CompatibilityMatrix.entries().values()) - .filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.STABLE) + .filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE) .allSatisfy( entry -> assertThat(CertifiedEvidence.approvedGaps(entry.adapter())) @@ -98,14 +98,14 @@ class CompatibilityMatrixTest { assertThatThrownBy( () -> new CompatibilityMatrix.Entry( - "messaging-x", List.of(), CompatibilityMatrix.Tier.STABLE, true, true)) + "messaging-x", List.of(), CompatibilityMatrix.SupportGrade.STABLE, true, true)) .isInstanceOf(IllegalArgumentException.class); } @Test void everyStableAdapterIsCertifiedAgainstALiveBroker() { assertThat(CompatibilityMatrix.entries().values()) - .filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.STABLE) + .filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE) .isNotEmpty() .allSatisfy( entry -> @@ -119,7 +119,7 @@ class CompatibilityMatrixTest { @Test void noExperimentalAdapterClaimsLiveBrokerCertification() { assertThat(CompatibilityMatrix.entries().values()) - .filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.EXPERIMENTAL) + .filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.EXPERIMENTAL) .allSatisfy(entry -> assertThat(entry.hasLiveBrokerCertification()).isFalse()); } @@ -127,7 +127,11 @@ class CompatibilityMatrixTest { void anAdapterWithoutEvidenceCannotBeCalledStable() { CompatibilityMatrix.Entry undeclared = new CompatibilityMatrix.Entry( - "messaging-artemis", List.of("2.42"), CompatibilityMatrix.Tier.STABLE, true, false); + "messaging-artemis", + List.of("2.42"), + CompatibilityMatrix.SupportGrade.STABLE, + true, + false); assertThat(undeclared.hasLiveBrokerCertification()) .as("promoting an adapter used to be a boolean an author could set beside the tier") diff --git a/src/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CrossBrokerContractSuite.java b/src/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CrossBrokerContractSuite.java index ff0b29be..be044b0f 100644 --- a/src/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CrossBrokerContractSuite.java +++ b/src/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CrossBrokerContractSuite.java @@ -35,7 +35,7 @@ class CrossBrokerContractSuite { private static List stableAdapters() { return CompatibilityMatrix.entries().values().stream() - .filter(entry -> entry.tier() == CompatibilityMatrix.Tier.STABLE) + .filter(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE) .map(CompatibilityMatrix.Entry::adapter) .toList(); } @@ -88,7 +88,7 @@ class CrossBrokerContractSuite { void noExperimentalAdapterClaimsLiveBrokerFaultCoverage() { List experimental = CompatibilityMatrix.entries().values().stream() - .filter(entry -> entry.tier() == CompatibilityMatrix.Tier.EXPERIMENTAL) + .filter(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.EXPERIMENTAL) .map(CompatibilityMatrix.Entry::adapter) .toList(); diff --git a/src/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/MessagingDocumentationContractTest.java b/src/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/MessagingDocumentationContractTest.java index e97c8ac9..cc5755ba 100644 --- a/src/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/MessagingDocumentationContractTest.java +++ b/src/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/MessagingDocumentationContractTest.java @@ -62,7 +62,7 @@ class MessagingDocumentationContractTest { String matrix = read("support-matrix.md"); CompatibilityMatrix.entries().values().stream() - .filter(entry -> entry.tier() == CompatibilityMatrix.Tier.STABLE) + .filter(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE) .forEach(entry -> assertThat(matrix).contains(brokerLabel(entry.adapter()))); } @@ -71,7 +71,7 @@ class MessagingDocumentationContractTest { String matrix = read("support-matrix.md"); CompatibilityMatrix.entries().values().stream() - .filter(entry -> entry.tier() == CompatibilityMatrix.Tier.EXPERIMENTAL) + .filter(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.EXPERIMENTAL) .forEach( entry -> assertThat(matrix) diff --git a/src/messaging/messaging-transport-spi/build.gradle b/src/messaging/messaging-transport-spi/build.gradle index 81e3e70b..55c8be51 100644 --- a/src/messaging/messaging-transport-spi/build.gradle +++ b/src/messaging/messaging-transport-spi/build.gradle @@ -4,6 +4,5 @@ plugins { dependencies { api project(':messaging:messaging-core-api') - api project(':messaging:messaging-schema-api') api project(':messaging:messaging-policy') } diff --git a/src/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingLifecycle.java b/src/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingLifecycle.java deleted file mode 100644 index e45aa2bb..00000000 --- a/src/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingLifecycle.java +++ /dev/null @@ -1,67 +0,0 @@ -package dev.caskeleton.messaging.transport; - -import java.time.Duration; - -/** - * The ordered lifecycle every messaging runtime implements. - * - *

The order in {@link ShutdownPhase} is the contract, not an implementation detail. Closing - * connections before settlements have been transmitted loses the settlements, and pausing consumers - * after draining lets fresh deliveries arrive into a runtime that is already shutting down. Each - * adapter implements the phases; none of them chooses the order. - * - *

Implementations are driven by the Spring lifecycle rather than a JVM shutdown hook alone. A - * shutdown hook runs after the context has already begun disposing beans, so a handler mid-drain - * can find its datasource closed underneath it. - */ -public interface MessagingLifecycle { - - /** The fixed phases of an orderly shutdown, in the order they must run. */ - enum ShutdownPhase { - /** Refuse new publishes. Nothing in flight is affected. */ - STOP_PUBLISH_ADMISSION, - /** Refuse to start new delivery handlers. */ - STOP_NEW_HANDLERS, - /** Ask the broker to stop delivering. */ - PAUSE_CONSUMERS, - /** Let running handlers finish. */ - DRAIN_HANDLERS, - /** Transmit the settlements those handlers produced. */ - FLUSH_SETTLEMENTS, - /** Wait for outstanding producer confirms so publishes are not left ambiguous. */ - AWAIT_PRODUCER_CONFIRMS, - /** Return outbox leases so another relay can claim the rows immediately. */ - RELEASE_OUTBOX_LEASES, - /** Close connections and channels. */ - CLOSE_CONNECTIONS - } - - /** The default drain budget from the design. */ - Duration DEFAULT_DRAIN_DEADLINE = Duration.ofSeconds(30); - - /** - * Starts the runtime. - * - * @throws IllegalStateException when the runtime was already started - */ - void start(); - - /** - * Runs the shutdown phases in order, bounded by the drain deadline. - * - *

Work still running at the deadline is abandoned unsettled so the broker redelivers - * it. Unconfirmed publishes are recorded as ambiguous rather than as successes. - * - * @param drainDeadline how long in-flight work may take - * @return the phase that was still running when the deadline passed, or {@link - * ShutdownPhase#CLOSE_CONNECTIONS} when the shutdown completed - */ - ShutdownPhase shutdown(Duration drainDeadline); - - /** - * Reports whether the runtime is running and accepting work. - * - * @return true between {@link #start()} and the first shutdown phase - */ - boolean isRunning(); -} diff --git a/src/messaging/messaging-transport-spi/src/test/java/dev/caskeleton/messaging/transport/MessagingLifecycleTest.java b/src/messaging/messaging-transport-spi/src/test/java/dev/caskeleton/messaging/transport/MessagingLifecycleTest.java deleted file mode 100644 index beabf828..00000000 --- a/src/messaging/messaging-transport-spi/src/test/java/dev/caskeleton/messaging/transport/MessagingLifecycleTest.java +++ /dev/null @@ -1,59 +0,0 @@ -package dev.caskeleton.messaging.transport; - -import static org.assertj.core.api.Assertions.assertThat; - -import dev.caskeleton.messaging.transport.MessagingLifecycle.ShutdownPhase; -import java.time.Duration; -import java.util.List; -import org.junit.jupiter.api.Test; - -class MessagingLifecycleTest { - - @Test - void publishAdmissionClosesBeforeConsumersArePaused() { - List order = List.of(ShutdownPhase.values()); - - assertThat(order.indexOf(ShutdownPhase.STOP_PUBLISH_ADMISSION)) - .isLessThan(order.indexOf(ShutdownPhase.PAUSE_CONSUMERS)); - } - - @Test - void handlersDrainBeforeTheirSettlementsAreFlushed() { - List order = List.of(ShutdownPhase.values()); - - assertThat(order.indexOf(ShutdownPhase.DRAIN_HANDLERS)) - .as("flushing before the handlers finish would lose the settlements they produce") - .isLessThan(order.indexOf(ShutdownPhase.FLUSH_SETTLEMENTS)); - } - - @Test - void connectionsCloseLastOfAll() { - ShutdownPhase[] order = ShutdownPhase.values(); - - assertThat(order[order.length - 1]) - .as("every earlier phase needs the connection that this one closes") - .isEqualTo(ShutdownPhase.CLOSE_CONNECTIONS); - } - - @Test - void producerConfirmsAreAwaitedBeforeTheConnectionGoesAway() { - List order = List.of(ShutdownPhase.values()); - - assertThat(order.indexOf(ShutdownPhase.AWAIT_PRODUCER_CONFIRMS)) - .as("a confirm that arrives after close cannot be observed, leaving the publish ambiguous") - .isLessThan(order.indexOf(ShutdownPhase.CLOSE_CONNECTIONS)); - } - - @Test - void outboxLeasesAreReleasedBeforeClosing() { - List order = List.of(ShutdownPhase.values()); - - assertThat(order.indexOf(ShutdownPhase.RELEASE_OUTBOX_LEASES)) - .isLessThan(order.indexOf(ShutdownPhase.CLOSE_CONNECTIONS)); - } - - @Test - void theDefaultDrainDeadlineMatchesTheDesign() { - assertThat(MessagingLifecycle.DEFAULT_DRAIN_DEADLINE).isEqualTo(Duration.ofSeconds(30)); - } -}