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

This commit is contained in:
DongHyeonka
2026-08-24 18:26:40 +09:00
parent 16e33ce986
commit a261df2a2b
100 changed files with 7072 additions and 902 deletions
@@ -1,20 +1,27 @@
package dev.caskeleton.messaging.testkit;
import java.time.Instant;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Objects;
/**
* One scenario actually exercised against one broker image.
*
* <p>{@code BrokerFailureMatrix.shipped()} hard-coded every scenario as {@code LIVE_BROKER} for
* both brokers, and the suite that "verified" the matrix asserted the contents of that same map. A
* test comparing a constant to itself passes on a machine with no Docker at all, and the support
* matrix it feeds then tells an adopter that connection-cut and confirm-timeout are certified when
* neither has ever run.
* <p>Coverage used to be a constant: every scenario marked live-broker for both brokers, with the
* suite that "verified" the matrix asserting the contents of that same map. A test comparing a
* constant to itself passes on a machine with no Docker at all, and the support matrix it feeds
* then tells an adopter that connection-cut and confirm-timeout are certified when neither has ever
* run.
*
* <p>This record is what a lane emits after running. The image reference and the commit are here
* because "certified" is a claim about a specific broker build and a specific source tree; without
* them the evidence cannot be checked against anything later.
*
* <p>{@link #toJson()} and {@link #fromJson(String)} are the same statement in both directions: the
* certification lane writes a line per scenario it proved and the compatibility matrix reads those
* lines back. One line is one object rather than an array, so appending a scenario is an append and
* a diff of two runs is a diff of two sets of lines.
*/
public record BrokerCertificationEvidence(
String adapter,
@@ -37,24 +44,103 @@ public record BrokerCertificationEvidence(
throw new IllegalArgumentException(
"evidence names the adapter, the broker image and the test that produced it");
}
// The serialised form is a flat object written by hand, so a quote or a backslash in any field
// would produce a manifest line that the reader silently truncates instead of rejecting. Every
// value here is an identifier, an image reference or an instant; none of them needs escaping,
// and a value that does is a sign the caller is recording something else.
requireUnescaped(adapter, "adapter");
requireUnescaped(brokerImage, "brokerImage");
requireUnescaped(testId, "testId");
requireUnescaped(outcome, "outcome");
requireUnescaped(gitCommit, "gitCommit");
}
/** The machine-readable form a release lane writes out. */
/** The order fields appear in, shared by the writer and the reader. */
private static final String[] FIELDS = {
"adapter", "brokerImage", "scenario", "testId", "outcome", "gitCommit", "observedAt"
};
/**
* The machine-readable form a release lane writes out.
*
* @return one JSON object on a single line
*/
public String toJson() {
return "{\"adapter\":\""
+ adapter
+ "\",\"brokerImage\":\""
+ brokerImage
+ "\",\"scenario\":\""
+ scenario.name()
+ "\",\"testId\":\""
+ testId
+ "\",\"outcome\":\""
+ outcome
+ "\",\"gitCommit\":\""
+ gitCommit
+ "\",\"observedAt\":\""
+ observedAt
+ "\"}";
String[] values = {
adapter, brokerImage, scenario.name(), testId, outcome, gitCommit, observedAt.toString()
};
StringBuilder json = new StringBuilder("{");
for (int index = 0; index < FIELDS.length; index++) {
if (index > 0) {
json.append(',');
}
json.append('"').append(FIELDS[index]).append("\":\"").append(values[index]).append('"');
}
return json.append('}').toString();
}
/**
* Reads back one line a lane wrote.
*
* <p>Hand-rolled rather than pulled from a JSON library because this module is the test support
* for a platform whose {@code *-api} leaves carry no dependencies at all, and because the shape
* is fixed by {@link #toJson()} above. A missing or unknown field is refused: evidence that
* cannot be fully read is not partial coverage, it is a manifest nobody can act on.
*
* @param json one line produced by {@link #toJson()}
* @return the evidence that line records
*/
public static BrokerCertificationEvidence fromJson(String json) {
Objects.requireNonNull(json, "json must not be null");
Map<String, String> fields = parse(json.trim());
for (String field : FIELDS) {
if (!fields.containsKey(field)) {
throw new IllegalArgumentException(
"certification evidence is missing '" + field + "': " + json);
}
}
if (fields.size() != FIELDS.length) {
throw new IllegalArgumentException(
"certification evidence carries fields this release does not define: " + fields.keySet());
}
return new BrokerCertificationEvidence(
fields.get("adapter"),
fields.get("brokerImage"),
NetworkFaultScenario.byName(fields.get("scenario")),
fields.get("testId"),
fields.get("outcome"),
fields.get("gitCommit"),
Instant.parse(fields.get("observedAt")));
}
private static Map<String, String> parse(String json) {
if (json.length() < 2 || json.charAt(0) != '{' || json.charAt(json.length() - 1) != '}') {
throw new IllegalArgumentException("certification evidence is not a JSON object: " + json);
}
Map<String, String> fields = new LinkedHashMap<>();
String body = json.substring(1, json.length() - 1);
int cursor = 0;
while (cursor < body.length()) {
int keyStart = body.indexOf('"', cursor);
if (keyStart < 0) {
break;
}
int keyEnd = body.indexOf('"', keyStart + 1);
int valueStart = body.indexOf('"', keyEnd + 1);
int valueEnd = valueStart < 0 ? -1 : body.indexOf('"', valueStart + 1);
if (keyEnd < 0 || valueStart < 0 || valueEnd < 0) {
throw new IllegalArgumentException("certification evidence is truncated: " + json);
}
fields.put(body.substring(keyStart + 1, keyEnd), body.substring(valueStart + 1, valueEnd));
cursor = valueEnd + 1;
}
return fields;
}
private static void requireUnescaped(String value, String field) {
if (value.indexOf('"') >= 0 || value.indexOf('\\') >= 0) {
throw new IllegalArgumentException(
field + " must not contain a quote or a backslash: " + field + "='" + value + "'");
}
}
}
@@ -75,6 +75,17 @@ public final class BrokerFailureMatrix {
.toList();
}
/**
* Reports whether an adapter has been run against a live broker at all.
*
* @param adapter the adapter module name
* @return true when at least one scenario has live-broker evidence
*/
public boolean hasLiveBrokerCoverage(String adapter) {
return NetworkFaultScenario.all().stream()
.anyMatch(scenario -> coverageOf(adapter, scenario) == Coverage.LIVE_BROKER);
}
/**
* Reports whether an adapter covers every scenario.
*
@@ -94,22 +105,13 @@ public final class BrokerFailureMatrix {
return List.copyOf(coverage.keySet());
}
/**
* Returns the matrix the platform ships with.
*
* <p>Kafka and RabbitMQ are Stable and cover everything. The experimental adapters cover the
* deterministic scenarios their contract suite exercises and are explicitly recorded as having no
* live-broker coverage — which is what makes their Experimental tier a statement of fact rather
* than a disclaimer.
*
* @return the shipped coverage matrix
*/
/**
* Builds a matrix from evidence a lane actually produced.
*
* <p>Anything with no evidence is {@link Coverage#NOT_COVERED}. That is the whole difference from
* {@link #shipped()}: a scenario is covered because a test ran it against a broker, not because
* somebody wrote the constant.
* <p>Anything with no evidence is {@link Coverage#NOT_COVERED}. A hard-coded matrix marked every
* scenario as live-broker coverage for both brokers, and the suite that checked it asserted the
* same constants, so the whole claim passed on a machine with no Docker. A scenario is covered
* because a test ran it against a broker, not because somebody wrote the constant.
*
* @param evidence what the certification lane observed
*/
@@ -118,43 +120,28 @@ public final class BrokerFailureMatrix {
Objects.requireNonNull(evidence, "evidence must not be null");
BrokerFailureMatrix matrix = new BrokerFailureMatrix();
for (BrokerCertificationEvidence observed : evidence) {
requireOutcomeMatchesExpectation(observed);
matrix.record(observed.adapter(), observed.scenario(), Coverage.LIVE_BROKER);
}
return matrix;
}
/**
* The declared shipping matrix.
* Refuses evidence whose observed outcome contradicts the scenario it claims to cover.
*
* @deprecated These constants describe what the platform intends to certify, not what any run
* proved. Every scenario was marked {@code LIVE_BROKER} for both brokers and the suite that
* checked the matrix asserted the same map, so it passed on a machine with no Docker. Use
* {@link #from(java.util.Collection)} with a lane's evidence; this remains only so an
* existing caller keeps compiling while it migrates.
* <p>Nothing compared the two, so a run that reported a definite rejection where the scenario
* says the outcome is unknowable counted as coverage of that scenario. That is worse than no
* evidence: it certifies the adapter for exactly the behaviour it got wrong, and the support
* matrix then tells an adopter the case is handled.
*/
@Deprecated
public static BrokerFailureMatrix shipped() {
BrokerFailureMatrix matrix = new BrokerFailureMatrix();
for (NetworkFaultScenario scenario : NetworkFaultScenario.all()) {
matrix.record("messaging-kafka", scenario, Coverage.LIVE_BROKER);
matrix.record("messaging-rabbit", scenario, Coverage.LIVE_BROKER);
private static void requireOutcomeMatchesExpectation(BrokerCertificationEvidence observed) {
String expected = observed.scenario().expectation().name();
if (!expected.equals(observed.outcome())) {
throw new IllegalArgumentException(
"%s recorded %s for %s, which expects %s; a run that disagrees with the scenario is a"
.formatted(
observed.adapter(), observed.outcome(), observed.scenario().name(), expected)
+ " failing certification, not coverage of it (%s)".formatted(observed.testId()));
}
matrix.record(
"messaging-pulsar-experimental",
NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE,
Coverage.DETERMINISTIC);
matrix.record(
"messaging-pulsar-experimental",
NetworkFaultScenario.CONFIRM_TIMEOUT,
Coverage.DETERMINISTIC);
matrix.record(
"messaging-nats-experimental",
NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE,
Coverage.DETERMINISTIC);
matrix.record(
"messaging-nats-experimental",
NetworkFaultScenario.CONFIRM_TIMEOUT,
Coverage.DETERMINISTIC);
return matrix;
}
}
@@ -0,0 +1,84 @@
package dev.caskeleton.messaging.testkit;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.Set;
/**
* The fault scenarios this repository's certification lane has actually exercised.
*
* <p>Read from a manifest a run produced, not from a list somebody typed. It was the list: an
* author added a line and the compatibility matrix, the cross-broker suite and the support matrix
* all believed it, on a machine that may never have started a container. "Certified against a live
* broker" then meant "a developer wrote that down", which is the one thing a certification claim
* must not mean.
*
* <p>The manifest is committed because a release claim has to survive the build that produced it —
* a matrix that reads {@code build/} answers differently on a clean checkout. What stops it from
* being hand-written again is the gate: {@code verifyMessagingCertificationEvidence} runs the lane
* against a real broker and refuses to pass when this file claims a scenario the run did not
* produce. Editing the file without running the lane fails the build; running the lane rewrites the
* file.
*
* <p>An absent or empty manifest is not an error here. It means no scenario has evidence, so every
* scenario is {@link BrokerFailureMatrix.Coverage#NOT_COVERED} and every Stable claim that depends
* on evidence fails — which is the correct reading of "nothing has been run".
*/
public final class CertifiedEvidence {
/** Where the certification lane writes what it proved, and where the matrix reads it. */
public static final String MANIFEST_RESOURCE = "/messaging/broker-certification-evidence.jsonl";
private static final List<BrokerCertificationEvidence> RECORDED = load();
private CertifiedEvidence() {}
/**
* Returns what the certification lane recorded.
*
* @return the evidence this repository can show
*/
public static List<BrokerCertificationEvidence> recorded() {
return RECORDED;
}
/**
* Returns the scenarios an adapter has no evidence for.
*
* <p>Named explicitly so the gap is a fact in the build rather than a silent absence.
*
* @param adapter the adapter module name
* @return the uncovered scenarios
*/
public static List<NetworkFaultScenario> knownGaps(String adapter) {
Set<NetworkFaultScenario> covered =
recorded().stream()
.filter(evidence -> evidence.adapter().equals(adapter))
.map(BrokerCertificationEvidence::scenario)
.collect(java.util.stream.Collectors.toUnmodifiableSet());
return NetworkFaultScenario.all().stream()
.filter(scenario -> !covered.contains(scenario))
.toList();
}
private static List<BrokerCertificationEvidence> load() {
try (InputStream manifest = CertifiedEvidence.class.getResourceAsStream(MANIFEST_RESOURCE)) {
if (manifest == null) {
return List.of();
}
return new String(manifest.readAllBytes(), StandardCharsets.UTF_8)
.lines()
.map(String::trim)
.filter(line -> !line.isEmpty())
.map(BrokerCertificationEvidence::fromJson)
.toList();
} catch (IOException failure) {
// Not swallowed into "no evidence": a manifest that exists and cannot be read is a broken
// build, and reporting it as an absence would quietly demote every adapter instead.
throw new IllegalStateException(
"could not read the broker certification manifest " + MANIFEST_RESOURCE, failure);
}
}
}
@@ -9,8 +9,11 @@ import java.util.Objects;
*
* <p>Held as code with a test over it rather than as a document, because a support matrix that
* lives only in prose drifts the first time an adapter is added. The test asserts the rules the
* design fixes: a Stable adapter must run the shared contract, and an Experimental adapter must be
* disabled by default.
* design fixes: a Stable adapter must run the shared contract and be certified against a live
* broker, and an Experimental adapter must be disabled by default.
*
* <p>The certification claim is derived from lane evidence rather than declared beside the tier, so
* an adapter cannot be promoted by editing a boolean.
*/
public final class CompatibilityMatrix {
@@ -36,15 +39,27 @@ public final class CompatibilityMatrix {
* @param tier the support tier
* @param runsSharedContract whether the module runs {@link MessagingAdapterContract}
* @param enabledByDefault whether the adapter is active without an explicit opt-in
* @param hasLiveBrokerCertification whether a container-backed suite exercises a real broker
*/
public record Entry(
String adapter,
List<String> brokerVersions,
Tier tier,
boolean runsSharedContract,
boolean enabledByDefault,
boolean hasLiveBrokerCertification) {
boolean enabledByDefault) {
/**
* Reports whether a lane has run this adapter against a real broker.
*
* <p>Read from the evidence rather than declared. As a field it was a boolean an author set
* next to the tier, and RabbitMQ carried {@code true} while no fault scenario had ever been
* executed against it — the same shape as the coverage matrix that used to assert its own
* constants.
*
* @return true when {@link CertifiedEvidence} has live-broker evidence for this adapter
*/
public boolean hasLiveBrokerCertification() {
return BrokerFailureMatrix.from(CertifiedEvidence.recorded()).hasLiveBrokerCoverage(adapter);
}
public Entry {
Objects.requireNonNull(tier, "tier must not be null");
@@ -67,16 +82,20 @@ public final class CompatibilityMatrix {
// the locked client is 4.1.1, so the matrix and the support document agreed with each
// other and with nothing that had executed. A version returns here when a lane runs
// against its image.
new Entry("messaging-kafka", List.of("4.1"), Tier.STABLE, true, true, true),
new Entry("messaging-kafka", List.of("4.1"), Tier.STABLE, true, true),
"messaging-rabbit",
new Entry("messaging-rabbit", List.of("4.3"), Tier.STABLE, true, true, true),
// Experimental until a lane runs a fault scenario against a RabbitMQ container. The
// adapter passes the shared contract and its broker IT exercises the routable and
// unroutable happy paths, but Stable in this repository means fault evidence, and
// there is none: connection-refused, cut-after-write, confirm-timeout,
// settlement-lost and high-latency have never been executed here.
new Entry("messaging-rabbit", List.of("4.3"), Tier.EXPERIMENTAL, true, false),
"messaging-kafka-share-experimental",
new Entry(
"messaging-kafka-share-experimental",
List.of("4.2", "4.3"),
Tier.EXPERIMENTAL,
false,
false,
false),
"messaging-pulsar-experimental",
new Entry(
@@ -84,16 +103,10 @@ public final class CompatibilityMatrix {
List.of("4.0", "4.2"),
Tier.EXPERIMENTAL,
false,
false,
false),
"messaging-nats-experimental",
new Entry(
"messaging-nats-experimental",
List.of("2.14"),
Tier.EXPERIMENTAL,
false,
false,
false));
"messaging-nats-experimental", List.of("2.14"), Tier.EXPERIMENTAL, false, false));
/**
* Returns every certified adapter.
@@ -111,6 +111,30 @@ public record NetworkFaultScenario(
"latency above the publish deadline is indistinguishable from a lost confirm at the "
+ "moment the decision has to be made");
/**
* Resolves a scenario by the name a recorded run wrote down.
*
* <p>Evidence travels as text, so the read side has to answer what a name that this release does
* not define means. It means the manifest describes a scenario the code no longer has, and
* treating it as coverage would credit an adapter for a fault nobody can reproduce — so it is
* refused rather than skipped.
*
* @param name the scenario name as it appears in recorded evidence
* @return the scenario
*/
public static NetworkFaultScenario byName(String name) {
return all().stream()
.filter(scenario -> scenario.name().equals(name))
.findFirst()
.orElseThrow(
() ->
new IllegalArgumentException(
"no fault scenario is named '"
+ name
+ "'; evidence for a scenario this release does not define is coverage of"
+ " nothing"));
}
/**
* Returns every scenario the shared fault suite runs.
*
@@ -0,0 +1,4 @@
{"adapter":"messaging-kafka","brokerImage":"apache/kafka:4.1.0","scenario":"confirm-timeout","testId":"KafkaBrokerCertificationIT#aConfirmThatNeverArrivesIsReportedAsAmbiguousAndTheRecordIsThere","outcome":"AMBIGUOUS","gitCommit":"e98b56eb03ecab588c21fd1e7dbcaa493c1d8645","observedAt":"2026-08-19T14:21:30.826332993Z"}
{"adapter":"messaging-kafka","brokerImage":"apache/kafka:4.1.0","scenario":"connection-cut-after-write","testId":"KafkaBrokerCertificationIT#aConnectionCutAfterTheWriteIsReportedAsAmbiguous","outcome":"AMBIGUOUS","gitCommit":"e98b56eb03ecab588c21fd1e7dbcaa493c1d8645","observedAt":"2026-08-19T14:21:34.906464945Z"}
{"adapter":"messaging-kafka","brokerImage":"apache/kafka:4.1.0","scenario":"high-latency","testId":"KafkaBrokerCertificationIT#latencyBeyondThePublishDeadlineIsReportedAsAmbiguous","outcome":"AMBIGUOUS","gitCommit":"e98b56eb03ecab588c21fd1e7dbcaa493c1d8645","observedAt":"2026-08-19T14:21:21.870705263Z"}
{"adapter":"messaging-kafka","brokerImage":"apache/kafka:4.1.0","scenario":"settlement-lost","testId":"KafkaBrokerCertificationIT#aDeliveryLostBeforeSettlementIsRedelivered","outcome":"REDELIVERED","gitCommit":"e98b56eb03ecab588c21fd1e7dbcaa493c1d8645","observedAt":"2026-08-19T14:21:42.058283607Z"}
@@ -1,72 +0,0 @@
package dev.caskeleton.messaging.testkit;
import java.time.Instant;
import java.util.List;
import java.util.Set;
/**
* The fault scenarios this repository's container lanes actually exercise today.
*
* <p>Committed rather than generated because the generated form belongs to a release run: a
* certification lane writes {@link BrokerCertificationEvidence} per scenario, and the release gate
* compares that output to what the support matrix claims. This file is the same statement for the
* lanes that exist in the repository right now, so the cross-broker suite has something real to
* compare against instead of comparing a hard-coded matrix to itself.
*
* <p>Adding a line here without a lane that produces it re-creates the defect. The rule is: a
* scenario appears when a test in this repository runs it against a container, and the test id
* names that test.
*/
final class CertifiedEvidence {
private static final String COMMIT = "repository-local";
private CertifiedEvidence() {}
/** What the container lanes in this repository exercise. */
static List<BrokerCertificationEvidence> recorded() {
Instant observedAt = Instant.parse("2026-08-15T00:00:00Z");
return List.of(
new BrokerCertificationEvidence(
"messaging-kafka",
"apache/kafka:4.1.0",
NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE,
"KafkaAmbiguityChaosIT#aConnectionCutAfterWriteIsAmbiguous",
"AMBIGUOUS",
COMMIT,
observedAt),
new BrokerCertificationEvidence(
"messaging-kafka",
"apache/kafka:4.1.0",
NetworkFaultScenario.SETTLEMENT_LOST,
"KafkaConsumerSettlementIT#aLostSettlementIsRedelivered",
"AMBIGUOUS",
COMMIT,
observedAt),
new BrokerCertificationEvidence(
"messaging-rabbit",
"rabbitmq:4.3-management",
NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE,
"RabbitBrokerIT#anUnroutablePublishIsRejected",
"REJECTED",
COMMIT,
observedAt));
}
/**
* The scenarios an adapter has no evidence for.
*
* <p>Named explicitly so the gap is a fact in the build rather than a silent absence. These are
* what MSG-014 asks the certification lane to close.
*/
static List<NetworkFaultScenario> knownGaps(String adapter) {
Set<NetworkFaultScenario> covered =
recorded().stream()
.filter(evidence -> evidence.adapter().equals(adapter))
.map(BrokerCertificationEvidence::scenario)
.collect(java.util.stream.Collectors.toUnmodifiableSet());
return NetworkFaultScenario.all().stream()
.filter(scenario -> !covered.contains(scenario))
.toList();
}
}
@@ -0,0 +1,127 @@
package dev.caskeleton.messaging.testkit;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.util.List;
import org.junit.jupiter.api.Test;
/**
* Holds the line between evidence a run produced and evidence a developer typed.
*
* <p>The distinction is the whole of the finding this suite exists for. A committed list of
* scenarios reads exactly like a manifest and passes exactly the same assertions, so the only thing
* that can tell them apart is where the values come from — which is what these tests check.
*/
class CertifiedEvidenceTest {
@Test
void everyRecordedScenarioIsALineTheCertificationLaneWrote() throws IOException {
List<String> manifestLines = manifest();
assertThat(manifestLines)
.as("the certification lane writes this file; nothing else may")
.isNotEmpty();
assertThat(CertifiedEvidence.recorded())
.as("coverage is read from the manifest, not from a list somebody maintained beside it")
.containsExactlyElementsOf(
manifestLines.stream().map(BrokerCertificationEvidence::fromJson).toList());
}
@Test
void everyClaimNamesTheImageItRanAgainst() {
assertThat(CertifiedEvidence.recorded())
.allSatisfy(
evidence ->
assertThat(evidence.brokerImage())
.as("a floating tag makes a certification unrepeatable")
.contains(":")
.doesNotEndWith(":latest"));
}
@Test
void everyClaimNamesTheTestThatProducedIt() {
assertThat(CertifiedEvidence.recorded())
.allSatisfy(evidence -> assertThat(evidence.testId()).contains("#"));
}
@Test
void aScenarioWithNoLineInTheManifestIsAGapRatherThanAnAbsence() {
assertThat(CertifiedEvidence.knownGaps("messaging-kafka"))
.as("a Kafka producer buffers before it learns a connection exists, so this stays unproven")
.contains(NetworkFaultScenario.CONNECTION_REFUSED);
assertThat(CertifiedEvidence.knownGaps("messaging-rabbit"))
.as("no lane runs a fault scenario against RabbitMQ, so every scenario is a gap")
.containsExactlyElementsOf(NetworkFaultScenario.all());
}
@Test
void anEvidenceLineRoundTripsThroughItsSerialisedForm() {
BrokerCertificationEvidence evidence =
new BrokerCertificationEvidence(
"messaging-kafka",
"apache/kafka:4.1.0",
NetworkFaultScenario.CONFIRM_TIMEOUT,
"SomeIT#someScenario",
"AMBIGUOUS",
"0123456789abcdef",
java.time.Instant.parse("2026-08-15T00:00:00Z"));
assertThat(BrokerCertificationEvidence.fromJson(evidence.toJson())).isEqualTo(evidence);
}
@Test
void aManifestLineMissingAFieldIsRefusedRatherThanPartiallyRead() {
assertThatThrownBy(
() ->
BrokerCertificationEvidence.fromJson(
"{\"adapter\":\"messaging-kafka\",\"scenario\":\"confirm-timeout\"}"))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("brokerImage");
}
@Test
void aManifestLineNamingAScenarioThisReleaseDoesNotDefineIsRefused() {
assertThatThrownBy(
() ->
BrokerCertificationEvidence.fromJson(
"{\"adapter\":\"messaging-kafka\",\"brokerImage\":\"apache/kafka:4.1.0\","
+ "\"scenario\":\"disk-full\",\"testId\":\"X#y\",\"outcome\":\"AMBIGUOUS\","
+ "\"gitCommit\":\"abc\",\"observedAt\":\"2026-08-15T00:00:00Z\"}"))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("disk-full");
}
@Test
void aValueThatWouldBreakTheManifestIsRefusedWhenTheEvidenceIsBuilt() {
assertThatThrownBy(
() ->
new BrokerCertificationEvidence(
"messaging-kafka",
"apache/kafka:4.1.0",
NetworkFaultScenario.CONFIRM_TIMEOUT,
"Some\"IT#someScenario",
"AMBIGUOUS",
"abc",
java.time.Instant.parse("2026-08-15T00:00:00Z")))
.as("a quote would truncate the line the release gate reads back")
.isInstanceOf(IllegalArgumentException.class);
}
private static List<String> manifest() throws IOException {
try (InputStream stream =
CertifiedEvidence.class.getResourceAsStream(CertifiedEvidence.MANIFEST_RESOURCE)) {
assertThat(stream)
.as("%s is missing; no lane has produced evidence", CertifiedEvidence.MANIFEST_RESOURCE)
.isNotNull();
return new String(stream.readAllBytes(), StandardCharsets.UTF_8)
.lines()
.map(String::trim)
.filter(line -> !line.isEmpty())
.toList();
}
}
}
@@ -37,11 +37,26 @@ class CompatibilityMatrixTest {
}
@Test
void theStableSetIsExactlyKafkaAndRabbit() {
void theStableSetIsExactlyWhatALaneHasCertified() {
assertThat(CompatibilityMatrix.entries().values())
.filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.STABLE)
.extracting(CompatibilityMatrix.Entry::adapter)
.containsExactlyInAnyOrder("messaging-kafka", "messaging-rabbit");
.as("RabbitMQ passes the shared contract, but no fault scenario has been run against it")
.containsExactly("messaging-kafka");
}
@Test
void aCertificationClaimCannotBeMadeWithoutEvidence() {
assertThat(CompatibilityMatrix.entries().values())
.allSatisfy(
entry ->
assertThat(entry.hasLiveBrokerCertification())
.as(
"%s claims certification, so a lane must have produced evidence",
entry.adapter())
.isEqualTo(
BrokerFailureMatrix.from(CertifiedEvidence.recorded())
.hasLiveBrokerCoverage(entry.adapter())));
}
@Test
@@ -75,7 +90,7 @@ class CompatibilityMatrixTest {
assertThatThrownBy(
() ->
new CompatibilityMatrix.Entry(
"messaging-x", List.of(), CompatibilityMatrix.Tier.STABLE, true, true, true))
"messaging-x", List.of(), CompatibilityMatrix.Tier.STABLE, true, true))
.isInstanceOf(IllegalArgumentException.class);
}
@@ -99,4 +114,15 @@ class CompatibilityMatrixTest {
.filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.EXPERIMENTAL)
.allSatisfy(entry -> assertThat(entry.hasLiveBrokerCertification()).isFalse());
}
@Test
void anAdapterWithoutEvidenceCannotBeCalledStable() {
CompatibilityMatrix.Entry undeclared =
new CompatibilityMatrix.Entry(
"messaging-artemis", List.of("2.42"), CompatibilityMatrix.Tier.STABLE, true, false);
assertThat(undeclared.hasLiveBrokerCertification())
.as("promoting an adapter used to be a boolean an author could set beside the tier")
.isFalse();
}
}
@@ -22,14 +22,14 @@ class CrossBrokerContractSuite {
/**
* The matrix built from the evidence this repository actually has.
*
* <p>It used to be {@code BrokerFailureMatrix.shipped()} — a hard-coded map marking every
* scenario {@code LIVE_BROKER} for both brokers — and the assertions below then compared that map
* to itself. This suite passed on a machine with no Docker, and the support matrix it feeds told
* adopters that connection-cut and confirm-timeout were certified when neither had ever run.
* <p>A hard-coded map marking every scenario live-broker for both brokers would leave the
* assertions below comparing that map to itself: the suite passes on a machine with no Docker,
* and the support matrix it feeds tells adopters that connection-cut and confirm-timeout are
* certified when neither has ever run.
*
* <p>{@link CertifiedEvidence#recorded()} is the committed record of what the container lanes
* exercise today. The assertions below now fail when the shipped claim exceeds it, which is the
* failure they were written to catch.
* <p>{@link CertifiedEvidence#recorded()} is the manifest the certification lane wrote, so the
* assertions below fail when the shipped claim exceeds what a run produced — which is the failure
* they were written to catch.
*/
private final BrokerFailureMatrix matrix = BrokerFailureMatrix.from(CertifiedEvidence.recorded());
@@ -53,6 +53,25 @@ class CrossBrokerContractSuite {
.isEqualTo(CertifiedEvidence.knownGaps("messaging-rabbit"));
}
@Test
void evidenceThatDisagreesWithItsScenarioIsNotCoverage() {
BrokerCertificationEvidence contradicting =
new BrokerCertificationEvidence(
"messaging-rabbit",
"rabbitmq:4.3-management",
NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE,
"RabbitBrokerIT#anUnroutablePublishIsRejectedEvenThoughTheExchangeConfirmedIt",
"REJECTED",
"repository-local",
java.time.Instant.parse("2026-08-15T00:00:00Z"));
org.assertj.core.api.Assertions.assertThatThrownBy(
() -> BrokerFailureMatrix.from(List.of(contradicting)))
.as("certifying an adapter for the behaviour it got wrong is worse than no evidence")
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("AMBIGUOUS");
}
@Test
void aScenarioWithNoEvidenceIsNotCovered() {
assertThat(matrix.coverageOf("messaging-kafka", NetworkFaultScenario.CONNECTION_REFUSED))
@@ -64,7 +83,7 @@ class CrossBrokerContractSuite {
void anEvidencedScenarioIsCovered() {
assertThat(
matrix.coverageOf("messaging-kafka", NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE))
.as("KafkaAmbiguityChaosIT exercises this against a container")
.as("the certification lane cuts the connection after the write against a container")
.isEqualTo(Coverage.LIVE_BROKER);
}
@@ -0,0 +1,350 @@
package dev.caskeleton.bootstrap.contract.messaging;
import static org.assertj.core.api.Assertions.assertThat;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.TreeSet;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Stream;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
/**
* Whether an adopter can compile against the messaging types this platform hands them.
*
* <p>A Gradle {@code implementation} dependency is not encapsulation. It removes the library from
* the consumer's compile classpath, but it does not remove the library's types from this module's
* public signatures. When both are true the artifact ships an API nobody can call: the method is
* there, the javadoc describes it, and the caller cannot name its parameter or its return type
* without guessing which library and which version to add to their own build. Every case below was
* exactly that — a Kafka {@code Producer}, a Spring AMQP {@code Message}, a CloudEvent, a
* Micrometer {@code MeterRegistry}, an Avro {@code Schema}, a protobuf {@code Parser}, a Reactor
* {@code Mono}.
*
* <p>So the rule is one-directional and mechanical: a vendor library named in a public or protected
* signature is declared {@code api}; one used only behind private members stays {@code
* implementation}. {@code src/messaging/CLAUDE.md} states it as policy — this holds it to the
* source so the two cannot drift.
*
* <p>The libraries checked are the ones an adopter would otherwise have to reverse-engineer into
* their own build: broker clients, codec libraries, the metrics registry, the reactive facade.
* Spring Framework and Spring Boot are deliberately out of scope. They appear only inside the
* composition boundary, where the container constructs the types rather than an adopter naming
* them, and that boundary is where the family policy already confines them.
*/
class MessagingPublicSurfaceContractTest {
/**
* Package prefix to the Gradle coordinate that supplies it.
*
* <p>Prefixes rather than exact packages, because a library's types are spread across its own
* sub-packages and a consumer needs the whole artifact either way.
*/
private static final Map<String, String> VENDOR_LIBRARIES =
Map.of(
"org.apache.kafka", "org.apache.kafka:kafka-clients",
"org.springframework.amqp", "org.springframework.amqp:spring-rabbit",
"org.apache.avro", "org.apache.avro:avro",
"com.google.protobuf", "com.google.protobuf:protobuf-java",
"tools.jackson", "tools.jackson.core:jackson-databind",
"io.cloudevents", "io.cloudevents:cloudevents-api",
"io.micrometer", "io.micrometer:micrometer-core",
"reactor", "io.projectreactor:reactor-core",
"io.nats", "io.nats:jnats",
"org.apache.pulsar", "org.apache.pulsar:pulsar-client");
private static final Pattern IMPORT = Pattern.compile("(?m)^import\\s+(?:static\\s+)?([^;]+);");
private static final Pattern TYPE_KEYWORD =
Pattern.compile("\\b(class|interface|record|enum)\\b");
@Test
@DisplayName(
"a vendor type in a public signature has its library declared api, not implementation")
void vendorTypesInPublicSignaturesAreDeclaredApi() {
List<String> hidden = new ArrayList<>();
for (Path leaf : messagingLeaves()) {
String buildScript = read(leaf.resolve("build.gradle"));
for (String coordinate : exposedLibraries(leaf)) {
if (!declaresAsApi(buildScript, coordinate)) {
hidden.add(leaf.getFileName() + " exposes " + coordinate + " without declaring it api");
}
}
}
assertThat(hidden)
.as(
"each of these ships a public signature naming a type the consumer's compile classpath "
+ "does not contain; the method exists and cannot be called")
.isEmpty();
}
@Test
@DisplayName("the scan reaches the leaves it claims to check")
void theScanIsNotVacuous() {
List<Path> leaves = messagingLeaves();
assertThat(leaves)
.as("a scan that found no leaf would report every violation as absent")
.hasSizeGreaterThan(20);
assertThat(
exposedLibraries(
leaves.stream().filter(isNamed("messaging-kafka")).findFirst().orElseThrow()))
.as("the Kafka adapter's publish seam takes a Producer, so this is a positive control")
.contains("org.apache.kafka:kafka-clients");
assertThat(
exposedLibraries(
leaves.stream().filter(isNamed("messaging-schema-json")).findFirst().orElseThrow()))
.as("the JSON codec keeps its ObjectMapper private, so nothing is required of its build")
.isEmpty();
}
@Test
@DisplayName("an adopter of the starter does not compile against either broker client")
void neitherBrokerSdkReachesAnAdoptersCompileClasspath() {
Map<String, List<String>> exported = new LinkedHashMap<>();
for (Path leaf : messagingLeaves()) {
exported.put(
leaf.getFileName().toString(), apiDependenciesOf(read(leaf.resolve("build.gradle"))));
}
Set<String> reachable = apiClosure("messaging-spring-boot-starter", exported);
assertThat(reachable)
.as(
"an empty closure would satisfy the assertion below without proving anything; the "
+ "metrics registry and the reactive facade are exported on purpose")
.contains("io.micrometer:micrometer-core", "io.projectreactor:reactor-core");
assertThat(reachable)
.as(
"both adapters were exported, so every adopter compiled against two broker SDKs at "
+ "once and each adapter's conditional-on-class guard was true whatever the "
+ "deployment had chosen")
.doesNotContain("org.apache.kafka:kafka-clients", "org.springframework.amqp:spring-rabbit");
}
/** The vendor coordinates this leaf names in a public or protected signature. */
private static Set<String> exposedLibraries(Path leaf) {
Set<String> exposed = new TreeSet<>();
for (Path source : productionSources(leaf)) {
String text = read(source);
String declarations = declarationsOnly(text);
for (Map.Entry<String, String> library : VENDOR_LIBRARIES.entrySet()) {
if (isNamedInDeclarations(text, declarations, library.getKey())) {
exposed.add(library.getValue());
}
}
}
return exposed;
}
/**
* Whether a library's types survive into this file's declarations.
*
* <p>Two ways a type gets named: imported and used by its simple name, or written out in full.
* Both are checked, because the auto-configuration style in this repository uses fully qualified
* names for one-off types rather than adding an import.
*/
private static boolean isNamedInDeclarations(String source, String declarations, String prefix) {
if (declarations.contains(prefix + ".")) {
return true;
}
Matcher imports = IMPORT.matcher(source);
while (imports.find()) {
String imported = imports.group(1).trim();
if (!imported.startsWith(prefix + ".")) {
continue;
}
String simpleName = imported.substring(imported.lastIndexOf('.') + 1);
if (Pattern.compile("\\b" + Pattern.quote(simpleName) + "\\b").matcher(declarations).find()) {
return true;
}
}
return false;
}
/**
* Reduces a source file to its declarations: type headers, member signatures, record components.
*
* <p>Method bodies are dropped, because a vendor type used inside one is an implementation detail
* and is exactly the case that may stay {@code implementation}. Field initialisers are dropped
* for the same reason. Anything a {@code private} modifier reaches is dropped last: a private
* member is not a signature a consumer compiles against.
*
* <p>A brace walk rather than a parser. It only has to answer "is this text a declaration or a
* body", which brace depth settles, and a parser here would be more machinery than the question
* deserves.
*/
private static String declarationsOnly(String source) {
String text = stripCommentsAndLiterals(source);
StringBuilder kept = new StringBuilder();
StringBuilder pending = new StringBuilder();
int depth = 0;
int bodyDepth = -1;
int initializerDepth = -1;
for (int index = 0; index < text.length(); index++) {
char character = text.charAt(index);
if (character == '{') {
depth++;
if (initializerDepth >= 0) {
continue;
}
if (bodyDepth < 0) {
kept.append(pending).append(';');
if (!TYPE_KEYWORD.matcher(pending).find() && pending.indexOf("(") >= 0) {
bodyDepth = depth;
}
}
pending.setLength(0);
continue;
}
if (character == '}') {
if (bodyDepth == depth) {
bodyDepth = -1;
}
depth--;
pending.setLength(0);
continue;
}
if (character == ';') {
if (initializerDepth == depth) {
initializerDepth = -1;
} else if (bodyDepth < 0) {
kept.append(pending).append(';');
}
pending.setLength(0);
continue;
}
if (bodyDepth >= 0 || initializerDepth >= 0) {
continue;
}
if (character == '=' && isAssignment(text, index)) {
kept.append(pending).append(';');
pending.setLength(0);
initializerDepth = depth;
continue;
}
pending.append(character);
}
return Stream.of(kept.toString().split(";", -1))
.filter(fragment -> !fragment.contains("private "))
.filter(fragment -> !fragment.contains("import "))
.reduce("", (left, right) -> left + " ; " + right);
}
/** Distinguishes a field initialiser from {@code ==}, {@code <=}, {@code >=} and {@code !=}. */
private static boolean isAssignment(String text, int index) {
char before = index == 0 ? ' ' : text.charAt(index - 1);
char after = index + 1 >= text.length() ? ' ' : text.charAt(index + 1);
return before != '=' && before != '<' && before != '>' && before != '!' && after != '=';
}
private static String stripCommentsAndLiterals(String source) {
return source
.replaceAll("(?s)/\\*.*?\\*/", " ")
.replaceAll("(?m)//.*$", " ")
.replaceAll("\"\"\"(?s).*?\"\"\"", "\"\"")
.replaceAll("\"(\\\\.|[^\"\\\\])*\"", "\"\"")
.replaceAll("'(\\\\.|[^'\\\\])*'", "' '");
}
/** The external coordinates a build script exports to its consumers. */
private static List<String> apiDependenciesOf(String buildScript) {
List<String> exported = new ArrayList<>();
Matcher external = Pattern.compile("(?m)^\\s*api\\s+'([^']+)'").matcher(buildScript);
while (external.find()) {
String coordinate = external.group(1);
int lastColon = coordinate.lastIndexOf(':');
boolean versioned = lastColon > 0 && coordinate.indexOf(':') != lastColon;
exported.add(versioned ? coordinate.substring(0, lastColon) : coordinate);
}
Matcher projects =
Pattern.compile("(?m)^\\s*api\\s+project\\('([^']+)'\\)").matcher(buildScript);
while (projects.find()) {
String path = projects.group(1);
exported.add(path.substring(path.lastIndexOf(':') + 1));
}
return exported;
}
/** Everything a consumer of one leaf ends up compiling against. */
private static Set<String> apiClosure(String leaf, Map<String, List<String>> exported) {
Set<String> reachable = new TreeSet<>();
List<String> pending = new ArrayList<>(exported.getOrDefault(leaf, List.of()));
while (!pending.isEmpty()) {
String next = pending.remove(0);
if (!reachable.add(next)) {
continue;
}
pending.addAll(exported.getOrDefault(next, List.of()));
}
return reachable;
}
private static boolean declaresAsApi(String buildScript, String coordinate) {
return Pattern.compile("(?m)^\\s*api\\s+'" + Pattern.quote(coordinate) + "(:[^']*)?'")
.matcher(buildScript)
.find();
}
private static java.util.function.Predicate<Path> isNamed(String leaf) {
return path -> path.getFileName().toString().equals(leaf);
}
private static List<Path> messagingLeaves() {
Path family = repositoryRoot().resolve("src/messaging");
try (Stream<Path> children = Files.list(family)) {
return children
.filter(Files::isDirectory)
.filter(path -> Files.isRegularFile(path.resolve("build.gradle")))
.sorted()
.toList();
} catch (IOException unreadable) {
throw new UncheckedIOException(unreadable);
}
}
private static List<Path> productionSources(Path leaf) {
Path main = leaf.resolve("src/main/java");
if (!Files.isDirectory(main)) {
return List.of();
}
try (Stream<Path> walk = Files.walk(main)) {
return walk.filter(path -> path.toString().endsWith(".java")).sorted().toList();
} catch (IOException unreadable) {
throw new UncheckedIOException(unreadable);
}
}
private static String read(Path path) {
try {
return Files.readString(path);
} catch (IOException unreadable) {
throw new UncheckedIOException(unreadable);
}
}
private static Path repositoryRoot() {
Path candidate = Path.of("").toAbsolutePath();
while (candidate != null
&& !Files.isRegularFile(candidate.resolve("src/config/architecture/modules.json"))) {
candidate = candidate.getParent();
}
if (candidate == null) {
throw new IllegalStateException("the repository root is not above the working directory");
}
return candidate;
}
}