feat(messaging): 브로커 중립 메시징 플랫폼 24개 leaf 추가

messaging-superpowers-package 설계서/계획서 기반 구현.
registry를 19 → 43 leaf로 확장하고 src/messaging 아래 24개 leaf를 등록.

- core-api: M1 publish/consume + M2 batch·delayed·pause-resume
- policy/transport-spi: 재시도 결정, DLQ orchestration, admission control, lifecycle
- kafka·rabbit(Stable): contiguous commit, confirm/return 상관, 배치, 보안 설정
- pulsar·nats(Experimental): 기본 비활성, live 인증 없음을 코드로 기록
- outbox/inbox/claim-check: 트랜잭션 결합, lease, 무결성 검증
- admin: plan → approve → execute를 타입으로 강제
- 문서 9종, infra compose 7종, JMH 벤치마크 3종

검증: 아키텍처 게이트 3종 통과, 24개 leaf 전부 check 통과,
messaging 테스트 604개 통과/0 실패.

미완: 계획서가 요구한 실 브로커 IT 40개 중 7개만 작성.
Rabbit 13 / Outbox 6 / Inbox 4 / NATS·Pulsar·Share 5 / testkit 2 /
starter·admin 3, 그리고 TLS·ACL 2개가 남음.
This commit is contained in:
DongHyeonka
2026-08-14 14:55:38 +09:00
parent 432130fd62
commit e23ed9486e
475 changed files with 39748 additions and 0 deletions
@@ -0,0 +1,45 @@
package dev.caskeleton.messaging.admin;
import java.time.Instant;
import java.util.Objects;
/**
* The approval that authorises a destructive messaging operation.
*
* <p>Approvals expire. An open-ended approval becomes a standing permission, which is the same
* thing as no approval at all — the window is what keeps "we approved a redrive last quarter" from
* authorising one today.
*
* @param ticket the change reference
* @param approvedBy the approver's identity
* @param approvedAt when the approval was granted
* @param validUntil when the approval stops authorising anything
*/
public record AdminApproval(
String ticket, String approvedBy, Instant approvedAt, Instant validUntil) {
public AdminApproval {
Objects.requireNonNull(approvedAt, "approvedAt must not be null");
Objects.requireNonNull(validUntil, "validUntil must not be null");
if (ticket == null || ticket.isBlank()) {
throw new IllegalArgumentException("ticket must not be blank");
}
if (approvedBy == null || approvedBy.isBlank()) {
throw new IllegalArgumentException("approvedBy must not be blank");
}
if (validUntil.isBefore(approvedAt)) {
throw new IllegalArgumentException("an approval cannot expire before it was granted");
}
}
/**
* Reports whether the approval still authorises an operation.
*
* @param now the current instant
* @return true while inside the window
*/
public boolean isValidAt(Instant now) {
Objects.requireNonNull(now, "now must not be null");
return !now.isBefore(approvedAt) && now.isBefore(validUntil);
}
}
@@ -0,0 +1,56 @@
package dev.caskeleton.messaging.admin;
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
import java.time.Instant;
import java.util.Objects;
/**
* A redrive plan that a named human has approved.
*
* <p>Carries {@code loopAcknowledged} separately from the approval itself. Approving a redrive of
* 900 parked messages and approving a redrive that will re-fail 400 of them are different
* decisions, and the second one needs the approver to have seen the number — so the plan cannot
* execute on a loop-risking set unless that was acknowledged explicitly.
*
* @param plan the plan that was approved
* @param approval the approval authorising it
* @param loopAcknowledged whether the approver accepted the previously-redriven candidates
*/
public record ApprovedRedrivePlan(
RedrivePlan plan, AdminApproval approval, boolean loopAcknowledged) {
public ApprovedRedrivePlan {
Objects.requireNonNull(plan, "plan must not be null");
Objects.requireNonNull(approval, "approval must not be null");
}
/**
* Refuses execution when the approval, the topology, or the loop risk no longer permits it.
*
* @param now the current instant
* @param currentTopologyVersion the topology version at execution time
* @throws MessageAuthorizationException when the plan may not execute
*/
public void requireExecutable(Instant now, String currentTopologyVersion) {
Objects.requireNonNull(now, "now must not be null");
Objects.requireNonNull(currentTopologyVersion, "currentTopologyVersion must not be null");
if (!approval.isValidAt(now)) {
throw new MessageAuthorizationException(
"APPROVAL_EXPIRED", "approval %s is not valid at %s".formatted(approval.ticket(), now));
}
if (!plan.topologyVersion().equals(currentTopologyVersion)) {
throw new MessageAuthorizationException(
"TOPOLOGY_CHANGED_SINCE_APPROVAL",
"the plan was approved against topology %s but the broker is now at %s"
.formatted(plan.topologyVersion(), currentTopologyVersion));
}
if (plan.risksALoop() && !loopAcknowledged) {
throw new MessageAuthorizationException(
"REDRIVE_LOOP_NOT_ACKNOWLEDGED",
"%d of the %d candidates already failed a previous redrive; re-running them without "
.formatted(plan.alreadyRedrivenCandidates(), plan.candidates())
+ "fixing the cause produces a loop that looks like progress");
}
}
}
@@ -0,0 +1,49 @@
package dev.caskeleton.messaging.admin;
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
import java.time.Instant;
import java.util.Objects;
/**
* A replay plan that a named human has approved.
*
* <p>A distinct type from {@link ReplayPlan} rather than a boolean on it. The execute method takes
* this type, so an unapproved plan cannot reach it — the authorisation is enforced by the compiler
* instead of by a runtime check somebody can forget to write.
*
* @param plan the plan that was approved
* @param approval the approval authorising it
*/
public record ApprovedReplayPlan(ReplayPlan plan, AdminApproval approval) {
public ApprovedReplayPlan {
Objects.requireNonNull(plan, "plan must not be null");
Objects.requireNonNull(approval, "approval must not be null");
}
/**
* Refuses execution when the approval or the plan no longer applies.
*
* @param now the current instant
* @param currentTopologyVersion the topology version at execution time
* @throws MessageAuthorizationException when the approval has expired or the topology moved
*/
public void requireExecutable(Instant now, String currentTopologyVersion) {
Objects.requireNonNull(now, "now must not be null");
Objects.requireNonNull(currentTopologyVersion, "currentTopologyVersion must not be null");
if (!approval.isValidAt(now)) {
throw new MessageAuthorizationException(
"APPROVAL_EXPIRED", "approval %s is not valid at %s".formatted(approval.ticket(), now));
}
if (!plan.topologyVersion().equals(currentTopologyVersion)) {
// Every number in the plan was computed against the old topology, so the approver agreed to
// an impact estimate that no longer describes what would happen.
throw new MessageAuthorizationException(
"TOPOLOGY_CHANGED_SINCE_APPROVAL",
"the plan was approved against topology %s but the broker is now at %s; the estimated "
.formatted(plan.topologyVersion(), currentTopologyVersion)
+ "impact no longer applies and the plan must be rebuilt");
}
}
}
@@ -0,0 +1,46 @@
package dev.caskeleton.messaging.admin;
import java.util.Map;
import java.util.Objects;
/**
* What the broker actually reports for one destination.
*
* <p>The counterpart to {@link TopologyManifest}: the manifest is what was declared, this is what
* exists. Kept as a separate type rather than reusing the manifest so that a comparison cannot
* accidentally compare a manifest with itself and report success.
*
* @param physicalName the broker-side name
* @param partitions the observed partition count
* @param replicationFactor the observed replication factor
* @param configuration the observed configuration entries
* @param exists whether the destination is present at all
*/
public record DestinationTopology(
String physicalName,
int partitions,
int replicationFactor,
Map<String, String> configuration,
boolean exists) {
public DestinationTopology {
Objects.requireNonNull(configuration, "configuration must not be null");
if (physicalName == null || physicalName.isBlank()) {
throw new IllegalArgumentException("physicalName must not be blank");
}
if (exists && partitions < 1) {
throw new IllegalArgumentException("an existing destination has at least one partition");
}
configuration = Map.copyOf(configuration);
}
/**
* Returns the topology for a destination the broker does not have.
*
* @param physicalName the broker-side name that was looked up
* @return the absent topology
*/
public static DestinationTopology absent(String physicalName) {
return new DestinationTopology(physicalName, 0, 0, Map.of(), false);
}
}
@@ -0,0 +1,25 @@
package dev.caskeleton.messaging.admin;
/**
* The operations that cannot be undone.
*
* <p>Enumerated so the guard is exhaustive rather than a list of {@code if} statements that a new
* operation can quietly avoid.
*/
public enum DestructiveOperation {
/** Re-read a destination from an earlier position. */
REPLAY,
/** Move messages from a dead letter destination back to their source. */
REDRIVE,
/** Move a consumer group's committed position. */
OFFSET_RESET,
/** Discard the contents of a destination. */
PURGE,
/** Remove a destination entirely. */
DELETE_DESTINATION
}
@@ -0,0 +1,73 @@
package dev.caskeleton.messaging.admin;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
import java.time.Instant;
import java.util.Objects;
import java.util.Optional;
/**
* The single gate every destructive messaging operation passes through.
*
* <p>Three conditions, all required. The caller must hold the admin credential — an application
* runtime does not, by construction. The approval must be present and inside its validity window.
* And a dry run is always permitted, because the way to make operators plan before they act is to
* make planning free.
*
* <p>Centralised so that adding a new destructive operation means adding an enum constant, not
* remembering to re-implement the checks.
*/
public final class DestructiveOperationGuard {
private final boolean adminCredentialPresent;
/**
* Creates a guard for a runtime.
*
* @param adminCredentialPresent whether this runtime holds the admin credential
*/
public DestructiveOperationGuard(boolean adminCredentialPresent) {
this.adminCredentialPresent = adminCredentialPresent;
}
/**
* Authorises one destructive operation.
*
* @param operation the operation
* @param destination the destination affected
* @param approval the approval, when one was supplied
* @param dryRun whether this is a plan-only run
* @param now the current instant
* @throws MessageAuthorizationException when the operation is not authorised
*/
public void authorize(
DestructiveOperation operation,
DestinationName destination,
Optional<AdminApproval> approval,
boolean dryRun,
Instant now) {
Objects.requireNonNull(operation, "operation must not be null");
Objects.requireNonNull(destination, "destination must not be null");
Objects.requireNonNull(approval, "approval must not be null");
Objects.requireNonNull(now, "now must not be null");
if (dryRun) {
return;
}
if (!adminCredentialPresent) {
throw new MessageAuthorizationException(
"ADMIN_CREDENTIAL_REQUIRED",
operation + " on " + destination.value() + " requires the admin credential");
}
AdminApproval granted =
approval.orElseThrow(
() ->
new MessageAuthorizationException(
"APPROVAL_REQUIRED",
operation + " on " + destination.value() + " requires an approval"));
if (!granted.isValidAt(now)) {
throw new MessageAuthorizationException(
"APPROVAL_EXPIRED", "approval " + granted.ticket() + " is outside its validity window");
}
}
}
@@ -0,0 +1,64 @@
package dev.caskeleton.messaging.admin;
import java.time.Instant;
import java.util.Objects;
/**
* What a redrive would do, produced before anything is moved.
*
* <p>{@code alreadyRedrivenCandidates} is the number that matters most. A message with a non-zero
* redrive count has been sent back to its source before and failed again; redriving it a second
* time without fixing the cause produces a loop that looks like progress in every dashboard.
* Surfacing the count at plan time is what lets an operator notice before starting it.
*
* @param request the request this plan was built from
* @param candidates how many messages are eligible
* @param alreadyRedrivenCandidates how many of those have been redriven before
* @param plannedAt when the plan was produced
* @param topologyVersion the topology the estimate was computed against
*/
public record RedrivePlan(
RedriveRequest request,
int candidates,
int alreadyRedrivenCandidates,
Instant plannedAt,
String topologyVersion) {
public RedrivePlan {
Objects.requireNonNull(request, "request must not be null");
Objects.requireNonNull(plannedAt, "plannedAt must not be null");
if (candidates < 0) {
throw new IllegalArgumentException("candidates must not be negative");
}
if (alreadyRedrivenCandidates < 0 || alreadyRedrivenCandidates > candidates) {
throw new IllegalArgumentException(
"alreadyRedrivenCandidates must be between 0 and the candidate count");
}
if (topologyVersion == null || topologyVersion.isBlank()) {
throw new IllegalArgumentException("topologyVersion must not be blank");
}
}
/**
* Reports whether this redrive would replay messages that already failed a redrive.
*
* @return true when any candidate has been redriven before
*/
public boolean risksALoop() {
return alreadyRedrivenCandidates > 0;
}
/**
* Returns a one-line operator-facing summary of the impact.
*
* @return the sanitized summary
*/
public String describeImpact() {
String loop =
risksALoop()
? ", %d of which already failed a previous redrive".formatted(alreadyRedrivenCandidates)
: "";
return "redrive %d messages from %s to %s%s"
.formatted(candidates, request.source().value(), request.target().value(), loop);
}
}
@@ -0,0 +1,37 @@
package dev.caskeleton.messaging.admin;
import dev.caskeleton.messaging.api.destination.DestinationName;
import java.util.Objects;
import java.util.UUID;
/**
* A request to move messages from a dead letter destination back to their source.
*
* <p>The redrive id is a separate identifier from the message id, and both travel with the message.
* Reusing the message id as the operation id would make "this message was redriven" and "this
* message is a different message" indistinguishable, and an operator could not tell a redrive loop
* from ordinary traffic.
*
* @param redriveId the operation identity
* @param source the dead letter destination to drain
* @param target the destination to publish back to
* @param batchSize how many messages to move per pass
* @param dryRun whether to plan without moving anything
*/
public record RedriveRequest(
UUID redriveId, DestinationName source, DestinationName target, int batchSize, boolean dryRun) {
private static final int MAX_BATCH = 100;
public RedriveRequest {
Objects.requireNonNull(redriveId, "redriveId must not be null");
Objects.requireNonNull(source, "source must not be null");
Objects.requireNonNull(target, "target must not be null");
if (source.equals(target)) {
throw new IllegalArgumentException("a redrive cannot target its own source");
}
if (batchSize < 1 || batchSize > MAX_BATCH) {
throw new IllegalArgumentException("redrive batch size must be between 1 and " + MAX_BATCH);
}
}
}
@@ -0,0 +1,51 @@
package dev.caskeleton.messaging.admin;
import java.time.Duration;
import java.util.Objects;
import java.util.UUID;
/**
* What a redrive actually did.
*
* <p>{@code stillParked} is not simply {@code candidates - moved}. A message stays parked when its
* republish did not confirm, and the redrive deliberately leaves it there rather than settling it —
* the DLQ-confirm-before-settle rule applies to a redrive exactly as it does to the original
* dead-lettering, because a redrive that settles an unconfirmed republish deletes the last copy.
*
* @param redriveId the operation identity
* @param candidates how many messages were eligible
* @param moved how many were republished and settled
* @param stillParked how many stayed on the dead letter destination
* @param elapsed how long the redrive took
* @param dryRun whether nothing was actually moved
*/
public record RedriveResult(
UUID redriveId, int candidates, int moved, int stillParked, Duration elapsed, boolean dryRun) {
public RedriveResult {
Objects.requireNonNull(redriveId, "redriveId must not be null");
Objects.requireNonNull(elapsed, "elapsed must not be null");
if (candidates < 0 || moved < 0 || stillParked < 0) {
throw new IllegalArgumentException("redrive counters must not be negative");
}
if (moved + stillParked > candidates) {
throw new IllegalArgumentException(
"a redrive cannot account for more messages than it had candidates");
}
if (dryRun && moved > 0) {
throw new IllegalArgumentException("a dry run must not move anything");
}
}
/**
* Reports whether every candidate was accounted for.
*
* <p>An unaccounted message is a bug, not a partial success: it was neither republished nor left
* parked, which means the redrive lost track of it.
*
* @return true when moved plus still-parked covers every candidate
*/
public boolean isFullyAccounted() {
return moved + stillParked == candidates;
}
}
@@ -0,0 +1,55 @@
package dev.caskeleton.messaging.admin;
import java.time.Instant;
import java.util.Objects;
/**
* What a replay would do, produced before anything is read.
*
* <p>The plan exists so the estimate can be reviewed. "Replay from yesterday" is a sentence; "this
* will re-deliver 4.2 million messages into the live consumer group" is a decision, and the only
* moment an operator can make it is before the replay starts.
*
* <p>{@code topologyVersion} is captured here and re-checked at execution. A plan approved against
* one topology and executed against another is estimating a different thing entirely — a partition
* count that changed in between invalidates every number in this record.
*
* @param request the request this plan was built from
* @param estimatedMessages how many messages the window covers
* @param plannedAt when the plan was produced
* @param topologyVersion the topology the estimate was computed against
* @param targetsLiveConsumerGroup whether the replay would feed the live group rather than an
* isolated one
*/
public record ReplayPlan(
ReplayRequest request,
long estimatedMessages,
Instant plannedAt,
String topologyVersion,
boolean targetsLiveConsumerGroup) {
public ReplayPlan {
Objects.requireNonNull(request, "request must not be null");
Objects.requireNonNull(plannedAt, "plannedAt must not be null");
if (estimatedMessages < 0) {
throw new IllegalArgumentException("estimatedMessages must not be negative");
}
if (topologyVersion == null || topologyVersion.isBlank()) {
throw new IllegalArgumentException("topologyVersion must not be blank");
}
}
/**
* Returns a one-line operator-facing summary of the impact.
*
* @return the sanitized summary
*/
public String describeImpact() {
return "replay %s from %s: about %d messages into %s"
.formatted(
request.destination().value(),
request.from(),
estimatedMessages,
targetsLiveConsumerGroup ? "the LIVE consumer group" : "an isolated group");
}
}
@@ -0,0 +1,36 @@
package dev.caskeleton.messaging.admin;
import dev.caskeleton.messaging.api.destination.DestinationName;
import java.time.Instant;
import java.util.Objects;
import java.util.Optional;
import java.util.UUID;
/**
* A request to re-read a destination from an earlier position.
*
* @param replayId the operation identity
* @param destination the destination to replay
* @param from the replay start point
* @param to the replay end point, when bounded
* @param isolatedConsumerGroup whether to replay into a throwaway group
* @param dryRun whether to plan without reading anything
*/
public record ReplayRequest(
UUID replayId,
DestinationName destination,
Instant from,
Optional<Instant> to,
boolean isolatedConsumerGroup,
boolean dryRun) {
public ReplayRequest {
Objects.requireNonNull(replayId, "replayId must not be null");
Objects.requireNonNull(destination, "destination must not be null");
Objects.requireNonNull(from, "from must not be null");
Objects.requireNonNull(to, "to must not be null");
if (to.filter(end -> end.isBefore(from)).isPresent()) {
throw new IllegalArgumentException("replay window ends before it starts");
}
}
}
@@ -0,0 +1,49 @@
package dev.caskeleton.messaging.admin;
import java.time.Duration;
import java.util.Objects;
import java.util.UUID;
/**
* What a replay actually did.
*
* <p>Reports the delivered count against the plan's estimate. They routinely differ — retention may
* have expired part of the window, or the stream may have grown while the plan was being approved —
* and the difference is the operator's signal that the replay covered something other than what was
* approved.
*
* @param replayId the operation identity
* @param estimatedMessages what the plan predicted
* @param deliveredMessages what was actually re-delivered
* @param elapsed how long the replay took
* @param completed whether the whole window was covered
* @param dryRun whether nothing was actually read
*/
public record ReplayResult(
UUID replayId,
long estimatedMessages,
long deliveredMessages,
Duration elapsed,
boolean completed,
boolean dryRun) {
public ReplayResult {
Objects.requireNonNull(replayId, "replayId must not be null");
Objects.requireNonNull(elapsed, "elapsed must not be null");
if (estimatedMessages < 0 || deliveredMessages < 0) {
throw new IllegalArgumentException("replay counters must not be negative");
}
if (dryRun && deliveredMessages > 0) {
throw new IllegalArgumentException("a dry run must not deliver anything");
}
}
/**
* Reports whether the replay covered materially less than was approved.
*
* @return true when fewer than 90% of the estimated messages were delivered
*/
public boolean fellShortOfTheEstimate() {
return completed && estimatedMessages > 0 && deliveredMessages * 10 < estimatedMessages * 9;
}
}
@@ -0,0 +1,82 @@
package dev.caskeleton.messaging.admin;
import java.util.Objects;
/**
* One discrepancy between a declared topology and what the broker actually has.
*
* <p>Severity is part of the finding because the two kinds behave differently at startup. A {@link
* Severity#BLOCKING} issue means the destination cannot deliver its declared guarantee —
* replication factor 1 on a destination promising durability is not a warning, it is a promise the
* platform cannot keep — so the context refuses to start. A {@link Severity#ADVISORY} issue is a
* drift worth reporting that does not break a guarantee.
*
* @param destination the logical destination
* @param attribute the topology attribute that differs
* @param declared what the manifest declared
* @param actual what the broker reported
* @param severity how the platform should react
*/
public record TopologyIssue(
String destination, String attribute, String declared, String actual, Severity severity) {
/** How the platform reacts to a topology discrepancy. */
public enum Severity {
/** The destination cannot deliver a declared guarantee; startup must fail. */
BLOCKING,
/** Drift worth reporting that does not break a guarantee. */
ADVISORY
}
public TopologyIssue {
Objects.requireNonNull(severity, "severity must not be null");
requireText(destination, "destination");
requireText(attribute, "attribute");
requireText(declared, "declared");
requireText(actual, "actual");
}
/**
* Creates a blocking issue.
*
* @param destination the logical destination
* @param attribute the differing attribute
* @param declared the declared value
* @param actual the observed value
* @return the issue
*/
public static TopologyIssue blocking(
String destination, String attribute, String declared, String actual) {
return new TopologyIssue(destination, attribute, declared, actual, Severity.BLOCKING);
}
/**
* Creates an advisory issue.
*
* @param destination the logical destination
* @param attribute the differing attribute
* @param declared the declared value
* @param actual the observed value
* @return the issue
*/
public static TopologyIssue advisory(
String destination, String attribute, String declared, String actual) {
return new TopologyIssue(destination, attribute, declared, actual, Severity.ADVISORY);
}
/**
* Returns a one-line operator-facing description.
*
* @return the sanitized description
*/
public String describe() {
return "%s: %s declared %s but the broker has %s"
.formatted(destination, attribute, declared, actual);
}
private static void requireText(String value, String field) {
if (value == null || value.isBlank()) {
throw new IllegalArgumentException(field + " must not be blank");
}
}
}
@@ -0,0 +1,37 @@
package dev.caskeleton.messaging.admin;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
/**
* Whether the application may create broker topology, or only check it.
*
* <p>{@link #VALIDATE_ONLY} in production, always. An application that auto-creates topology will
* auto-create it after a configuration typo too, and the topic it makes is indistinguishable from a
* real one — same broker, same client, same metrics — while carrying the broker's default partition
* count and replication factor instead of the ones the destination needs. The failure surfaces
* weeks later as data loss on a partition that was never replicated.
*/
public enum TopologyManagementMode {
/** Compare the declared topology against the broker and fail on a mismatch. */
VALIDATE_ONLY,
/** Create missing topology. Permitted outside production only. */
CREATE_IF_MISSING;
/**
* Refuses auto-creation on a production runtime.
*
* @param production whether this runtime is production
* @throws MessagingConfigurationException when auto-creation is configured in production
*/
public void requireSafeFor(boolean production) {
if (production && this == CREATE_IF_MISSING) {
throw new MessagingConfigurationException(
"AUTO_CREATE_IN_PRODUCTION",
"topology auto-creation is not permitted in production: a mistyped destination would be "
+ "created with the broker's default partition count and replication factor, and "
+ "would look exactly like a correctly provisioned one");
}
}
}
@@ -0,0 +1,76 @@
package dev.caskeleton.messaging.admin;
import java.util.List;
import java.util.Map;
import java.util.Objects;
/**
* The declared shape of a destination's broker topology.
*
* <p>Production topology is created by infrastructure code and only <em>validated</em> by the
* application. An application that creates topology on startup will happily create it in the wrong
* place after a configuration mistake, and the resulting topic looks exactly like a real one.
*
* @param destination the logical destination
* @param physicalName the broker-side name
* @param partitions the expected partition count, where the broker has partitions
* @param replicationFactor the expected replication factor
* @param requiredConfiguration configuration entries that must match exactly
*/
public record TopologyManifest(
String destination,
String physicalName,
int partitions,
int replicationFactor,
Map<String, String> requiredConfiguration) {
public TopologyManifest {
Objects.requireNonNull(requiredConfiguration, "requiredConfiguration must not be null");
if (destination == null || destination.isBlank()) {
throw new IllegalArgumentException("destination must not be blank");
}
if (physicalName == null || physicalName.isBlank()) {
throw new IllegalArgumentException("physicalName must not be blank");
}
if (partitions < 1) {
throw new IllegalArgumentException("partitions must be at least 1");
}
if (replicationFactor < 1) {
throw new IllegalArgumentException("replicationFactor must be at least 1");
}
requiredConfiguration = Map.copyOf(requiredConfiguration);
}
/**
* Compares this manifest against what the broker actually reports.
*
* @param actualPartitions the observed partition count
* @param actualReplicationFactor the observed replication factor
* @param actualConfiguration the observed configuration
* @return the differences, empty when the topology matches
*/
public List<String> differencesFrom(
int actualPartitions, int actualReplicationFactor, Map<String, String> actualConfiguration) {
Objects.requireNonNull(actualConfiguration, "actualConfiguration must not be null");
List<String> differences = new java.util.ArrayList<>();
if (actualPartitions != partitions) {
differences.add("partitions expected " + partitions + " but found " + actualPartitions);
}
if (actualReplicationFactor != replicationFactor) {
differences.add(
"replicationFactor expected "
+ replicationFactor
+ " but found "
+ actualReplicationFactor);
}
requiredConfiguration.forEach(
(key, expected) -> {
String actual = actualConfiguration.get(key);
if (!expected.equals(actual)) {
differences.add(key + " expected " + expected + " but found " + actual);
}
});
return List.copyOf(differences);
}
}
@@ -0,0 +1,83 @@
package dev.caskeleton.messaging.admin;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import java.util.List;
import java.util.Objects;
/**
* The outcome of comparing every declared topology against the broker.
*
* <p>Reports both severities together rather than failing on the first blocking issue. An operator
* fixing a topology wants the whole list — fixing one attribute, redeploying, and discovering the
* next one is how a ten-minute fix becomes an afternoon.
*
* @param issues every discrepancy found
* @param destinationsChecked how many destinations were compared
*/
public record TopologyValidationReport(List<TopologyIssue> issues, int destinationsChecked) {
public TopologyValidationReport {
Objects.requireNonNull(issues, "issues must not be null");
if (destinationsChecked < 0) {
throw new IllegalArgumentException("destinationsChecked must not be negative");
}
issues = List.copyOf(issues);
}
/**
* Returns a report with nothing to fix.
*
* @param destinationsChecked how many destinations were compared
* @return the clean report
*/
public static TopologyValidationReport clean(int destinationsChecked) {
return new TopologyValidationReport(List.of(), destinationsChecked);
}
/**
* Returns the issues that must fail startup.
*
* @return the blocking issues
*/
public List<TopologyIssue> blocking() {
return issues.stream()
.filter(issue -> issue.severity() == TopologyIssue.Severity.BLOCKING)
.toList();
}
/**
* Returns the issues worth reporting that do not break a guarantee.
*
* @return the advisory issues
*/
public List<TopologyIssue> advisory() {
return issues.stream()
.filter(issue -> issue.severity() == TopologyIssue.Severity.ADVISORY)
.toList();
}
/**
* Reports whether the topology may be used.
*
* @return true when nothing blocking was found
*/
public boolean isAcceptable() {
return blocking().isEmpty();
}
/**
* Fails startup when any blocking issue was found.
*
* @throws MessagingConfigurationException listing every blocking issue
*/
public void requireAcceptable() {
List<TopologyIssue> blocking = blocking();
if (blocking.isEmpty()) {
return;
}
throw new MessagingConfigurationException(
"TOPOLOGY_MISMATCH",
"the broker topology cannot deliver the declared guarantees: "
+ String.join("; ", blocking.stream().map(TopologyIssue::describe).toList()));
}
}
@@ -0,0 +1,116 @@
package dev.caskeleton.messaging.admin;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
import java.time.Instant;
import java.util.Map;
import java.util.Optional;
import java.util.UUID;
import org.junit.jupiter.api.Test;
class DestructiveOperationGuardTest {
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
private static final DestinationName ORDERS = new DestinationName("order-events");
private static final AdminApproval VALID =
new AdminApproval("CHG-1001", "operator", NOW.minusSeconds(60), NOW.plusSeconds(3600));
@Test
void anApplicationRuntimeCannotRedrive() {
DestructiveOperationGuard guard = new DestructiveOperationGuard(false);
assertThatThrownBy(
() ->
guard.authorize(
DestructiveOperation.REDRIVE, ORDERS, Optional.of(VALID), false, NOW))
.isInstanceOf(MessageAuthorizationException.class)
.hasMessageContaining("admin credential");
}
@Test
void anAdminRuntimeStillNeedsAnApproval() {
DestructiveOperationGuard guard = new DestructiveOperationGuard(true);
assertThatThrownBy(
() -> guard.authorize(DestructiveOperation.PURGE, ORDERS, Optional.empty(), false, NOW))
.isInstanceOf(MessageAuthorizationException.class)
.hasMessageContaining("approval");
}
@Test
void anExpiredApprovalDoesNotAuthorise() {
DestructiveOperationGuard guard = new DestructiveOperationGuard(true);
AdminApproval expired =
new AdminApproval("CHG-1000", "operator", NOW.minusSeconds(7200), NOW.minusSeconds(60));
assertThatThrownBy(
() ->
guard.authorize(
DestructiveOperation.OFFSET_RESET, ORDERS, Optional.of(expired), false, NOW))
.isInstanceOf(MessageAuthorizationException.class)
.hasMessageContaining("validity window");
}
@Test
void aDryRunIsAlwaysPermitted() {
DestructiveOperationGuard guard = new DestructiveOperationGuard(false);
assertThatCode(
() ->
guard.authorize(
DestructiveOperation.DELETE_DESTINATION, ORDERS, Optional.empty(), true, NOW))
.doesNotThrowAnyException();
}
@Test
void anApprovedAdminOperationIsAuthorised() {
DestructiveOperationGuard guard = new DestructiveOperationGuard(true);
assertThatCode(
() ->
guard.authorize(
DestructiveOperation.REPLAY, ORDERS, Optional.of(VALID), false, NOW))
.doesNotThrowAnyException();
}
@Test
void aRedriveCannotTargetItsOwnSource() {
assertThatThrownBy(() -> new RedriveRequest(UUID.randomUUID(), ORDERS, ORDERS, 100, false))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void aRedriveBatchIsBoundedSoOneOperationCannotFloodTheSource() {
assertThatThrownBy(
() ->
new RedriveRequest(
UUID.randomUUID(), new DestinationName("order-events-dlq"), ORDERS, 101, false))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void aTopologyManifestReportsEveryDifference() {
TopologyManifest manifest =
new TopologyManifest(
"order-events", "order.events.v1", 6, 3, Map.of("min.insync.replicas", "2"));
assertThat(manifest.differencesFrom(3, 3, Map.of("min.insync.replicas", "1")))
.hasSize(2)
.anySatisfy(difference -> assertThat(difference).contains("partitions"))
.anySatisfy(difference -> assertThat(difference).contains("min.insync.replicas"));
}
@Test
void aMatchingTopologyReportsNoDifferences() {
TopologyManifest manifest =
new TopologyManifest(
"order-events", "order.events.v1", 6, 3, Map.of("min.insync.replicas", "2"));
assertThat(manifest.differencesFrom(6, 3, Map.of("min.insync.replicas", "2"))).isEmpty();
}
}