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:
@@ -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
@@ -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
|
||||
|
||||
|
||||
@@ -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 | 의존 |
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
@@ -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
|
||||
-50
@@ -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);
|
||||
}
|
||||
}
|
||||
-75
@@ -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);
|
||||
}
|
||||
}
|
||||
-85
@@ -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();
|
||||
}
|
||||
}
|
||||
-66
@@ -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);
|
||||
}
|
||||
}
|
||||
-150
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
|
||||
-69
@@ -1,69 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.kotlin;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Whether a Kotlin adapter may be advertised as supported.
|
||||
*
|
||||
* <p>Fails closed in this repository, and says so rather than reporting a pass it cannot justify.
|
||||
* There is no Kotlin toolchain here (adaptation design D7), so the compile lane that would
|
||||
* establish the last requirement has never run; a gate that reported success anyway would put an
|
||||
* unverified claim in the support matrix.
|
||||
*
|
||||
* <p>The other four requirements are checkable and are checked, so turning the toolchain on later
|
||||
* is a lane to add rather than a contract to write.
|
||||
*/
|
||||
public final class GrpcKotlinCompatibilityGate {
|
||||
|
||||
private GrpcKotlinCompatibilityGate() {}
|
||||
|
||||
/**
|
||||
* Every reason a Kotlin adapter is not yet supportable.
|
||||
*
|
||||
* @param toolchainLaneRan whether a Kotlin compile lane actually ran against this profile
|
||||
* @return an empty list only when the profile is complete and its lane has run
|
||||
*/
|
||||
public static List<String> blockers(GrpcKotlinProfile profile, boolean toolchainLaneRan) {
|
||||
if (profile == null) {
|
||||
throw new IllegalArgumentException("a Kotlin profile is required");
|
||||
}
|
||||
List<String> blockers = new ArrayList<>();
|
||||
if (!profile.sharesSchemaSourceWithJava()) {
|
||||
blockers.add(
|
||||
"the Kotlin contract does not share one schema source with the Java contract; two "
|
||||
+ "sources diverge where only somebody reading both would notice");
|
||||
}
|
||||
if (!profile.propagatesCoroutineCancellation()) {
|
||||
blockers.add(
|
||||
"coroutine cancellation does not reach the gRPC call; a cancelled scope would leave the "
|
||||
+ "call running");
|
||||
}
|
||||
if (!profile.respectsStableFlowControl()) {
|
||||
blockers.add(
|
||||
"Flow backpressure bypasses the Stable buffer bounds; a slow collector would buffer "
|
||||
+ "without a limit rather than terminating the stream");
|
||||
}
|
||||
if (!profile.preservesPlatformEvidenceTypes()) {
|
||||
blockers.add(
|
||||
"the adapter does not preserve the platform's evidence, status and deadline types; a "
|
||||
+ "Kotlin-idiomatic re-creation is a second model of the same facts");
|
||||
}
|
||||
if (!toolchainLaneRan) {
|
||||
blockers.add(
|
||||
"no Kotlin toolchain lane has run against "
|
||||
+ profile.kotlinToolchainVersion()
|
||||
+ "; this repository has no Kotlin toolchain, so the compile evidence does not exist");
|
||||
}
|
||||
return List.copyOf(blockers);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether the Kotlin adapter is supportable in this repository as it stands.
|
||||
*
|
||||
* <p>False. The four contract requirements can be satisfied; the toolchain lane cannot.
|
||||
*/
|
||||
public static boolean supportableHere() {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
-35
@@ -1,35 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.kotlin;
|
||||
|
||||
/**
|
||||
* How a Kotlin adapter must behave, stated from the Java side.
|
||||
*
|
||||
* <p>Java-side because this repository has no Kotlin toolchain (adaptation design D7). What can be
|
||||
* expressed without one is every rule that constrains the adapter: one schema source shared with
|
||||
* the Java contract, coroutine cancellation propagated to the call, Flow backpressure inside the
|
||||
* Stable buffer bounds, and the platform's evidence and status types preserved rather than
|
||||
* re-created in Kotlin idiom.
|
||||
*
|
||||
* <p>Each is a component so the gate can check them individually. A single "compatible" flag would
|
||||
* let a partially compliant adapter through, and the most likely partial failure — a Flow that
|
||||
* buffers without a bound — is the one with the worst production behaviour.
|
||||
*/
|
||||
public record GrpcKotlinProfile(
|
||||
boolean sharesSchemaSourceWithJava,
|
||||
boolean propagatesCoroutineCancellation,
|
||||
boolean respectsStableFlowControl,
|
||||
boolean preservesPlatformEvidenceTypes,
|
||||
String kotlinToolchainVersion) {
|
||||
|
||||
/** Refuses a profile that claims support without naming a toolchain. */
|
||||
public GrpcKotlinProfile {
|
||||
if (kotlinToolchainVersion == null || kotlinToolchainVersion.isBlank()) {
|
||||
throw new IllegalArgumentException(
|
||||
"a Kotlin profile names the toolchain it was verified against; 'Kotlin' is not a version");
|
||||
}
|
||||
}
|
||||
|
||||
/** A profile for a toolchain this repository has not verified. */
|
||||
public static GrpcKotlinProfile unverified(String kotlinToolchainVersion) {
|
||||
return new GrpcKotlinProfile(false, false, false, false, kotlinToolchainVersion);
|
||||
}
|
||||
}
|
||||
-50
@@ -1,50 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.servlet;
|
||||
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* What a Servlet container can and cannot do compared with Netty.
|
||||
*
|
||||
* <p>The gaps are not incidental. A Servlet container owns the socket, so everything below the
|
||||
* request abstraction belongs to it: keepalive, connection age, and the flow-control window are the
|
||||
* container's settings, not gRPC's. Naming them is what stops a deployment from configuring a
|
||||
* keepalive that is silently ignored and concluding the client is at fault.
|
||||
*/
|
||||
public enum GrpcServletCapabilityMatrix {
|
||||
/** HTTP/2 request and response. Available. */
|
||||
HTTP2(true),
|
||||
/** TLS. Available, terminated by the container. */
|
||||
TLS(true),
|
||||
/** Inbound message and metadata limits. Available. */
|
||||
MESSAGE_LIMITS(true),
|
||||
/** The standard health service. Available. */
|
||||
HEALTH(true),
|
||||
/** Server reflection. Available. */
|
||||
REFLECTION(true),
|
||||
/** Graceful shutdown. Available through the container's lifecycle. */
|
||||
GRACEFUL_SHUTDOWN(true),
|
||||
/** gRPC-level keepalive tuning. The container owns the connection. */
|
||||
KEEPALIVE_TUNING(false),
|
||||
/** Maximum connection age. The container owns the connection. */
|
||||
MAX_CONNECTION_AGE(false),
|
||||
/** HTTP/2 flow-control window tuning. The container owns the transport. */
|
||||
FLOW_CONTROL_WINDOW_TUNING(false);
|
||||
|
||||
private final boolean available;
|
||||
|
||||
GrpcServletCapabilityMatrix(boolean available) {
|
||||
this.available = available;
|
||||
}
|
||||
|
||||
/** Whether the Servlet transport provides this. */
|
||||
public boolean available() {
|
||||
return available;
|
||||
}
|
||||
|
||||
/** Everything the Servlet transport cannot do. */
|
||||
public static Set<GrpcServletCapabilityMatrix> unavailable() {
|
||||
return java.util.Arrays.stream(values())
|
||||
.filter(capability -> !capability.available())
|
||||
.collect(java.util.stream.Collectors.toUnmodifiableSet());
|
||||
}
|
||||
}
|
||||
-51
@@ -1,51 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.servlet;
|
||||
|
||||
import dev.caskeleton.grpc.server.GrpcServerTransport;
|
||||
|
||||
/**
|
||||
* A deployment that serves gRPC from its Servlet container, on the web server's own port.
|
||||
*
|
||||
* <p>Attractive because it is one port, one TLS configuration and one lifecycle. The cost is that
|
||||
* the container owns the transport, so the Netty settings a Stable profile carries have no effect —
|
||||
* and this profile refuses to pretend otherwise.
|
||||
*
|
||||
* <p>Its evidence never counts as Netty certification. A suite that passes here has established
|
||||
* that the container serves gRPC, not that the platform's Netty profile is correct.
|
||||
*/
|
||||
public record GrpcServletCompatibilityProfile(
|
||||
String contextPath, boolean containerOwnsTls, boolean asyncSupported) {
|
||||
|
||||
/** Refuses a configuration the container cannot honour. */
|
||||
public GrpcServletCompatibilityProfile {
|
||||
if (contextPath == null || !contextPath.startsWith("/")) {
|
||||
throw new IllegalArgumentException(
|
||||
"a servlet profile needs a context path starting with '/'");
|
||||
}
|
||||
if (!asyncSupported) {
|
||||
throw new IllegalArgumentException(
|
||||
"gRPC over Servlet requires async support; without it every streaming call blocks a "
|
||||
+ "container thread for its lifetime");
|
||||
}
|
||||
if (!containerOwnsTls) {
|
||||
throw new IllegalArgumentException(
|
||||
"the container owns the socket, so it owns TLS; a profile that claims otherwise "
|
||||
+ "configures a setting nothing reads");
|
||||
}
|
||||
}
|
||||
|
||||
/** The transport this profile runs on. */
|
||||
public GrpcServerTransport transport() {
|
||||
return GrpcServerTransport.SERVLET;
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether a run under this profile certifies the platform's Netty transport.
|
||||
*
|
||||
* <p>Always false. The container's HTTP/2 is real, but it is the container's: its keepalive, its
|
||||
* connection age and its flow-control window. Stable certification is a statement about the
|
||||
* platform's own Netty profile, and a Servlet run establishes nothing about it.
|
||||
*/
|
||||
public boolean certifiesNettyTransport() {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
-51
@@ -1,51 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.servlet;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* Refuses a Servlet deployment that asks for something the container will not do.
|
||||
*
|
||||
* <p>Refuses rather than warns, because the setting would otherwise be accepted and ignored. A
|
||||
* keepalive configured on a Servlet deployment does nothing, the connections behave as the
|
||||
* container decides, and the investigation starts from the assumption that the setting is in force.
|
||||
*/
|
||||
public final class GrpcServletStartupValidator {
|
||||
|
||||
private GrpcServletStartupValidator() {}
|
||||
|
||||
/**
|
||||
* Every requested capability the Servlet transport cannot provide.
|
||||
*
|
||||
* @param requestedCapabilities the transport settings the deployment configured
|
||||
* @return an empty list when everything requested is available
|
||||
*/
|
||||
public static List<String> violations(
|
||||
GrpcServletCompatibilityProfile profile,
|
||||
Set<GrpcServletCapabilityMatrix> requestedCapabilities) {
|
||||
if (profile == null || requestedCapabilities == null) {
|
||||
throw new IllegalArgumentException("validation needs the profile and the requested set");
|
||||
}
|
||||
List<String> violations = new ArrayList<>();
|
||||
requestedCapabilities.stream()
|
||||
.filter(capability -> !capability.available())
|
||||
.sorted()
|
||||
.forEach(
|
||||
capability ->
|
||||
violations.add(
|
||||
capability
|
||||
+ " is not available on the Servlet transport; the container owns the "
|
||||
+ "connection, so this setting would be accepted and ignored"));
|
||||
return List.copyOf(violations);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether a Servlet run may stand in for Netty certification.
|
||||
*
|
||||
* <p>Always false.
|
||||
*/
|
||||
public static boolean substitutesForNettyCertification() {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
-56
@@ -1,56 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.web;
|
||||
|
||||
import dev.caskeleton.grpc.core.GrpcMethodName;
|
||||
import dev.caskeleton.grpc.core.RpcType;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* Checks that everything exposed to browsers can actually be served to them, on the same schema as
|
||||
* the native clients.
|
||||
*
|
||||
* <p>The same schema is the point. Two schemas — one for browsers, one for services — is how a
|
||||
* field ends up meaning something different depending on which client asked, and the divergence is
|
||||
* only visible to whoever reads both files.
|
||||
*/
|
||||
public final class GrpcWebCompatibilityGate {
|
||||
|
||||
private GrpcWebCompatibilityGate() {}
|
||||
|
||||
/**
|
||||
* Every method this profile could not serve.
|
||||
*
|
||||
* @param exposedMethods the methods a browser is meant to be able to call
|
||||
* @return an empty list when every exposed method is servable
|
||||
*/
|
||||
public static List<String> violations(Map<GrpcMethodName, RpcType> exposedMethods) {
|
||||
if (exposedMethods == null) {
|
||||
throw new IllegalArgumentException("an exposed method map is required");
|
||||
}
|
||||
List<String> violations = new ArrayList<>();
|
||||
exposedMethods.entrySet().stream()
|
||||
.sorted(java.util.Comparator.comparing(entry -> entry.getKey().canonical()))
|
||||
.forEach(
|
||||
entry -> {
|
||||
if (!GrpcWebRpcSupport.supported(entry.getValue())) {
|
||||
violations.add(
|
||||
"method '"
|
||||
+ entry.getKey().canonical()
|
||||
+ "' is "
|
||||
+ entry.getValue()
|
||||
+ ", which gRPC-Web cannot carry");
|
||||
}
|
||||
});
|
||||
return List.copyOf(violations);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether the browser and native suites must run against one schema.
|
||||
*
|
||||
* <p>Always true. Stated as a method so the property is asserted rather than described.
|
||||
*/
|
||||
public static boolean sharesOneSchemaWithNativeClients() {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
+1
-34
@@ -4,8 +4,6 @@ import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.kotlin.GrpcCoroutineContextBridge;
|
||||
import dev.caskeleton.grpc.advanced.kotlin.GrpcKotlinCompatibilityGate;
|
||||
import dev.caskeleton.grpc.advanced.kotlin.GrpcKotlinProfile;
|
||||
import dev.caskeleton.grpc.api.deadline.GrpcCancellationToken;
|
||||
import dev.caskeleton.grpc.deadline.GrpcCancellationCoordinator;
|
||||
import dev.caskeleton.grpc.deadline.GrpcCancellationReason;
|
||||
@@ -14,41 +12,10 @@ import java.util.concurrent.atomic.AtomicBoolean;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcKotlinCompatibilityGateTest {
|
||||
class GrpcCoroutineContextBridgeTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-08-30T10:00:00Z");
|
||||
|
||||
@Test
|
||||
@DisplayName("the Kotlin adapter fails closed here, and says which lane is missing")
|
||||
void theGateFailsClosed() {
|
||||
GrpcKotlinProfile complete = new GrpcKotlinProfile(true, true, true, true, "2.1.0");
|
||||
|
||||
assertThat(GrpcKotlinCompatibilityGate.blockers(complete, false))
|
||||
.singleElement()
|
||||
.satisfies(blocker -> assertThat(blocker).contains("no Kotlin toolchain"));
|
||||
assertThat(GrpcKotlinCompatibilityGate.blockers(complete, true)).isEmpty();
|
||||
assertThat(GrpcKotlinCompatibilityGate.supportableHere()).isFalse();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("each Kotlin contract requirement is checked on its own")
|
||||
void eachRequirementIsCheckedSeparately() {
|
||||
assertThat(GrpcKotlinCompatibilityGate.blockers(GrpcKotlinProfile.unverified("2.1.0"), true))
|
||||
.hasSize(4)
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("one schema source"))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("cancelled scope"))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("buffer without a limit"))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("second model of the same facts"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a profile that claims support without naming a toolchain is refused")
|
||||
void aProfileNamesItsToolchain() {
|
||||
assertThatThrownBy(() -> GrpcKotlinProfile.unverified(" "))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("not a version");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("coroutine cancellation reaches the platform, and the platform reaches the scope")
|
||||
void cancellationCrossesBothWays() {
|
||||
+1
-1
@@ -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(
|
||||
|
||||
+1
-1
@@ -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() {
|
||||
|
||||
-79
@@ -1,79 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.compat;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.servlet.GrpcServletCapabilityMatrix;
|
||||
import dev.caskeleton.grpc.advanced.servlet.GrpcServletCompatibilityProfile;
|
||||
import dev.caskeleton.grpc.advanced.servlet.GrpcServletStartupValidator;
|
||||
import dev.caskeleton.grpc.server.GrpcServerTransport;
|
||||
import java.util.Set;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcServletStartupValidatorTest {
|
||||
|
||||
private static final GrpcServletCompatibilityProfile PROFILE =
|
||||
new GrpcServletCompatibilityProfile("/grpc", true, true);
|
||||
|
||||
@Test
|
||||
@DisplayName("the Servlet transport names what it cannot do")
|
||||
void theMatrixNamesItsGaps() {
|
||||
assertThat(GrpcServletCapabilityMatrix.unavailable())
|
||||
.containsExactlyInAnyOrder(
|
||||
GrpcServletCapabilityMatrix.KEEPALIVE_TUNING,
|
||||
GrpcServletCapabilityMatrix.MAX_CONNECTION_AGE,
|
||||
GrpcServletCapabilityMatrix.FLOW_CONTROL_WINDOW_TUNING);
|
||||
assertThat(GrpcServletCapabilityMatrix.HTTP2.available()).isTrue();
|
||||
assertThat(GrpcServletCapabilityMatrix.GRACEFUL_SHUTDOWN.available()).isTrue();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a deployment asking for a Netty-only setting is refused, not warned")
|
||||
void aNettyOnlySettingIsRefused() {
|
||||
assertThat(
|
||||
GrpcServletStartupValidator.violations(
|
||||
PROFILE, Set.of(GrpcServletCapabilityMatrix.KEEPALIVE_TUNING)))
|
||||
.singleElement()
|
||||
.satisfies(violation -> assertThat(violation).contains("accepted and ignored"));
|
||||
assertThat(
|
||||
GrpcServletStartupValidator.violations(
|
||||
PROFILE,
|
||||
Set.of(
|
||||
GrpcServletCapabilityMatrix.KEEPALIVE_TUNING,
|
||||
GrpcServletCapabilityMatrix.MAX_CONNECTION_AGE)))
|
||||
.hasSize(2);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an available capability passes")
|
||||
void anAvailableCapabilityPasses() {
|
||||
assertThat(
|
||||
GrpcServletStartupValidator.violations(
|
||||
PROFILE,
|
||||
Set.of(GrpcServletCapabilityMatrix.HTTP2, GrpcServletCapabilityMatrix.TLS)))
|
||||
.isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a Servlet run never substitutes for Netty certification")
|
||||
void servletIsNotNettyCertification() {
|
||||
assertThat(GrpcServletStartupValidator.substitutesForNettyCertification()).isFalse();
|
||||
assertThat(PROFILE.certifiesNettyTransport()).isFalse();
|
||||
assertThat(PROFILE.transport()).isEqualTo(GrpcServerTransport.SERVLET);
|
||||
assertThat(GrpcServerTransport.SERVLET.certifiesNetworkBehaviour()).isFalse();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a profile without async support or container-owned TLS is refused")
|
||||
void anIncoherentProfileIsRefused() {
|
||||
assertThatThrownBy(() -> new GrpcServletCompatibilityProfile("/grpc", true, false))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("blocks a container thread");
|
||||
assertThatThrownBy(() -> new GrpcServletCompatibilityProfile("/grpc", false, true))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("a setting nothing reads");
|
||||
assertThatThrownBy(() -> new GrpcServletCompatibilityProfile("grpc", true, true))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
}
|
||||
}
|
||||
+58
-22
@@ -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);
|
||||
}
|
||||
+13
-3
@@ -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')
|
||||
}
|
||||
-87
@@ -1,87 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.diagnostics;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
|
||||
import java.util.ArrayList;
|
||||
import java.util.EnumSet;
|
||||
import java.util.List;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* What an advanced capability has to be exercised against before it counts as verified.
|
||||
*
|
||||
* <p>Real infrastructure, named per capability. gRPC-Web without a proxy tests a code path no
|
||||
* browser will take; a Servlet profile without a container tests the profile object; xDS without a
|
||||
* control plane cannot exercise the case that matters, which is the control plane going away. In
|
||||
* all three, a suite that runs without the infrastructure passes and establishes nothing, which is
|
||||
* worse than not having one.
|
||||
*/
|
||||
public final class GrpcAdvancedInfrastructureTestkit {
|
||||
|
||||
private GrpcAdvancedInfrastructureTestkit() {}
|
||||
|
||||
/** A piece of infrastructure a capability's suite needs. */
|
||||
public enum Infrastructure {
|
||||
/** An Envoy or equivalent gRPC-Web proxy. */
|
||||
GRPC_WEB_PROXY,
|
||||
/** A Servlet container serving HTTP/2. */
|
||||
SERVLET_CONTAINER,
|
||||
/** An xDS control plane that can be stopped. */
|
||||
XDS_CONTROL_PLANE,
|
||||
/** A Kotlin toolchain. */
|
||||
KOTLIN_TOOLCHAIN
|
||||
}
|
||||
|
||||
/** What {@code capability} needs before its evidence means anything. */
|
||||
public static Set<Infrastructure> requiredFor(GrpcAdvancedCapability capability) {
|
||||
if (capability == null) {
|
||||
throw new IllegalArgumentException("a capability is required");
|
||||
}
|
||||
return switch (capability) {
|
||||
case GRPC_WEB -> Set.of(Infrastructure.GRPC_WEB_PROXY);
|
||||
case SERVLET_COMPAT -> Set.of(Infrastructure.SERVLET_CONTAINER);
|
||||
case XDS -> Set.of(Infrastructure.XDS_CONTROL_PLANE);
|
||||
case KOTLIN -> Set.of(Infrastructure.KOTLIN_TOOLCHAIN);
|
||||
case EDITION_2024,
|
||||
EDITION_2026,
|
||||
CLIENT_STREAMING,
|
||||
BIDI_STREAMING,
|
||||
MANUAL_FLOW_CONTROL,
|
||||
HEDGING,
|
||||
CUSTOM_RESOLVER,
|
||||
CUSTOM_LOAD_BALANCER,
|
||||
INTEGRATION_BRIDGE,
|
||||
REACTOR,
|
||||
CHANNEL_DIAGNOSTICS ->
|
||||
Set.of();
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Every piece of infrastructure a capability needs and does not have.
|
||||
*
|
||||
* @return an empty list when the suite can produce evidence that means something
|
||||
*/
|
||||
public static List<String> missingInfrastructure(
|
||||
GrpcAdvancedCapability capability, Set<Infrastructure> available) {
|
||||
if (available == null) {
|
||||
throw new IllegalArgumentException("the available infrastructure set is required");
|
||||
}
|
||||
Set<Infrastructure> required = requiredFor(capability);
|
||||
if (required.isEmpty()) {
|
||||
return List.of();
|
||||
}
|
||||
Set<Infrastructure> missing = EnumSet.copyOf(required);
|
||||
missing.removeAll(available);
|
||||
List<String> gaps = new ArrayList<>();
|
||||
missing.stream()
|
||||
.sorted()
|
||||
.forEach(
|
||||
infrastructure ->
|
||||
gaps.add(
|
||||
capability.flagName()
|
||||
+ " needs "
|
||||
+ infrastructure
|
||||
+ "; a suite that runs without it passes and establishes nothing"));
|
||||
return List.copyOf(gaps);
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
-61
@@ -1,61 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.edition;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Decides whether Edition 2024 may be adopted, and keeps its failures out of the Stable release.
|
||||
*
|
||||
* <p>The separation the Stable plan asks for, in one place: an Edition 2024 failure blocks the
|
||||
* edition's own promotion and does not block a proto3 release. Without that split, an opt-in lane
|
||||
* that nobody depends on can hold up every release, and the first response to that is to stop
|
||||
* running the lane.
|
||||
*/
|
||||
public final class GrpcEdition2024Gate {
|
||||
|
||||
private GrpcEdition2024Gate() {}
|
||||
|
||||
/**
|
||||
* Every reason Edition 2024 may not be promoted.
|
||||
*
|
||||
* @return an empty list when the edition is ready to adopt
|
||||
*/
|
||||
public static List<String> promotionBlockers(
|
||||
GrpcEditionCompatibilityReport report,
|
||||
boolean consumerMigrationPlanned,
|
||||
boolean promotionAdr) {
|
||||
if (report == null) {
|
||||
throw new IllegalArgumentException("a compatibility report is required");
|
||||
}
|
||||
List<String> blockers = new ArrayList<>(report.incompatibilities());
|
||||
if (!consumerMigrationPlanned) {
|
||||
blockers.add(
|
||||
"no consumer migration is planned; moving a public service to an edition breaks whichever "
|
||||
+ "consumer's generator treats its features differently");
|
||||
}
|
||||
if (!promotionAdr) {
|
||||
blockers.add(
|
||||
"no promotion ADR records the decision to move onto Edition "
|
||||
+ GrpcEdition2024Policy.EDITION);
|
||||
}
|
||||
return List.copyOf(blockers);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether an Edition 2024 failure blocks a proto3 Stable release.
|
||||
*
|
||||
* <p>Always false. Stated as a method so the property is tested rather than described.
|
||||
*/
|
||||
public static boolean blocksStableRelease() {
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether an Edition 2024 failure blocks the edition's own promotion.
|
||||
*
|
||||
* <p>Always true, for the same reason.
|
||||
*/
|
||||
public static boolean blocksEditionPromotion() {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
-48
@@ -1,48 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.edition;
|
||||
|
||||
/**
|
||||
* Refuses Edition 2026 as a schema source, whatever a report says.
|
||||
*
|
||||
* <p>The guard is deliberately not conditional on the watch report. A watch lane's purpose is to
|
||||
* record what is true, and letting the same record also authorise use means the moment somebody
|
||||
* marks four fields SUPPORTED, a schema can move onto an edition with no promotion decision, no
|
||||
* consumer migration and no ADR. Turning the watch into a lane that can be used is a code change
|
||||
* here, and that is the point.
|
||||
*/
|
||||
public final class GrpcEdition2026Guard {
|
||||
|
||||
private GrpcEdition2026Guard() {}
|
||||
|
||||
/** Whether Edition 2026 may be used as a Stable contract source. Always false. */
|
||||
public static boolean allowedAsStableSource() {
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fails when Edition 2026 is used as a schema source.
|
||||
*
|
||||
* @throws IllegalStateException naming what is still outstanding, so the refusal is actionable
|
||||
*/
|
||||
public static void requireNotUsedAsSource(GrpcEdition2026WatchReport report) {
|
||||
if (report == null) {
|
||||
throw new IllegalArgumentException("a watch report is required");
|
||||
}
|
||||
throw new IllegalStateException(
|
||||
"Edition "
|
||||
+ GrpcEdition2026WatchReport.EDITION
|
||||
+ " is a watch lane, not a schema source"
|
||||
+ (report.outstanding().isEmpty()
|
||||
? "; every toolchain gate is satisfied, so the next step is a promotion decision "
|
||||
+ "rather than a schema change"
|
||||
: "; outstanding: " + report.outstanding()));
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether an Edition 2026 CI failure blocks the Stable build.
|
||||
*
|
||||
* <p>False. A watch lane that can break the build is a watch lane somebody deletes.
|
||||
*/
|
||||
public static boolean blocksStableBuild() {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
@@ -1,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')
|
||||
}
|
||||
-100
@@ -1,100 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.xds;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedFeatureFlags;
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedModuleGuard;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Refuses to start an xDS channel that is not fully configured, and refuses to let xDS be described
|
||||
* as Stable support.
|
||||
*
|
||||
* <p>The second refusal is the one worth having in code. xDS working in a deployment is not the
|
||||
* same claim as the platform supporting it: it brings a control plane, its outage modes, its own
|
||||
* security boundary and its own version skew, and the Stable support statement covers DNS and
|
||||
* static targets. A support matrix that quietly widens is a support matrix nobody can rely on.
|
||||
*/
|
||||
public final class GrpcXdsStartupGuard {
|
||||
|
||||
private GrpcXdsStartupGuard() {}
|
||||
|
||||
/**
|
||||
* Every reason an xDS channel may not start.
|
||||
*
|
||||
* @return an empty list when the profile and flags permit it
|
||||
*/
|
||||
public static List<String> startupBlockers(
|
||||
GrpcXdsProfile profile, GrpcAdvancedFeatureFlags flags, boolean applicationDefinesRetries) {
|
||||
if (profile == null || flags == null) {
|
||||
throw new IllegalArgumentException("startup validation needs a profile and the flags");
|
||||
}
|
||||
List<String> blockers = new ArrayList<>();
|
||||
if (!GrpcAdvancedModuleGuard.available(flags, GrpcAdvancedCapability.XDS)) {
|
||||
blockers.add(
|
||||
"the xds capability is not available; it is "
|
||||
+ flags.gradeOf(GrpcAdvancedCapability.XDS)
|
||||
+ " and "
|
||||
+ (flags.flagSet(GrpcAdvancedCapability.XDS)
|
||||
? "production has not approved it"
|
||||
: "its flag is not set"));
|
||||
}
|
||||
if (applicationDefinesRetries) {
|
||||
blockers.add(
|
||||
"the application also defines retry policy; with xDS the control plane owns it, and "
|
||||
+ "defining it in both places makes the winner depend on resolution order");
|
||||
}
|
||||
return List.copyOf(blockers);
|
||||
}
|
||||
|
||||
/**
|
||||
* Every disagreement between a deployment's profile and the bootstrap file its client will read.
|
||||
*
|
||||
* <p>Checked because the two are written by different people in different repositories, and the
|
||||
* failure is silent: a client whose bootstrap names a namespace the deployment did not configure
|
||||
* subscribes successfully and receives another team's routing. Nothing errors — the control plane
|
||||
* answers, the resources parse, and traffic goes somewhere nobody chose.
|
||||
*
|
||||
* <p>Matched textually rather than with a JSON parser, deliberately. This leaf's test classpath
|
||||
* is plain JUnit and AssertJ, and adding a JSON library to check three fields would put a parser
|
||||
* on the runtime classpath of every deployment that enables xDS.
|
||||
*
|
||||
* @param bootstrapJson the bootstrap document's contents
|
||||
* @return an empty list when the bootstrap and the profile agree
|
||||
*/
|
||||
public static List<String> bootstrapMismatches(GrpcXdsProfile profile, String bootstrapJson) {
|
||||
if (profile == null) {
|
||||
throw new IllegalArgumentException("a profile is required");
|
||||
}
|
||||
if (bootstrapJson == null || bootstrapJson.isBlank()) {
|
||||
throw new IllegalArgumentException(
|
||||
"the bootstrap document is required; a client with no bootstrap has no control plane to ask");
|
||||
}
|
||||
List<String> mismatches = new ArrayList<>();
|
||||
if (!bootstrapJson.contains("\"xds_servers\"")) {
|
||||
mismatches.add("the bootstrap declares no xds_servers");
|
||||
}
|
||||
if (!bootstrapJson.contains("\"channel_creds\"") || !bootstrapJson.contains("\"tls\"")) {
|
||||
mismatches.add(
|
||||
"the bootstrap's control-plane channel is not TLS; that connection carries routing and "
|
||||
+ "often certificates, so an unauthenticated one can be impersonated");
|
||||
}
|
||||
if (!bootstrapJson.contains(profile.resourceNamespace())) {
|
||||
mismatches.add(
|
||||
"the bootstrap does not name the profile's resource namespace '"
|
||||
+ profile.resourceNamespace()
|
||||
+ "'; a client that subscribes outside its namespace receives another team's routing, "
|
||||
+ "and nothing about that fails");
|
||||
}
|
||||
return List.copyOf(mismatches);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether xDS may be advertised as part of Stable discovery support.
|
||||
*
|
||||
* <p>Always false. Stable support is DNS and static.
|
||||
*/
|
||||
public static boolean advertisableAsStableSupport() {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
-188
@@ -1,188 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.resilience;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedFeatureFlags;
|
||||
import dev.caskeleton.grpc.advanced.xds.GrpcXdsFailurePolicy;
|
||||
import dev.caskeleton.grpc.advanced.xds.GrpcXdsProfile;
|
||||
import dev.caskeleton.grpc.advanced.xds.GrpcXdsResourceSnapshot;
|
||||
import dev.caskeleton.grpc.advanced.xds.GrpcXdsStartupGuard;
|
||||
import dev.caskeleton.grpc.resilience.GrpcRetryOwner;
|
||||
import java.io.IOException;
|
||||
import java.io.InputStream;
|
||||
import java.io.UncheckedIOException;
|
||||
import java.net.URI;
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.time.Instant;
|
||||
import java.util.List;
|
||||
import java.util.Optional;
|
||||
import java.util.Set;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcXdsStartupGuardTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-08-30T10:00:00Z");
|
||||
|
||||
private static GrpcXdsProfile profile(String namespace) {
|
||||
return new GrpcXdsProfile(
|
||||
URI.create("xds:///documents"),
|
||||
"classpath:/xds/bootstrap.json",
|
||||
namespace,
|
||||
GrpcRetryOwner.SERVICE_MESH,
|
||||
true);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an xDS profile requires an xds target, a namespace, mesh retries and mTLS")
|
||||
void anXdsProfileRequiresItsFourConditions() {
|
||||
assertThat(profile("hyeonworks/documents").target().getScheme()).isEqualTo("xds");
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcXdsProfile(
|
||||
URI.create("dns:///documents"),
|
||||
"file:/etc/grpc/bootstrap.json",
|
||||
"ns",
|
||||
GrpcRetryOwner.SERVICE_MESH,
|
||||
true))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcXdsProfile(
|
||||
URI.create("xds:///documents"), " ", "ns", GrpcRetryOwner.SERVICE_MESH, true))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("no control plane to ask");
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcXdsProfile(
|
||||
URI.create("xds:///documents"),
|
||||
"file:/etc/grpc/bootstrap.json",
|
||||
"ns",
|
||||
GrpcRetryOwner.APPLICATION,
|
||||
true))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("two places");
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcXdsProfile(
|
||||
URI.create("xds:///documents"),
|
||||
"file:/etc/grpc/bootstrap.json",
|
||||
"ns",
|
||||
GrpcRetryOwner.SERVICE_MESH,
|
||||
false))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("impersonated");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("xDS needs its capability approved and refuses duplicate retry ownership")
|
||||
void startupRequiresApprovalAndSingleRetryOwner() {
|
||||
GrpcAdvancedFeatureFlags unapproved =
|
||||
GrpcAdvancedFeatureFlags.forProduction(Set.of()).enable(GrpcAdvancedCapability.XDS);
|
||||
GrpcAdvancedFeatureFlags approved =
|
||||
GrpcAdvancedFeatureFlags.forProduction(Set.of(GrpcAdvancedCapability.XDS))
|
||||
.enable(GrpcAdvancedCapability.XDS);
|
||||
|
||||
assertThat(
|
||||
GrpcXdsStartupGuard.startupBlockers(profile("hyeonworks/documents"), unapproved, false))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("production has not approved it"));
|
||||
assertThat(
|
||||
GrpcXdsStartupGuard.startupBlockers(profile("hyeonworks/documents"), approved, false))
|
||||
.isEmpty();
|
||||
assertThat(GrpcXdsStartupGuard.startupBlockers(profile("hyeonworks/documents"), approved, true))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("resolution order"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an unflagged capability is reported as unflagged rather than unapproved")
|
||||
void anUnflaggedCapabilityIsReportedAsSuch() {
|
||||
assertThat(
|
||||
GrpcXdsStartupGuard.startupBlockers(
|
||||
profile("hyeonworks/documents"),
|
||||
GrpcAdvancedFeatureFlags.forProduction(Set.of()),
|
||||
false))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("its flag is not set"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the committed bootstrap fixture agrees with the profile it is meant to serve")
|
||||
void theBootstrapFixtureAgreesWithItsProfile() {
|
||||
assertThat(
|
||||
GrpcXdsStartupGuard.bootstrapMismatches(
|
||||
profile("hyeonworks/documents"), resource("xds/bootstrap.json")))
|
||||
.isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a bootstrap naming another namespace is reported, since nothing else would fail")
|
||||
void aNamespaceMismatchIsReported() {
|
||||
assertThat(
|
||||
GrpcXdsStartupGuard.bootstrapMismatches(
|
||||
profile("hyeonworks/billing"), resource("xds/bootstrap.json")))
|
||||
.anySatisfy(mismatch -> assertThat(mismatch).contains("another team's routing"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a bootstrap with an unauthenticated control-plane channel is reported")
|
||||
void anUnauthenticatedControlPlaneIsReported() {
|
||||
String insecure =
|
||||
resource("xds/bootstrap.json")
|
||||
.replace("{ \"type\": \"tls\" }", "{ \"type\": \"insecure\" }");
|
||||
|
||||
assertThat(GrpcXdsStartupGuard.bootstrapMismatches(profile("hyeonworks/documents"), insecure))
|
||||
.anySatisfy(mismatch -> assertThat(mismatch).contains("can be impersonated"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a missing bootstrap is refused rather than treated as an empty one")
|
||||
void aMissingBootstrapIsRefused() {
|
||||
assertThatThrownBy(
|
||||
() -> GrpcXdsStartupGuard.bootstrapMismatches(profile("hyeonworks/documents"), " "))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("no control plane to ask");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("last-known-good is bounded, and an empty resource set is not a snapshot")
|
||||
void lastKnownGoodIsBounded() {
|
||||
GrpcXdsFailurePolicy policy = GrpcXdsFailurePolicy.standard();
|
||||
GrpcXdsResourceSnapshot snapshot =
|
||||
new GrpcXdsResourceSnapshot("v7", List.of("documents-cluster"), NOW);
|
||||
|
||||
assertThat(policy.decide(Optional.of(snapshot), NOW.plusSeconds(60)))
|
||||
.isEqualTo(GrpcXdsFailurePolicy.Decision.SERVE_LAST_KNOWN_GOOD);
|
||||
assertThat(policy.decide(Optional.of(snapshot), NOW.plusSeconds(1000)))
|
||||
.isEqualTo(GrpcXdsFailurePolicy.Decision.STALE_BEYOND_BOUND);
|
||||
assertThat(policy.decide(Optional.empty(), NOW))
|
||||
.isEqualTo(GrpcXdsFailurePolicy.Decision.NO_SNAPSHOT_YET);
|
||||
assertThat(snapshot.ageAt(NOW.plusSeconds(60))).isEqualTo(java.time.Duration.ofSeconds(60));
|
||||
assertThatThrownBy(() -> new GrpcXdsResourceSnapshot("v7", List.of(), NOW))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcXdsFailurePolicy(
|
||||
java.time.Duration.ZERO, true, java.time.Duration.ofSeconds(1)))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("receiving traffic indefinitely");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("xDS is not part of the Stable discovery support statement")
|
||||
void xdsIsNotStableSupport() {
|
||||
assertThat(GrpcXdsStartupGuard.advertisableAsStableSupport()).isFalse();
|
||||
}
|
||||
|
||||
private static String resource(String path) {
|
||||
try (InputStream stream =
|
||||
GrpcXdsStartupGuardTest.class.getClassLoader().getResourceAsStream(path)) {
|
||||
if (stream == null) {
|
||||
throw new IllegalStateException("missing test resource " + path);
|
||||
}
|
||||
return new String(stream.readAllBytes(), StandardCharsets.UTF_8);
|
||||
} catch (IOException e) {
|
||||
throw new UncheckedIOException(e);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,40 +0,0 @@
|
||||
{
|
||||
"_comment": [
|
||||
"An xDS bootstrap fixture. The client reads this file to learn where its control plane is and",
|
||||
"who it claims to be; GrpcXdsProfile validates the deployment settings that must agree with it.",
|
||||
"The two fields the profile actually checks against are server_uri (the control plane must be",
|
||||
"reached over authenticated mTLS) and the node id's namespace (a client that subscribes outside",
|
||||
"its namespace receives another team's routing)."
|
||||
],
|
||||
"xds_servers": [
|
||||
{
|
||||
"server_uri": "xds-control-plane.hyeonworks.internal:15010",
|
||||
"channel_creds": [
|
||||
{ "type": "tls" }
|
||||
],
|
||||
"server_features": ["xds_v3"]
|
||||
}
|
||||
],
|
||||
"node": {
|
||||
"id": "hyeonworks/documents/documents-7f9c4",
|
||||
"cluster": "documents",
|
||||
"metadata": {
|
||||
"NAMESPACE": "hyeonworks/documents"
|
||||
},
|
||||
"locality": {
|
||||
"region": "ap-northeast-2",
|
||||
"zone": "ap-northeast-2a"
|
||||
}
|
||||
},
|
||||
"authorities": {
|
||||
"hyeonworks.internal": {
|
||||
"xds_servers": [
|
||||
{
|
||||
"server_uri": "xds-control-plane.hyeonworks.internal:15010",
|
||||
"channel_creds": [{ "type": "tls" }],
|
||||
"server_features": ["xds_v3"]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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=
|
||||
@@ -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')
|
||||
}
|
||||
+2
-2
@@ -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. */
|
||||
-20
@@ -1,9 +1,5 @@
|
||||
package dev.caskeleton.grpc.advanced.bootstrap;
|
||||
|
||||
import dev.caskeleton.grpc.core.GrpcStableBuildInvariant;
|
||||
import dev.caskeleton.grpc.core.GrpcStableModuleCatalog;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* The single gate every advanced capability passes through.
|
||||
*
|
||||
@@ -65,20 +61,4 @@ public final class GrpcAdvancedModuleGuard {
|
||||
+ "that somebody accepted its uncharacterised failure modes");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Fails when the Stable starter's dependency set reaches an advanced module.
|
||||
*
|
||||
* <p>The same invariant the registry enforces at build time, asserted here so a runtime that was
|
||||
* assembled some other way — a fat jar, a shaded artifact, a test harness — is checked too.
|
||||
*/
|
||||
public static void requireStableStarterIsClean(Set<String> starterDependencies) {
|
||||
GrpcStableBuildInvariant.requireNoAdvancedDependency(
|
||||
"grpc-spring-boot-starter", starterDependencies);
|
||||
}
|
||||
|
||||
/** The advanced module ids, for a runtime classpath check. */
|
||||
public static Set<String> advancedModules() {
|
||||
return GrpcStableModuleCatalog.advancedModules();
|
||||
}
|
||||
}
|
||||
+38
-30
@@ -2,7 +2,9 @@ package dev.caskeleton.grpc.advanced.discovery;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
import java.util.Set;
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
/**
|
||||
@@ -19,8 +21,14 @@ public final class GrpcResolverSafetyPolicy {
|
||||
private static final Pattern AUTHORITY =
|
||||
Pattern.compile("[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:\\d{1,5})?");
|
||||
|
||||
private static final Pattern CREDENTIAL_SHAPED =
|
||||
Pattern.compile("(?i).*(authorization|bearer|password|secret|token|api[_-]?key).*");
|
||||
/** The top-level fields of a gRPC service config. Anything else is not policy. */
|
||||
private static final Set<String> SERVICE_CONFIG_FIELDS =
|
||||
Set.of(
|
||||
"loadBalancingConfig",
|
||||
"loadBalancingPolicy",
|
||||
"methodConfig",
|
||||
"retryThrottling",
|
||||
"healthCheckConfig");
|
||||
|
||||
private GrpcResolverSafetyPolicy() {}
|
||||
|
||||
@@ -53,40 +61,40 @@ public final class GrpcResolverSafetyPolicy {
|
||||
+ (lastAccepted == null ? "none" : lastAccepted.revision())
|
||||
+ "; applying it would replace newer endpoints with older ones");
|
||||
}
|
||||
update
|
||||
.serviceConfigJson()
|
||||
.ifPresent(
|
||||
config -> {
|
||||
if (CREDENTIAL_SHAPED.matcher(config).find()) {
|
||||
violations.add(
|
||||
"the pushed service config contains a credential-shaped field; a resolver "
|
||||
+ "supplies addresses and policy, never authentication material");
|
||||
}
|
||||
});
|
||||
update.serviceConfig().ifPresent(config -> serviceConfigViolations(config, violations));
|
||||
return List.copyOf(violations);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether a closed resolver's update should be applied.
|
||||
*
|
||||
* <p>Always false. A resolver that keeps delivering after close is one whose discovery source has
|
||||
* not noticed the channel is gone, and applying its updates resurrects routing for a channel
|
||||
* nobody is using.
|
||||
*/
|
||||
public static boolean acceptAfterClose() {
|
||||
return false;
|
||||
}
|
||||
|
||||
/** Whether a resolver may supply caller identity or business metadata. Always false. */
|
||||
public static boolean mayCarryBusinessMetadata() {
|
||||
return false;
|
||||
private static void serviceConfigViolations(Map<String, ?> config, List<String> violations) {
|
||||
if (!SERVICE_CONFIG_FIELDS.containsAll(config.keySet())) {
|
||||
violations.add(
|
||||
"the pushed service config has top-level fields outside "
|
||||
+ SERVICE_CONFIG_FIELDS.stream().sorted().toList()
|
||||
+ "; a resolver supplies addresses and policy, never authentication material");
|
||||
}
|
||||
Object methodConfig = config.get("methodConfig");
|
||||
if (methodConfig == null) {
|
||||
return;
|
||||
}
|
||||
if (!(methodConfig instanceof List<?> entries)
|
||||
|| !entries.stream().allMatch(entry -> entry instanceof Map<?, ?>)) {
|
||||
violations.add("the pushed service config's methodConfig is not a list of objects");
|
||||
return;
|
||||
}
|
||||
if (entries.stream()
|
||||
.map(entry -> (Map<?, ?>) entry)
|
||||
.anyMatch(
|
||||
entry -> entry.containsKey("retryPolicy") || entry.containsKey("hedgingPolicy"))) {
|
||||
violations.add(
|
||||
"the pushed service config sets retryPolicy or hedgingPolicy; retries and hedging are "
|
||||
+ "owned by the platform's method policy catalog, and a resolver that could turn them "
|
||||
+ "on could retry a non-idempotent method from outside the codebase");
|
||||
}
|
||||
}
|
||||
|
||||
/** The service config an update may contribute, once validated. */
|
||||
public static Optional<String> acceptedServiceConfig(
|
||||
public static Optional<Map<String, ?>> acceptedServiceConfig(
|
||||
GrpcResolverUpdate update, GrpcEndpointSnapshot lastAccepted) {
|
||||
return violations(update, lastAccepted).isEmpty()
|
||||
? update.serviceConfigJson()
|
||||
: Optional.empty();
|
||||
return violations(update, lastAccepted).isEmpty() ? update.serviceConfig() : Optional.empty();
|
||||
}
|
||||
}
|
||||
+15
-6
@@ -1,5 +1,8 @@
|
||||
package dev.caskeleton.grpc.advanced.discovery;
|
||||
|
||||
import java.util.Collections;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
@@ -11,20 +14,26 @@ import java.util.Optional;
|
||||
* anyone reviewed it.
|
||||
*/
|
||||
public record GrpcResolverUpdate(
|
||||
GrpcEndpointSnapshot snapshot, Optional<String> serviceConfigJson) {
|
||||
GrpcEndpointSnapshot snapshot, Optional<Map<String, ?>> serviceConfig) {
|
||||
|
||||
/** Requires a snapshot and the Optional. */
|
||||
/**
|
||||
* Requires a snapshot and the Optional. The service config is the parsed JSON object, the same
|
||||
* {@code Map<String, ?>} shape gRPC's {@code NameResolver.Helper.parseServiceConfig} takes; it is
|
||||
* copied so it cannot change between validation and delivery.
|
||||
*/
|
||||
public GrpcResolverUpdate {
|
||||
if (snapshot == null || serviceConfigJson == null) {
|
||||
if (snapshot == null || serviceConfig == null) {
|
||||
throw new IllegalArgumentException("a resolver update carries a snapshot and the Optional");
|
||||
}
|
||||
serviceConfigJson.ifPresent(
|
||||
serviceConfig.ifPresent(
|
||||
config -> {
|
||||
if (config.isBlank()) {
|
||||
if (config.isEmpty()) {
|
||||
throw new IllegalArgumentException(
|
||||
"a present service config must not be blank; absent and empty are different states");
|
||||
"a present service config must not be empty; absent and empty are different states");
|
||||
}
|
||||
});
|
||||
serviceConfig =
|
||||
serviceConfig.map(config -> Collections.unmodifiableMap(new LinkedHashMap<>(config)));
|
||||
}
|
||||
|
||||
/** An update with endpoints only. */
|
||||
+2
-18
@@ -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() {
|
||||
-30
@@ -191,36 +191,6 @@ class GrpcChannelDiagnosticsPolicyTest {
|
||||
assertThat(snapshot.xdsResourceVersions()).hasSize(3);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("each capability names the real infrastructure its evidence depends on")
|
||||
void capabilitiesNameTheirInfrastructure() {
|
||||
assertThat(GrpcAdvancedInfrastructureTestkit.requiredFor(GrpcAdvancedCapability.GRPC_WEB))
|
||||
.containsExactly(GrpcAdvancedInfrastructureTestkit.Infrastructure.GRPC_WEB_PROXY);
|
||||
assertThat(GrpcAdvancedInfrastructureTestkit.requiredFor(GrpcAdvancedCapability.XDS))
|
||||
.containsExactly(GrpcAdvancedInfrastructureTestkit.Infrastructure.XDS_CONTROL_PLANE);
|
||||
assertThat(GrpcAdvancedInfrastructureTestkit.requiredFor(GrpcAdvancedCapability.HEDGING))
|
||||
.isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a suite without its infrastructure is reported as establishing nothing")
|
||||
void missingInfrastructureIsReported() {
|
||||
assertThat(
|
||||
GrpcAdvancedInfrastructureTestkit.missingInfrastructure(
|
||||
GrpcAdvancedCapability.XDS, Set.of()))
|
||||
.singleElement()
|
||||
.satisfies(gap -> assertThat(gap).contains("establishes nothing"));
|
||||
assertThat(
|
||||
GrpcAdvancedInfrastructureTestkit.missingInfrastructure(
|
||||
GrpcAdvancedCapability.XDS,
|
||||
Set.of(GrpcAdvancedInfrastructureTestkit.Infrastructure.XDS_CONTROL_PLANE)))
|
||||
.isEmpty();
|
||||
assertThat(
|
||||
GrpcAdvancedInfrastructureTestkit.missingInfrastructure(
|
||||
GrpcAdvancedCapability.HEDGING, Set.of()))
|
||||
.isEmpty();
|
||||
}
|
||||
|
||||
private static String resource(String path) {
|
||||
try (java.io.InputStream stream =
|
||||
GrpcChannelDiagnosticsPolicyTest.class.getClassLoader().getResourceAsStream(path)) {
|
||||
+10
-33
@@ -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);
|
||||
}
|
||||
+1
-36
@@ -7,7 +7,7 @@ import java.time.Instant;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcEdition2026GuardTest {
|
||||
class GrpcEdition2026WatchReportTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-08-30T10:00:00Z");
|
||||
|
||||
@@ -55,39 +55,4 @@ class GrpcEdition2026GuardTest {
|
||||
assertThat(GrpcEdition2026Status.UNKNOWN.usable()).isFalse();
|
||||
assertThat(GrpcEdition2026Status.UNSUPPORTED.usable()).isFalse();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("Edition 2026 is refused as a schema source even when every gate is satisfied")
|
||||
void theGuardIsNotConditionalOnTheReport() {
|
||||
GrpcEdition2026WatchReport allSupported =
|
||||
new GrpcEdition2026WatchReport(
|
||||
GrpcEdition2026Status.SUPPORTED,
|
||||
GrpcEdition2026Status.SUPPORTED,
|
||||
GrpcEdition2026Status.SUPPORTED,
|
||||
GrpcEdition2026Status.SUPPORTED,
|
||||
NOW);
|
||||
|
||||
assertThat(allSupported.readyToEvaluate()).isTrue();
|
||||
assertThat(GrpcEdition2026Guard.allowedAsStableSource()).isFalse();
|
||||
assertThatThrownBy(() -> GrpcEdition2026Guard.requireNotUsedAsSource(allSupported))
|
||||
.isInstanceOf(IllegalStateException.class)
|
||||
.hasMessageContaining("promotion decision rather than a schema change");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a refusal names what is still outstanding, so it is actionable")
|
||||
void aRefusalNamesWhatIsOutstanding() {
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
GrpcEdition2026Guard.requireNotUsedAsSource(
|
||||
GrpcEdition2026WatchReport.nothingKnown(NOW)))
|
||||
.isInstanceOf(IllegalStateException.class)
|
||||
.hasMessageContaining("outstanding:");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a watch lane failure does not break the Stable build")
|
||||
void theWatchLaneDoesNotBlockTheStableBuild() {
|
||||
assertThat(GrpcEdition2026Guard.blocksStableBuild()).isFalse();
|
||||
}
|
||||
}
|
||||
+3
-3
@@ -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));
|
||||
|
||||
+49
-9
@@ -2,6 +2,7 @@ package dev.caskeleton.grpc.advanced.resilience;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
import static org.assertj.core.api.Assertions.catchThrowable;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.discovery.GrpcCustomResolver;
|
||||
import dev.caskeleton.grpc.advanced.discovery.GrpcEndpointSnapshot;
|
||||
@@ -9,6 +10,7 @@ import dev.caskeleton.grpc.advanced.discovery.GrpcResolverSafetyPolicy;
|
||||
import dev.caskeleton.grpc.advanced.discovery.GrpcResolverUpdate;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
@@ -65,7 +67,6 @@ class GrpcResolverSafetyPolicyTest {
|
||||
new GrpcEndpointSnapshot(1L, "documents", List.of("10.0.0.1")))))
|
||||
.anySatisfy(violation -> assertThat(violation).contains("resolver is closed"));
|
||||
assertThat(delivered).isEmpty();
|
||||
assertThat(GrpcResolverSafetyPolicy.acceptAfterClose()).isFalse();
|
||||
}
|
||||
|
||||
@Test
|
||||
@@ -74,11 +75,10 @@ class GrpcResolverSafetyPolicyTest {
|
||||
GrpcResolverUpdate withCredential =
|
||||
new GrpcResolverUpdate(
|
||||
new GrpcEndpointSnapshot(1L, "documents", List.of("10.0.0.1")),
|
||||
Optional.of("{\"authorization\":\"Bearer abc\"}"));
|
||||
Optional.of(Map.of("authorization", "Bearer abc")));
|
||||
|
||||
assertThat(GrpcResolverSafetyPolicy.violations(withCredential, null))
|
||||
.anySatisfy(violation -> assertThat(violation).contains("never authentication material"));
|
||||
assertThat(GrpcResolverSafetyPolicy.mayCarryBusinessMetadata()).isFalse();
|
||||
assertThat(GrpcResolverSafetyPolicy.acceptedServiceConfig(withCredential, null)).isEmpty();
|
||||
}
|
||||
|
||||
@@ -88,12 +88,48 @@ class GrpcResolverSafetyPolicyTest {
|
||||
GrpcResolverUpdate clean =
|
||||
new GrpcResolverUpdate(
|
||||
new GrpcEndpointSnapshot(1L, "documents", List.of("10.0.0.1")),
|
||||
Optional.of("{\"loadBalancingConfig\":[{\"round_robin\":{}}]}"));
|
||||
Optional.of(Map.of("loadBalancingConfig", List.of(Map.of("round_robin", Map.of())))));
|
||||
|
||||
assertThat(GrpcResolverSafetyPolicy.violations(clean, null)).isEmpty();
|
||||
assertThat(GrpcResolverSafetyPolicy.acceptedServiceConfig(clean, null)).isPresent();
|
||||
}
|
||||
|
||||
@Test
|
||||
void aServiceConfigWithRetryThrottlingIsAccepted() {
|
||||
// given
|
||||
GrpcResolverUpdate throttled =
|
||||
new GrpcResolverUpdate(
|
||||
new GrpcEndpointSnapshot(1L, "documents", List.of("10.0.0.1")),
|
||||
Optional.of(Map.of("retryThrottling", Map.of("maxTokens", 10, "tokenRatio", 0.1))));
|
||||
|
||||
// when
|
||||
List<String> violations = GrpcResolverSafetyPolicy.violations(throttled, null);
|
||||
|
||||
// then
|
||||
assertThat(violations).isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
void aServiceConfigThatTurnsOnRetriesIsRefused() {
|
||||
// given
|
||||
GrpcResolverUpdate retrying =
|
||||
new GrpcResolverUpdate(
|
||||
new GrpcEndpointSnapshot(1L, "documents", List.of("10.0.0.1")),
|
||||
Optional.of(
|
||||
Map.of(
|
||||
"methodConfig",
|
||||
List.of(
|
||||
Map.of(
|
||||
"name", List.of(Map.of("service", "documents.v1.Documents")),
|
||||
"retryPolicy", Map.of("maxAttempts", 5))))));
|
||||
|
||||
// when
|
||||
List<String> violations = GrpcResolverSafetyPolicy.violations(retrying, null);
|
||||
|
||||
// then
|
||||
assertThat(violations).singleElement().asString().contains("retryPolicy or hedgingPolicy");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an invalid authority is refused, because it decides which certificate is accepted")
|
||||
void anInvalidAuthorityIsRefused() {
|
||||
@@ -106,14 +142,18 @@ class GrpcResolverSafetyPolicyTest {
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a present service config may not be blank")
|
||||
void aPresentServiceConfigMayNotBeBlank() {
|
||||
assertThatThrownBy(
|
||||
void aPresentServiceConfigMayNotBeEmpty() {
|
||||
// when
|
||||
Throwable failure =
|
||||
catchThrowable(
|
||||
() ->
|
||||
new GrpcResolverUpdate(
|
||||
new GrpcEndpointSnapshot(1L, "documents", List.of("10.0.0.1")),
|
||||
Optional.of(" ")))
|
||||
Optional.of(Map.of())));
|
||||
|
||||
// then
|
||||
assertThat(failure)
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("different states");
|
||||
.hasMessageContaining("absent and empty are different states");
|
||||
}
|
||||
}
|
||||
+94
@@ -0,0 +1,94 @@
|
||||
package dev.caskeleton.grpc.advanced.resilience;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.xds.GrpcXdsFailurePolicy;
|
||||
import dev.caskeleton.grpc.advanced.xds.GrpcXdsProfile;
|
||||
import dev.caskeleton.grpc.advanced.xds.GrpcXdsResourceSnapshot;
|
||||
import dev.caskeleton.grpc.resilience.GrpcRetryOwner;
|
||||
import java.net.URI;
|
||||
import java.time.Instant;
|
||||
import java.util.List;
|
||||
import java.util.Optional;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcXdsProfileTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-08-30T10:00:00Z");
|
||||
|
||||
private static GrpcXdsProfile profile(String namespace) {
|
||||
return new GrpcXdsProfile(
|
||||
URI.create("xds:///documents"),
|
||||
"classpath:/xds/bootstrap.json",
|
||||
namespace,
|
||||
GrpcRetryOwner.SERVICE_MESH,
|
||||
true);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an xDS profile requires an xds target, a namespace, mesh retries and mTLS")
|
||||
void anXdsProfileRequiresItsFourConditions() {
|
||||
assertThat(profile("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
Reference in New Issue
Block a user