refactor: 각 어댑터터별 리펙토링 진행

This commit is contained in:
DongHyeonka
2026-08-24 18:26:40 +09:00
parent 16e33ce986
commit a261df2a2b
100 changed files with 7072 additions and 902 deletions
@@ -0,0 +1,50 @@
package dev.caskeleton.messaging.autoconfigure;
import java.util.List;
import org.springframework.boot.context.properties.bind.DefaultValue;
/**
* One entry of {@code app.messaging.security}, keyed by the broker it secures.
*
* <p>No field here holds a secret, and that is a structural rule rather than a convention: the
* platform stores a credential id and resolves the material through a {@code CredentialProvider} at
* connect time, so a configuration dump or a heap dump yields a name and nothing usable.
*
* <p>The admin credential is bindable and its presence on a production broker is a startup failure.
* Leaving it unbindable would have been the safer-looking choice and the wrong one: an operator who
* needs it in a non-production runtime would then configure it somewhere the platform cannot see,
* and the check that refuses it in production would have nothing to refuse.
*
* @param producer the producer credential
* @param consumer the consumer credential
* @param admin the admin credential, which an application runtime must not hold in production
* @param hostnameVerification whether the server certificate hostname is verified
* @param access which destinations each role may touch
*/
public record BrokerSecuritySettings(
Credential producer,
Credential consumer,
Credential admin,
@DefaultValue("true") boolean hostnameVerification,
@DefaultValue Access access) {
/**
* One credential reference.
*
* @param type the authentication mechanism
* @param credentialId the identifier the credential provider resolves
*/
public record Credential(String type, String credentialId) {}
/**
* Which destinations each role may touch.
*
* @param publishable destinations the producer credential may publish to
* @param consumable destinations the consumer credential may consume
* @param administrable destinations the admin credential may operate on
*/
public record Access(
@DefaultValue List<String> publishable,
@DefaultValue List<String> consumable,
@DefaultValue List<String> administrable) {}
}
@@ -0,0 +1,69 @@
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}.
*
* <p>Both broker families are described by one record because a deployment names its brokers in one
* map, and a reader of that map should not have to know which half of the fields apply. Which half
* does apply is decided by {@link #type()}, and the compiler refuses a field belonging to the other
* family rather than ignoring it — a Kafka broker carrying {@code prefetch} is a configuration the
* author believed was doing something.
*
* <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
* constructed, which is how a profile can be production in one validator's view and not in
* another's.
*
* @param type the broker family, {@code kafka} or {@code rabbitmq}
* @param stable whether this profile claims the Stable guarantees
* @param production whether this profile is used in production
* @param tlsEnabled whether transport encryption is on
* @param authenticationEnabled whether broker authentication is on
* @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
* @param addresses RabbitMQ broker addresses
* @param publisherConfirms whether correlated publisher confirms are on
* @param publisherReturns whether unroutable returns are delivered
* @param mandatory whether publishes carry the mandatory flag
* @param confirmTimeout how long to wait for a RabbitMQ confirm
* @param autoAck whether the RabbitMQ consumer acknowledges on delivery
* @param prefetch the RabbitMQ consumer prefetch window
* @param quorumQueues whether durable work queues are declared as quorum queues
*/
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 List<String> addresses,
@DefaultValue("true") boolean publisherConfirms,
@DefaultValue("true") boolean publisherReturns,
@DefaultValue("true") boolean mandatory,
@DefaultValue("5s") Duration confirmTimeout,
@DefaultValue("false") boolean autoAck,
@DefaultValue("16") int prefetch,
@DefaultValue("true") boolean quorumQueues) {
/** The broker family a Kafka entry declares. */
public static final String KAFKA = "kafka";
/** The broker family a RabbitMQ entry declares. */
public static final String RABBITMQ = "rabbitmq";
}
@@ -0,0 +1,53 @@
package dev.caskeleton.messaging.autoconfigure;
import dev.caskeleton.messaging.kafka.KafkaBrokerProfile;
import dev.caskeleton.messaging.policy.DestinationProfile;
import dev.caskeleton.messaging.rabbit.RabbitBrokerProfile;
import dev.caskeleton.messaging.security.BrokerSecurityProfile;
import java.util.List;
import java.util.Objects;
/**
* What the documented configuration compiles to.
*
* <p>One object rather than four beans, because the four are only meaningful together: a
* destination names a broker, a security entry secures one, and a compile that produced three of
* the four would leave the fourth silently empty. Holding them as one result means the startup
* validations either all see this deployment's configuration or the compile failed.
*
* @param destinations the destination profiles built from {@code app.messaging.destinations}
* @param kafkaBrokers the Kafka profiles built from {@code app.messaging.brokers}
* @param rabbitBrokers the RabbitMQ profiles built from {@code app.messaging.brokers}
* @param security the broker security profiles built from {@code app.messaging.security}
*/
public record CompiledMessagingConfiguration(
List<DestinationProfile> destinations,
List<KafkaBrokerProfile> kafkaBrokers,
List<RabbitBrokerProfile> rabbitBrokers,
List<BrokerSecurityProfile> security) {
public CompiledMessagingConfiguration {
Objects.requireNonNull(destinations, "destinations must not be null");
Objects.requireNonNull(kafkaBrokers, "kafkaBrokers must not be null");
Objects.requireNonNull(rabbitBrokers, "rabbitBrokers must not be null");
Objects.requireNonNull(security, "security must not be null");
destinations = List.copyOf(destinations);
kafkaBrokers = List.copyOf(kafkaBrokers);
rabbitBrokers = List.copyOf(rabbitBrokers);
security = List.copyOf(security);
}
/**
* Returns the result of compiling a deployment that configured nothing.
*
* <p>Empty is a legitimate state, not a failure: an application may still register its profiles
* as beans, which is how this platform worked before anything bound. What is not legitimate is a
* deployment that configured destinations and got this — which is why the compiler builds it only
* when the sections really are absent.
*
* @return the empty compilation
*/
public static CompiledMessagingConfiguration empty() {
return new CompiledMessagingConfiguration(List.of(), List.of(), List.of(), List.of());
}
}
@@ -0,0 +1,177 @@
package dev.caskeleton.messaging.autoconfigure;
import dev.caskeleton.messaging.api.delivery.DeliveryGuarantee;
import dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee;
import dev.caskeleton.messaging.api.delivery.OrderingScope;
import dev.caskeleton.messaging.api.destination.ConfirmationRequirement;
import dev.caskeleton.messaging.api.destination.DestinationKind;
import dev.caskeleton.messaging.policy.CapabilityTier;
import dev.caskeleton.messaging.policy.OrderingImpact;
import dev.caskeleton.messaging.policy.RetryMode;
import dev.caskeleton.messaging.schema.SchemaCompatibility;
import java.time.Duration;
import java.util.List;
import org.springframework.boot.context.properties.bind.DefaultValue;
/**
* One entry of {@code app.messaging.destinations}.
*
* <p>The shape is the one the configuration reference documents, and it is bound rather than
* described: the reference showed destination, broker and security sections for a platform whose
* only binder held four flags, so an operator who configured exactly what the page said changed
* nothing and was told nothing.
*
* <p>Records rather than mutable nested beans. A destination profile is a contract the platform
* validates once at startup and then relies on; a settings object whose fields can be reassigned
* afterwards offers a second, unvalidated way for that contract to change.
*
* <p>Defaults are the conservative ones. Retry is off, ordering is unconstrained and nothing is a
* production profile until it says so, because every one of those defaults, chosen the other way,
* is a guarantee the deployment never asked for and would discover only under load.
*
* @param broker the logical broker this destination binds to, keyed into {@code
* app.messaging.brokers}
* @param kind the interaction pattern
* @param tier the API tier this destination is approved for
* @param physical the broker-specific address
* @param schema the codec and compatibility contract
* @param guarantees the delivery, ordering and side-effect contract
* @param producer the producer contract
* @param consumer the consumer contract
* @param retry the retry contract
* @param dlq the dead letter contract
* @param payload the size contract
* @param keyResolverConfigured whether a key resolver is registered for keyed ordering
* @param production whether this profile is a production profile
* @param topologyAutoCreate whether the application may create topology itself
*/
public record DestinationSettings(
String broker,
DestinationKind kind,
@DefaultValue("M1") CapabilityTier tier,
@DefaultValue Physical physical,
@DefaultValue Schema schema,
@DefaultValue Guarantees guarantees,
@DefaultValue Producer producer,
@DefaultValue Consumer consumer,
@DefaultValue Retry retry,
@DefaultValue Dlq dlq,
@DefaultValue Payload payload,
@DefaultValue("false") boolean keyResolverConfigured,
@DefaultValue("false") boolean production,
@DefaultValue("false") boolean topologyAutoCreate) {
/**
* The broker-specific address, of which exactly one family is filled in.
*
* @param topic the Kafka or Pulsar topic
* @param exchange the AMQP exchange
* @param routingKey the AMQP routing key
* @param queue the AMQP queue
* @param subject the NATS subject
* @param stream the NATS or Pulsar stream
*/
public record Physical(
String topic,
String exchange,
String routingKey,
String queue,
String subject,
String stream) {}
/**
* The codec and compatibility contract.
*
* @param codec the content type payloads are encoded with
* @param compatibility the schema evolution mode enforced here
* @param messageTypes the closed catalog of types this destination carries
*/
public record Schema(
@DefaultValue("application/json") String codec,
@DefaultValue("BACKWARD_TRANSITIVE") SchemaCompatibility compatibility,
@DefaultValue List<String> messageTypes) {}
/**
* What the destination promises about delivery and order.
*
* @param delivery the broker-level delivery guarantee
* @param ordering the scope inside which order holds
* @param externalSideEffect how handler side effects are protected
*/
public record Guarantees(
@DefaultValue("AT_LEAST_ONCE") DeliveryGuarantee delivery,
@DefaultValue("NONE") OrderingScope ordering,
@DefaultValue("IDEMPOTENCY_REQUIRED") ExternalSideEffectGuarantee externalSideEffect) {}
/**
* The producer contract.
*
* @param confirmation the confirmation strength this destination demands
* @param timeout the publish deadline
* @param mandatoryRouting whether the broker must report unroutable publishes
* @param idempotent whether producer-side duplicate suppression is required
*/
public record Producer(
@DefaultValue("REPLICATION_OR_PERSISTENCE_ACK") ConfirmationRequirement confirmation,
@DefaultValue("5s") Duration timeout,
@DefaultValue("true") boolean mandatoryRouting,
@DefaultValue("true") boolean idempotent) {}
/**
* The consumer contract.
*
* @param group the consumer group, where the broker has one
* @param concurrency how many deliveries may be processed at once
* @param maxInFlightPerOrderingUnit the in-flight ceiling inside one ordering unit
* @param prefetch the broker prefetch window
* @param handlerTimeout the handler deadline
* @param manualSettlement whether this destination uses the M2 manual settlement tier
*/
public record Consumer(
String group,
@DefaultValue("1") int concurrency,
@DefaultValue("1") int maxInFlightPerOrderingUnit,
@DefaultValue("16") int prefetch,
@DefaultValue("30s") Duration handlerTimeout,
@DefaultValue("false") boolean manualSettlement) {}
/**
* The retry contract, off by default.
*
* @param mode how the retry is carried out
* @param maxAttempts total attempts including the first delivery
* @param initialDelay the first backoff interval
* @param maxDelay the backoff ceiling
* @param multiplier the exponential backoff factor
* @param jitter whether to randomise the backoff
* @param orderingImpact what this policy is allowed to do to order
* @param destination the destination messages are re-published to, when the mode uses one
*/
public record Retry(
@DefaultValue("NONE") RetryMode mode,
@DefaultValue("1") int maxAttempts,
@DefaultValue("0s") Duration initialDelay,
@DefaultValue("0s") Duration maxDelay,
@DefaultValue("1.0") double multiplier,
@DefaultValue("false") boolean jitter,
@DefaultValue("PRESERVE") OrderingImpact orderingImpact,
String destination) {}
/**
* Where permanently failed messages go.
*
* @param destination the dead letter destination; absent means dead lettering is off
* @param maxRedriveCount how many times a message may be redriven back
*/
public record Dlq(String destination, @DefaultValue("1") int maxRedriveCount) {}
/**
* The size contract.
*
* @param maxBytes the encoded payload ceiling for this destination
* @param claimCheckThresholdBytes the size above which payloads are offloaded
*/
public record Payload(
@DefaultValue("1048576") int maxBytes,
@DefaultValue("1048576") int claimCheckThresholdBytes) {}
}
@@ -6,6 +6,7 @@ import dev.caskeleton.messaging.kafka.KafkaSecurityConfigurer;
import dev.caskeleton.messaging.kafka.KafkaTransactionProfileValidator;
import dev.caskeleton.messaging.security.BrokerTlsPolicy;
import dev.caskeleton.messaging.security.CredentialRuntimeRegistry;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@@ -41,6 +42,28 @@ public class KafkaMessagingAutoConfiguration {
return new KafkaProfileValidator();
}
/**
* Runs the Kafka profile validator over every Kafka broker profile, declared or configured.
*
* @param profiles the broker profiles the application declared as beans
* @param compiled the broker profiles compiled from {@code app.messaging.brokers}
* @param validator the Kafka profile validator
* @return the startup validation
*/
@Bean
public StartupProfileValidation<dev.caskeleton.messaging.kafka.KafkaBrokerProfile>
kafkaProfileStartupValidation(
ObjectProvider<dev.caskeleton.messaging.kafka.KafkaBrokerProfile> profiles,
CompiledMessagingConfiguration compiled,
KafkaProfileValidator validator) {
return new StartupProfileValidation<>(
() ->
java.util.stream.Stream.concat(
compiled.kafkaBrokers().stream(), profiles.orderedStream())
.toList(),
validator::validate);
}
/**
* Returns the Kafka transaction profile validator.
*
@@ -0,0 +1,331 @@
package dev.caskeleton.messaging.autoconfigure;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import dev.caskeleton.messaging.kafka.KafkaBrokerProfile;
import dev.caskeleton.messaging.policy.ConsumerPolicy;
import dev.caskeleton.messaging.policy.DeadLetterPolicy;
import dev.caskeleton.messaging.policy.DestinationProfile;
import dev.caskeleton.messaging.policy.PayloadPolicy;
import dev.caskeleton.messaging.policy.PhysicalDestination;
import dev.caskeleton.messaging.policy.ProducerPolicy;
import dev.caskeleton.messaging.policy.RetryPolicy;
import dev.caskeleton.messaging.policy.SchemaPolicy;
import dev.caskeleton.messaging.rabbit.RabbitBrokerProfile;
import dev.caskeleton.messaging.security.BrokerCredentialProfile;
import dev.caskeleton.messaging.security.BrokerSecurityProfile;
import dev.caskeleton.messaging.security.DestinationAccessPolicy;
import java.util.ArrayList;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.Set;
import java.util.function.Supplier;
/**
* Turns the documented configuration into the objects the platform already validates.
*
* <p>The gap this closes is not a missing feature but a missing binder. {@code
* docs/messaging/configuration-reference.md} described destination, broker and security sections;
* the only thing that bound was four flags, and destination profiles, broker profiles and security
* profiles had to arrive as beans an application wrote in Java. So a deployment that followed the
* documentation configured nothing, and nothing said so — which is the worst of the three possible
* outcomes, the other two being "it works" and "it refuses to start".
*
* <p>Every refusal here names the key. A configuration error that names a type — "no qualifying
* bean of type DestinationProfile" — tells an operator about the platform's internals rather than
* about the line they have to change.
*
* <p>Compiling is separate from validating on purpose. This class turns text into objects and
* checks only what the object model itself cannot express — that a destination's broker exists,
* that a dead letter destination is declared, that a security entry secures a broker somebody
* configured. Whether the resulting profile is coherent is {@code DestinationProfileValidator}'s
* question and it is asked at startup over the whole registry, so a configured profile and a
* bean-declared one are held to exactly the same rules.
*/
public final class MessagingConfigurationCompiler {
private final MessagingSettings settings;
/**
* Creates a compiler over the bound settings.
*
* @param settings the bound configuration
*/
public MessagingConfigurationCompiler(MessagingSettings settings) {
this.settings = Objects.requireNonNull(settings, "settings must not be null");
}
/**
* Compiles the bound configuration.
*
* @return the compiled destinations, broker profiles and security profiles
*/
public CompiledMessagingConfiguration compile() {
Map<String, BrokerSettings> brokers = settings.getBrokers();
List<KafkaBrokerProfile> kafka = new ArrayList<>();
List<RabbitBrokerProfile> rabbit = new ArrayList<>();
brokers.forEach(
(name, broker) -> {
switch (familyOf(name, broker)) {
case BrokerSettings.KAFKA -> kafka.add(toKafkaProfile(name, broker));
case BrokerSettings.RABBITMQ -> rabbit.add(toRabbitProfile(name, broker));
default ->
throw configurationError(
key("brokers", name, "type"),
"'%s' is not a broker family this platform binds; use '%s' or '%s'"
.formatted(broker.type(), BrokerSettings.KAFKA, BrokerSettings.RABBITMQ));
}
});
List<DestinationProfile> destinations = new ArrayList<>();
settings
.getDestinations()
.forEach((name, destination) -> destinations.add(toProfile(name, destination, brokers)));
List<BrokerSecurityProfile> security = new ArrayList<>();
settings
.getSecurity()
.forEach((name, entry) -> security.add(toSecurityProfile(name, entry, brokers)));
return new CompiledMessagingConfiguration(destinations, kafka, rabbit, security);
}
private static String familyOf(String name, BrokerSettings broker) {
if (broker.type() == null || broker.type().isBlank()) {
throw configurationError(
key("brokers", name, "type"),
"a broker entry must declare its family; without one the platform cannot tell which of "
+ "its settings apply, and would apply none of them");
}
return broker.type().toLowerCase(Locale.ROOT);
}
private static KafkaBrokerProfile toKafkaProfile(String name, BrokerSettings broker) {
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");
}
return new KafkaBrokerProfile(
name,
broker.stable(),
broker.production(),
broker.bootstrapServers(),
broker.enableIdempotence(),
broker.acks(),
broker.maxInFlightRequestsPerConnection(),
broker.deliveryTimeout(),
broker.enableAutoCommit(),
broker.consumerGroup(),
broker.tlsEnabled(),
broker.authenticationEnabled());
}
private static RabbitBrokerProfile toRabbitProfile(String name, BrokerSettings broker) {
if (broker.addresses().isEmpty()) {
throw configurationError(
key("brokers", name, "addresses"),
"a RabbitMQ broker needs at least one address; a client with none defaults to "
+ "localhost and connects as guest");
}
return new RabbitBrokerProfile(
name,
broker.stable(),
broker.production(),
broker.addresses(),
broker.publisherConfirms(),
broker.publisherReturns(),
broker.mandatory(),
broker.confirmTimeout(),
broker.autoAck(),
broker.prefetch(),
broker.quorumQueues(),
broker.tlsEnabled(),
broker.authenticationEnabled());
}
private DestinationProfile toProfile(
String name, DestinationSettings settings, Map<String, BrokerSettings> brokers) {
if (settings.broker() == null || settings.broker().isBlank()) {
throw configurationError(
key("destinations", name, "broker"), "a destination must name the broker it binds to");
}
if (!brokers.containsKey(settings.broker())) {
throw configurationError(
key("destinations", name, "broker"),
"'%s' is not a configured broker; declared brokers are %s"
.formatted(settings.broker(), brokers.keySet()));
}
if (settings.kind() == null) {
throw configurationError(
key("destinations", name, "kind"),
"a destination must declare its interaction pattern; the platform's retry, ordering and "
+ "dead letter rules all read it");
}
return new DestinationProfile(
new DestinationName(name),
settings.broker(),
settings.kind(),
physical(name, settings.physical()),
schema(name, settings.schema()),
settings.guarantees().delivery(),
settings.guarantees().ordering(),
settings.guarantees().externalSideEffect(),
new ProducerPolicy(
settings.producer().confirmation(),
settings.producer().timeout(),
settings.producer().mandatoryRouting(),
settings.producer().idempotent()),
new ConsumerPolicy(
Optional.ofNullable(blankToNull(settings.consumer().group())),
settings.consumer().concurrency(),
settings.consumer().maxInFlightPerOrderingUnit(),
settings.consumer().prefetch(),
settings.consumer().handlerTimeout(),
settings.consumer().manualSettlement()),
retry(settings.retry()),
deadLetter(settings.dlq()),
new PayloadPolicy(
settings.payload().maxBytes(), settings.payload().claimCheckThresholdBytes()),
settings.tier(),
settings.production(),
settings.keyResolverConfigured(),
settings.topologyAutoCreate());
}
private static PhysicalDestination physical(String name, DestinationSettings.Physical physical) {
PhysicalDestination address =
new PhysicalDestination(
Optional.ofNullable(blankToNull(physical.topic())),
Optional.ofNullable(blankToNull(physical.exchange())),
Optional.ofNullable(blankToNull(physical.routingKey())),
Optional.ofNullable(blankToNull(physical.queue())),
Optional.ofNullable(blankToNull(physical.subject())),
Optional.ofNullable(blankToNull(physical.stream())));
if (address.isEmpty()) {
throw configurationError(
key("destinations", name, "physical"),
"a destination needs a broker address — a topic, an exchange, a queue, a subject or a "
+ "stream; a logical name that maps to nothing cannot be published to");
}
return address;
}
private static SchemaPolicy schema(String name, DestinationSettings.Schema schema) {
if (schema.messageTypes().isEmpty()) {
throw configurationError(
key("destinations", name, "schema.message-types"),
"a destination carries a closed catalog of message types; one that accepts whatever it "
+ "is handed has no reviewable wire contract");
}
Set<MessageType> types = new LinkedHashSet<>();
schema.messageTypes().forEach(type -> types.add(new MessageType(type)));
return new SchemaPolicy(new ContentType(schema.codec()), schema.compatibility(), types);
}
private static RetryPolicy retry(DestinationSettings.Retry retry) {
return new RetryPolicy(
retry.mode(),
retry.maxAttempts(),
retry.initialDelay(),
retry.maxDelay(),
retry.multiplier(),
retry.jitter(),
retry.orderingImpact(),
Set.of(),
Set.of(),
Optional.ofNullable(blankToNull(retry.destination())).map(DestinationName::new));
}
private static DeadLetterPolicy deadLetter(DestinationSettings.Dlq dlq) {
String destination = blankToNull(dlq.destination());
if (destination == null) {
return DeadLetterPolicy.disabled();
}
return new DeadLetterPolicy(
true, Optional.of(new DestinationName(destination)), dlq.maxRedriveCount());
}
private static BrokerSecurityProfile toSecurityProfile(
String name, BrokerSecuritySettings security, Map<String, BrokerSettings> brokers) {
BrokerSettings broker = brokers.get(name);
if (broker == null) {
throw configurationError(
key("security", name, ""),
"'%s' is not a configured broker; a security profile for a broker nobody declared "
.formatted(name)
+ "secures nothing. Declared brokers are "
+ brokers.keySet());
}
return new BrokerSecurityProfile(
name,
broker.production(),
broker.tlsEnabled(),
security.hostnameVerification(),
credential(name, "producer", security.producer(), () -> true),
credential(name, "consumer", security.consumer(), () -> true),
Optional.ofNullable(security.admin())
.map(admin -> credential(name, "admin", admin, () -> true)),
new DestinationAccessPolicy(
destinationNames(security.access().publishable()),
destinationNames(security.access().consumable()),
destinationNames(security.access().administrable())));
}
private static BrokerCredentialProfile credential(
String broker,
String role,
BrokerSecuritySettings.Credential credential,
Supplier<Boolean> required) {
if (credential == null && Boolean.TRUE.equals(required.get())) {
throw configurationError(
key("security", broker, role),
"a configured broker needs a %s credential; the roles are separate so that a compromised "
.formatted(role)
+ "handler has nothing to escalate with");
}
String type = credential.type() == null ? "" : credential.type().toUpperCase(Locale.ROOT);
String id = credential.credentialId();
return switch (type) {
case "SASL_SCRAM" -> new BrokerCredentialProfile.SaslScram(id);
case "OAUTH2" -> new BrokerCredentialProfile.OAuth2(id);
case "MUTUAL_TLS" -> new BrokerCredentialProfile.MutualTls(id);
case "USERNAME_PASSWORD" -> new BrokerCredentialProfile.UsernamePassword(id);
case "NKEY" -> new BrokerCredentialProfile.Nkey(id);
default ->
throw configurationError(
key("security", broker, role + ".type"),
"'%s' is not an authentication mechanism this platform implements; the closed set is "
.formatted(credential.type())
+ "SASL_SCRAM, OAUTH2, MUTUAL_TLS, USERNAME_PASSWORD, NKEY");
};
}
private static Set<DestinationName> destinationNames(List<String> names) {
Set<DestinationName> destinations = new LinkedHashSet<>();
names.forEach(name -> destinations.add(new DestinationName(name)));
return destinations;
}
private static String blankToNull(String value) {
return value == null || value.isBlank() ? null : value;
}
private static String key(String section, String entry, String leaf) {
String path = MessagingSettings.PREFIX + '.' + section + '.' + entry;
return leaf.isEmpty() ? path : path + '.' + leaf;
}
private static MessagingConfigurationException configurationError(String key, String message) {
return new MessagingConfigurationException(
"MESSAGING_CONFIGURATION_INVALID", key + ": " + message);
}
}
@@ -0,0 +1,227 @@
package dev.caskeleton.messaging.autoconfigure;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import java.lang.reflect.RecordComponent;
import java.util.ArrayList;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Objects;
import java.util.Set;
import org.springframework.beans.factory.InitializingBean;
import org.springframework.core.env.ConfigurableEnvironment;
import org.springframework.core.env.EnumerablePropertySource;
import org.springframework.core.env.PropertySource;
/**
* Refuses a key inside the platform's own configuration sections that nothing binds.
*
* <p>A misspelt prefix is loud — the whole section is missing and someone notices. A misspelt key
* inside a section that does bind is the opposite: the entry appears, the platform starts, and the
* one setting the operator came to change is the only one that did not take. {@code
* consumer.prefech: 64} is a throughput change that never happened, and the first evidence is the
* incident it was supposed to prevent.
*
* <p>The legal keys are derived from the settings records rather than listed here. A list would be
* a second description of the same shape, and the failure mode of a second description is that it
* is right on the day it is written: a field added to {@code DestinationSettings} would be rejected
* as unknown by the very check that exists to catch typos.
*
* <p>Only enumerable property sources are scanned, which in practice means files and explicitly
* supplied properties rather than environment variables. An environment variable arrives as {@code
* APP_MESSAGING_DESTINATIONS_ORDER_EVENTS_CONSUMER_PREFETCH}, and the underscores that separate the
* entry name from the leaf are the same underscores inside both, so there is no way to split it
* back without guessing. Guessing here would mean refusing valid deployments, which is worse than
* missing a typo in the one place typos are least likely — a variable somebody had to spell out in
* a deployment manifest.
*/
public final class MessagingConfigurationKeyValidator implements InitializingBean {
/** Broker keys that only a Kafka entry may carry. */
private static final Set<String> KAFKA_ONLY_KEYS =
Set.of(
"bootstrap-servers",
"enable-idempotence",
"acks",
"max-in-flight-requests-per-connection",
"delivery-timeout",
"enable-auto-commit",
"consumer-group");
/** Broker keys that only a RabbitMQ entry may carry. */
private static final Set<String> RABBIT_ONLY_KEYS =
Set.of(
"addresses",
"publisher-confirms",
"publisher-returns",
"mandatory",
"confirm-timeout",
"auto-ack",
"prefetch",
"quorum-queues");
private final ConfigurableEnvironment environment;
/**
* Creates a validator over the resolved environment.
*
* @param environment the environment whose keys are checked
*/
public MessagingConfigurationKeyValidator(ConfigurableEnvironment environment) {
this.environment = Objects.requireNonNull(environment, "environment must not be null");
}
@Override
public void afterPropertiesSet() {
validate();
}
/**
* Fails when a key under a bound section is not one the settings declare.
*
* @throws MessagingConfigurationException naming the offending key
*/
public void validate() {
Map<String, Class<?>> sections =
Map.of(
"destinations", DestinationSettings.class,
"brokers", BrokerSettings.class,
"security", BrokerSecuritySettings.class);
List<String> rejected = new ArrayList<>();
sections.forEach(
(section, shape) -> {
Set<String> legal = leafPaths(shape);
for (String key : keysUnder(MessagingSettings.PREFIX + '.' + section + '.')) {
Entry entry = split(key, MessagingSettings.PREFIX + '.' + section + '.');
if (entry.leaf().isEmpty()) {
continue;
}
if (!legal.contains(entry.leaf())) {
rejected.add(
"%s binds nothing; %s entries accept %s"
.formatted(key, section, legal.stream().sorted().toList()));
} else if ("brokers".equals(section)) {
wrongFamily(entry).ifPresent(rejected::add);
}
}
});
if (rejected.isEmpty()) {
return;
}
throw new MessagingConfigurationException(
"MESSAGING_CONFIGURATION_KEY_UNKNOWN",
"these messaging keys do not bind: "
+ String.join("; ", rejected.stream().sorted().limit(10).toList())
+ (rejected.size() > 10 ? " (and " + (rejected.size() - 10) + " more)" : ""));
}
/**
* Reports a broker key that belongs to the other broker family.
*
* <p>Both families are described by one record, so a Kafka entry carrying {@code prefetch} binds
* without complaint and does nothing. The author of that line believed it was doing something,
* which is the same silence this class exists to end.
*/
private java.util.Optional<String> wrongFamily(Entry entry) {
String declared =
environment.getProperty(
MessagingSettings.PREFIX + ".brokers." + entry.name() + ".type", "");
String family = declared.toLowerCase(Locale.ROOT);
String leaf = entry.leaf();
if (BrokerSettings.KAFKA.equals(family) && RABBIT_ONLY_KEYS.contains(leaf)) {
return java.util.Optional.of(
"%s.brokers.%s.%s is a RabbitMQ setting on a Kafka broker"
.formatted(MessagingSettings.PREFIX, entry.name(), leaf));
}
if (BrokerSettings.RABBITMQ.equals(family) && KAFKA_ONLY_KEYS.contains(leaf)) {
return java.util.Optional.of(
"%s.brokers.%s.%s is a Kafka setting on a RabbitMQ broker"
.formatted(MessagingSettings.PREFIX, entry.name(), leaf));
}
return java.util.Optional.empty();
}
/** One configuration key split into the map entry it configures and the leaf inside it. */
private record Entry(String name, String leaf) {}
private static Entry split(String key, String sectionPrefix) {
String remainder = key.substring(sectionPrefix.length());
String name;
String leaf;
if (remainder.startsWith("[")) {
// Relaxed binding writes a map key containing a dot as `[order.events]`, so the bracket is
// the only reliable boundary when one is present.
int close = remainder.indexOf(']');
name = close < 0 ? remainder : remainder.substring(1, close);
leaf = close < 0 ? "" : remainder.substring(close + 1);
} else {
int dot = remainder.indexOf('.');
name = dot < 0 ? remainder : remainder.substring(0, dot);
leaf = dot < 0 ? "" : remainder.substring(dot);
}
if (leaf.startsWith(".")) {
leaf = leaf.substring(1);
}
return new Entry(name, canonical(leaf.replaceAll("\\[\\d+\\]", "")));
}
/**
* Returns every leaf path a settings record accepts, in the canonical kebab form.
*
* <p>Nested records are walked because the configuration is nested; a list-valued component is a
* leaf because its indices are stripped before the comparison.
*/
private static Set<String> leafPaths(Class<?> shape) {
Set<String> paths = new LinkedHashSet<>();
collectLeafPaths(shape, "", paths);
return paths;
}
private static void collectLeafPaths(Class<?> shape, String prefix, Set<String> paths) {
for (RecordComponent component : shape.getRecordComponents()) {
String path = prefix + canonical(component.getName());
if (component.getType().isRecord()) {
collectLeafPaths(component.getType(), path + '.', paths);
} else {
paths.add(path);
}
}
}
/** Normalises a property path to the kebab-case form the settings records declare. */
private static String canonical(String path) {
StringBuilder canonical = new StringBuilder(path.length() + 4);
for (int index = 0; index < path.length(); index++) {
char character = path.charAt(index);
if (character == '_') {
canonical.append('-');
} else if (Character.isUpperCase(character)) {
if (index > 0 && path.charAt(index - 1) != '.' && path.charAt(index - 1) != '-') {
canonical.append('-');
}
canonical.append(Character.toLowerCase(character));
} else {
canonical.append(character);
}
}
return canonical.toString();
}
private List<String> keysUnder(String prefix) {
List<String> keys = new ArrayList<>();
for (PropertySource<?> source : environment.getPropertySources()) {
if (!(source instanceof EnumerablePropertySource<?> enumerable)) {
continue;
}
for (String key : enumerable.getPropertyNames()) {
if (key.startsWith(prefix)) {
keys.add(key);
}
}
}
return keys;
}
}
@@ -15,7 +15,6 @@ 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.BackpressureController;
import dev.caskeleton.messaging.transport.DefaultMessagingRuntimeRegistry;
import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator;
import dev.caskeleton.messaging.transport.MessagingRuntimeRegistry;
@@ -54,11 +53,13 @@ public class MessagingCoreAutoConfiguration {
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, credentials, environment);
return new MessagingCredentialRequirementValidator(
profiles, compiled.security(), credentials, environment);
}
/**
@@ -73,20 +74,63 @@ public class MessagingCoreAutoConfiguration {
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.
*
* @param profiles the registered profiles
* <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) {
List<DestinationProfile> registered = profiles.orderedStream().toList();
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);
}
@@ -148,20 +192,6 @@ public class MessagingCoreAutoConfiguration {
return new DefaultMessagingRuntimeRegistry(properties.getShutdown().getDrainDeadline());
}
/**
* Returns the process-wide backpressure controller.
*
* @param properties the bound configuration
* @return the controller
*/
@Bean
@ConditionalOnMissingBean
public BackpressureController backpressureController(MessagingSettings properties) {
return new BackpressureController(
properties.getBackpressure().getGlobalLimit(),
properties.getBackpressure().getPerDestinationLimit());
}
/**
* Returns the graceful shutdown coordinator.
*
@@ -174,6 +204,45 @@ public class MessagingCoreAutoConfiguration {
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.
*
@@ -264,14 +333,15 @@ public class MessagingCoreAutoConfiguration {
* Returns the read-only actuator endpoint.
*
* @param registry the validated destination registry
* @param backpressure the in-flight counters
* @param admission the gate every publish passes through
* @return the endpoint
*/
@Bean
@ConditionalOnMissingBean
public MessagingEndpoint messagingEndpoint(
ValidatedDestinationRegistry registry, BackpressureController backpressure) {
return new MessagingEndpoint(registry, backpressure);
ValidatedDestinationRegistry registry,
dev.caskeleton.messaging.policy.MessagingAdmissionController admission) {
return new MessagingEndpoint(registry, admission);
}
/**
@@ -342,8 +412,8 @@ public class MessagingCoreAutoConfiguration {
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().getPerDestinationLimit(),
java.time.Duration.ofSeconds(5)));
properties.getBackpressure().getGlobalLimit(), java.time.Duration.ofSeconds(5)),
properties.getBackpressure().getPerDestinationLimit());
}
/**
@@ -21,20 +21,38 @@ import org.springframework.core.env.Environment;
* <p>The check is scoped to production profiles. A local profile that connects to a broker with no
* authentication is a legitimate development setup; the same profile marked production is not, and
* the two must not be satisfiable by the same configuration.
*
* <p>It reads both the profiles an application declared as beans and the ones compiled from {@code
* app.messaging.security}. A deployment that configures its production broker in YAML and one that
* writes it in Java must meet the same refusal, or the check becomes advice about how to write the
* configuration rather than a rule about what the configuration may say.
*/
public final class MessagingCredentialRequirementValidator implements InitializingBean {
private final ObjectProvider<BrokerSecurityProfile> profiles;
private final List<BrokerSecurityProfile> configured;
private final ObjectProvider<dev.caskeleton.messaging.security.CredentialProvider> credentials;
private final Environment environment;
/**
* Creates the validator.
*
* @param profiles the security profiles the application declared as beans
* @param configured the security profiles compiled from configuration
* @param credentials the application's credential source, if it supplied one
* @param environment the resolved environment, used to report the active profiles
*/
public MessagingCredentialRequirementValidator(
ObjectProvider<BrokerSecurityProfile> profiles,
List<BrokerSecurityProfile> configured,
ObjectProvider<dev.caskeleton.messaging.security.CredentialProvider> credentials,
Environment environment) {
this.profiles = Objects.requireNonNull(profiles, "profiles must not be null");
this.configured =
List.copyOf(Objects.requireNonNull(configured, "configured must not be null"));
this.credentials = Objects.requireNonNull(credentials, "credentials must not be null");
this.environment = Objects.requireNonNull(environment, "environment must not be null");
}
@@ -54,9 +72,10 @@ public final class MessagingCredentialRequirementValidator implements Initializi
return;
}
List<String> production =
profiles.stream()
java.util.stream.Stream.concat(configured.stream(), profiles.stream())
.filter(BrokerSecurityProfile::production)
.map(BrokerSecurityProfile::broker)
.distinct()
.toList();
if (production.isEmpty()) {
return;
@@ -1,7 +1,7 @@
package dev.caskeleton.messaging.autoconfigure;
import dev.caskeleton.messaging.policy.DestinationProfile;
import dev.caskeleton.messaging.transport.BackpressureController;
import dev.caskeleton.messaging.policy.MessagingAdmissionController;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
@@ -26,18 +26,22 @@ import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
public class MessagingEndpoint {
private final ValidatedDestinationRegistry registry;
private final BackpressureController backpressure;
private final MessagingAdmissionController admission;
/**
* Creates the endpoint.
*
* <p>The counts come from the gate every publish passes through. They used to come from a second
* limiter that no publish ever touched, so the endpoint reported zero in flight under any load —
* a diagnostic that is worse than absent, because it looks like an answer.
*
* @param registry the validated destination registry
* @param backpressure the in-flight counters
* @param admission the gate every publish passes through
*/
public MessagingEndpoint(
ValidatedDestinationRegistry registry, BackpressureController backpressure) {
ValidatedDestinationRegistry registry, MessagingAdmissionController admission) {
this.registry = Objects.requireNonNull(registry, "registry must not be null");
this.backpressure = Objects.requireNonNull(backpressure, "backpressure must not be null");
this.admission = Objects.requireNonNull(admission, "admission must not be null");
}
/**
@@ -48,7 +52,7 @@ public class MessagingEndpoint {
@ReadOperation
public Map<String, Object> messaging() {
Map<String, Object> report = new LinkedHashMap<>();
report.put("globalInFlight", backpressure.globalInFlight());
report.put("globalInFlight", admission.inFlight());
report.put("destinations", destinations());
return Map.copyOf(report);
}
@@ -68,7 +72,7 @@ public class MessagingEndpoint {
entry.put("production", profile.production());
entry.put("deadLetterEnabled", profile.deadLetter().enabled());
entry.put("retryMode", profile.retry().mode().name());
entry.put("inFlight", backpressure.inFlight(profile.name().value()));
entry.put("inFlight", admission.inFlight(profile.name().value()));
return Map.copyOf(entry);
}
}
@@ -0,0 +1,69 @@
package dev.caskeleton.messaging.autoconfigure;
import dev.caskeleton.messaging.outbox.OutboxRelayWorker;
import java.time.Duration;
import java.util.Objects;
import org.springframework.context.SmartLifecycle;
/**
* Starts and stops the outbox relay with the application context.
*
* <p>Without this the relay is a bean an application has to remember to drive itself, and the
* failure when it forgets is silent: rows accumulate in a table that looks healthy while no message
* is ever published.
*
* <p>Stopping drains rather than interrupts. A pass killed between claiming a row and writing its
* outcome leaves that row {@code IN_FLIGHT} under a lease no other relay may touch until it
* expires, so an orderly shutdown would strand exactly what a crash strands.
*
* <p>Every replica runs its own relay. Claims are taken with {@code FOR UPDATE SKIP LOCKED} under
* an owner and a fencing token, so two relays never publish the same row; leader election would buy
* nothing here except a single point of failure for the whole outbox.
*/
public final class MessagingOutboxRelayLifecycle implements SmartLifecycle {
private final OutboxRelayWorker worker;
private final Duration drainDeadline;
/**
* Creates the lifecycle.
*
* @param worker the relay worker to drive
* @param drainDeadline how long a running pass may take to finish on stop
*/
public MessagingOutboxRelayLifecycle(OutboxRelayWorker worker, Duration drainDeadline) {
this.worker = Objects.requireNonNull(worker, "worker must not be null");
this.drainDeadline = Objects.requireNonNull(drainDeadline, "drainDeadline must not be null");
}
@Override
public void start() {
worker.start();
}
@Override
public void stop() {
worker.stop(drainDeadline);
}
@Override
public boolean isRunning() {
return worker.isRunning();
}
/**
* Stops before the admission gate closes.
*
* <p>{@code SmartLifecycle} stops in descending phase order, so the highest phase stops first.
* The relay has to be the one that stops first: closing admission while a pass is mid-publish
* turns that pass's rows ambiguous — a shutdown that manufactures exactly the uncertainty the
* drain exists to avoid.
*
* @return the lifecycle phase
*/
@Override
public int getPhase() {
return Integer.MAX_VALUE;
}
}
@@ -48,11 +48,42 @@ public class MessagingProviderSelection {
"kafka", KafkaMessagingAutoConfiguration.class,
"rabbit", RabbitMessagingAutoConfiguration.class);
/**
* Broker ids that ship without a {@code MessagingTransport}, and why.
*
* <p>Registered is not the same as assemblable. The Rabbit leaf ships its profile validator,
* failure classifier and security configurer, and no transport — the native channel bridge those
* would sit on has only test implementations. Selecting it therefore produced an unsatisfied
* dependency on {@code MessagingTransport} deep inside the core configuration, which tells an
* operator that a bean is missing rather than that the transport they chose is not finished.
*
* <p>Refused here instead, next to the other selection errors, so the message names the state the
* deployment is actually in. An entry leaves this map on the day its transport does exist.
*/
static final Map<String, String> BROKERS_WITHOUT_A_TRANSPORT =
Map.of(
"rabbit",
"the Rabbit adapter ships its validators and security configuration but no "
+ "MessagingTransport: its native channel publisher is not implemented, so a publish "
+ "has nothing to travel on");
/** The registered broker ids, so a message can tell an operator what is available. */
public static List<String> registeredBrokerIds() {
return REGISTERED_BROKERS.keySet().stream().sorted().toList();
}
/**
* The registered broker ids that actually assemble a transport.
*
* @return the ids a deployment can select today
*/
public static List<String> assemblableBrokerIds() {
return REGISTERED_BROKERS.keySet().stream()
.filter(id -> !BROKERS_WITHOUT_A_TRANSPORT.containsKey(id))
.sorted()
.toList();
}
/**
* Resolves the selection, or throws naming the property and the values it accepts.
*
@@ -87,6 +118,17 @@ public class MessagingProviderSelection {
+ clientClass
+ " on the classpath; the deployment selected a transport it did not ship");
}
String unfinished = BROKERS_WITHOUT_A_TRANSPORT.get(broker);
if (unfinished != null) {
throw new IllegalStateException(
MessagingSettings.PREFIX
+ ".broker="
+ broker
+ " cannot be selected: "
+ unfinished
+ ". Transports that can be assembled today: "
+ assemblableBrokerIds());
}
return broker;
}
@@ -1,11 +1,15 @@
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;
import dev.caskeleton.messaging.outbox.OutboxRelay;
import dev.caskeleton.messaging.outbox.OutboxRelayWorker;
import dev.caskeleton.messaging.outbox.OutboxRetryScheduler;
import dev.caskeleton.messaging.reliability.InboxRepository;
import dev.caskeleton.messaging.reliability.OutboxRepository;
@@ -28,6 +32,10 @@ import org.springframework.context.annotation.Configuration;
* <p>The cleanup jobs are beans but no scheduler is registered for them. Scheduling is the
* application's decision: a service running several replicas usually wants one of them to run
* cleanup, and auto-registering a fixed-rate task would have every replica delete the same rows.
*
* <p>The relay is the opposite case and is driven here. Its claims are fenced by owner and token
* under {@code SKIP LOCKED}, so every replica running one is safe, while nobody running one is a
* table that fills up behind a business transaction that reported success.
*/
@Configuration(proxyBeanMethods = false)
public class MessagingReliabilityAutoConfiguration {
@@ -55,6 +63,70 @@ public class MessagingReliabilityAutoConfiguration {
return new OutboxRetryScheduler(properties, Duration.ofMinutes(1));
}
/**
* Returns the relay, when the application supplied the two things only it can supply.
*
* <p>The repository writes inside the application's transaction and the envelope factory carries
* the application's producer identity; the platform can invent neither, and a default for either
* would publish from the wrong place under the wrong name.
*
* @param outbox the application's outbox repository
* @param publisher the platform publisher
* @param envelopes rebuilds envelopes from rows
* @param properties the relay settings
* @param scheduler the retry policy
* @return the relay
*/
@Bean
@ConditionalOnBean({OutboxRepository.class, OutboxEnvelopeFactory.class})
@ConditionalOnMissingBean
public OutboxRelay outboxRelay(
OutboxRepository outbox,
MessagePublisher publisher,
OutboxEnvelopeFactory envelopes,
OutboxProperties properties,
OutboxRetryScheduler scheduler) {
return new OutboxRelay(
outbox,
publisher,
envelopes,
properties.batchSize(),
properties.leaseDuration(),
scheduler);
}
/**
* Returns the worker that runs relay passes.
*
* @param relay the relay to drive
* @param scheduler the policy deciding when the next pass runs
* @return the worker
*/
@Bean
@ConditionalOnBean(OutboxRelay.class)
@ConditionalOnMissingBean
public OutboxRelayWorker outboxRelayWorker(OutboxRelay relay, OutboxRetryScheduler scheduler) {
return new OutboxRelayWorker(relay, scheduler);
}
/**
* Binds the relay worker to the context lifecycle.
*
* <p>The drain budget is the lease duration: a pass holds its claims for at most that long, so
* waiting longer proves nothing that waiting that long has not already proved.
*
* @param worker the relay worker
* @param properties the relay settings supplying the lease duration
* @return the lifecycle
*/
@Bean
@ConditionalOnBean(OutboxRelayWorker.class)
@ConditionalOnMissingBean
public MessagingOutboxRelayLifecycle outboxRelayLifecycle(
OutboxRelayWorker worker, OutboxProperties properties) {
return new MessagingOutboxRelayLifecycle(worker, properties.leaseDuration());
}
/**
* Returns the outbox cleanup job.
*
@@ -1,6 +1,8 @@
package dev.caskeleton.messaging.autoconfigure;
import java.time.Duration;
import java.util.LinkedHashMap;
import java.util.Map;
import org.springframework.boot.context.properties.ConfigurationProperties;
/**
@@ -22,6 +24,17 @@ import org.springframework.boot.context.properties.ConfigurationProperties;
* is still being proven must not become load-bearing because a default turned it on, and the same
* applies to the Spring Cloud Stream bridge, which bypasses the platform's retry and dead letter
* policy by design.
*
* <p>The destination, broker and security maps are what the configuration reference has always
* described and nothing bound. Until they existed, a deployment that configured them exactly as
* documented changed no behaviour and produced no error: the profiles the platform actually used
* had to arrive as beans an application wrote in Java, and the documented keys were inert text.
* {@link MessagingConfigurationCompiler} turns them into those same profiles, so the documented
* shape is now the working shape.
*
* <p>The maps are ordered. Configuration errors name the entry that caused them, and an operator
* reading a startup failure against a file they wrote should meet the entries in the order they
* wrote them rather than in hash order.
*/
@ConfigurationProperties(prefix = MessagingSettings.PREFIX)
public class MessagingSettings {
@@ -39,6 +52,63 @@ public class MessagingSettings {
private final Bridge bridge = new Bridge();
private final Backpressure backpressure = new Backpressure();
private final Shutdown shutdown = new Shutdown();
private Map<String, DestinationSettings> destinations = new LinkedHashMap<>();
private Map<String, BrokerSettings> brokers = new LinkedHashMap<>();
private Map<String, BrokerSecuritySettings> security = new LinkedHashMap<>();
/**
* Returns the declared destinations, keyed by logical name.
*
* @return the destination settings
*/
public Map<String, DestinationSettings> getDestinations() {
return destinations;
}
/**
* Sets the declared destinations.
*
* @param destinations the destination settings, keyed by logical name
*/
public void setDestinations(Map<String, DestinationSettings> destinations) {
this.destinations = new LinkedHashMap<>(destinations);
}
/**
* Returns the declared brokers, keyed by logical name.
*
* @return the broker settings
*/
public Map<String, BrokerSettings> getBrokers() {
return brokers;
}
/**
* Sets the declared brokers.
*
* @param brokers the broker settings, keyed by logical name
*/
public void setBrokers(Map<String, BrokerSettings> brokers) {
this.brokers = new LinkedHashMap<>(brokers);
}
/**
* Returns the declared broker security profiles, keyed by broker name.
*
* @return the security settings
*/
public Map<String, BrokerSecuritySettings> getSecurity() {
return security;
}
/**
* Sets the declared broker security profiles.
*
* @param security the security settings, keyed by broker name
*/
public void setSecurity(Map<String, BrokerSecuritySettings> security) {
this.security = new LinkedHashMap<>(security);
}
/**
* Returns the experimental adapter switches.
@@ -0,0 +1,124 @@
package dev.caskeleton.messaging.autoconfigure;
import dev.caskeleton.messaging.policy.MessagingAdmissionController;
import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator;
import java.time.Duration;
import java.time.Instant;
import java.util.Objects;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.function.Supplier;
import org.springframework.context.SmartLifecycle;
/**
* Runs the platform's shutdown phases in order when the context stops.
*
* <p>The admission controller and the drain coordinator were beans nobody drove. Both could refuse
* new work and wait for in-flight work, and neither was ever asked to: a context shutdown went
* straight to closing beans while publishes were still in flight and handlers were still between
* their side effect and their settlement, which is the shape that turns a deploy into duplicated
* effects and unexplained ambiguous publishes.
*
* <p>The order is admission first, drain second. Reversed, the drain waits for a count that new
* work keeps topping up, so it either never finishes or finishes only because the deadline passed —
* and work abandoned at the deadline is redelivered rather than completed.
*
* <p>The wait is bounded by the same drain deadline the runtime registry uses. A handler that never
* returns must not hold the process open; what is still running when the deadline passes is left
* unsettled on purpose, so the broker redelivers it instead of the platform recording a completion
* it cannot prove.
*/
public final class MessagingShutdownLifecycle implements SmartLifecycle {
/** How often the drain is re-checked. Short enough that a fast drain is not padded. */
private static final Duration POLL = Duration.ofMillis(50);
private final MessagingAdmissionController admission;
private final GracefulShutdownCoordinator drain;
private final Duration drainDeadline;
private final Supplier<Instant> clock;
private final AtomicBoolean running = new AtomicBoolean();
/**
* Creates the lifecycle.
*
* @param admission the publish admission gate
* @param drain the in-flight work coordinator
* @param drainDeadline how long in-flight work may take
*/
public MessagingShutdownLifecycle(
MessagingAdmissionController admission,
GracefulShutdownCoordinator drain,
Duration drainDeadline) {
this(admission, drain, drainDeadline, Instant::now);
}
/**
* Creates the lifecycle with an explicit clock, so the deadline is testable without sleeping.
*
* @param admission the publish admission gate
* @param drain the in-flight work coordinator
* @param drainDeadline how long in-flight work may take
* @param clock the source of the current instant
*/
public MessagingShutdownLifecycle(
MessagingAdmissionController admission,
GracefulShutdownCoordinator drain,
Duration drainDeadline,
Supplier<Instant> clock) {
this.admission = Objects.requireNonNull(admission, "admission must not be null");
this.drain = Objects.requireNonNull(drain, "drain must not be null");
this.drainDeadline = Objects.requireNonNull(drainDeadline, "drainDeadline must not be null");
this.clock = Objects.requireNonNull(clock, "clock must not be null");
}
@Override
public void start() {
running.set(true);
}
@Override
public void stop() {
if (!running.compareAndSet(true, false)) {
return;
}
admission.stopAcceptingNewWork();
Instant startedAt = clock.get();
drain.beginDrain(startedAt);
Instant deadline = startedAt.plus(drainDeadline);
while (!drain.isDrained(clock.get()) && clock.get().isBefore(deadline)) {
try {
Thread.sleep(POLL.toMillis());
} catch (InterruptedException interrupted) {
// The interrupt is the signal to stop waiting, not a reason to lose it: the phases below
// still have to run, and a swallowed interrupt leaves the shutdown thread looking healthy.
Thread.currentThread().interrupt();
return;
}
}
}
@Override
public boolean isRunning() {
return running.get();
}
/**
* Stops after the producers of work and before the beans that own broker connections.
*
* <p>{@code SmartLifecycle} stops in descending phase order. A phase above the default puts this
* drain ahead of the transports it is draining, because closing a connection first would strand
* the settlements the drain exists to flush. It sits below the outbox relay's phase for the
* mirror-image reason: refusing admission while a relay pass is mid-publish turns that pass's
* rows ambiguous, which is the uncertainty the drain exists to avoid.
*
* @return the lifecycle phase
*/
@Override
public int getPhase() {
return Integer.MAX_VALUE - 1024;
}
}
@@ -36,6 +36,30 @@ public class RabbitMessagingAutoConfiguration {
return new RabbitProfileValidator();
}
/**
* Runs the RabbitMQ profile validator over every broker profile, declared or configured.
*
* @param profiles the broker profiles the application declared as beans
* @param compiled the broker profiles compiled from {@code app.messaging.brokers}
* @param validator the RabbitMQ profile validator
* @return the startup validation
*/
@Bean
public StartupProfileValidation<dev.caskeleton.messaging.rabbit.RabbitBrokerProfile>
rabbitProfileStartupValidation(
org.springframework.beans.factory.ObjectProvider<
dev.caskeleton.messaging.rabbit.RabbitBrokerProfile>
profiles,
CompiledMessagingConfiguration compiled,
RabbitProfileValidator validator) {
return new StartupProfileValidation<>(
() ->
java.util.stream.Stream.concat(
compiled.rabbitBrokers().stream(), profiles.orderedStream())
.toList(),
validator::validate);
}
/**
* Returns the publish failure classifier.
*
@@ -0,0 +1,46 @@
package dev.caskeleton.messaging.autoconfigure;
import java.util.List;
import java.util.Objects;
import java.util.function.Consumer;
import java.util.function.Supplier;
import org.springframework.beans.factory.InitializingBean;
/**
* Applies one profile validator to every profile of its kind at startup.
*
* <p>The Kafka, RabbitMQ and security validators were all beans and none of them was injected
* anywhere: the context published a validator per broker and validated nothing. A profile that
* promises a guarantee its broker cannot give — an exactly-once claim on a non-transactional
* producer, a quorum ack on a single replica, a plaintext credential on a production listener —
* then boots cleanly and fails on the first message that depends on it, which is the wrong place to
* find out.
*
* <p>Validation runs as {@code afterPropertiesSet} rather than on an application event, so the
* failure happens while the context is still being built and the profile bean that caused it is
* named in the stack.
*
* <p>The profiles arrive through a supplier rather than an {@code ObjectProvider} because there are
* now two sources of them — beans an application declares and profiles compiled from {@code
* app.messaging} — and a validator that saw only one of the two would leave the other half of a
* deployment's configuration unchecked. Which half went unchecked would depend on how the
* deployment happened to be written, which is the worst possible rule.
*
* @param <T> the profile type this instance validates
*/
final class StartupProfileValidation<T> implements InitializingBean {
private final Supplier<List<T>> profiles;
private final Consumer<T> validator;
StartupProfileValidation(Supplier<List<T>> profiles, Consumer<T> validator) {
this.profiles = Objects.requireNonNull(profiles, "profiles must not be null");
this.validator = Objects.requireNonNull(validator, "validator must not be null");
}
@Override
public void afterPropertiesSet() {
profiles.get().forEach(validator);
}
}
@@ -76,8 +76,7 @@ class BlockingFacadeTest {
Duration.ofMillis(50),
dev.caskeleton.messaging.api.destination.ConfirmationRequirement
.REPLICATION_OR_PERSISTENCE_ACK,
Optional.empty(),
java.util.Map.of());
Optional.empty());
assertThatThrownBy(
() ->
@@ -19,13 +19,13 @@ import dev.caskeleton.messaging.policy.CapabilityTier;
import dev.caskeleton.messaging.policy.ConsumerPolicy;
import dev.caskeleton.messaging.policy.DeadLetterPolicy;
import dev.caskeleton.messaging.policy.DestinationProfile;
import dev.caskeleton.messaging.policy.MessagingAdmissionController;
import dev.caskeleton.messaging.policy.PayloadPolicy;
import dev.caskeleton.messaging.policy.PhysicalDestination;
import dev.caskeleton.messaging.policy.ProducerPolicy;
import dev.caskeleton.messaging.policy.RetryPolicy;
import dev.caskeleton.messaging.policy.SchemaPolicy;
import dev.caskeleton.messaging.schema.SchemaCompatibility;
import dev.caskeleton.messaging.transport.BackpressureController;
import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
@@ -51,7 +51,7 @@ class MessagingAutoConfigurationTest {
.hasSingleBean(ValidatedDestinationRegistry.class)
.hasSingleBean(BlockingMessagePublisher.class)
.hasSingleBean(ReactiveMessagePublisher.class)
.hasSingleBean(BackpressureController.class)
.hasSingleBean(MessagingAdmissionController.class)
.hasSingleBean(GracefulShutdownCoordinator.class));
}
@@ -236,6 +236,25 @@ class MessagingAutoConfigurationTest {
false);
}
@org.junit.jupiter.api.Test
@org.junit.jupiter.api.DisplayName("a broker profile the adapter cannot honour fails startup")
void anUnhonourableBrokerProfileFailsStartup() {
new org.springframework.boot.test.context.runner.ApplicationContextRunner()
.withConfiguration(
org.springframework.boot.autoconfigure.AutoConfigurations.of(
MessagingCoreAutoConfiguration.class, KafkaMessagingAutoConfiguration.class))
.withUserConfiguration(PublisherConfiguration.class, AutoCommittingKafkaProfile.class)
.withPropertyValues("spring.kafka.bootstrap-servers=localhost:9092")
.run(
context ->
org.assertj.core.api.Assertions.assertThat(context)
.getFailure()
.as(
"a validator nothing injects lets a profile boot and fail on the first"
+ " message that depends on the guarantee")
.hasMessageContaining("consumer auto commit is forbidden"));
}
@org.junit.jupiter.api.Test
@org.junit.jupiter.api.DisplayName("a superseded prefix fails startup instead of binding nothing")
void aSupersededPrefixFailsStartup() {
@@ -364,6 +383,7 @@ class MessagingAutoConfigurationTest {
java.util.Optional.empty(),
dev.caskeleton.messaging.security.DestinationAccessPolicy
.denyAll())),
java.util.List.of(),
new StaticProvider<dev.caskeleton.messaging.security.CredentialProvider>(),
new org.springframework.core.env.StandardEnvironment())
.validate())
@@ -394,6 +414,7 @@ class MessagingAutoConfigurationTest {
java.util.Optional.empty(),
dev.caskeleton.messaging.security.DestinationAccessPolicy
.denyAll())),
java.util.List.of(),
new StaticProvider<dev.caskeleton.messaging.security.CredentialProvider>(),
new org.springframework.core.env.StandardEnvironment())
.validate())
@@ -491,3 +512,35 @@ class MessagingAutoConfigurationTest {
}
}
}
/** A Kafka profile that acknowledges on a timer rather than after the handler. */
@Configuration(proxyBeanMethods = false)
class AutoCommittingKafkaProfile {
@Bean
dev.caskeleton.messaging.kafka.KafkaBrokerProfile kafkaBrokerProfile() {
return KafkaProfiles.profile(true);
}
}
/** Builds a Kafka broker profile whose consumer acknowledges on a timer. */
final class KafkaProfiles {
private KafkaProfiles() {}
static dev.caskeleton.messaging.kafka.KafkaBrokerProfile profile(boolean enableAutoCommit) {
return new dev.caskeleton.messaging.kafka.KafkaBrokerProfile(
"kafka-primary",
true,
false,
java.util.List.of("localhost:9092"),
true,
"all",
5,
java.time.Duration.ofSeconds(30),
enableAutoCommit,
"orders",
false,
false);
}
}
@@ -0,0 +1,320 @@
package dev.caskeleton.messaging.autoconfigure;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.messaging.api.delivery.OrderingScope;
import dev.caskeleton.messaging.api.destination.DestinationKind;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.policy.DestinationProfile;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import org.junit.jupiter.api.Test;
import org.springframework.boot.autoconfigure.AutoConfigurations;
import org.springframework.boot.env.YamlPropertySourceLoader;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
import org.springframework.core.env.PropertySource;
import org.springframework.core.io.ByteArrayResource;
/**
* Makes the configuration reference an executable statement rather than a description.
*
* <p>The document described destination, broker and security sections for a platform whose binder
* held four flags. Every one of those keys was inert: a deployment that configured exactly what the
* page said started cleanly, changed nothing, and reported nothing — the outcome that is worse than
* both "it works" and "it refuses to start", because there is no moment at which anybody learns.
*
* <p>So the first test below reads the YAML out of the shipped page and boots a context on it. An
* edit to the document that the binder cannot honour fails here, and so does a change to the binder
* that leaves the document describing a shape that no longer exists.
*
* <p>The rest are the refusals. Each one is a configuration an operator can write and each fails
* startup with the key in the message, because a platform that silently ignores the line somebody
* came to change is the defect this whole suite is about.
*/
class MessagingConfigurationBindingTest {
private final ApplicationContextRunner runner =
new ApplicationContextRunner()
.withConfiguration(AutoConfigurations.of(MessagingCoreAutoConfiguration.class))
.withUserConfiguration(MessagingAutoConfigurationTest.PublisherConfiguration.class);
@Test
void theDocumentedConfigurationBindsToTheProfilesThePlatformUses() {
documented()
.run(
context -> {
assertThat(context).hasNotFailed();
DestinationProfile orders =
context
.getBean(ValidatedDestinationRegistry.class)
.require(new DestinationName("order-events"));
assertThat(orders.broker()).isEqualTo("kafka-primary");
assertThat(orders.kind()).isEqualTo(DestinationKind.EVENT_STREAM);
assertThat(orders.physical().topic()).contains("order.events.v1");
assertThat(orders.orderingScope()).isEqualTo(OrderingScope.KEY);
assertThat(orders.retry().maxAttempts()).isEqualTo(3);
assertThat(orders.deadLetter().destination())
.contains(new DestinationName("order-events-dlq"));
assertThat(orders.schema().messageTypes())
.extracting(dev.caskeleton.messaging.api.MessageType::value)
.containsExactly("order.created");
CompiledMessagingConfiguration compiled =
context.getBean(CompiledMessagingConfiguration.class);
assertThat(compiled.kafkaBrokers())
.singleElement()
.satisfies(
broker -> {
assertThat(broker.broker()).isEqualTo("kafka-primary");
assertThat(broker.bootstrapServers())
.containsExactly("broker-1:9093", "broker-2:9093");
assertThat(broker.enableAutoCommit()).isFalse();
});
assertThat(compiled.rabbitBrokers())
.singleElement()
.satisfies(broker -> assertThat(broker.quorumQueues()).isTrue());
assertThat(compiled.security())
.singleElement()
.satisfies(
security -> {
assertThat(security.broker()).isEqualTo("kafka-primary");
assertThat(security.hostnameVerification()).isTrue();
assertThat(security.admin())
.as("an application runtime holds no admin credential")
.isEmpty();
assertThat(
security.access().mayPublish(new DestinationName("order-events")))
.isTrue();
});
});
}
@Test
void aTypoInsideABoundSectionFailsStartupNamingTheKey() {
runner
.withPropertyValues(minimal())
.withPropertyValues("app.messaging.destinations.order-events.consumer.prefech=64")
.run(
context ->
assertThat(context)
.hasFailed()
.getFailure()
.hasMessageContaining(
"app.messaging.destinations.order-events.consumer.prefech")
.hasMessageContaining("prefetch"));
}
@Test
void aDestinationNamingAnUnconfiguredBrokerFailsNamingTheKey() {
runner
.withPropertyValues(minimal())
.withPropertyValues("app.messaging.destinations.order-events.broker=kafka-secondary")
.run(
context ->
assertThat(context)
.hasFailed()
.getFailure()
.hasMessageContaining("app.messaging.destinations.order-events.broker")
.hasMessageContaining("kafka-secondary"));
}
@Test
void aDanglingDeadLetterDestinationFailsStartup() {
runner
.withPropertyValues(minimal())
.withPropertyValues(
"app.messaging.destinations.order-events.dlq.destination=nobody-declared-this")
.run(
context ->
assertThat(context)
.hasFailed()
.getFailure()
.hasMessageContaining("nobody-declared-this"));
}
@Test
void aRetryAndDeadLetterCycleAcrossTwoDestinationsIsRefusedWithItsPath() {
runner
.withPropertyValues(minimal())
.withPropertyValues(
"app.messaging.destinations.order-events.retry.mode=RETRY_DESTINATION",
"app.messaging.destinations.order-events.retry.max-attempts=3",
"app.messaging.destinations.order-events.retry.ordering-impact=ALLOW_REORDER",
"app.messaging.destinations.order-events.retry.destination=order-retry",
"app.messaging.destinations.order-events.dlq.destination=order-retry",
"app.messaging.destinations.order-retry.broker=kafka-primary",
"app.messaging.destinations.order-retry.kind=WORK_QUEUE",
"app.messaging.destinations.order-retry.physical.topic=order.retry.v1",
"app.messaging.destinations.order-retry.schema.message-types[0]=order.created",
"app.messaging.destinations.order-retry.dlq.destination=order-events")
.run(
context ->
assertThat(context)
.hasFailed()
.getFailure()
.hasMessageContaining("cycle")
.hasMessageContaining("order-events")
.hasMessageContaining("order-retry"));
}
@Test
void aRabbitSettingOnAKafkaBrokerFailsNamingTheKey() {
runner
.withPropertyValues(minimal())
.withPropertyValues("app.messaging.brokers.kafka-primary.prefetch=32")
.run(
context ->
assertThat(context)
.hasFailed()
.getFailure()
.hasMessageContaining("app.messaging.brokers.kafka-primary.prefetch")
.hasMessageContaining("RabbitMQ setting on a Kafka broker"));
}
@Test
void aSecurityEntryForAnUndeclaredBrokerFailsNamingTheKey() {
runner
.withPropertyValues(minimal())
.withPropertyValues(
"app.messaging.security.kafka-secondary.producer.type=SASL_SCRAM",
"app.messaging.security.kafka-secondary.producer.credential-id=p",
"app.messaging.security.kafka-secondary.consumer.type=SASL_SCRAM",
"app.messaging.security.kafka-secondary.consumer.credential-id=c")
.run(
context ->
assertThat(context)
.hasFailed()
.getFailure()
.hasMessageContaining("app.messaging.security.kafka-secondary")
.hasMessageContaining("is not a configured broker"));
}
@Test
void producerAndConsumerSharingOneCredentialFailsStartup() {
runner
.withPropertyValues(minimal())
.withPropertyValues(
"app.messaging.security.kafka-primary.producer.type=SASL_SCRAM",
"app.messaging.security.kafka-primary.producer.credential-id=one-account",
"app.messaging.security.kafka-primary.consumer.type=SASL_SCRAM",
"app.messaging.security.kafka-primary.consumer.credential-id=one-account")
.run(
context ->
assertThat(context)
.hasFailed()
.getFailure()
.as("the validator was a bean nothing injected; bound values now reach it")
.hasMessageContaining("separate credentials"));
}
@Test
void anUnknownAuthenticationMechanismFailsNamingTheKey() {
runner
.withPropertyValues(minimal())
.withPropertyValues(
"app.messaging.security.kafka-primary.producer.type=TRUST_ME",
"app.messaging.security.kafka-primary.producer.credential-id=p",
"app.messaging.security.kafka-primary.consumer.type=SASL_SCRAM",
"app.messaging.security.kafka-primary.consumer.credential-id=c")
.run(
context ->
assertThat(context)
.hasFailed()
.getFailure()
.hasMessageContaining("app.messaging.security.kafka-primary.producer.type")
.hasMessageContaining("TRUST_ME"));
}
@Test
void aProductionKafkaBrokerWithoutTransportSecurityFailsStartup() {
runner
.withConfiguration(AutoConfigurations.of(KafkaMessagingAutoConfiguration.class))
.withPropertyValues(minimal())
.withPropertyValues(
"spring.kafka.bootstrap-servers=localhost:9092",
"app.messaging.brokers.kafka-primary.production=true")
.run(
context ->
assertThat(context)
.hasFailed()
.getFailure()
.as("the Kafka validator existed as a bean and validated nothing")
.hasMessageContaining("production Kafka connection requires TLS"));
}
/**
* The smallest configuration that boots, which every refusal above then breaks in one way.
*
* <p>Written as properties rather than reused from the document because a refusal test has to
* change exactly one thing; sharing the documented fixture would make each failure depend on
* everything else the page happens to say.
*/
private static String[] minimal() {
return new String[] {
"app.messaging.brokers.kafka-primary.type=kafka",
"app.messaging.brokers.kafka-primary.bootstrap-servers[0]=broker-1:9093",
"app.messaging.destinations.order-events.broker=kafka-primary",
"app.messaging.destinations.order-events.kind=EVENT_STREAM",
"app.messaging.destinations.order-events.physical.topic=order.events.v1",
"app.messaging.destinations.order-events.schema.message-types[0]=order.created",
};
}
private ApplicationContextRunner documented() {
List<PropertySource<?>> sources = new ArrayList<>();
YamlPropertySourceLoader loader = new YamlPropertySourceLoader();
List<String> blocks = yamlBlocks(reference());
assertThat(blocks)
.as("the configuration reference has stopped carrying YAML examples")
.isNotEmpty();
for (int index = 0; index < blocks.size(); index++) {
try {
sources.addAll(
loader.load(
"configuration-reference-" + index,
new ByteArrayResource(blocks.get(index).getBytes(StandardCharsets.UTF_8))));
} catch (IOException failure) {
throw new UncheckedIOException(failure);
}
}
return runner.withInitializer(
context -> sources.forEach(context.getEnvironment().getPropertySources()::addLast));
}
private static List<String> yamlBlocks(String document) {
List<String> blocks = new ArrayList<>();
StringBuilder current = null;
for (String line : document.lines().toList()) {
if (line.startsWith("```yaml")) {
current = new StringBuilder();
} else if (line.startsWith("```") && current != null) {
blocks.add(current.toString());
current = null;
} else if (current != null) {
current.append(line).append('\n');
}
}
return blocks;
}
private static String reference() {
Path candidate = Path.of("").toAbsolutePath();
while (candidate != null && !Files.isDirectory(candidate.resolve("docs/messaging"))) {
candidate = candidate.getParent();
}
if (candidate == null) {
throw new IllegalStateException("could not locate docs/messaging from the test cwd");
}
try {
return Files.readString(candidate.resolve("docs/messaging/configuration-reference.md"));
} catch (IOException failure) {
throw new UncheckedIOException(failure);
}
}
}
@@ -13,13 +13,15 @@ import dev.caskeleton.messaging.policy.CapabilityTier;
import dev.caskeleton.messaging.policy.ConsumerPolicy;
import dev.caskeleton.messaging.policy.DeadLetterPolicy;
import dev.caskeleton.messaging.policy.DestinationProfile;
import dev.caskeleton.messaging.policy.InFlightLimiter;
import dev.caskeleton.messaging.policy.MessagingAdmissionController;
import dev.caskeleton.messaging.policy.PayloadLimitGuard;
import dev.caskeleton.messaging.policy.PayloadPolicy;
import dev.caskeleton.messaging.policy.PhysicalDestination;
import dev.caskeleton.messaging.policy.ProducerPolicy;
import dev.caskeleton.messaging.policy.RetryPolicy;
import dev.caskeleton.messaging.policy.SchemaPolicy;
import dev.caskeleton.messaging.schema.SchemaCompatibility;
import dev.caskeleton.messaging.transport.BackpressureController;
import java.util.List;
import java.util.Map;
import java.util.Set;
@@ -51,9 +53,16 @@ class MessagingEndpointTest {
false);
}
private static MessagingEndpoint endpoint(BackpressureController backpressure) {
return new MessagingEndpoint(
new ValidatedDestinationRegistry(List.of(profile())), backpressure);
private static MessagingEndpoint endpoint(MessagingAdmissionController admission) {
return new MessagingEndpoint(new ValidatedDestinationRegistry(List.of(profile())), admission);
}
/** The real gate, so the endpoint reports what a publish actually occupies. */
private static MessagingAdmissionController admission(int global, int perDestination) {
return new MessagingAdmissionController(
new PayloadLimitGuard(PayloadPolicy.defaults()),
new InFlightLimiter(global, java.time.Duration.ZERO),
perDestination);
}
@SuppressWarnings("unchecked")
@@ -63,7 +72,7 @@ class MessagingEndpointTest {
@Test
void theReportNamesEveryRegisteredDestination() {
Map<String, Object> report = endpoint(new BackpressureController(100, 10)).messaging();
Map<String, Object> report = endpoint(admission(100, 10)).messaging();
assertThat(destinations(report))
.singleElement()
@@ -72,8 +81,7 @@ class MessagingEndpointTest {
@Test
void theReportCarriesTheDeclaredGuaranteesAnOperatorNeeds() {
Map<String, Object> entry =
destinations(endpoint(new BackpressureController(100, 10)).messaging()).get(0);
Map<String, Object> entry = destinations(endpoint(admission(100, 10)).messaging()).get(0);
assertThat(entry)
.containsEntry("deliveryGuarantee", "AT_LEAST_ONCE")
@@ -84,11 +92,11 @@ class MessagingEndpointTest {
@Test
void theReportShowsCurrentInFlightWork() {
BackpressureController backpressure = new BackpressureController(100, 10);
backpressure.tryAcquire("orders.v1");
backpressure.tryAcquire("orders.v1");
MessagingAdmissionController admission = admission(100, 10);
admission.admit("orders.v1", 128);
admission.admit("orders.v1", 128);
Map<String, Object> report = endpoint(backpressure).messaging();
Map<String, Object> report = endpoint(admission).messaging();
assertThat(report).containsEntry("globalInFlight", 2);
assertThat(destinations(report).get(0)).containsEntry("inFlight", 2);
@@ -96,8 +104,7 @@ class MessagingEndpointTest {
@Test
void theReportCarriesNoPerMessageIdentity() {
Map<String, Object> entry =
destinations(endpoint(new BackpressureController(100, 10)).messaging()).get(0);
Map<String, Object> entry = destinations(endpoint(admission(100, 10)).messaging()).get(0);
assertThat(entry.keySet())
.as("an actuator response that echoes message content is a re-identification surface")
@@ -59,7 +59,11 @@ class MessagingLiveRoundTripQualificationTest {
private static final String TOPIC = "order-events";
private static final DestinationName DLQ = new DestinationName("order-events-dlq");
@Container static final KafkaContainer KAFKA = new KafkaContainer("apache/kafka:3.8.0");
// The version the support matrix certifies and every other fixture pins. Qualifying runtime
// membership against 3.8.0 proved the membership on a broker two minors below the one the matrix
// calls certified, so the one test that decides whether the starter may reach a deployment's
// classpath was the only one not run against what a deployment gets.
@Container static final KafkaContainer KAFKA = new KafkaContainer("apache/kafka:4.1.0");
static boolean dockerAvailable() {
return DockerClientFactory.instance().isDockerAvailable();
@@ -0,0 +1,203 @@
package dev.caskeleton.messaging.autoconfigure;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.ProducerId;
import dev.caskeleton.messaging.api.destination.MessageDestination;
import dev.caskeleton.messaging.api.publish.MessagePublisher;
import dev.caskeleton.messaging.api.publish.PublishOptions;
import dev.caskeleton.messaging.api.publish.PublishResult;
import dev.caskeleton.messaging.outbox.OutboxEnvelopeFactory;
import dev.caskeleton.messaging.reliability.OutboxLease;
import dev.caskeleton.messaging.reliability.OutboxRecord;
import dev.caskeleton.messaging.reliability.OutboxRepository;
import dev.caskeleton.messaging.reliability.OutboxTransitionResult;
import java.time.Duration;
import java.time.Instant;
import java.util.List;
import java.util.Optional;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.boot.autoconfigure.AutoConfigurations;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
* Whether a started context drives the outbox relay.
*
* <p>The auto-configuration built the relay's settings and its retry scheduler and never built a
* relay, let alone ran one. An application that added the starter got a table that fills up behind
* business transactions reporting success.
*/
class MessagingOutboxRelayLifecycleTest {
private final ApplicationContextRunner runner =
new ApplicationContextRunner()
.withConfiguration(AutoConfigurations.of(MessagingReliabilityAutoConfiguration.class))
.withUserConfiguration(RelayDependencies.class);
@Test
@DisplayName("a started context runs relay passes without the application driving them")
void aStartedContextRunsRelayPasses() {
runner.run(
context -> {
assertThat(context).hasSingleBean(MessagingOutboxRelayLifecycle.class);
CountingOutboxRepository repository = context.getBean(CountingOutboxRepository.class);
assertThat(repository.claimed.await(5, TimeUnit.SECONDS))
.as("a relay nobody calls is an outbox that stages messages and publishes none")
.isTrue();
assertThat(context.getBean(MessagingOutboxRelayLifecycle.class).isRunning()).isTrue();
});
}
@Test
@DisplayName("closing the context stops the relay rather than leaving it publishing")
void closingTheContextStopsTheRelay() {
MessagingOutboxRelayLifecycle[] captured = new MessagingOutboxRelayLifecycle[1];
runner.run(
context -> {
captured[0] = context.getBean(MessagingOutboxRelayLifecycle.class);
assertThat(captured[0].isRunning()).isTrue();
});
assertThat(captured[0].isRunning())
.as("a relay thread outliving its context publishes from a half-disposed application")
.isFalse();
}
/** The two beans only the application can supply, plus the publisher the platform needs. */
@Configuration(proxyBeanMethods = false)
static class RelayDependencies {
@Bean
CountingOutboxRepository outboxRepository() {
return new CountingOutboxRepository();
}
@Bean
OutboxEnvelopeFactory outboxEnvelopeFactory() {
return new OutboxEnvelopeFactory(new ProducerId("order-api"));
}
@Bean
MessagePublisher messagePublisher() {
return new MessagePublisher() {
@Override
public <T> CompletionStage<PublishResult> publish(
MessageDestination<T> destination, MessageEnvelope<T> message, PublishOptions options) {
throw new UnsupportedOperationException("this relay never claims a row to publish");
}
};
}
}
/**
* An outbox that has nothing to publish and counts being asked.
*
* <p>Only the claim is implemented: the point under test is whether anything asks, not what the
* relay does with what it gets. Every other method throws so that a test which starts depending
* on one fails loudly instead of silently exercising a stub.
*/
static final class CountingOutboxRepository implements OutboxRepository {
private final CountDownLatch claimed = new CountDownLatch(1);
@Override
public List<OutboxLease> claimBatch(
String owner, int batchSize, Duration leaseDuration, Instant now, int maxAttempts) {
claimed.countDown();
return List.of();
}
@Override
public void append(OutboxRecord record) {
throw new UnsupportedOperationException("not used by this test");
}
@Override
public List<OutboxRecord> leaseBatch(int batchSize, Duration leaseDuration, Instant now) {
throw new UnsupportedOperationException("not used by this test");
}
@Override
public List<OutboxLease> claimBatch(
String owner, int batchSize, Duration leaseDuration, Instant now) {
throw new UnsupportedOperationException("not used by this test");
}
@Override
public void markPublished(MessageId messageId, Instant now) {
throw new UnsupportedOperationException("not used by this test");
}
@Override
public OutboxTransitionResult markPublished(OutboxLease lease, Instant now) {
throw new UnsupportedOperationException("not used by this test");
}
@Override
public void markAmbiguous(MessageId messageId, String failureCode, Instant now) {
throw new UnsupportedOperationException("not used by this test");
}
@Override
public OutboxTransitionResult markAmbiguous(
OutboxLease lease, String failureCode, Instant now) {
throw new UnsupportedOperationException("not used by this test");
}
@Override
public OutboxTransitionResult markAmbiguous(
OutboxLease lease, String failureCode, Instant now, Instant nextAttemptAt) {
throw new UnsupportedOperationException("not used by this test");
}
@Override
public OutboxTransitionResult markExhausted(OutboxLease lease, String reason, Instant now) {
throw new UnsupportedOperationException("not used by this test");
}
@Override
public void markFailed(MessageId messageId, String failureCode, Instant now) {
throw new UnsupportedOperationException("not used by this test");
}
@Override
public OutboxTransitionResult markFailed(OutboxLease lease, String failureCode, Instant now) {
throw new UnsupportedOperationException("not used by this test");
}
@Override
public void releaseLease(MessageId messageId) {
throw new UnsupportedOperationException("not used by this test");
}
@Override
public OutboxTransitionResult releaseLease(OutboxLease lease) {
throw new UnsupportedOperationException("not used by this test");
}
@Override
public Optional<OutboxRecord> find(MessageId messageId) {
throw new UnsupportedOperationException("not used by this test");
}
@Override
public int purgePublishedBefore(Instant publishedBefore) {
throw new UnsupportedOperationException("not used by this test");
}
@Override
public int purgePublishedBefore(Instant publishedBefore, int limit) {
throw new UnsupportedOperationException("not used by this test");
}
}
}
@@ -0,0 +1,78 @@
package dev.caskeleton.messaging.autoconfigure;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.error.MessageBackpressureException;
import dev.caskeleton.messaging.policy.InFlightLimiter;
import dev.caskeleton.messaging.policy.MessagingAdmissionController;
import dev.caskeleton.messaging.policy.PayloadLimitGuard;
import dev.caskeleton.messaging.policy.PayloadPolicy;
import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator;
import java.time.Duration;
import java.time.Instant;
import java.util.concurrent.atomic.AtomicReference;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
/**
* What a context stop actually does to in-flight messaging work.
*
* <p>The admission gate and the drain coordinator both existed and neither was driven by anything,
* so a shutdown went straight to destroying beans: publishes in flight, handlers between their side
* effect and their settlement, and no phase in between.
*/
class MessagingShutdownLifecycleTest {
private static final Instant NOW = Instant.parse("2026-08-15T12:00:00Z");
private final MessagingAdmissionController admission =
new MessagingAdmissionController(
new PayloadLimitGuard(PayloadPolicy.defaults()),
new InFlightLimiter(4, Duration.ofMillis(10)));
private final GracefulShutdownCoordinator drain =
new GracefulShutdownCoordinator(Duration.ofSeconds(30));
@Test
@DisplayName("stopping refuses new publishes before waiting for the ones in flight")
void stoppingRefusesNewPublishesFirst() {
MessagingShutdownLifecycle lifecycle = lifecycle(Duration.ofSeconds(30), NOW);
lifecycle.start();
lifecycle.stop();
assertThatThrownBy(() -> admission.admit("order-events", 16))
.as("a drain that new work keeps topping up finishes only when the deadline passes")
.isInstanceOf(MessageBackpressureException.class);
assertThat(drain.isAcceptingWork()).isFalse();
assertThat(lifecycle.isRunning()).isFalse();
}
@Test
@DisplayName("a handler that never returns does not hold the process open")
void aLeakedHandlerDoesNotHoldTheProcessOpen() {
// Work that begins and never ends: the drain can only finish by reaching its deadline.
GracefulShutdownCoordinator leaking = new GracefulShutdownCoordinator(Duration.ofMillis(100));
leaking.tryBeginWork();
AtomicReference<Instant> clock = new AtomicReference<>(NOW);
MessagingShutdownLifecycle lifecycle =
new MessagingShutdownLifecycle(
admission,
leaking,
Duration.ofMillis(150),
() -> clock.getAndUpdate(current -> current.plusMillis(100)));
lifecycle.start();
lifecycle.stop();
assertThat(leaking.inFlight())
.as("work still running at the deadline is abandoned unsettled, not counted as done")
.isEqualTo(1);
assertThat(leaking.abandonedWorkAtDeadline(clock.get())).isTrue();
}
private MessagingShutdownLifecycle lifecycle(Duration drainDeadline, Instant fixed) {
return new MessagingShutdownLifecycle(admission, drain, drainDeadline, () -> fixed);
}
}
@@ -132,18 +132,41 @@ class MessagingStarterOffContractTest {
}
@Test
@DisplayName("selecting Rabbit assembles Rabbit and not Kafka")
void selectingRabbitAssemblesOnlyRabbit() {
withAPublisher()
@DisplayName("selecting Rabbit is refused, and the message says the transport is not finished")
void selectingRabbitIsRefused() {
// This test used to run under `withAPublisher()` and assert the context started. The fake
// MessagePublisher tripped @ConditionalOnMissingBean and removed the very bean whose missing
// dependency is the defect — so a configuration that cannot start in any deployment passed as
// "assembles Rabbit and not Kafka". Without the fake, the real behaviour appears.
//
// Rabbit ships validators and a security configurer and no MessagingTransport, because its
// native channel publisher has only test implementations. That is refused at selection now,
// where the message can say so, rather than surfacing as "No qualifying bean of type
// MessagingTransport" from inside the core configuration.
runner
.withPropertyValues("app.messaging.enabled=true", "app.messaging.broker=rabbit")
.run(
context -> {
assertThat(context).hasNotFailed();
assertThat(context).hasSingleBean(RabbitMessagingAutoConfiguration.class);
assertThat(context).doesNotHaveBean(KafkaMessagingAutoConfiguration.class);
assertThat(context).hasFailed();
assertThat(context.getStartupFailure())
.rootCause()
.hasMessageContaining("app.messaging.broker=rabbit")
.hasMessageContaining("no MessagingTransport")
.hasMessageContaining("kafka");
});
}
@Test
@DisplayName("a fake publisher does not make an unassemblable transport look assemblable")
void aFakePublisherDoesNotHideAnUnassemblableTransport() {
// The guard on the test above. Supplying a MessagePublisher removes the dependency that fails,
// so if the refusal ever moves back to bean wiring this case goes green while the deployment
// stays broken. Selection-time refusal is what makes it fail either way.
withAPublisher()
.withPropertyValues("app.messaging.enabled=true", "app.messaging.broker=rabbit")
.run(context -> assertThat(context).hasFailed());
}
@Test
@DisplayName("MSG-INT-003: a selected transport now assembles a publisher")
void aSelectedTransportAssemblesAPublisher() {