docs: 별도 repo 라이브러리로서의 지침·작업 문서·릴리스 절차를 쓴다
pr / ci (pull_request) Successful in 1m9s

옮겨 온 문서는 템플릿 안의 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).
This commit is contained in:
DongHyeonka
2026-11-08 11:22:12 +09:00
parent 8d705bcaaf
commit ce83f4d550
15 changed files with 382 additions and 98 deletions
+32 -33
View File
@@ -1,17 +1,17 @@
# grpc — gRPC 플랫폼 family의 지역 정본
이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 기본 application build와 분리된
`src/platforms/optional-build` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급,
이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 이 repo(`grpc-library`)가 소유하고
Maven group `com.hyeonworks.grpc`로 배포한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급,
Stable 범위의 경계와 application에 채택될 때 필요한 계약이다.
루트 `AGENTS.md`와 충돌하면 루트가 이긴다.
이 family는 Clean Architecture의 계층이 아니라 **벤더드 RPC 플랫폼**이다 — `messaging:*`와 같은
자리에 있고 같은 이유로 있다. 자기 API(port)와 adapter와 조립 경계(starter)를 가지며, 애플리케이션은
`adapter:inbound:grpc`를 통해 라이브러리로서 도달한다.
이 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다.
[docs/design/2026-08-30-grpc-platform-adaptation-design.md](../docs/design/2026-08-30-grpc-platform-adaptation-design.md)가 SSOT다.
## Family와 framework 규칙
@@ -20,7 +20,7 @@ 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 job `grpc-proto-buf`) | `protobuf-java`(생성 코드 runtime)만. 규칙을 Java로 재구현하지 않는다 |
| `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에 있다** |
@@ -37,18 +37,18 @@ server profile·named channel profile·method size profile·method policy 기본
그 상수를 쓴다. `GrpcPlatformStartupValidator`는 method의 inbound 한도가 server profile 한도보다 크면
기동을 거부한다.
`.proto`의 proto 조직 이름은 `caskeleton`이다(`package caskeleton.grpc.common.v1`, 생성 Java 패키지
`caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할
때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다.
`.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`을 쓰지 않는 것은 의도다. 이
family는 optional build에 있는 vendored 플랫폼이고 registry edge는 `grpc:*` 안에서만 닫힌다(위 표).
`shared-contract` edge를 주면 플랫폼이 템플릿 계약 leaf에 묶여 따로 떼어 쓸 수 없게 된다 — messaging
family가 같은 이유로 고른 배치(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정함)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과
같은 규칙인지 함께 본다.
안에 둔다. 백엔드 템플릿 `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인 이유
@@ -82,12 +82,11 @@ capability flag 뒤에 있다. `GrpcPlatformStartupValidator`가 Stable catalog
`grpc-spring-boot-starter`는 어떤 advanced module도 참조하지 않는다. registry의
`allowed_dependencies`와 `verifyCleanArchitectureDependencies`가 이를 build time에 강제한다.
## Optional build에 있다는 것의 의미
## 라이브러리로 배포된다는 것의 의미
`grpc:*`와 `grpc-advanced:*`는 기본 `ca-skeleton` settings에 include되지 않는다. 따라서 일반
`:app-bootstrap:build`는 이 project들을 configure하지 않는다(목록은 registry의 `"build": "optional-grpc"`). 플랫폼 자체는
`./gradlew -p platforms/optional-build ci`로 검증하고, application runtime에 실제 채택하려면 composition root가
명시적으로 dependency를 가져오는 별도 변경이 필요하다.
앱은 이 repo를 빌드에 넣지 않고 Gitea Packages에 배포한 버전(`com.hyeonworks.grpc:<모듈>:<버전>`)을 받는다. 플랫폼
자체는 이 repo의 `./gradlew ci`로 검증하고, 앱 runtime에 실제 채택하려면 그 앱의 조립 루트가 명시적으로
dependency를 가져오는 별도 변경이 필요하다. 백엔드 템플릿은 지금 이 라이브러리를 받지 않는다.
런타임 포함 여부와 qualification은 별개다. in-process·Netty·fault lane이 통과해도 실제 배포 환경의
soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위는 release gate와 support matrix가
@@ -102,9 +101,9 @@ application-owned port → adapter:inbound:grpc (typed service adapter) → :grp
```
이고 `GrpcServiceAdapter`가 그 SPI를 소유한다. inbound adapter가 outbound adapter·persistence에
직접 닿지 않는 규칙은 app-bootstrap ArchUnit(`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`)이
검사한다. 현재 `adapter:inbound:grpc`는 이 family에 의존하지 않는다 — registry의
`allowed_dependencies`를 보라. 배선은 별도 결정이며, 그때 registry edge와 브리지가 함께 들어간다.
직접 닿지 않는 규칙은 백엔드 템플릿이면 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」).
@@ -114,12 +113,11 @@ ledger adoption」).
focused test는 registry의 `gradle_path`에서 파생한다.
```bash
cd src
./gradlew -p platforms/optional-build :grpc:<leaf>:test --console=plain
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest --console=plain
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcNettyContractTest --console=plain
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcFaultTest --console=plain
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcPerformanceTest --console=plain
./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
```
## 금지
@@ -134,8 +132,8 @@ cd src
### 채택할 때의 관측 게이트
`grpc-observability`가 구현한 metric 이름은 **아직 `docs/registries/metrics.yaml`에 등록하지
않았다**. 이 optional family는 출하하는 런타임 capability가 아니기 때문이다. 채택하면서 저장소의
`grpc-observability`가 구현한 metric 이름은 **채택하는 앱의 metric registry(백엔드 템플릿이면
`docs/registries/metrics.yaml`)에 아직 없다**. 그 앱이 이 라이브러리를 아직 출하하지 않기 때문이다. 채택하면서 그 앱의
`.seconds` / `.total` 단위 이름 규칙에 맞는 registry 항목과 그에 맞는 검증 게이트를 더하기 전에는 그
이름을 저장소가 인증한 metric처럼 내세우지 않는다.
@@ -159,8 +157,9 @@ operation 멱등성이 필요한 배포는 `:grpc:grpc-operation-ledger-jpa`를
(`app.capabilities.idempotency.replay-ttl`)과 같다. 레코드를 지운 뒤 같은 키로 하는 재시도는 새
operation이므로, 보존 시간은 호출자의 재시도 창보다 길어야 한다.
이 키들은 `docs/registries/env-keys.yaml`에 없다. optional 빌드는 출하하는 런타임이 아니라서
`app.grpc.platform.*` 키는 하나도 없다. 조립 루트가 플랫폼을 채택할 때 registry에 들어간다.
이 키들은 채택하는 앱의 환경 변수 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에