Files
grpc-library/grpc/CLAUDE.md
T

7.2 KiB

grpc — local authority for the gRPC platform family

이 문서는 grpc:* family의 local authority다. gRPC platform은 기본 application build와 분리된 src/optional-platforms build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급, Stable 범위의 경계와 application에 채택될 때 필요한 계약이다.

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에 강제한다.

Optional build에 있다는 것의 의미

grpc:*와 grpc-advanced:*는 기본 ca-skeleton settings에 include되지 않는다. 따라서 일반 :app-bootstrap:build는 이 18개 project를 configure하지 않는다. 플랫폼 자체는 ./gradlew -p optional-platforms ci로 검증하고, application runtime에 실제 채택하려면 composition root가 명시적으로 dependency를 가져오는 별도 변경이 필요하다.

런타임 포함 여부와 qualification은 별개다. in-process·Netty·fault lane이 통과해도 실제 배포 환경의 soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위는 release gate와 support matrix가 별도로 정의한다.

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가 거부한다).