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:
+45
@@ -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);
|
||||
}
|
||||
}
|
||||
+56
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+49
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+46
@@ -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);
|
||||
}
|
||||
}
|
||||
+25
@@ -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
|
||||
}
|
||||
+73
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+64
@@ -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);
|
||||
}
|
||||
}
|
||||
+37
@@ -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);
|
||||
}
|
||||
}
|
||||
}
|
||||
+51
@@ -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;
|
||||
}
|
||||
}
|
||||
+55
@@ -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");
|
||||
}
|
||||
}
|
||||
+36
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+49
@@ -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;
|
||||
}
|
||||
}
|
||||
+82
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+37
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+76
@@ -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);
|
||||
}
|
||||
}
|
||||
+83
@@ -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()));
|
||||
}
|
||||
}
|
||||
+116
@@ -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();
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user