7.4 KiB
grpc — local authority for the gRPC platform family
이 문서는 grpc:* family의 local authority다. leaf 목록·gradle path·허용 의존성은
src/config/architecture/modules.json이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는
것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, 증거 등급, Stable 범위의 경계,
그리고 runtime_memberships가 비어 있다는 사실의 의미.
Root 정책(CLAUDE.md / AGENTS.md)과 충돌하면 root가 이긴다.
이 family는 Clean Architecture의 계층이 아니라 벤더드 RPC 플랫폼이다 — messaging:*와 같은
자리에 있고 같은 이유로 있다. 자기 API(port)와 adapter와 조립 경계(starter)를 가지며, 애플리케이션은
adapter:inbound:grpc를 통해 라이브러리로서 도달한다.
설계 근거와 원본 계획 대비 deviation은 docs/superpowers/specs/2026-08-30-grpc-platform-adaptation-design.md가 SSOT다.
Family와 framework 규칙
leaf의 정확한 id는 registry에서 읽는다.
| Family | 역할 | 허용 framework |
|---|---|---|
grpc-core-api |
식별자, method policy, 실행 증거, 실패 모델, deadline, request context, operation ledger port | Java stdlib만. io.grpc / Spring / protobuf / DB 타입 금지 |
grpc-proto-contract |
.proto 스키마 소스와 style/schema 규칙 검증기 |
Java stdlib만 |
grpc-codegen |
Buf governance, codegen manifest, descriptor 릴리스 아티팩트 | Java stdlib만 |
grpc-policy |
validation, context, status/rich error, TLS/credential, deadline/cancellation, retry, idempotency, streaming, size/compression | io.grpc:grpc-api, grpc-stub. Spring 금지 |
grpc-server |
application boundary rule, typed service adapter SPI, interceptor 순서, Netty profile | io.grpc:grpc-api, grpc-stub. Netty 자체 금지 — profile은 설정 모델이다 |
grpc-client |
named channel, runtime generation, typed stub factory, client metadata/credentials | io.grpc:grpc-api, grpc-stub |
grpc-discovery |
Static/DNS resolver, pick_first/round_robin, Kubernetes routing profile | Java stdlib만 |
grpc-admin |
health, reflection, drain, secret-free policy snapshot | Java stdlib만 |
grpc-observability |
bounded metric/trace convention | io.micrometer:micrometer-core만 |
grpc-operation-ledger-jpa |
mutation idempotency의 durable 저장 | jakarta.persistence, spring-data-jpa. port는 core-api에 있다 |
grpc-spring-boot-starter |
조립 경계, typed properties, startup validator | Spring Boot autoconfigure. 여기서만 |
grpc-testkit |
in-process / 실제 Netty / fault / performance 인증 | io.grpc netty-shaded, inprocess. production leaf가 의존하지 않는다 |
grpc-core-api가 io.grpc를 이름조차 부르지 않는다는 것이 이 family의 핵심 제약이다. 실행 증거와
실패 모델은 "전송이 무엇을 했는가"를 기술하는 계약이고, 그 계약 안에 전송 타입이 들어가면 계약이
전송의 일부가 된다. GrpcStatusCode가 io.grpc의 코드를 미러링하는 이유가 이것이고, 양방향 번역은
grpc-policy의 GrpcStatusMapping이 단독으로 소유한다.
증거 등급 — testkit이 하나의 leaf인 이유
원본 계획은 testkit을 core/in-process/netty/fault 4개 모듈로 쪼갠다. 목적은 "in-process 결과를
네트워크 증거로 오해하지 않게 한다"이고, 이 저장소는 그 목적을 모듈 경계가 아니라 strict test
lane으로 표현한다(ca.strict-test-lane: lane은 아무것도 실행하지 않으면 실패하고 up-to-date
결과를 제공하지 않는다).
grpc-testkit의 네 lane과 그 태그:
| lane | 태그 | 증명하는 것 |
|---|---|---|
grpcInProcessContractTest |
grpc-inprocess |
adapter, interceptor 순서, status, validation, idempotency replay |
grpcNettyContractTest |
grpc-netty |
실제 소켓 위의 HTTP/2, TLS/mTLS, metadata·message hard limit, GOAWAY, drain |
grpcFaultTest |
grpc-fault |
각 증거 경계에서의 연결 손실, completion unknown, partial stream |
grpcPerformanceTest |
grpc-performance |
latency percentile, saturation, drain budget |
lane 분리만으로는 리포트가 잘못된 run을 인용하는 것을 막지 못하므로 GrpcEvidenceGrade가 런타임
체크로 이를 붙든다: CONTRACT 등급으로 tls를 주장하면 예외다.
performance lane은 기본 test에서 제외된다(leaf build.gradle). 공유 CI runner에서의 측정은
release path의 flaky gate가 되고, flaky gate는 꺼진다.
Stable 범위
Stable RPC 유형은 Unary와 Server Streaming뿐이다. Client Streaming, Bidirectional Streaming,
hedging, xDS, custom resolver/LB, gRPC-Web, Servlet, Reactor, Kotlin은 전부 grpc-advanced:*이며
capability flag 뒤에 있다. GrpcPlatformStartupValidator가 Stable catalog에 streaming method가
등록되면 startup을 거부한다.
grpc-spring-boot-starter는 어떤 advanced module도 참조하지 않는다. registry의
allowed_dependencies가 이를 build time에, GrpcStableBuildInvariant가 runtime에 강제한다.
Runtime membership이 비어 있다는 것의 의미
registry의 모든 grpc:* leaf는 현재 runtime_memberships가 비어 있다. messaging:*가 처음
착지했을 때와 같은 상태다:
- 배포 아티팩트가 싣고 있지 않다. build-only다.
- 애플리케이션에 배선하려면 registry의
runtime_memberships를 먼저 바꾸고verifyRuntimeModuleMembership을 통과시켜야 한다. 코드만 추가하는 것으로는 런타임에 들어가지 않는다. - 런타임에 있다는 것과 자격이 증명됐다는 것은 다르다. 현재 in-process·Netty·fault lane은 실제로
실행되어 통과하지만, 실제 배포 환경에서의 soak·performance baseline은 없다.
GrpcStableReleaseGate가 그 구분을 문서가 아니라 코드로 붙들고 있다.
application이 이 family에 도달하는 경로
messaging:*의 MSG-015(bridge 부재)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는
application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-server SPI
이고 GrpcApplicationBoundaryRules·GrpcRawApiImportRule·GrpcServiceAdapter가 그 경계를
소유한다. 현재 adapter:inbound:grpc는 이 family에 의존하지 않는다 — registry의
allowed_dependencies를 보라. 배선은 별도 결정이며, 그때 registry edge와 브리지가 함께 들어간다.
테스트 명령
focused test는 registry의 gradle_path에서 파생한다.
cd src
./gradlew :grpc:<leaf>:test --console=plain
./gradlew :grpc:grpc-testkit:grpcInProcessContractTest --console=plain
./gradlew :grpc:grpc-testkit:grpcNettyContractTest --console=plain
./gradlew :grpc:grpc-testkit:grpcFaultTest --console=plain
./gradlew :grpc:grpc-testkit:grpcPerformanceTest --console=plain
금지
grpc-core-api에서 io.grpc / Spring / protobuf / JPA 타입 사용.- Stable leaf에서
:grpc-advanced:*참조. grpc-testkit을 production leaf가 의존하는 것.- in-process 결과로 transport capability를 주장하는 것 (
GrpcEvidenceGrade가 거부한다). - metric tag에 raw metadata·payload·actor/tenant/object/stream/idempotency 식별자를 넣는 것
(
GrpcMetricCardinalityPolicy가 거부한다).