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

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

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

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-29 13:29:46 +09:00
co-authored by Claude Opus 5.5
parent 6397f52dc8
commit 763392c8b2
188 changed files with 3405 additions and 4015 deletions
@@ -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).
*
* <p>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<OrderCreated> received = new LinkedBlockingQueue<>();
MessageHandler<OrderCreated> 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> T inTransaction(java.util.function.Supplier<T> work) {
return transactions.execute(status -> work.get());
}
});
AtomicInteger calls = new AtomicInteger();
MessageHandler<OrderCreated> 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<OrderCreated> 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<OrderCreated> 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<OrderCreated> 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<OrderCreated> handler(
DestinationName orders, Function<MessageDelivery<OrderCreated>, HandleResult> body) {
return new MessageHandler<>() {
@Override
public MessageDestination<OrderCreated> destination() {
return new MessageDestination<>(orders, CREATED, OrderCreated.class);
}
@Override
public CompletionStage<HandleResult> handle(MessageDelivery<OrderCreated> delivery) {
return CompletableFuture.completedFuture(body.apply(delivery));
}
};
}
private static void publish(
MessagePublisher publisher, DestinationName orders, MessageEnvelope<OrderCreated> 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<OrderCreated> 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<TopicPartition, OffsetAndMetadata> 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<String> 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<byte[], byte[]> consumer = new KafkaConsumer<>(config)) {
consumer.subscribe(List.of(topic));
Instant deadline = Instant.now().plusSeconds(60);
while (Instant.now().isBefore(deadline)) {
List<String> 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<byte[], byte[]> 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);
}
}
}
@@ -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);
@@ -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.
*
* <p>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.
* <p>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}).
*
* <p>{@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<String> 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";
@@ -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.
*
* <p>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.
*
* <p>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.
*
* <p>{@code stopOnFirstRejection} short-circuits the <em>submission</em>, 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<Instant> 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<Instant> 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<Instant> 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<BatchPublishResult> publish(
List<PublishRequest<?>> 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<CompletableFuture<BatchPublishItemResult>> 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<BatchPublishItemResult> 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<BatchPublishItemResult> 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<BatchPublishResult> completed = new CompletableFuture<>();
CompletableFuture<Void> 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<Void> 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<CompletableFuture<BatchPublishItemResult>> 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.
*
* <p>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<BatchPublishItemResult> resolveAll(
List<CompletableFuture<BatchPublishItemResult>> pending,
List<BatchPublishItemResult> placeholders) {
List<BatchPublishItemResult> resolved = new ArrayList<>(pending.size());
for (int index = 0; index < pending.size(); index++) {
CompletableFuture<BatchPublishItemResult> 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 <T> CompletableFuture<BatchPublishItemResult> submit(
PublishRequest<?> request, int index) {
@SuppressWarnings("unchecked")
PublishRequest<T> typed = (PublishRequest<T>) request;
MessageDestination<T> destination = typed.destination();
MessageEnvelope<T> 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)));
}
}
}
@@ -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.
*
* <p>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 <T> PublishResult publish(
MessageDestination<T> destination, MessageEnvelope<T> message, PublishOptions options) {
Objects.requireNonNull(options, "options must not be null");
CompletableFuture<PublishResult> 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);
}
}
}
@@ -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}.
*
* <p>{@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 <T> Mono<PublishResult> publish(
MessageDestination<T> destination, MessageEnvelope<T> 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());
}
}
@@ -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,
@@ -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.
*
* <p>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<Consumer> 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<TransportDelivery, CompletionStage<Void>> 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");
}
}
}
}
@@ -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()));
}
}
@@ -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<String> rejected = new ArrayList<>();
sections.forEach(
(section, shape) -> {
Set<String> legal = leafPaths(shape);
Set<String> common = leafPaths(shape);
for (String key : keysUnder(MessagingSettings.PREFIX + '.' + section + '.')) {
Entry entry = split(key, MessagingSettings.PREFIX + '.' + section + '.');
if (entry.leaf().isEmpty()) {
continue;
}
Set<String> 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.
*
* <p>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<String> brokerLeafPaths(String brokerName, Set<String> 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<String> 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) {}
@@ -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).
*
* <p>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:
*
* <ul>
* <li>a handler for a destination nobody declared;
* <li>a consumed destination without {@code consumer.group} — the group is also the inbox
* identity, and inventing one would split or merge consumers silently;
* <li>a destination the broker's security profile does not list as consumable;
* <li>{@code INBOX_TRANSACTIONAL} without an {@link IdempotentConsumer} bean to run it.
* </ul>
*/
@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<MessageHandler<?>> handlers,
ValidatedDestinationRegistry destinations,
MessageCodecRegistry codecs,
DeadLetterOrchestrator deadLetters,
ObjectProvider<IdempotentConsumer> inbox,
CompiledMessagingConfiguration compiled,
ObjectProvider<BrokerSecurityProfile> declaredSecurity) {
Map<DestinationName, List<MessageHandler<?>>> byDestination = new LinkedHashMap<>();
handlers
.orderedStream()
.forEach(
handler ->
byDestination
.computeIfAbsent(handler.destination().name(), name -> new ArrayList<>())
.add(handler));
Map<String, DestinationAccessPolicy> access = new LinkedHashMap<>();
Stream.concat(compiled.security().stream(), declaredSecurity.orderedStream())
.forEach(profile -> access.putIfAbsent(profile.broker(), profile.access()));
List<MessageConsumers.Consumer> 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<MessageHandler<?>> pipeline =
profile.externalSideEffectGuarantee()
== ExternalSideEffectGuarantee.INBOX_TRANSACTIONAL
? forDestination.stream()
.<MessageHandler<?>>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 <T> MessageHandler<T> inboxed(
MessageHandler<T> 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);
}
}
@@ -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.
*
* <p>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.
* <p>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.
*
* <p>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.
*
* <p>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.
*
* <p>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.
*
* <p>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.
*
* <p>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.
*
* <p>Returns a marker rather than a service because its only job is to fail the context when the
* registry is inconsistent.
*
* <p>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<DestinationProfile> profiles, CompiledMessagingConfiguration compiled) {
List<DestinationProfile> 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<dev.caskeleton.messaging.security.BrokerSecurityProfile>
brokerSecurityStartupValidation(
ObjectProvider<dev.caskeleton.messaging.security.BrokerSecurityProfile> 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.
*
* <p>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.
*
* <p>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).
*
* <p>The message contracts come from the deployment — a {@code Map} of message type and schema
* version to payload class — and default to <b>empty</b>, 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<MessageContracts> 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.
*
* <p>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.
*
* <p>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<dev.caskeleton.messaging.security.BrokerSecurityProfile> declared) {
java.util.Map<String, dev.caskeleton.messaging.security.DestinationAccessPolicy> 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).
*
* <p>{@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<dev.caskeleton.messaging.observation.MessagingObservation> 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).
*
* <p>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<dev.caskeleton.messaging.transport.MessagingTransport> 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<String> 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 {}
@@ -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.
*
* <p>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.
*
* <p>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);
}
}
@@ -45,6 +45,16 @@ public class MessagingProviderSelection {
static final Map<String, String> 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.<name>} entry into.
*
* <p>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<String, String> 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<String, String> PROVIDER_STARTERS =
Map.of("kafka", "messaging-spring-boot-starter-kafka");
@@ -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.
*
* <p>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).
*
* <p>The message contracts come from the deployment — a {@code Map} of message type and schema
* version to payload class — and default to <b>empty</b>, 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<MessageContracts> 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.
*
* <p>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.
*
* <p>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<dev.caskeleton.messaging.security.BrokerSecurityProfile> declared) {
java.util.Map<String, dev.caskeleton.messaging.security.DestinationAccessPolicy> 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).
*
* <p>{@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<dev.caskeleton.messaging.observation.MessagingObservation> 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).
*
* <p>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<dev.caskeleton.messaging.transport.MessagingTransport> 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<String> 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();
}
}
@@ -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<Object> transactionalInboxHandler(IdempotentConsumer consumer) {
return new TransactionalInboxHandler<>(consumer, Instant::now);
}
}
@@ -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.
*
* <p>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.
*
* <p>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.
*
* <p>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.
*
* <p>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.
*
* <p>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.
*
* <p>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.
*
* <p>Returns a marker rather than a service because its only job is to fail the context when the
* registry is inconsistent.
*
* <p>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<DestinationProfile> profiles, CompiledMessagingConfiguration compiled) {
List<DestinationProfile> 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<dev.caskeleton.messaging.security.BrokerSecurityProfile>
brokerSecurityStartupValidation(
ObjectProvider<dev.caskeleton.messaging.security.BrokerSecurityProfile> 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.
*
* <p>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();
}
}
@@ -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.
*
* <p>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()))));
}
}
@@ -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.
*
* <p>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.
*
* <p>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 <T> 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
*/
<T> Mono<PublishResult> publish(
MessageDestination<T> destination, MessageEnvelope<T> message, PublishOptions options);
}
@@ -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<Outcome> script, List<Integer> calls) {
return new MessagePublisher() {
private int index;
@Override
public <T> CompletionStage<PublishResult> publish(
MessageDestination<T> destination, MessageEnvelope<T> 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<String> request() {
MessageDestination<String> destination =
new MessageDestination<>(
new DestinationName("orders.v1"), new MessageType("order.created"), String.class);
MessageEnvelope<String> 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<PublishRequest<?>> requests(int count) {
List<PublishRequest<?>> requests = new ArrayList<>();
for (int index = 0; index < count; index++) {
requests.add(request());
}
return requests;
}
private static BatchPublishResult publish(List<Outcome> script, BatchPublishOptions options) {
List<Integer> 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<Integer> 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<Integer> 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 <T> CompletionStage<PublishResult> publish(
MessageDestination<T> destination,
MessageEnvelope<T> 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<Integer> calls = new ArrayList<>();
java.util.concurrent.CompletableFuture<dev.caskeleton.messaging.api.publish.PublishResult>
delayed = new java.util.concurrent.CompletableFuture<>();
BatchPublishResult result =
new DefaultBatchMessagePublisher(
new MessagePublisher() {
@Override
public <T> CompletionStage<PublishResult> publish(
MessageDestination<T> destination,
MessageEnvelope<T> 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<Integer> 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();
}
}
@@ -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<String> ORDERS =
new MessageDestination<>(
new DestinationName("order-events"), new MessageType("order.created"), String.class);
@Test
void aConfirmedPublishIsReturnedDirectly() {
BlockingMessagePublisher publisher =
new DefaultBlockingMessagePublisher(
new MessagePublisher() {
@Override
public <T> CompletionStage<PublishResult> publish(
MessageDestination<T> destination,
MessageEnvelope<T> 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 <T> CompletionStage<PublishResult> publish(
MessageDestination<T> destination,
MessageEnvelope<T> 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<String> 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")));
}
}
@@ -90,6 +90,7 @@ class KafkaProducerConfigTest {
private static Map<String, Object> producerConfig(AssertableApplicationContext context) {
return KafkaMessagingAutoConfiguration.producerConfig(
context.getBean(CompiledMessagingConfiguration.class),
context.getBean(KafkaBrokerCatalog.class),
context.getBeanProvider(BrokerSecurityProfile.class),
context.getBeanProvider(KafkaSecurityConfigurer.class));
}
@@ -228,6 +228,7 @@ class KafkaProducerSecurityTest {
private static Map<String, Object> producerConfig(AssertableApplicationContext context) {
return KafkaMessagingAutoConfiguration.producerConfig(
context.getBean(CompiledMessagingConfiguration.class),
context.getBean(KafkaBrokerCatalog.class),
context.getBeanProvider(BrokerSecurityProfile.class),
context.getBeanProvider(KafkaSecurityConfigurer.class));
}
@@ -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);
@@ -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
@@ -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<String> handler() {
return new MessageHandler<>() {
@Override
public MessageDestination<String> destination() {
return new MessageDestination<>(
new DestinationName("order-events"), new MessageType("order.created"), String.class);
}
@Override
public CompletionStage<HandleResult> handle(MessageDelivery<String> delivery) {
return CompletableFuture.completedFuture(HandleResult.success());
}
};
}
}
@@ -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);
@@ -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<String> 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<PublishResult> 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<PublishResult> 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 <T> CompletionStage<PublishResult> publish(
MessageDestination<T> destination,
MessageEnvelope<T> 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<Thread> publishedOn =
new java.util.concurrent.atomic.AtomicReference<>();
MessagePublisher recording =
new MessagePublisher() {
@Override
public <T> CompletionStage<PublishResult> publish(
MessageDestination<T> destination,
MessageEnvelope<T> 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 <T> CompletionStage<PublishResult> publish(
MessageDestination<T> destination, MessageEnvelope<T> 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<String> 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");
}
}