4.2 KiB
grpc-advanced — local authority for the advanced gRPC capabilities
이 문서는 grpc-advanced:* family의 local authority다. leaf 목록·gradle path·허용 의존성은
src/config/architecture/modules.json이 SSOT다. Root 정책(CLAUDE.md / AGENTS.md)과 충돌하면
root가 이긴다.
이 family는 Stable gRPC 플랫폼(grpc:*)이 의도적으로 제외한 능력들을 담는다. 별도 디렉터리와
별도 Gradle prefix인 이유는 하나다: "Stable starter가 advanced module을 참조하면 build가 실패한다"는
불변 조건을 registry의 allowed_dependencies만으로 기계 검증할 수 있게 하기 위해서다.
의존 방향
grpc-advanced:* → grpc:* (허용)
grpc:* → grpc-advanced:* (금지 — registry가 거부한다)
grpc-spring-boot-starter의 registry 엔트리에는 어떤 advanced id도 없다.
verifyCleanArchitectureDependencies가 build time에, GrpcStableBuildInvariant와
GrpcAdvancedModuleGuard.requireStableStarterIsClean이 runtime에 같은 규칙을 강제한다.
Capability grade와 feature flag
capability마다 별도 flag를 갖는다. 하나의 "advanced" 스위치로 묶지 않는 이유는, gRPC-Web을 켜는 결정(프록시 하나)과 xDS를 켜는 결정(control plane과 그 장애 모드 전체)이 같은 결정이 아니기 때문이다. 하나의 스위치는 두 번째 결정을 실수로 내리게 만든다.
| grade | 시작 가능 | production 추가 승인 |
|---|---|---|
ADVANCED_STABLE |
O | 불필요 |
EXPERIMENTAL |
O | 필요 |
WATCH |
X (추적만) | — |
DISABLED |
X | — |
property key는 ca-skeleton.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 요구사항 |
Promotion은 capability별로 독립이다
GrpcAdvancedPromotionEvidence는 capability마다 별도 레코드다. 공유 레코드였다면 하나를 승격할 때
같은 시점에 측정된 다른 것들이 함께 승격된다. GrpcAdvancedPromotionGate.capabilitiesDraggedAlong이
항상 빈 리스트인 것은 주석이 아니라 테스트되는 속성이다.
승격 문턱은 두 개다: ADVANCED_STABLE은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가
더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다.
이 저장소에서 검증할 수 없는 것
GrpcAdvancedInfrastructureTestkit이 capability별로 필요한 실제 인프라를 명시한다.
grpc-web→ gRPC-Web 프록시servlet-compat→ Servlet 컨테이너xds→ 중지 가능한 xDS control planekotlin→ Kotlin 툴체인 (이 저장소에 없다)
인프라 없이 도는 suite는 통과하면서 아무것도 증명하지 않으므로, suite가 없는 것보다 나쁘다.
GrpcKotlinCompatibilityGate.supportableHere()가 false를 반환하는 것은 그 사실의 코드 표현이다 —
Kotlin 계약 요구사항 4개는 검증되지만 compile lane은 존재하지 않는다.
금지
- Stable leaf(
grpc:*)가 이 family를 참조하는 것. - capability grade 없이, 또는 flag 없이 advanced 코드 경로를 실행하는 것.
WATCHcapability를 스키마 소스로 사용하는 것 (GrpcEdition2026Guard가 무조건 거부한다).- 실제 인프라 없이 실행한 suite를 promotion evidence로 인용하는 것.