Merge pull request 'docs: 별도 repo 라이브러리로서의 지침·작업 문서·릴리스 절차를 쓴다' (#1) from docs/library-guides into main
main / main-check (push) Successful in 5m30s
main / main-check (push) Successful in 5m30s
This commit was merged in pull request #1.
This commit is contained in:
@@ -4,7 +4,7 @@
|
|||||||
# anonymously). Publishing starts only after releaseCheck has passed, so a red check leaves nothing
|
# anonymously). Publishing starts only after releaseCheck has passed, so a red check leaves nothing
|
||||||
# half-published (Gitea refuses a second upload of a version).
|
# 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
|
# package read/write only (the job token cannot publish packages); SIGNING_KEY, an ASCII-armoured PGP
|
||||||
# secret key; SIGNING_PASSWORD, its passphrase.
|
# secret key; SIGNING_PASSWORD, its passphrase.
|
||||||
name: release
|
name: release
|
||||||
@@ -36,7 +36,7 @@ jobs:
|
|||||||
- run: ./gradlew releaseCheck release --stacktrace
|
- run: ./gradlew releaseCheck release --stacktrace
|
||||||
env:
|
env:
|
||||||
RELEASE_TAG: ${{ github.ref_name }}
|
RELEASE_TAG: ${{ github.ref_name }}
|
||||||
PACKAGES_TOKEN: ${{ secrets.PACKAGES_TOKEN }}
|
PACKAGE_TOKEN: ${{ secrets.PACKAGE_TOKEN }}
|
||||||
SIGNING_KEY: ${{ secrets.SIGNING_KEY }}
|
SIGNING_KEY: ${{ secrets.SIGNING_KEY }}
|
||||||
SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }}
|
SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }}
|
||||||
TESTCONTAINERS_REUSE_ENABLE: "false"
|
TESTCONTAINERS_REUSE_ENABLE: "false"
|
||||||
|
|||||||
@@ -1,36 +1,38 @@
|
|||||||
# AGENTS.md — grpc-library의 정본
|
# 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. 관련 검증(아래 「검증」) 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.
|
1. 관련 검증(아래 「검증」) 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.
|
||||||
2. 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 명령을 한다.
|
2. 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 명령을 한다.
|
||||||
3. 비밀 값(`.env`, 키, 토큰)을 읽거나 커밋한다.
|
3. 비밀 값(`.env`, 키, 토큰)을 읽거나 커밋한다. 배포 토큰·서명 키는 repo secret에만 있다.
|
||||||
4. (채울 것: 이 프로젝트의 아키텍처 불변식. 예: 도메인 계층이 프레임워크·DB를 import한다)
|
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절)을 따르지 않는다.
|
||||||
|
|
||||||
## 지도
|
## 지도
|
||||||
|
|
||||||
- (채울 것: 최상위 폴더 → 하는 일. 개수·버전 숫자는 적지 않는다. 정본이 따로 있으면 그 파일을 가리킨다)
|
- `grpc/`(Stable)·`grpc-advanced/`(capability flag 뒤): 모듈. 모듈 목록·경로·허용 의존의 정본은 registry `config/architecture/modules.json`이다. 개수는 적지 않는다.
|
||||||
- 폴더마다의 규칙은 그 폴더의 `AGENTS.md`다. 작업 파일과 가장 가까운 것을 따른다.
|
- `build-logic/`: 템플릿에서 복사해 줄인 convention 플러그인. 어디서 복사했고 무엇을 고쳤는지는 `build-logic/UPSTREAM.md`.
|
||||||
- 결정 기록은 `docs/adr/`(양식 `0000-template.md`), 예측·실측 장부는 `docs/ledger/`다.
|
- `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의 범위·크기·완료 기준이 먼저다.
|
- brief가 있으면 brief의 범위·크기·완료 기준이 먼저다.
|
||||||
|
|
||||||
## 검증
|
## 검증
|
||||||
|
|
||||||
- 진입점은 하나다: `scripts/verify.sh <단계>`(docs · unit · pr · app). 사람·CI·에이전트가 같은 명령을 쓴다.
|
- 진입점: `scripts/verify.sh <단계>`(docs · unit · pr · main · release). 사람·CI·에이전트가 같은 명령을 쓴다.
|
||||||
- 무거운 실행을 다른 기계에서 돌릴 때는 `scripts/verify.sh <단계> --on <호스트>`(지금 작업 트리를 패치로 옮긴다).
|
- Gradle·Docker는 소유자 환경에서 desktop에서만 돈다: `scripts/verify.sh pr --on desktop`.
|
||||||
|
|
||||||
## 헷갈리는 곳
|
|
||||||
|
|
||||||
- (채울 것: 코드만 보고는 알 수 없는 것. 없으면 이 절을 지운다)
|
|
||||||
|
|
||||||
## 일하는 방식
|
## 일하는 방식
|
||||||
|
|
||||||
- 착수할 때 예측을, 끝날 때 실측을 장부에 남긴다(Claude Code는 `estimate` 스킬).
|
- 착수할 때 예측을, 끝날 때 실측을 `docs/ledger/estimates.jsonl`에 남긴다(Claude Code는 `estimate` 스킬).
|
||||||
- 파일을 바꾸는 위임은 사람이 열어 보고 멈출 수 있는 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다.
|
- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일은 서브에이전트에 맡긴다.
|
||||||
- 커밋 메시지·PR 규칙: (채울 것: 규칙 문서 경로)
|
- 커밋·PR 규칙: design-docs `conventions/commit-and-pr.md`(PR 본문 칸은 `.gitea/pull_request_template.md`).
|
||||||
|
|||||||
@@ -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`는 그대로다.
|
||||||
@@ -3,5 +3,15 @@
|
|||||||
## Claude Code에서만
|
## Claude Code에서만
|
||||||
|
|
||||||
- 권한은 `.claude/settings.json`이다: 실제 `.env` 읽기·쓰기를 막는다(`.env.example` 같은 예시는 막지 않는다).
|
- 권한은 `.claude/settings.json`이다: 실제 `.env` 읽기·쓰기를 막는다(`.env.example` 같은 예시는 막지 않는다).
|
||||||
- 공통 훅과 스킬은 하네스 플러그인 `harness@claude-harness`가 준다: 되돌릴 수 없는 명령 차단, 비밀 값 알림, 예측·실측 장부 기록, `estimate`·`retro`·`techdebt`. 플러그인 설명은 claude-harness repo의 README다.
|
- 공통 훅과 스킬은 하네스 플러그인 `harness@claude-harness`가 준다: 되돌릴 수 없는 명령 차단, 비밀 값 알림, 예측·실측 장부 기록, `estimate`·`retro`·`techdebt`. 대화형 Claude Code는 이 폴더를 처음 믿을 때 설치를 묻는다. 비대화형(`claude -p`)은 묻지도 설치하지도 않으니 이 폴더에서 한 번 돌린다(설정 파일은 이미 맞다).
|
||||||
- 이 프로젝트만의 훅은 `scripts/hooks/`, 경로별 규칙은 `.claude/rules/`, 스킬은 `.claude/skills/`, 서브에이전트는 `.claude/agents/`에 둔다.
|
|
||||||
|
```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` 아래).
|
||||||
|
|||||||
@@ -1,13 +1,112 @@
|
|||||||
# optional gRPC 플랫폼
|
# grpc-library
|
||||||
|
|
||||||
기본 애플리케이션은 `grpc/*`나 `grpc-advanced/*`에 의존하지 않는다. 그래서 이 프로젝트들(registry에서
|
Spring Boot 앱에 gRPC 서버·클라이언트를 붙이는 플랫폼 라이브러리다. 타입 있는 서비스 adapter, method 정책(deadline·멱등성·크기 한도), 실행 증거와 실패 모델, durable operation 원장, 관측 규칙, 인증 lane(in-process·실제 Netty·fault·performance)을 준다.
|
||||||
`"build": "optional-grpc"`인 항목)은 주 멀티 프로젝트 빌드에서 뺀다. 이 빌드는 그 프로젝트들의 원래
|
|
||||||
프로젝트 경로와 내부 프로젝트 의존을 그대로 두면서, 그 설정을 고를 때만 켜지게 한다.
|
|
||||||
|
|
||||||
```bash
|
```text
|
||||||
./gradlew -p platforms/optional-build ci
|
앱 소유 port ──> 앱의 inbound adapter ──> grpc-spring-boot-starter (조립)
|
||||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest
|
├─ 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).
|
||||||
|
|||||||
@@ -25,6 +25,7 @@
|
|||||||
| `java/JavaConventionsPlugin` | `group`을 `gradle.properties`의 `libraryGroup`에서 읽는다(템플릿은 `dev.caskeleton` 고정). 버전은 `RELEASE_TAG`/`-PreleaseTag`(`vX.Y.Z`)에서도 읽는다. 이미지 목록·도구 설정은 루트의 `config/`만 본다 |
|
| `java/JavaConventionsPlugin` | `group`을 `gradle.properties`의 `libraryGroup`에서 읽는다(템플릿은 `dev.caskeleton` 고정). 버전은 `RELEASE_TAG`/`-PreleaseTag`(`vX.Y.Z`)에서도 읽는다. 이미지 목록·도구 설정은 루트의 `config/`만 본다 |
|
||||||
| `quality/QualityConventionsPlugin` | 도구 설정은 루트의 `config/`만 본다 |
|
| `quality/QualityConventionsPlugin` | 도구 설정은 루트의 `config/`만 본다 |
|
||||||
| `convention/PlatformModuleConventionPlugin` | `ca.library-publishing`을 함께 켠다 |
|
| `convention/PlatformModuleConventionPlugin` | `ca.library-publishing`을 함께 켠다 |
|
||||||
|
| `ModuleRegistry` | registry 행의 `build` 칸을 거절한다. main이 아닌 값(오타 포함)이면 그 모듈이 조용히 빌드에서 빠졌다. 템플릿 `91804ec1` 뒤 브랜치 `claude/x2-grpc-library-43dd09`에 같은 수정이 있다 |
|
||||||
| `strictlane/StrictLaneStagesPlugin` | 단계의 계획을 따라갈 때 included build 태스크(`ci`가 부르는 build-logic `test`)는 묻지 않는다. 템플릿 `ci`에는 그런 의존이 없어 드러나지 않았다. 템플릿에도 옮길 만한 수정이다 |
|
| `strictlane/StrictLaneStagesPlugin` | 단계의 계획을 따라갈 때 included build 태스크(`ci`가 부르는 build-logic `test`)는 묻지 않는다. 템플릿 `ci`에는 그런 의존이 없어 드러나지 않았다. 템플릿에도 옮길 만한 수정이다 |
|
||||||
| 새 `publishing/LibraryPublishingPlugin`(`ca.library-publishing`) | 모듈마다 Maven publication(sources·javadoc jar, 해석된 버전), 저장소 `gitea`·`staging`, `SIGNING_KEY`가 있으면 PGP 서명 |
|
| 새 `publishing/LibraryPublishingPlugin`(`ca.library-publishing`) | 모듈마다 Maven publication(sources·javadoc jar, 해석된 버전), 저장소 `gitea`·`staging`, `SIGNING_KEY`가 있으면 PGP 서명 |
|
||||||
| 테스트 fixture | `source_path`를 Gradle 루트 기준으로, `PlatformModuleConventionTest`에 `libraryGroup` |
|
| 테스트 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 id = requireNonBlankText(module, "id", index);
|
||||||
String gradlePath = requireNonBlankText(module, "gradle_path", index);
|
String gradlePath = requireNonBlankText(module, "gradle_path", index);
|
||||||
String sourcePath = requireNonBlankText(module, "source_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 =
|
List<String> allowedDependencies =
|
||||||
requireStringList(module.get("allowed_dependencies"), id, "allowed_dependencies");
|
requireStringList(module.get("allowed_dependencies"), id, "allowed_dependencies");
|
||||||
|
|
||||||
|
|||||||
+3
-3
@@ -23,7 +23,7 @@ import org.gradle.plugins.signing.SigningExtension;
|
|||||||
*
|
*
|
||||||
* <ul>
|
* <ul>
|
||||||
* <li>{@code gitea}: {@code packagesUrl} from gradle.properties, authenticated with the {@code
|
* <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
|
* 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.
|
* from the environment and never written to a file.
|
||||||
* <li>{@code staging}: {@code build/staging-repository} under the root project. {@code
|
* <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> packagesUrl = project.getProviders().gradleProperty("packagesUrl");
|
||||||
Provider<String> repositoryUrl = project.getProviders().gradleProperty("repositoryUrl");
|
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);
|
PublishingExtension publishing = project.getExtensions().getByType(PublishingExtension.class);
|
||||||
MavenPublication publication =
|
MavenPublication publication =
|
||||||
@@ -166,7 +166,7 @@ public final class LibraryPublishingPlugin implements Plugin<Project> {
|
|||||||
}
|
}
|
||||||
if (token.getOrElse("").isBlank()) {
|
if (token.getOrElse("").isBlank()) {
|
||||||
throw new GradleException(
|
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
|
@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"));
|
Files.createDirectories(root.resolve("src/grpc/grpc-client"));
|
||||||
String json =
|
String json =
|
||||||
registry(
|
registry(
|
||||||
@@ -96,15 +106,13 @@ class ModuleRegistryTest {
|
|||||||
{"id":"grpc-client","gradle_path":":grpc:grpc-client","source_path":"src/grpc/grpc-client",
|
{"id":"grpc-client","gradle_path":":grpc:grpc-client","source_path":"src/grpc/grpc-client",
|
||||||
"allowed_dependencies":[],"build":"optional-grpc"}
|
"allowed_dependencies":[],"build":"optional-grpc"}
|
||||||
""");
|
""");
|
||||||
ModuleRegistry parsed = read(json);
|
IllegalStateException failure = assertThrows(IllegalStateException.class, () -> read(json));
|
||||||
assertEquals("main", parsed.byId("app-bootstrap").buildName());
|
assertTrue(failure.getMessage().contains("'grpc-client'"), failure.getMessage());
|
||||||
assertEquals("optional-grpc", parsed.byId("grpc-client").buildName());
|
assertTrue(failure.getMessage().contains("'build'"), failure.getMessage());
|
||||||
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());
|
|
||||||
}
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
void blankBuildOwnershipIsRefused() {
|
void aBlankBuildFieldIsRefusedToo() {
|
||||||
String json =
|
String json =
|
||||||
"""
|
"""
|
||||||
{"modules":[
|
{"modules":[
|
||||||
@@ -112,7 +120,7 @@ class ModuleRegistryTest {
|
|||||||
"allowed_dependencies":[],"build":" "}]}
|
"allowed_dependencies":[],"build":" "}]}
|
||||||
""";
|
""";
|
||||||
IllegalStateException failure = assertThrows(IllegalStateException.class, () -> read(json));
|
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
|
@Test
|
||||||
|
|||||||
+3
-3
@@ -177,7 +177,7 @@ publishing {
|
|||||||
url = providers.gradleProperty('packagesUrl')
|
url = providers.gradleProperty('packagesUrl')
|
||||||
credentials(HttpHeaderCredentials) {
|
credentials(HttpHeaderCredentials) {
|
||||||
name = 'Authorization'
|
name = 'Authorization'
|
||||||
value = "token ${providers.environmentVariable('PACKAGES_TOKEN').getOrElse('')}"
|
value = "token ${providers.environmentVariable('PACKAGE_TOKEN').getOrElse('')}"
|
||||||
}
|
}
|
||||||
authentication {
|
authentication {
|
||||||
header(HttpHeaderAuthentication)
|
header(HttpHeaderAuthentication)
|
||||||
@@ -202,13 +202,13 @@ tasks.withType(PublishToMavenRepository).configureEach {
|
|||||||
mustRunAfter tasks.named('releaseCheck')
|
mustRunAfter tasks.named('releaseCheck')
|
||||||
if (name.endsWith('ToGiteaRepository')) {
|
if (name.endsWith('ToGiteaRepository')) {
|
||||||
def signed = !signingKey.isBlank()
|
def signed = !signingKey.isBlank()
|
||||||
def token = providers.environmentVariable('PACKAGES_TOKEN').getOrElse('')
|
def token = providers.environmentVariable('PACKAGE_TOKEN').getOrElse('')
|
||||||
doFirst {
|
doFirst {
|
||||||
if (!signed) {
|
if (!signed) {
|
||||||
throw new GradleException('SIGNING_KEY is not set; refusing to publish unsigned files to Gitea.')
|
throw new GradleException('SIGNING_KEY is not set; refusing to publish unsigned files to Gitea.')
|
||||||
}
|
}
|
||||||
if (token.isBlank()) {
|
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.')
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -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/…`)는 그 결정 때의 템플릿 경로다.
|
||||||
@@ -3,8 +3,8 @@
|
|||||||
Stable gRPC 플랫폼(`:grpc:*`)이 무엇에 대해 인증됐고, 무엇에 대해서는 확인만 하고, 무엇은 지켜보기만 하는지다. 그 구별이
|
Stable gRPC 플랫폼(`:grpc:*`)이 무엇에 대해 인증됐고, 무엇에 대해서는 확인만 하고, 무엇은 지켜보기만 하는지다. 그 구별이
|
||||||
요점이다. 「Spring Boot와 동작한다」는 누구도 행동에 옮길 수 없는 말이다.
|
요점이다. 「Spring Boot와 동작한다」는 누구도 행동에 옮길 수 없는 말이다.
|
||||||
|
|
||||||
릴리스 gate는 `.github/workflows/release.yml`의 `grpc-stable-release-gate` job이다. 인증된 lane마다 아무것도 돌리지 않으면
|
릴리스 gate는 `.gitea/workflows/release.yml`이 돌리는 Gradle 단계 `releaseCheck`다(`docs/work/release.md`). 인증된 lane마다
|
||||||
실패하는 strict test lane이다.
|
아무것도 돌리지 않으면 실패하는 strict test lane이다.
|
||||||
|
|
||||||
> 이력: 코드 안의 `GrpcCompatibilityMatrix`/`GrpcStableReleaseGate` 짝은 지웠다(리뷰 2026-09-24 S5-lead-4). 운영 코드도 빌드
|
> 이력: 코드 안의 `GrpcCompatibilityMatrix`/`GrpcStableReleaseGate` 짝은 지웠다(리뷰 2026-09-24 S5-lead-4). 운영 코드도 빌드
|
||||||
> 코드도 그것을 부르지 않아서 아무것도 막지 않았다.
|
> 코드도 그것을 부르지 않아서 아무것도 막지 않았다.
|
||||||
@@ -26,9 +26,9 @@ Stable gRPC 플랫폼(`:grpc:*`)이 무엇에 대해 인증됐고, 무엇에 대
|
|||||||
| | |
|
| | |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| Java | 21 |
|
| Java | 21 |
|
||||||
| Spring Boot | 저장소 기준선, `src/gradle/libs.versions.toml`(계획은 4.1을 가정한다) |
|
| Spring Boot | `gradle/libs.versions.toml`의 `springBoot`(이 줄로 컴파일하고 시험한다. 버전별 표는 README 「지원 표」) |
|
||||||
| io.grpc | `src/gradle/libs.versions.toml`의 `grpc`. `GrpcPlatformModuleConventionPlugin`이 그 BOM을 모듈 범위로 import한다 |
|
| io.grpc | `gradle/libs.versions.toml`의 `grpc`. `GrpcPlatformModuleConventionPlugin`이 그 BOM을 모듈 범위로 import한다 |
|
||||||
| Protobuf | `src/gradle/libs.versions.toml`의 protobuf 항목(어느 leaf가 어느 것을 쓰는지는 그 파일의 주석이 적는다) |
|
| Protobuf | `gradle/libs.versions.toml`의 `protobufGrpc`(생성 코드 runtime과 protoc가 같은 줄) |
|
||||||
| Stable 전송 | Netty(shaded) |
|
| Stable 전송 | Netty(shaded) |
|
||||||
| Stable RPC 모양 | Unary, Server Streaming |
|
| Stable RPC 모양 | Unary, Server Streaming |
|
||||||
| Stable resolver | Static, DNS, Unix domain socket |
|
| Stable resolver | Static, DNS, Unix domain socket |
|
||||||
@@ -63,8 +63,8 @@ in-process 결과는 절대 전송 증거가 아니다. in-process 전송은 TLS
|
|||||||
|
|
||||||
## 지금 릴리스 상태
|
## 지금 릴리스 상태
|
||||||
|
|
||||||
릴리스하지 않았다. registry에서 모든 `:grpc:*` leaf는 `"build": "optional-grpc"`라 주 빌드 밖에 있고 어느 조립에도 들어가지
|
Gitea Packages에 아직 버전을 내지 않았다(첫 버전은 `v1.0.0`, `docs/work/release.md`). 이 라이브러리를 조립하는 앱도
|
||||||
않는다. 플랫폼은 빌드만 된다. 컴파일되고 lane이 돌지만, 배포되는 산출물 어디에도 실리지 않는다.
|
아직 없다. 플랫폼은 빌드만 된다. 컴파일되고 lane이 돌지만, 배포되는 앱 어디에도 실리지 않는다.
|
||||||
|
|
||||||
릴리스 gate 입력 둘이 남아 있고, 그것이 지금부터 릴리스까지의 일이다.
|
릴리스 gate 입력 둘이 남아 있고, 그것이 지금부터 릴리스까지의 일이다.
|
||||||
|
|
||||||
|
|||||||
@@ -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절.
|
||||||
|
|||||||
@@ -47,7 +47,7 @@ xDS가 켜진 동안 애플리케이션 수준의 재시도 정책을 **더하
|
|||||||
**거의 언제나 proxy다.** gRPC 상태는 trailer로 오고, 브라우저는 proxy가 노출하지 않은 trailer를 읽지 못한다.
|
**거의 언제나 proxy다.** gRPC 상태는 trailer로 오고, 브라우저는 proxy가 노출하지 않은 trailer를 읽지 못한다.
|
||||||
proxy의 CORS `expose_headers`에 `grpc-status`와 `grpc-message`가 있는지 확인한다.
|
proxy의 CORS `expose_headers`에 `grpc-status`와 `grpc-message`가 있는지 확인한다.
|
||||||
`GrpcWebProxyContract.violations`가 정확히 이것을 보고하고, 참조 설정
|
`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으로는 아예 되지 않는다. 브라우저는
|
**메서드가 client streaming이나 bidirectional streaming이면** gRPC-Web으로는 아예 되지 않는다. 브라우저는
|
||||||
메시지 stream을 보낼 방법이 없다. `GrpcWebRpcSupport.require`가 그런 메서드를 거부한다.
|
메시지 stream을 보낼 방법이 없다. `GrpcWebRpcSupport.require`가 그런 메서드를 거부한다.
|
||||||
|
|||||||
@@ -1,7 +1,7 @@
|
|||||||
# Runbook: gRPC platform operations
|
# Runbook: gRPC platform operations
|
||||||
|
|
||||||
범위: `:grpc:*` family. 지금은 모두 빌드만 된다. registry에서 이 family의 leaf는 모두 `"build": "optional-grpc"`
|
범위: `:grpc:*` family. 지금은 모두 빌드만 된다. 이 라이브러리를 실제로 쓰는 앱은 아직 없다(백엔드 템플릿의
|
||||||
(주 빌드 밖, `-p platforms/optional-build`로 돈다)이고 어느 조립에도 들어가지 않으므로, 여기 있는 것은 아직 운영에서
|
`adapter:inbound:grpc`도 이 라이브러리가 아니라 `io.grpc`를 직접 쓴다). 그래서 여기 있는 것은 아직 운영에서
|
||||||
일어나지 않는다. 그래도 지금 쓰는 이유가 있다. 여기서 다루는 상태는 당번이 새벽 세 시에 처음부터 따져서는 알아낼
|
일어나지 않는다. 그래도 지금 쓰는 이유가 있다. 여기서 다루는 상태는 당번이 새벽 세 시에 처음부터 따져서는 알아낼
|
||||||
수 없는 것들이고, runbook보다 동작을 먼저 내보내면 그것을 처음 만난 사람이 그 따지기를 하게 된다.
|
수 없는 것들이고, runbook보다 동작을 먼저 내보내면 그것을 처음 만난 사람이 그 따지기를 하게 된다.
|
||||||
|
|
||||||
@@ -156,5 +156,5 @@ snapshot에는 해시와 이름만 실린다. 자격 증명처럼 보이는 이
|
|||||||
- **운영의 reflection.** `GrpcReflectionMode.defaultFor`는 `STAGE`와 `PROD`에 `DISABLED`를 돌려준다. reflection은
|
- **운영의 reflection.** `GrpcReflectionMode.defaultFor`는 `STAGE`와 `PROD`에 `DISABLED`를 돌려준다. reflection은
|
||||||
연결을 열 수 있는 누구에게나 스키마 전체를 공개한다.
|
연결을 열 수 있는 누구에게나 스키마 전체를 공개한다.
|
||||||
- **모든 advanced capability.** `docs/runbooks/grpc-advanced-capabilities.md`를 본다.
|
- **모든 advanced capability.** `docs/runbooks/grpc-advanced-capabilities.md`를 본다.
|
||||||
- **플랫폼 자체.** `app.grpc.platform.enabled`의 기본값은 false이고, registry에서 모든 `:grpc:*` leaf는
|
- **플랫폼 자체.** `app.grpc.platform.enabled`의 기본값은 false이고, 앱이 이 라이브러리를 의존성으로 받지 않으면
|
||||||
`"build": "optional-grpc"`라 기본 조립에 들어가지 않는다.
|
아무것도 조립되지 않는다.
|
||||||
|
|||||||
@@ -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로 넣는다(첫 커밋들만 예외였다).
|
||||||
@@ -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>`.
|
||||||
@@ -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로 넣는다.
|
||||||
@@ -1,7 +1,7 @@
|
|||||||
# grpc-advanced — 고급 gRPC capability의 지역 정본
|
# grpc-advanced — 고급 gRPC capability의 지역 정본
|
||||||
|
|
||||||
이 문서는 `grpc-advanced:*` family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은
|
이 문서는 `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:*`)이 **의도적으로 제외한** 능력들을 담는다. 별도 디렉터리와
|
이 family는 Stable gRPC 플랫폼(`grpc:*`)이 **의도적으로 제외한** 능력들을 담는다. 별도 디렉터리와
|
||||||
@@ -43,7 +43,7 @@ property key는 `app.grpc.advanced.<capability>.enabled`이고 전부 기본 off
|
|||||||
|
|
||||||
## Leaf별 담당 capability
|
## 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` | `bootstrap` | capability grade, feature flag, module guard, capability별 promotion gate |
|
||||||
| `grpc-advanced` | `edition` | Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane |
|
| `grpc-advanced` | `edition` | Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane |
|
||||||
|
|||||||
+32
-33
@@ -1,17 +1,17 @@
|
|||||||
# grpc — gRPC 플랫폼 family의 지역 정본
|
# grpc — gRPC 플랫폼 family의 지역 정본
|
||||||
|
|
||||||
이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 기본 application build와 분리된
|
이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 이 repo(`grpc-library`)가 소유하고
|
||||||
`src/platforms/optional-build` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급,
|
Maven group `com.hyeonworks.grpc`로 배포한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급,
|
||||||
Stable 범위의 경계와 application에 채택될 때 필요한 계약이다.
|
Stable 범위의 경계와 application에 채택될 때 필요한 계약이다.
|
||||||
|
|
||||||
루트 `AGENTS.md`와 충돌하면 루트가 이긴다.
|
루트 `AGENTS.md`와 충돌하면 루트가 이긴다.
|
||||||
|
|
||||||
이 family는 Clean Architecture의 계층이 아니라 **벤더드 RPC 플랫폼**이다 — `messaging:*`와 같은
|
이 family는 앱의 Clean Architecture 계층이 아니라 **RPC 플랫폼 라이브러리**다. 자기 API(port)와 adapter와 조립
|
||||||
자리에 있고 같은 이유로 있다. 자기 API(port)와 adapter와 조립 경계(starter)를 가지며, 애플리케이션은
|
경계(starter)를 가지며, 앱은 자기 inbound adapter(백엔드 템플릿이면 `adapter:inbound:grpc`)를 통해 라이브러리로서
|
||||||
`adapter:inbound:grpc`를 통해 라이브러리로서 도달한다.
|
도달한다. 2026-11-08까지 백엔드 템플릿 안(`src/platforms/grpc`)에 있었고, 그 전 이력도 이 repo에 그대로 있다.
|
||||||
|
|
||||||
설계 근거와 원본 계획 대비 deviation은
|
설계 근거와 원본 계획 대비 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 규칙
|
## Family와 framework 규칙
|
||||||
|
|
||||||
@@ -20,7 +20,7 @@ leaf의 정확한 id는 registry에서 읽는다.
|
|||||||
| Family | 역할 | 허용 framework |
|
| Family | 역할 | 허용 framework |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| `grpc-core-api` | 식별자, method policy, 실행 증거, 실패 모델, deadline, request context, operation ledger port | **Java stdlib만.** io.grpc / Spring / protobuf / DB 타입 금지 |
|
| `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-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-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-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 한도보다 크면
|
그 상수를 쓴다. `GrpcPlatformStartupValidator`는 method의 inbound 한도가 server profile 한도보다 크면
|
||||||
기동을 거부한다.
|
기동을 거부한다.
|
||||||
|
|
||||||
`.proto`의 proto 조직 이름은 `caskeleton`이다(`package caskeleton.grpc.common.v1`, 생성 Java 패키지
|
`.proto`의 proto 조직 이름은 `hyeonworks`다(`package hyeonworks.grpc.common.v1`, 생성 Java 패키지
|
||||||
`caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할
|
`hyeonworks.grpc.common.v1.generated` — 손으로 쓴 `com.hyeonworks`와 겹치지 않는다). proto 패키지는 wire
|
||||||
때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다.
|
이름이라 바꾸면 MAJOR다(`docs/work/release.md` 2절). 2026-11-08 전의 이름은 `caskeleton`이었다.
|
||||||
|
|
||||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유
|
### 공용 다이제스트 헬퍼를 복사해 두는 이유
|
||||||
|
|
||||||
`grpc-runtime`(`GrpcRequestFingerprint`, `GrpcResumeTokenCodec`)은 SHA-256·HMAC-SHA256 계산을 자기
|
`grpc-runtime`(`GrpcRequestFingerprint`, `GrpcResumeTokenCodec`)은 SHA-256·HMAC-SHA256 계산을 자기
|
||||||
안에 둔다. 템플릿의 `shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이
|
안에 둔다. 백엔드 템플릿 `shared-contract`의 `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 repo는
|
||||||
family는 optional build에 있는 vendored 플랫폼이고 registry edge는 `grpc:*` 안에서만 닫힌다(위 표).
|
템플릿에 의존하지 않고(루트 `AGENTS.md` 5번), registry edge는 `grpc:*` 안에서만 닫힌다(위 표). 템플릿 안에
|
||||||
`shared-contract` edge를 주면 플랫폼이 템플릿 계약 leaf에 묶여 따로 떼어 쓸 수 없게 된다 — messaging
|
있던 때도 같은 이유로 복사본이었다(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치). 복사본을 고칠
|
||||||
family가 같은 이유로 고른 배치(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정함)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과
|
때는 템플릿 `shared-contract`의 정본과 같은 규칙인지 함께 본다. `grpc-operation-ledger-jpa` integrationTest의
|
||||||
같은 규칙인지 함께 본다.
|
migration 헬퍼 셋도 같은 종류의 복사본이다(그 모듈 `build.gradle`).
|
||||||
|
|
||||||
## 증거 등급 — testkit이 하나의 leaf인 이유
|
## 증거 등급 — testkit이 하나의 leaf인 이유
|
||||||
|
|
||||||
@@ -82,12 +82,11 @@ capability flag 뒤에 있다. `GrpcPlatformStartupValidator`가 Stable catalog
|
|||||||
`grpc-spring-boot-starter`는 어떤 advanced module도 참조하지 않는다. registry의
|
`grpc-spring-boot-starter`는 어떤 advanced module도 참조하지 않는다. registry의
|
||||||
`allowed_dependencies`와 `verifyCleanArchitectureDependencies`가 이를 build time에 강제한다.
|
`allowed_dependencies`와 `verifyCleanArchitectureDependencies`가 이를 build time에 강제한다.
|
||||||
|
|
||||||
## Optional build에 있다는 것의 의미
|
## 라이브러리로 배포된다는 것의 의미
|
||||||
|
|
||||||
`grpc:*`와 `grpc-advanced:*`는 기본 `ca-skeleton` settings에 include되지 않는다. 따라서 일반
|
앱은 이 repo를 빌드에 넣지 않고 Gitea Packages에 배포한 버전(`com.hyeonworks.grpc:<모듈>:<버전>`)을 받는다. 플랫폼
|
||||||
`:app-bootstrap:build`는 이 project들을 configure하지 않는다(목록은 registry의 `"build": "optional-grpc"`). 플랫폼 자체는
|
자체는 이 repo의 `./gradlew ci`로 검증하고, 앱 runtime에 실제 채택하려면 그 앱의 조립 루트가 명시적으로
|
||||||
`./gradlew -p platforms/optional-build ci`로 검증하고, application runtime에 실제 채택하려면 composition root가
|
dependency를 가져오는 별도 변경이 필요하다. 백엔드 템플릿은 지금 이 라이브러리를 받지 않는다.
|
||||||
명시적으로 dependency를 가져오는 별도 변경이 필요하다.
|
|
||||||
|
|
||||||
런타임 포함 여부와 qualification은 별개다. in-process·Netty·fault lane이 통과해도 실제 배포 환경의
|
런타임 포함 여부와 qualification은 별개다. in-process·Netty·fault lane이 통과해도 실제 배포 환경의
|
||||||
soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위는 release gate와 support matrix가
|
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에
|
이고 `GrpcServiceAdapter`가 그 SPI를 소유한다. inbound adapter가 outbound adapter·persistence에
|
||||||
직접 닿지 않는 규칙은 app-bootstrap ArchUnit(`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`)이
|
직접 닿지 않는 규칙은 백엔드 템플릿이면 app-bootstrap ArchUnit(`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`)이
|
||||||
검사한다. 현재 `adapter:inbound:grpc`는 이 family에 의존하지 않는다 — registry의
|
검사한다. 현재 템플릿 `adapter:inbound:grpc`는 이 라이브러리에 의존하지 않는다. 배선은 별도 결정이며, 그때
|
||||||
`allowed_dependencies`를 보라. 배선은 별도 결정이며, 그때 registry edge와 브리지가 함께 들어간다.
|
템플릿 카탈로그 항목과 registry의 허용 라이브러리, 브리지가 함께 들어간다.
|
||||||
starter가 `operation-ledger-enabled=true`일 때 멱등성 판단 bean을 조립하는 것(03-11)은 이 배선이 아니다 —
|
starter가 `operation-ledger-enabled=true`일 때 멱등성 판단 bean을 조립하는 것(03-11)은 이 배선이 아니다 —
|
||||||
starter는 서버를 만들지 않고, 그 bean을 서버에 붙이는 일은 채택하는 쪽의 몫이다(아래 「Durable operation
|
starter는 서버를 만들지 않고, 그 bean을 서버에 붙이는 일은 채택하는 쪽의 몫이다(아래 「Durable operation
|
||||||
ledger adoption」).
|
ledger adoption」).
|
||||||
@@ -114,12 +113,11 @@ ledger adoption」).
|
|||||||
focused test는 registry의 `gradle_path`에서 파생한다.
|
focused test는 registry의 `gradle_path`에서 파생한다.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd src
|
./gradlew :grpc:<leaf>:test --console=plain
|
||||||
./gradlew -p platforms/optional-build :grpc:<leaf>:test --console=plain
|
./gradlew :grpc:grpc-testkit:grpcInProcessContractTest --console=plain
|
||||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest --console=plain
|
./gradlew :grpc:grpc-testkit:grpcNettyContractTest --console=plain
|
||||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcNettyContractTest --console=plain
|
./gradlew :grpc:grpc-testkit:grpcFaultTest --console=plain
|
||||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcFaultTest --console=plain
|
./gradlew :grpc:grpc-testkit:grpcPerformanceTest --console=plain
|
||||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcPerformanceTest --console=plain
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 금지
|
## 금지
|
||||||
@@ -134,8 +132,8 @@ cd src
|
|||||||
|
|
||||||
### 채택할 때의 관측 게이트
|
### 채택할 때의 관측 게이트
|
||||||
|
|
||||||
`grpc-observability`가 구현한 metric 이름은 **아직 `docs/registries/metrics.yaml`에 등록하지
|
`grpc-observability`가 구현한 metric 이름은 **채택하는 앱의 metric registry(백엔드 템플릿이면
|
||||||
않았다**. 이 optional family는 출하하는 런타임 capability가 아니기 때문이다. 채택하면서 저장소의
|
`docs/registries/metrics.yaml`)에 아직 없다**. 그 앱이 이 라이브러리를 아직 출하하지 않기 때문이다. 채택하면서 그 앱의
|
||||||
`.seconds` / `.total` 단위 이름 규칙에 맞는 registry 항목과 그에 맞는 검증 게이트를 더하기 전에는 그
|
`.seconds` / `.total` 단위 이름 규칙에 맞는 registry 항목과 그에 맞는 검증 게이트를 더하기 전에는 그
|
||||||
이름을 저장소가 인증한 metric처럼 내세우지 않는다.
|
이름을 저장소가 인증한 metric처럼 내세우지 않는다.
|
||||||
|
|
||||||
@@ -159,8 +157,9 @@ operation 멱등성이 필요한 배포는 `:grpc:grpc-operation-ledger-jpa`를
|
|||||||
(`app.capabilities.idempotency.replay-ttl`)과 같다. 레코드를 지운 뒤 같은 키로 하는 재시도는 새
|
(`app.capabilities.idempotency.replay-ttl`)과 같다. 레코드를 지운 뒤 같은 키로 하는 재시도는 새
|
||||||
operation이므로, 보존 시간은 호출자의 재시도 창보다 길어야 한다.
|
operation이므로, 보존 시간은 호출자의 재시도 창보다 길어야 한다.
|
||||||
|
|
||||||
이 키들은 `docs/registries/env-keys.yaml`에 없다. optional 빌드는 출하하는 런타임이 아니라서
|
이 키들은 채택하는 앱의 환경 변수 registry(백엔드 템플릿이면 `docs/registries/env-keys.yaml`)에 아직 없다.
|
||||||
`app.grpc.platform.*` 키는 하나도 없다. 조립 루트가 플랫폼을 채택할 때 registry에 들어간다.
|
조립 루트가 플랫폼을 채택할 때 그 registry에 들어간다. 키 이름(`app.grpc.platform.*`)은 이 라이브러리의 공개
|
||||||
|
계약이라 바꾸면 MAJOR다.
|
||||||
|
|
||||||
**starter가 interceptor를 조립하는 이유(선택지 (b)), (a)가 아닌 이유.** 2026-11-01 성숙도 리뷰는
|
**starter가 interceptor를 조립하는 이유(선택지 (b)), (a)가 아닌 이유.** 2026-11-01 성숙도 리뷰는
|
||||||
(a)를 제안했다: flag를 지우고 원장 bean이 있는지로 판단한다. 2026-11-03에 (b)를 골랐고 ADR-GRPC-004에
|
(a)를 제안했다: flag를 지우고 원장 bean이 있는지로 판단한다. 2026-11-03에 (b)를 골랐고 ADR-GRPC-004에
|
||||||
|
|||||||
+20
-16
@@ -3,18 +3,20 @@
|
|||||||
#
|
#
|
||||||
# scripts/verify.sh <단계> [--on here|<호스트>] [--log <이름>]
|
# scripts/verify.sh <단계> [--on here|<호스트>] [--log <이름>]
|
||||||
#
|
#
|
||||||
# 단계 무엇 채우는 곳
|
# 단계 무엇 Gradle
|
||||||
# docs 루트 지침·장부 검사 run_docs(뼈대에 기본 검사가 있다)
|
# docs 루트 지침·장부 검사 (없음)
|
||||||
# unit 빠른 단위 시험 run_unit
|
# unit 모듈 check 전부(단위 시험·정적 분석·lane 포함) checkAll
|
||||||
# pr PR 전에 통과해야 하는 게이트 묶음 run_pr
|
# pr PR 단계 = pr.yml ci, verifyStrictLaneStages --dry-run
|
||||||
# app 앱을 띄워 health와 기본 기능을 직접 확인 run_app
|
# main main 단계 = main.yml(Docker 필요) mainCheck
|
||||||
|
# release release.yml에서 올리기 직전까지(Docker 필요, 비밀 값 없이) releaseRehearsal
|
||||||
|
# 라이브러리라 띄울 앱이 없다. 템플릿 뼈대의 `app` 단계는 두지 않는다.
|
||||||
#
|
#
|
||||||
# --on <호스트>: 지금 작업 트리(커밋 안 된 변경 포함)를 패치로 그 호스트에 옮긴다. 기준 커밋에서 새 worktree를
|
# --on <호스트>: 지금 작업 트리(커밋 안 된 변경 포함)를 패치로 그 호스트에 옮긴다. 기준 커밋에서 새 worktree를
|
||||||
# 만들어 패치를 적용하고, 트리 해시가 여기와 같은지 본 뒤 잠금 아래에서 같은 단계를 돌리고 worktree를 지운다.
|
# 만들어 패치를 적용하고, 트리 해시가 여기와 같은지 본 뒤 잠금 아래에서 같은 단계를 돌리고 worktree를 지운다.
|
||||||
# push하지 않는다. 기준 커밋은 원격 checkout이 fetch로 받을 수 있어야 한다(기본: origin/main과 갈라진 곳).
|
# push하지 않는다. 기준 커밋은 원격 checkout이 fetch로 받을 수 있어야 한다(기본: origin/main과 갈라진 곳).
|
||||||
# 환경 변수: VERIFY_HOST(--on 기본값, 없으면 here), VERIFY_REMOTE_REPO(원격 checkout, 기본 ~/workspace/<repo 이름>),
|
# 환경 변수: 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).
|
# VERIFY_BASE_REF(기본 origin/main), VERIFY_LOCK(기본 /tmp/claude-gates/heavy.lock), VERIFY_SSH(기본 ssh).
|
||||||
# 종료 코드: 단계의 종료 코드. 2 = 사용법, 3 = 아직 채우지 않은 단계, 4 = 원격 준비 실패.
|
# 종료 코드: 단계의 종료 코드. 2 = 사용법, 4 = 원격 준비 실패.
|
||||||
set -euo pipefail
|
set -euo pipefail
|
||||||
|
|
||||||
ROOT=$(git rev-parse --show-toplevel)
|
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에서 오류다
|
trap '[ ${#TMP_FILES[@]} -eq 0 ] || rm -f "${TMP_FILES[@]}"' EXIT # 빈 배열 + set -u는 옛 bash에서 오류다
|
||||||
|
|
||||||
usage() {
|
usage() {
|
||||||
sed -n '2,19p' "$0" | sed 's/^# \{0,1\}//' >&2
|
sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//' >&2
|
||||||
exit 2
|
exit 2
|
||||||
}
|
}
|
||||||
|
|
||||||
todo() {
|
|
||||||
echo "verify: '$1' 단계는 아직 정하지 않았다. scripts/verify.sh의 run_$1을 채운다." >&2
|
|
||||||
return 3
|
|
||||||
}
|
|
||||||
|
|
||||||
# ---------------------------------------------------------------- 단계 본문(프로젝트가 채운다)
|
# ---------------------------------------------------------------- 단계 본문(프로젝트가 채운다)
|
||||||
|
|
||||||
run_docs() {
|
run_docs() {
|
||||||
@@ -56,17 +53,24 @@ for n, line in enumerate(open(sys.argv[1], encoding="utf-8"), 1):
|
|||||||
return "$rc"
|
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() {
|
run_here() {
|
||||||
case "$1" in
|
case "$1" in
|
||||||
docs | unit | pr | app) "run_$1" ;;
|
docs | unit | pr | main | release) "run_$1" ;;
|
||||||
*) usage ;;
|
*) usage ;;
|
||||||
esac
|
esac
|
||||||
}
|
}
|
||||||
|
|||||||
Reference in New Issue
Block a user