Merge branch 'refactor/review-followup': 리뷰 후속 Wave 1–3(보안·정합성·구조)

2026-09-24 리뷰 두 건의 후속 반영. Wave 1(보안·데이터), Wave 2(정합성), Wave 2.5, Wave 3(구조) 완료.
현황표 docs/reviews/2026-09-25-review-followup-status.md: 완료 606 · 해당 없음 133 · 보류 5 · 남음 173(W4 테스트 규칙 63 · W5 문서 110).
Wave 3 종료 검증 전부 통과(check · ci · mainCheck · integrationCheck · build-logic · optional-platforms · releaseCheck).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-29 17:02:03 +09:00
co-authored by Claude Opus 5.5
345 changed files with 2386 additions and 6329 deletions
+2 -2
View File
@@ -1,7 +1,7 @@
# Optional gRPC platforms
The default application does not depend on `grpc/*` or `grpc-advanced/*`, so those 18 projects are
kept out of the main multi-project build. This build preserves their existing project paths and
The default application does not depend on `grpc/*` or `grpc-advanced/*`, so those projects (the
registry entries with `"build": "optional-grpc"`) are kept out of the main multi-project build. This build preserves their existing project paths and
internal project dependencies while making their configuration opt-in.
```bash
+6 -10
View File
@@ -1,16 +1,10 @@
plugins {
id 'ca.architecture'
// Without it every gRPC leaf's jar is versioned 0.0.1-SNAPSHOT, because JavaConventionsPlugin
// falls back to that when the root has no ReleaseProvenanceExtension — so one commit produced
// two artifact sets under two different version schemes, and only one of them could be traced
// back to a revision.
id 'ca.release-provenance'
}
ext.sourceRevision = providers.gradleProperty('gitRevision')
.orElse(providers.environmentVariable('GIT_SHA'))
.orElse(providers.environmentVariable('GITHUB_SHA'))
.getOrElse('unknown')
// No `ca.release-provenance` any more: each gRPC leaf's `ca.java-conventions` derives its version
// and `sourceRevision` from the same -PreleaseVersion/-PgitRevision (GIT_SHA, GITHUB_SHA) inputs the
// main build reads, so one commit produces one version scheme in both builds (review BUILD-O3-5).
tasks.register('resolveAndLockAll') {
group = 'build setup'
@@ -35,7 +29,9 @@ tasks.register('ci') {
description = 'Runs the optional gRPC platform verification surface.'
dependsOn tasks.named('checkAll')
dependsOn tasks.named('qualityCheck')
dependsOn tasks.named('verifyCleanArchitectureDependencies')
// architectureCheck, not only the direction gate: it also runs verifyNoIgnoredSourcePackages, so
// a gRPC source Git would drop fails this build's ci the way it fails the main build's.
dependsOn tasks.named('architectureCheck')
}
// A strict integration lane that no workflow invokes is not coverage; it is a file that looks like
@@ -1,8 +1,17 @@
# ADR-GRPC-002: Schema governance runs without protoc and without the Buf CLI
- Status: accepted
- Status: **superseded (2026-09-28)** by owner decision 18 of the 2026-09-25 review follow-up
- Date: 2026-08-30
- Scope: `:grpc:grpc-proto-contract`, `:grpc:grpc-codegen`
- Scope: `:grpc:grpc-proto-contract`, `:grpc:grpc-codegen` (both removed)
> **Superseded.** The regex `.proto` validator and the Java re-implementation of Buf's rules were
> deleted. The schema now lives in `:grpc:grpc-contract` (`src/grpc/grpc-contract/src/main/proto`),
> compiled by the Gradle protobuf plugin (`com.google.protobuf`, version pinned in
> `src/gradle/libs.versions.toml`; protoc and the protobuf-java runtime are both `protobufGrpc`).
> Generated sources are excluded from Spotless, Checkstyle and Error Prone in that leaf only.
> `buf lint` and `buf breaking` (`src/grpc/grpc-contract/buf.yaml`, STANDARD lint, FILE breaking)
> run in CI, job `grpc-proto-buf` in `.github/workflows/ci-quality-gates.yml`. The proto organization
> is `caskeleton` (was `hyeonworks`). The text below is kept as the record of the original decision.
## Context
@@ -2,7 +2,7 @@
- Status: accepted
- Date: 2026-08-30
- Scope: `:grpc:grpc-core-api`, `:grpc:grpc-policy`, `:grpc:grpc-testkit`
- Scope: `:grpc:grpc-core-api`, `:grpc:grpc-runtime` (was `grpc-policy`), `:grpc:grpc-testkit`
## Context
@@ -2,7 +2,7 @@
- Status: accepted
- Date: 2026-08-30
- Scope: `:grpc:grpc-policy`, `:grpc:grpc-operation-ledger-jpa`, `:grpc:grpc-core-api`
- Scope: `:grpc:grpc-runtime` (was `grpc-policy`), `:grpc:grpc-operation-ledger-jpa`, `:grpc:grpc-core-api`
## Context
@@ -2,7 +2,7 @@
- Status: accepted
- Date: 2026-08-30
- Scope: `:grpc:grpc-policy`
- Scope: `:grpc:grpc-runtime` (was `grpc-policy`)
## Context
@@ -2,7 +2,7 @@
- Status: accepted
- Date: 2026-08-31
- Scope: `:grpc:grpc-discovery`, `:grpc:grpc-client`
- Scope: `:grpc:grpc-runtime` (was `grpc-discovery`, `grpc-client`)
## Context
@@ -63,6 +63,6 @@ declaration is a wrong statement somebody wrote down, and a missing one is a que
`GrpcChannelProfileValidator` takes resolved counts where they are known at startup and skips the
check where they are not, rather than guessing and failing on a name that cannot be resolved yet.
**xDS is reachable, and not by this route.** It lives in `grpc-advanced-resilience` behind its
**xDS is reachable, and not by this route.** It lives in `grpc-advanced` (package `resilience`/`xds`) behind its
capability flag and its production approval, and `GrpcXdsStartupGuard.advertisableAsStableSupport()`
returns false so the Stable support statement cannot widen quietly. See ADR-GRPC-ADV-001.
@@ -29,7 +29,9 @@ production unapproved — because the remedy differs in each case.
**Promotion evidence is per capability.** `GrpcAdvancedPromotionEvidence` is one record per
capability, so no promotion can drag another along;
`GrpcAdvancedPromotionGate.capabilitiesDraggedAlong` returns an empty list, and that is a tested
property rather than a claim. Two thresholds: seven days of soak plus complete evidence for
property rather than a claim. (2026-09-28: the gate classes were removed because nothing outside
their own tests called them — review 2026-09-24 S5-lead-4. The per-capability rule stands as a
review rule in `docs/runbooks/grpc-advanced-capabilities.md`.) Two thresholds: seven days of soak plus complete evidence for
`ADVANCED_STABLE`, thirty for a Stable default, because the second means every deployment gets the
capability's dependencies and its failure modes.
@@ -4,7 +4,7 @@ Every capability in `:grpc-advanced:*`, its grade, and what it would take to rai
`GrpcAdvancedSupportMatrix` is the machine-readable form; `GrpcAdvancedCapability.defaultGrade`
carries the same values.
All capabilities are off by default. Flags are `ca-skeleton.grpc.advanced.<capability>.enabled`.
All capabilities are off by default. Flags are `app.grpc.advanced.<capability>.enabled`.
## Grades
@@ -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
+10 -8
View File
@@ -4,8 +4,10 @@ What the Stable gRPC platform (`:grpc:*`) is certified against, what it is only
what is merely watched. The distinction is the point: "works with Spring Boot" is not a statement
anyone can act on.
`GrpcCompatibilityMatrix.caSkeleton()` is the machine-readable form of this table, and
`GrpcStableReleaseGate` blocks a release when a certified lane has no result or a failing one.
The release gate is the `grpc-stable-release-gate` job in `.github/workflows/release.yml`: each
certified lane is a strict test lane that fails when it runs nothing. The in-code
`GrpcCompatibilityMatrix`/`GrpcStableReleaseGate` pair was removed (review 2026-09-24 S5-lead-4):
no production or build code called it, so it gated nothing.
## Lanes
@@ -53,13 +55,13 @@ tested the adapter and not the transport.
| | Where it lives |
| --- | --- |
| Client streaming, bidirectional streaming | `grpc-advanced-streaming` |
| Manual flow control | `grpc-advanced-streaming` |
| Hedging | `grpc-advanced-resilience` |
| Custom name resolver, custom load balancer | `grpc-advanced-resilience` |
| xDS | `grpc-advanced-resilience` |
| Client streaming, bidirectional streaming | `grpc-advanced` (`streaming`) |
| Manual flow control | `grpc-advanced` (`streaming`) |
| Hedging | `grpc-advanced` (`resilience`) |
| Custom name resolver, custom load balancer | `grpc-advanced` (`resilience`) |
| xDS | `grpc-advanced` (`resilience`) |
| gRPC-Web, Servlet HTTP/2, Spring Integration, Reactor, Kotlin | `grpc-advanced-compat` |
| Channelz / CSDS diagnostics | `grpc-advanced-diagnostics` |
| Channelz / CSDS diagnostics | `grpc-advanced` (`diagnostics`) |
## Current release status
@@ -39,6 +39,13 @@ src/adapter/inbound/grpc 기존 인바운드 전송 어댑터 (
원본 모듈 경계 중 **이 저장소가 이미 다른 메커니즘으로 표현하는 것**만 합친다. 능력(capability)은
하나도 버리지 않는다.
> **2026-09-28 변경(리뷰 후속 S7-#3·S7-#13, 소유자 결정 18).** 아래 두 표는 채택 당시의 leaf 구성이다.
> 현재는 `grpc-policy`·`grpc-server`·`grpc-client`·`grpc-discovery`·`grpc-admin` → `grpc-runtime`,
> `grpc-proto-contract`·`grpc-codegen` → `grpc-contract`(protobuf Gradle 플러그인 + CI의 Buf, D5/D6 폐기 —
> ADR-GRPC-002 superseded), `grpc-advanced-bootstrap`·`-edition`·`-streaming`·`-resilience`·`-diagnostics`
> → `grpc-advanced`로 합쳐졌다. `grpc-advanced-compat`은 그대로다. 패키지 이름은 바뀌지 않았다. 현재
> leaf 목록은 registry(`src/config/architecture/modules.json`)가 SSOT다.
### Stable — `src/grpc/`
| leaf | 원본 모듈 | 담는 Task | 의존 |
+14 -18
View File
@@ -3,7 +3,7 @@
Scope: the `:grpc-advanced:*` family. Everything here is off by default and stays off until a
deployment names it. Nothing in this family ships in a runtime composition today.
Flags are `ca-skeleton.grpc.advanced.<capability>.enabled`. `GrpcAdvancedCapability` owns the list of
Flags are `app.grpc.advanced.<capability>.enabled`. `GrpcAdvancedCapability` owns the list of
capability names; `GrpcAdvancedSupportMatrix` owns their current grades.
---
@@ -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.
@@ -86,13 +84,11 @@ rather than retrying a failure.
## Promoting a capability
`GrpcAdvancedPromotionGate.evaluate` names every missing item. Promotion to `ADVANCED_STABLE` needs
compatibility evidence, a security review, fault evidence, performance evidence, an ADR, a runbook, a
real-environment test and seven days of soak. A Stable default needs thirty.
Promotion to `ADVANCED_STABLE` needs compatibility evidence, a security review, fault evidence,
performance evidence, an ADR, a runbook, a real-environment test and seven days of soak. A Stable
default needs thirty. Promotions are independent: promoting one capability changes no other's
grade. This is a review checklist; the in-code `GrpcAdvancedPromotionGate` that restated it was
removed (review 2026-09-24 S5-lead-4) because nothing but its own test called it.
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.
+4 -4
View File
@@ -5,8 +5,8 @@ empty — so nothing here fires in production yet. It is written now because the
the ones an on-call cannot work out from first principles at three in the morning, and shipping the
behaviour before the runbook means the first person to meet one is doing that.
Configuration lives under `ca-skeleton.grpc.platform.*` and is bound by `GrpcPlatformProperties`.
The platform does not start unless `ca-skeleton.grpc.platform.enabled=true`.
Configuration lives under `app.grpc.platform.*` and is bound by `GrpcPlatformProperties`.
The platform does not start unless `app.grpc.platform.enabled=true`.
---
@@ -94,7 +94,7 @@ capacity on nothing.
means the bottleneck is admission, not the work.
2. Check which saturation counter is moving — executor, channel or flow control. They look identical
in a latency graph and have different fixes.
3. Raising `ca-skeleton.grpc.platform.executor-queue-capacity` defers the problem; it does not remove
3. Raising `app.grpc.platform.executor-queue-capacity` defers the problem; it does not remove
it. `GrpcExecutorProfile` refuses a queue above ten thousand for that reason.
---
@@ -138,5 +138,5 @@ construction rather than redacted.
- **Reflection in production.** `GrpcReflectionMode.defaultFor` returns `DISABLED` for `STAGE` and
`PROD`. Reflection publishes the whole schema to anyone who can open a connection.
- **Every advanced capability.** See `docs/runbooks/grpc-advanced-capabilities.md`.
- **The platform itself.** `ca-skeleton.grpc.platform.enabled` defaults to false, and every `:grpc:*`
- **The platform itself.** `app.grpc.platform.enabled` defaults to false, and every `:grpc:*`
leaf is build-only in the registry.
+24 -19
View File
@@ -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
@@ -32,46 +31,52 @@ capability마다 별도 flag를 갖는다. 하나의 "advanced" 스위치로 묶
| `WATCH` | X (추적만) | — |
| `DISABLED` | X | — |
property key는 `ca-skeleton.grpc.advanced.<capability>.enabled`이고 전부 기본 off다.
property key는 `app.grpc.advanced.<capability>.enabled`이고 전부 기본 off다.
`GrpcAdvancedModuleGuard`가 세 조건(flag 미설정 / grade가 시작 불가 / production 승인 없음)을
구분해서 거부하며, 세 경우의 조치가 다르므로 메시지도 다르다.
## Leaf별 담당 capability
| leaf | capability |
| --- | --- |
| `grpc-advanced-bootstrap` | capability grade, feature flag, module guard, capability별 promotion gate |
| `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 요구사항 |
| leaf | 패키지(`dev.caskeleton.grpc.advanced.*`) | capability |
| --- | --- | --- |
| `grpc-advanced` | `bootstrap` | capability grade, feature flag, module guard, capability별 promotion gate |
| `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`·`discovery`·`xds` | read-only hedging, custom name resolver SPI, custom load balancer SPI, proxyless xDS |
| `grpc-advanced` | `diagnostics` | Channelz/CSDS 진단 |
| `grpc-advanced-compat` | `web`·`integration`·`reactor`·`kotlin` | gRPC-Web, Spring Integration bridge, Reactor adapter, Kotlin coroutine 취소 bridge |
`grpc-advanced-compat`만 따로 있는 이유는 Reactor·Spring Integration이라는 실제 의존성 경계다. 나머지
다섯 capability는 framework 의존이 없어 한 leaf에 있다(2026-09-28까지는 leaf 다섯 개). capability별
독립은 leaf 경계가 아니라 capability flag와 promotion 레코드가 보장한다. 참조 Envoy 설정은 jar에 싣지
않는 테스트 fixture(`grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`)다.
## Promotion은 capability별로 독립이다
`GrpcAdvancedPromotionEvidence`는 capability마다 별도 레코드다. 공유 레코드였다면 하나를 승격할 때
같은 시점에 측정된 다른 것들이 함께 승격된다. `GrpcAdvancedPromotionGate.capabilitiesDraggedAlong`이
항상 빈 리스트인 것은 주석이 아니라 테스트되는 속성이다.
승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른
것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고
호출처가 없어 삭제했다(리뷰 2026-09-24 S5-lead-4). 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의
리뷰 규칙이다.
승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가
더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다.
## 이 저장소에서 검증할 수 없는 것
`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로 인용하는 것.
@@ -1,14 +0,0 @@
plugins {
id 'ca.platform-module'
}
// The Advanced boundary itself: capability grades, the `ca-skeleton.grpc.advanced.*` feature-flag
// contract, the module guard that refuses an unflagged capability, and the per-capability
// promotion gate.
//
// This leaf depends on Stable public types and never the other way round. The Stable starter's
// registry entry names no advanced id, so `verifyCleanArchitectureDependencies` is what makes
// "Advanced never leaks into Stable" a build failure rather than a review note.
dependencies {
api project(':grpc:grpc-core-api')
}
@@ -1,84 +0,0 @@
# This is a Gradle generated file for dependency locking.
# Manual edits can break the build and are not advised.
# This file is expected to be part of source control.
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
com.github.spotbugs:spotbugs:4.10.2=spotbugs
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs
com.google.code.gson:gson:2.13.2=spotbugs
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
com.google.guava:guava:33.6.0-jre=checkstyle
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
commons-beanutils:commons-beanutils:1.11.0=checkstyle
commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.21.0=spotbugs
info.picocli:picocli:4.7.7=checkstyle
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
org.antlr:antlr4-runtime:4.13.2=checkstyle
org.apache.bcel:bcel:6.12.0=spotbugs
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
org.apache.commons:commons-text:1.15.0=spotbugs
org.apache.commons:commons-text:1.3=checkstyle
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
org.apache.logging.log4j:log4j-api:2.25.5=spotbugs
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
org.apache.xbean:xbean-reflect:3.7=checkstyle
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
org.dom4j:dom4j:2.2.0=spotbugs
org.javassist:javassist:3.28.0-GA=checkstyle
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit:junit-bom:6.1.0=spotbugs
org.mockito:mockito-core:5.20.0=mockitoAgent
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
org.ow2.asm:asm-analysis:9.10.1=spotbugs
org.ow2.asm:asm-commons:9.10.1=spotbugs
org.ow2.asm:asm-tree:9.10.1=spotbugs
org.ow2.asm:asm-util:9.10.1=spotbugs
org.ow2.asm:asm:9.10.1=spotbugs
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
org.reflections:reflections:0.10.2=checkstyle
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
empty=compileClasspath,runtimeClasspath
@@ -1,50 +0,0 @@
package dev.caskeleton.grpc.advanced.release;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcCapabilityGrade;
import java.util.List;
/**
* Whether one capability moves to a new grade.
*
* <p>Carries the grade it would move to as well as the blockers, so a refusal says what was being
* asked for. "Not promoted" is ambiguous between a failed promotion to Advanced Stable and a failed
* promotion to a Stable default, and the second is a much larger decision.
*/
public record GrpcAdvancedPromotionDecision(
GrpcAdvancedCapability capability,
GrpcCapabilityGrade from,
GrpcCapabilityGrade to,
boolean promoted,
List<String> blockers) {
/** Requires blockers exactly when refused. */
public GrpcAdvancedPromotionDecision {
if (capability == null || from == null || to == null || blockers == null) {
throw new IllegalArgumentException(
"a promotion decision names its capability and both grades");
}
blockers = List.copyOf(blockers);
if (promoted && !blockers.isEmpty()) {
throw new IllegalArgumentException("a granted promotion has no blockers");
}
if (!promoted && blockers.isEmpty()) {
throw new IllegalArgumentException("a refused promotion says why");
}
}
/** A granted promotion. */
public static GrpcAdvancedPromotionDecision grant(
GrpcAdvancedCapability capability, GrpcCapabilityGrade from, GrpcCapabilityGrade to) {
return new GrpcAdvancedPromotionDecision(capability, from, to, true, List.of());
}
/** A refused promotion. */
public static GrpcAdvancedPromotionDecision refuse(
GrpcAdvancedCapability capability,
GrpcCapabilityGrade from,
GrpcCapabilityGrade to,
List<String> blockers) {
return new GrpcAdvancedPromotionDecision(capability, from, to, false, blockers);
}
}
@@ -1,75 +0,0 @@
package dev.caskeleton.grpc.advanced.release;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
import java.time.Duration;
import java.util.Set;
/**
* What one capability has behind it.
*
* <p>Per capability, never shared. The Stable plan's requirement that Edition, streaming, xDS,
* gRPC-Web, Servlet and the language adapters do not gate each other only means something if their
* evidence is separate: a shared record makes promoting one of them promote whichever others
* happened to be measured at the same time.
*/
public record GrpcAdvancedPromotionEvidence(
GrpcAdvancedCapability capability,
boolean compatibilityEvidence,
boolean securityReview,
boolean faultEvidence,
boolean performanceEvidence,
Duration soakDuration,
boolean architectureDecisionRecord,
boolean runbook,
boolean realEnvironmentTest) {
/** Requires a capability and a non-negative soak. */
public GrpcAdvancedPromotionEvidence {
if (capability == null) {
throw new IllegalArgumentException("promotion evidence names its capability");
}
if (soakDuration == null || soakDuration.isNegative()) {
throw new IllegalArgumentException("a soak duration must be present and non-negative");
}
}
/** No evidence at all, which is where a capability starts. */
public static GrpcAdvancedPromotionEvidence none(GrpcAdvancedCapability capability) {
return new GrpcAdvancedPromotionEvidence(
capability, false, false, false, false, Duration.ZERO, false, false, false);
}
/** Everything a promotion to Advanced Stable needs. */
public static GrpcAdvancedPromotionEvidence complete(
GrpcAdvancedCapability capability, Duration soakDuration) {
return new GrpcAdvancedPromotionEvidence(
capability, true, true, true, true, soakDuration, true, true, true);
}
/** Which required items are absent, as a set a report can print. */
public Set<String> missing() {
Set<String> missing = new java.util.LinkedHashSet<>();
if (!compatibilityEvidence) {
missing.add("compatibility evidence");
}
if (!securityReview) {
missing.add("security review");
}
if (!faultEvidence) {
missing.add("fault evidence");
}
if (!performanceEvidence) {
missing.add("performance evidence");
}
if (!architectureDecisionRecord) {
missing.add("architecture decision record");
}
if (!runbook) {
missing.add("runbook");
}
if (!realEnvironmentTest) {
missing.add("real environment test");
}
return Set.copyOf(missing);
}
}
@@ -1,85 +0,0 @@
package dev.caskeleton.grpc.advanced.release;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcCapabilityGrade;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
/**
* Decides one capability's promotion, on its own evidence.
*
* <p>Two thresholds rather than one. Reaching Advanced Stable means the capability works and is
* documented; becoming a Stable default means every deployment gets it, which additionally puts its
* dependencies on every classpath and its failure modes in every on-call rotation. The second needs
* the first plus a longer soak, because a capability that has run in one deployment for a week is
* not the same claim as one that ships to all of them.
*/
public final class GrpcAdvancedPromotionGate {
/** The soak a promotion to Advanced Stable requires. */
public static final Duration ADVANCED_STABLE_SOAK = Duration.ofDays(7);
/** The soak a promotion to a Stable default requires. */
public static final Duration STABLE_DEFAULT_SOAK = Duration.ofDays(30);
private GrpcAdvancedPromotionGate() {}
/**
* Whether {@code capability} may move from {@code from} to {@code to}.
*
* @throws IllegalArgumentException when the transition is not one this gate governs
*/
public static GrpcAdvancedPromotionDecision evaluate(
GrpcAdvancedPromotionEvidence evidence, GrpcCapabilityGrade from, GrpcCapabilityGrade to) {
if (evidence == null || from == null || to == null) {
throw new IllegalArgumentException("a promotion needs evidence and both grades");
}
if (from == to) {
throw new IllegalArgumentException("a promotion changes the grade");
}
GrpcAdvancedCapability capability = evidence.capability();
List<String> blockers = new ArrayList<>();
evidence.missing().stream()
.sorted()
.forEach(missing -> blockers.add(capability.flagName() + " has no " + missing));
Duration requiredSoak =
to == GrpcCapabilityGrade.ADVANCED_STABLE ? ADVANCED_STABLE_SOAK : STABLE_DEFAULT_SOAK;
if (evidence.soakDuration().compareTo(requiredSoak) < 0) {
blockers.add(
capability.flagName()
+ " soaked for "
+ evidence.soakDuration().toDays()
+ " day(s); promotion to "
+ to
+ " requires "
+ requiredSoak.toDays());
}
if (from == GrpcCapabilityGrade.WATCH && to != GrpcCapabilityGrade.EXPERIMENTAL) {
blockers.add(
capability.flagName()
+ " is WATCH, which is tracked rather than implemented; it becomes EXPERIMENTAL "
+ "before anything else");
}
return blockers.isEmpty()
? GrpcAdvancedPromotionDecision.grant(capability, from, to)
: GrpcAdvancedPromotionDecision.refuse(capability, from, to, blockers);
}
/**
* Whether promoting {@code promoted} would drag another capability with it.
*
* <p>Always empty, and the method exists so a test can assert that rather than a comment claiming
* it: each capability's evidence is its own record, so there is no path by which one promotion
* changes another's grade.
*/
public static List<GrpcAdvancedCapability> capabilitiesDraggedAlong(
GrpcAdvancedCapability promoted) {
if (promoted == null) {
throw new IllegalArgumentException("a capability is required");
}
return List.of();
}
}
@@ -1,66 +0,0 @@
package dev.caskeleton.grpc.advanced.release;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcCapabilityGrade;
import java.util.EnumMap;
import java.util.Map;
/**
* Every advanced capability's current grade, in one place an adopter can read.
*
* <p>The published answer to "is this supported". Without it the answer is inferred from whether a
* class exists, which says only that somebody wrote it.
*/
public final class GrpcAdvancedSupportMatrix {
private final Map<GrpcAdvancedCapability, GrpcCapabilityGrade> grades =
new EnumMap<>(GrpcAdvancedCapability.class);
/** A matrix at each capability's default grade. */
public GrpcAdvancedSupportMatrix() {
for (GrpcAdvancedCapability capability : GrpcAdvancedCapability.values()) {
grades.put(capability, capability.defaultGrade());
}
}
/** The grade of one capability. */
public GrpcCapabilityGrade gradeOf(GrpcAdvancedCapability capability) {
if (capability == null) {
throw new IllegalArgumentException("a capability is required");
}
return grades.get(capability);
}
/**
* Applies a granted promotion.
*
* @throws IllegalArgumentException when the decision's starting grade is not the current one,
* which means two promotions raced or one was replayed
*/
public GrpcAdvancedSupportMatrix apply(GrpcAdvancedPromotionDecision decision) {
if (decision == null) {
throw new IllegalArgumentException("a decision is required");
}
if (!decision.promoted()) {
return this;
}
GrpcCapabilityGrade current = grades.get(decision.capability());
if (current != decision.from()) {
throw new IllegalArgumentException(
"capability '"
+ decision.capability().flagName()
+ "' is "
+ current
+ ", not "
+ decision.from()
+ "; this decision was made against a different matrix");
}
grades.put(decision.capability(), decision.to());
return this;
}
/** The whole matrix. */
public Map<GrpcAdvancedCapability, GrpcCapabilityGrade> snapshot() {
return Map.copyOf(grades);
}
}
@@ -1,150 +0,0 @@
package dev.caskeleton.grpc.advanced.release;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcCapabilityGrade;
import java.time.Duration;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
class GrpcAdvancedPromotionGateTest {
@Test
@DisplayName("a capability with complete evidence and a full soak is promoted")
void completeEvidencePromotes() {
GrpcAdvancedPromotionDecision decision =
GrpcAdvancedPromotionGate.evaluate(
GrpcAdvancedPromotionEvidence.complete(
GrpcAdvancedCapability.HEDGING, Duration.ofDays(7)),
GrpcCapabilityGrade.EXPERIMENTAL,
GrpcCapabilityGrade.ADVANCED_STABLE);
assertThat(decision.promoted()).isTrue();
assertThat(decision.blockers()).isEmpty();
}
@Test
@DisplayName("every missing piece of evidence is named")
void everyMissingPieceIsNamed() {
GrpcAdvancedPromotionDecision decision =
GrpcAdvancedPromotionGate.evaluate(
GrpcAdvancedPromotionEvidence.none(GrpcAdvancedCapability.XDS),
GrpcCapabilityGrade.EXPERIMENTAL,
GrpcCapabilityGrade.ADVANCED_STABLE);
assertThat(decision.blockers())
.anySatisfy(blocker -> assertThat(blocker).contains("compatibility evidence"))
.anySatisfy(blocker -> assertThat(blocker).contains("security review"))
.anySatisfy(blocker -> assertThat(blocker).contains("fault evidence"))
.anySatisfy(blocker -> assertThat(blocker).contains("runbook"))
.anySatisfy(blocker -> assertThat(blocker).contains("real environment test"))
.anySatisfy(blocker -> assertThat(blocker).contains("soaked for"));
}
@Test
@DisplayName("becoming a Stable default needs a longer soak than becoming Advanced Stable")
void theStableDefaultThresholdIsHigher() {
GrpcAdvancedPromotionEvidence weekLongSoak =
GrpcAdvancedPromotionEvidence.complete(GrpcAdvancedCapability.GRPC_WEB, Duration.ofDays(7));
assertThat(
GrpcAdvancedPromotionGate.evaluate(
weekLongSoak,
GrpcCapabilityGrade.EXPERIMENTAL,
GrpcCapabilityGrade.ADVANCED_STABLE)
.promoted())
.isTrue();
assertThat(
GrpcAdvancedPromotionGate.evaluate(
weekLongSoak, GrpcCapabilityGrade.ADVANCED_STABLE, GrpcCapabilityGrade.DISABLED)
.blockers())
.anySatisfy(blocker -> assertThat(blocker).contains("requires 30"));
}
@Test
@DisplayName("a WATCH capability becomes EXPERIMENTAL before anything else")
void watchPromotesOnlyToExperimental() {
assertThat(
GrpcAdvancedPromotionGate.evaluate(
GrpcAdvancedPromotionEvidence.complete(
GrpcAdvancedCapability.EDITION_2026, Duration.ofDays(60)),
GrpcCapabilityGrade.WATCH,
GrpcCapabilityGrade.ADVANCED_STABLE)
.blockers())
.anySatisfy(blocker -> assertThat(blocker).contains("becomes EXPERIMENTAL"));
assertThat(
GrpcAdvancedPromotionGate.evaluate(
GrpcAdvancedPromotionEvidence.complete(
GrpcAdvancedCapability.EDITION_2026, Duration.ofDays(60)),
GrpcCapabilityGrade.WATCH,
GrpcCapabilityGrade.EXPERIMENTAL)
.promoted())
.isTrue();
}
@Test
@DisplayName("promoting one capability drags none of the others with it")
void promotionsAreIndependent() {
GrpcAdvancedSupportMatrix matrix = new GrpcAdvancedSupportMatrix();
GrpcCapabilityGrade webBefore = matrix.gradeOf(GrpcAdvancedCapability.GRPC_WEB);
matrix.apply(
GrpcAdvancedPromotionGate.evaluate(
GrpcAdvancedPromotionEvidence.complete(
GrpcAdvancedCapability.HEDGING, Duration.ofDays(7)),
GrpcCapabilityGrade.EXPERIMENTAL,
GrpcCapabilityGrade.ADVANCED_STABLE));
assertThat(matrix.gradeOf(GrpcAdvancedCapability.HEDGING))
.isEqualTo(GrpcCapabilityGrade.ADVANCED_STABLE);
assertThat(matrix.gradeOf(GrpcAdvancedCapability.GRPC_WEB)).isEqualTo(webBefore);
assertThat(GrpcAdvancedPromotionGate.capabilitiesDraggedAlong(GrpcAdvancedCapability.HEDGING))
.isEmpty();
}
@Test
@DisplayName("a decision made against a different matrix state is refused")
void aStaleDecisionIsRefused() {
GrpcAdvancedSupportMatrix matrix = new GrpcAdvancedSupportMatrix();
assertThatThrownBy(
() ->
matrix.apply(
GrpcAdvancedPromotionGate.evaluate(
GrpcAdvancedPromotionEvidence.complete(
GrpcAdvancedCapability.GRPC_WEB, Duration.ofDays(7)),
GrpcCapabilityGrade.EXPERIMENTAL,
GrpcCapabilityGrade.ADVANCED_STABLE)))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("made against a different matrix");
}
@Test
@DisplayName("a refused promotion leaves the matrix alone")
void aRefusedPromotionChangesNothing() {
GrpcAdvancedSupportMatrix matrix = new GrpcAdvancedSupportMatrix();
matrix.apply(
GrpcAdvancedPromotionGate.evaluate(
GrpcAdvancedPromotionEvidence.none(GrpcAdvancedCapability.XDS),
GrpcCapabilityGrade.EXPERIMENTAL,
GrpcCapabilityGrade.ADVANCED_STABLE));
assertThat(matrix.gradeOf(GrpcAdvancedCapability.XDS))
.isEqualTo(GrpcCapabilityGrade.EXPERIMENTAL);
}
@Test
@DisplayName("a promotion that changes nothing is refused")
void aNoOpPromotionIsRefused() {
assertThatThrownBy(
() ->
GrpcAdvancedPromotionGate.evaluate(
GrpcAdvancedPromotionEvidence.none(GrpcAdvancedCapability.XDS),
GrpcCapabilityGrade.EXPERIMENTAL,
GrpcCapabilityGrade.EXPERIMENTAL))
.isInstanceOf(IllegalArgumentException.class);
}
}
+11 -12
View File
@@ -1,21 +1,20 @@
plugins {
id 'ca.platform-module'
// grpc-platform, not platform: grpc-runtime's io.grpc api dependencies are versionless and
// need the gRPC BOM on every classpath they reach.
id 'ca.grpc-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.
//
// The reference Envoy configuration is a test fixture (src/test/resources/envoy), not something
// this jar ships: a proxy configuration belongs to the deployment that runs the proxy.
dependencies {
api project(':grpc:grpc-core-api')
api project(':grpc:grpc-policy')
api project(':grpc:grpc-server')
api project(':grpc:grpc-client')
api project(':grpc-advanced:grpc-advanced-bootstrap')
api project(':grpc:grpc-runtime')
// api: the Reactor adapter's public signatures are Mono/Flux, and the Integration gateways name
// Spring Integration's Message. Hiding either would only stop an adopter compiling against the
@@ -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;
}
}
@@ -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);
}
}
@@ -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());
}
}
@@ -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;
}
}
@@ -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;
}
}
@@ -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;
}
}
@@ -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() {
@@ -27,7 +27,7 @@ class GrpcIntegrationBridgePolicyTest {
private static final GrpcMetadataKey CORRELATION = GrpcMetadataKey.ascii("x-correlation-id");
private static final GrpcMethodName GET =
GrpcMethodName.parse("hyeonworks.document.v1.DocumentService/GetDocument");
GrpcMethodName.parse("caskeleton.document.v1.DocumentService/GetDocument");
private static GrpcRequestContext requestContext() {
return GrpcRequestContext.create(
@@ -28,7 +28,7 @@ import reactor.util.context.Context;
class GrpcReactorContextBridgeTest {
private static final GrpcMethodName GET =
GrpcMethodName.parse("hyeonworks.document.v1.DocumentService/GetDocument");
GrpcMethodName.parse("caskeleton.document.v1.DocumentService/GetDocument");
private static final Instant NOW = Instant.parse("2026-08-30T10:00:00Z");
private static GrpcContextSnapshot snapshot() {
@@ -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);
}
}
@@ -3,27 +3,23 @@ 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 dev.caskeleton.grpc.error.GrpcErrorMapper;
import dev.caskeleton.grpc.validation.GrpcValidationInterceptor;
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 java.util.regex.Matcher;
import java.util.regex.Pattern;
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 +33,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() {
@@ -130,9 +114,61 @@ class GrpcWebCompatibilityGateTest {
.contains("envoy.filters.http.grpc_web");
}
@Test
void theReferenceProxyExposesEveryTrailerThePlatformSends() {
// when
Set<String> exposed = headerList(resource("envoy/envoy.yaml"), "expose_headers");
// then
assertThat(exposed)
.contains(
"grpc-status",
"grpc-message",
"grpc-status-details-bin",
GrpcErrorMapper.REASON_KEY.name(),
GrpcErrorMapper.EXECUTION_ID_KEY.name(),
GrpcErrorMapper.COMPLETION_OUTCOME_KEY.name(),
GrpcValidationInterceptor.VIOLATIONS_KEY.name());
}
@Test
void theReferenceProxyLetsTheBrowserSendItsDeadlineAndClientHeaders() {
// when
Set<String> allowed = headerList(resource("envoy/envoy.yaml"), "allow_headers");
// then
assertThat(allowed).contains("grpc-timeout", "x-user-agent", "x-grpc-web", "content-type");
}
@Test
void theReferenceRouteLeavesStreamLengthToTheCallersDeadline() {
// when
String envoy = resource("envoy/envoy.yaml");
// then
assertThat(envoy).contains("timeout: 0s").contains("grpc_timeout_header_max: 0s");
}
@Test
void theReferenceProxyTerminatesTlsWithACertificate() {
// when
String envoy = resource("envoy/envoy.yaml");
// then
assertThat(envoy).contains("certificate_chain:").contains("private_key:");
}
private static Set<String> headerList(String envoy, String field) {
Matcher matcher = Pattern.compile(field + ": \"([^\"]*)\"").matcher(envoy);
if (!matcher.find()) {
throw new IllegalStateException("the reference proxy has no " + field);
}
return Set.of(matcher.group(1).split(","));
}
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);
}
@@ -29,13 +29,18 @@ static_resources:
- match: { prefix: "/" }
route:
cluster: grpc_backend
timeout: 30s
# No route timeout: it would cut every server stream at that age. The
# caller's grpc-timeout header bounds each call instead.
timeout: 0s
max_stream_duration:
grpc_timeout_header_max: 0s
cors:
allow_origin_string_match:
- exact: "https://app.example.com"
allow_methods: "POST,OPTIONS"
allow_headers: "content-type,x-grpc-web,x-correlation-id,authorization"
expose_headers: "grpc-status,grpc-message,error-code,error-category"
allow_headers: "content-type,x-grpc-web,x-user-agent,grpc-timeout,x-correlation-id,authorization"
# Every trailer the platform sends (GrpcErrorMapper, GrpcValidationInterceptor).
expose_headers: "grpc-status,grpc-message,grpc-status-details-bin,error-reason,error-execution-id,completion-outcome,validation-violations"
max_age: "1728000"
http_filters:
- name: envoy.filters.http.grpc_web
@@ -51,6 +56,11 @@ static_resources:
name: envoy.transport_sockets.tls
typed_config:
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
# Placeholder paths: mount the proxy's certificate and key here.
common_tls_context:
tls_certificates:
- certificate_chain: { filename: /etc/envoy/tls/tls.crt }
private_key: { filename: /etc/envoy/tls/tls.key }
clusters:
- name: grpc_backend
connect_timeout: 1s
@@ -1,12 +0,0 @@
plugins {
id 'ca.platform-module'
}
// 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).
dependencies {
api project(':grpc:grpc-core-api')
api project(':grpc:grpc-client')
api project(':grpc-advanced:grpc-advanced-bootstrap')
}
@@ -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);
}
}
@@ -1,12 +0,0 @@
plugins {
id 'ca.platform-module'
}
// 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.
dependencies {
api project(':grpc:grpc-core-api')
api project(':grpc:grpc-proto-contract')
api project(':grpc-advanced:grpc-advanced-bootstrap')
}
@@ -1,84 +0,0 @@
# This is a Gradle generated file for dependency locking.
# Manual edits can break the build and are not advised.
# This file is expected to be part of source control.
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
com.github.spotbugs:spotbugs:4.10.2=spotbugs
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs
com.google.code.gson:gson:2.13.2=spotbugs
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
com.google.guava:guava:33.6.0-jre=checkstyle
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
commons-beanutils:commons-beanutils:1.11.0=checkstyle
commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.21.0=spotbugs
info.picocli:picocli:4.7.7=checkstyle
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
org.antlr:antlr4-runtime:4.13.2=checkstyle
org.apache.bcel:bcel:6.12.0=spotbugs
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
org.apache.commons:commons-text:1.15.0=spotbugs
org.apache.commons:commons-text:1.3=checkstyle
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
org.apache.logging.log4j:log4j-api:2.25.5=spotbugs
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
org.apache.xbean:xbean-reflect:3.7=checkstyle
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
org.dom4j:dom4j:2.2.0=spotbugs
org.javassist:javassist:3.28.0-GA=checkstyle
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit:junit-bom:6.1.0=spotbugs
org.mockito:mockito-core:5.20.0=mockitoAgent
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
org.ow2.asm:asm-analysis:9.10.1=spotbugs
org.ow2.asm:asm-commons:9.10.1=spotbugs
org.ow2.asm:asm-tree:9.10.1=spotbugs
org.ow2.asm:asm-util:9.10.1=spotbugs
org.ow2.asm:asm:9.10.1=spotbugs
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
org.reflections:reflections:0.10.2=checkstyle
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
empty=compileClasspath,runtimeClasspath
@@ -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;
}
}
@@ -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,13 +0,0 @@
plugins {
id 'ca.platform-module'
}
// Resilience and discovery capabilities that Stable refuses: read-only unary hedging, the custom
// name resolver SPI, the custom load balancer SPI, and the proxyless xDS experimental profile.
dependencies {
api project(':grpc:grpc-core-api')
api project(':grpc:grpc-policy')
api project(':grpc:grpc-client')
api project(':grpc:grpc-discovery')
api project(':grpc-advanced:grpc-advanced-bootstrap')
}
@@ -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;
}
}
@@ -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"]
}
]
}
}
}
@@ -1,12 +0,0 @@
plugins {
id 'ca.platform-module'
}
// The streaming shapes the Stable plan deliberately excludes: client streaming sessions with
// dedup/checkpoint/resume, bidirectional sessions with independent per-direction sequences, and the
// manual flow-control approval API.
dependencies {
api project(':grpc:grpc-core-api')
api project(':grpc:grpc-policy')
api project(':grpc-advanced:grpc-advanced-bootstrap')
}
@@ -1,91 +0,0 @@
# This is a Gradle generated file for dependency locking.
# Manual edits can break the build and are not advised.
# This file is expected to be part of source control.
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
com.github.spotbugs:spotbugs:4.10.2=spotbugs
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
com.google.code.findbugs:jsr305:3.0.2=checkstyle,compileClasspath,runtimeClasspath,spotbugs,testCompileClasspath,testRuntimeClasspath
com.google.code.gson:gson:2.13.2=spotbugs
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_annotations:2.28.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
com.google.guava:failureaccess:1.0.2=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.guava:guava:33.2.1-android=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
com.google.guava:guava:33.6.0-jre=checkstyle
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
com.google.j2objc:j2objc-annotations:3.0.0=compileClasspath,testCompileClasspath
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
commons-beanutils:commons-beanutils:1.11.0=checkstyle
commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.21.0=spotbugs
info.picocli:picocli:4.7.7=checkstyle
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
io.grpc:grpc-api:1.68.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.grpc:grpc-stub:1.68.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
org.antlr:antlr4-runtime:4.13.2=checkstyle
org.apache.bcel:bcel:6.12.0=spotbugs
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
org.apache.commons:commons-text:1.15.0=spotbugs
org.apache.commons:commons-text:1.3=checkstyle
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
org.apache.logging.log4j:log4j-api:2.25.5=spotbugs
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
org.apache.xbean:xbean-reflect:3.7=checkstyle
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
org.checkerframework:checker-qual:3.42.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
org.dom4j:dom4j:2.2.0=spotbugs
org.javassist:javassist:3.28.0-GA=checkstyle
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit:junit-bom:6.1.0=spotbugs
org.mockito:mockito-core:5.20.0=mockitoAgent
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
org.ow2.asm:asm-analysis:9.10.1=spotbugs
org.ow2.asm:asm-commons:9.10.1=spotbugs
org.ow2.asm:asm-tree:9.10.1=spotbugs
org.ow2.asm:asm-util:9.10.1=spotbugs
org.ow2.asm:asm:9.10.1=spotbugs
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
org.reflections:reflections:0.10.2=checkstyle
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
empty=
+28
View File
@@ -0,0 +1,28 @@
plugins {
// grpc-platform, not platform: grpc-runtime's io.grpc api dependencies are versionless and
// need the gRPC BOM on every classpath they reach.
id 'ca.grpc-platform-module'
}
// The capabilities the Stable platform deliberately excludes, each behind its own capability flag:
//
// bootstrap capability grades, the `app.grpc.advanced.*` feature-flag contract, the
// module guard that refuses an unflagged capability, the per-capability promotion
// gate
// edition Protobuf Edition 2024 opt-in lane and Edition 2026 watch lane
// streaming client streaming sessions (dedup/checkpoint/resume), bidirectional sessions with
// independent per-direction sequences, the manual flow-control approval API
// resilience read-only unary hedging, custom name resolver / load balancer SPIs, proxyless xDS
// diagnostics Channelz/CSDS snapshots and the redactor that keeps secrets out of them
//
// These were five leaves until 2026-09-28. None of them carried a framework dependency of its own,
// and the only rule the split enforced — Stable never reaches Advanced — is expressed by the
// registry through the two prefixes (`grpc:*` may not depend on `grpc-advanced:*`), not by how many
// advanced leaves exist. `grpc-advanced-compat` stays separate because Reactor and Spring
// Integration are a real dependency boundary.
//
// This leaf depends on Stable public types and never the other way round.
dependencies {
api project(':grpc:grpc-core-api')
api project(':grpc:grpc-runtime')
}
@@ -48,14 +48,14 @@ public enum GrpcAdvancedCapability {
this.defaultGrade = defaultGrade;
}
/** The property suffix under {@code ca-skeleton.grpc.advanced}. */
/** The property suffix under {@code app.grpc.advanced}. */
public String flagName() {
return flagName;
}
/** The full property key that enables this capability. */
public String propertyKey() {
return "ca-skeleton.grpc.advanced." + flagName + ".enabled";
return "app.grpc.advanced." + flagName + ".enabled";
}
/** How ready this capability is today. */
@@ -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();
}
}
@@ -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();
}
}
@@ -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. */
@@ -23,8 +23,7 @@ class GrpcAdvancedModuleGuardTest {
@Test
@DisplayName("each capability has its own flag, not a shared one")
void eachCapabilityHasItsOwnFlag() {
assertThat(GrpcAdvancedCapability.XDS.propertyKey())
.isEqualTo("ca-skeleton.grpc.advanced.xds.enabled");
assertThat(GrpcAdvancedCapability.XDS.propertyKey()).isEqualTo("app.grpc.advanced.xds.enabled");
assertThat(GrpcAdvancedCapability.GRPC_WEB.propertyKey())
.isNotEqualTo(GrpcAdvancedCapability.XDS.propertyKey());
@@ -43,7 +42,7 @@ class GrpcAdvancedModuleGuardTest {
GrpcAdvancedModuleGuard.require(
GrpcAdvancedFeatureFlags.forDevelopment(), GrpcAdvancedCapability.REACTOR))
.isInstanceOf(GrpcAdvancedCapabilityDisabledException.class)
.hasMessageContaining("ca-skeleton.grpc.advanced.reactor.enabled=true");
.hasMessageContaining("app.grpc.advanced.reactor.enabled=true");
}
@Test
@@ -89,21 +88,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() {
@@ -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)) {
@@ -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) {
@@ -24,10 +24,10 @@ class GrpcEdition2024GateTest {
void editionIsOptInPerModule() {
GrpcEdition2024Policy policy = GrpcEdition2024Policy.notAdopted();
assertThat(policy.allowedIn("grpc-proto-contract")).isFalse();
assertThat(policy.allowedIn("grpc-contract")).isFalse();
assertThat(
new GrpcEdition2024Policy(Set.of("grpc-advanced-edition"), Set.of(), false)
.allowedIn("grpc-advanced-edition"))
new GrpcEdition2024Policy(Set.of("grpc-advanced"), Set.of(), false)
.allowedIn("grpc-advanced"))
.isTrue();
}
@@ -36,18 +36,14 @@ class GrpcEdition2024GateTest {
void publicServicesNeedAPromotion() {
GrpcEdition2024Policy withoutPromotion =
new GrpcEdition2024Policy(
Set.of("grpc-advanced-edition"),
Set.of("hyeonworks.document.v1.DocumentService"),
false);
Set.of("grpc-advanced"), Set.of("caskeleton.document.v1.DocumentService"), false);
GrpcEdition2024Policy withPromotion =
new GrpcEdition2024Policy(
Set.of("grpc-advanced-edition"),
Set.of("hyeonworks.document.v1.DocumentService"),
true);
Set.of("grpc-advanced"), Set.of("caskeleton.document.v1.DocumentService"), true);
assertThat(withoutPromotion.serviceMayMove("hyeonworks.document.v1.DocumentService")).isFalse();
assertThat(withPromotion.serviceMayMove("hyeonworks.document.v1.DocumentService")).isTrue();
assertThat(withoutPromotion.serviceMayMove("hyeonworks.internal.v1.ScratchService")).isTrue();
assertThat(withoutPromotion.serviceMayMove("caskeleton.document.v1.DocumentService")).isFalse();
assertThat(withPromotion.serviceMayMove("caskeleton.document.v1.DocumentService")).isTrue();
assertThat(withoutPromotion.serviceMayMove("caskeleton.internal.v1.ScratchService")).isTrue();
}
@Test
@@ -74,25 +70,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 +83,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);
}
@@ -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();
}
}
@@ -17,11 +17,11 @@ import org.junit.jupiter.api.Test;
class GrpcHedgingEligibilityTest {
private static final GrpcMethodName GET =
GrpcMethodName.parse("hyeonworks.document.v1.DocumentService/GetDocument");
GrpcMethodName.parse("caskeleton.document.v1.DocumentService/GetDocument");
private static final GrpcMethodName CREATE =
GrpcMethodName.parse("hyeonworks.document.v1.DocumentService/CreateDocument");
GrpcMethodName.parse("caskeleton.document.v1.DocumentService/CreateDocument");
private static final GrpcMethodName WATCH =
GrpcMethodName.parse("hyeonworks.document.v1.DocumentService/WatchDocuments");
GrpcMethodName.parse("caskeleton.document.v1.DocumentService/WatchDocuments");
private static final GrpcDeadlineProfile TWO_SECONDS =
GrpcDeadlineProfile.of(Duration.ofSeconds(2));
@@ -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");
}
}
@@ -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("caskeleton/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");
}
}

Some files were not shown because too many files have changed in this diff Show More