Files
grpc-library/grpc/AGENTS.md
T
DongHyeonka eed2d152a5
pr / ci (pull_request) Successful in 4m0s
build: Maven group을 dev.cakit.grpc로 바꾸고 남은 hyeonworks 이름을 지운다
앞 커밋에서 패키지를 dev.cakit.grpc로 바꿨다. 배포 좌표(group)와 문서는
아직 com.hyeonworks.grpc였다.

- gradle.properties libraryGroup = dev.cakit.grpc(모든 모듈과 SBOM
  artifact의 group)
- README 받는 법(exclusiveContent 필터 dev.cakit), AGENTS.md, CHANGELOG
  옮기는 법, problem-statement, release.md, family AGENTS.md 둘
- SpotBugs 제외에서 템플릿 클래스(@RequiresPermission)를 가리키던 줄을
  지웠다. 이 repo에는 그런 bean이 없다

남긴 것: Gitea 주소 git.learn.hyeonworks.com(서버 주소), 기록
ADR-GRPC-002 본문의 「예전에는 hyeonworks」(기록 본문은 고치지 않는다).

검증: git grep -i hyeonworks에서 위 둘만 남는다. 빌드 게이트는 desktop
(이 PR 본문).
2026-11-08 14:08:45 +09:00

15 KiB

grpc — gRPC 플랫폼 family의 지역 정본

이 문서는 grpc:* family의 **지역 정본(local authority)**이다. gRPC platform은 이 repo(grpc-library)가 소유하고 Maven group dev.cakit.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가 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 조직 이름은 cakit이다(package cakit.grpc.common.v1, 생성 Java 패키지 cakit.grpc.common.v1.generated — 손으로 쓴 dev.cakit과 겹치지 않는다). 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에 배포한 버전(dev.cakit.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의 목표다. 계약상의 경로는

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에서 파생한다.

./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에 있다.