diff --git a/AGENTS.md b/AGENTS.md index 112c9d9..82e482d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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`). diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..b71909c --- /dev/null +++ b/CHANGELOG.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`는 그대로다. diff --git a/CLAUDE.md b/CLAUDE.md index cbbd698..f0e7062 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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` 아래). diff --git a/README.md b/README.md index 8df221e..993d461 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,78 @@ -# 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`)이 붙는다. 공개 키는 첫 릴리스 때 소유자가 여기에 붙인다(`docs/work/release.md` 1절). + +## 이력 + +- 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). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..6b37478 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,30 @@ +# 문서 지도 + +## 1. 어디에 무엇이 있나 + +| 폴더 | 종류 | 고치는 법 | +| --- | --- | --- | +| `work/` | 작업 방법(고치기, 게이트, 릴리스) | 살아 있는 문서. 동작이 바뀌면 같은 변경에서 고친다 | +| `compatibility/` | 지원 매트릭스(무엇을 인증했나) | 살아 있는 문서 | +| `runbooks/` | 운영 대응 | 살아 있는 문서 | +| `adr/` | 결정 기록(ADR-GRPC-*) | 기록. 본문은 고치지 않는다 | +| `design/` | 설계서 | 기록. 본문은 고치지 않는다 | +| `ledger/` | 예측·실측 장부 | 줄을 더하기만 한다 | +| `vision.md`, `problem-statement.md` | 방향, 풀 문제 | `vision.md`는 소유자만 쓴다 | + +## 2. 기록 문서의 머리 블록 + +`adr/`와 `design/`의 문서는 맨 위에 머리 블록을 둔다. 본문은 쓴 때의 원문이고, 지금도 맞는지는 머리 블록이 말한다. + +```markdown + +> **결정 기록** 본문은 결정한 때의 내용이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. + +- 상태: 채택 | 대체됨(무엇으로) | 폐기 +- 작성일: YYYY-MM-DD +- 요약: 한 문장 +- 현재 정본: 지금 동작을 설명하는 살아 있는 문서 경로 + +``` + +지난 결정이 바뀌면 본문은 두고 「상태」와 「현재 정본」만 고친다. 템플릿에서 옮겨 온 기록의 본문 경로(`src/platforms/…`, `.github/workflows/…`)는 그 결정 때의 템플릿 경로다. diff --git a/docs/compatibility/grpc-support-matrix.md b/docs/compatibility/grpc-support-matrix.md index 67e9f73..a469245 100644 --- a/docs/compatibility/grpc-support-matrix.md +++ b/docs/compatibility/grpc-support-matrix.md @@ -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 입력 둘이 남아 있고, 그것이 지금부터 릴리스까지의 일이다. diff --git a/docs/problem-statement.md b/docs/problem-statement.md index 1676af5..e33cf6c 100644 --- a/docs/problem-statement.md +++ b/docs/problem-statement.md @@ -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절. diff --git a/docs/runbooks/grpc-advanced-capabilities.md b/docs/runbooks/grpc-advanced-capabilities.md index 1382ead..ae02851 100644 --- a/docs/runbooks/grpc-advanced-capabilities.md +++ b/docs/runbooks/grpc-advanced-capabilities.md @@ -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`가 그런 메서드를 거부한다. diff --git a/docs/runbooks/grpc-platform-operations.md b/docs/runbooks/grpc-platform-operations.md index 44f2bf3..996bd80 100644 --- a/docs/runbooks/grpc-platform-operations.md +++ b/docs/runbooks/grpc-platform-operations.md @@ -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이고, 앱이 이 라이브러리를 의존성으로 받지 않으면 + 아무것도 조립되지 않는다. diff --git a/docs/work/README.md b/docs/work/README.md new file mode 100644 index 0000000..85fae15 --- /dev/null +++ b/docs/work/README.md @@ -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로 넣는다(첫 커밋들만 예외였다). diff --git a/docs/work/gates.md b/docs/work/gates.md new file mode 100644 index 0000000..72622c9 --- /dev/null +++ b/docs/work/gates.md @@ -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 :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=`. diff --git a/docs/work/release.md b/docs/work/release.md new file mode 100644 index 0000000..959547e --- /dev/null +++ b/docs/work/release.md @@ -0,0 +1,80 @@ +# 릴리스 — 태그에서 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에 넣지 않는다. 아래는 소유자가 한다. + +1. **배포 토큰 `PACKAGES_TOKEN`**: Gitea 웹 → 설정 → 애플리케이션 → 새 토큰. 권한은 `package` 읽기·쓰기만 준다(repository·user 권한은 주지 않는다). Gitea job 토큰(`GITEA_TOKEN`)은 패키지를 올릴 수 없어서 사람 토큰이 필요하다. +2. **서명 키 `SIGNING_KEY`·`SIGNING_PASSWORD`**: PGP 키 쌍 하나를 두 라이브러리(grpc, messaging)가 함께 쓴다. + + ```bash + gpg --quick-generate-key "hyeonworks release " ed25519 sign 2y + ``` + + ```bash + gpg --armor --export-secret-keys <키 ID> > signing-key.asc + ``` + + `signing-key.asc` 내용 전체가 `SIGNING_KEY`, 키를 만들 때 넣은 암호가 `SIGNING_PASSWORD`다. 넣은 뒤 `signing-key.asc`는 지운다. 공개 키(`gpg --armor --export <키 ID>`)는 README 「서명」 절에 붙인다. +3. **repo secret 셋**: grpc-library → 설정 → Actions → Secrets에 `PACKAGES_TOKEN`, `SIGNING_KEY`, `SIGNING_PASSWORD`. +4. **첫 태그 `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로 넣는다. diff --git a/grpc-advanced/AGENTS.md b/grpc-advanced/AGENTS.md index 6121029..cd7cdf1 100644 --- a/grpc-advanced/AGENTS.md +++ b/grpc-advanced/AGENTS.md @@ -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..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 | diff --git a/grpc/AGENTS.md b/grpc/AGENTS.md index 2dd4889..807feda 100644 --- a/grpc/AGENTS.md +++ b/grpc/AGENTS.md @@ -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::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::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에 diff --git a/scripts/verify.sh b/scripts/verify.sh index 3297275..8f41a3d 100755 --- a/scripts/verify.sh +++ b/scripts/verify.sh @@ -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/), # 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 }