diff --git a/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md b/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md index 004528e..041a85a 100644 --- a/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md +++ b/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md @@ -29,7 +29,9 @@ production unapproved — because the remedy differs in each case. **Promotion evidence is per capability.** `GrpcAdvancedPromotionEvidence` is one record per capability, so no promotion can drag another along; `GrpcAdvancedPromotionGate.capabilitiesDraggedAlong` returns an empty list, and that is a tested -property rather than a claim. Two thresholds: seven days of soak plus complete evidence for +property rather than a claim. (2026-09-28: the gate classes were removed because nothing outside +their own tests called them — review 2026-09-24 S5-lead-4. The per-capability rule stands as a +review rule in `docs/runbooks/grpc-advanced-capabilities.md`.) Two thresholds: seven days of soak plus complete evidence for `ADVANCED_STABLE`, thirty for a Stable default, because the second means every deployment gets the capability's dependencies and its failure modes. diff --git a/docs/compatibility/grpc-support-matrix.md b/docs/compatibility/grpc-support-matrix.md index 0300565..525f33f 100644 --- a/docs/compatibility/grpc-support-matrix.md +++ b/docs/compatibility/grpc-support-matrix.md @@ -4,8 +4,10 @@ What the Stable gRPC platform (`:grpc:*`) is certified against, what it is only what is merely watched. The distinction is the point: "works with Spring Boot" is not a statement anyone can act on. -`GrpcCompatibilityMatrix.caSkeleton()` is the machine-readable form of this table, and -`GrpcStableReleaseGate` blocks a release when a certified lane has no result or a failing one. +The release gate is the `grpc-stable-release-gate` job in `.github/workflows/release.yml`: each +certified lane is a strict test lane that fails when it runs nothing. The in-code +`GrpcCompatibilityMatrix`/`GrpcStableReleaseGate` pair was removed (review 2026-09-24 S5-lead-4): +no production or build code called it, so it gated nothing. ## Lanes diff --git a/docs/runbooks/grpc-advanced-capabilities.md b/docs/runbooks/grpc-advanced-capabilities.md index 09d2c4d..a4b0b49 100644 --- a/docs/runbooks/grpc-advanced-capabilities.md +++ b/docs/runbooks/grpc-advanced-capabilities.md @@ -84,12 +84,11 @@ rather than retrying a failure. ## Promoting a capability -`GrpcAdvancedPromotionGate.evaluate` names every missing item. Promotion to `ADVANCED_STABLE` needs -compatibility evidence, a security review, fault evidence, performance evidence, an ADR, a runbook, a -real-environment test and seven days of soak. A Stable default needs thirty. - -Promotions are independent: promoting one capability changes no other's grade, and -`GrpcAdvancedSupportMatrix.apply` refuses a decision made against a different matrix state. +Promotion to `ADVANCED_STABLE` needs compatibility evidence, a security review, fault evidence, +performance evidence, an ADR, a runbook, a real-environment test and seven days of soak. A Stable +default needs thirty. Promotions are independent: promoting one capability changes no other's +grade. This is a review checklist; the in-code `GrpcAdvancedPromotionGate` that restated it was +removed (review 2026-09-24 S5-lead-4) because nothing but its own test called it. Before citing a suite as evidence, check that it ran against the real infrastructure it needs (proxy, container, control plane or toolchain). A suite that ran without it passed and established nothing. diff --git a/grpc-advanced/CLAUDE.md b/grpc-advanced/CLAUDE.md index c051e62..cf3a6d7 100644 --- a/grpc-advanced/CLAUDE.md +++ b/grpc-advanced/CLAUDE.md @@ -53,9 +53,10 @@ property key는 `ca-skeleton.grpc.advanced..enabled`이고 전부 ## Promotion은 capability별로 독립이다 -`GrpcAdvancedPromotionEvidence`는 capability마다 별도 레코드다. 공유 레코드였다면 하나를 승격할 때 -같은 시점에 측정된 다른 것들이 함께 승격된다. `GrpcAdvancedPromotionGate.capabilitiesDraggedAlong`이 -항상 빈 리스트인 것은 주석이 아니라 테스트되는 속성이다. +승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른 +것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고 +호출처가 없어 삭제했다(리뷰 2026-09-24 S5-lead-4). 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의 +리뷰 규칙이다. 승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가 더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다. diff --git a/grpc-advanced/grpc-advanced/src/main/java/dev/caskeleton/grpc/advanced/release/GrpcAdvancedPromotionDecision.java b/grpc-advanced/grpc-advanced/src/main/java/dev/caskeleton/grpc/advanced/release/GrpcAdvancedPromotionDecision.java deleted file mode 100644 index 9d4ef31..0000000 --- a/grpc-advanced/grpc-advanced/src/main/java/dev/caskeleton/grpc/advanced/release/GrpcAdvancedPromotionDecision.java +++ /dev/null @@ -1,50 +0,0 @@ -package dev.caskeleton.grpc.advanced.release; - -import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability; -import dev.caskeleton.grpc.advanced.bootstrap.GrpcCapabilityGrade; -import java.util.List; - -/** - * Whether one capability moves to a new grade. - * - *

Carries the grade it would move to as well as the blockers, so a refusal says what was being - * asked for. "Not promoted" is ambiguous between a failed promotion to Advanced Stable and a failed - * promotion to a Stable default, and the second is a much larger decision. - */ -public record GrpcAdvancedPromotionDecision( - GrpcAdvancedCapability capability, - GrpcCapabilityGrade from, - GrpcCapabilityGrade to, - boolean promoted, - List blockers) { - - /** Requires blockers exactly when refused. */ - public GrpcAdvancedPromotionDecision { - if (capability == null || from == null || to == null || blockers == null) { - throw new IllegalArgumentException( - "a promotion decision names its capability and both grades"); - } - blockers = List.copyOf(blockers); - if (promoted && !blockers.isEmpty()) { - throw new IllegalArgumentException("a granted promotion has no blockers"); - } - if (!promoted && blockers.isEmpty()) { - throw new IllegalArgumentException("a refused promotion says why"); - } - } - - /** A granted promotion. */ - public static GrpcAdvancedPromotionDecision grant( - GrpcAdvancedCapability capability, GrpcCapabilityGrade from, GrpcCapabilityGrade to) { - return new GrpcAdvancedPromotionDecision(capability, from, to, true, List.of()); - } - - /** A refused promotion. */ - public static GrpcAdvancedPromotionDecision refuse( - GrpcAdvancedCapability capability, - GrpcCapabilityGrade from, - GrpcCapabilityGrade to, - List blockers) { - return new GrpcAdvancedPromotionDecision(capability, from, to, false, blockers); - } -} diff --git a/grpc-advanced/grpc-advanced/src/main/java/dev/caskeleton/grpc/advanced/release/GrpcAdvancedPromotionEvidence.java b/grpc-advanced/grpc-advanced/src/main/java/dev/caskeleton/grpc/advanced/release/GrpcAdvancedPromotionEvidence.java deleted file mode 100644 index f5a81c2..0000000 --- a/grpc-advanced/grpc-advanced/src/main/java/dev/caskeleton/grpc/advanced/release/GrpcAdvancedPromotionEvidence.java +++ /dev/null @@ -1,75 +0,0 @@ -package dev.caskeleton.grpc.advanced.release; - -import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability; -import java.time.Duration; -import java.util.Set; - -/** - * What one capability has behind it. - * - *

Per capability, never shared. The Stable plan's requirement that Edition, streaming, xDS, - * gRPC-Web, Servlet and the language adapters do not gate each other only means something if their - * evidence is separate: a shared record makes promoting one of them promote whichever others - * happened to be measured at the same time. - */ -public record GrpcAdvancedPromotionEvidence( - GrpcAdvancedCapability capability, - boolean compatibilityEvidence, - boolean securityReview, - boolean faultEvidence, - boolean performanceEvidence, - Duration soakDuration, - boolean architectureDecisionRecord, - boolean runbook, - boolean realEnvironmentTest) { - - /** Requires a capability and a non-negative soak. */ - public GrpcAdvancedPromotionEvidence { - if (capability == null) { - throw new IllegalArgumentException("promotion evidence names its capability"); - } - if (soakDuration == null || soakDuration.isNegative()) { - throw new IllegalArgumentException("a soak duration must be present and non-negative"); - } - } - - /** No evidence at all, which is where a capability starts. */ - public static GrpcAdvancedPromotionEvidence none(GrpcAdvancedCapability capability) { - return new GrpcAdvancedPromotionEvidence( - capability, false, false, false, false, Duration.ZERO, false, false, false); - } - - /** Everything a promotion to Advanced Stable needs. */ - public static GrpcAdvancedPromotionEvidence complete( - GrpcAdvancedCapability capability, Duration soakDuration) { - return new GrpcAdvancedPromotionEvidence( - capability, true, true, true, true, soakDuration, true, true, true); - } - - /** Which required items are absent, as a set a report can print. */ - public Set missing() { - Set missing = new java.util.LinkedHashSet<>(); - if (!compatibilityEvidence) { - missing.add("compatibility evidence"); - } - if (!securityReview) { - missing.add("security review"); - } - if (!faultEvidence) { - missing.add("fault evidence"); - } - if (!performanceEvidence) { - missing.add("performance evidence"); - } - if (!architectureDecisionRecord) { - missing.add("architecture decision record"); - } - if (!runbook) { - missing.add("runbook"); - } - if (!realEnvironmentTest) { - missing.add("real environment test"); - } - return Set.copyOf(missing); - } -} diff --git a/grpc-advanced/grpc-advanced/src/main/java/dev/caskeleton/grpc/advanced/release/GrpcAdvancedPromotionGate.java b/grpc-advanced/grpc-advanced/src/main/java/dev/caskeleton/grpc/advanced/release/GrpcAdvancedPromotionGate.java deleted file mode 100644 index 3947536..0000000 --- a/grpc-advanced/grpc-advanced/src/main/java/dev/caskeleton/grpc/advanced/release/GrpcAdvancedPromotionGate.java +++ /dev/null @@ -1,85 +0,0 @@ -package dev.caskeleton.grpc.advanced.release; - -import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability; -import dev.caskeleton.grpc.advanced.bootstrap.GrpcCapabilityGrade; -import java.time.Duration; -import java.util.ArrayList; -import java.util.List; - -/** - * Decides one capability's promotion, on its own evidence. - * - *

Two thresholds rather than one. Reaching Advanced Stable means the capability works and is - * documented; becoming a Stable default means every deployment gets it, which additionally puts its - * dependencies on every classpath and its failure modes in every on-call rotation. The second needs - * the first plus a longer soak, because a capability that has run in one deployment for a week is - * not the same claim as one that ships to all of them. - */ -public final class GrpcAdvancedPromotionGate { - - /** The soak a promotion to Advanced Stable requires. */ - public static final Duration ADVANCED_STABLE_SOAK = Duration.ofDays(7); - - /** The soak a promotion to a Stable default requires. */ - public static final Duration STABLE_DEFAULT_SOAK = Duration.ofDays(30); - - private GrpcAdvancedPromotionGate() {} - - /** - * Whether {@code capability} may move from {@code from} to {@code to}. - * - * @throws IllegalArgumentException when the transition is not one this gate governs - */ - public static GrpcAdvancedPromotionDecision evaluate( - GrpcAdvancedPromotionEvidence evidence, GrpcCapabilityGrade from, GrpcCapabilityGrade to) { - if (evidence == null || from == null || to == null) { - throw new IllegalArgumentException("a promotion needs evidence and both grades"); - } - if (from == to) { - throw new IllegalArgumentException("a promotion changes the grade"); - } - GrpcAdvancedCapability capability = evidence.capability(); - List blockers = new ArrayList<>(); - - evidence.missing().stream() - .sorted() - .forEach(missing -> blockers.add(capability.flagName() + " has no " + missing)); - - Duration requiredSoak = - to == GrpcCapabilityGrade.ADVANCED_STABLE ? ADVANCED_STABLE_SOAK : STABLE_DEFAULT_SOAK; - if (evidence.soakDuration().compareTo(requiredSoak) < 0) { - blockers.add( - capability.flagName() - + " soaked for " - + evidence.soakDuration().toDays() - + " day(s); promotion to " - + to - + " requires " - + requiredSoak.toDays()); - } - if (from == GrpcCapabilityGrade.WATCH && to != GrpcCapabilityGrade.EXPERIMENTAL) { - blockers.add( - capability.flagName() - + " is WATCH, which is tracked rather than implemented; it becomes EXPERIMENTAL " - + "before anything else"); - } - return blockers.isEmpty() - ? GrpcAdvancedPromotionDecision.grant(capability, from, to) - : GrpcAdvancedPromotionDecision.refuse(capability, from, to, blockers); - } - - /** - * Whether promoting {@code promoted} would drag another capability with it. - * - *

Always empty, and the method exists so a test can assert that rather than a comment claiming - * it: each capability's evidence is its own record, so there is no path by which one promotion - * changes another's grade. - */ - public static List capabilitiesDraggedAlong( - GrpcAdvancedCapability promoted) { - if (promoted == null) { - throw new IllegalArgumentException("a capability is required"); - } - return List.of(); - } -} diff --git a/grpc-advanced/grpc-advanced/src/main/java/dev/caskeleton/grpc/advanced/release/GrpcAdvancedSupportMatrix.java b/grpc-advanced/grpc-advanced/src/main/java/dev/caskeleton/grpc/advanced/release/GrpcAdvancedSupportMatrix.java deleted file mode 100644 index 568e3ed..0000000 --- a/grpc-advanced/grpc-advanced/src/main/java/dev/caskeleton/grpc/advanced/release/GrpcAdvancedSupportMatrix.java +++ /dev/null @@ -1,66 +0,0 @@ -package dev.caskeleton.grpc.advanced.release; - -import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability; -import dev.caskeleton.grpc.advanced.bootstrap.GrpcCapabilityGrade; -import java.util.EnumMap; -import java.util.Map; - -/** - * Every advanced capability's current grade, in one place an adopter can read. - * - *

The published answer to "is this supported". Without it the answer is inferred from whether a - * class exists, which says only that somebody wrote it. - */ -public final class GrpcAdvancedSupportMatrix { - - private final Map grades = - new EnumMap<>(GrpcAdvancedCapability.class); - - /** A matrix at each capability's default grade. */ - public GrpcAdvancedSupportMatrix() { - for (GrpcAdvancedCapability capability : GrpcAdvancedCapability.values()) { - grades.put(capability, capability.defaultGrade()); - } - } - - /** The grade of one capability. */ - public GrpcCapabilityGrade gradeOf(GrpcAdvancedCapability capability) { - if (capability == null) { - throw new IllegalArgumentException("a capability is required"); - } - return grades.get(capability); - } - - /** - * Applies a granted promotion. - * - * @throws IllegalArgumentException when the decision's starting grade is not the current one, - * which means two promotions raced or one was replayed - */ - public GrpcAdvancedSupportMatrix apply(GrpcAdvancedPromotionDecision decision) { - if (decision == null) { - throw new IllegalArgumentException("a decision is required"); - } - if (!decision.promoted()) { - return this; - } - GrpcCapabilityGrade current = grades.get(decision.capability()); - if (current != decision.from()) { - throw new IllegalArgumentException( - "capability '" - + decision.capability().flagName() - + "' is " - + current - + ", not " - + decision.from() - + "; this decision was made against a different matrix"); - } - grades.put(decision.capability(), decision.to()); - return this; - } - - /** The whole matrix. */ - public Map snapshot() { - return Map.copyOf(grades); - } -} diff --git a/grpc-advanced/grpc-advanced/src/test/java/dev/caskeleton/grpc/advanced/release/GrpcAdvancedPromotionGateTest.java b/grpc-advanced/grpc-advanced/src/test/java/dev/caskeleton/grpc/advanced/release/GrpcAdvancedPromotionGateTest.java deleted file mode 100644 index ec80715..0000000 --- a/grpc-advanced/grpc-advanced/src/test/java/dev/caskeleton/grpc/advanced/release/GrpcAdvancedPromotionGateTest.java +++ /dev/null @@ -1,150 +0,0 @@ -package dev.caskeleton.grpc.advanced.release; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability; -import dev.caskeleton.grpc.advanced.bootstrap.GrpcCapabilityGrade; -import java.time.Duration; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -class GrpcAdvancedPromotionGateTest { - - @Test - @DisplayName("a capability with complete evidence and a full soak is promoted") - void completeEvidencePromotes() { - GrpcAdvancedPromotionDecision decision = - GrpcAdvancedPromotionGate.evaluate( - GrpcAdvancedPromotionEvidence.complete( - GrpcAdvancedCapability.HEDGING, Duration.ofDays(7)), - GrpcCapabilityGrade.EXPERIMENTAL, - GrpcCapabilityGrade.ADVANCED_STABLE); - - assertThat(decision.promoted()).isTrue(); - assertThat(decision.blockers()).isEmpty(); - } - - @Test - @DisplayName("every missing piece of evidence is named") - void everyMissingPieceIsNamed() { - GrpcAdvancedPromotionDecision decision = - GrpcAdvancedPromotionGate.evaluate( - GrpcAdvancedPromotionEvidence.none(GrpcAdvancedCapability.XDS), - GrpcCapabilityGrade.EXPERIMENTAL, - GrpcCapabilityGrade.ADVANCED_STABLE); - - assertThat(decision.blockers()) - .anySatisfy(blocker -> assertThat(blocker).contains("compatibility evidence")) - .anySatisfy(blocker -> assertThat(blocker).contains("security review")) - .anySatisfy(blocker -> assertThat(blocker).contains("fault evidence")) - .anySatisfy(blocker -> assertThat(blocker).contains("runbook")) - .anySatisfy(blocker -> assertThat(blocker).contains("real environment test")) - .anySatisfy(blocker -> assertThat(blocker).contains("soaked for")); - } - - @Test - @DisplayName("becoming a Stable default needs a longer soak than becoming Advanced Stable") - void theStableDefaultThresholdIsHigher() { - GrpcAdvancedPromotionEvidence weekLongSoak = - GrpcAdvancedPromotionEvidence.complete(GrpcAdvancedCapability.GRPC_WEB, Duration.ofDays(7)); - - assertThat( - GrpcAdvancedPromotionGate.evaluate( - weekLongSoak, - GrpcCapabilityGrade.EXPERIMENTAL, - GrpcCapabilityGrade.ADVANCED_STABLE) - .promoted()) - .isTrue(); - assertThat( - GrpcAdvancedPromotionGate.evaluate( - weekLongSoak, GrpcCapabilityGrade.ADVANCED_STABLE, GrpcCapabilityGrade.DISABLED) - .blockers()) - .anySatisfy(blocker -> assertThat(blocker).contains("requires 30")); - } - - @Test - @DisplayName("a WATCH capability becomes EXPERIMENTAL before anything else") - void watchPromotesOnlyToExperimental() { - assertThat( - GrpcAdvancedPromotionGate.evaluate( - GrpcAdvancedPromotionEvidence.complete( - GrpcAdvancedCapability.EDITION_2026, Duration.ofDays(60)), - GrpcCapabilityGrade.WATCH, - GrpcCapabilityGrade.ADVANCED_STABLE) - .blockers()) - .anySatisfy(blocker -> assertThat(blocker).contains("becomes EXPERIMENTAL")); - assertThat( - GrpcAdvancedPromotionGate.evaluate( - GrpcAdvancedPromotionEvidence.complete( - GrpcAdvancedCapability.EDITION_2026, Duration.ofDays(60)), - GrpcCapabilityGrade.WATCH, - GrpcCapabilityGrade.EXPERIMENTAL) - .promoted()) - .isTrue(); - } - - @Test - @DisplayName("promoting one capability drags none of the others with it") - void promotionsAreIndependent() { - GrpcAdvancedSupportMatrix matrix = new GrpcAdvancedSupportMatrix(); - GrpcCapabilityGrade webBefore = matrix.gradeOf(GrpcAdvancedCapability.GRPC_WEB); - - matrix.apply( - GrpcAdvancedPromotionGate.evaluate( - GrpcAdvancedPromotionEvidence.complete( - GrpcAdvancedCapability.HEDGING, Duration.ofDays(7)), - GrpcCapabilityGrade.EXPERIMENTAL, - GrpcCapabilityGrade.ADVANCED_STABLE)); - - assertThat(matrix.gradeOf(GrpcAdvancedCapability.HEDGING)) - .isEqualTo(GrpcCapabilityGrade.ADVANCED_STABLE); - assertThat(matrix.gradeOf(GrpcAdvancedCapability.GRPC_WEB)).isEqualTo(webBefore); - assertThat(GrpcAdvancedPromotionGate.capabilitiesDraggedAlong(GrpcAdvancedCapability.HEDGING)) - .isEmpty(); - } - - @Test - @DisplayName("a decision made against a different matrix state is refused") - void aStaleDecisionIsRefused() { - GrpcAdvancedSupportMatrix matrix = new GrpcAdvancedSupportMatrix(); - - assertThatThrownBy( - () -> - matrix.apply( - GrpcAdvancedPromotionGate.evaluate( - GrpcAdvancedPromotionEvidence.complete( - GrpcAdvancedCapability.GRPC_WEB, Duration.ofDays(7)), - GrpcCapabilityGrade.EXPERIMENTAL, - GrpcCapabilityGrade.ADVANCED_STABLE))) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("made against a different matrix"); - } - - @Test - @DisplayName("a refused promotion leaves the matrix alone") - void aRefusedPromotionChangesNothing() { - GrpcAdvancedSupportMatrix matrix = new GrpcAdvancedSupportMatrix(); - - matrix.apply( - GrpcAdvancedPromotionGate.evaluate( - GrpcAdvancedPromotionEvidence.none(GrpcAdvancedCapability.XDS), - GrpcCapabilityGrade.EXPERIMENTAL, - GrpcCapabilityGrade.ADVANCED_STABLE)); - - assertThat(matrix.gradeOf(GrpcAdvancedCapability.XDS)) - .isEqualTo(GrpcCapabilityGrade.EXPERIMENTAL); - } - - @Test - @DisplayName("a promotion that changes nothing is refused") - void aNoOpPromotionIsRefused() { - assertThatThrownBy( - () -> - GrpcAdvancedPromotionGate.evaluate( - GrpcAdvancedPromotionEvidence.none(GrpcAdvancedCapability.XDS), - GrpcCapabilityGrade.EXPERIMENTAL, - GrpcCapabilityGrade.EXPERIMENTAL)) - .isInstanceOf(IllegalArgumentException.class); - } -} diff --git a/grpc/grpc-testkit/src/main/java/dev/caskeleton/grpc/release/GrpcCompatibilityMatrix.java b/grpc/grpc-testkit/src/main/java/dev/caskeleton/grpc/release/GrpcCompatibilityMatrix.java deleted file mode 100644 index 4385302..0000000 --- a/grpc/grpc-testkit/src/main/java/dev/caskeleton/grpc/release/GrpcCompatibilityMatrix.java +++ /dev/null @@ -1,93 +0,0 @@ -package dev.caskeleton.grpc.release; - -import java.util.ArrayList; -import java.util.List; -import java.util.Map; - -/** - * Which combinations a release is certified against, and which are only watched. - * - *

The distinction is what keeps a support claim honest. "Works with Spring Boot" is not a - * statement anyone can act on; "certified on the managed Boot platform, compatibility-checked - * against an upstream gRPC override, and not run at all on Edition 2024" is. - */ -public record GrpcCompatibilityMatrix(Map lanes) { - - /** How much a combination has actually been exercised. */ - public enum Lane { - /** Run on every release. A failure blocks. */ - CERTIFIED(true), - /** Run, but a failure is reported rather than blocking. */ - COMPATIBILITY(false), - /** Recorded and not run. */ - WATCH(false); - - private final boolean blocking; - - Lane(boolean blocking) { - this.blocking = blocking; - } - - /** Whether a failure in this lane blocks a release. */ - public boolean blocking() { - return blocking; - } - } - - /** Copies the lane map. */ - public GrpcCompatibilityMatrix { - if (lanes == null || lanes.isEmpty()) { - throw new IllegalArgumentException("a compatibility matrix names at least one lane"); - } - lanes = Map.copyOf(lanes); - if (lanes.values().stream().noneMatch(Lane::blocking)) { - throw new IllegalArgumentException( - "a matrix with no certified lane certifies nothing; every combination is optional"); - } - } - - /** This repository's matrix. */ - public static GrpcCompatibilityMatrix caSkeleton() { - return new GrpcCompatibilityMatrix( - Map.of( - "boot-managed-platform", Lane.CERTIFIED, - "proto3-explicit-optional", Lane.CERTIFIED, - "netty-shaded", Lane.CERTIFIED, - "netty-unshaded", Lane.COMPATIBILITY, - "upstream-grpc-java-override", Lane.COMPATIBILITY, - "protobuf-edition-2024", Lane.WATCH, - "protobuf-edition-2026", Lane.WATCH)); - } - - /** The lanes whose failure blocks a release. */ - public List blockingLanes() { - return lanes.entrySet().stream() - .filter(entry -> entry.getValue().blocking()) - .map(Map.Entry::getKey) - .sorted() - .toList(); - } - - /** - * Every blocking lane that has no result. - * - * @return an empty list when every certified lane ran - */ - public List missingResults(Map laneResults) { - if (laneResults == null) { - throw new IllegalArgumentException("a lane result map is required"); - } - List missing = new ArrayList<>(); - blockingLanes() - .forEach( - lane -> { - Boolean passed = laneResults.get(lane); - if (passed == null) { - missing.add("certified lane '" + lane + "' produced no result"); - } else if (!passed) { - missing.add("certified lane '" + lane + "' failed"); - } - }); - return List.copyOf(missing); - } -} diff --git a/grpc/grpc-testkit/src/main/java/dev/caskeleton/grpc/release/GrpcReleaseDecision.java b/grpc/grpc-testkit/src/main/java/dev/caskeleton/grpc/release/GrpcReleaseDecision.java deleted file mode 100644 index 903ec41..0000000 --- a/grpc/grpc-testkit/src/main/java/dev/caskeleton/grpc/release/GrpcReleaseDecision.java +++ /dev/null @@ -1,42 +0,0 @@ -package dev.caskeleton.grpc.release; - -import java.util.List; - -/** - * Whether a Stable release may go out. - * - *

Blockers are a list rather than a boolean because a release conversation is about what is - * missing. "The gate failed" starts a search; "the fault lane did not run and the runbook is - * absent" starts the work. - */ -public record GrpcReleaseDecision(boolean approved, List blockers) { - - /** Requires blockers exactly when refused. */ - public GrpcReleaseDecision { - if (blockers == null) { - throw new IllegalArgumentException("a release decision lists its blockers, even when empty"); - } - blockers = List.copyOf(blockers); - if (approved && !blockers.isEmpty()) { - throw new IllegalArgumentException("an approved release has no blockers"); - } - if (!approved && blockers.isEmpty()) { - throw new IllegalArgumentException("a refused release says why"); - } - } - - /** - * An approved release. - * - *

Named {@code approve} rather than {@code approved}, which the record already uses for its - * accessor. - */ - public static GrpcReleaseDecision approve() { - return new GrpcReleaseDecision(true, List.of()); - } - - /** A refused release. */ - public static GrpcReleaseDecision refuse(List blockers) { - return new GrpcReleaseDecision(false, blockers); - } -} diff --git a/grpc/grpc-testkit/src/main/java/dev/caskeleton/grpc/release/GrpcReleaseEvidence.java b/grpc/grpc-testkit/src/main/java/dev/caskeleton/grpc/release/GrpcReleaseEvidence.java deleted file mode 100644 index 7161c12..0000000 --- a/grpc/grpc-testkit/src/main/java/dev/caskeleton/grpc/release/GrpcReleaseEvidence.java +++ /dev/null @@ -1,63 +0,0 @@ -package dev.caskeleton.grpc.release; - -import dev.caskeleton.grpc.testkit.GrpcEvidenceGrade; -import java.util.EnumSet; -import java.util.LinkedHashSet; -import java.util.Set; - -/** - * What a release actually has evidence for. - * - *

Graded, so a release cannot cite an in-process run as transport evidence. That substitution is - * the easiest one to make under time pressure and the hardest to spot afterwards: the suite name - * says "contract", the report says the platform is certified, and nothing in between records that - * no socket was opened. - */ -public record GrpcReleaseEvidence( - Set gradesRun, - Set certifiedCapabilities, - boolean runbookPresent, - boolean architectureDecisionRecordsPresent, - boolean supportMatrixPresent) { - - /** The grades a Stable release must have run. */ - private static final Set REQUIRED_GRADES = - EnumSet.of( - GrpcEvidenceGrade.CONTRACT, - GrpcEvidenceGrade.TRANSPORT, - GrpcEvidenceGrade.FAULT, - GrpcEvidenceGrade.PERFORMANCE); - - /** Copies both sets. */ - public GrpcReleaseEvidence { - if (gradesRun == null || certifiedCapabilities == null) { - throw new IllegalArgumentException("release evidence states what ran and what it certified"); - } - gradesRun = Set.copyOf(gradesRun); - certifiedCapabilities = Set.copyOf(certifiedCapabilities); - } - - /** The grades a Stable release requires. */ - public static Set requiredGrades() { - return Set.copyOf(REQUIRED_GRADES); - } - - /** The grades that were not run. */ - public Set missingGrades() { - Set missing = new LinkedHashSet<>(REQUIRED_GRADES); - missing.removeAll(gradesRun); - return Set.copyOf(missing); - } - - /** - * Whether {@code capability} is backed by a grade that can establish it. - * - *

The check the whole type exists for: a TLS claim needs a run that opened a socket. - */ - public boolean supports(String capability) { - if (!certifiedCapabilities.contains(capability)) { - return false; - } - return gradesRun.stream().anyMatch(grade -> grade.certifies().contains(capability)); - } -} diff --git a/grpc/grpc-testkit/src/main/java/dev/caskeleton/grpc/release/GrpcStableReleaseGate.java b/grpc/grpc-testkit/src/main/java/dev/caskeleton/grpc/release/GrpcStableReleaseGate.java deleted file mode 100644 index 14913cf..0000000 --- a/grpc/grpc-testkit/src/main/java/dev/caskeleton/grpc/release/GrpcStableReleaseGate.java +++ /dev/null @@ -1,94 +0,0 @@ -package dev.caskeleton.grpc.release; - -import dev.caskeleton.grpc.testkit.GrpcEvidenceGrade; -import java.util.ArrayList; -import java.util.List; -import java.util.Map; - -/** - * The last check before a Stable release: every lane ran, every grade is present, and the - * operational documents exist. - * - *

Documents are a blocker rather than a follow-up. A platform whose failure modes are {@code - * COMPLETION_UNKNOWN} and a stream that needs a full resync is a platform whose on-call has to be - * told what to do about them; shipping the behaviour and writing the runbook afterwards means the - * first person to meet it is the one who has to work it out at three in the morning. - */ -public final class GrpcStableReleaseGate { - - private final GrpcCompatibilityMatrix matrix; - - /** Binds the gate to its compatibility matrix. */ - public GrpcStableReleaseGate(GrpcCompatibilityMatrix matrix) { - if (matrix == null) { - throw new IllegalArgumentException("a release gate needs a compatibility matrix"); - } - this.matrix = matrix; - } - - /** - * The release decision. - * - * @param schemaBreakages what {@code buf breaking} reported against the released schema (the CI - * job {@code grpc-proto-buf}); empty when the schema is compatible - */ - public GrpcReleaseDecision evaluate( - GrpcReleaseEvidence evidence, - Map laneResults, - List schemaBreakages) { - if (evidence == null || laneResults == null || schemaBreakages == null) { - throw new IllegalArgumentException( - "a release decision needs evidence, lanes and the schema verdict"); - } - List blockers = new ArrayList<>(matrix.missingResults(laneResults)); - - evidence.missingGrades().stream() - .sorted() - .forEach( - grade -> - blockers.add( - grade - + " evidence was not produced; without it the release cannot claim " - + grade.certifies().stream().sorted().toList())); - - schemaBreakages.forEach(breakage -> blockers.add("schema: " + breakage)); - if (!evidence.runbookPresent()) { - blockers.add( - "the operations runbook is missing; COMPLETION_UNKNOWN and FULL_RESYNC_REQUIRED are " - + "states an on-call has to be told what to do about"); - } - if (!evidence.architectureDecisionRecordsPresent()) { - blockers.add("the architecture decision records are missing"); - } - if (!evidence.supportMatrixPresent()) { - blockers.add("the support matrix is missing, so no combination has a stated support level"); - } - return blockers.isEmpty() - ? GrpcReleaseDecision.approve() - : GrpcReleaseDecision.refuse(blockers); - } - - /** - * Whether a capability may be advertised as supported. - * - * @throws IllegalStateException when the evidence behind it is of the wrong grade - */ - public static void requireCertified(GrpcReleaseEvidence evidence, String capability) { - if (evidence == null) { - throw new IllegalArgumentException("release evidence is required"); - } - if (!evidence.supports(capability)) { - throw new IllegalStateException( - "capability '" - + capability - + "' is not certified by the evidence this release produced (" - + evidence.gradesRun().stream().map(GrpcEvidenceGrade::name).sorted().toList() - + ")"); - } - } - - /** The matrix in force. */ - public GrpcCompatibilityMatrix matrix() { - return matrix; - } -} diff --git a/grpc/grpc-testkit/src/test/java/dev/caskeleton/grpc/release/GrpcStableReleaseGateTest.java b/grpc/grpc-testkit/src/test/java/dev/caskeleton/grpc/release/GrpcStableReleaseGateTest.java deleted file mode 100644 index ad2be8d..0000000 --- a/grpc/grpc-testkit/src/test/java/dev/caskeleton/grpc/release/GrpcStableReleaseGateTest.java +++ /dev/null @@ -1,151 +0,0 @@ -package dev.caskeleton.grpc.release; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.grpc.testkit.GrpcEvidenceGrade; -import java.util.EnumSet; -import java.util.LinkedHashMap; -import java.util.List; -import java.util.Map; -import java.util.Set; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -class GrpcStableReleaseGateTest { - - private final GrpcStableReleaseGate gate = - new GrpcStableReleaseGate(GrpcCompatibilityMatrix.caSkeleton()); - - private static Map allLanesPassing() { - Map lanes = new LinkedHashMap<>(); - GrpcCompatibilityMatrix.caSkeleton().blockingLanes().forEach(lane -> lanes.put(lane, true)); - return lanes; - } - - private static GrpcReleaseEvidence completeEvidence() { - return new GrpcReleaseEvidence( - GrpcReleaseEvidence.requiredGrades(), - Set.of("tls", "http2", "interceptor-order", "completion-unknown", "latency"), - true, - true, - true); - } - - private static List schemaAllowed() { - return List.of(); - } - - @Test - @DisplayName("a release with every lane, grade and document approved goes out") - void aCompleteReleaseIsApproved() { - GrpcReleaseDecision decision = - gate.evaluate(completeEvidence(), allLanesPassing(), schemaAllowed()); - - assertThat(decision.approved()).isTrue(); - assertThat(decision.blockers()).isEmpty(); - } - - @Test - @DisplayName("a certified lane that did not run blocks the release") - void aMissingCertifiedLaneBlocks() { - Map missing = allLanesPassing(); - missing.remove("netty-shaded"); - - assertThat(gate.evaluate(completeEvidence(), missing, schemaAllowed()).blockers()) - .anySatisfy(blocker -> assertThat(blocker).contains("netty-shaded")); - } - - @Test - @DisplayName("a certified lane that failed blocks the release") - void aFailedCertifiedLaneBlocks() { - Map failed = allLanesPassing(); - failed.put("boot-managed-platform", false); - - assertThat(gate.evaluate(completeEvidence(), failed, schemaAllowed()).blockers()) - .anySatisfy(blocker -> assertThat(blocker).contains("boot-managed-platform")); - } - - @Test - @DisplayName("a watch lane's absence does not block") - void watchLanesDoNotBlock() { - assertThat(GrpcCompatibilityMatrix.caSkeleton().blockingLanes()) - .doesNotContain("protobuf-edition-2024", "protobuf-edition-2026"); - assertThat(GrpcCompatibilityMatrix.Lane.WATCH.blocking()).isFalse(); - assertThat(GrpcCompatibilityMatrix.Lane.COMPATIBILITY.blocking()).isFalse(); - assertThat(GrpcCompatibilityMatrix.Lane.CERTIFIED.blocking()).isTrue(); - } - - @Test - @DisplayName("a missing evidence grade blocks and says what it would have certified") - void aMissingGradeBlocks() { - GrpcReleaseEvidence noFaultLane = - new GrpcReleaseEvidence( - EnumSet.of( - GrpcEvidenceGrade.CONTRACT, - GrpcEvidenceGrade.TRANSPORT, - GrpcEvidenceGrade.PERFORMANCE), - Set.of("tls"), - true, - true, - true); - - assertThat(gate.evaluate(noFaultLane, allLanesPassing(), schemaAllowed()).blockers()) - .anySatisfy( - blocker -> assertThat(blocker).contains("FAULT").contains("completion-unknown")); - } - - @Test - @DisplayName("the operational documents are blockers, not follow-ups") - void missingDocumentsBlock() { - GrpcReleaseEvidence undocumented = - new GrpcReleaseEvidence( - GrpcReleaseEvidence.requiredGrades(), Set.of("tls"), false, false, false); - - assertThat(gate.evaluate(undocumented, allLanesPassing(), schemaAllowed()).blockers()) - .anySatisfy(blocker -> assertThat(blocker).contains("runbook")) - .anySatisfy(blocker -> assertThat(blocker).contains("architecture decision records")) - .anySatisfy(blocker -> assertThat(blocker).contains("support matrix")); - } - - @Test - @DisplayName("a schema that breaks a consumer blocks the release") - void aBrokenConsumerBlocks() { - List refused = - List.of( - "caskeleton/grpc/common/v1/stream.proto: Field \"3\" on message \"StreamEnvelope\" deleted."); - - assertThat(gate.evaluate(completeEvidence(), allLanesPassing(), refused).blockers()) - .anySatisfy(blocker -> assertThat(blocker).startsWith("schema:")); - } - - @Test - @DisplayName("a capability may not be advertised on evidence of the wrong grade") - void aCapabilityNeedsEvidenceOfTheRightGrade() { - GrpcReleaseEvidence contractOnly = - new GrpcReleaseEvidence( - EnumSet.of(GrpcEvidenceGrade.CONTRACT), - Set.of("tls", "interceptor-order"), - true, - true, - true); - - assertThat(contractOnly.supports("interceptor-order")).isTrue(); - assertThat(contractOnly.supports("tls")).isFalse(); - GrpcStableReleaseGate.requireCertified(contractOnly, "interceptor-order"); - assertThatThrownBy(() -> GrpcStableReleaseGate.requireCertified(contractOnly, "tls")) - .isInstanceOf(IllegalStateException.class) - .hasMessageContaining("not certified by the evidence"); - } - - @Test - @DisplayName("a matrix with no certified lane certifies nothing and is refused") - void aMatrixWithNoCertifiedLaneIsRefused() { - assertThatThrownBy( - () -> - new GrpcCompatibilityMatrix( - Map.of("everything", GrpcCompatibilityMatrix.Lane.WATCH))) - .isInstanceOf(IllegalArgumentException.class) - .hasMessageContaining("certifies nothing"); - } -}