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,10 @@
apply plugin: 'java-library'
dependencies {
api project(':messaging:messaging-core-api')
api project(':messaging:messaging-policy')
api project(':messaging:messaging-admin-api')
api project(':messaging:messaging-transport-spi')
api project(':messaging:messaging-security')
api project(':messaging:messaging-observability')
}
@@ -0,0 +1,88 @@
# This is a Gradle generated file for dependency locking.
# Manual edits can break the build and are not advised.
# This file is expected to be part of source control.
com.github.ben-manes.caffeine:caffeine:3.2.3=annotationProcessor,testAnnotationProcessor
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
com.github.spotbugs:spotbugs:4.10.2=spotbugs
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs
com.google.code.gson:gson:2.13.2=spotbugs
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
com.google.guava:guava:33.6.0-jre=checkstyle
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
commons-beanutils:commons-beanutils:1.11.0=checkstyle
commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.21.0=spotbugs
info.picocli:picocli:4.7.7=checkstyle
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
io.micrometer:micrometer-commons:1.16.0=runtimeClasspath,testRuntimeClasspath
io.micrometer:micrometer-core:1.16.0=runtimeClasspath,testRuntimeClasspath
io.micrometer:micrometer-observation:1.16.0=runtimeClasspath,testRuntimeClasspath
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
jaxen:jaxen:2.0.0=spotbugs
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
org.antlr:antlr4-runtime:4.13.2=checkstyle
org.apache.bcel:bcel:6.12.0=spotbugs
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
org.apache.commons:commons-text:1.15.0=spotbugs
org.apache.commons:commons-text:1.3=checkstyle
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
org.apache.logging.log4j:log4j-api:2.25.2=spotbugs
org.apache.logging.log4j:log4j-core:2.25.2=spotbugs
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
org.apache.xbean:xbean-reflect:3.7=checkstyle
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
org.assertj:assertj-core:3.27.6=testCompileClasspath,testRuntimeClasspath
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
org.dom4j:dom4j:2.2.0=spotbugs
org.hdrhistogram:HdrHistogram:2.2.2=runtimeClasspath,testRuntimeClasspath
org.javassist:javassist:3.28.0-GA=checkstyle
org.jspecify:jspecify:1.0.0=annotationProcessor,checkstyle,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-api:6.0.1=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:6.0.1=testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.1=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.1=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.1=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:6.0.1=testRuntimeClasspath
org.junit.platform:junit-platform-launcher:6.0.1=testRuntimeClasspath
org.junit:junit-bom:6.0.1=testCompileClasspath,testRuntimeClasspath
org.junit:junit-bom:6.1.0=spotbugs
org.latencyutils:LatencyUtils:2.0.3=runtimeClasspath,testRuntimeClasspath
org.mockito:mockito-core:5.20.0=mockitoAgent
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
org.ow2.asm:asm-analysis:9.10.1=spotbugs
org.ow2.asm:asm-commons:9.10.1=spotbugs
org.ow2.asm:asm-tree:9.10.1=spotbugs
org.ow2.asm:asm-util:9.10.1=spotbugs
org.ow2.asm:asm:9.10.1=spotbugs
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
org.reflections:reflections:0.10.2=checkstyle
org.slf4j:slf4j-api:2.0.17=spotbugs,spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.17=checkstyle,spotbugsSlf4j
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
empty=compileClasspath
@@ -0,0 +1,78 @@
package dev.caskeleton.messaging.admin.runtime;
import java.time.Instant;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.concurrent.ConcurrentHashMap;
/**
* Remembers which approvals have already been executed.
*
* <p>An approval authorises one execution, not a standing permission. Without this, re-running the
* same approved redrive twice is a single command-history arrow-up away — and the second run
* republishes messages the first one already moved, which on a destination without an inbox is
* indistinguishable from a duplicate storm.
*
* <p>Claiming is atomic and returns the previous claim rather than a boolean, so a duplicate
* attempt can tell the operator <em>when</em> it ran and by which operation id instead of just
* refusing.
*/
public final class AdminOperationIdempotencyStore {
private final Map<String, Claim> claims = new ConcurrentHashMap<>();
/**
* One recorded execution of an approval.
*
* @param approvalTicket the approval that was executed
* @param operationId the operation identity that claimed it
* @param executedAt when it ran
*/
public record Claim(String approvalTicket, String operationId, Instant executedAt) {
public Claim {
Objects.requireNonNull(executedAt, "executedAt must not be null");
if (approvalTicket == null || approvalTicket.isBlank()) {
throw new IllegalArgumentException("approvalTicket must not be blank");
}
if (operationId == null || operationId.isBlank()) {
throw new IllegalArgumentException("operationId must not be blank");
}
}
}
/**
* Claims an approval for execution.
*
* @param approvalTicket the approval to claim
* @param operationId the operation attempting it
* @param now the current instant
* @return empty when the claim succeeded; the existing claim when it was already executed
*/
public Optional<Claim> claim(String approvalTicket, String operationId, Instant now) {
Objects.requireNonNull(now, "now must not be null");
Claim candidate = new Claim(approvalTicket, operationId, now);
Claim existing = claims.putIfAbsent(approvalTicket, candidate);
return Optional.ofNullable(existing);
}
/**
* Returns the recorded execution of an approval.
*
* @param approvalTicket the approval
* @return the claim, when the approval has been executed
*/
public Optional<Claim> find(String approvalTicket) {
return Optional.ofNullable(claims.get(approvalTicket));
}
/**
* Returns how many approvals have been executed.
*
* @return the claim count
*/
public int size() {
return claims.size();
}
}
@@ -0,0 +1,33 @@
package dev.caskeleton.messaging.admin.runtime;
import dev.caskeleton.messaging.admin.DestinationTopology;
import java.util.Optional;
/**
* Reads the broker's current topology.
*
* <p>Read-only by construction. The inspector is what the application's own credential uses, and
* that credential holds no destructive grant, so the type exposes no way to create, alter, or
* delete — an application cannot reach a destructive operation even by mistake because there is no
* method to reach.
*/
public interface BrokerTopologyInspector {
/**
* Describes one destination.
*
* @param physicalName the broker-side name
* @return the observed topology, absent when the broker has no such destination
*/
Optional<DestinationTopology> describe(String physicalName);
/**
* Returns an opaque version for the broker's current topology.
*
* <p>Used to invalidate an approved plan whose impact estimate was computed against an earlier
* shape. Any value that changes when the topology changes is sufficient; it is never parsed.
*
* @return the topology version
*/
String topologyVersion();
}
@@ -0,0 +1,52 @@
package dev.caskeleton.messaging.admin.runtime;
import dev.caskeleton.messaging.admin.DestinationTopology;
import dev.caskeleton.messaging.admin.TopologyIssue;
import dev.caskeleton.messaging.admin.TopologyManifest;
import dev.caskeleton.messaging.admin.TopologyValidationReport;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
/**
* Validates every declared topology in one pass and reports the whole result.
*
* <p>Collects all issues rather than stopping at the first blocking one. An operator fixing a
* topology mismatch wants the complete list — discovering the next problem only after a redeploy
* turns one fix into a sequence of them, and each redeploy is another restart of a production
* service.
*/
public final class CompositeTopologyValidator {
private final BrokerTopologyInspector inspector;
private final TopologyValidator validator = new TopologyValidator();
/**
* Creates a validator over a broker inspector.
*
* @param inspector reads the broker's current topology
*/
public CompositeTopologyValidator(BrokerTopologyInspector inspector) {
this.inspector = Objects.requireNonNull(inspector, "inspector must not be null");
}
/**
* Compares every manifest against the broker.
*
* @param manifests the declared topologies
* @return the complete report
*/
public TopologyValidationReport validate(List<TopologyManifest> manifests) {
Objects.requireNonNull(manifests, "manifests must not be null");
List<TopologyIssue> issues = new ArrayList<>();
for (TopologyManifest manifest : manifests) {
DestinationTopology observed =
inspector
.describe(manifest.physicalName())
.orElseGet(() -> DestinationTopology.absent(manifest.physicalName()));
issues.addAll(validator.compare(manifest, observed));
}
return new TopologyValidationReport(issues, manifests.size());
}
}
@@ -0,0 +1,199 @@
package dev.caskeleton.messaging.admin.runtime;
import dev.caskeleton.messaging.admin.ApprovedRedrivePlan;
import dev.caskeleton.messaging.admin.ApprovedReplayPlan;
import dev.caskeleton.messaging.admin.RedrivePlan;
import dev.caskeleton.messaging.admin.RedriveRequest;
import dev.caskeleton.messaging.admin.RedriveResult;
import dev.caskeleton.messaging.admin.ReplayPlan;
import dev.caskeleton.messaging.admin.ReplayRequest;
import dev.caskeleton.messaging.admin.ReplayResult;
import dev.caskeleton.messaging.admin.TopologyManifest;
import dev.caskeleton.messaging.admin.TopologyValidationReport;
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
import java.time.Duration;
import java.time.Instant;
import java.util.List;
import java.util.Objects;
import java.util.Optional;
import java.util.function.Supplier;
/**
* Wires plan, approval, and execution together for the non-destructive admin operations.
*
* <p>Execution runs four checks, in this order, and the order is the point.
*
* <ol>
* <li>The approval is still inside its window.
* <li>The topology has not changed since the plan was approved.
* <li>The approval has not already been executed.
* <li>Only then does anything move.
* </ol>
*
* <p>The idempotency claim comes <em>before</em> the work rather than after it. Claiming afterwards
* leaves a window where a second execution starts while the first is still running, which is
* precisely the double-redrive this store exists to prevent.
*/
public final class DefaultMessagingAdminService implements MessagingAdminService {
private final CompositeTopologyValidator topologyValidator;
private final BrokerTopologyInspector inspector;
private final AdminOperationIdempotencyStore idempotency;
private final ReplayService replayService;
private final RedriveService redriveService;
private final Supplier<List<TopologyManifest>> manifests;
private final ReplayEstimator replayEstimator;
private final RedriveEstimator redriveEstimator;
private final Supplier<Instant> clock;
/**
* Creates the admin service.
*
* @param topologyValidator compares declared topology against the broker
* @param inspector reads the broker's topology version
* @param idempotency records which approvals have been executed
* @param replayService performs replays
* @param redriveService performs redrives
* @param manifests supplies the declared topologies
* @param replayEstimator estimates a replay's message count
* @param redriveEstimator estimates a redrive's candidates
* @param clock supplies the current instant
*/
public DefaultMessagingAdminService(
CompositeTopologyValidator topologyValidator,
BrokerTopologyInspector inspector,
AdminOperationIdempotencyStore idempotency,
ReplayService replayService,
RedriveService redriveService,
Supplier<List<TopologyManifest>> manifests,
ReplayEstimator replayEstimator,
RedriveEstimator redriveEstimator,
Supplier<Instant> clock) {
this.topologyValidator =
Objects.requireNonNull(topologyValidator, "topologyValidator required");
this.inspector = Objects.requireNonNull(inspector, "inspector must not be null");
this.idempotency = Objects.requireNonNull(idempotency, "idempotency must not be null");
this.replayService = Objects.requireNonNull(replayService, "replayService must not be null");
this.redriveService = Objects.requireNonNull(redriveService, "redriveService must not be null");
this.manifests = Objects.requireNonNull(manifests, "manifests must not be null");
this.replayEstimator = Objects.requireNonNull(replayEstimator, "replayEstimator required");
this.redriveEstimator = Objects.requireNonNull(redriveEstimator, "redriveEstimator required");
this.clock = Objects.requireNonNull(clock, "clock must not be null");
}
@Override
public TopologyValidationReport validateTopology() {
return topologyValidator.validate(manifests.get());
}
@Override
public ReplayPlan planReplay(ReplayRequest request) {
Objects.requireNonNull(request, "request must not be null");
return new ReplayPlan(
request,
replayEstimator.estimate(request),
clock.get(),
inspector.topologyVersion(),
!request.isolatedConsumerGroup());
}
@Override
public ReplayResult executeReplay(ApprovedReplayPlan plan) {
Objects.requireNonNull(plan, "plan must not be null");
Instant now = clock.get();
ReplayRequest request = plan.plan().request();
plan.requireExecutable(now, inspector.topologyVersion());
claimOrRefuse(plan.approval().ticket(), request.replayId().toString(), now);
Instant startedAt = clock.get();
ReplayReport report =
replayService.replay(
request, Optional.of(plan.approval()), plan.approval().approvedBy(), now);
return new ReplayResult(
request.replayId(),
plan.plan().estimatedMessages(),
report.replayed(),
Duration.between(startedAt, clock.get()),
true,
report.dryRun());
}
@Override
public RedrivePlan planRedrive(RedriveRequest request) {
Objects.requireNonNull(request, "request must not be null");
RedriveEstimate estimate = redriveEstimator.estimate(request);
return new RedrivePlan(
request,
estimate.candidates(),
estimate.alreadyRedriven(),
clock.get(),
inspector.topologyVersion());
}
@Override
public RedriveResult executeRedrive(ApprovedRedrivePlan plan) {
Objects.requireNonNull(plan, "plan must not be null");
Instant now = clock.get();
RedriveRequest request = plan.plan().request();
plan.requireExecutable(now, inspector.topologyVersion());
claimOrRefuse(plan.approval().ticket(), request.redriveId().toString(), now);
Instant startedAt = clock.get();
RedriveReport report =
redriveService.redrive(
request, Optional.of(plan.approval()), plan.approval().approvedBy(), now);
return new RedriveResult(
request.redriveId(),
report.candidates(),
report.moved(),
report.failed(),
Duration.between(startedAt, clock.get()),
report.dryRun());
}
private void claimOrRefuse(String approvalTicket, String operationId, Instant now) {
idempotency
.claim(approvalTicket, operationId, now)
.ifPresent(
existing -> {
throw new MessageAuthorizationException(
"APPROVAL_ALREADY_EXECUTED",
"approval %s was already executed at %s by operation %s; an approval authorises "
.formatted(approvalTicket, existing.executedAt(), existing.operationId())
+ "one execution, not a standing permission");
});
}
/** Estimates how many messages a replay would re-deliver. */
@FunctionalInterface
public interface ReplayEstimator {
/**
* Estimates a replay's message count without reading anything.
*
* @param request the replay request
* @return the estimated count
*/
long estimate(ReplayRequest request);
}
/** How many messages a redrive would move, and how many already failed one. */
record RedriveEstimate(int candidates, int alreadyRedriven) {}
/** Estimates a redrive's candidates. */
@FunctionalInterface
public interface RedriveEstimator {
/**
* Estimates a redrive's candidates without moving anything.
*
* @param request the redrive request
* @return the estimate
*/
RedriveEstimate estimate(RedriveRequest request);
}
}
@@ -0,0 +1,82 @@
package dev.caskeleton.messaging.admin.runtime;
import dev.caskeleton.messaging.admin.AdminApproval;
import dev.caskeleton.messaging.admin.DestructiveOperation;
import dev.caskeleton.messaging.api.destination.DestinationName;
import java.time.Duration;
import java.time.Instant;
import java.util.Objects;
/**
* The operations that destroy data an application cannot recreate.
*
* <p>A separate interface from {@link MessagingAdminService}, and no bean for it is ever registered
* in an application runtime. The separation is the control: an application that never receives this
* type cannot purge a topic even if every other guard is bypassed, because the method does not
* exist on anything it holds.
*
* <p>Each operation takes an {@link Approved} argument rather than an approval parameter, so the
* authorisation cannot be forgotten at a call site — there is no way to call these without one.
*/
public interface DestructiveMessagingAdmin {
/** An authorised destructive request. */
record Approved(
DestructiveOperation operation,
DestinationName destination,
AdminApproval approval,
long estimatedMessagesAffected) {
public Approved {
Objects.requireNonNull(operation, "operation must not be null");
Objects.requireNonNull(destination, "destination must not be null");
Objects.requireNonNull(approval, "approval must not be null");
if (estimatedMessagesAffected < 0) {
throw new IllegalArgumentException("estimatedMessagesAffected must not be negative");
}
}
}
/** What a destructive operation did. */
record DestructiveResult(
DestructiveOperation operation,
DestinationName destination,
long messagesAffected,
Duration elapsed,
Instant executedAt) {
public DestructiveResult {
Objects.requireNonNull(operation, "operation must not be null");
Objects.requireNonNull(destination, "destination must not be null");
Objects.requireNonNull(elapsed, "elapsed must not be null");
Objects.requireNonNull(executedAt, "executedAt must not be null");
if (messagesAffected < 0) {
throw new IllegalArgumentException("messagesAffected must not be negative");
}
}
}
/**
* Moves a consumer group's committed position.
*
* @param request the authorised request
* @return what the reset did
*/
DestructiveResult resetOffset(Approved request);
/**
* Discards the messages a destination currently holds.
*
* @param request the authorised request
* @return what the purge did
*/
DestructiveResult purge(Approved request);
/**
* Removes a destination entirely.
*
* @param request the authorised request
* @return what the deletion did
*/
DestructiveResult deleteDestination(Approved request);
}
@@ -0,0 +1,65 @@
package dev.caskeleton.messaging.admin.runtime;
import dev.caskeleton.messaging.admin.ApprovedRedrivePlan;
import dev.caskeleton.messaging.admin.ApprovedReplayPlan;
import dev.caskeleton.messaging.admin.RedrivePlan;
import dev.caskeleton.messaging.admin.RedriveRequest;
import dev.caskeleton.messaging.admin.RedriveResult;
import dev.caskeleton.messaging.admin.ReplayPlan;
import dev.caskeleton.messaging.admin.ReplayRequest;
import dev.caskeleton.messaging.admin.ReplayResult;
import dev.caskeleton.messaging.admin.TopologyValidationReport;
/**
* The non-destructive half of the admin plane.
*
* <p>Every mutating operation is split into plan and execute, and the execute methods take an
* {@code Approved*} type. A caller cannot execute something it has not planned, because it has no
* way to construct the argument — the plan/approve/execute sequence is enforced by the types rather
* than by a runtime check.
*
* <p>Destructive operations live in {@link DestructiveMessagingAdmin}, a separate interface that an
* application runtime never receives a bean for. Splitting them means a compromised handler that
* somehow reaches this service still has no method that deletes anything.
*/
public interface MessagingAdminService {
/**
* Compares every declared topology against the broker.
*
* @return the discrepancies found
*/
TopologyValidationReport validateTopology();
/**
* Estimates what a replay would do, without reading anything.
*
* @param request the replay request
* @return the plan, including its impact estimate
*/
ReplayPlan planReplay(ReplayRequest request);
/**
* Executes an approved replay.
*
* @param plan the approved plan
* @return what the replay actually did
*/
ReplayResult executeReplay(ApprovedReplayPlan plan);
/**
* Estimates what a redrive would do, without moving anything.
*
* @param request the redrive request
* @return the plan, including how many candidates already failed a redrive
*/
RedrivePlan planRedrive(RedriveRequest request);
/**
* Executes an approved redrive.
*
* @param plan the approved plan
* @return what the redrive actually did
*/
RedriveResult executeRedrive(ApprovedRedrivePlan plan);
}
@@ -0,0 +1,18 @@
package dev.caskeleton.messaging.admin.runtime;
/**
* What one redrive pass did.
*
* @param candidates how many messages were eligible
* @param moved how many were republished and settled
* @param failed how many did not confirm and stay parked
* @param dryRun whether this was a plan-only run
*/
public record RedriveReport(int candidates, int moved, int failed, boolean dryRun) {
public RedriveReport {
if (candidates < 0 || moved < 0 || failed < 0) {
throw new IllegalArgumentException("redrive counters must not be negative");
}
}
}
@@ -0,0 +1,152 @@
package dev.caskeleton.messaging.admin.runtime;
import dev.caskeleton.messaging.admin.AdminApproval;
import dev.caskeleton.messaging.admin.DestructiveOperation;
import dev.caskeleton.messaging.admin.DestructiveOperationGuard;
import dev.caskeleton.messaging.admin.RedriveRequest;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.publish.PublishCompletion;
import dev.caskeleton.messaging.api.publish.PublishResult;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
import java.util.Optional;
/**
* Moves messages from a dead letter destination back to their source.
*
* <p>A redrive is a publish followed by a settlement, in that order, exactly like dead lettering in
* reverse. A message whose republish did not confirm stays in the dead letter destination: losing
* it on the way back would be the one outcome worse than leaving it parked.
*
* <p>The redrive id and a redrive counter travel with each message. Without them a message that
* fails again is indistinguishable from a new one, and a redrive loop is invisible until the dead
* letter destination is full.
*/
public final class RedriveService {
private final DestructiveOperationGuard guard;
private final RedriveSource source;
private final RedrivePublisher publisher;
private final AuditSink audit;
/**
* Creates a redrive service.
*
* @param guard the destructive operation guard
* @param source reads and settles dead letter messages
* @param publisher republishes to the target destination
* @param audit records the operation
*/
public RedriveService(
DestructiveOperationGuard guard,
RedriveSource source,
RedrivePublisher publisher,
AuditSink audit) {
this.guard = Objects.requireNonNull(guard, "guard must not be null");
this.source = Objects.requireNonNull(source, "source must not be null");
this.publisher = Objects.requireNonNull(publisher, "publisher must not be null");
this.audit = Objects.requireNonNull(audit, "audit must not be null");
}
/**
* Runs one redrive pass.
*
* @param request what to move
* @param approval the approval, when one was supplied
* @param subject the operator identity
* @param now the current instant
* @return what the pass did
*/
public RedriveReport redrive(
RedriveRequest request, Optional<AdminApproval> approval, String subject, Instant now) {
Objects.requireNonNull(request, "request must not be null");
guard.authorize(
DestructiveOperation.REDRIVE, request.source(), approval, request.dryRun(), now);
List<MessageId> candidates = source.peek(request.source(), request.batchSize());
if (request.dryRun()) {
return new RedriveReport(candidates.size(), 0, 0, true);
}
List<MessageId> moved = new ArrayList<>();
int failed = 0;
for (MessageId messageId : candidates) {
PublishResult result = publisher.republish(messageId, request.target(), request.redriveId());
if (result.completion() == PublishCompletion.CONFIRMED) {
source.settle(request.source(), messageId);
moved.add(messageId);
} else {
failed++;
}
}
audit.record(
new dev.caskeleton.messaging.observation.MessagingAuditEvent(
"REDRIVE",
subject,
request.source().value(),
approval.map(AdminApproval::ticket).orElse("dry-run"),
now,
java.util.Map.of(
"redriveId", request.redriveId().toString(),
"moved", Integer.toString(moved.size()),
"failed", Integer.toString(failed))));
return new RedriveReport(candidates.size(), moved.size(), failed, false);
}
/** Reads and settles messages on a dead letter destination. */
public interface RedriveSource {
/**
* Returns the next candidates without settling them.
*
* @param destination the dead letter destination
* @param batchSize how many to return
* @return the candidate identities
*/
List<MessageId> peek(
dev.caskeleton.messaging.api.destination.DestinationName destination, int batchSize);
/**
* Settles a message that has been successfully republished.
*
* @param destination the dead letter destination
* @param messageId the message identity
*/
void settle(
dev.caskeleton.messaging.api.destination.DestinationName destination, MessageId messageId);
}
/** Republishes a dead lettered message to its target destination. */
@FunctionalInterface
public interface RedrivePublisher {
/**
* Republishes one message under its original identity.
*
* @param messageId the message identity
* @param target the destination to publish back to
* @param redriveId the operation identity stamped on the message
* @return the publish outcome
*/
PublishResult republish(
MessageId messageId,
dev.caskeleton.messaging.api.destination.DestinationName target,
java.util.UUID redriveId);
}
/** Records privileged operations. */
@FunctionalInterface
public interface AuditSink {
/**
* Records one audit event.
*
* @param event the event
*/
void record(dev.caskeleton.messaging.observation.MessagingAuditEvent event);
}
}
@@ -0,0 +1,21 @@
package dev.caskeleton.messaging.admin.runtime;
import java.util.Objects;
import java.util.UUID;
/**
* What one replay did.
*
* @param replayId the operation identity
* @param replayed how many messages were re-read
* @param dryRun whether this was a plan-only run
*/
public record ReplayReport(UUID replayId, long replayed, boolean dryRun) {
public ReplayReport {
Objects.requireNonNull(replayId, "replayId must not be null");
if (replayed < 0) {
throw new IllegalArgumentException("replayed must not be negative");
}
}
}
@@ -0,0 +1,99 @@
package dev.caskeleton.messaging.admin.runtime;
import dev.caskeleton.messaging.admin.AdminApproval;
import dev.caskeleton.messaging.admin.DestructiveOperation;
import dev.caskeleton.messaging.admin.DestructiveOperationGuard;
import dev.caskeleton.messaging.admin.ReplayRequest;
import dev.caskeleton.messaging.observation.MessagingAuditEvent;
import java.time.Instant;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
/**
* Re-reads a destination from an earlier position.
*
* <p>An isolated replay reads alongside the live consumer and needs no approval, because it changes
* nothing: a throwaway group has its own offsets. Replaying into an existing production group is a
* different operation entirely — it rewinds a live consumer and reprocesses everything since — so
* it goes through the destructive guard.
*
* <p>Making the safe form free and the destructive form approved is what keeps operators from
* reaching for the destructive one out of convenience.
*/
public final class ReplayService {
private final DestructiveOperationGuard guard;
private final ReplayExecutor executor;
private final RedriveService.AuditSink audit;
/**
* Creates a replay service.
*
* @param guard the destructive operation guard
* @param executor performs the replay
* @param audit records the operation
*/
public ReplayService(
DestructiveOperationGuard guard, ReplayExecutor executor, RedriveService.AuditSink audit) {
this.guard = Objects.requireNonNull(guard, "guard must not be null");
this.executor = Objects.requireNonNull(executor, "executor must not be null");
this.audit = Objects.requireNonNull(audit, "audit must not be null");
}
/**
* Runs one replay.
*
* @param request what to replay
* @param approval the approval, when one was supplied
* @param subject the operator identity
* @param now the current instant
* @return what the replay did
*/
public ReplayReport replay(
ReplayRequest request, Optional<AdminApproval> approval, String subject, Instant now) {
Objects.requireNonNull(request, "request must not be null");
Objects.requireNonNull(approval, "approval must not be null");
boolean needsApproval = !request.isolatedConsumerGroup();
guard.authorize(
DestructiveOperation.REPLAY,
request.destination(),
approval,
request.dryRun() || !needsApproval,
now);
if (request.dryRun()) {
return new ReplayReport(request.replayId(), 0, true);
}
long replayed = executor.replay(request);
audit.record(
new MessagingAuditEvent(
"REPLAY",
subject,
request.destination().value(),
approval.map(AdminApproval::ticket).orElse("isolated"),
now,
Map.of(
"replayId", request.replayId().toString(),
"isolated", Boolean.toString(request.isolatedConsumerGroup()),
"replayed", Long.toString(replayed))));
return new ReplayReport(request.replayId(), replayed, false);
}
/** Performs the replay against a broker. */
@FunctionalInterface
public interface ReplayExecutor {
/**
* Replays a destination and returns how many messages were re-read.
*
* @param request the replay request
* @return the replayed message count
*/
long replay(ReplayRequest request);
}
}
@@ -0,0 +1,88 @@
package dev.caskeleton.messaging.admin.runtime;
import dev.caskeleton.messaging.admin.TopologyManifest;
import dev.caskeleton.messaging.api.error.MessageTopologyException;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Objects;
/**
* Validates declared topology against what the broker actually has.
*
* <p>Validate-only, and it fails startup rather than logging. A partition count that silently
* differs from the manifest changes the ordering guarantee the destination advertises, and a
* missing {@code min.insync.replicas} changes what {@code acks=all} actually means — both are the
* kind of drift that is invisible until the incident.
*/
public final class TopologyValidationRuntime {
private final TopologyReader reader;
/**
* Creates a validator over a broker reader.
*
* @param reader reads the observed topology
*/
public TopologyValidationRuntime(TopologyReader reader) {
this.reader = Objects.requireNonNull(reader, "reader must not be null");
}
/**
* Validates every manifest, reporting all differences at once.
*
* @param manifests the declared topology
* @throws MessageTopologyException when the broker does not match
*/
public void validate(List<TopologyManifest> manifests) {
Objects.requireNonNull(manifests, "manifests must not be null");
List<String> problems = new ArrayList<>();
for (TopologyManifest manifest : manifests) {
ObservedTopology observed = reader.read(manifest.physicalName());
if (observed == null) {
problems.add(manifest.physicalName() + " does not exist");
continue;
}
manifest
.differencesFrom(
observed.partitions(), observed.replicationFactor(), observed.configuration())
.forEach(difference -> problems.add(manifest.physicalName() + ": " + difference));
}
if (!problems.isEmpty()) {
throw new MessageTopologyException(
"TOPOLOGY_MISMATCH",
"broker topology does not match the manifest: " + String.join("; ", problems));
}
}
/** Reads the observed topology for a physical destination. */
@FunctionalInterface
public interface TopologyReader {
/**
* Reads one destination's topology.
*
* @param physicalName the broker-side name
* @return the observed topology, or null when it does not exist
*/
ObservedTopology read(String physicalName);
}
/**
* What the broker reports for a destination.
*
* @param partitions the observed partition count
* @param replicationFactor the observed replication factor
* @param configuration the observed configuration
*/
public record ObservedTopology(
int partitions, int replicationFactor, Map<String, String> configuration) {
public ObservedTopology {
Objects.requireNonNull(configuration, "configuration must not be null");
configuration = Map.copyOf(configuration);
}
}
}
@@ -0,0 +1,91 @@
package dev.caskeleton.messaging.admin.runtime;
import dev.caskeleton.messaging.admin.DestinationTopology;
import dev.caskeleton.messaging.admin.TopologyIssue;
import dev.caskeleton.messaging.admin.TopologyManifest;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Objects;
/**
* Compares one declared topology against what the broker reports.
*
* <p>Which discrepancies block is a judgement encoded here rather than left to configuration.
* Replication factor and absence are blocking because a destination that is missing or unreplicated
* cannot deliver the durability its profile promises. A partition count that is <em>higher</em>
* than declared is advisory rather than blocking: extra partitions do not break durability, and
* someone scaling a topic up deliberately should not be met with a refusal to start.
*
* <p>A partition count that is <em>lower</em> is blocking, because it silently reduces the
* concurrency the destination was sized for and, on a keyed topic, changes which key lands where.
*/
public final class TopologyValidator {
/**
* Compares a manifest against observed topology.
*
* @param manifest what was declared
* @param observed what the broker reports
* @return the discrepancies found, empty when they agree
*/
public List<TopologyIssue> compare(TopologyManifest manifest, DestinationTopology observed) {
Objects.requireNonNull(manifest, "manifest must not be null");
Objects.requireNonNull(observed, "observed must not be null");
List<TopologyIssue> issues = new ArrayList<>();
String destination = manifest.destination();
if (!observed.exists()) {
issues.add(
TopologyIssue.blocking(destination, "existence", manifest.physicalName(), "absent"));
return List.copyOf(issues);
}
if (!manifest.physicalName().equals(observed.physicalName())) {
issues.add(
TopologyIssue.blocking(
destination, "physicalName", manifest.physicalName(), observed.physicalName()));
}
if (observed.partitions() < manifest.partitions()) {
issues.add(
TopologyIssue.blocking(
destination,
"partitions",
Integer.toString(manifest.partitions()),
Integer.toString(observed.partitions())));
} else if (observed.partitions() > manifest.partitions()) {
// Scaling a topic up is a legitimate operation; refusing to start would punish it.
issues.add(
TopologyIssue.advisory(
destination,
"partitions",
Integer.toString(manifest.partitions()),
Integer.toString(observed.partitions())));
}
if (observed.replicationFactor() < manifest.replicationFactor()) {
issues.add(
TopologyIssue.blocking(
destination,
"replicationFactor",
Integer.toString(manifest.replicationFactor()),
Integer.toString(observed.replicationFactor())));
}
for (Map.Entry<String, String> required : manifest.requiredConfiguration().entrySet()) {
String actual = observed.configuration().get(required.getKey());
if (!required.getValue().equals(actual)) {
issues.add(
TopologyIssue.blocking(
destination,
required.getKey(),
required.getValue(),
actual == null ? "unset" : actual));
}
}
return List.copyOf(issues);
}
}
@@ -0,0 +1,190 @@
package dev.caskeleton.messaging.admin.runtime;
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.admin.AdminApproval;
import dev.caskeleton.messaging.admin.ApprovedRedrivePlan;
import dev.caskeleton.messaging.admin.ApprovedReplayPlan;
import dev.caskeleton.messaging.admin.RedrivePlan;
import dev.caskeleton.messaging.admin.RedriveRequest;
import dev.caskeleton.messaging.admin.RedriveResult;
import dev.caskeleton.messaging.admin.ReplayPlan;
import dev.caskeleton.messaging.admin.ReplayRequest;
import dev.caskeleton.messaging.admin.ReplayResult;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
import java.time.Duration;
import java.time.Instant;
import java.util.Optional;
import java.util.UUID;
import org.junit.jupiter.api.Test;
class ApprovedPlanExecutionTest {
private static final Instant NOW = Instant.parse("2026-08-10T09:00:00Z");
private static final UUID OPERATION_ID = UUID.fromString("0199aaaa-bbbb-7ccc-8ddd-eeeeffff0000");
private static AdminApproval approval() {
return new AdminApproval("CHG-1042", "ops@example.com", NOW, NOW.plus(Duration.ofHours(2)));
}
private static ReplayRequest replayRequest() {
return new ReplayRequest(
OPERATION_ID,
new DestinationName("orders.v1"),
NOW.minus(Duration.ofDays(1)),
Optional.empty(),
true,
false);
}
private static ReplayPlan replayPlan(String topologyVersion) {
return new ReplayPlan(replayRequest(), 4_200_000, NOW, topologyVersion, false);
}
private static RedriveRequest redriveRequest() {
return new RedriveRequest(
OPERATION_ID,
new DestinationName("orders.v1.dlq"),
new DestinationName("orders.v1"),
50,
false);
}
private static RedrivePlan redrivePlan(int candidates, int alreadyRedriven) {
return new RedrivePlan(redriveRequest(), candidates, alreadyRedriven, NOW, "v1");
}
@Test
void anExpiredApprovalCannotExecute() {
ApprovedReplayPlan approved = new ApprovedReplayPlan(replayPlan("v1"), approval());
assertThatThrownBy(() -> approved.requireExecutable(NOW.plus(Duration.ofDays(1)), "v1"))
.isInstanceOf(MessageAuthorizationException.class)
.hasMessageContaining("CHG-1042");
}
@Test
void aTopologyChangeSinceApprovalInvalidatesThePlan() {
ApprovedReplayPlan approved = new ApprovedReplayPlan(replayPlan("v1"), approval());
assertThatThrownBy(() -> approved.requireExecutable(NOW, "v2"))
.as("every number in the plan was computed against the old topology")
.isInstanceOf(MessageAuthorizationException.class)
.hasMessageContaining("rebuilt");
}
@Test
void aValidApprovalOnUnchangedTopologyExecutes() {
assertThatCode(
() -> new ApprovedReplayPlan(replayPlan("v1"), approval()).requireExecutable(NOW, "v1"))
.doesNotThrowAnyException();
}
@Test
void aRedriveThatWouldLoopNeedsThatAcknowledgedExplicitly() {
ApprovedRedrivePlan approved =
new ApprovedRedrivePlan(redrivePlan(900, 400), approval(), false);
assertThatThrownBy(() -> approved.requireExecutable(NOW, "v1"))
.isInstanceOf(MessageAuthorizationException.class)
.hasMessageContaining("looks like progress");
}
@Test
void anAcknowledgedLoopMayProceed() {
assertThatCode(
() ->
new ApprovedRedrivePlan(redrivePlan(900, 400), approval(), true)
.requireExecutable(NOW, "v1"))
.doesNotThrowAnyException();
}
@Test
void aRedriveWithNoPreviouslyRedrivenCandidatesNeedsNoAcknowledgement() {
assertThatCode(
() ->
new ApprovedRedrivePlan(redrivePlan(900, 0), approval(), false)
.requireExecutable(NOW, "v1"))
.doesNotThrowAnyException();
}
@Test
void thePlanDescribesItsImpactBeforeAnythingRuns() {
assertThat(replayPlan("v1").describeImpact()).contains("4200000").contains("isolated group");
assertThat(redrivePlan(900, 400).describeImpact())
.contains("already failed a previous redrive");
}
@Test
void aReplayIntoTheLiveGroupSaysSoInCapitals() {
ReplayPlan live =
new ReplayPlan(
new ReplayRequest(
OPERATION_ID,
new DestinationName("orders.v1"),
NOW.minus(Duration.ofDays(1)),
Optional.empty(),
false,
false),
4_200_000,
NOW,
"v1",
true);
assertThat(live.describeImpact())
.as("re-delivering millions of messages into the live group is the decision to flag")
.contains("LIVE consumer group");
}
@Test
void anApprovalAuthorisesOneExecutionNotAStandingPermission() {
AdminOperationIdempotencyStore store = new AdminOperationIdempotencyStore();
assertThat(store.claim("CHG-1042", "op-1", NOW)).isEmpty();
assertThat(store.claim("CHG-1042", "op-2", NOW.plus(Duration.ofMinutes(5))))
.as("an arrow-up in the shell must not re-run an approved redrive")
.hasValueSatisfying(existing -> assertThat(existing.operationId()).isEqualTo("op-1"));
}
@Test
void aDifferentApprovalIsClaimedIndependently() {
AdminOperationIdempotencyStore store = new AdminOperationIdempotencyStore();
store.claim("CHG-1042", "op-1", NOW);
assertThat(store.claim("CHG-1043", "op-2", NOW)).isEmpty();
assertThat(store.size()).isEqualTo(2);
}
@Test
void aReplayResultFlagsAShortfallAgainstTheApprovedEstimate() {
ReplayResult result =
new ReplayResult(OPERATION_ID, 1_000_000, 100_000, Duration.ofMinutes(3), true, false);
assertThat(result.fellShortOfTheEstimate())
.as("retention may have expired part of the approved window")
.isTrue();
}
@Test
void aRedriveResultMustAccountForEveryCandidate() {
RedriveResult accounted =
new RedriveResult(OPERATION_ID, 100, 80, 20, Duration.ofSeconds(4), false);
RedriveResult unaccounted =
new RedriveResult(OPERATION_ID, 100, 80, 10, Duration.ofSeconds(4), false);
assertThat(accounted.isFullyAccounted()).isTrue();
assertThat(unaccounted.isFullyAccounted())
.as("a message that was neither moved nor left parked has been lost track of")
.isFalse();
}
@Test
void aDryRunCannotClaimToHaveMovedAnything() {
assertThatThrownBy(
() -> new RedriveResult(OPERATION_ID, 100, 5, 0, Duration.ofSeconds(1), true))
.isInstanceOf(IllegalArgumentException.class);
}
}
@@ -0,0 +1,65 @@
package dev.caskeleton.messaging.admin.runtime;
import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.admin.TopologyManifest;
import dev.caskeleton.messaging.api.error.MessageTopologyException;
import java.util.List;
import java.util.Map;
import org.junit.jupiter.api.Test;
class TopologyValidationRuntimeTest {
private static final TopologyManifest ORDERS =
new TopologyManifest(
"order-events", "order.events.v1", 6, 3, Map.of("min.insync.replicas", "2"));
@Test
void aMatchingTopologyValidates() {
TopologyValidationRuntime runtime =
new TopologyValidationRuntime(
name ->
new TopologyValidationRuntime.ObservedTopology(
6, 3, Map.of("min.insync.replicas", "2")));
assertThatCode(() -> runtime.validate(List.of(ORDERS))).doesNotThrowAnyException();
}
@Test
void aMissingDestinationFailsStartup() {
TopologyValidationRuntime runtime = new TopologyValidationRuntime(name -> null);
assertThatThrownBy(() -> runtime.validate(List.of(ORDERS)))
.isInstanceOf(MessageTopologyException.class)
.hasMessageContaining("does not exist");
}
@Test
void aWeakenedReplicationSettingFailsStartup() {
TopologyValidationRuntime runtime =
new TopologyValidationRuntime(
name ->
new TopologyValidationRuntime.ObservedTopology(
6, 3, Map.of("min.insync.replicas", "1")));
assertThatThrownBy(() -> runtime.validate(List.of(ORDERS)))
.isInstanceOf(MessageTopologyException.class)
.hasMessageContaining("min.insync.replicas");
}
@Test
void everyDifferenceIsReportedAtOnce() {
TopologyValidationRuntime runtime =
new TopologyValidationRuntime(
name ->
new TopologyValidationRuntime.ObservedTopology(
3, 1, Map.of("min.insync.replicas", "1")));
assertThatThrownBy(() -> runtime.validate(List.of(ORDERS)))
.isInstanceOf(MessageTopologyException.class)
.hasMessageContaining("partitions")
.hasMessageContaining("replicationFactor")
.hasMessageContaining("min.insync.replicas");
}
}
@@ -0,0 +1,172 @@
package dev.caskeleton.messaging.admin.runtime;
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.admin.DestinationTopology;
import dev.caskeleton.messaging.admin.TopologyIssue;
import dev.caskeleton.messaging.admin.TopologyManagementMode;
import dev.caskeleton.messaging.admin.TopologyManifest;
import dev.caskeleton.messaging.admin.TopologyValidationReport;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import org.junit.jupiter.api.Test;
class TopologyValidatorTest {
private final TopologyValidator validator = new TopologyValidator();
private static TopologyManifest manifest() {
return new TopologyManifest(
"orders.v1", "orders-v1", 12, 3, Map.of("min.insync.replicas", "2"));
}
private static DestinationTopology observed(
int partitions, int replication, Map<String, String> config) {
return new DestinationTopology("orders-v1", partitions, replication, config, true);
}
@Test
void anAgreeingTopologyProducesNoIssues() {
assertThat(validator.compare(manifest(), observed(12, 3, Map.of("min.insync.replicas", "2"))))
.isEmpty();
}
@Test
void anAbsentDestinationBlocksStartup() {
List<TopologyIssue> issues =
validator.compare(manifest(), DestinationTopology.absent("orders-v1"));
assertThat(issues)
.singleElement()
.satisfies(
issue -> {
assertThat(issue.attribute()).isEqualTo("existence");
assertThat(issue.severity()).isEqualTo(TopologyIssue.Severity.BLOCKING);
});
}
@Test
void tooFewPartitionsBlocksBecauseKeysWouldLandDifferently() {
List<TopologyIssue> issues =
validator.compare(manifest(), observed(6, 3, Map.of("min.insync.replicas", "2")));
assertThat(issues)
.singleElement()
.satisfies(
issue -> assertThat(issue.severity()).isEqualTo(TopologyIssue.Severity.BLOCKING));
}
@Test
void extraPartitionsAreAdvisoryBecauseScalingUpIsLegitimate() {
List<TopologyIssue> issues =
validator.compare(manifest(), observed(24, 3, Map.of("min.insync.replicas", "2")));
assertThat(issues)
.singleElement()
.satisfies(
issue -> assertThat(issue.severity()).isEqualTo(TopologyIssue.Severity.ADVISORY));
}
@Test
void tooLittleReplicationBlocksBecauseDurabilityIsPromised() {
List<TopologyIssue> issues =
validator.compare(manifest(), observed(12, 1, Map.of("min.insync.replicas", "2")));
assertThat(issues)
.singleElement()
.satisfies(
issue -> {
assertThat(issue.attribute()).isEqualTo("replicationFactor");
assertThat(issue.severity()).isEqualTo(TopologyIssue.Severity.BLOCKING);
});
}
@Test
void aMissingRequiredConfigurationEntryBlocks() {
List<TopologyIssue> issues = validator.compare(manifest(), observed(12, 3, Map.of()));
assertThat(issues)
.singleElement()
.satisfies(issue -> assertThat(issue.actual()).isEqualTo("unset"));
}
@Test
void everyIssueIsCollectedRatherThanFailingOnTheFirst() {
List<TopologyIssue> issues = validator.compare(manifest(), observed(6, 1, Map.of()));
assertThat(issues)
.as("discovering the next problem only after a redeploy turns one fix into several")
.hasSize(3);
}
@Test
void aReportRefusesStartupWhenAnythingBlocks() {
TopologyValidationReport report =
new TopologyValidationReport(
validator.compare(manifest(), observed(12, 1, Map.of("min.insync.replicas", "2"))), 1);
assertThat(report.isAcceptable()).isFalse();
assertThatThrownBy(report::requireAcceptable)
.isInstanceOf(MessagingConfigurationException.class)
.hasMessageContaining("replicationFactor");
}
@Test
void anAdvisoryOnlyReportStillStarts() {
TopologyValidationReport report =
new TopologyValidationReport(
validator.compare(manifest(), observed(24, 3, Map.of("min.insync.replicas", "2"))), 1);
assertThat(report.isAcceptable()).isTrue();
assertThat(report.advisory()).hasSize(1);
assertThatCode(report::requireAcceptable).doesNotThrowAnyException();
}
@Test
void theCompositeValidatorChecksEveryManifest() {
CompositeTopologyValidator composite =
new CompositeTopologyValidator(
new BrokerTopologyInspector() {
@Override
public Optional<DestinationTopology> describe(String physicalName) {
return Optional.empty();
}
@Override
public String topologyVersion() {
return "v1";
}
});
TopologyValidationReport report =
composite.validate(
List.of(
manifest(), new TopologyManifest("payments.v1", "payments-v1", 3, 3, Map.of())));
assertThat(report.destinationsChecked()).isEqualTo(2);
assertThat(report.blocking()).hasSize(2);
}
@Test
void autoCreationIsRefusedInProduction() {
assertThatThrownBy(() -> TopologyManagementMode.CREATE_IF_MISSING.requireSafeFor(true))
.as("a mistyped destination would be created and look exactly like a real one")
.isInstanceOf(MessagingConfigurationException.class);
}
@Test
void autoCreationIsAllowedOutsideProduction() {
assertThatCode(() -> TopologyManagementMode.CREATE_IF_MISSING.requireSafeFor(false))
.doesNotThrowAnyException();
}
@Test
void validateOnlyIsAlwaysSafe() {
assertThatCode(() -> TopologyManagementMode.VALIDATE_ONLY.requireSafeFor(true))
.doesNotThrowAnyException();
}
}