refactor: 백엔드 리펙토링 진행 중
This commit is contained in:
@@ -29,7 +29,7 @@ All capabilities are off by default. Flags are `ca-skeleton.grpc.advanced.<capab
|
||||
| Custom load balancer | `custom-load-balancer` | `EXPERIMENTAL` | — |
|
||||
| Proxyless xDS | `xds` | `EXPERIMENTAL` | xDS control plane |
|
||||
| gRPC-Web | `grpc-web` | `ADVANCED_STABLE` | gRPC-Web proxy |
|
||||
| Servlet HTTP/2 | `servlet-compat` | `ADVANCED_STABLE` | Servlet container |
|
||||
| Servlet HTTP/2 | `servlet-compat` | `ADVANCED_STABLE` (flag only; no Servlet transport code since 2026-09-25) | Servlet container |
|
||||
| Spring Integration bridge | `integration-bridge` | `ADVANCED_STABLE` | — |
|
||||
| Reactor adapter | `reactor` | `ADVANCED_STABLE` | — |
|
||||
| Kotlin coroutine / Flow | `kotlin` | `ADVANCED_STABLE` | Kotlin toolchain |
|
||||
@@ -42,14 +42,12 @@ implemented and tested in this repository. What no capability has is evidence fr
|
||||
`GrpcAdvancedPromotionEvidence` for each one is empty, and no promotion has been granted.
|
||||
|
||||
**Four capabilities cannot produce meaningful evidence here at all**, because the infrastructure they
|
||||
need is absent. `GrpcAdvancedInfrastructureTestkit.missingInfrastructure` names them, and a suite that
|
||||
runs without its infrastructure passes and establishes nothing.
|
||||
need is absent (gRPC-Web proxy, Servlet container, xDS control plane, Kotlin toolchain), and a suite
|
||||
that runs without its infrastructure passes and establishes nothing.
|
||||
|
||||
**Kotlin is the sharpest case.** This repository has no Kotlin toolchain, so
|
||||
`GrpcKotlinCompatibilityGate.supportableHere()` returns false and always will until one exists. The
|
||||
four contract requirements — one schema source shared with Java, coroutine cancellation propagated,
|
||||
Flow backpressure inside the Stable buffer bounds, platform evidence types preserved — are checkable
|
||||
without a toolchain and are checked. The compile lane is not.
|
||||
**Kotlin is the sharpest case.** This repository has no Kotlin toolchain, so Kotlin is not
|
||||
supportable here until one exists. Only the Java-side coroutine cancellation bridge
|
||||
(`GrpcCoroutineContextBridge`) is implemented and tested; there is no compile lane.
|
||||
|
||||
## Promotion thresholds
|
||||
|
||||
|
||||
@@ -38,9 +38,9 @@ bound.
|
||||
3. `NO_SNAPSHOT_YET` on a starting instance means it never reached the control plane. It fails after
|
||||
the initial fetch timeout rather than starting with no routing.
|
||||
|
||||
**Do not** add application-level retry policy while xDS is enabled. `GrpcXdsStartupGuard` refuses it,
|
||||
because retry defined in two places has a winner that depends on resolution order rather than on a
|
||||
decision.
|
||||
**Do not** add application-level retry policy while xDS is enabled. `GrpcXdsProfile` refuses an
|
||||
`APPLICATION` retry owner, because retry defined in two places has a winner that depends on
|
||||
resolution order rather than on a decision.
|
||||
|
||||
---
|
||||
|
||||
@@ -52,17 +52,15 @@ the proxy did not expose. Check that the proxy's CORS `expose_headers` includes
|
||||
configuration in `envoy/envoy.yaml` shows it in place.
|
||||
|
||||
**If the method is client- or bidirectional-streaming**, it cannot work over gRPC-Web at all — a
|
||||
browser has no way to send a stream of messages. `GrpcWebCompatibilityGate` reports such a method
|
||||
before it is exposed.
|
||||
browser has no way to send a stream of messages. `GrpcWebRpcSupport.require` refuses such a method.
|
||||
|
||||
---
|
||||
|
||||
## Servlet: a transport setting appears to be ignored
|
||||
|
||||
It is ignored. The container owns the socket, so keepalive tuning, maximum connection age and
|
||||
flow-control window tuning belong to it. `GrpcServletStartupValidator` refuses those settings at
|
||||
startup rather than accepting and dropping them, because a setting that is silently ignored sends the
|
||||
investigation somewhere else.
|
||||
flow-control window tuning belong to it. This repository has no Servlet transport code that would
|
||||
refuse them, so configure them on the container.
|
||||
|
||||
A Servlet run never substitutes for Netty certification.
|
||||
|
||||
@@ -93,6 +91,5 @@ 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.
|
||||
|
||||
Before citing a suite as evidence, check `GrpcAdvancedInfrastructureTestkit.missingInfrastructure`.
|
||||
A suite that ran without the proxy, the container, the control plane or the toolchain it needs passed
|
||||
and established nothing.
|
||||
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.
|
||||
|
||||
@@ -16,8 +16,7 @@ grpc:* → grpc-advanced:* (금지 — registry가 거부한다)
|
||||
```
|
||||
|
||||
`grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다.
|
||||
`verifyCleanArchitectureDependencies`가 build time에, `GrpcStableBuildInvariant`와
|
||||
`GrpcAdvancedModuleGuard.requireStableStarterIsClean`이 runtime에 같은 규칙을 강제한다.
|
||||
`verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다.
|
||||
|
||||
## Capability grade와 feature flag
|
||||
|
||||
@@ -44,8 +43,8 @@ property key는 `ca-skeleton.grpc.advanced.<capability>.enabled`이고 전부
|
||||
| `grpc-advanced-edition` | Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane |
|
||||
| `grpc-advanced-streaming` | client streaming(session/dedup/checkpoint), bidi(dual sequence), manual flow control |
|
||||
| `grpc-advanced-resilience` | read-only hedging, custom name resolver SPI, custom load balancer SPI, proxyless xDS |
|
||||
| `grpc-advanced-compat` | gRPC-Web, Servlet HTTP/2, Spring Integration bridge, Reactor adapter, Kotlin 경계 |
|
||||
| `grpc-advanced-diagnostics` | Channelz/CSDS 진단, advanced infrastructure testkit 요구사항 |
|
||||
| `grpc-advanced-compat` | gRPC-Web, Spring Integration bridge, Reactor adapter, Kotlin coroutine 취소 bridge |
|
||||
| `grpc-advanced-diagnostics` | Channelz/CSDS 진단 |
|
||||
|
||||
## Promotion은 capability별로 독립이다
|
||||
|
||||
@@ -58,20 +57,20 @@ property key는 `ca-skeleton.grpc.advanced.<capability>.enabled`이고 전부
|
||||
|
||||
## 이 저장소에서 검증할 수 없는 것
|
||||
|
||||
`GrpcAdvancedInfrastructureTestkit`이 capability별로 필요한 실제 인프라를 명시한다.
|
||||
capability별로 필요한 실제 인프라가 이 저장소에 없다.
|
||||
|
||||
- `grpc-web` → gRPC-Web 프록시
|
||||
- `servlet-compat` → Servlet 컨테이너
|
||||
- `xds` → 중지 가능한 xDS control plane
|
||||
- `kotlin` → Kotlin 툴체인 (**이 저장소에 없다**)
|
||||
- `kotlin` → Kotlin 툴체인
|
||||
|
||||
인프라 없이 도는 suite는 통과하면서 아무것도 증명하지 않으므로, suite가 없는 것보다 나쁘다.
|
||||
`GrpcKotlinCompatibilityGate.supportableHere()`가 `false`를 반환하는 것은 그 사실의 코드 표현이다 —
|
||||
Kotlin 계약 요구사항 4개는 검증되지만 compile lane은 존재하지 않는다.
|
||||
이 사실을 상수로 반환하던 gate 클래스(`GrpcKotlinCompatibilityGate`, `GrpcAdvancedInfrastructureTestkit`
|
||||
등)는 2026-09-25 삭제됐다 — 지원 여부는 이 문서와 support matrix가 적는다.
|
||||
|
||||
## 금지
|
||||
|
||||
- Stable leaf(`grpc:*`)가 이 family를 참조하는 것.
|
||||
- capability grade 없이, 또는 flag 없이 advanced 코드 경로를 실행하는 것.
|
||||
- `WATCH` capability를 스키마 소스로 사용하는 것 (`GrpcEdition2026Guard`가 무조건 거부한다).
|
||||
- `WATCH` capability를 스키마 소스로 사용하는 것.
|
||||
- 실제 인프라 없이 실행한 suite를 promotion evidence로 인용하는 것.
|
||||
|
||||
-20
@@ -1,9 +1,5 @@
|
||||
package dev.caskeleton.grpc.advanced.bootstrap;
|
||||
|
||||
import dev.caskeleton.grpc.core.GrpcStableBuildInvariant;
|
||||
import dev.caskeleton.grpc.core.GrpcStableModuleCatalog;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* The single gate every advanced capability passes through.
|
||||
*
|
||||
@@ -65,20 +61,4 @@ public final class GrpcAdvancedModuleGuard {
|
||||
+ "that somebody accepted its uncharacterised failure modes");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Fails when the Stable starter's dependency set reaches an advanced module.
|
||||
*
|
||||
* <p>The same invariant the registry enforces at build time, asserted here so a runtime that was
|
||||
* assembled some other way — a fat jar, a shaded artifact, a test harness — is checked too.
|
||||
*/
|
||||
public static void requireStableStarterIsClean(Set<String> starterDependencies) {
|
||||
GrpcStableBuildInvariant.requireNoAdvancedDependency(
|
||||
"grpc-spring-boot-starter", starterDependencies);
|
||||
}
|
||||
|
||||
/** The advanced module ids, for a runtime classpath check. */
|
||||
public static Set<String> advancedModules() {
|
||||
return GrpcStableModuleCatalog.advancedModules();
|
||||
}
|
||||
}
|
||||
|
||||
-15
@@ -89,21 +89,6 @@ class GrpcAdvancedModuleGuardTest {
|
||||
GrpcAdvancedModuleGuard.require(flags, GrpcAdvancedCapability.HEDGING);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the Stable starter reaching an advanced module is refused")
|
||||
void theStableStarterMayNotReachAnAdvancedModule() {
|
||||
GrpcAdvancedModuleGuard.requireStableStarterIsClean(Set.of("grpc-core-api", "grpc-policy"));
|
||||
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
GrpcAdvancedModuleGuard.requireStableStarterIsClean(
|
||||
Set.of("grpc-core-api", "grpc-advanced-resilience")))
|
||||
.isInstanceOf(IllegalStateException.class)
|
||||
.hasMessageContaining("grpc-advanced-resilience");
|
||||
assertThat(GrpcAdvancedModuleGuard.advancedModules())
|
||||
.contains("grpc-advanced-bootstrap", "grpc-advanced-streaming", "grpc-advanced-compat");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("only flagged and permitted capabilities appear as active")
|
||||
void activeReflectsBothFlagAndGrade() {
|
||||
|
||||
@@ -2,14 +2,11 @@ plugins {
|
||||
id 'ca.platform-module'
|
||||
}
|
||||
|
||||
// Compatibility bridges: gRPC-Web, the Servlet HTTP/2 profile, the Spring Integration bridge, the
|
||||
// Reactor adapter, and the Kotlin coroutine/Flow boundary.
|
||||
// Compatibility bridges: gRPC-Web, the Spring Integration bridge, the Reactor adapter, and the
|
||||
// Kotlin coroutine cancellation bridge.
|
||||
//
|
||||
// No Kotlin source set (adaptation D7): this repository has no Kotlin toolchain, so the Kotlin lane
|
||||
// is expressed as a Java-side boundary contract whose compatibility gate fails closed until a real
|
||||
// toolchain lane exists. Everything the gate would otherwise assert — one schema source, coroutine
|
||||
// cancellation propagation, Flow backpressure inside the Stable buffer limits, evidence type
|
||||
// preservation — is a checkable contract without it.
|
||||
// No Kotlin source set (adaptation D7): this repository has no Kotlin toolchain, so the Kotlin side
|
||||
// is only the Java-side cancellation bridge; nothing here claims Kotlin support.
|
||||
dependencies {
|
||||
api project(':grpc:grpc-core-api')
|
||||
api project(':grpc:grpc-policy')
|
||||
|
||||
-69
@@ -1,69 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.kotlin;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Whether a Kotlin adapter may be advertised as supported.
|
||||
*
|
||||
* <p>Fails closed in this repository, and says so rather than reporting a pass it cannot justify.
|
||||
* There is no Kotlin toolchain here (adaptation design D7), so the compile lane that would
|
||||
* establish the last requirement has never run; a gate that reported success anyway would put an
|
||||
* unverified claim in the support matrix.
|
||||
*
|
||||
* <p>The other four requirements are checkable and are checked, so turning the toolchain on later
|
||||
* is a lane to add rather than a contract to write.
|
||||
*/
|
||||
public final class GrpcKotlinCompatibilityGate {
|
||||
|
||||
private GrpcKotlinCompatibilityGate() {}
|
||||
|
||||
/**
|
||||
* Every reason a Kotlin adapter is not yet supportable.
|
||||
*
|
||||
* @param toolchainLaneRan whether a Kotlin compile lane actually ran against this profile
|
||||
* @return an empty list only when the profile is complete and its lane has run
|
||||
*/
|
||||
public static List<String> blockers(GrpcKotlinProfile profile, boolean toolchainLaneRan) {
|
||||
if (profile == null) {
|
||||
throw new IllegalArgumentException("a Kotlin profile is required");
|
||||
}
|
||||
List<String> blockers = new ArrayList<>();
|
||||
if (!profile.sharesSchemaSourceWithJava()) {
|
||||
blockers.add(
|
||||
"the Kotlin contract does not share one schema source with the Java contract; two "
|
||||
+ "sources diverge where only somebody reading both would notice");
|
||||
}
|
||||
if (!profile.propagatesCoroutineCancellation()) {
|
||||
blockers.add(
|
||||
"coroutine cancellation does not reach the gRPC call; a cancelled scope would leave the "
|
||||
+ "call running");
|
||||
}
|
||||
if (!profile.respectsStableFlowControl()) {
|
||||
blockers.add(
|
||||
"Flow backpressure bypasses the Stable buffer bounds; a slow collector would buffer "
|
||||
+ "without a limit rather than terminating the stream");
|
||||
}
|
||||
if (!profile.preservesPlatformEvidenceTypes()) {
|
||||
blockers.add(
|
||||
"the adapter does not preserve the platform's evidence, status and deadline types; a "
|
||||
+ "Kotlin-idiomatic re-creation is a second model of the same facts");
|
||||
}
|
||||
if (!toolchainLaneRan) {
|
||||
blockers.add(
|
||||
"no Kotlin toolchain lane has run against "
|
||||
+ profile.kotlinToolchainVersion()
|
||||
+ "; this repository has no Kotlin toolchain, so the compile evidence does not exist");
|
||||
}
|
||||
return List.copyOf(blockers);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether the Kotlin adapter is supportable in this repository as it stands.
|
||||
*
|
||||
* <p>False. The four contract requirements can be satisfied; the toolchain lane cannot.
|
||||
*/
|
||||
public static boolean supportableHere() {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
-35
@@ -1,35 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.kotlin;
|
||||
|
||||
/**
|
||||
* How a Kotlin adapter must behave, stated from the Java side.
|
||||
*
|
||||
* <p>Java-side because this repository has no Kotlin toolchain (adaptation design D7). What can be
|
||||
* expressed without one is every rule that constrains the adapter: one schema source shared with
|
||||
* the Java contract, coroutine cancellation propagated to the call, Flow backpressure inside the
|
||||
* Stable buffer bounds, and the platform's evidence and status types preserved rather than
|
||||
* re-created in Kotlin idiom.
|
||||
*
|
||||
* <p>Each is a component so the gate can check them individually. A single "compatible" flag would
|
||||
* let a partially compliant adapter through, and the most likely partial failure — a Flow that
|
||||
* buffers without a bound — is the one with the worst production behaviour.
|
||||
*/
|
||||
public record GrpcKotlinProfile(
|
||||
boolean sharesSchemaSourceWithJava,
|
||||
boolean propagatesCoroutineCancellation,
|
||||
boolean respectsStableFlowControl,
|
||||
boolean preservesPlatformEvidenceTypes,
|
||||
String kotlinToolchainVersion) {
|
||||
|
||||
/** Refuses a profile that claims support without naming a toolchain. */
|
||||
public GrpcKotlinProfile {
|
||||
if (kotlinToolchainVersion == null || kotlinToolchainVersion.isBlank()) {
|
||||
throw new IllegalArgumentException(
|
||||
"a Kotlin profile names the toolchain it was verified against; 'Kotlin' is not a version");
|
||||
}
|
||||
}
|
||||
|
||||
/** A profile for a toolchain this repository has not verified. */
|
||||
public static GrpcKotlinProfile unverified(String kotlinToolchainVersion) {
|
||||
return new GrpcKotlinProfile(false, false, false, false, kotlinToolchainVersion);
|
||||
}
|
||||
}
|
||||
-50
@@ -1,50 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.servlet;
|
||||
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* What a Servlet container can and cannot do compared with Netty.
|
||||
*
|
||||
* <p>The gaps are not incidental. A Servlet container owns the socket, so everything below the
|
||||
* request abstraction belongs to it: keepalive, connection age, and the flow-control window are the
|
||||
* container's settings, not gRPC's. Naming them is what stops a deployment from configuring a
|
||||
* keepalive that is silently ignored and concluding the client is at fault.
|
||||
*/
|
||||
public enum GrpcServletCapabilityMatrix {
|
||||
/** HTTP/2 request and response. Available. */
|
||||
HTTP2(true),
|
||||
/** TLS. Available, terminated by the container. */
|
||||
TLS(true),
|
||||
/** Inbound message and metadata limits. Available. */
|
||||
MESSAGE_LIMITS(true),
|
||||
/** The standard health service. Available. */
|
||||
HEALTH(true),
|
||||
/** Server reflection. Available. */
|
||||
REFLECTION(true),
|
||||
/** Graceful shutdown. Available through the container's lifecycle. */
|
||||
GRACEFUL_SHUTDOWN(true),
|
||||
/** gRPC-level keepalive tuning. The container owns the connection. */
|
||||
KEEPALIVE_TUNING(false),
|
||||
/** Maximum connection age. The container owns the connection. */
|
||||
MAX_CONNECTION_AGE(false),
|
||||
/** HTTP/2 flow-control window tuning. The container owns the transport. */
|
||||
FLOW_CONTROL_WINDOW_TUNING(false);
|
||||
|
||||
private final boolean available;
|
||||
|
||||
GrpcServletCapabilityMatrix(boolean available) {
|
||||
this.available = available;
|
||||
}
|
||||
|
||||
/** Whether the Servlet transport provides this. */
|
||||
public boolean available() {
|
||||
return available;
|
||||
}
|
||||
|
||||
/** Everything the Servlet transport cannot do. */
|
||||
public static Set<GrpcServletCapabilityMatrix> unavailable() {
|
||||
return java.util.Arrays.stream(values())
|
||||
.filter(capability -> !capability.available())
|
||||
.collect(java.util.stream.Collectors.toUnmodifiableSet());
|
||||
}
|
||||
}
|
||||
-51
@@ -1,51 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.servlet;
|
||||
|
||||
import dev.caskeleton.grpc.server.GrpcServerTransport;
|
||||
|
||||
/**
|
||||
* A deployment that serves gRPC from its Servlet container, on the web server's own port.
|
||||
*
|
||||
* <p>Attractive because it is one port, one TLS configuration and one lifecycle. The cost is that
|
||||
* the container owns the transport, so the Netty settings a Stable profile carries have no effect —
|
||||
* and this profile refuses to pretend otherwise.
|
||||
*
|
||||
* <p>Its evidence never counts as Netty certification. A suite that passes here has established
|
||||
* that the container serves gRPC, not that the platform's Netty profile is correct.
|
||||
*/
|
||||
public record GrpcServletCompatibilityProfile(
|
||||
String contextPath, boolean containerOwnsTls, boolean asyncSupported) {
|
||||
|
||||
/** Refuses a configuration the container cannot honour. */
|
||||
public GrpcServletCompatibilityProfile {
|
||||
if (contextPath == null || !contextPath.startsWith("/")) {
|
||||
throw new IllegalArgumentException(
|
||||
"a servlet profile needs a context path starting with '/'");
|
||||
}
|
||||
if (!asyncSupported) {
|
||||
throw new IllegalArgumentException(
|
||||
"gRPC over Servlet requires async support; without it every streaming call blocks a "
|
||||
+ "container thread for its lifetime");
|
||||
}
|
||||
if (!containerOwnsTls) {
|
||||
throw new IllegalArgumentException(
|
||||
"the container owns the socket, so it owns TLS; a profile that claims otherwise "
|
||||
+ "configures a setting nothing reads");
|
||||
}
|
||||
}
|
||||
|
||||
/** The transport this profile runs on. */
|
||||
public GrpcServerTransport transport() {
|
||||
return GrpcServerTransport.SERVLET;
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether a run under this profile certifies the platform's Netty transport.
|
||||
*
|
||||
* <p>Always false. The container's HTTP/2 is real, but it is the container's: its keepalive, its
|
||||
* connection age and its flow-control window. Stable certification is a statement about the
|
||||
* platform's own Netty profile, and a Servlet run establishes nothing about it.
|
||||
*/
|
||||
public boolean certifiesNettyTransport() {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
-51
@@ -1,51 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.servlet;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* Refuses a Servlet deployment that asks for something the container will not do.
|
||||
*
|
||||
* <p>Refuses rather than warns, because the setting would otherwise be accepted and ignored. A
|
||||
* keepalive configured on a Servlet deployment does nothing, the connections behave as the
|
||||
* container decides, and the investigation starts from the assumption that the setting is in force.
|
||||
*/
|
||||
public final class GrpcServletStartupValidator {
|
||||
|
||||
private GrpcServletStartupValidator() {}
|
||||
|
||||
/**
|
||||
* Every requested capability the Servlet transport cannot provide.
|
||||
*
|
||||
* @param requestedCapabilities the transport settings the deployment configured
|
||||
* @return an empty list when everything requested is available
|
||||
*/
|
||||
public static List<String> violations(
|
||||
GrpcServletCompatibilityProfile profile,
|
||||
Set<GrpcServletCapabilityMatrix> requestedCapabilities) {
|
||||
if (profile == null || requestedCapabilities == null) {
|
||||
throw new IllegalArgumentException("validation needs the profile and the requested set");
|
||||
}
|
||||
List<String> violations = new ArrayList<>();
|
||||
requestedCapabilities.stream()
|
||||
.filter(capability -> !capability.available())
|
||||
.sorted()
|
||||
.forEach(
|
||||
capability ->
|
||||
violations.add(
|
||||
capability
|
||||
+ " is not available on the Servlet transport; the container owns the "
|
||||
+ "connection, so this setting would be accepted and ignored"));
|
||||
return List.copyOf(violations);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether a Servlet run may stand in for Netty certification.
|
||||
*
|
||||
* <p>Always false.
|
||||
*/
|
||||
public static boolean substitutesForNettyCertification() {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
-56
@@ -1,56 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.web;
|
||||
|
||||
import dev.caskeleton.grpc.core.GrpcMethodName;
|
||||
import dev.caskeleton.grpc.core.RpcType;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* Checks that everything exposed to browsers can actually be served to them, on the same schema as
|
||||
* the native clients.
|
||||
*
|
||||
* <p>The same schema is the point. Two schemas — one for browsers, one for services — is how a
|
||||
* field ends up meaning something different depending on which client asked, and the divergence is
|
||||
* only visible to whoever reads both files.
|
||||
*/
|
||||
public final class GrpcWebCompatibilityGate {
|
||||
|
||||
private GrpcWebCompatibilityGate() {}
|
||||
|
||||
/**
|
||||
* Every method this profile could not serve.
|
||||
*
|
||||
* @param exposedMethods the methods a browser is meant to be able to call
|
||||
* @return an empty list when every exposed method is servable
|
||||
*/
|
||||
public static List<String> violations(Map<GrpcMethodName, RpcType> exposedMethods) {
|
||||
if (exposedMethods == null) {
|
||||
throw new IllegalArgumentException("an exposed method map is required");
|
||||
}
|
||||
List<String> violations = new ArrayList<>();
|
||||
exposedMethods.entrySet().stream()
|
||||
.sorted(java.util.Comparator.comparing(entry -> entry.getKey().canonical()))
|
||||
.forEach(
|
||||
entry -> {
|
||||
if (!GrpcWebRpcSupport.supported(entry.getValue())) {
|
||||
violations.add(
|
||||
"method '"
|
||||
+ entry.getKey().canonical()
|
||||
+ "' is "
|
||||
+ entry.getValue()
|
||||
+ ", which gRPC-Web cannot carry");
|
||||
}
|
||||
});
|
||||
return List.copyOf(violations);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether the browser and native suites must run against one schema.
|
||||
*
|
||||
* <p>Always true. Stated as a method so the property is asserted rather than described.
|
||||
*/
|
||||
public static boolean sharesOneSchemaWithNativeClients() {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
+1
-34
@@ -4,8 +4,6 @@ import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.kotlin.GrpcCoroutineContextBridge;
|
||||
import dev.caskeleton.grpc.advanced.kotlin.GrpcKotlinCompatibilityGate;
|
||||
import dev.caskeleton.grpc.advanced.kotlin.GrpcKotlinProfile;
|
||||
import dev.caskeleton.grpc.api.deadline.GrpcCancellationToken;
|
||||
import dev.caskeleton.grpc.deadline.GrpcCancellationCoordinator;
|
||||
import dev.caskeleton.grpc.deadline.GrpcCancellationReason;
|
||||
@@ -14,41 +12,10 @@ import java.util.concurrent.atomic.AtomicBoolean;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcKotlinCompatibilityGateTest {
|
||||
class GrpcCoroutineContextBridgeTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-08-30T10:00:00Z");
|
||||
|
||||
@Test
|
||||
@DisplayName("the Kotlin adapter fails closed here, and says which lane is missing")
|
||||
void theGateFailsClosed() {
|
||||
GrpcKotlinProfile complete = new GrpcKotlinProfile(true, true, true, true, "2.1.0");
|
||||
|
||||
assertThat(GrpcKotlinCompatibilityGate.blockers(complete, false))
|
||||
.singleElement()
|
||||
.satisfies(blocker -> assertThat(blocker).contains("no Kotlin toolchain"));
|
||||
assertThat(GrpcKotlinCompatibilityGate.blockers(complete, true)).isEmpty();
|
||||
assertThat(GrpcKotlinCompatibilityGate.supportableHere()).isFalse();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("each Kotlin contract requirement is checked on its own")
|
||||
void eachRequirementIsCheckedSeparately() {
|
||||
assertThat(GrpcKotlinCompatibilityGate.blockers(GrpcKotlinProfile.unverified("2.1.0"), true))
|
||||
.hasSize(4)
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("one schema source"))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("cancelled scope"))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("buffer without a limit"))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("second model of the same facts"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a profile that claims support without naming a toolchain is refused")
|
||||
void aProfileNamesItsToolchain() {
|
||||
assertThatThrownBy(() -> GrpcKotlinProfile.unverified(" "))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("not a version");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("coroutine cancellation reaches the platform, and the platform reaches the scope")
|
||||
void cancellationCrossesBothWays() {
|
||||
-79
@@ -1,79 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.compat;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.servlet.GrpcServletCapabilityMatrix;
|
||||
import dev.caskeleton.grpc.advanced.servlet.GrpcServletCompatibilityProfile;
|
||||
import dev.caskeleton.grpc.advanced.servlet.GrpcServletStartupValidator;
|
||||
import dev.caskeleton.grpc.server.GrpcServerTransport;
|
||||
import java.util.Set;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcServletStartupValidatorTest {
|
||||
|
||||
private static final GrpcServletCompatibilityProfile PROFILE =
|
||||
new GrpcServletCompatibilityProfile("/grpc", true, true);
|
||||
|
||||
@Test
|
||||
@DisplayName("the Servlet transport names what it cannot do")
|
||||
void theMatrixNamesItsGaps() {
|
||||
assertThat(GrpcServletCapabilityMatrix.unavailable())
|
||||
.containsExactlyInAnyOrder(
|
||||
GrpcServletCapabilityMatrix.KEEPALIVE_TUNING,
|
||||
GrpcServletCapabilityMatrix.MAX_CONNECTION_AGE,
|
||||
GrpcServletCapabilityMatrix.FLOW_CONTROL_WINDOW_TUNING);
|
||||
assertThat(GrpcServletCapabilityMatrix.HTTP2.available()).isTrue();
|
||||
assertThat(GrpcServletCapabilityMatrix.GRACEFUL_SHUTDOWN.available()).isTrue();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a deployment asking for a Netty-only setting is refused, not warned")
|
||||
void aNettyOnlySettingIsRefused() {
|
||||
assertThat(
|
||||
GrpcServletStartupValidator.violations(
|
||||
PROFILE, Set.of(GrpcServletCapabilityMatrix.KEEPALIVE_TUNING)))
|
||||
.singleElement()
|
||||
.satisfies(violation -> assertThat(violation).contains("accepted and ignored"));
|
||||
assertThat(
|
||||
GrpcServletStartupValidator.violations(
|
||||
PROFILE,
|
||||
Set.of(
|
||||
GrpcServletCapabilityMatrix.KEEPALIVE_TUNING,
|
||||
GrpcServletCapabilityMatrix.MAX_CONNECTION_AGE)))
|
||||
.hasSize(2);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an available capability passes")
|
||||
void anAvailableCapabilityPasses() {
|
||||
assertThat(
|
||||
GrpcServletStartupValidator.violations(
|
||||
PROFILE,
|
||||
Set.of(GrpcServletCapabilityMatrix.HTTP2, GrpcServletCapabilityMatrix.TLS)))
|
||||
.isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a Servlet run never substitutes for Netty certification")
|
||||
void servletIsNotNettyCertification() {
|
||||
assertThat(GrpcServletStartupValidator.substitutesForNettyCertification()).isFalse();
|
||||
assertThat(PROFILE.certifiesNettyTransport()).isFalse();
|
||||
assertThat(PROFILE.transport()).isEqualTo(GrpcServerTransport.SERVLET);
|
||||
assertThat(GrpcServerTransport.SERVLET.certifiesNetworkBehaviour()).isFalse();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a profile without async support or container-owned TLS is refused")
|
||||
void anIncoherentProfileIsRefused() {
|
||||
assertThatThrownBy(() -> new GrpcServletCompatibilityProfile("/grpc", true, false))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("blocks a container thread");
|
||||
assertThatThrownBy(() -> new GrpcServletCompatibilityProfile("/grpc", false, true))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("a setting nothing reads");
|
||||
assertThatThrownBy(() -> new GrpcServletCompatibilityProfile("grpc", true, true))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
}
|
||||
}
|
||||
+2
-22
@@ -3,27 +3,19 @@ package dev.caskeleton.grpc.advanced.compat;
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.web.GrpcWebCompatibilityGate;
|
||||
import dev.caskeleton.grpc.advanced.web.GrpcWebProfile;
|
||||
import dev.caskeleton.grpc.advanced.web.GrpcWebProxyContract;
|
||||
import dev.caskeleton.grpc.advanced.web.GrpcWebRpcSupport;
|
||||
import dev.caskeleton.grpc.core.GrpcMethodName;
|
||||
import dev.caskeleton.grpc.core.RpcType;
|
||||
import java.io.IOException;
|
||||
import java.io.InputStream;
|
||||
import java.io.UncheckedIOException;
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcWebCompatibilityGateTest {
|
||||
|
||||
private static final GrpcMethodName GET =
|
||||
GrpcMethodName.parse("hyeonworks.document.v1.DocumentService/GetDocument");
|
||||
private static final GrpcMethodName UPLOAD =
|
||||
GrpcMethodName.parse("hyeonworks.document.v1.DocumentService/UploadDocument");
|
||||
class GrpcWebCompatibilityTest {
|
||||
|
||||
@Test
|
||||
@DisplayName("gRPC-Web carries unary and server streaming, and nothing else")
|
||||
@@ -37,18 +29,6 @@ class GrpcWebCompatibilityGateTest {
|
||||
.hasMessageContaining("no way to send a stream of messages");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a client-streaming method exposed to browsers is reported")
|
||||
void anUnservableMethodIsReported() {
|
||||
assertThat(
|
||||
GrpcWebCompatibilityGate.violations(
|
||||
Map.of(GET, RpcType.UNARY, UPLOAD, RpcType.CLIENT_STREAMING)))
|
||||
.singleElement()
|
||||
.satisfies(violation -> assertThat(violation).contains("UploadDocument"));
|
||||
assertThat(GrpcWebCompatibilityGate.violations(Map.of(GET, RpcType.UNARY))).isEmpty();
|
||||
assertThat(GrpcWebCompatibilityGate.sharesOneSchemaWithNativeClients()).isTrue();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a wildcard origin is refused, and cookie credentials require CSRF protection")
|
||||
void browserCredentialRulesDifferByStyle() {
|
||||
@@ -132,7 +112,7 @@ class GrpcWebCompatibilityGateTest {
|
||||
|
||||
private static String resource(String path) {
|
||||
try (InputStream stream =
|
||||
GrpcWebCompatibilityGateTest.class.getClassLoader().getResourceAsStream(path)) {
|
||||
GrpcWebCompatibilityTest.class.getClassLoader().getResourceAsStream(path)) {
|
||||
if (stream == null) {
|
||||
throw new IllegalStateException("missing resource " + path);
|
||||
}
|
||||
@@ -3,8 +3,7 @@ plugins {
|
||||
}
|
||||
|
||||
// Channelz/CSDS diagnostics for administrators, with the redactor that keeps socket authority,
|
||||
// credentials, certificate material, metadata and payload out of a snapshot, plus the advanced
|
||||
// infrastructure testkit contract (gRPC-Web proxy, Servlet container, xDS control-plane failure).
|
||||
// credentials, certificate material, metadata and payload out of a snapshot.
|
||||
dependencies {
|
||||
api project(':grpc:grpc-core-api')
|
||||
api project(':grpc:grpc-client')
|
||||
|
||||
-87
@@ -1,87 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.diagnostics;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
|
||||
import java.util.ArrayList;
|
||||
import java.util.EnumSet;
|
||||
import java.util.List;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* What an advanced capability has to be exercised against before it counts as verified.
|
||||
*
|
||||
* <p>Real infrastructure, named per capability. gRPC-Web without a proxy tests a code path no
|
||||
* browser will take; a Servlet profile without a container tests the profile object; xDS without a
|
||||
* control plane cannot exercise the case that matters, which is the control plane going away. In
|
||||
* all three, a suite that runs without the infrastructure passes and establishes nothing, which is
|
||||
* worse than not having one.
|
||||
*/
|
||||
public final class GrpcAdvancedInfrastructureTestkit {
|
||||
|
||||
private GrpcAdvancedInfrastructureTestkit() {}
|
||||
|
||||
/** A piece of infrastructure a capability's suite needs. */
|
||||
public enum Infrastructure {
|
||||
/** An Envoy or equivalent gRPC-Web proxy. */
|
||||
GRPC_WEB_PROXY,
|
||||
/** A Servlet container serving HTTP/2. */
|
||||
SERVLET_CONTAINER,
|
||||
/** An xDS control plane that can be stopped. */
|
||||
XDS_CONTROL_PLANE,
|
||||
/** A Kotlin toolchain. */
|
||||
KOTLIN_TOOLCHAIN
|
||||
}
|
||||
|
||||
/** What {@code capability} needs before its evidence means anything. */
|
||||
public static Set<Infrastructure> requiredFor(GrpcAdvancedCapability capability) {
|
||||
if (capability == null) {
|
||||
throw new IllegalArgumentException("a capability is required");
|
||||
}
|
||||
return switch (capability) {
|
||||
case GRPC_WEB -> Set.of(Infrastructure.GRPC_WEB_PROXY);
|
||||
case SERVLET_COMPAT -> Set.of(Infrastructure.SERVLET_CONTAINER);
|
||||
case XDS -> Set.of(Infrastructure.XDS_CONTROL_PLANE);
|
||||
case KOTLIN -> Set.of(Infrastructure.KOTLIN_TOOLCHAIN);
|
||||
case EDITION_2024,
|
||||
EDITION_2026,
|
||||
CLIENT_STREAMING,
|
||||
BIDI_STREAMING,
|
||||
MANUAL_FLOW_CONTROL,
|
||||
HEDGING,
|
||||
CUSTOM_RESOLVER,
|
||||
CUSTOM_LOAD_BALANCER,
|
||||
INTEGRATION_BRIDGE,
|
||||
REACTOR,
|
||||
CHANNEL_DIAGNOSTICS ->
|
||||
Set.of();
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Every piece of infrastructure a capability needs and does not have.
|
||||
*
|
||||
* @return an empty list when the suite can produce evidence that means something
|
||||
*/
|
||||
public static List<String> missingInfrastructure(
|
||||
GrpcAdvancedCapability capability, Set<Infrastructure> available) {
|
||||
if (available == null) {
|
||||
throw new IllegalArgumentException("the available infrastructure set is required");
|
||||
}
|
||||
Set<Infrastructure> required = requiredFor(capability);
|
||||
if (required.isEmpty()) {
|
||||
return List.of();
|
||||
}
|
||||
Set<Infrastructure> missing = EnumSet.copyOf(required);
|
||||
missing.removeAll(available);
|
||||
List<String> gaps = new ArrayList<>();
|
||||
missing.stream()
|
||||
.sorted()
|
||||
.forEach(
|
||||
infrastructure ->
|
||||
gaps.add(
|
||||
capability.flagName()
|
||||
+ " needs "
|
||||
+ infrastructure
|
||||
+ "; a suite that runs without it passes and establishes nothing"));
|
||||
return List.copyOf(gaps);
|
||||
}
|
||||
}
|
||||
-30
@@ -191,36 +191,6 @@ class GrpcChannelDiagnosticsPolicyTest {
|
||||
assertThat(snapshot.xdsResourceVersions()).hasSize(3);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("each capability names the real infrastructure its evidence depends on")
|
||||
void capabilitiesNameTheirInfrastructure() {
|
||||
assertThat(GrpcAdvancedInfrastructureTestkit.requiredFor(GrpcAdvancedCapability.GRPC_WEB))
|
||||
.containsExactly(GrpcAdvancedInfrastructureTestkit.Infrastructure.GRPC_WEB_PROXY);
|
||||
assertThat(GrpcAdvancedInfrastructureTestkit.requiredFor(GrpcAdvancedCapability.XDS))
|
||||
.containsExactly(GrpcAdvancedInfrastructureTestkit.Infrastructure.XDS_CONTROL_PLANE);
|
||||
assertThat(GrpcAdvancedInfrastructureTestkit.requiredFor(GrpcAdvancedCapability.HEDGING))
|
||||
.isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a suite without its infrastructure is reported as establishing nothing")
|
||||
void missingInfrastructureIsReported() {
|
||||
assertThat(
|
||||
GrpcAdvancedInfrastructureTestkit.missingInfrastructure(
|
||||
GrpcAdvancedCapability.XDS, Set.of()))
|
||||
.singleElement()
|
||||
.satisfies(gap -> assertThat(gap).contains("establishes nothing"));
|
||||
assertThat(
|
||||
GrpcAdvancedInfrastructureTestkit.missingInfrastructure(
|
||||
GrpcAdvancedCapability.XDS,
|
||||
Set.of(GrpcAdvancedInfrastructureTestkit.Infrastructure.XDS_CONTROL_PLANE)))
|
||||
.isEmpty();
|
||||
assertThat(
|
||||
GrpcAdvancedInfrastructureTestkit.missingInfrastructure(
|
||||
GrpcAdvancedCapability.HEDGING, Set.of()))
|
||||
.isEmpty();
|
||||
}
|
||||
|
||||
private static String resource(String path) {
|
||||
try (java.io.InputStream stream =
|
||||
GrpcChannelDiagnosticsPolicyTest.class.getClassLoader().getResourceAsStream(path)) {
|
||||
|
||||
@@ -4,7 +4,7 @@ plugins {
|
||||
|
||||
// Protobuf Edition lanes. Edition 2024 is an opt-in Advanced lane that must produce cross-consumer
|
||||
// compile evidence before anything public moves onto it; Edition 2026 is a watch lane that records
|
||||
// release/toolchain status and is refused as a Stable contract source.
|
||||
// release/toolchain status.
|
||||
dependencies {
|
||||
api project(':grpc:grpc-core-api')
|
||||
api project(':grpc:grpc-proto-contract')
|
||||
|
||||
-61
@@ -1,61 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.edition;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Decides whether Edition 2024 may be adopted, and keeps its failures out of the Stable release.
|
||||
*
|
||||
* <p>The separation the Stable plan asks for, in one place: an Edition 2024 failure blocks the
|
||||
* edition's own promotion and does not block a proto3 release. Without that split, an opt-in lane
|
||||
* that nobody depends on can hold up every release, and the first response to that is to stop
|
||||
* running the lane.
|
||||
*/
|
||||
public final class GrpcEdition2024Gate {
|
||||
|
||||
private GrpcEdition2024Gate() {}
|
||||
|
||||
/**
|
||||
* Every reason Edition 2024 may not be promoted.
|
||||
*
|
||||
* @return an empty list when the edition is ready to adopt
|
||||
*/
|
||||
public static List<String> promotionBlockers(
|
||||
GrpcEditionCompatibilityReport report,
|
||||
boolean consumerMigrationPlanned,
|
||||
boolean promotionAdr) {
|
||||
if (report == null) {
|
||||
throw new IllegalArgumentException("a compatibility report is required");
|
||||
}
|
||||
List<String> blockers = new ArrayList<>(report.incompatibilities());
|
||||
if (!consumerMigrationPlanned) {
|
||||
blockers.add(
|
||||
"no consumer migration is planned; moving a public service to an edition breaks whichever "
|
||||
+ "consumer's generator treats its features differently");
|
||||
}
|
||||
if (!promotionAdr) {
|
||||
blockers.add(
|
||||
"no promotion ADR records the decision to move onto Edition "
|
||||
+ GrpcEdition2024Policy.EDITION);
|
||||
}
|
||||
return List.copyOf(blockers);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether an Edition 2024 failure blocks a proto3 Stable release.
|
||||
*
|
||||
* <p>Always false. Stated as a method so the property is tested rather than described.
|
||||
*/
|
||||
public static boolean blocksStableRelease() {
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether an Edition 2024 failure blocks the edition's own promotion.
|
||||
*
|
||||
* <p>Always true, for the same reason.
|
||||
*/
|
||||
public static boolean blocksEditionPromotion() {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
-48
@@ -1,48 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.edition;
|
||||
|
||||
/**
|
||||
* Refuses Edition 2026 as a schema source, whatever a report says.
|
||||
*
|
||||
* <p>The guard is deliberately not conditional on the watch report. A watch lane's purpose is to
|
||||
* record what is true, and letting the same record also authorise use means the moment somebody
|
||||
* marks four fields SUPPORTED, a schema can move onto an edition with no promotion decision, no
|
||||
* consumer migration and no ADR. Turning the watch into a lane that can be used is a code change
|
||||
* here, and that is the point.
|
||||
*/
|
||||
public final class GrpcEdition2026Guard {
|
||||
|
||||
private GrpcEdition2026Guard() {}
|
||||
|
||||
/** Whether Edition 2026 may be used as a Stable contract source. Always false. */
|
||||
public static boolean allowedAsStableSource() {
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fails when Edition 2026 is used as a schema source.
|
||||
*
|
||||
* @throws IllegalStateException naming what is still outstanding, so the refusal is actionable
|
||||
*/
|
||||
public static void requireNotUsedAsSource(GrpcEdition2026WatchReport report) {
|
||||
if (report == null) {
|
||||
throw new IllegalArgumentException("a watch report is required");
|
||||
}
|
||||
throw new IllegalStateException(
|
||||
"Edition "
|
||||
+ GrpcEdition2026WatchReport.EDITION
|
||||
+ " is a watch lane, not a schema source"
|
||||
+ (report.outstanding().isEmpty()
|
||||
? "; every toolchain gate is satisfied, so the next step is a promotion decision "
|
||||
+ "rather than a schema change"
|
||||
: "; outstanding: " + report.outstanding()));
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether an Edition 2026 CI failure blocks the Stable build.
|
||||
*
|
||||
* <p>False. A watch lane that can break the build is a watch lane somebody deletes.
|
||||
*/
|
||||
public static boolean blocksStableBuild() {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
+1
-1
@@ -13,7 +13,7 @@ option java_package = "hyeonworks.grpc.edition.v1.generated";
|
||||
// both files to exist.
|
||||
//
|
||||
// Not a Stable contract source. No public service moves onto an edition until the lane has produced
|
||||
// cross-consumer compile evidence and a promotion ADR — see GrpcEdition2024Gate.
|
||||
// cross-consumer compile evidence and a promotion ADR (GrpcEdition2024Policy.promotionApproved).
|
||||
message DocumentSummary {
|
||||
string id = 1;
|
||||
string title = 2 [features.field_presence = EXPLICIT];
|
||||
|
||||
+2
-21
@@ -12,7 +12,7 @@ import java.util.Set;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcEdition2024GateTest {
|
||||
class GrpcEdition2024PolicyTest {
|
||||
|
||||
private static GrpcEditionCompatibilityReport report(
|
||||
boolean wire, boolean json, Map<String, Boolean> toolchains) {
|
||||
@@ -74,25 +74,6 @@ class GrpcEdition2024GateTest {
|
||||
.satisfies(problem -> assertThat(problem).contains("browser clients"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("promotion needs compatibility, a consumer migration and an ADR")
|
||||
void promotionNeedsAllThree() {
|
||||
GrpcEditionCompatibilityReport clean = report(true, true, Map.of("java", true, "go", true));
|
||||
|
||||
assertThat(GrpcEdition2024Gate.promotionBlockers(clean, true, true)).isEmpty();
|
||||
assertThat(GrpcEdition2024Gate.promotionBlockers(clean, false, true))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("consumer migration"));
|
||||
assertThat(GrpcEdition2024Gate.promotionBlockers(clean, true, false))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("promotion ADR"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an Edition failure blocks the edition's promotion and not a proto3 release")
|
||||
void editionFailuresAreIsolatedFromStable() {
|
||||
assertThat(GrpcEdition2024Gate.blocksStableRelease()).isFalse();
|
||||
assertThat(GrpcEdition2024Gate.blocksEditionPromotion()).isTrue();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the Edition 2024 comparison fixture ships beside its proto3 twin")
|
||||
void theComparisonFixtureShips() {
|
||||
@@ -106,7 +87,7 @@ class GrpcEdition2024GateTest {
|
||||
|
||||
private static String resource(String path) {
|
||||
try (InputStream stream =
|
||||
GrpcEdition2024GateTest.class.getClassLoader().getResourceAsStream(path)) {
|
||||
GrpcEdition2024PolicyTest.class.getClassLoader().getResourceAsStream(path)) {
|
||||
if (stream == null) {
|
||||
throw new IllegalStateException("missing resource " + path);
|
||||
}
|
||||
+1
-36
@@ -7,7 +7,7 @@ import java.time.Instant;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcEdition2026GuardTest {
|
||||
class GrpcEdition2026WatchReportTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-08-30T10:00:00Z");
|
||||
|
||||
@@ -55,39 +55,4 @@ class GrpcEdition2026GuardTest {
|
||||
assertThat(GrpcEdition2026Status.UNKNOWN.usable()).isFalse();
|
||||
assertThat(GrpcEdition2026Status.UNSUPPORTED.usable()).isFalse();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("Edition 2026 is refused as a schema source even when every gate is satisfied")
|
||||
void theGuardIsNotConditionalOnTheReport() {
|
||||
GrpcEdition2026WatchReport allSupported =
|
||||
new GrpcEdition2026WatchReport(
|
||||
GrpcEdition2026Status.SUPPORTED,
|
||||
GrpcEdition2026Status.SUPPORTED,
|
||||
GrpcEdition2026Status.SUPPORTED,
|
||||
GrpcEdition2026Status.SUPPORTED,
|
||||
NOW);
|
||||
|
||||
assertThat(allSupported.readyToEvaluate()).isTrue();
|
||||
assertThat(GrpcEdition2026Guard.allowedAsStableSource()).isFalse();
|
||||
assertThatThrownBy(() -> GrpcEdition2026Guard.requireNotUsedAsSource(allSupported))
|
||||
.isInstanceOf(IllegalStateException.class)
|
||||
.hasMessageContaining("promotion decision rather than a schema change");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a refusal names what is still outstanding, so it is actionable")
|
||||
void aRefusalNamesWhatIsOutstanding() {
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
GrpcEdition2026Guard.requireNotUsedAsSource(
|
||||
GrpcEdition2026WatchReport.nothingKnown(NOW)))
|
||||
.isInstanceOf(IllegalStateException.class)
|
||||
.hasMessageContaining("outstanding:");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a watch lane failure does not break the Stable build")
|
||||
void theWatchLaneDoesNotBlockTheStableBuild() {
|
||||
assertThat(GrpcEdition2026Guard.blocksStableBuild()).isFalse();
|
||||
}
|
||||
}
|
||||
+38
-30
@@ -2,7 +2,9 @@ package dev.caskeleton.grpc.advanced.discovery;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
import java.util.Set;
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
/**
|
||||
@@ -19,8 +21,14 @@ public final class GrpcResolverSafetyPolicy {
|
||||
private static final Pattern AUTHORITY =
|
||||
Pattern.compile("[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:\\d{1,5})?");
|
||||
|
||||
private static final Pattern CREDENTIAL_SHAPED =
|
||||
Pattern.compile("(?i).*(authorization|bearer|password|secret|token|api[_-]?key).*");
|
||||
/** The top-level fields of a gRPC service config. Anything else is not policy. */
|
||||
private static final Set<String> SERVICE_CONFIG_FIELDS =
|
||||
Set.of(
|
||||
"loadBalancingConfig",
|
||||
"loadBalancingPolicy",
|
||||
"methodConfig",
|
||||
"retryThrottling",
|
||||
"healthCheckConfig");
|
||||
|
||||
private GrpcResolverSafetyPolicy() {}
|
||||
|
||||
@@ -53,40 +61,40 @@ public final class GrpcResolverSafetyPolicy {
|
||||
+ (lastAccepted == null ? "none" : lastAccepted.revision())
|
||||
+ "; applying it would replace newer endpoints with older ones");
|
||||
}
|
||||
update
|
||||
.serviceConfigJson()
|
||||
.ifPresent(
|
||||
config -> {
|
||||
if (CREDENTIAL_SHAPED.matcher(config).find()) {
|
||||
violations.add(
|
||||
"the pushed service config contains a credential-shaped field; a resolver "
|
||||
+ "supplies addresses and policy, never authentication material");
|
||||
}
|
||||
});
|
||||
update.serviceConfig().ifPresent(config -> serviceConfigViolations(config, violations));
|
||||
return List.copyOf(violations);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether a closed resolver's update should be applied.
|
||||
*
|
||||
* <p>Always false. A resolver that keeps delivering after close is one whose discovery source has
|
||||
* not noticed the channel is gone, and applying its updates resurrects routing for a channel
|
||||
* nobody is using.
|
||||
*/
|
||||
public static boolean acceptAfterClose() {
|
||||
return false;
|
||||
}
|
||||
|
||||
/** Whether a resolver may supply caller identity or business metadata. Always false. */
|
||||
public static boolean mayCarryBusinessMetadata() {
|
||||
return false;
|
||||
private static void serviceConfigViolations(Map<String, ?> config, List<String> violations) {
|
||||
if (!SERVICE_CONFIG_FIELDS.containsAll(config.keySet())) {
|
||||
violations.add(
|
||||
"the pushed service config has top-level fields outside "
|
||||
+ SERVICE_CONFIG_FIELDS.stream().sorted().toList()
|
||||
+ "; a resolver supplies addresses and policy, never authentication material");
|
||||
}
|
||||
Object methodConfig = config.get("methodConfig");
|
||||
if (methodConfig == null) {
|
||||
return;
|
||||
}
|
||||
if (!(methodConfig instanceof List<?> entries)
|
||||
|| !entries.stream().allMatch(entry -> entry instanceof Map<?, ?>)) {
|
||||
violations.add("the pushed service config's methodConfig is not a list of objects");
|
||||
return;
|
||||
}
|
||||
if (entries.stream()
|
||||
.map(entry -> (Map<?, ?>) entry)
|
||||
.anyMatch(
|
||||
entry -> entry.containsKey("retryPolicy") || entry.containsKey("hedgingPolicy"))) {
|
||||
violations.add(
|
||||
"the pushed service config sets retryPolicy or hedgingPolicy; retries and hedging are "
|
||||
+ "owned by the platform's method policy catalog, and a resolver that could turn them "
|
||||
+ "on could retry a non-idempotent method from outside the codebase");
|
||||
}
|
||||
}
|
||||
|
||||
/** The service config an update may contribute, once validated. */
|
||||
public static Optional<String> acceptedServiceConfig(
|
||||
public static Optional<Map<String, ?>> acceptedServiceConfig(
|
||||
GrpcResolverUpdate update, GrpcEndpointSnapshot lastAccepted) {
|
||||
return violations(update, lastAccepted).isEmpty()
|
||||
? update.serviceConfigJson()
|
||||
: Optional.empty();
|
||||
return violations(update, lastAccepted).isEmpty() ? update.serviceConfig() : Optional.empty();
|
||||
}
|
||||
}
|
||||
|
||||
+15
-6
@@ -1,5 +1,8 @@
|
||||
package dev.caskeleton.grpc.advanced.discovery;
|
||||
|
||||
import java.util.Collections;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
@@ -11,20 +14,26 @@ import java.util.Optional;
|
||||
* anyone reviewed it.
|
||||
*/
|
||||
public record GrpcResolverUpdate(
|
||||
GrpcEndpointSnapshot snapshot, Optional<String> serviceConfigJson) {
|
||||
GrpcEndpointSnapshot snapshot, Optional<Map<String, ?>> serviceConfig) {
|
||||
|
||||
/** Requires a snapshot and the Optional. */
|
||||
/**
|
||||
* Requires a snapshot and the Optional. The service config is the parsed JSON object, the same
|
||||
* {@code Map<String, ?>} shape gRPC's {@code NameResolver.Helper.parseServiceConfig} takes; it is
|
||||
* copied so it cannot change between validation and delivery.
|
||||
*/
|
||||
public GrpcResolverUpdate {
|
||||
if (snapshot == null || serviceConfigJson == null) {
|
||||
if (snapshot == null || serviceConfig == null) {
|
||||
throw new IllegalArgumentException("a resolver update carries a snapshot and the Optional");
|
||||
}
|
||||
serviceConfigJson.ifPresent(
|
||||
serviceConfig.ifPresent(
|
||||
config -> {
|
||||
if (config.isBlank()) {
|
||||
if (config.isEmpty()) {
|
||||
throw new IllegalArgumentException(
|
||||
"a present service config must not be blank; absent and empty are different states");
|
||||
"a present service config must not be empty; absent and empty are different states");
|
||||
}
|
||||
});
|
||||
serviceConfig =
|
||||
serviceConfig.map(config -> Collections.unmodifiableMap(new LinkedHashMap<>(config)));
|
||||
}
|
||||
|
||||
/** An update with endpoints only. */
|
||||
|
||||
-100
@@ -1,100 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.xds;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedFeatureFlags;
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedModuleGuard;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Refuses to start an xDS channel that is not fully configured, and refuses to let xDS be described
|
||||
* as Stable support.
|
||||
*
|
||||
* <p>The second refusal is the one worth having in code. xDS working in a deployment is not the
|
||||
* same claim as the platform supporting it: it brings a control plane, its outage modes, its own
|
||||
* security boundary and its own version skew, and the Stable support statement covers DNS and
|
||||
* static targets. A support matrix that quietly widens is a support matrix nobody can rely on.
|
||||
*/
|
||||
public final class GrpcXdsStartupGuard {
|
||||
|
||||
private GrpcXdsStartupGuard() {}
|
||||
|
||||
/**
|
||||
* Every reason an xDS channel may not start.
|
||||
*
|
||||
* @return an empty list when the profile and flags permit it
|
||||
*/
|
||||
public static List<String> startupBlockers(
|
||||
GrpcXdsProfile profile, GrpcAdvancedFeatureFlags flags, boolean applicationDefinesRetries) {
|
||||
if (profile == null || flags == null) {
|
||||
throw new IllegalArgumentException("startup validation needs a profile and the flags");
|
||||
}
|
||||
List<String> blockers = new ArrayList<>();
|
||||
if (!GrpcAdvancedModuleGuard.available(flags, GrpcAdvancedCapability.XDS)) {
|
||||
blockers.add(
|
||||
"the xds capability is not available; it is "
|
||||
+ flags.gradeOf(GrpcAdvancedCapability.XDS)
|
||||
+ " and "
|
||||
+ (flags.flagSet(GrpcAdvancedCapability.XDS)
|
||||
? "production has not approved it"
|
||||
: "its flag is not set"));
|
||||
}
|
||||
if (applicationDefinesRetries) {
|
||||
blockers.add(
|
||||
"the application also defines retry policy; with xDS the control plane owns it, and "
|
||||
+ "defining it in both places makes the winner depend on resolution order");
|
||||
}
|
||||
return List.copyOf(blockers);
|
||||
}
|
||||
|
||||
/**
|
||||
* Every disagreement between a deployment's profile and the bootstrap file its client will read.
|
||||
*
|
||||
* <p>Checked because the two are written by different people in different repositories, and the
|
||||
* failure is silent: a client whose bootstrap names a namespace the deployment did not configure
|
||||
* subscribes successfully and receives another team's routing. Nothing errors — the control plane
|
||||
* answers, the resources parse, and traffic goes somewhere nobody chose.
|
||||
*
|
||||
* <p>Matched textually rather than with a JSON parser, deliberately. This leaf's test classpath
|
||||
* is plain JUnit and AssertJ, and adding a JSON library to check three fields would put a parser
|
||||
* on the runtime classpath of every deployment that enables xDS.
|
||||
*
|
||||
* @param bootstrapJson the bootstrap document's contents
|
||||
* @return an empty list when the bootstrap and the profile agree
|
||||
*/
|
||||
public static List<String> bootstrapMismatches(GrpcXdsProfile profile, String bootstrapJson) {
|
||||
if (profile == null) {
|
||||
throw new IllegalArgumentException("a profile is required");
|
||||
}
|
||||
if (bootstrapJson == null || bootstrapJson.isBlank()) {
|
||||
throw new IllegalArgumentException(
|
||||
"the bootstrap document is required; a client with no bootstrap has no control plane to ask");
|
||||
}
|
||||
List<String> mismatches = new ArrayList<>();
|
||||
if (!bootstrapJson.contains("\"xds_servers\"")) {
|
||||
mismatches.add("the bootstrap declares no xds_servers");
|
||||
}
|
||||
if (!bootstrapJson.contains("\"channel_creds\"") || !bootstrapJson.contains("\"tls\"")) {
|
||||
mismatches.add(
|
||||
"the bootstrap's control-plane channel is not TLS; that connection carries routing and "
|
||||
+ "often certificates, so an unauthenticated one can be impersonated");
|
||||
}
|
||||
if (!bootstrapJson.contains(profile.resourceNamespace())) {
|
||||
mismatches.add(
|
||||
"the bootstrap does not name the profile's resource namespace '"
|
||||
+ profile.resourceNamespace()
|
||||
+ "'; a client that subscribes outside its namespace receives another team's routing, "
|
||||
+ "and nothing about that fails");
|
||||
}
|
||||
return List.copyOf(mismatches);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether xDS may be advertised as part of Stable discovery support.
|
||||
*
|
||||
* <p>Always false. Stable support is DNS and static.
|
||||
*/
|
||||
public static boolean advertisableAsStableSupport() {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
+49
-9
@@ -2,6 +2,7 @@ package dev.caskeleton.grpc.advanced.resilience;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
import static org.assertj.core.api.Assertions.catchThrowable;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.discovery.GrpcCustomResolver;
|
||||
import dev.caskeleton.grpc.advanced.discovery.GrpcEndpointSnapshot;
|
||||
@@ -9,6 +10,7 @@ import dev.caskeleton.grpc.advanced.discovery.GrpcResolverSafetyPolicy;
|
||||
import dev.caskeleton.grpc.advanced.discovery.GrpcResolverUpdate;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
@@ -65,7 +67,6 @@ class GrpcResolverSafetyPolicyTest {
|
||||
new GrpcEndpointSnapshot(1L, "documents", List.of("10.0.0.1")))))
|
||||
.anySatisfy(violation -> assertThat(violation).contains("resolver is closed"));
|
||||
assertThat(delivered).isEmpty();
|
||||
assertThat(GrpcResolverSafetyPolicy.acceptAfterClose()).isFalse();
|
||||
}
|
||||
|
||||
@Test
|
||||
@@ -74,11 +75,10 @@ class GrpcResolverSafetyPolicyTest {
|
||||
GrpcResolverUpdate withCredential =
|
||||
new GrpcResolverUpdate(
|
||||
new GrpcEndpointSnapshot(1L, "documents", List.of("10.0.0.1")),
|
||||
Optional.of("{\"authorization\":\"Bearer abc\"}"));
|
||||
Optional.of(Map.of("authorization", "Bearer abc")));
|
||||
|
||||
assertThat(GrpcResolverSafetyPolicy.violations(withCredential, null))
|
||||
.anySatisfy(violation -> assertThat(violation).contains("never authentication material"));
|
||||
assertThat(GrpcResolverSafetyPolicy.mayCarryBusinessMetadata()).isFalse();
|
||||
assertThat(GrpcResolverSafetyPolicy.acceptedServiceConfig(withCredential, null)).isEmpty();
|
||||
}
|
||||
|
||||
@@ -88,12 +88,48 @@ class GrpcResolverSafetyPolicyTest {
|
||||
GrpcResolverUpdate clean =
|
||||
new GrpcResolverUpdate(
|
||||
new GrpcEndpointSnapshot(1L, "documents", List.of("10.0.0.1")),
|
||||
Optional.of("{\"loadBalancingConfig\":[{\"round_robin\":{}}]}"));
|
||||
Optional.of(Map.of("loadBalancingConfig", List.of(Map.of("round_robin", Map.of())))));
|
||||
|
||||
assertThat(GrpcResolverSafetyPolicy.violations(clean, null)).isEmpty();
|
||||
assertThat(GrpcResolverSafetyPolicy.acceptedServiceConfig(clean, null)).isPresent();
|
||||
}
|
||||
|
||||
@Test
|
||||
void aServiceConfigWithRetryThrottlingIsAccepted() {
|
||||
// given
|
||||
GrpcResolverUpdate throttled =
|
||||
new GrpcResolverUpdate(
|
||||
new GrpcEndpointSnapshot(1L, "documents", List.of("10.0.0.1")),
|
||||
Optional.of(Map.of("retryThrottling", Map.of("maxTokens", 10, "tokenRatio", 0.1))));
|
||||
|
||||
// when
|
||||
List<String> violations = GrpcResolverSafetyPolicy.violations(throttled, null);
|
||||
|
||||
// then
|
||||
assertThat(violations).isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
void aServiceConfigThatTurnsOnRetriesIsRefused() {
|
||||
// given
|
||||
GrpcResolverUpdate retrying =
|
||||
new GrpcResolverUpdate(
|
||||
new GrpcEndpointSnapshot(1L, "documents", List.of("10.0.0.1")),
|
||||
Optional.of(
|
||||
Map.of(
|
||||
"methodConfig",
|
||||
List.of(
|
||||
Map.of(
|
||||
"name", List.of(Map.of("service", "documents.v1.Documents")),
|
||||
"retryPolicy", Map.of("maxAttempts", 5))))));
|
||||
|
||||
// when
|
||||
List<String> violations = GrpcResolverSafetyPolicy.violations(retrying, null);
|
||||
|
||||
// then
|
||||
assertThat(violations).singleElement().asString().contains("retryPolicy or hedgingPolicy");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an invalid authority is refused, because it decides which certificate is accepted")
|
||||
void anInvalidAuthorityIsRefused() {
|
||||
@@ -106,14 +142,18 @@ class GrpcResolverSafetyPolicyTest {
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a present service config may not be blank")
|
||||
void aPresentServiceConfigMayNotBeBlank() {
|
||||
assertThatThrownBy(
|
||||
void aPresentServiceConfigMayNotBeEmpty() {
|
||||
// when
|
||||
Throwable failure =
|
||||
catchThrowable(
|
||||
() ->
|
||||
new GrpcResolverUpdate(
|
||||
new GrpcEndpointSnapshot(1L, "documents", List.of("10.0.0.1")),
|
||||
Optional.of(" ")))
|
||||
Optional.of(Map.of())));
|
||||
|
||||
// then
|
||||
assertThat(failure)
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("different states");
|
||||
.hasMessageContaining("absent and empty are different states");
|
||||
}
|
||||
}
|
||||
|
||||
+94
@@ -0,0 +1,94 @@
|
||||
package dev.caskeleton.grpc.advanced.resilience;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.xds.GrpcXdsFailurePolicy;
|
||||
import dev.caskeleton.grpc.advanced.xds.GrpcXdsProfile;
|
||||
import dev.caskeleton.grpc.advanced.xds.GrpcXdsResourceSnapshot;
|
||||
import dev.caskeleton.grpc.resilience.GrpcRetryOwner;
|
||||
import java.net.URI;
|
||||
import java.time.Instant;
|
||||
import java.util.List;
|
||||
import java.util.Optional;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcXdsProfileTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-08-30T10:00:00Z");
|
||||
|
||||
private static GrpcXdsProfile profile(String namespace) {
|
||||
return new GrpcXdsProfile(
|
||||
URI.create("xds:///documents"),
|
||||
"classpath:/xds/bootstrap.json",
|
||||
namespace,
|
||||
GrpcRetryOwner.SERVICE_MESH,
|
||||
true);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an xDS profile requires an xds target, a namespace, mesh retries and mTLS")
|
||||
void anXdsProfileRequiresItsFourConditions() {
|
||||
assertThat(profile("hyeonworks/documents").target().getScheme()).isEqualTo("xds");
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcXdsProfile(
|
||||
URI.create("dns:///documents"),
|
||||
"file:/etc/grpc/bootstrap.json",
|
||||
"ns",
|
||||
GrpcRetryOwner.SERVICE_MESH,
|
||||
true))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcXdsProfile(
|
||||
URI.create("xds:///documents"), " ", "ns", GrpcRetryOwner.SERVICE_MESH, true))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("no control plane to ask");
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcXdsProfile(
|
||||
URI.create("xds:///documents"),
|
||||
"file:/etc/grpc/bootstrap.json",
|
||||
"ns",
|
||||
GrpcRetryOwner.APPLICATION,
|
||||
true))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("two places");
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcXdsProfile(
|
||||
URI.create("xds:///documents"),
|
||||
"file:/etc/grpc/bootstrap.json",
|
||||
"ns",
|
||||
GrpcRetryOwner.SERVICE_MESH,
|
||||
false))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("impersonated");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("last-known-good is bounded, and an empty resource set is not a snapshot")
|
||||
void lastKnownGoodIsBounded() {
|
||||
GrpcXdsFailurePolicy policy = GrpcXdsFailurePolicy.standard();
|
||||
GrpcXdsResourceSnapshot snapshot =
|
||||
new GrpcXdsResourceSnapshot("v7", List.of("documents-cluster"), NOW);
|
||||
|
||||
assertThat(policy.decide(Optional.of(snapshot), NOW.plusSeconds(60)))
|
||||
.isEqualTo(GrpcXdsFailurePolicy.Decision.SERVE_LAST_KNOWN_GOOD);
|
||||
assertThat(policy.decide(Optional.of(snapshot), NOW.plusSeconds(1000)))
|
||||
.isEqualTo(GrpcXdsFailurePolicy.Decision.STALE_BEYOND_BOUND);
|
||||
assertThat(policy.decide(Optional.empty(), NOW))
|
||||
.isEqualTo(GrpcXdsFailurePolicy.Decision.NO_SNAPSHOT_YET);
|
||||
assertThat(snapshot.ageAt(NOW.plusSeconds(60))).isEqualTo(java.time.Duration.ofSeconds(60));
|
||||
assertThatThrownBy(() -> new GrpcXdsResourceSnapshot("v7", List.of(), NOW))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcXdsFailurePolicy(
|
||||
java.time.Duration.ZERO, true, java.time.Duration.ofSeconds(1)))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("receiving traffic indefinitely");
|
||||
}
|
||||
}
|
||||
-188
@@ -1,188 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.resilience;
|
||||
|
||||
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.GrpcAdvancedFeatureFlags;
|
||||
import dev.caskeleton.grpc.advanced.xds.GrpcXdsFailurePolicy;
|
||||
import dev.caskeleton.grpc.advanced.xds.GrpcXdsProfile;
|
||||
import dev.caskeleton.grpc.advanced.xds.GrpcXdsResourceSnapshot;
|
||||
import dev.caskeleton.grpc.advanced.xds.GrpcXdsStartupGuard;
|
||||
import dev.caskeleton.grpc.resilience.GrpcRetryOwner;
|
||||
import java.io.IOException;
|
||||
import java.io.InputStream;
|
||||
import java.io.UncheckedIOException;
|
||||
import java.net.URI;
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.time.Instant;
|
||||
import java.util.List;
|
||||
import java.util.Optional;
|
||||
import java.util.Set;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcXdsStartupGuardTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-08-30T10:00:00Z");
|
||||
|
||||
private static GrpcXdsProfile profile(String namespace) {
|
||||
return new GrpcXdsProfile(
|
||||
URI.create("xds:///documents"),
|
||||
"classpath:/xds/bootstrap.json",
|
||||
namespace,
|
||||
GrpcRetryOwner.SERVICE_MESH,
|
||||
true);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an xDS profile requires an xds target, a namespace, mesh retries and mTLS")
|
||||
void anXdsProfileRequiresItsFourConditions() {
|
||||
assertThat(profile("hyeonworks/documents").target().getScheme()).isEqualTo("xds");
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcXdsProfile(
|
||||
URI.create("dns:///documents"),
|
||||
"file:/etc/grpc/bootstrap.json",
|
||||
"ns",
|
||||
GrpcRetryOwner.SERVICE_MESH,
|
||||
true))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcXdsProfile(
|
||||
URI.create("xds:///documents"), " ", "ns", GrpcRetryOwner.SERVICE_MESH, true))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("no control plane to ask");
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcXdsProfile(
|
||||
URI.create("xds:///documents"),
|
||||
"file:/etc/grpc/bootstrap.json",
|
||||
"ns",
|
||||
GrpcRetryOwner.APPLICATION,
|
||||
true))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("two places");
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcXdsProfile(
|
||||
URI.create("xds:///documents"),
|
||||
"file:/etc/grpc/bootstrap.json",
|
||||
"ns",
|
||||
GrpcRetryOwner.SERVICE_MESH,
|
||||
false))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("impersonated");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("xDS needs its capability approved and refuses duplicate retry ownership")
|
||||
void startupRequiresApprovalAndSingleRetryOwner() {
|
||||
GrpcAdvancedFeatureFlags unapproved =
|
||||
GrpcAdvancedFeatureFlags.forProduction(Set.of()).enable(GrpcAdvancedCapability.XDS);
|
||||
GrpcAdvancedFeatureFlags approved =
|
||||
GrpcAdvancedFeatureFlags.forProduction(Set.of(GrpcAdvancedCapability.XDS))
|
||||
.enable(GrpcAdvancedCapability.XDS);
|
||||
|
||||
assertThat(
|
||||
GrpcXdsStartupGuard.startupBlockers(profile("hyeonworks/documents"), unapproved, false))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("production has not approved it"));
|
||||
assertThat(
|
||||
GrpcXdsStartupGuard.startupBlockers(profile("hyeonworks/documents"), approved, false))
|
||||
.isEmpty();
|
||||
assertThat(GrpcXdsStartupGuard.startupBlockers(profile("hyeonworks/documents"), approved, true))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("resolution order"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an unflagged capability is reported as unflagged rather than unapproved")
|
||||
void anUnflaggedCapabilityIsReportedAsSuch() {
|
||||
assertThat(
|
||||
GrpcXdsStartupGuard.startupBlockers(
|
||||
profile("hyeonworks/documents"),
|
||||
GrpcAdvancedFeatureFlags.forProduction(Set.of()),
|
||||
false))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("its flag is not set"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the committed bootstrap fixture agrees with the profile it is meant to serve")
|
||||
void theBootstrapFixtureAgreesWithItsProfile() {
|
||||
assertThat(
|
||||
GrpcXdsStartupGuard.bootstrapMismatches(
|
||||
profile("hyeonworks/documents"), resource("xds/bootstrap.json")))
|
||||
.isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a bootstrap naming another namespace is reported, since nothing else would fail")
|
||||
void aNamespaceMismatchIsReported() {
|
||||
assertThat(
|
||||
GrpcXdsStartupGuard.bootstrapMismatches(
|
||||
profile("hyeonworks/billing"), resource("xds/bootstrap.json")))
|
||||
.anySatisfy(mismatch -> assertThat(mismatch).contains("another team's routing"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a bootstrap with an unauthenticated control-plane channel is reported")
|
||||
void anUnauthenticatedControlPlaneIsReported() {
|
||||
String insecure =
|
||||
resource("xds/bootstrap.json")
|
||||
.replace("{ \"type\": \"tls\" }", "{ \"type\": \"insecure\" }");
|
||||
|
||||
assertThat(GrpcXdsStartupGuard.bootstrapMismatches(profile("hyeonworks/documents"), insecure))
|
||||
.anySatisfy(mismatch -> assertThat(mismatch).contains("can be impersonated"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a missing bootstrap is refused rather than treated as an empty one")
|
||||
void aMissingBootstrapIsRefused() {
|
||||
assertThatThrownBy(
|
||||
() -> GrpcXdsStartupGuard.bootstrapMismatches(profile("hyeonworks/documents"), " "))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("no control plane to ask");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("last-known-good is bounded, and an empty resource set is not a snapshot")
|
||||
void lastKnownGoodIsBounded() {
|
||||
GrpcXdsFailurePolicy policy = GrpcXdsFailurePolicy.standard();
|
||||
GrpcXdsResourceSnapshot snapshot =
|
||||
new GrpcXdsResourceSnapshot("v7", List.of("documents-cluster"), NOW);
|
||||
|
||||
assertThat(policy.decide(Optional.of(snapshot), NOW.plusSeconds(60)))
|
||||
.isEqualTo(GrpcXdsFailurePolicy.Decision.SERVE_LAST_KNOWN_GOOD);
|
||||
assertThat(policy.decide(Optional.of(snapshot), NOW.plusSeconds(1000)))
|
||||
.isEqualTo(GrpcXdsFailurePolicy.Decision.STALE_BEYOND_BOUND);
|
||||
assertThat(policy.decide(Optional.empty(), NOW))
|
||||
.isEqualTo(GrpcXdsFailurePolicy.Decision.NO_SNAPSHOT_YET);
|
||||
assertThat(snapshot.ageAt(NOW.plusSeconds(60))).isEqualTo(java.time.Duration.ofSeconds(60));
|
||||
assertThatThrownBy(() -> new GrpcXdsResourceSnapshot("v7", List.of(), NOW))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcXdsFailurePolicy(
|
||||
java.time.Duration.ZERO, true, java.time.Duration.ofSeconds(1)))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("receiving traffic indefinitely");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("xDS is not part of the Stable discovery support statement")
|
||||
void xdsIsNotStableSupport() {
|
||||
assertThat(GrpcXdsStartupGuard.advertisableAsStableSupport()).isFalse();
|
||||
}
|
||||
|
||||
private static String resource(String path) {
|
||||
try (InputStream stream =
|
||||
GrpcXdsStartupGuardTest.class.getClassLoader().getResourceAsStream(path)) {
|
||||
if (stream == null) {
|
||||
throw new IllegalStateException("missing test resource " + path);
|
||||
}
|
||||
return new String(stream.readAllBytes(), StandardCharsets.UTF_8);
|
||||
} catch (IOException e) {
|
||||
throw new UncheckedIOException(e);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,40 +0,0 @@
|
||||
{
|
||||
"_comment": [
|
||||
"An xDS bootstrap fixture. The client reads this file to learn where its control plane is and",
|
||||
"who it claims to be; GrpcXdsProfile validates the deployment settings that must agree with it.",
|
||||
"The two fields the profile actually checks against are server_uri (the control plane must be",
|
||||
"reached over authenticated mTLS) and the node id's namespace (a client that subscribes outside",
|
||||
"its namespace receives another team's routing)."
|
||||
],
|
||||
"xds_servers": [
|
||||
{
|
||||
"server_uri": "xds-control-plane.hyeonworks.internal:15010",
|
||||
"channel_creds": [
|
||||
{ "type": "tls" }
|
||||
],
|
||||
"server_features": ["xds_v3"]
|
||||
}
|
||||
],
|
||||
"node": {
|
||||
"id": "hyeonworks/documents/documents-7f9c4",
|
||||
"cluster": "documents",
|
||||
"metadata": {
|
||||
"NAMESPACE": "hyeonworks/documents"
|
||||
},
|
||||
"locality": {
|
||||
"region": "ap-northeast-2",
|
||||
"zone": "ap-northeast-2a"
|
||||
}
|
||||
},
|
||||
"authorities": {
|
||||
"hyeonworks.internal": {
|
||||
"xds_servers": [
|
||||
{
|
||||
"server_uri": "xds-control-plane.hyeonworks.internal:15010",
|
||||
"channel_creds": [{ "type": "tls" }],
|
||||
"server_features": ["xds_v3"]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
+4
-3
@@ -67,7 +67,7 @@ capability flag 뒤에 있다. `GrpcPlatformStartupValidator`가 Stable catalog
|
||||
등록되면 startup을 거부한다.
|
||||
|
||||
`grpc-spring-boot-starter`는 어떤 advanced module도 참조하지 않는다. registry의
|
||||
`allowed_dependencies`가 이를 build time에, `GrpcStableBuildInvariant`가 runtime에 강제한다.
|
||||
`allowed_dependencies`와 `verifyCleanArchitectureDependencies`가 이를 build time에 강제한다.
|
||||
|
||||
## Optional build에 있다는 것의 의미
|
||||
|
||||
@@ -88,8 +88,9 @@ soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위
|
||||
application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-server SPI
|
||||
```
|
||||
|
||||
이고 `GrpcApplicationBoundaryRules`·`GrpcRawApiImportRule`·`GrpcServiceAdapter`가 그 경계를
|
||||
소유한다. 현재 `adapter:inbound:grpc`는 이 family에 의존하지 않는다 — registry의
|
||||
이고 `GrpcServiceAdapter`가 그 SPI를 소유한다. inbound adapter가 outbound adapter·persistence에
|
||||
직접 닿지 않는 규칙은 app-bootstrap ArchUnit(`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`)이
|
||||
검사한다. 현재 `adapter:inbound:grpc`는 이 family에 의존하지 않는다 — registry의
|
||||
`allowed_dependencies`를 보라. 배선은 별도 결정이며, 그때 registry edge와 브리지가 함께 들어간다.
|
||||
|
||||
## 테스트 명령
|
||||
|
||||
-53
@@ -1,53 +0,0 @@
|
||||
package dev.caskeleton.grpc.core;
|
||||
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* Build-time invariants the Stable platform holds about its own module graph.
|
||||
*
|
||||
* <p>These are asserted from Java as well as from Gradle on purpose. The registry gate ({@code
|
||||
* verifyCleanArchitectureDependencies}) is the one that fails a build, and it is the authority;
|
||||
* this class is what a runtime component calls when it is handed a dependency set it did not
|
||||
* compile against — a starter reading its own classpath, say — where the Gradle gate has nothing to
|
||||
* look at.
|
||||
*/
|
||||
public final class GrpcStableBuildInvariant {
|
||||
|
||||
private GrpcStableBuildInvariant() {}
|
||||
|
||||
/**
|
||||
* Whether a Stable module may depend on an Advanced one.
|
||||
*
|
||||
* <p>Always false, and it takes no argument for a reason: the answer does not vary by module, by
|
||||
* capability or by environment. A method that could return true for some input would be the seam
|
||||
* through which "just this one Advanced type in the starter" arrives.
|
||||
*/
|
||||
public static boolean advancedDependencyAllowed() {
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fails when a Stable module's dependency set reaches an Advanced module.
|
||||
*
|
||||
* @throws IllegalStateException naming every advanced dependency found
|
||||
*/
|
||||
public static void requireNoAdvancedDependency(String moduleId, Set<String> dependencies) {
|
||||
GrpcIdentifiers.requireBounded(moduleId, "module id");
|
||||
if (dependencies == null) {
|
||||
throw new IllegalArgumentException("dependency set must not be null");
|
||||
}
|
||||
if (!GrpcStableModuleCatalog.standard().isStable(moduleId)) {
|
||||
return;
|
||||
}
|
||||
Set<String> leaks = GrpcStableModuleCatalog.advancedLeaks(dependencies);
|
||||
if (!leaks.isEmpty()) {
|
||||
throw new IllegalStateException(
|
||||
"Stable module '"
|
||||
+ moduleId
|
||||
+ "' must not depend on advanced modules "
|
||||
+ leaks.stream().sorted().toList()
|
||||
+ "; advanced capabilities are reached through an explicit feature flag, never by "
|
||||
+ "being on the Stable classpath.");
|
||||
}
|
||||
}
|
||||
}
|
||||
-79
@@ -1,79 +0,0 @@
|
||||
package dev.caskeleton.grpc.core;
|
||||
|
||||
import java.util.LinkedHashSet;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* The exact set of Stable platform modules, and the exact set that is not Stable.
|
||||
*
|
||||
* <p>The Stable plan fixes its module list as a Global Constraint so that "this capability is
|
||||
* Stable" is a fact with one owner instead of a property of whatever happens to be on a classpath.
|
||||
* This repository's module registry ({@code src/config/architecture/modules.json}) is the SSOT for
|
||||
* which Gradle projects exist; this catalog is the SSOT for which of them the Stable contract
|
||||
* covers, and {@code GrpcStableModuleCatalogTest} holds the two together.
|
||||
*
|
||||
* <p>The names are this repository's leaf ids rather than the plan's, because the plan's four
|
||||
* testkit modules are four strict test lanes here — see the adaptation design, §2.
|
||||
*/
|
||||
public record GrpcStableModuleCatalog(Set<String> modules) {
|
||||
|
||||
private static final Set<String> STABLE =
|
||||
Set.of(
|
||||
"grpc-core-api",
|
||||
"grpc-proto-contract",
|
||||
"grpc-codegen",
|
||||
"grpc-policy",
|
||||
"grpc-server",
|
||||
"grpc-client",
|
||||
"grpc-discovery",
|
||||
"grpc-admin",
|
||||
"grpc-observability",
|
||||
"grpc-operation-ledger-jpa",
|
||||
"grpc-spring-boot-starter",
|
||||
"grpc-testkit");
|
||||
|
||||
private static final Set<String> ADVANCED =
|
||||
Set.of(
|
||||
"grpc-advanced-bootstrap",
|
||||
"grpc-advanced-edition",
|
||||
"grpc-advanced-streaming",
|
||||
"grpc-advanced-resilience",
|
||||
"grpc-advanced-compat",
|
||||
"grpc-advanced-diagnostics");
|
||||
|
||||
/** Defensively copies, so a caller cannot widen the Stable set by mutating what it was given. */
|
||||
public GrpcStableModuleCatalog {
|
||||
if (modules == null || modules.isEmpty()) {
|
||||
throw new IllegalArgumentException("a module catalog needs at least one module");
|
||||
}
|
||||
modules = Set.copyOf(modules);
|
||||
}
|
||||
|
||||
/** The Stable module set. */
|
||||
public static GrpcStableModuleCatalog standard() {
|
||||
return new GrpcStableModuleCatalog(STABLE);
|
||||
}
|
||||
|
||||
/** The Advanced and Experimental module set, which is disjoint from {@link #standard()}. */
|
||||
public static Set<String> advancedModules() {
|
||||
return ADVANCED;
|
||||
}
|
||||
|
||||
/** Whether {@code moduleId} is part of the Stable contract. */
|
||||
public boolean isStable(String moduleId) {
|
||||
return modules.contains(moduleId);
|
||||
}
|
||||
|
||||
/**
|
||||
* The advanced module ids that appear in {@code candidateDependencies}.
|
||||
*
|
||||
* <p>Returned rather than thrown so a build or startup check can name every violation at once. A
|
||||
* gate that reports the first advanced dependency it finds makes removing four of them a
|
||||
* four-round conversation.
|
||||
*/
|
||||
public static Set<String> advancedLeaks(Set<String> candidateDependencies) {
|
||||
Set<String> leaks = new LinkedHashSet<>(candidateDependencies);
|
||||
leaks.retainAll(ADVANCED);
|
||||
return Set.copyOf(leaks);
|
||||
}
|
||||
}
|
||||
-90
@@ -1,90 +0,0 @@
|
||||
package dev.caskeleton.grpc.core;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
import java.util.Set;
|
||||
import java.util.regex.Pattern;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcStableModuleCatalogTest {
|
||||
|
||||
@Test
|
||||
@DisplayName("the Stable module set is exact and excludes every advanced module")
|
||||
void stableModuleSetIsExactAndAdvancedIsExcluded() {
|
||||
GrpcStableModuleCatalog catalog = GrpcStableModuleCatalog.standard();
|
||||
|
||||
assertThat(catalog.modules())
|
||||
.contains("grpc-core-api", "grpc-client", "grpc-server", "grpc-policy")
|
||||
.doesNotContainAnyElementsOf(GrpcStableModuleCatalog.advancedModules());
|
||||
assertThat(GrpcStableBuildInvariant.advancedDependencyAllowed()).isFalse();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the optional gRPC registry is exactly classified as Stable or Advanced")
|
||||
void registryAndCatalogStayTogether() throws Exception {
|
||||
Path candidate = Path.of("").toAbsolutePath();
|
||||
while (candidate != null
|
||||
&& !Files.isRegularFile(candidate.resolve("src/config/architecture/modules.json"))) {
|
||||
candidate = candidate.getParent();
|
||||
}
|
||||
assertThat(candidate).as("repository root").isNotNull();
|
||||
String registry = Files.readString(candidate.resolve("src/config/architecture/modules.json"));
|
||||
Pattern entry =
|
||||
Pattern.compile(
|
||||
"\\{[^{}]*\"id\"\\s*:\\s*\"(grpc-[^\"]+)\"[^{}]*"
|
||||
+ "\"build\"\\s*:\\s*\"optional-grpc\"[^{}]*\\}",
|
||||
Pattern.DOTALL);
|
||||
Set<String> registered =
|
||||
entry
|
||||
.matcher(registry)
|
||||
.results()
|
||||
.map(result -> result.group(1))
|
||||
.collect(java.util.stream.Collectors.toUnmodifiableSet());
|
||||
Set<String> classified = new java.util.HashSet<>(GrpcStableModuleCatalog.standard().modules());
|
||||
classified.addAll(GrpcStableModuleCatalog.advancedModules());
|
||||
|
||||
assertThat(registered).isNotEmpty().containsExactlyInAnyOrderElementsOf(classified);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the Stable and Advanced sets are disjoint")
|
||||
void stableAndAdvancedAreDisjoint() {
|
||||
GrpcStableModuleCatalog catalog = GrpcStableModuleCatalog.standard();
|
||||
|
||||
assertThat(GrpcStableModuleCatalog.advancedModules()).isNotEmpty().noneMatch(catalog::isStable);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a Stable module reaching an advanced module fails, naming every leak")
|
||||
void stableModuleMayNotDependOnAdvanced() {
|
||||
Set<String> dependencies =
|
||||
Set.of("grpc-core-api", "grpc-advanced-streaming", "grpc-advanced-compat");
|
||||
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
GrpcStableBuildInvariant.requireNoAdvancedDependency(
|
||||
"grpc-spring-boot-starter", dependencies))
|
||||
.isInstanceOf(IllegalStateException.class)
|
||||
.hasMessageContaining("grpc-spring-boot-starter")
|
||||
.hasMessageContaining("grpc-advanced-streaming")
|
||||
.hasMessageContaining("grpc-advanced-compat");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a Stable module with only Stable dependencies passes")
|
||||
void stableOnlyDependenciesPass() {
|
||||
GrpcStableBuildInvariant.requireNoAdvancedDependency(
|
||||
"grpc-server", Set.of("grpc-core-api", "grpc-policy"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an advanced module is not judged by the Stable invariant")
|
||||
void advancedModuleIsNotGovernedByTheStableRule() {
|
||||
GrpcStableBuildInvariant.requireNoAdvancedDependency(
|
||||
"grpc-advanced-compat", Set.of("grpc-advanced-bootstrap"));
|
||||
}
|
||||
}
|
||||
-92
@@ -1,92 +0,0 @@
|
||||
package dev.caskeleton.grpc.architecture;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* What a gRPC service adapter may not reach.
|
||||
*
|
||||
* <p>The list is package prefixes rather than a prose rule, so it can be applied by an architecture
|
||||
* test, by a source scan and by a review checklist without three people deciding what "must not use
|
||||
* a repository" covers.
|
||||
*
|
||||
* <p>The rule these encode is one of this repository's hard stops: a transport adapter that calls a
|
||||
* repository has moved the use case into the transport, and the next caller of that use case — a
|
||||
* scheduled job, a message consumer — either duplicates it or reaches through the controller.
|
||||
*/
|
||||
public final class GrpcApplicationBoundaryRules {
|
||||
|
||||
/** Package prefixes an adapter may not reference. */
|
||||
private static final Set<String> FORBIDDEN_PREFIXES =
|
||||
Set.of(
|
||||
"jakarta.persistence",
|
||||
"org.hibernate",
|
||||
"org.springframework.data",
|
||||
"org.springframework.jdbc",
|
||||
"org.springframework.orm",
|
||||
"org.springframework.web.client",
|
||||
"org.springframework.web.reactive.function.client",
|
||||
"java.net.http",
|
||||
"org.apache.kafka",
|
||||
"org.springframework.kafka",
|
||||
"org.springframework.amqp",
|
||||
"software.amazon.awssdk",
|
||||
"dev.caskeleton.adapter.outbound");
|
||||
|
||||
/** Exact types an adapter may not reference, where the package alone is too broad. */
|
||||
private static final Set<String> FORBIDDEN_TYPES =
|
||||
Set.of("javax.sql.DataSource", "java.sql.Connection", "java.sql.DriverManager");
|
||||
|
||||
private GrpcApplicationBoundaryRules() {}
|
||||
|
||||
/** The forbidden package prefixes, for an architecture test to consume. */
|
||||
public static Set<String> forbiddenPackagePrefixes() {
|
||||
return FORBIDDEN_PREFIXES;
|
||||
}
|
||||
|
||||
/** The forbidden exact types. */
|
||||
public static Set<String> forbiddenTypes() {
|
||||
return FORBIDDEN_TYPES;
|
||||
}
|
||||
|
||||
/**
|
||||
* Every forbidden reference in {@code referencedTypes}.
|
||||
*
|
||||
* @param adapterName the adapter under test, for the message
|
||||
* @return an empty list when the adapter stays inside the boundary
|
||||
*/
|
||||
public static List<String> violations(String adapterName, Set<String> referencedTypes) {
|
||||
if (adapterName == null || adapterName.isBlank()) {
|
||||
throw new IllegalArgumentException("a boundary check names the adapter it is about");
|
||||
}
|
||||
if (referencedTypes == null) {
|
||||
throw new IllegalArgumentException("the referenced type set must not be null");
|
||||
}
|
||||
List<String> violations = new ArrayList<>();
|
||||
referencedTypes.stream()
|
||||
.sorted()
|
||||
.forEach(
|
||||
referenced -> {
|
||||
if (FORBIDDEN_TYPES.contains(referenced)) {
|
||||
violations.add(
|
||||
adapterName + " references " + referenced + ", which belongs behind a port");
|
||||
return;
|
||||
}
|
||||
FORBIDDEN_PREFIXES.stream()
|
||||
.filter(prefix -> referenced.startsWith(prefix + "."))
|
||||
.findFirst()
|
||||
.ifPresent(
|
||||
prefix ->
|
||||
violations.add(
|
||||
adapterName
|
||||
+ " references "
|
||||
+ referenced
|
||||
+ " from forbidden package '"
|
||||
+ prefix
|
||||
+ "'; a transport adapter reaches persistence, messaging and "
|
||||
+ "HTTP only through an application port"));
|
||||
});
|
||||
return List.copyOf(violations);
|
||||
}
|
||||
}
|
||||
-108
@@ -1,108 +0,0 @@
|
||||
package dev.caskeleton.grpc.architecture;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Set;
|
||||
import java.util.regex.Matcher;
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
/**
|
||||
* Keeps raw gRPC construction APIs out of ordinary application code.
|
||||
*
|
||||
* <p>The types below are the ones that build a channel, a server or a call by hand. Every one of
|
||||
* them bypasses a Stable guarantee: a hand-built {@code ManagedChannel} has no named profile, no
|
||||
* deadline policy and no credential rotation; a hand-built {@code ClientCall} skips the interceptor
|
||||
* chain entirely. They are legitimate inside the platform and inside generated code, which is why
|
||||
* this rule takes an allowlist of packages rather than banning them outright.
|
||||
*/
|
||||
public final class GrpcRawApiImportRule {
|
||||
|
||||
/** The construction APIs ordinary application code may not import. */
|
||||
private static final Set<String> RAW_API_TYPES =
|
||||
Set.of(
|
||||
"io.grpc.ManagedChannelBuilder",
|
||||
"io.grpc.ManagedChannel",
|
||||
"io.grpc.ServerBuilder",
|
||||
"io.grpc.Server",
|
||||
"io.grpc.ClientCall",
|
||||
"io.grpc.ClientCalls",
|
||||
"io.grpc.MethodDescriptor",
|
||||
"io.grpc.CallCredentials",
|
||||
"io.grpc.netty.NettyChannelBuilder",
|
||||
"io.grpc.netty.NettyServerBuilder",
|
||||
"io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder",
|
||||
"io.grpc.netty.shaded.io.grpc.netty.NettyServerBuilder",
|
||||
"io.grpc.inprocess.InProcessChannelBuilder",
|
||||
"io.grpc.inprocess.InProcessServerBuilder");
|
||||
|
||||
private static final Pattern IMPORT =
|
||||
Pattern.compile("^\\s*import\\s+(?:static\\s+)?([\\w.]+)\\s*;", Pattern.MULTILINE);
|
||||
private static final Pattern PACKAGE =
|
||||
Pattern.compile("^\\s*package\\s+([\\w.]+)\\s*;", Pattern.MULTILINE);
|
||||
|
||||
private final Set<String> allowedPackagePrefixes;
|
||||
|
||||
/**
|
||||
* @param allowedPackagePrefixes packages where raw construction is the job — the platform's own
|
||||
* leaves and the generated code root. Everything else reaches gRPC through a typed stub or a
|
||||
* service adapter.
|
||||
*/
|
||||
public GrpcRawApiImportRule(Set<String> allowedPackagePrefixes) {
|
||||
if (allowedPackagePrefixes == null || allowedPackagePrefixes.isEmpty()) {
|
||||
throw new IllegalArgumentException(
|
||||
"a raw-API rule needs at least one allowed package; the platform itself has to build "
|
||||
+ "channels somewhere");
|
||||
}
|
||||
this.allowedPackagePrefixes = Set.copyOf(allowedPackagePrefixes);
|
||||
}
|
||||
|
||||
/** This repository's rule: the platform leaves and the generated package may construct. */
|
||||
public static GrpcRawApiImportRule caSkeleton() {
|
||||
return new GrpcRawApiImportRule(Set.of("dev.caskeleton.grpc", "hyeonworks.grpc"));
|
||||
}
|
||||
|
||||
/** The raw construction types this rule governs. */
|
||||
public static Set<String> rawApiTypes() {
|
||||
return RAW_API_TYPES;
|
||||
}
|
||||
|
||||
/**
|
||||
* Every forbidden import in one Java source file.
|
||||
*
|
||||
* @return an empty list when the file is compliant, or when it is inside an allowed package
|
||||
*/
|
||||
public List<String> violations(String fileName, String source) {
|
||||
if (fileName == null || fileName.isBlank()) {
|
||||
throw new IllegalArgumentException("a source file needs a name");
|
||||
}
|
||||
if (source == null) {
|
||||
throw new IllegalArgumentException("a source file needs its text");
|
||||
}
|
||||
Matcher packageMatcher = PACKAGE.matcher(source);
|
||||
String declaredPackage = packageMatcher.find() ? packageMatcher.group(1) : "";
|
||||
if (allowed(declaredPackage)) {
|
||||
return List.of();
|
||||
}
|
||||
|
||||
List<String> violations = new ArrayList<>();
|
||||
Matcher imports = IMPORT.matcher(source);
|
||||
while (imports.find()) {
|
||||
String imported = imports.group(1);
|
||||
if (RAW_API_TYPES.contains(imported)) {
|
||||
violations.add(
|
||||
fileName
|
||||
+ " imports "
|
||||
+ imported
|
||||
+ "; a hand-built channel, server or call has no named profile, no deadline policy "
|
||||
+ "and no interceptor chain. Use a typed stub or a service adapter.");
|
||||
}
|
||||
}
|
||||
return List.copyOf(violations);
|
||||
}
|
||||
|
||||
/** Whether {@code packageName} may construct raw gRPC objects. */
|
||||
public boolean allowed(String packageName) {
|
||||
return allowedPackagePrefixes.stream()
|
||||
.anyMatch(prefix -> packageName.equals(prefix) || packageName.startsWith(prefix + "."));
|
||||
}
|
||||
}
|
||||
-25
@@ -1,25 +0,0 @@
|
||||
package dev.caskeleton.grpc.architecture;
|
||||
|
||||
import java.lang.annotation.Documented;
|
||||
import java.lang.annotation.ElementType;
|
||||
import java.lang.annotation.Retention;
|
||||
import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* Marks a class as a gRPC service adapter, which is what the boundary rules are stated about.
|
||||
*
|
||||
* <p>An annotation rather than a naming convention, because a rule keyed on a suffix is a rule that
|
||||
* stops applying the moment somebody names a class {@code DocumentGrpcFacade}. The marker is what a
|
||||
* rule set can enumerate exactly.
|
||||
*
|
||||
* <p>Runtime retention so an architecture test can find the classes without a source scan.
|
||||
*/
|
||||
@Documented
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@Target(ElementType.TYPE)
|
||||
public @interface GrpcServiceAdapterMarker {
|
||||
|
||||
/** The full method names this adapter serves, for cross-checking against the policy catalog. */
|
||||
String[] methods() default {};
|
||||
}
|
||||
-142
@@ -1,142 +0,0 @@
|
||||
package dev.caskeleton.grpc.architecture;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import java.util.Set;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcApplicationBoundaryRulesTest {
|
||||
|
||||
@Test
|
||||
@DisplayName("an adapter reaching persistence, messaging or HTTP directly is refused")
|
||||
void anAdapterMayNotReachInfrastructureDirectly() {
|
||||
Set<String> referenced =
|
||||
Set.of(
|
||||
"dev.caskeleton.application.document.CreateDocumentUseCase",
|
||||
"jakarta.persistence.EntityManager",
|
||||
"org.springframework.data.jpa.repository.JpaRepository",
|
||||
"org.apache.kafka.clients.producer.KafkaProducer",
|
||||
"java.net.http.HttpClient");
|
||||
|
||||
assertThat(GrpcApplicationBoundaryRules.violations("DocumentServiceAdapter", referenced))
|
||||
.hasSize(4)
|
||||
.allSatisfy(violation -> assertThat(violation).startsWith("DocumentServiceAdapter"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an adapter that only reaches application ports passes")
|
||||
void anAdapterOnApplicationPortsPasses() {
|
||||
assertThat(
|
||||
GrpcApplicationBoundaryRules.violations(
|
||||
"DocumentServiceAdapter",
|
||||
Set.of(
|
||||
"dev.caskeleton.application.document.CreateDocumentUseCase",
|
||||
"dev.caskeleton.grpc.api.context.GrpcRequestContext")))
|
||||
.isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a raw DataSource or Connection is refused even though its package is not")
|
||||
void exactTypesAreRefusedWherePackagesAreTooBroad() {
|
||||
assertThat(
|
||||
GrpcApplicationBoundaryRules.violations(
|
||||
"DocumentServiceAdapter", Set.of("javax.sql.DataSource")))
|
||||
.singleElement()
|
||||
.satisfies(violation -> assertThat(violation).contains("belongs behind a port"));
|
||||
assertThat(GrpcApplicationBoundaryRules.forbiddenTypes())
|
||||
.contains("java.sql.Connection", "java.sql.DriverManager");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an inbound adapter may not reach an outbound adapter")
|
||||
void inboundMayNotReachOutbound() {
|
||||
assertThat(
|
||||
GrpcApplicationBoundaryRules.violations(
|
||||
"DocumentServiceAdapter",
|
||||
Set.of("dev.caskeleton.adapter.outbound.persistence.DocumentJpaRepository")))
|
||||
.hasSize(1);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("ordinary application code may not import a raw channel, server or call builder")
|
||||
void rawConstructionApisAreRefusedOutsideThePlatform() {
|
||||
GrpcRawApiImportRule rule = GrpcRawApiImportRule.caSkeleton();
|
||||
String applicationSource =
|
||||
"""
|
||||
package dev.caskeleton.application.document;
|
||||
|
||||
import io.grpc.ManagedChannelBuilder;
|
||||
import java.util.List;
|
||||
|
||||
class DocumentClient {}
|
||||
""";
|
||||
|
||||
assertThat(rule.violations("DocumentClient.java", applicationSource))
|
||||
.singleElement()
|
||||
.satisfies(
|
||||
violation ->
|
||||
assertThat(violation)
|
||||
.contains("io.grpc.ManagedChannelBuilder")
|
||||
.contains("no interceptor chain"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the platform's own packages and generated code may construct")
|
||||
void thePlatformAndGeneratedCodeMayConstruct() {
|
||||
GrpcRawApiImportRule rule = GrpcRawApiImportRule.caSkeleton();
|
||||
String platformSource =
|
||||
"""
|
||||
package dev.caskeleton.grpc.client;
|
||||
|
||||
import io.grpc.ManagedChannelBuilder;
|
||||
|
||||
class ChannelFactory {}
|
||||
""";
|
||||
String generatedSource =
|
||||
"""
|
||||
package hyeonworks.grpc.common.v1.generated;
|
||||
|
||||
import io.grpc.MethodDescriptor;
|
||||
|
||||
public final class DocumentServiceGrpc {}
|
||||
""";
|
||||
|
||||
assertThat(rule.violations("ChannelFactory.java", platformSource)).isEmpty();
|
||||
assertThat(rule.violations("DocumentServiceGrpc.java", generatedSource)).isEmpty();
|
||||
assertThat(rule.allowed("dev.caskeleton.grpc.server")).isTrue();
|
||||
assertThat(rule.allowed("dev.caskeleton.application")).isFalse();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a rule with no allowed package is refused, since the platform must build somewhere")
|
||||
void aRuleWithNoAllowedPackageIsRefused() {
|
||||
assertThatThrownBy(() -> new GrpcRawApiImportRule(Set.of()))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("build channels somewhere");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the raw API list covers channel, server and call construction on every transport")
|
||||
void theRawApiListCoversEveryConstructionPath() {
|
||||
assertThat(GrpcRawApiImportRule.rawApiTypes())
|
||||
.contains(
|
||||
"io.grpc.ManagedChannelBuilder",
|
||||
"io.grpc.ServerBuilder",
|
||||
"io.grpc.ClientCall",
|
||||
"io.grpc.netty.NettyServerBuilder",
|
||||
"io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder",
|
||||
"io.grpc.inprocess.InProcessServerBuilder");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the marker annotation is visible at runtime, so a rule can enumerate adapters")
|
||||
void theMarkerIsVisibleAtRuntime() {
|
||||
assertThat(
|
||||
GrpcServiceAdapterMarker.class
|
||||
.getAnnotation(java.lang.annotation.Retention.class)
|
||||
.value())
|
||||
.isEqualTo(java.lang.annotation.RetentionPolicy.RUNTIME);
|
||||
}
|
||||
}
|
||||
+19
-13
@@ -10,11 +10,11 @@ import dev.caskeleton.grpc.client.GrpcNamedChannelProfile;
|
||||
import dev.caskeleton.grpc.context.GrpcContextBinder;
|
||||
import dev.caskeleton.grpc.context.GrpcContextPropagationPolicy;
|
||||
import dev.caskeleton.grpc.error.GrpcErrorMapper;
|
||||
import dev.caskeleton.grpc.security.GrpcTlsProfile;
|
||||
import dev.caskeleton.grpc.server.GrpcAdmissionController;
|
||||
import dev.caskeleton.grpc.server.GrpcExecutorProfile;
|
||||
import dev.caskeleton.grpc.server.GrpcServerProfile;
|
||||
import java.time.Duration;
|
||||
import java.util.Set;
|
||||
import java.util.UUID;
|
||||
import org.springframework.beans.factory.ObjectProvider;
|
||||
import org.springframework.beans.factory.SmartInitializingSingleton;
|
||||
@@ -80,16 +80,23 @@ public class GrpcPlatformAutoConfiguration {
|
||||
return new GrpcServiceHealthRegistry(GrpcHealthPolicy.standalone());
|
||||
}
|
||||
|
||||
/** The reflection policy, defaulted from the environment. */
|
||||
/**
|
||||
* The reflection policy, defaulted from the environment. An unset environment gets the strictest
|
||||
* floor here; the startup check then refuses the configuration with the reason.
|
||||
*/
|
||||
@Bean
|
||||
@ConditionalOnMissingBean
|
||||
public GrpcReflectionPolicy grpcReflectionPolicy(GrpcPlatformProperties properties) {
|
||||
return properties.getReflectionMode() == null
|
||||
? GrpcReflectionPolicy.defaultFor(properties.getEnvironment())
|
||||
: new GrpcReflectionPolicy(
|
||||
properties.getReflectionMode(),
|
||||
java.util.Set.of("admin"),
|
||||
java.util.Set.of("ROLE_PLATFORM_ADMIN"));
|
||||
if (properties.getReflectionMode() != null) {
|
||||
return new GrpcReflectionPolicy(
|
||||
properties.getReflectionMode(),
|
||||
java.util.Set.of("admin"),
|
||||
java.util.Set.of("ROLE_PLATFORM_ADMIN"));
|
||||
}
|
||||
return GrpcReflectionPolicy.defaultFor(
|
||||
properties.getEnvironment() == null
|
||||
? GrpcTlsProfile.Environment.PROD
|
||||
: properties.getEnvironment());
|
||||
}
|
||||
|
||||
/** The admin exposure gates. */
|
||||
@@ -116,9 +123,9 @@ public class GrpcPlatformAutoConfiguration {
|
||||
/**
|
||||
* Runs the Stable startup validator against the bean graph after singleton assembly.
|
||||
*
|
||||
* <p>The Gradle architecture gate owns dependency-graph isolation. Runtime validation therefore
|
||||
* passes no synthetic dependency list; it validates only inputs a running process can actually
|
||||
* observe: typed properties, the method-policy catalog and named client channels.
|
||||
* <p>The Gradle architecture gate owns dependency-graph isolation. Runtime validation checks only
|
||||
* inputs a running process can actually observe: typed properties, the method-policy catalog and
|
||||
* named client channels.
|
||||
*/
|
||||
@Bean
|
||||
public SmartInitializingSingleton grpcPlatformStartupCheck(
|
||||
@@ -129,8 +136,7 @@ public class GrpcPlatformAutoConfiguration {
|
||||
GrpcPlatformStartupValidator.requireValid(
|
||||
properties,
|
||||
catalogs.getIfAvailable(() -> GrpcMethodPolicyCatalog.builder().build()),
|
||||
channelProfiles.orderedStream().toList(),
|
||||
Set.of());
|
||||
channelProfiles.orderedStream().toList());
|
||||
}
|
||||
|
||||
/** The shared error mapper. Its execution ids are random and carry no derived content. */
|
||||
|
||||
+16
-4
@@ -22,8 +22,12 @@ public class GrpcPlatformProperties {
|
||||
/** Whether the platform is assembled at all. */
|
||||
private boolean enabled;
|
||||
|
||||
/** Which environment this deployment is, which decides the TLS and reflection floors. */
|
||||
private GrpcTlsProfile.Environment environment = GrpcTlsProfile.Environment.LOCAL;
|
||||
/**
|
||||
* Which environment this deployment is, which decides the TLS and reflection floors. No default:
|
||||
* a missing value used to mean LOCAL, which silently switched every TLS and reflection check off,
|
||||
* so an enabled platform without it is refused at startup.
|
||||
*/
|
||||
private GrpcTlsProfile.Environment environment;
|
||||
|
||||
/** The server transport. Only a production transport is accepted outside tests. */
|
||||
private GrpcServerTransport transport = GrpcServerTransport.NETTY_SHADED;
|
||||
@@ -120,8 +124,16 @@ public class GrpcPlatformProperties {
|
||||
this.operationLedgerEnabled = operationLedgerEnabled;
|
||||
}
|
||||
|
||||
/** The reflection mode this deployment runs, defaulting to the environment's floor. */
|
||||
/**
|
||||
* The reflection mode this deployment runs, defaulting to the environment's floor, and to
|
||||
* disabled while the environment is unset (the startup check refuses that state).
|
||||
*/
|
||||
public GrpcReflectionMode effectiveReflectionMode() {
|
||||
return reflectionMode == null ? GrpcReflectionMode.defaultFor(environment) : reflectionMode;
|
||||
if (reflectionMode != null) {
|
||||
return reflectionMode;
|
||||
}
|
||||
return environment == null
|
||||
? GrpcReflectionMode.DISABLED
|
||||
: GrpcReflectionMode.defaultFor(environment);
|
||||
}
|
||||
}
|
||||
|
||||
+14
-25
@@ -6,7 +6,6 @@ import dev.caskeleton.grpc.api.policy.GrpcMethodPolicyCatalog;
|
||||
import dev.caskeleton.grpc.api.policy.RpcIdempotencyProfile;
|
||||
import dev.caskeleton.grpc.client.GrpcNamedChannelProfile;
|
||||
import dev.caskeleton.grpc.core.GrpcMethodName;
|
||||
import dev.caskeleton.grpc.core.GrpcStableBuildInvariant;
|
||||
import dev.caskeleton.grpc.core.RpcType;
|
||||
import dev.caskeleton.grpc.discovery.GrpcDiscoveryPolicyValidator;
|
||||
import dev.caskeleton.grpc.resilience.GrpcRetryOwner;
|
||||
@@ -33,20 +32,17 @@ public final class GrpcPlatformStartupValidator {
|
||||
/**
|
||||
* Every reason this configuration is refused.
|
||||
*
|
||||
* @param stableModuleDependencies dependency ids supplied by a caller that can observe a runtime
|
||||
* dependency set; the Spring auto-configuration passes an empty set because the Gradle
|
||||
* registry gate is authoritative for the compiled graph
|
||||
* <p>Stable-to-Advanced module isolation is not checked here: the Gradle registry gate ({@code
|
||||
* verifyCleanArchitectureDependencies}) owns the compiled graph, and a running process has no
|
||||
* dependency list to check it against.
|
||||
*
|
||||
* @return an empty list when the configuration is safe to start
|
||||
*/
|
||||
public static List<String> violations(
|
||||
GrpcPlatformProperties properties,
|
||||
GrpcMethodPolicyCatalog catalog,
|
||||
List<GrpcNamedChannelProfile> channelProfiles,
|
||||
Set<String> stableModuleDependencies) {
|
||||
if (properties == null
|
||||
|| catalog == null
|
||||
|| channelProfiles == null
|
||||
|| stableModuleDependencies == null) {
|
||||
List<GrpcNamedChannelProfile> channelProfiles) {
|
||||
if (properties == null || catalog == null || channelProfiles == null) {
|
||||
throw new IllegalArgumentException("startup validation needs every input");
|
||||
}
|
||||
List<String> violations = new ArrayList<>();
|
||||
@@ -55,7 +51,6 @@ public final class GrpcPlatformStartupValidator {
|
||||
validateExecutor(properties, violations);
|
||||
validateMethods(properties, catalog, violations);
|
||||
validateChannels(channelProfiles, violations);
|
||||
validateAdvancedIsolation(stableModuleDependencies, violations);
|
||||
return List.copyOf(violations);
|
||||
}
|
||||
|
||||
@@ -67,10 +62,8 @@ public final class GrpcPlatformStartupValidator {
|
||||
public static void requireValid(
|
||||
GrpcPlatformProperties properties,
|
||||
GrpcMethodPolicyCatalog catalog,
|
||||
List<GrpcNamedChannelProfile> channelProfiles,
|
||||
Set<String> stableModuleDependencies) {
|
||||
List<String> violations =
|
||||
violations(properties, catalog, channelProfiles, stableModuleDependencies);
|
||||
List<GrpcNamedChannelProfile> channelProfiles) {
|
||||
List<String> violations = violations(properties, catalog, channelProfiles);
|
||||
if (!violations.isEmpty()) {
|
||||
throw new GrpcPlatformConfigurationException(violations);
|
||||
}
|
||||
@@ -84,6 +77,12 @@ public final class GrpcPlatformStartupValidator {
|
||||
+ properties.getTransport()
|
||||
+ " may not serve production traffic; in-process evidence is not network evidence");
|
||||
}
|
||||
if (properties.getEnvironment() == null) {
|
||||
violations.add(
|
||||
"ca-skeleton.grpc.platform.environment is not set; the TLS and reflection floors depend on"
|
||||
+ " it, so it is refused rather than assumed LOCAL");
|
||||
return;
|
||||
}
|
||||
boolean deployed = properties.getEnvironment().tlsRequired();
|
||||
if (deployed && !properties.isTlsEnabled()) {
|
||||
violations.add("TLS is required in " + properties.getEnvironment() + " and is disabled");
|
||||
@@ -172,16 +171,6 @@ public final class GrpcPlatformStartupValidator {
|
||||
}
|
||||
}
|
||||
|
||||
private static void validateAdvancedIsolation(
|
||||
Set<String> stableModuleDependencies, List<String> violations) {
|
||||
try {
|
||||
GrpcStableBuildInvariant.requireNoAdvancedDependency(
|
||||
"grpc-spring-boot-starter", stableModuleDependencies);
|
||||
} catch (IllegalStateException leaked) {
|
||||
violations.add(leaked.getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
private static List<GrpcMethodName> sorted(Set<GrpcMethodName> methods) {
|
||||
return methods.stream()
|
||||
.sorted(java.util.Comparator.comparing(GrpcMethodName::canonical))
|
||||
|
||||
+20
@@ -2,6 +2,7 @@ package dev.caskeleton.grpc.boot;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
import static org.assertj.core.api.Assertions.catchThrowable;
|
||||
|
||||
import java.util.Map;
|
||||
import org.junit.jupiter.api.Test;
|
||||
@@ -26,6 +27,25 @@ class GrpcPlatformAutoConfigurationContextTest {
|
||||
.hasMessageContaining("providing none");
|
||||
}
|
||||
|
||||
@Test
|
||||
void enabledPlatformWithoutAnEnvironmentRefusesToStartInsteadOfAssumingLocal() {
|
||||
// when
|
||||
Throwable failure =
|
||||
catchThrowable(
|
||||
() ->
|
||||
start(
|
||||
Map.of(
|
||||
"ca-skeleton.grpc.platform.enabled", "true",
|
||||
"ca-skeleton.grpc.platform.transport", "NETTY_SHADED",
|
||||
"ca-skeleton.grpc.platform.tls-enabled", "false",
|
||||
"ca-skeleton.grpc.platform.reflection-mode", "ENABLED")));
|
||||
|
||||
// then
|
||||
assertThat(failure)
|
||||
.isInstanceOf(GrpcPlatformConfigurationException.class)
|
||||
.hasMessageContaining("ca-skeleton.grpc.platform.environment is not set");
|
||||
}
|
||||
|
||||
@Test
|
||||
void coherentLocalConfigurationRunsTheStartupValidatorAndStarts() {
|
||||
try (AnnotationConfigApplicationContext context =
|
||||
|
||||
+11
-41
@@ -23,7 +23,6 @@ import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
import java.time.Duration;
|
||||
import java.util.List;
|
||||
import java.util.Set;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
@@ -36,9 +35,6 @@ class GrpcPlatformStartupValidatorTest {
|
||||
private static final GrpcTlsProfile PROD_TLS =
|
||||
GrpcTlsProfile.serverAuthenticated(GrpcTlsProfile.Environment.PROD, "trust-bundle");
|
||||
|
||||
private static final Set<String> STABLE_DEPENDENCIES =
|
||||
Set.of("grpc-core-api", "grpc-policy", "grpc-server", "grpc-client");
|
||||
|
||||
private static GrpcPlatformProperties productionProperties() {
|
||||
GrpcPlatformProperties properties = new GrpcPlatformProperties();
|
||||
properties.setEnabled(true);
|
||||
@@ -73,10 +69,10 @@ class GrpcPlatformStartupValidatorTest {
|
||||
void aCoherentConfigurationStarts() {
|
||||
assertThat(
|
||||
GrpcPlatformStartupValidator.violations(
|
||||
productionProperties(), healthyCatalog(), oneChannel(), STABLE_DEPENDENCIES))
|
||||
productionProperties(), healthyCatalog(), oneChannel()))
|
||||
.isEmpty();
|
||||
GrpcPlatformStartupValidator.requireValid(
|
||||
productionProperties(), healthyCatalog(), oneChannel(), STABLE_DEPENDENCIES);
|
||||
productionProperties(), healthyCatalog(), oneChannel());
|
||||
}
|
||||
|
||||
@Test
|
||||
@@ -91,9 +87,7 @@ class GrpcPlatformStartupValidatorTest {
|
||||
GrpcPlatformProperties properties = productionProperties();
|
||||
properties.setTransport(GrpcServerTransport.IN_PROCESS);
|
||||
|
||||
assertThat(
|
||||
GrpcPlatformStartupValidator.violations(
|
||||
properties, healthyCatalog(), oneChannel(), STABLE_DEPENDENCIES))
|
||||
assertThat(GrpcPlatformStartupValidator.violations(properties, healthyCatalog(), oneChannel()))
|
||||
.anySatisfy(violation -> assertThat(violation).contains("not network evidence"));
|
||||
}
|
||||
|
||||
@@ -105,13 +99,9 @@ class GrpcPlatformStartupValidatorTest {
|
||||
GrpcPlatformProperties trustAll = productionProperties();
|
||||
trustAll.setTrustAllCertificates(true);
|
||||
|
||||
assertThat(
|
||||
GrpcPlatformStartupValidator.violations(
|
||||
noTls, healthyCatalog(), oneChannel(), STABLE_DEPENDENCIES))
|
||||
assertThat(GrpcPlatformStartupValidator.violations(noTls, healthyCatalog(), oneChannel()))
|
||||
.anySatisfy(violation -> assertThat(violation).contains("TLS is required"));
|
||||
assertThat(
|
||||
GrpcPlatformStartupValidator.violations(
|
||||
trustAll, healthyCatalog(), oneChannel(), STABLE_DEPENDENCIES))
|
||||
assertThat(GrpcPlatformStartupValidator.violations(trustAll, healthyCatalog(), oneChannel()))
|
||||
.anySatisfy(violation -> assertThat(violation).contains("providing none"));
|
||||
}
|
||||
|
||||
@@ -121,9 +111,7 @@ class GrpcPlatformStartupValidatorTest {
|
||||
GrpcPlatformProperties properties = productionProperties();
|
||||
properties.setReflectionMode(GrpcReflectionMode.ENABLED);
|
||||
|
||||
assertThat(
|
||||
GrpcPlatformStartupValidator.violations(
|
||||
properties, healthyCatalog(), oneChannel(), STABLE_DEPENDENCIES))
|
||||
assertThat(GrpcPlatformStartupValidator.violations(properties, healthyCatalog(), oneChannel()))
|
||||
.anySatisfy(violation -> assertThat(violation).contains("published to anyone"));
|
||||
assertThat(productionProperties().effectiveReflectionMode())
|
||||
.isEqualTo(GrpcReflectionMode.DISABLED);
|
||||
@@ -135,9 +123,7 @@ class GrpcPlatformStartupValidatorTest {
|
||||
GrpcPlatformProperties properties = productionProperties();
|
||||
properties.setExecutorQueueCapacity(0);
|
||||
|
||||
assertThat(
|
||||
GrpcPlatformStartupValidator.violations(
|
||||
properties, healthyCatalog(), oneChannel(), STABLE_DEPENDENCIES))
|
||||
assertThat(GrpcPlatformStartupValidator.violations(properties, healthyCatalog(), oneChannel()))
|
||||
.anySatisfy(violation -> assertThat(violation).contains("unbounded latency"));
|
||||
}
|
||||
|
||||
@@ -160,9 +146,7 @@ class GrpcPlatformStartupValidatorTest {
|
||||
1024))
|
||||
.build();
|
||||
|
||||
assertThat(
|
||||
GrpcPlatformStartupValidator.violations(
|
||||
properties, catalog, oneChannel(), STABLE_DEPENDENCIES))
|
||||
assertThat(GrpcPlatformStartupValidator.violations(properties, catalog, oneChannel()))
|
||||
.anySatisfy(violation -> assertThat(violation).contains("never honoured"));
|
||||
}
|
||||
|
||||
@@ -184,8 +168,7 @@ class GrpcPlatformStartupValidatorTest {
|
||||
.build();
|
||||
|
||||
assertThat(
|
||||
GrpcPlatformStartupValidator.violations(
|
||||
productionProperties(), catalog, oneChannel(), STABLE_DEPENDENCIES))
|
||||
GrpcPlatformStartupValidator.violations(productionProperties(), catalog, oneChannel()))
|
||||
.anySatisfy(violation -> assertThat(violation).contains("Advanced capability"));
|
||||
}
|
||||
|
||||
@@ -207,21 +190,10 @@ class GrpcPlatformStartupValidatorTest {
|
||||
|
||||
assertThat(
|
||||
GrpcPlatformStartupValidator.violations(
|
||||
productionProperties(), healthyCatalog(), twoOwners, STABLE_DEPENDENCIES))
|
||||
productionProperties(), healthyCatalog(), twoOwners))
|
||||
.anySatisfy(violation -> assertThat(violation).contains("multiply the load"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the Stable starter reaching an Advanced module is refused at startup too")
|
||||
void advancedLeakIsRefusedAtStartup() {
|
||||
Set<String> leaked = Set.of("grpc-core-api", "grpc-policy", "grpc-advanced-streaming");
|
||||
|
||||
assertThat(
|
||||
GrpcPlatformStartupValidator.violations(
|
||||
productionProperties(), healthyCatalog(), oneChannel(), leaked))
|
||||
.anySatisfy(violation -> assertThat(violation).contains("grpc-advanced-streaming"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a refusal names every violation at once")
|
||||
void aRefusalNamesEveryViolation() {
|
||||
@@ -231,9 +203,7 @@ class GrpcPlatformStartupValidatorTest {
|
||||
broken.setExecutorQueueCapacity(0);
|
||||
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
GrpcPlatformStartupValidator.requireValid(
|
||||
broken, healthyCatalog(), oneChannel(), STABLE_DEPENDENCIES))
|
||||
() -> GrpcPlatformStartupValidator.requireValid(broken, healthyCatalog(), oneChannel()))
|
||||
.isInstanceOf(GrpcPlatformConfigurationException.class)
|
||||
.satisfies(
|
||||
failure ->
|
||||
|
||||
Reference in New Issue
Block a user