Files
clean-architecture-backend-…/docs/compatibility/grpc-support-matrix.md
T
donghyeon-kaandClaude Opus 5.5 0ed7bc8df7 review-followup Wave 3 라운드 1(P16): 빌드 게이트 정리 — JPA evidence manifest 폐기, build-tools 제거, API surface를 leaf check로
- 결정 4: JPA evidence·qualification manifest 폐기 → persistence-jpa 테스트, build-tools included build 비움(verifyEnvKeys는
  app-bootstrap 태스크, 구현은 build-logic `ca.config-contract`), gRPC release gate 삭제
- 결정 20: API surface 검사를 leaf `check`로, JPA adopter 검사를 `ca.api-surface`로 합침(구현 하나)
- 레인 단계 정리(문서 대조 레인은 `mainStage()`), integrationCheck가 입력 없는 레인을 이름과 함께 제외 → 로컬 통과(NEW-16)
- release workflow 통합, releaseCheck는 tag 전용, build-logic 비핵심 플러그인 정리, sample을 ArchUnit 대상에
- 보류 4행(B3 변경 모듈만 실행, C 이미지 서명, messaging 카드 검증 이동 2행 — 결정 필요), 남음 2행(O3-5 나머지)
- 통합: P17이 옮긴 gRPC release gate 사본 삭제, `grpc-proto-buf`를 release-gate needs에(P17-new-3)

검증: ./gradlew ci verifyDependencyLocks --warning-mode=fail 통과(685 task), mainCheck 통과(268 task),
-p optional-platforms ci 통과, -p build-logic test 78건 통과(손상된 TestKit 캐시 삭제 후)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-28 16:44:17 +09:00

78 lines
3.6 KiB
Markdown

# gRPC platform support matrix
What the Stable gRPC platform (`:grpc:*`) is certified against, what it is only checked against, and
what is merely watched. The distinction is the point: "works with Spring Boot" is not a statement
anyone can act on.
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
| Lane | Grade | Failure blocks a release |
| --- | --- | --- |
| Boot-managed platform (Spring Boot 4.0.8 BOM) | Certified | Yes |
| proto3 with explicit `optional` | Certified | Yes |
| `grpc-netty-shaded` | Certified | Yes |
| `grpc-netty` (unshaded) | Compatibility | No |
| Upstream gRPC Java version override | Compatibility | No |
| Protobuf Edition 2024 | Watch | No |
| Protobuf Edition 2026 | Watch | No |
## Runtime baseline
| | |
| --- | --- |
| Java | 21 |
| Spring Boot | 4.0.8 (the repository baseline; the plans assume 4.1) |
| io.grpc | `ext.grpcVersion` in `src/build.gradle` |
| Protobuf | `ext.protobufVersion` in `src/build.gradle` |
| Stable transport | Netty (shaded) |
| Stable RPC shapes | Unary, Server Streaming |
| Stable resolvers | Static, DNS, Unix domain socket |
| Stable load balancing | `pick_first`, `round_robin` |
## Evidence grades
A capability may only be advertised on evidence of a grade that can establish it.
`GrpcEvidenceGrade.requireCertifies` enforces this, and `GrpcReleaseEvidence.supports` refuses a
claim backed by the wrong lane.
| Grade | Lane | Establishes |
| --- | --- | --- |
| `CONTRACT` | `grpcInProcessContractTest` | adapter, interceptor order, status mapping, validation, idempotency replay, context propagation |
| `TRANSPORT` | `grpcNettyContractTest` | HTTP/2, TLS, mTLS, metadata limit, message limit, GOAWAY, keepalive, graceful shutdown |
| `FAULT` | `grpcFaultTest` | connection loss, completion unknown, partial stream, evidence classifier |
| `PERFORMANCE` | `grpcPerformanceTest` | latency, stream saturation, executor saturation, drain budget |
In-process results are never transport evidence. The in-process transport does not negotiate TLS,
does not frame HTTP/2 and does not enforce transport-level limits, so a suite that passes there has
tested the adapter and not the transport.
## What is not supported
| | 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`) |
| gRPC-Web, Servlet HTTP/2, Spring Integration, Reactor, Kotlin | `grpc-advanced-compat` |
| Channelz / CSDS diagnostics | `grpc-advanced` (`diagnostics`) |
## Current release status
Not released. Every `:grpc:*` leaf is `runtime_memberships: []` in the module registry, so the
platform is build-only: it compiles, its lanes run, and no deployed artifact carries it.
Two release gate inputs are outstanding and are the work between here and a release:
- **Performance baseline.** The performance lane runs and asserts shape — ordered percentiles, a gate
that reads them — rather than absolute numbers. A recorded baseline on a known runner is what turns
it into a regression gate.
- **Schema codegen.** No `protoc` runs in this build (ADR-GRPC-002), so the descriptor artifact and
the consumer-compile fixture are governed as policy rather than produced from a compiled schema.