Files
grpc-library/grpc/AGENTS.md
T
DongHyeonka ce83f4d550
pr / ci (pull_request) Successful in 1m9s
docs: 별도 repo 라이브러리로서의 지침·작업 문서·릴리스 절차를 쓴다
옮겨 온 문서는 템플릿 안의 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).
2026-11-08 11:22:12 +09:00

192 lines
15 KiB
Markdown

# grpc — gRPC 플랫폼 family의 지역 정본
이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 이 repo(`grpc-library`)가 소유하고
Maven group `com.hyeonworks.grpc`로 배포한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급,
Stable 범위의 경계와 application에 채택될 때 필요한 계약이다.
루트 `AGENTS.md`와 충돌하면 루트가 이긴다.
이 family는 앱의 Clean Architecture 계층이 아니라 **RPC 플랫폼 라이브러리**다. 자기 API(port)와 adapter와 조립
경계(starter)를 가지며, 앱은 자기 inbound adapter(백엔드 템플릿이면 `adapter:inbound:grpc`)를 통해 라이브러리로서
도달한다. 2026-11-08까지 백엔드 템플릿 안(`src/platforms/grpc`)에 있었고, 그 전 이력도 이 repo에 그대로 있다.
설계 근거와 원본 계획 대비 deviation은
[docs/design/2026-08-30-grpc-platform-adaptation-design.md](../docs/design/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-contract` | `.proto` 스키마 소스(`src/main/proto`)와 protoc 생성 message. lint/breaking은 Buf(`buf.yaml`, 루트 `ci`의 `bufLint`·`bufBreaking`) | `protobuf-java`(생성 코드 runtime)만. 규칙을 Java로 재구현하지 않는다 |
| `grpc-runtime` | policy(validation, context, status/rich error, TLS/credential, deadline/cancellation, retry, idempotency, streaming, size/compression) · server(typed service adapter SPI, interceptor 순서, Netty profile) · client(named channel, runtime generation, typed stub factory) · discovery(Static/DNS, pick_first/round_robin, Kubernetes routing) · admin(health, reflection, drain, policy snapshot) | `io.grpc:grpc-api`, `grpc-stub`. Spring·Netty 자체 금지 — Netty profile은 설정 모델이다 |
| `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-runtime`의 `GrpcStatusMapping`이 단독으로 소유한다.
기본 전송 한도(메시지 1 MiB, metadata 8 KiB)는 `grpc-core-api`의 `GrpcTransportLimits` 한 곳에 있고,
server profile·named channel profile·method size profile·method policy 기본값·metadata budget이 모두
그 상수를 쓴다. `GrpcPlatformStartupValidator`는 method의 inbound 한도가 server profile 한도보다 크면
기동을 거부한다.
`.proto`의 proto 조직 이름은 `hyeonworks`다(`package hyeonworks.grpc.common.v1`, 생성 Java 패키지
`hyeonworks.grpc.common.v1.generated` — 손으로 쓴 `com.hyeonworks`와 겹치지 않는다). proto 패키지는 wire
이름이라 바꾸면 MAJOR다(`docs/work/release.md` 2절). 2026-11-08 전의 이름은 `caskeleton`이었다.
### 공용 다이제스트 헬퍼를 복사해 두는 이유
`grpc-runtime`(`GrpcRequestFingerprint`, `GrpcResumeTokenCodec`)은 SHA-256·HMAC-SHA256 계산을 자기
안에 둔다. 백엔드 템플릿 `shared-contract`의 `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 repo는
템플릿에 의존하지 않고(루트 `AGENTS.md` 5번), registry edge는 `grpc:*` 안에서만 닫힌다(위 표). 템플릿 안에
있던 때도 같은 이유로 복사본이었다(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치). 복사본을 고칠
때는 템플릿 `shared-contract`의 정본과 같은 규칙인지 함께 본다. `grpc-operation-ledger-jpa` integrationTest의
migration 헬퍼 셋도 같은 종류의 복사본이다(그 모듈 `build.gradle`).
## 증거 등급 — 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`와 `verifyCleanArchitectureDependencies`가 이를 build time에 강제한다.
## 라이브러리로 배포된다는 것의 의미
앱은 이 repo를 빌드에 넣지 않고 Gitea Packages에 배포한 버전(`com.hyeonworks.grpc:<모듈>:<버전>`)을 받는다. 플랫폼
자체는 이 repo의 `./gradlew ci`로 검증하고, 앱 runtime에 실제 채택하려면 그 앱의 조립 루트가 명시적으로
dependency를 가져오는 별도 변경이 필요하다. 백엔드 템플릿은 지금 이 라이브러리를 받지 않는다.
런타임 포함 여부와 qualification은 별개다. in-process·Netty·fault lane이 통과해도 실제 배포 환경의
soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위는 release gate와 support matrix가
별도로 정의한다.
## application이 이 family에 도달하는 경로
`messaging:*`가 겪은 bridge 부재(2026-08-14 messaging 모듈 리뷰)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는
```text
application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-runtime SPI
```
이고 `GrpcServiceAdapter`가 그 SPI를 소유한다. inbound adapter가 outbound adapter·persistence에
직접 닿지 않는 규칙은 백엔드 템플릿이면 app-bootstrap ArchUnit(`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`)이
검사한다. 현재 템플릿 `adapter:inbound:grpc`는 이 라이브러리에 의존하지 않는다. 배선은 별도 결정이며, 그때
템플릿 카탈로그 항목과 registry의 허용 라이브러리, 브리지가 함께 들어간다.
starter가 `operation-ledger-enabled=true`일 때 멱등성 판단 bean을 조립하는 것(03-11)은 이 배선이 아니다 —
starter는 서버를 만들지 않고, 그 bean을 서버에 붙이는 일은 채택하는 쪽의 몫이다(아래 「Durable operation
ledger adoption」).
## 테스트 명령
focused test는 registry의 `gradle_path`에서 파생한다.
```bash
./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`가 거부한다).
### 채택할 때의 관측 게이트
`grpc-observability`가 구현한 metric 이름은 **채택하는 앱의 metric registry(백엔드 템플릿이면
`docs/registries/metrics.yaml`)에 아직 없다**. 그 앱이 이 라이브러리를 아직 출하하지 않기 때문이다. 채택하면서 그 앱의
`.seconds` / `.total` 단위 이름 규칙에 맞는 registry 항목과 그에 맞는 검증 게이트를 더하기 전에는 그
이름을 저장소가 인증한 metric처럼 내세우지 않는다.
### durable operation 원장 채택
`grpc-spring-boot-starter`는 JPA 원장 어댑터를 전이 의존으로 끌어오지 않는다(2026-09-18 리뷰가 찾은 문제). durable
operation 멱등성이 필요한 배포는 `:grpc:grpc-operation-ledger-jpa`를 직접 더하고,
`GrpcOperationLedger` bean(`new JpaGrpcOperationLedger(repository)`)을 정의하고, 그 어댑터의 Flyway
위치 `db/migration/grpc`(V001 테이블, V002 보존 index, V003 claim attempt)를 넣고, 아래 flag를 켠다.
원장을 채택하지 않는 배포는 Spring Data JPA classpath 비용을 내지 않는다.
| 키 (`app.grpc.platform.*`) | 기본값 | 하는 일 |
| --- | --- | --- |
| `operation-ledger-enabled` | `false` | `true`: starter가 배포의 `GrpcOperationLedger` bean 위에 `GrpcIdempotencyInterceptor`(bean `grpcIdempotencyInterceptor`)와 `GrpcOperationLedgerRetention`(bean `grpcOperationLedgerRetention`)을 조립하고, 원장 bean이 없으면 기동을 거절한다. `false`: 두 bean 모두 없고, `IDEMPOTENCY_KEY_REQUIRED`인 메서드가 있으면 기동을 거절한다 |
| `operation-ledger-claim-ttl` | `5m` | `IN_PROGRESS` claim의 주인이 살아 있다고 믿는 시간. 지나면 같은 요청의 재시도가 claim을 넘겨받는다(`GrpcOperationLedger.reclaimStale`). 키가 필요한 모든 메서드의 deadline보다 길지 않으면 기동에서 거절한다 |
| `operation-ledger-retention` | `24h` | 끝난(`COMMITTED`/`FAILED_TERMINAL`) 레코드를 `GrpcOperationLedgerRetention.purgeExpired`가 지울 수 있게 되기 전까지 두는 시간. `IN_PROGRESS` 행은 지우지 않는다 |
기본값: 5분 TTL은 원장 계약 시험과 interceptor 시험이 인증한 값이다. unary deadline보다 훨씬 길고,
주인이 죽은 키가 클라이언트의 재시도 인내 안에 풀릴 만큼 짧다. 24시간 보존은 HTTP 멱등성 재생 TTL
(`app.capabilities.idempotency.replay-ttl`)과 같다. 레코드를 지운 뒤 같은 키로 하는 재시도는 새
operation이므로, 보존 시간은 호출자의 재시도 창보다 길어야 한다.
이 키들은 채택하는 앱의 환경 변수 registry(백엔드 템플릿이면 `docs/registries/env-keys.yaml`)에 아직 없다.
조립 루트가 플랫폼을 채택할 때 그 registry에 들어간다. 키 이름(`app.grpc.platform.*`)은 이 라이브러리의 공개
계약이라 바꾸면 MAJOR다.
**starter가 interceptor를 조립하는 이유(선택지 (b)), (a)가 아닌 이유.** 2026-11-01 성숙도 리뷰는
(a)를 제안했다: flag를 지우고 원장 bean이 있는지로 판단한다. 2026-11-03에 (b)를 골랐고 ADR-GRPC-004에
적었다: flag를 남기고 flag는 말 그대로의 뜻이다 — true이면 판정 함수를 조립하고 그 TTL은 설정에서
온다. (a)는 거짓 약속을 없앴겠지만 채택하는 쪽마다 같은 조립과 TTL 검증을 손으로 다시 만들게
했다. (b)는 그것을 한곳에 둔다. interceptor bean에는 일부러 `@ConditionalOnMissingBean`이 없다:
바꿔 넣은 bean은 `operation-ledger-claim-ttl`을 소리 없이 무시하게 된다. 돌고 있는 operation의
중복은 기다리라고 하지 않고 거절한다(`REJECT_IN_PROGRESS`). 기다렸다가 다시 묻는 선택지는 키가
필요한 메서드가 그것을 필요로 할 때 키가 된다.
**서버 배선은 여전히 채택하는 쪽의 몫이고, 따로 정할 일로 남는다.** starter는 서버를 만들지
않으므로, 판정을 조립한다고 플랫폼이 `adapter:inbound:grpc`에 배선되지는 않는다(위 "배선은
별도 결정"을 본다). `GrpcIdempotencyInterceptor`는 판정 함수이고 `io.grpc.ServerInterceptor`가
아니다. 채택하는 쪽은 bean을 타입으로 주입받아 자기 `IDEMPOTENCY` 단계 interceptor
(`GrpcServerInterceptorChain.builder().stage(GrpcServerInterceptorStage.IDEMPOTENCY, ...)`)나 자기
typed service adapter에서 부른다: 변경 전에 `decide(...)`, 변경의 트랜잭션 안에서
`recordCommit(...)`, 끝난 실패에 `recordFailure(...)`. 두 기록 호출은 모두 `PROCEED` 판정이 실어 온
`GrpcClaimToken`을 받는다: claim을 넘겨준 시도의 커밋은 거절되고(그 트랜잭션은 롤백된다) 그 실패는
무시된다. 그래서 느린 주인이 claim을 가져간 시도를 덮어쓰지 못한다(ADR-GRPC-004).
**지우기 일정은 채택하는 쪽의 몫이다.** `GrpcOperationLedgerRetention.purgeExpired(now)`는 기한이 지난
끝난 행을 한계 있는 batch(문장 하나에 500)로 지우고, batch가 덜 차서 돌아오면 멈춘다. starter는 이것을
예약하지 않는다: scheduler를 가지지 않고 어느 replica가 돌려야 하는지 알 수 없으며, 예약된 bean은 모든
배포에 task scheduler를 강요하게 된다. 채택하는 쪽이 자기 scheduler에서 부른다(예: 한 시간마다).
지우기가 잠긴 행을 건너뛰므로 여러 replica에서 동시에 돌려도 안전하다. 한 번도 돌리지 않아도 안전하지만
테이블이 끝없이 커진다.
커밋은 변경의 트랜잭션 안에서 기록해야 하고 TTL은 키가 필요한 가장 느린 메서드보다 길어야 한다. 두
이유는 모두 ADR-GRPC-004에 있다.