118 lines
7.4 KiB
Markdown
118 lines
7.4 KiB
Markdown
# 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](../../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의 목표다. 계약상의 경로는
|
|
|
|
```text
|
|
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`에서 파생한다.
|
|
|
|
```bash
|
|
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`가 거부한다).
|