옮겨 온 문서는 템플릿 안의 optional build를 전제로 했다(`-p platforms/optional-build`, 템플릿 registry·workflow 경로, "벤더드 플랫폼"). 하네스 뼈대의 루트 지침과 문제 정의는 비어 있었다. - 루트 AGENTS.md(38줄)·CLAUDE.md: 꼭 지킬 것(core-api 순수성, Stable이 advanced를 안 씀, 템플릿에 기대지 않음, 배포한 버전 불변, 버전 규칙), 지도, 맡은 일, 검증 진입점. 비대화형 세션의 플러그인 설치 두 줄. - README: 무엇인가, 받는 법(exclusiveContent), 지원 표, 구조, 문서 지도, 서명, 이력(filter-repo, 커밋 SHA·리뷰 ID는 템플릿 기준). - docs/work/README.md·gates.md·release.md: 고치는 법, 단계와 바꾼 것별 게이트, 템플릿과 같이 고치기(composite), 릴리스와 소유자가 할 일 (PACKAGES_TOKEN, SIGNING_KEY·SIGNING_PASSWORD, 첫 태그 v1.0.0). - CHANGELOG.md(1.0.0 미발행, 옮기는 법), docs/README.md(지도, 머리 블록). - scripts/verify.sh: unit·pr·main·release 단계. 라이브러리라 app은 없다. - 살아 있는 문서(grpc·grpc-advanced AGENTS.md, 지원 매트릭스, runbook): 경로·패키지·optional build 문장을 이 repo 기준으로. ADR·설계서 본문은 기록이라 고치지 않았다. - docs/vision.md는 소유자가 쓰는 문서라 비워 두었다. 검증: scripts/verify.sh docs rc=0(AGENTS.md 38줄, 장부 JSON).
4.2 KiB
gRPC 플랫폼 지원 매트릭스
Stable gRPC 플랫폼(:grpc:*)이 무엇에 대해 인증됐고, 무엇에 대해서는 확인만 하고, 무엇은 지켜보기만 하는지다. 그 구별이
요점이다. 「Spring Boot와 동작한다」는 누구도 행동에 옮길 수 없는 말이다.
릴리스 gate는 .gitea/workflows/release.yml이 돌리는 Gradle 단계 releaseCheck다(docs/work/release.md). 인증된 lane마다
아무것도 돌리지 않으면 실패하는 strict test lane이다.
이력: 코드 안의
GrpcCompatibilityMatrix/GrpcStableReleaseGate짝은 지웠다(리뷰 2026-09-24 S5-lead-4). 운영 코드도 빌드 코드도 그것을 부르지 않아서 아무것도 막지 않았다.
lane
| lane | 등급 | 실패하면 릴리스를 막나 |
|---|---|---|
| Boot가 관리하는 플랫폼(저장소의 Spring Boot BOM) | Certified | 예 |
명시적 optional을 쓰는 proto3 |
Certified | 예 |
grpc-netty-shaded |
Certified | 예 |
grpc-netty(shade하지 않음) |
Compatibility | 아니요 |
| upstream gRPC Java 버전 override | Compatibility | 아니요 |
| Protobuf Edition 2024 | Watch | 아니요 |
| Protobuf Edition 2026 | Watch | 아니요 |
런타임 기준선
| Java | 21 |
| Spring Boot | gradle/libs.versions.toml의 springBoot(이 줄로 컴파일하고 시험한다. 버전별 표는 README 「지원 표」) |
| io.grpc | gradle/libs.versions.toml의 grpc. GrpcPlatformModuleConventionPlugin이 그 BOM을 모듈 범위로 import한다 |
| Protobuf | gradle/libs.versions.toml의 protobufGrpc(생성 코드 runtime과 protoc가 같은 줄) |
| Stable 전송 | Netty(shaded) |
| Stable RPC 모양 | Unary, Server Streaming |
| Stable resolver | Static, DNS, Unix domain socket |
| Stable load balancing | pick_first, round_robin |
증거 등급
capability는 그것을 세울 수 있는 등급의 증거로만 광고한다. GrpcEvidenceGrade.requireCertifies가 이것을 강제하고,
GrpcReleaseEvidence.supports가 맞지 않는 lane이 뒷받침하는 주장을 거부한다.
| 등급 | lane | 세우는 것 |
|---|---|---|
CONTRACT |
grpcInProcessContractTest |
어댑터, interceptor 순서, 상태 매핑, 검증, 멱등 replay, context 전파 |
TRANSPORT |
grpcNettyContractTest |
HTTP/2, TLS, mTLS, metadata 한도, 메시지 한도, GOAWAY, keepalive, graceful shutdown |
FAULT |
grpcFaultTest |
연결 끊김, 완료 모름, 부분 stream, 증거 분류기 |
PERFORMANCE |
grpcPerformanceTest |
지연, stream 포화, executor 포화, drain 예산 |
in-process 결과는 절대 전송 증거가 아니다. in-process 전송은 TLS를 협상하지 않고, HTTP/2 frame을 만들지 않고, 전송 수준 한도를 강제하지 않는다. 그래서 거기서 통과한 suite는 전송이 아니라 어댑터를 시험한 것이다.
지원하지 않는 것
| 있는 곳 | |
|---|---|
| client streaming, bidirectional streaming | grpc-advanced (streaming) |
| 수동 flow control | grpc-advanced (streaming) |
| Hedging | grpc-advanced (resilience) |
| 사용자 정의 name resolver, 사용자 정의 load balancer | grpc-advanced (resilience) |
| xDS | grpc-advanced (resilience) |
| gRPC-Web, Servlet HTTP/2, Spring Integration, Reactor, Kotlin | grpc-advanced-compat |
| Channelz / CSDS 진단 | grpc-advanced (diagnostics) |
지금 릴리스 상태
Gitea Packages에 아직 버전을 내지 않았다(첫 버전은 v1.0.0, docs/work/release.md). 이 라이브러리를 조립하는 앱도
아직 없다. 플랫폼은 빌드만 된다. 컴파일되고 lane이 돌지만, 배포되는 앱 어디에도 실리지 않는다.
릴리스 gate 입력 둘이 남아 있고, 그것이 지금부터 릴리스까지의 일이다.
- 성능 기준선. 성능 lane은 돌고, 절대 수치가 아니라 모양을 단언한다. 순서 있는 백분위수와 그것을 읽는 gate다. 알려진 runner에서 기록한 기준선이 생겨야 회귀 gate가 된다.
- schema codegen. 이 빌드에서는
protoc가 돌지 않는다(ADR-GRPC-002). 그래서 descriptor 산출물과 consumer-compile fixture는 컴파일한 schema에서 만들어지지 않고 정책으로 다스린다.