Files
grpc-library/docs/compatibility/grpc-support-matrix.md
T
DongHyeonka fd6a45f888 docs(compatibility): gRPC 지원 매트릭스를 한국어로 옮기고 정본을 가리킨다
문제: `docs/compatibility`의 두 문서가 영어였고, `grpc-support-matrix.md`는 Spring Boot
버전을 복사했다(number 예외). 지운 `GrpcAdvancedSupportMatrix`·
`GrpcAdvancedPromotionEvidence`와 없는 `runtime_memberships`, `src/build.gradle`의
`ext.grpcVersion`을 가리켰다.

고친 것: 둘을 번역했다. 버전은 `src/gradle/libs.versions.toml`을 가리키고, 등급의 정본은
`GrpcAdvancedCapability.defaultGrade`, 빌드 상태는 registry의 `"build": "optional-grpc"`로
적었다. 예외 목록에서 language 줄 2개와 number 줄 1개를 지웠다.

검증: 최종 트리 기준(첫 커밋 본문 참고).
2026-11-07 17:56:35 +09:00

4.2 KiB

gRPC 플랫폼 지원 매트릭스

Stable gRPC 플랫폼(:grpc:*)이 무엇에 대해 인증됐고, 무엇에 대해서는 확인만 하고, 무엇은 지켜보기만 하는지다. 그 구별이 요점이다. 「Spring Boot와 동작한다」는 누구도 행동에 옮길 수 없는 말이다.

릴리스 gate는 .github/workflows/release.yml의 grpc-stable-release-gate job이다. 인증된 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 저장소 기준선, src/gradle/libs.versions.toml(계획은 4.1을 가정한다)
io.grpc src/gradle/libs.versions.toml의 grpc. GrpcPlatformModuleConventionPlugin이 그 BOM을 모듈 범위로 import한다
Protobuf src/gradle/libs.versions.toml의 protobuf 항목(어느 leaf가 어느 것을 쓰는지는 그 파일의 주석이 적는다)
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)

지금 릴리스 상태

릴리스하지 않았다. registry에서 모든 :grpc:* leaf는 "build": "optional-grpc"라 주 빌드 밖에 있고 어느 조립에도 들어가지 않는다. 플랫폼은 빌드만 된다. 컴파일되고 lane이 돌지만, 배포되는 산출물 어디에도 실리지 않는다.

릴리스 gate 입력 둘이 남아 있고, 그것이 지금부터 릴리스까지의 일이다.

  • 성능 기준선. 성능 lane은 돌고, 절대 수치가 아니라 모양을 단언한다. 순서 있는 백분위수와 그것을 읽는 gate다. 알려진 runner에서 기록한 기준선이 생겨야 회귀 gate가 된다.
  • schema codegen. 이 빌드에서는 protoc가 돌지 않는다(ADR-GRPC-002). 그래서 descriptor 산출물과 consumer-compile fixture는 컴파일한 schema에서 만들어지지 않고 정책으로 다스린다.