옮겨 온 문서는 템플릿 안의 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).
5.0 KiB
grpc-advanced — 고급 gRPC capability의 지역 정본
이 문서는 grpc-advanced:* family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은
config/architecture/modules.json이 SSOT다. 루트 AGENTS.md와 충돌하면
루트가 이긴다.
이 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에 이 규칙을 강제한다. runtime 검사는 없다.
공용 다이제스트 헬퍼를 복사해 두는 이유
grpc-advanced(GrpcDiagnosticsRedactor)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이
grpc-advanced:* → grpc:*로 닫혀 있고 shared-contract edge가 없는 것은 의도다. grpc/AGENTS.md의
같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치).
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는 app.grpc.advanced.<capability>.enabled이고 전부 기본 off다.
GrpcAdvancedModuleGuard가 세 조건(flag 미설정 / grade가 시작 불가 / production 승인 없음)을
구분해서 거부하며, 세 경우의 조치가 다르므로 메시지도 다르다.
Leaf별 담당 capability
| leaf | 패키지(com.hyeonworks.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별로 독립이다
승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른
것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 GrpcAdvancedPromotionGate는 자기 테스트 말고
호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 docs/runbooks/grpc-advanced-capabilities.md의
리뷰 규칙이다.
승격 문턱은 두 개다: ADVANCED_STABLE은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가
더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다.
이 저장소에서 검증할 수 없는 것
capability별로 필요한 실제 인프라가 이 저장소에 없다.
grpc-web→ gRPC-Web 프록시servlet-compat→ Servlet 컨테이너xds→ 중지 가능한 xDS control planekotlin→ Kotlin 툴체인
인프라 없이 도는 suite는 통과하면서 아무것도 증명하지 않으므로, suite가 없는 것보다 나쁘다.
이 사실을 상수로 반환하던 gate 클래스(GrpcKotlinCompatibilityGate, GrpcAdvancedInfrastructureTestkit
등)는 2026-09-25 삭제됐다 — 지원 여부는 이 문서와 support matrix가 적는다.
금지
- Stable leaf(
grpc:*)가 이 family를 참조하는 것. - capability grade 없이, 또는 flag 없이 advanced 코드 경로를 실행하는 것.
WATCHcapability를 스키마 소스로 사용하는 것.- 실제 인프라 없이 실행한 suite를 promotion evidence로 인용하는 것.