Merge pull request 'docs: 별도 repo 라이브러리로서의 지침·작업 문서·릴리스 절차를 쓴다' (#1) from docs/library-guides into main
main / main-check (push) Successful in 5m30s

This commit was merged in pull request #1.
This commit is contained in:
2026-11-08 04:51:00 +00:00
21 changed files with 446 additions and 115 deletions
+2 -2
View File
@@ -4,7 +4,7 @@
# anonymously). Publishing starts only after releaseCheck has passed, so a red check leaves nothing
# half-published (Gitea refuses a second upload of a version).
#
# Secrets (repository settings, created by the owner): PACKAGES_TOKEN, a personal access token with
# Secrets (repository settings, created by the owner): PACKAGE_TOKEN, a personal access token with
# package read/write only (the job token cannot publish packages); SIGNING_KEY, an ASCII-armoured PGP
# secret key; SIGNING_PASSWORD, its passphrase.
name: release
@@ -36,7 +36,7 @@ jobs:
- run: ./gradlew releaseCheck release --stacktrace
env:
RELEASE_TAG: ${{ github.ref_name }}
PACKAGES_TOKEN: ${{ secrets.PACKAGES_TOKEN }}
PACKAGE_TOKEN: ${{ secrets.PACKAGE_TOKEN }}
SIGNING_KEY: ${{ secrets.SIGNING_KEY }}
SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }}
TESTCONTAINERS_REUSE_ENABLE: "false"
+18 -16
View File
@@ -1,36 +1,38 @@
# AGENTS.md — grpc-library의 정본
gRPC 서버·클라이언트를 Spring Boot 앱에 붙이는 플랫폼 라이브러리다(Stable 7 모듈, advanced 2 모듈). 방향은 `docs/vision.md`, 풀 문제와 하지 않을 것은 `docs/problem-statement.md`다.
Spring Boot 앱에 gRPC 서버·클라이언트를 붙이는 플랫폼 라이브러리다(Maven group `com.hyeonworks.grpc`). 백엔드 템플릿에서 2026-11-08에 이력째 옮겨 왔다. 왜 따로 두는지와 받는 법은 `README.md`, 풀 문제는 `docs/problem-statement.md`다.
## 꼭 지킬 것 — 하나라도 어기면 동작해도 완료가 아니다
1. 관련 검증(아래 「검증」) 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.
2. 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 명령을 한다.
3. 비밀 값(`.env`, 키, 토큰)을 읽거나 커밋한다.
4. (채울 것: 이 프로젝트의 아키텍처 불변식. 예: 도메인 계층이 프레임워크·DB를 import한다)
3. 비밀 값(`.env`, 키, 토큰)을 읽거나 커밋한다. 배포 토큰·서명 키는 repo secret에만 있다.
4. `grpc-core-api`가 io.grpc·Spring·protobuf·JPA 타입을 쓰거나, Stable 모듈(`grpc/*`)이 `grpc-advanced/*`를 쓴다.
5. 백엔드 템플릿의 타입이나 파일 경로에 기댄다. 필요하면 edge 없는 복사본을 두고 이유를 그 모듈 `build.gradle`에 적는다.
6. 배포한 버전을 지우거나 같은 버전을 다시 올린다. 잘못 나갔으면 다음 PATCH를 낸다.
7. 공개 타입·proto를 바꾸면서 버전 규칙(`docs/work/release.md` 2절)을 따르지 않는다.
## 지도
- (채울 것: 최상위 폴더 → 하는 일. 개수·버전 숫자는 적지 않는다. 정본이 따로 있으면 그 파일을 가리킨다)
- 폴더마다의 규칙은 그 폴더의 `AGENTS.md`다. 작업 파일과 가장 가까운 것을 따른다.
- 결정 기록은 `docs/adr/`(양식 `0000-template.md`), 예측·실측 장부는 `docs/ledger/`다.
- `grpc/`(Stable)·`grpc-advanced/`(capability flag 뒤): 모듈. 모듈 목록·경로·허용 의존의 정본은 registry `config/architecture/modules.json`이다. 개수는 적지 않는다.
- `build-logic/`: 템플릿에서 복사해 줄인 convention 플러그인. 어디서 복사했고 무엇을 고쳤는지는 `build-logic/UPSTREAM.md`.
- `build.gradle`: 단계 태스크(`ci`·`mainCheck`·`releaseCheck`·`release`). `.gitea/workflows/`는 단계마다 Gradle 한 줄이다.
- `scripts/`: 고정 도구(`tool.sh`), Buf(`buf.sh`), 릴리스 보조(`release/`), 검증 진입점(`verify.sh`).
- 폴더마다의 규칙은 그 폴더의 `AGENTS.md`다(`grpc/`, `grpc-advanced/`, `build-logic/`). 결정 기록은 `docs/adr/`, 장부는 `docs/ledger/`.
## 맡은 일
- (채울 것: 일의 종류 → 먼저 읽을 문서. 예: 새 기능 → `docs/…`)
- 고치기·리뷰 → `docs/work/README.md`, 게이트 고르기 → `docs/work/gates.md`, 릴리스 → `docs/work/release.md`.
- 템플릿과 같이 고치기(composite build), 소비자 영향 확인 → `docs/work/README.md` 3절.
- brief가 있으면 brief의 범위·크기·완료 기준이 먼저다.
## 검증
- 진입점은 하나다: `scripts/verify.sh <단계>`(docs · unit · pr · app). 사람·CI·에이전트가 같은 명령을 쓴다.
- 무거운 실행을 다른 기계에서 돌릴 때는 `scripts/verify.sh <단계> --on <호스트>`(지금 작업 트리를 패치로 옮긴다).
## 헷갈리는 곳
- (채울 것: 코드만 보고는 알 수 없는 것. 없으면 이 절을 지운다)
- 진입점: `scripts/verify.sh <단계>`(docs · unit · pr · main · release). 사람·CI·에이전트가 같은 명령을 쓴다.
- Gradle·Docker는 소유자 환경에서 desktop에서만 돈다: `scripts/verify.sh pr --on desktop`.
## 일하는 방식
- 착수할 때 예측을, 끝날 때 실측을 장부에 남긴다(Claude Code는 `estimate` 스킬).
- 파일을 바꾸는 위임은 사람이 열어 보고 멈출 수 있는 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다.
- 커밋 메시지·PR 규칙: (채울 것: 규칙 문서 경로)
- 착수할 때 예측을, 끝날 때 실측을 `docs/ledger/estimates.jsonl`에 남긴다(Claude Code는 `estimate` 스킬).
- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일은 서브에이전트에 맡긴다.
- 커밋·PR 규칙: design-docs `conventions/commit-and-pr.md`(PR 본문 칸은 `.gitea/pull_request_template.md`).
+16
View File
@@ -0,0 +1,16 @@
# 바뀐 것
버전마다 바뀐 것과, 깨지는 변경이면 옮기는 법을 쓴다. 버전 규칙은 `docs/work/release.md` 2절이다.
## 1.0.0 — 아직 내지 않음
백엔드 템플릿 안에 있던 gRPC 플랫폼(`src/platforms/grpc`, `src/platforms/grpc-advanced`)의 첫 배포 버전이다.
### 템플릿 안에서 쓰던 코드에서 옮기는 법
템플릿 안 코드를 직접 썼다면(템플릿 기준 커밋 `22df3525` 이전):
- Java 패키지: `dev.caskeleton.grpc.*` → `com.hyeonworks.grpc.*`. import를 바꾼다.
- proto 패키지: `caskeleton.grpc.common.v1` → `hyeonworks.grpc.common.v1`, 생성 Java 패키지 `caskeleton.grpc.common.v1.generated` → `hyeonworks.grpc.common.v1.generated`. proto는 wire 이름이므로 상대편도 함께 바꾼다.
- Gradle: `project(':grpc:<모듈>')` → `com.hyeonworks.grpc:<모듈>:1.0.0`(저장소 선언은 README 「받는 법」).
- 설정 키 `app.grpc.platform.*`와 Flyway 위치 `db/migration/grpc`는 그대로다.
+12 -2
View File
@@ -3,5 +3,15 @@
## Claude Code에서만
- 권한은 `.claude/settings.json`이다: 실제 `.env` 읽기·쓰기를 막는다(`.env.example` 같은 예시는 막지 않는다).
- 공통 훅과 스킬은 하네스 플러그인 `harness@claude-harness`가 준다: 되돌릴 수 없는 명령 차단, 비밀 값 알림, 예측·실측 장부 기록, `estimate`·`retro`·`techdebt`. 플러그인 설명은 claude-harness repo의 README다.
- 이 프로젝트만의 훅은 `scripts/hooks/`, 경로별 규칙은 `.claude/rules/`, 스킬은 `.claude/skills/`, 서브에이전트는 `.claude/agents/`에 둔다.
- 공통 훅과 스킬은 하네스 플러그인 `harness@claude-harness`가 준다: 되돌릴 수 없는 명령 차단, 비밀 값 알림, 예측·실측 장부 기록, `estimate`·`retro`·`techdebt`. 대화형 Claude Code는 이 폴더를 처음 믿을 때 설치를 묻는다. 비대화형(`claude -p`)은 묻지도 설치하지도 않으니 이 폴더에서 한 번 돌린다(설정 파일은 이미 맞다).
```bash
claude plugin marketplace add https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git --scope project
```
```bash
claude plugin install harness@claude-harness --scope project
```
- 이 repo만의 훅·경로 규칙·스킬·서브에이전트는 아직 없다. 생기면 `scripts/hooks/`, `.claude/rules/`, `.claude/skills/`, `.claude/agents/`에 둔다.
- 소유자 환경: Gradle·Docker는 desktop에서만 돈다. `scripts/verify.sh <단계> --on desktop`(무거운 실행은 `/tmp/claude-gates/heavy.lock` 아래).
+108 -9
View File
@@ -1,13 +1,112 @@
# optional gRPC 플랫폼
# grpc-library
기본 애플리케이션은 `grpc/*`나 `grpc-advanced/*`에 의존하지 않는다. 그래서 이 프로젝트들(registry에서
`"build": "optional-grpc"`인 항목)은 주 멀티 프로젝트 빌드에서 뺀다. 이 빌드는 그 프로젝트들의 원래
프로젝트 경로와 내부 프로젝트 의존을 그대로 두면서, 그 설정을 고를 때만 켜지게 한다.
Spring Boot 앱에 gRPC 서버·클라이언트를 붙이는 플랫폼 라이브러리다. 타입 있는 서비스 adapter, method 정책(deadline·멱등성·크기 한도), 실행 증거와 실패 모델, durable operation 원장, 관측 규칙, 인증 lane(in-process·실제 Netty·fault·performance)을 준다.
```bash
./gradlew -p platforms/optional-build ci
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest
```text
앱 소유 port ──> 앱의 inbound adapter ──> grpc-spring-boot-starter (조립)
├─ grpc-runtime (io.grpc 위의 정책·서버·클라이언트)
├─ grpc-core-api (Java 표준 라이브러리만: 식별자·정책·증거·실패 모델)
├─ grpc-observability (metric·trace 규칙)
└─ grpc-operation-ledger-jpa (선택: 멱등성 원장)
```
`adapter:inbound:grpc`는 애플리케이션 어댑터라서 주 애플리케이션 빌드에 남는다. 다시 쓰는 gRPC
플랫폼 라이브러리는 optional capability 코드이고 여기 있다.
## 받는 법
Maven group은 `com.hyeonworks.grpc`, artifact는 모듈 이름 그대로다(`grpc-core-api`, `grpc-runtime`, `grpc-spring-boot-starter`, …). 저장소는 소유자 Gitea Packages이고, 공개라 읽을 때 토큰이 필요 없다.
```groovy
// settings.gradle
dependencyResolutionManagement {
repositories {
exclusiveContent {
forRepository {
maven { url = 'https://git.learn.hyeonworks.com/api/packages/donghyeon.kang/maven' }
}
filter { includeGroupByRegex 'com\\.hyeonworks(\\..*)?' }
}
mavenCentral()
}
}
```
```groovy
// build.gradle
dependencies {
implementation 'com.hyeonworks.grpc:grpc-spring-boot-starter:1.0.0'
}
```
`exclusiveContent`는 `com.hyeonworks` group을 이 저장소에서만, 나머지는 Maven Central에서만 찾게 한다. 같은 이름을 공개 저장소에 올리는 공격이 통하지 않고, Gitea가 느려도 다른 의존성 해석에는 영향이 없다.
## 지원 표
| 라이브러리 | Spring Boot(컴파일·시험한 줄) | io.grpc BOM | Java |
| --- | --- | --- | --- |
| 1.0.x | 4.0.x (`4.0.9`) | 1.75.0 | 21 |
무엇을 인증했고 무엇은 지켜보기만 하는지는 `docs/compatibility/grpc-support-matrix.md`와 `grpc-advanced-support-matrix.md`다.
## 프로젝트 구조
| 폴더 | 무엇 |
| --- | --- |
| `grpc/` | Stable 모듈 7개(Unary, Server Streaming). 규칙은 `grpc/AGENTS.md` |
| `grpc-advanced/` | capability flag 뒤의 고급 능력 2개(client·bidi streaming, xDS, gRPC-Web 등). 규칙은 `grpc-advanced/AGENTS.md` |
| `build-logic/` | 백엔드 템플릿에서 복사해 줄인 Gradle convention 플러그인. 출처는 `build-logic/UPSTREAM.md` |
| `config/` | 모듈 registry(`architecture/modules.json`), Checkstyle·SpotBugs 설정, 테스트 컨테이너 이미지 |
| `scripts/` | 검증 진입점 `verify.sh`, 고정 도구 `tool.sh`, Buf `buf.sh`, 릴리스 보조 `release/` |
| `.gitea/workflows/` | 단계 파일 셋: `pr.yml`(`ci`), `main.yml`(`mainCheck`), `release.yml`(`releaseCheck release`) |
| `docs/` | 문서. 지도는 `docs/README.md` |
## 문서 지도
- 작업 방법: `docs/work/README.md`(고치기·리뷰), `docs/work/gates.md`(게이트), `docs/work/release.md`(릴리스·버전 규칙·비밀 값)
- 결정 기록: `docs/adr/`(ADR-GRPC-001~006, ADR-GRPC-ADV-001)
- 운영: `docs/runbooks/grpc-platform-operations.md`, `docs/runbooks/grpc-advanced-capabilities.md`
- 설계서: `docs/design/2026-08-30-grpc-platform-adaptation-design.md`
- 바뀐 것: `CHANGELOG.md`
## 서명
배포 파일마다 PGP 서명(`.asc`)이 붙는다. 서명 키는 RSA 4096, 지문 `92646CEAFE816CF8B9C249F0A1C936D7F791F8AB`, 2028-11-07에 만료된다. 키를 바꾸는 법은 `docs/work/release.md` 1절이다.
```text
-----BEGIN PGP PUBLIC KEY BLOCK-----
mQINBGrv1SYBEADGgq8CTE7wdDPIg0zNRXelPvlgyK04tpDTL0b9k1INxDwFEiS0
87bTL22Zjipp+2uDg012TALeLsDV12yh1IToNaYq7zR9bRvEua25+351zw91ojC+
z2/1Y7S98o813hu6qP6EFUHnsWPVLEt40mlGDn3kl8iXMLgjozVYbylomweh/Yvz
HLJd5lQGE76mIejIeGp3m1OA5M2RV4xspA8K8TZkXXSqe3nbfSjPXAOwysPmRRd9
IoLDwakSq4tRI9dlm08bzznsoaaTCRcJ0XAbJK7+ZrQkSwIrsi/gsBkCOJI6Wcs6
+R+9Wy7tYsyd59TdgIdjq3uHadSLWQ3dc0g0ux2krxSL0PHXrT9Upmcorj2+Ltkh
9J1I6hUv1O7e0Y8Es7Ov5WUPfdSdQ5ApwtwFX5aSwYokoW9wXMLg2zdQx0JEx1ix
/qTEvpSKfM0/zVbKJO9RDF/F7HZkDWSOhZe+4x7dak+xN6KOfEQVmcBneaGtPqgJ
eAsIBgRwp42G5llqnTcWAHLAKCDEE9wHK3+gJt5f5rO5e+r1GoYHLn0Iw3iiX6rC
NFot/5my/oePTeRur5tjv14kw1FMXHVNvLOxHeaiZzfVVjO/vbwAtGvZDiRdAgd6
kHyt9Ch/JccIa0ylA9Tttb0A33ZGTQl6sAC6jTSIhfnEAdlCX7MVAE8n4wARAQAB
tCNkb25naHllb24ua2FuZyA8ZG9uZzUxMjlAZ21haWwuY29tPokCVwQTAQoAQRYh
BJJkbOr+gWz4ucJJ8KHJNtf3kfirBQJq79UmAhsDBQkDwmcABQsJCAcCAiICBhUK
CQgLAgQWAgMBAh4HAheAAAoJEKHJNtf3kfir2j8P/RWRT0GTxBNQvm76iO6XnvFD
mDPGq37A5iuD4pJ624/BccKTGe8+WWqtlpAiN6AdHGNi/LGhuYaGL9ce6Gja5tTX
y/ZY8jthbEoi41g6cim8W8knd3v2Ne/qj3dKvphSiVsZBrumEzrZyw2UUD3IRqVx
r2WQZTcSa4UDd7+Qie0h8IrnmfMYIseDCWjDCATNJqr9PBGoKYehv8+Wo3QDVBRd
B0lWepudJjLTsPCXsgFnFJ2HmltRQr1JB+I4CPasfsBp3xqF23hywUuW6fOsHZvv
g5QU7qYfaoxG6E8krGpiibocF5EKXtpEYzDOBFoDS9uNVBAD/LzS7OGtTFr5x3qL
is3eccwNClQS1jeX8Guxam+TlO8XaqnQLCIpdau20/sge6PqXKXauKZiBTGCak1j
zVDQ/sro3VRPePusNHK1CdOi6wiruXw4ZLWO3aEHibi8LbgfwymxXHEtJO5zwFcD
qAnp7KEAkOG8y5LR0FfwWWYnqUZxWJ0ua2Acf8gL8o6DO5pVyJSYrdgCpWjwEWcp
Ms2iit9bCNIMaH6EVgLA2NWCuIL9xAFdXqw/VXrMVK3XXftzNvayvLJCH2eintRg
IKLO/ewISKIFQd3+II3/MM80eUvKGtfi8Y1mj1zyQtcPVykru5DEHjpaLs2SPxdI
Lp+HGQo/NvzwdpIV+8TQ
=eD8w
-----END PGP PUBLIC KEY BLOCK-----
```
받은 파일을 확인하는 법: 위 키를 `gpg --import`로 넣고 `gpg --verify <파일>.asc <파일>`. 배포 토큰 secret 이름은 설계 문서의 `PACKAGES_TOKEN`이 아니라 등록된 `PACKAGE_TOKEN`이다.
## 이력
- 2026-08-31 ~ 2026-11-07: 백엔드 템플릿 `clean-architecture-backend-template` 안에서 만들었다(`src/grpc`, `src/grpc-advanced`, `src/optional-platforms` → 2026-11-07부터 `src/platforms/…`).
- 2026-11-08: `git filter-repo`로 그 경로들의 이력을 이 repo로 옮겼다(템플릿 main `22df3525` 기준). 옮긴 코드 폴더의 트리 해시는 템플릿 기준 커밋과 같다.
- filter-repo가 커밋 SHA를 모두 다시 썼다. 코드 주석과 문서가 부르는 커밋 SHA와 리뷰 ID(`RR6-…`, `BUILD-O3-5` 등)는 **템플릿 repo** 기준이다. 그 리뷰 문서는 템플릿 `docs/reviews/`에 남아 있다.
- 설계와 결정: design-docs `repo-structure/05-library-repos.md`(소유자 승인 2026-11-07).
+1
View File
@@ -25,6 +25,7 @@
| `java/JavaConventionsPlugin` | `group`을 `gradle.properties`의 `libraryGroup`에서 읽는다(템플릿은 `dev.caskeleton` 고정). 버전은 `RELEASE_TAG`/`-PreleaseTag`(`vX.Y.Z`)에서도 읽는다. 이미지 목록·도구 설정은 루트의 `config/`만 본다 |
| `quality/QualityConventionsPlugin` | 도구 설정은 루트의 `config/`만 본다 |
| `convention/PlatformModuleConventionPlugin` | `ca.library-publishing`을 함께 켠다 |
| `ModuleRegistry` | registry 행의 `build` 칸을 거절한다. main이 아닌 값(오타 포함)이면 그 모듈이 조용히 빌드에서 빠졌다. 템플릿 `91804ec1` 뒤 브랜치 `claude/x2-grpc-library-43dd09`에 같은 수정이 있다 |
| `strictlane/StrictLaneStagesPlugin` | 단계의 계획을 따라갈 때 included build 태스크(`ci`가 부르는 build-logic `test`)는 묻지 않는다. 템플릿 `ci`에는 그런 의존이 없어 드러나지 않았다. 템플릿에도 옮길 만한 수정이다 |
| 새 `publishing/LibraryPublishingPlugin`(`ca.library-publishing`) | 모듈마다 Maven publication(sources·javadoc jar, 해석된 버전), 저장소 `gitea`·`staging`, `SIGNING_KEY`가 있으면 PGP 서명 |
| 테스트 fixture | `source_path`를 Gradle 루트 기준으로, `PlatformModuleConventionTest`에 `libraryGroup` |
@@ -108,7 +108,16 @@ public record ModuleRegistry(List<Module> modules, File source) {
String id = requireNonBlankText(module, "id", index);
String gradlePath = requireNonBlankText(module, "gradle_path", index);
String sourcePath = requireNonBlankText(module, "source_path", index);
String buildName = module.has("build") ? requireNonBlankText(module, "build", id) : "main";
// Every module belongs to the one build. A row naming any other build (a typo included) would
// be included by no settings and checked by no direction gate while ci stays green, so the
// field is refused rather than read (the template's optional build, which used it, is gone).
if (module.has("build")) {
throw new IllegalStateException(
"Module registry entry '"
+ id
+ "' has a 'build' field; every module belongs to the main build, so remove it.");
}
String buildName = "main";
List<String> allowedDependencies =
requireStringList(module.get("allowed_dependencies"), id, "allowed_dependencies");
@@ -23,7 +23,7 @@ import org.gradle.plugins.signing.SigningExtension;
*
* <ul>
* <li>{@code gitea}: {@code packagesUrl} from gradle.properties, authenticated with the {@code
* Authorization: token <PACKAGES_TOKEN>} header. Gitea's job token cannot publish packages,
* Authorization: token <PACKAGE_TOKEN>} header. Gitea's job token cannot publish packages,
* so the token is a package-scoped personal access token in a repository secret; it is read
* from the environment and never written to a file.
* <li>{@code staging}: {@code build/staging-repository} under the root project. {@code
@@ -78,7 +78,7 @@ public final class LibraryPublishingPlugin implements Plugin<Project> {
Provider<String> packagesUrl = project.getProviders().gradleProperty("packagesUrl");
Provider<String> repositoryUrl = project.getProviders().gradleProperty("repositoryUrl");
Provider<String> token = project.getProviders().environmentVariable("PACKAGES_TOKEN");
Provider<String> token = project.getProviders().environmentVariable("PACKAGE_TOKEN");
PublishingExtension publishing = project.getExtensions().getByType(PublishingExtension.class);
MavenPublication publication =
@@ -166,7 +166,7 @@ public final class LibraryPublishingPlugin implements Plugin<Project> {
}
if (token.getOrElse("").isBlank()) {
throw new GradleException(
"PACKAGES_TOKEN is not set; Gitea's job token cannot publish packages.");
"PACKAGE_TOKEN is not set; Gitea's job token cannot publish packages.");
}
});
}
@@ -87,7 +87,17 @@ class ModuleRegistryTest {
}
@Test
void buildOwnershipDefaultsToMainAndCanSelectOptionalModules() throws Exception {
void everyModuleBelongsToTheMainBuild() throws Exception {
ModuleRegistry parsed = read(registry(entry("app-bootstrap", ":app-bootstrap", "src/alpha")));
assertEquals("main", parsed.byId("app-bootstrap").buildName());
assertEquals(List.of("app-bootstrap"), parsed.modulesForBuild("main").stream().map(ModuleRegistry.Module::id).toList());
}
@Test
void aBuildFieldIsRejectedBecauseNoOtherBuildIncludesOrChecksTheModule() throws Exception {
// The optional gRPC build was the only other build; it moved to its own repository on
// 2026-11-08. A row naming any other build (a typo included) would be included by no settings
// and checked by no direction gate, while ci stays green.
Files.createDirectories(root.resolve("src/grpc/grpc-client"));
String json =
registry(
@@ -96,15 +106,13 @@ class ModuleRegistryTest {
{"id":"grpc-client","gradle_path":":grpc:grpc-client","source_path":"src/grpc/grpc-client",
"allowed_dependencies":[],"build":"optional-grpc"}
""");
ModuleRegistry parsed = read(json);
assertEquals("main", parsed.byId("app-bootstrap").buildName());
assertEquals("optional-grpc", parsed.byId("grpc-client").buildName());
assertEquals(List.of("app-bootstrap"), parsed.modulesForBuild("main").stream().map(ModuleRegistry.Module::id).toList());
assertEquals(List.of("grpc-client"), parsed.modulesForBuild("optional-grpc").stream().map(ModuleRegistry.Module::id).toList());
IllegalStateException failure = assertThrows(IllegalStateException.class, () -> read(json));
assertTrue(failure.getMessage().contains("'grpc-client'"), failure.getMessage());
assertTrue(failure.getMessage().contains("'build'"), failure.getMessage());
}
@Test
void blankBuildOwnershipIsRefused() {
void aBlankBuildFieldIsRefusedToo() {
String json =
"""
{"modules":[
@@ -112,7 +120,7 @@ class ModuleRegistryTest {
"allowed_dependencies":[],"build":" "}]}
""";
IllegalStateException failure = assertThrows(IllegalStateException.class, () -> read(json));
assertTrue(failure.getMessage().contains("nonblank string 'build'"), failure.getMessage());
assertTrue(failure.getMessage().contains("'build' field"), failure.getMessage());
}
@Test
+3 -3
View File
@@ -177,7 +177,7 @@ publishing {
url = providers.gradleProperty('packagesUrl')
credentials(HttpHeaderCredentials) {
name = 'Authorization'
value = "token ${providers.environmentVariable('PACKAGES_TOKEN').getOrElse('')}"
value = "token ${providers.environmentVariable('PACKAGE_TOKEN').getOrElse('')}"
}
authentication {
header(HttpHeaderAuthentication)
@@ -202,13 +202,13 @@ tasks.withType(PublishToMavenRepository).configureEach {
mustRunAfter tasks.named('releaseCheck')
if (name.endsWith('ToGiteaRepository')) {
def signed = !signingKey.isBlank()
def token = providers.environmentVariable('PACKAGES_TOKEN').getOrElse('')
def token = providers.environmentVariable('PACKAGE_TOKEN').getOrElse('')
doFirst {
if (!signed) {
throw new GradleException('SIGNING_KEY is not set; refusing to publish unsigned files to Gitea.')
}
if (token.isBlank()) {
throw new GradleException('PACKAGES_TOKEN is not set; Gitea\'s job token cannot publish packages.')
throw new GradleException('PACKAGE_TOKEN is not set; Gitea\'s job token cannot publish packages.')
}
}
}
+30
View File
@@ -0,0 +1,30 @@
# 문서 지도
## 1. 어디에 무엇이 있나
| 폴더 | 종류 | 고치는 법 |
| --- | --- | --- |
| `work/` | 작업 방법(고치기, 게이트, 릴리스) | 살아 있는 문서. 동작이 바뀌면 같은 변경에서 고친다 |
| `compatibility/` | 지원 매트릭스(무엇을 인증했나) | 살아 있는 문서 |
| `runbooks/` | 운영 대응 | 살아 있는 문서 |
| `adr/` | 결정 기록(ADR-GRPC-*) | 기록. 본문은 고치지 않는다 |
| `design/` | 설계서 | 기록. 본문은 고치지 않는다 |
| `ledger/` | 예측·실측 장부 | 줄을 더하기만 한다 |
| `vision.md`, `problem-statement.md` | 방향, 풀 문제 | `vision.md`는 소유자만 쓴다 |
## 2. 기록 문서의 머리 블록
`adr/`와 `design/`의 문서는 맨 위에 머리 블록을 둔다. 본문은 쓴 때의 원문이고, 지금도 맞는지는 머리 블록이 말한다.
```markdown
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 내용이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택 | 대체됨(무엇으로) | 폐기
- 작성일: YYYY-MM-DD
- 요약: 한 문장
- 현재 정본: 지금 동작을 설명하는 살아 있는 문서 경로
<!-- 머리 블록 끝 -->
```
지난 결정이 바뀌면 본문은 두고 「상태」와 「현재 정본」만 고친다. 템플릿에서 옮겨 온 기록의 본문 경로(`src/platforms/…`, `.github/workflows/…`)는 그 결정 때의 템플릿 경로다.
+7 -7
View File
@@ -3,8 +3,8 @@
Stable gRPC 플랫폼(`:grpc:*`)이 무엇에 대해 인증됐고, 무엇에 대해서는 확인만 하고, 무엇은 지켜보기만 하는지다. 그 구별이
요점이다. 「Spring Boot와 동작한다」는 누구도 행동에 옮길 수 없는 말이다.
릴리스 gate는 `.github/workflows/release.yml`의 `grpc-stable-release-gate` job이다. 인증된 lane마다 아무것도 돌리지 않으면
실패하는 strict test lane이다.
릴리스 gate는 `.gitea/workflows/release.yml`이 돌리는 Gradle 단계 `releaseCheck`다(`docs/work/release.md`). 인증된 lane마다
아무것도 돌리지 않으면 실패하는 strict test lane이다.
> 이력: 코드 안의 `GrpcCompatibilityMatrix`/`GrpcStableReleaseGate` 짝은 지웠다(리뷰 2026-09-24 S5-lead-4). 운영 코드도 빌드
> 코드도 그것을 부르지 않아서 아무것도 막지 않았다.
@@ -26,9 +26,9 @@ Stable gRPC 플랫폼(`:grpc:*`)이 무엇에 대해 인증됐고, 무엇에 대
| | |
| --- | --- |
| Java | 21 |
| Spring Boot | 저장소 기준선, `src/gradle/libs.versions.toml`(계획은 4.1을 가정한다) |
| io.grpc | `src/gradle/libs.versions.toml`의 `grpc`. `GrpcPlatformModuleConventionPlugin`이 그 BOM을 모듈 범위로 import한다 |
| Protobuf | `src/gradle/libs.versions.toml`의 protobuf 항목(어느 leaf가 어느 것을 쓰는지는 그 파일의 주석이 적는다) |
| Spring Boot | `gradle/libs.versions.toml`의 `springBoot`(이 줄로 컴파일하고 시험한다. 버전별 표는 README 「지원 표」) |
| io.grpc | `gradle/libs.versions.toml`의 `grpc`. `GrpcPlatformModuleConventionPlugin`이 그 BOM을 모듈 범위로 import한다 |
| Protobuf | `gradle/libs.versions.toml`의 `protobufGrpc`(생성 코드 runtime과 protoc가 같은 줄) |
| Stable 전송 | Netty(shaded) |
| Stable RPC 모양 | Unary, Server Streaming |
| Stable resolver | Static, DNS, Unix domain socket |
@@ -63,8 +63,8 @@ in-process 결과는 절대 전송 증거가 아니다. in-process 전송은 TLS
## 지금 릴리스 상태
릴리스하지 않았다. registry에서 모든 `:grpc:*` leaf는 `"build": "optional-grpc"`라 주 빌드 밖에 있고 어느 조립에도 들어가지
않는다. 플랫폼은 빌드만 된다. 컴파일되고 lane이 돌지만, 배포되는 산출물 어디에도 실리지 않는다.
Gitea Packages에 아직 버전을 내지 않았다(첫 버전은 `v1.0.0`, `docs/work/release.md`). 이 라이브러리를 조립하는 앱도
아직 없다. 플랫폼은 빌드만 된다. 컴파일되고 lane이 돌지만, 배포되는 앱 어디에도 실리지 않는다.
릴리스 gate 입력 둘이 남아 있고, 그것이 지금부터 릴리스까지의 일이다.
+16 -8
View File
@@ -5,30 +5,38 @@
## 고객의 말 그대로
- (채울 것: 고객이 실제로 한 말을 따옴표로. 해석하지 않는다)
- 소유자(2026-11-07): 「템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리 폴더가 있으면 안 된다. 커스텀 라이브러리는 별도 repo로 관리하고, 매뉴얼에 관리 대상으로 둔다.」
- 고객은 이 라이브러리를 받아 쓰는 백엔드 서비스(백엔드 템플릿과 그 파생 서비스)와 그 서비스를 만드는 사람·에이전트다.
## 지금은 어떻게 버티나
- (채울 것: 고객이 지금 쓰는 우회 방법과 그 비용)
- 2026-11-08까지 이 코드는 템플릿 안의 두 번째 Gradle 빌드(`src/platforms/optional-build`)였다. 템플릿 빌드 규칙·카탈로그·testFixtures를 경로로 읽었고, 템플릿 CI가 job 넷과 단계 하나로 따로 돌렸다.
- 템플릿을 받은 파생 서비스는 쓰지도 않는 플랫폼 코드 수백 파일을 함께 받았다. 템플릿 재사용 체크리스트(「`dev.caskeleton`을 새 패키지로 바꾼다」)가 플랫폼 패키지까지 바꾸게 만들었다.
## 하지 않는 것
- (채울 것: 이번에 일부러 풀지 않는 문제, 만들지 않는 기능)
- 템플릿 `adapter:inbound:grpc`를 이 라이브러리에 배선하는 일. 별도 결정이다(`grpc/AGENTS.md` 「application이 이 family에 도달하는 경로」).
- Maven Central 배포. 템플릿 밖 공개 소비자가 생기면 본다.
- BOM. 소비자가 템플릿 하나라 카탈로그 버전 한 칸으로 충분하다. 템플릿 밖 소비자가 한 라이브러리에서 모듈 3개 이상을 쓰면 다시 본다.
- SNAPSHOT 배포. 같이 고칠 때는 composite build를 쓴다.
## 성공 기준
| 기준 | 구체적으로 | 어떻게 재나 | 목표 값 | 기한 |
|---|---|---|---|---|
| (채울 것) | | | | |
| 혼자 빌드된다 | 템플릿 없이 PR·main 단계가 초록 | Gitea Actions `pr`·`main` 실행 결과 | 초록 | 2026-11-08 |
| 배포된다 | 태그 하나로 서명된 모든 모듈이 Gitea Packages에 올라가고 익명으로 읽힌다 | release.yml, `maven-metadata.xml` | `v1.0.0` 게시 | 소유자가 비밀 값을 넣은 뒤 |
| 템플릿이 가벼워진다 | 템플릿에 gRPC 플랫폼 폴더·optional build·그 CI job이 없다 | `git ls-files src/platforms/grpc*` | 0 | 2026-11-08 PR |
## 세 관점 점검
| 관점 | 묻는 것 | 답 |
|---|---|---|
| 비즈니스 | 돈이 되나, 누가 대가를 치르나 | (채울 것) |
| 기술 | 만들 수 있나, 가장 위험한 가정은 | (채울 것) |
| 고객 | 쓸모 있나, 지금 방법보다 나은가 | (채울 것) |
| 비즈니스 | 돈이 되나, 누가 대가를 치르나 | 템플릿 유지비를 줄인다. 대가는 CI·build-logic 사본·release secret이 한 벌 더 생기는 것 |
| 기술 | 만들 수 있나, 가장 위험한 가정은 | Gitea Packages가 Gradle이 올리는 체크섬 넷과 `.asc`·`.module`을 모두 받는다는 가정(설계 16절 H8). 첫 태그에서 드러난다 |
| 고객 | 쓸모 있나, 지금 방법보다 나은가 | 쓰는 서비스는 버전으로 받고, 쓰지 않는 서비스는 아무것도 받지 않는다 |
## 되돌릴 수 없는 결정
- (채울 것: 되돌리기 비싼 결정만 여기 적고 `docs/adr/`에 결정 기록을 남긴다. 되돌릴 수 있는 결정은 빨리 한다)
- 배포한 버전은 지우지 않는다(`docs/work/release.md` 2절). 같은 버전은 다시 올릴 수 없다.
- Maven group `com.hyeonworks.grpc`와 proto 패키지 `hyeonworks.grpc.*`. 바꾸면 모든 소비자의 MAJOR다. 근거는 design-docs `repo-structure/05-library-repos.md` 6.3절.
+1 -1
View File
@@ -47,7 +47,7 @@ xDS가 켜진 동안 애플리케이션 수준의 재시도 정책을 **더하
**거의 언제나 proxy다.** gRPC 상태는 trailer로 오고, 브라우저는 proxy가 노출하지 않은 trailer를 읽지 못한다.
proxy의 CORS `expose_headers`에 `grpc-status`와 `grpc-message`가 있는지 확인한다.
`GrpcWebProxyContract.violations`가 정확히 이것을 보고하고, 참조 설정
`src/platforms/grpc-advanced/grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`에 그것이 들어 있다.
`grpc-advanced/grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`에 그것이 들어 있다.
**메서드가 client streaming이나 bidirectional streaming이면** gRPC-Web으로는 아예 되지 않는다. 브라우저는
메시지 stream을 보낼 방법이 없다. `GrpcWebRpcSupport.require`가 그런 메서드를 거부한다.
+4 -4
View File
@@ -1,7 +1,7 @@
# Runbook: gRPC platform operations
범위: `:grpc:*` family. 지금은 모두 빌드만 된다. registry에서 이 family의 leaf는 모두 `"build": "optional-grpc"`
(주 빌드 밖, `-p platforms/optional-build`로 돈다)이고 어느 조립에도 들어가지 않으므로, 여기 있는 것은 아직 운영에서
범위: `:grpc:*` family. 지금은 모두 빌드만 된다. 이 라이브러리를 실제로 쓰는 앱은 아직 없다(백엔드 템플릿의
`adapter:inbound:grpc`도 이 라이브러리가 아니라 `io.grpc`를 직접 쓴다). 그래서 여기 있는 것은 아직 운영에서
일어나지 않는다. 그래도 지금 쓰는 이유가 있다. 여기서 다루는 상태는 당번이 새벽 세 시에 처음부터 따져서는 알아낼
수 없는 것들이고, runbook보다 동작을 먼저 내보내면 그것을 처음 만난 사람이 그 따지기를 하게 된다.
@@ -156,5 +156,5 @@ snapshot에는 해시와 이름만 실린다. 자격 증명처럼 보이는 이
- **운영의 reflection.** `GrpcReflectionMode.defaultFor`는 `STAGE`와 `PROD`에 `DISABLED`를 돌려준다. reflection은
연결을 열 수 있는 누구에게나 스키마 전체를 공개한다.
- **모든 advanced capability.** `docs/runbooks/grpc-advanced-capabilities.md`를 본다.
- **플랫폼 자체.** `app.grpc.platform.enabled`의 기본값은 false이고, registry에서 모든 `:grpc:*` leaf는
`"build": "optional-grpc"`라 기본 조립에 들어가지 않는다.
- **플랫폼 자체.** `app.grpc.platform.enabled`의 기본값은 false이고, 앱이 이 라이브러리를 의존성으로 받지 않으면
아무것도 조립되지 않는다.
+40
View File
@@ -0,0 +1,40 @@
# 작업 방법 — grpc-library를 고칠 때
이 repo에서 일을 맡은 사람과 에이전트가 먼저 읽는다. 루트 `AGENTS.md`의 「꼭 지킬 것」이 이 문서보다 먼저다.
## 1. 일의 종류와 읽을 곳
| 일 | 먼저 읽을 곳 | 끝났다는 증거 |
| --- | --- | --- |
| 모듈 코드 고치기·기능 더하기 | 그 family의 `AGENTS.md`(`grpc/`, `grpc-advanced/`), 관련 ADR(`docs/adr/`) | 바꾼 모듈 `check` + `ci`(2절) |
| proto 바꾸기 | `grpc/grpc-contract/buf.yaml`, ADR-GRPC-002 | `ci`의 `bufLint`·`bufBreaking`. 깨지는 변경이면 MAJOR(`release.md` 2절) |
| 공개 타입·설정 키 바꾸기 | `release.md` 2절 | `CHANGELOG.md`에 옮기는 법, 템플릿 쪽 영향 확인(3절) |
| 빌드 규칙(build-logic) 고치기 | `build-logic/AGENTS.md`, `build-logic/UPSTREAM.md` | `buildLogicTest`(`ci` 안) |
| 릴리스 | `release.md` | release.yml 초록, 익명 메타데이터에 새 버전 |
| 리뷰 | 아래 2절의 게이트 목록과 루트 `AGENTS.md` 「꼭 지킬 것」 | 발견마다 위치·재현·고칠 곳 |
## 2. 검증
- 진입점은 `scripts/verify.sh <단계>`다. 소유자 환경에서는 Gradle·Docker를 desktop에서만 돌린다: `--on desktop`을 붙이면 지금 작업 트리를 패치로 옮겨 잠금(`/tmp/claude-gates/heavy.lock`) 아래에서 돌린다.
- 무엇을 돌릴지는 `gates.md`다. 완료를 말하기 전에 바꾼 것에 맞는 게이트를 돌리고, 못 돌렸으면 이유를 적는다.
## 3. 백엔드 템플릿과 같이 고치기
템플릿이 이 라이브러리를 버전으로 받게 되면(지금은 받지 않는다) 두 repo를 같이 바꾸는 일이 생긴다.
1. 이 repo와 템플릿에 브랜치를 하나씩 만든다. 두 repo를 같은 부모 폴더에 둔다.
2. 템플릿에서 명령 줄로만 이 repo를 끼운다. 파일은 바꾸지 않는다.
```bash
./gradlew --include-build ../grpc-library <태스크>
```
3. 그 상태로 lockfile을 쓰거나 커밋하지 않는다. 끼운 모듈은 lockfile 밖으로 빠질 수 있다.
4. 병합 순서는 하나다: 이 repo PR 병합 → 태그·릴리스 → 템플릿 PR에서 버전을 올리고 lockfile을 다시 쓴다 → 템플릿 병합. 끼운 상태로만 통과하는 템플릿 PR은 병합하지 않는다.
5. 공개 API를 바꾸는 PR은 본문에 템플릿 쪽 영향(끼운 상태로 돌린 태스크와 결과)을 적는다.
## 4. 이 repo에서 정한 것
- 결정 기록은 `docs/adr/`에 쌓는다. 템플릿에서 옮겨 온 ADR-GRPC-001~006·ADV-001은 번호를 그대로 둔다. 새 결정은 `docs/adr/0000-template.md` 양식으로 `ADR-GRPC-007`부터 쓴다.
- 문서는 한국어로 쓴다. 지난 결정을 고칠 때는 본문이 아니라 머리 블록의 「상태」·「현재 정본」만 고친다(`docs/README.md` 2절).
- 커밋·PR 규칙은 design-docs `conventions/commit-and-pr.md`다. `main`에는 PR로 넣는다(첫 커밋들만 예외였다).
+30
View File
@@ -0,0 +1,30 @@
# 게이트 — 무엇을 언제 돌리나
단계 태스크는 루트 `build.gradle`이 정한다. workflow는 단계마다 Gradle 한 줄이고, 어떤 모듈·lane·검사가 들어가는지는 workflow가 아니라 Gradle이 정한다.
## 1. 단계
| 단계 | 언제 | 명령(`scripts/verify.sh`) | 들어 있는 것 |
| --- | --- | --- | --- |
| `ci` | PR(`pr.yml`) | `pr` | 모듈 `check` 전부(단위 시험, Spotless, Checkstyle, Error Prone, strict lane), SpotBugs(main·test), lockfile, `architectureCheck`, `bufLint`·`bufBreaking`, build-logic 시험. 그리고 `verifyStrictLaneStages --dry-run` |
| `mainCheck` | main push·매일 03:00 KST(`main.yml`) | `main` | `ci` + `integrationCheck`(Testcontainers PostgreSQL) + `performanceCheck` |
| `releaseCheck` | `vX.Y.Z` 태그(`release.yml`) | `release` | 버전 확인, 인증 lane(`testLaneCheck`), `integrationCheck`, SBOM, 의존성 취약점 검사 |
| `release` | `vX.Y.Z` 태그 | — | `releaseCheck` 뒤 Gitea Packages에 서명해 올리고 익명으로 다시 읽는다 |
| `releaseRehearsal` | 손으로 | `release` | `releaseCheck` 뒤 `build/staging-repository`에 올리고 파일마다 확인. 비밀 값 없이 돈다 |
## 2. 바꾼 것에 맞는 게이트
| 바꾼 것 | 최소로 돌릴 것 |
| --- | --- |
| 모듈 하나의 코드 | `./gradlew <gradle path>:check`(path는 registry), 끝나기 전에 `scripts/verify.sh pr` |
| `grpc-operation-ledger-jpa`, migration | 위 + `./gradlew integrationCheck`(Docker) |
| 성능에 닿는 코드(`grpc-testkit` 성능 lane이 보는 곳) | 위 + `./gradlew performanceCheck` |
| `.proto`, `buf.yaml` | `./gradlew :grpc:grpc-contract:check :grpc:grpc-contract:bufLint :grpc:grpc-contract:bufBreaking` |
| `build.gradle`, `build-logic/`, registry, workflow | `scripts/verify.sh pr`(lane 단계 검사가 workflow를 읽는다) |
| 의존성 버전, lockfile | `./gradlew resolveAndLockAll --write-locks` 후 `scripts/verify.sh pr`, 릴리스 전이면 `scripts/verify.sh release` |
## 3. 증거로 남길 때
- 게이트, rc, 실행 직전 부하(`uptime`), 로그 경로, 대상 트리(커밋 또는 `git write-tree`), 캐시를 썼는지를 적는다.
- 증거로 쓰는 실행은 `--rerun-tasks`로 캐시 결과를 쓰지 않는다. 테스트 수는 `build/test-results/**.xml`에서 센다.
- `bufBreaking`의 기준은 PR이면 대상 브랜치와의 merge base, main이면 직전 커밋이다. 로컬에서 다른 기준을 쓰려면 `BUF_AGAINST=<ref>`.
+75
View File
@@ -0,0 +1,75 @@
# 릴리스 — 태그에서 Gitea Packages까지
이 문서는 grpc-library 버전을 내는 절차다. 버전을 내는 사람(소유자)과 릴리스를 준비하는 에이전트가 읽는다.
```text
main 병합 ──> 소유자가 태그 vX.Y.Z push ──> .gitea/workflows/release.yml (desktop-runner)
└─ ./gradlew releaseCheck release
1. 태그 형식·버전 확인 (verifyReleaseVersion)
2. 인증 lane + integration lane (testLaneCheck, integrationCheck)
3. SBOM 만들기 (releaseSbom, Trivy CycloneDX)
4. 의존성 취약점 검사 (HIGH·CRITICAL, KEV) — 여기까지 실패하면 아무것도 안 올라간다
5. 모든 모듈 + SBOM 서명해서 올리기 (publish…ToGiteaRepository)
6. 익명으로 maven-metadata.xml을 읽어 새 버전 확인
```
## 1. 비밀 값 — 소유자가 둔다
에이전트는 토큰·키를 만들거나 secret에 넣지 않는다. 소유자가 2026-11-08에 repo secret 셋을 등록했다.
| secret | 무엇 | 바꿀 때 |
| --- | --- | --- |
| `PACKAGE_TOKEN` | Gitea 개인 토큰. 권한은 `package` 읽기·쓰기만(repository·user 권한 없음). Gitea job 토큰(`GITEA_TOKEN`)은 패키지를 올릴 수 없어서 사람 토큰이 필요하다 | Gitea 웹 → 설정 → 애플리케이션에서 새로 만들어 secret을 덮어쓰고 옛 토큰을 지운다 |
| `SIGNING_KEY` | 서명용 PGP 비밀 키(ASCII armor 전체). 두 라이브러리(grpc, messaging)가 같은 키를 쓴다 | 새 키 쌍을 만들고 README 「서명」의 공개 키와 지문을 같은 PR에서 바꾼다. 만료(2028-11-07) 전에 한다 |
| `SIGNING_PASSWORD` | 그 키의 암호 | 키와 함께 |
- 이름: 설계(design-docs `repo-structure/05-library-repos.md` 7절)는 `PACKAGES_TOKEN`이라고 적었지만, 등록된 이름 `PACKAGE_TOKEN`에 workflow와 빌드를 맞췄다. 소유자에게 다시 등록을 부탁하지 않는다.
- 서명 키: RSA 4096, 지문 `92646CEAFE816CF8B9C249F0A1C936D7F791F8AB`, 2028-11-07 만료. 공개 키는 README 「서명」이다.
- 첫 태그는 `v1.0.0`이다(3절).
## 2. 버전 규칙
- SemVer, repo 하나에 버전 하나. 모든 모듈이 같은 버전으로 나간다. 태그는 `vMAJOR.MINOR.PATCH`이고 접미사(`-rc.1` 등)는 없다. 다른 모양의 태그는 `ca.java-conventions`가 빌드 전에 거부한다.
- 공개 타입·proto의 삭제·시그니처 변경, 설정 키(`app.grpc.platform.*`) 바꾸기는 MAJOR다. 커밋 제목에 `!`, 본문에 `BREAKING CHANGE:`, `CHANGELOG.md` 그 버전 절에 옮기는 법을 쓴다.
- 기능 추가는 MINOR, 고치기는 PATCH다.
- SNAPSHOT은 내지 않는다. Gitea는 같은 버전을 다시 받지 않는다. 개발 중 연결은 composite build로 한다(`docs/work/README.md` 3절).
- **배포한 버전은 지우지 않는다.** 잘못 나갔거나 일부만 올라갔으면 그 버전은 버리고 다음 PATCH를 낸다. Gitea는 owner의 삭제를 막지 않으므로 이것은 규칙으로 지킨다.
## 3. 버전 내기
1. main이 초록인지 본다(main.yml 마지막 실행).
2. `CHANGELOG.md`에 그 버전 절을 쓰고 PR로 병합한다.
3. 올리기 전까지를 desktop에서 미리 돌려 본다(비밀 값 없이, 4절).
4. 태그를 단다.
```bash
git tag -a v1.0.0 -m "grpc-library 1.0.0"
```
```bash
git push origin v1.0.0
```
5. release.yml 실행이 초록인지 Gitea Actions 화면에서 본다. 마지막 줄들에 모듈마다 `published: com.hyeonworks.grpc:<모듈>:<버전>`이 찍힌다.
6. 템플릿이 이 라이브러리를 쓰게 되면(지금은 쓰지 않는다) 템플릿 PR로 카탈로그 버전을 올린다. 절차는 템플릿 `docs/work/reference/related-repos.md`다.
## 4. 올리기 직전까지 미리 돌리기
```bash
scripts/verify.sh release --on desktop
```
`releaseRehearsal`이 `releaseCheck`를 돌고, 모든 모듈과 SBOM을 `build/staging-repository`에 올린 뒤 파일마다 확인한다(jar·sources·javadoc·POM·module 파일, 체크섬 넷, POM·module의 모든 의존성에 버전이 있는지). `SIGNING_KEY`가 환경에 있으면 `.asc`도 확인한다. 버전은 `RELEASE_VERSION`이 없으면 `0.0.0`이다.
## 5. 실패했을 때
| 어디서 | 뜻 | 할 일 |
| --- | --- | --- |
| 1~4단계 | 아무것도 올라가지 않았다 | 고쳐서 main에 병합하고 같은 태그 이름을 새 커밋에 다시 달지 않는다. 다음 PATCH 태그를 쓴다 |
| 5단계 중간 | 일부 모듈만 올라갔을 수 있다 | 그 버전은 버린다(지우지 않는다). 원인을 고치고 다음 PATCH를 낸다. `CHANGELOG.md`에 버린 버전을 적는다 |
| 6단계 | 올라갔지만 익명으로 안 읽힌다 | owner 공개 설정을 확인한다. 템플릿 이미지 빌드가 토큰 없이 읽는다는 전제(설계 8.3절 R1)가 깨진 것이다 |
## 6. 취약점 정책
- Trivy(버전·SHA-256은 `scripts/tool.sh`)가 커밋된 lockfile을 본다. HIGH·CRITICAL은 막고, MEDIUM·LOW는 보고만 하고, CISA KEV 목록에 있으면 등급과 상관없이 막는다. KEV 목록을 못 받으면 막는다.
- 예외는 `.trivyignore.yaml` 한 곳에만 둔다. 항목마다 이유(`statement`)와 90일 안의 만료(`expired_at`)를 적고 PR로 넣는다.
+2 -2
View File
@@ -1,7 +1,7 @@
# grpc-advanced — 고급 gRPC capability의 지역 정본
이 문서는 `grpc-advanced:*` family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은
`src/config/architecture/modules.json`이 SSOT다. 루트 `AGENTS.md`와 충돌하면
`config/architecture/modules.json`이 SSOT다. 루트 `AGENTS.md`와 충돌하면
루트가 이긴다.
이 family는 Stable gRPC 플랫폼(`grpc:*`)이 **의도적으로 제외한** 능력들을 담는다. 별도 디렉터리와
@@ -43,7 +43,7 @@ property key는 `app.grpc.advanced.<capability>.enabled`이고 전부 기본 off
## Leaf별 담당 capability
| leaf | 패키지(`dev.caskeleton.grpc.advanced.*`) | capability |
| leaf | 패키지(`com.hyeonworks.grpc.advanced.*`) | capability |
| --- | --- | --- |
| `grpc-advanced` | `bootstrap` | capability grade, feature flag, module guard, capability별 promotion gate |
| `grpc-advanced` | `edition` | Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane |
+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에
+20 -16
View File
@@ -3,18 +3,20 @@
#
# scripts/verify.sh <단계> [--on here|<호스트>] [--log <이름>]
#
# 단계 무엇 채우는 곳
# docs 루트 지침·장부 검사 run_docs(뼈대에 기본 검사가 있다)
# unit 빠른 단위 시험 run_unit
# pr PR 전에 통과해야 하는 게이트 묶음 run_pr
# app 앱을 띄워 health와 기본 기능을 직접 확인 run_app
# 단계 무엇 Gradle
# docs 루트 지침·장부 검사 (없음)
# unit 모듈 check 전부(단위 시험·정적 분석·lane 포함) checkAll
# pr PR 단계 = pr.yml ci, verifyStrictLaneStages --dry-run
# main main 단계 = main.yml(Docker 필요) mainCheck
# release release.yml에서 올리기 직전까지(Docker 필요, 비밀 값 없이) releaseRehearsal
# 라이브러리라 띄울 앱이 없다. 템플릿 뼈대의 `app` 단계는 두지 않는다.
#
# --on <호스트>: 지금 작업 트리(커밋 안 된 변경 포함)를 패치로 그 호스트에 옮긴다. 기준 커밋에서 새 worktree를
# 만들어 패치를 적용하고, 트리 해시가 여기와 같은지 본 뒤 잠금 아래에서 같은 단계를 돌리고 worktree를 지운다.
# push하지 않는다. 기준 커밋은 원격 checkout이 fetch로 받을 수 있어야 한다(기본: origin/main과 갈라진 곳).
# 환경 변수: VERIFY_HOST(--on 기본값, 없으면 here), VERIFY_REMOTE_REPO(원격 checkout, 기본 ~/workspace/<repo 이름>),
# VERIFY_BASE_REF(기본 origin/main), VERIFY_LOCK(기본 /tmp/claude-gates/heavy.lock), VERIFY_SSH(기본 ssh).
# 종료 코드: 단계의 종료 코드. 2 = 사용법, 3 = 아직 채우지 않은 단계, 4 = 원격 준비 실패.
# 종료 코드: 단계의 종료 코드. 2 = 사용법, 4 = 원격 준비 실패.
set -euo pipefail
ROOT=$(git rev-parse --show-toplevel)
@@ -23,15 +25,10 @@ TMP_FILES=()
trap '[ ${#TMP_FILES[@]} -eq 0 ] || rm -f "${TMP_FILES[@]}"' EXIT # 빈 배열 + set -u는 옛 bash에서 오류다
usage() {
sed -n '2,19p' "$0" | sed 's/^# \{0,1\}//' >&2
sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//' >&2
exit 2
}
todo() {
echo "verify: '$1' 단계는 아직 정하지 않았다. scripts/verify.sh의 run_$1을 채운다." >&2
return 3
}
# ---------------------------------------------------------------- 단계 본문(프로젝트가 채운다)
run_docs() {
@@ -56,17 +53,24 @@ for n, line in enumerate(open(sys.argv[1], encoding="utf-8"), 1):
return "$rc"
}
run_unit() { todo unit; }
run_unit() { ./gradlew checkAll --console=plain; }
run_pr() { run_docs && run_unit && todo pr; }
run_pr() { run_docs && ./gradlew ci --console=plain && ./gradlew verifyStrictLaneStages --dry-run --console=plain; }
run_app() { todo app; }
run_main() { ./gradlew mainCheck --console=plain; }
# releaseCheck needs a release version and a commit id. The rehearsal uses 0.0.0 unless
# RELEASE_VERSION is given: a version no release tag (v1.0.0 onward) will ever name.
run_release() {
RELEASE_VERSION=${RELEASE_VERSION:-0.0.0} GIT_SHA=${GIT_SHA:-$(git rev-parse HEAD)} \
./gradlew releaseRehearsal --console=plain
}
# ---------------------------------------------------------------- 실행 위치
run_here() {
case "$1" in
docs | unit | pr | app) "run_$1" ;;
docs | unit | pr | main | release) "run_$1" ;;
*) usage ;;
esac
}