diff --git a/.gitea/workflows/release.yml b/.gitea/workflows/release.yml index bfb5bb4..37a4b98 100644 --- a/.gitea/workflows/release.yml +++ b/.gitea/workflows/release.yml @@ -4,7 +4,7 @@ # anonymously). Publishing starts only after releaseCheck has passed, so a red check leaves nothing # half-published (Gitea refuses a second upload of a version). # -# Secrets (repository settings, created by the owner): PACKAGES_TOKEN, a personal access token with +# Secrets (repository settings, created by the owner): PACKAGE_TOKEN, a personal access token with # package read/write only (the job token cannot publish packages); SIGNING_KEY, an ASCII-armoured PGP # secret key; SIGNING_PASSWORD, its passphrase. name: release @@ -36,7 +36,7 @@ jobs: - run: ./gradlew releaseCheck release --stacktrace env: RELEASE_TAG: ${{ github.ref_name }} - PACKAGES_TOKEN: ${{ secrets.PACKAGES_TOKEN }} + PACKAGE_TOKEN: ${{ secrets.PACKAGE_TOKEN }} SIGNING_KEY: ${{ secrets.SIGNING_KEY }} SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }} TESTCONTAINERS_REUSE_ENABLE: "false" 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..52b54ac 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,112 @@ -# optional gRPC 플랫폼 +# grpc-library -기본 애플리케이션은 `grpc/*`나 `grpc-advanced/*`에 의존하지 않는다. 그래서 이 프로젝트들(registry에서 -`"build": "optional-grpc"`인 항목)은 주 멀티 프로젝트 빌드에서 뺀다. 이 빌드는 그 프로젝트들의 원래 -프로젝트 경로와 내부 프로젝트 의존을 그대로 두면서, 그 설정을 고를 때만 켜지게 한다. +Spring Boot 앱에 gRPC 서버·클라이언트를 붙이는 플랫폼 라이브러리다. 타입 있는 서비스 adapter, method 정책(deadline·멱등성·크기 한도), 실행 증거와 실패 모델, durable operation 원장, 관측 규칙, 인증 lane(in-process·실제 Netty·fault·performance)을 준다. -```bash -./gradlew -p platforms/optional-build ci -./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest +```text +앱 소유 port ──> 앱의 inbound adapter ──> grpc-spring-boot-starter (조립) + ├─ grpc-runtime (io.grpc 위의 정책·서버·클라이언트) + ├─ grpc-core-api (Java 표준 라이브러리만: 식별자·정책·증거·실패 모델) + ├─ grpc-observability (metric·trace 규칙) + └─ grpc-operation-ledger-jpa (선택: 멱등성 원장) ``` -`adapter:inbound:grpc`는 애플리케이션 어댑터라서 주 애플리케이션 빌드에 남는다. 다시 쓰는 gRPC -플랫폼 라이브러리는 optional capability 코드이고 여기 있다. +## 받는 법 + +Maven group은 `com.hyeonworks.grpc`, artifact는 모듈 이름 그대로다(`grpc-core-api`, `grpc-runtime`, `grpc-spring-boot-starter`, …). 저장소는 소유자 Gitea Packages이고, 공개라 읽을 때 토큰이 필요 없다. + +```groovy +// settings.gradle +dependencyResolutionManagement { + repositories { + exclusiveContent { + forRepository { + maven { url = 'https://git.learn.hyeonworks.com/api/packages/donghyeon.kang/maven' } + } + filter { includeGroupByRegex 'com\\.hyeonworks(\\..*)?' } + } + mavenCentral() + } +} +``` + +```groovy +// build.gradle +dependencies { + implementation 'com.hyeonworks.grpc:grpc-spring-boot-starter:1.0.0' +} +``` + +`exclusiveContent`는 `com.hyeonworks` group을 이 저장소에서만, 나머지는 Maven Central에서만 찾게 한다. 같은 이름을 공개 저장소에 올리는 공격이 통하지 않고, Gitea가 느려도 다른 의존성 해석에는 영향이 없다. + +## 지원 표 + +| 라이브러리 | Spring Boot(컴파일·시험한 줄) | io.grpc BOM | Java | +| --- | --- | --- | --- | +| 1.0.x | 4.0.x (`4.0.9`) | 1.75.0 | 21 | + +무엇을 인증했고 무엇은 지켜보기만 하는지는 `docs/compatibility/grpc-support-matrix.md`와 `grpc-advanced-support-matrix.md`다. + +## 프로젝트 구조 + +| 폴더 | 무엇 | +| --- | --- | +| `grpc/` | Stable 모듈 7개(Unary, Server Streaming). 규칙은 `grpc/AGENTS.md` | +| `grpc-advanced/` | capability flag 뒤의 고급 능력 2개(client·bidi streaming, xDS, gRPC-Web 등). 규칙은 `grpc-advanced/AGENTS.md` | +| `build-logic/` | 백엔드 템플릿에서 복사해 줄인 Gradle convention 플러그인. 출처는 `build-logic/UPSTREAM.md` | +| `config/` | 모듈 registry(`architecture/modules.json`), Checkstyle·SpotBugs 설정, 테스트 컨테이너 이미지 | +| `scripts/` | 검증 진입점 `verify.sh`, 고정 도구 `tool.sh`, Buf `buf.sh`, 릴리스 보조 `release/` | +| `.gitea/workflows/` | 단계 파일 셋: `pr.yml`(`ci`), `main.yml`(`mainCheck`), `release.yml`(`releaseCheck release`) | +| `docs/` | 문서. 지도는 `docs/README.md` | + +## 문서 지도 + +- 작업 방법: `docs/work/README.md`(고치기·리뷰), `docs/work/gates.md`(게이트), `docs/work/release.md`(릴리스·버전 규칙·비밀 값) +- 결정 기록: `docs/adr/`(ADR-GRPC-001~006, ADR-GRPC-ADV-001) +- 운영: `docs/runbooks/grpc-platform-operations.md`, `docs/runbooks/grpc-advanced-capabilities.md` +- 설계서: `docs/design/2026-08-30-grpc-platform-adaptation-design.md` +- 바뀐 것: `CHANGELOG.md` + +## 서명 + +배포 파일마다 PGP 서명(`.asc`)이 붙는다. 서명 키는 RSA 4096, 지문 `92646CEAFE816CF8B9C249F0A1C936D7F791F8AB`, 2028-11-07에 만료된다. 키를 바꾸는 법은 `docs/work/release.md` 1절이다. + +```text +-----BEGIN PGP PUBLIC KEY BLOCK----- + +mQINBGrv1SYBEADGgq8CTE7wdDPIg0zNRXelPvlgyK04tpDTL0b9k1INxDwFEiS0 +87bTL22Zjipp+2uDg012TALeLsDV12yh1IToNaYq7zR9bRvEua25+351zw91ojC+ +z2/1Y7S98o813hu6qP6EFUHnsWPVLEt40mlGDn3kl8iXMLgjozVYbylomweh/Yvz +HLJd5lQGE76mIejIeGp3m1OA5M2RV4xspA8K8TZkXXSqe3nbfSjPXAOwysPmRRd9 +IoLDwakSq4tRI9dlm08bzznsoaaTCRcJ0XAbJK7+ZrQkSwIrsi/gsBkCOJI6Wcs6 ++R+9Wy7tYsyd59TdgIdjq3uHadSLWQ3dc0g0ux2krxSL0PHXrT9Upmcorj2+Ltkh +9J1I6hUv1O7e0Y8Es7Ov5WUPfdSdQ5ApwtwFX5aSwYokoW9wXMLg2zdQx0JEx1ix +/qTEvpSKfM0/zVbKJO9RDF/F7HZkDWSOhZe+4x7dak+xN6KOfEQVmcBneaGtPqgJ +eAsIBgRwp42G5llqnTcWAHLAKCDEE9wHK3+gJt5f5rO5e+r1GoYHLn0Iw3iiX6rC +NFot/5my/oePTeRur5tjv14kw1FMXHVNvLOxHeaiZzfVVjO/vbwAtGvZDiRdAgd6 +kHyt9Ch/JccIa0ylA9Tttb0A33ZGTQl6sAC6jTSIhfnEAdlCX7MVAE8n4wARAQAB +tCNkb25naHllb24ua2FuZyA8ZG9uZzUxMjlAZ21haWwuY29tPokCVwQTAQoAQRYh +BJJkbOr+gWz4ucJJ8KHJNtf3kfirBQJq79UmAhsDBQkDwmcABQsJCAcCAiICBhUK +CQgLAgQWAgMBAh4HAheAAAoJEKHJNtf3kfir2j8P/RWRT0GTxBNQvm76iO6XnvFD +mDPGq37A5iuD4pJ624/BccKTGe8+WWqtlpAiN6AdHGNi/LGhuYaGL9ce6Gja5tTX +y/ZY8jthbEoi41g6cim8W8knd3v2Ne/qj3dKvphSiVsZBrumEzrZyw2UUD3IRqVx +r2WQZTcSa4UDd7+Qie0h8IrnmfMYIseDCWjDCATNJqr9PBGoKYehv8+Wo3QDVBRd +B0lWepudJjLTsPCXsgFnFJ2HmltRQr1JB+I4CPasfsBp3xqF23hywUuW6fOsHZvv +g5QU7qYfaoxG6E8krGpiibocF5EKXtpEYzDOBFoDS9uNVBAD/LzS7OGtTFr5x3qL +is3eccwNClQS1jeX8Guxam+TlO8XaqnQLCIpdau20/sge6PqXKXauKZiBTGCak1j +zVDQ/sro3VRPePusNHK1CdOi6wiruXw4ZLWO3aEHibi8LbgfwymxXHEtJO5zwFcD +qAnp7KEAkOG8y5LR0FfwWWYnqUZxWJ0ua2Acf8gL8o6DO5pVyJSYrdgCpWjwEWcp +Ms2iit9bCNIMaH6EVgLA2NWCuIL9xAFdXqw/VXrMVK3XXftzNvayvLJCH2eintRg +IKLO/ewISKIFQd3+II3/MM80eUvKGtfi8Y1mj1zyQtcPVykru5DEHjpaLs2SPxdI +Lp+HGQo/NvzwdpIV+8TQ +=eD8w +-----END PGP PUBLIC KEY BLOCK----- +``` + +받은 파일을 확인하는 법: 위 키를 `gpg --import`로 넣고 `gpg --verify <파일>.asc <파일>`. 배포 토큰 secret 이름은 설계 문서의 `PACKAGES_TOKEN`이 아니라 등록된 `PACKAGE_TOKEN`이다. + +## 이력 + +- 2026-08-31 ~ 2026-11-07: 백엔드 템플릿 `clean-architecture-backend-template` 안에서 만들었다(`src/grpc`, `src/grpc-advanced`, `src/optional-platforms` → 2026-11-07부터 `src/platforms/…`). +- 2026-11-08: `git filter-repo`로 그 경로들의 이력을 이 repo로 옮겼다(템플릿 main `22df3525` 기준). 옮긴 코드 폴더의 트리 해시는 템플릿 기준 커밋과 같다. +- filter-repo가 커밋 SHA를 모두 다시 썼다. 코드 주석과 문서가 부르는 커밋 SHA와 리뷰 ID(`RR6-…`, `BUILD-O3-5` 등)는 **템플릿 repo** 기준이다. 그 리뷰 문서는 템플릿 `docs/reviews/`에 남아 있다. +- 설계와 결정: design-docs `repo-structure/05-library-repos.md`(소유자 승인 2026-11-07). diff --git a/build-logic/UPSTREAM.md b/build-logic/UPSTREAM.md index 1dbe611..011e6b5 100644 --- a/build-logic/UPSTREAM.md +++ b/build-logic/UPSTREAM.md @@ -25,6 +25,7 @@ | `java/JavaConventionsPlugin` | `group`을 `gradle.properties`의 `libraryGroup`에서 읽는다(템플릿은 `dev.caskeleton` 고정). 버전은 `RELEASE_TAG`/`-PreleaseTag`(`vX.Y.Z`)에서도 읽는다. 이미지 목록·도구 설정은 루트의 `config/`만 본다 | | `quality/QualityConventionsPlugin` | 도구 설정은 루트의 `config/`만 본다 | | `convention/PlatformModuleConventionPlugin` | `ca.library-publishing`을 함께 켠다 | +| `ModuleRegistry` | registry 행의 `build` 칸을 거절한다. main이 아닌 값(오타 포함)이면 그 모듈이 조용히 빌드에서 빠졌다. 템플릿 `91804ec1` 뒤 브랜치 `claude/x2-grpc-library-43dd09`에 같은 수정이 있다 | | `strictlane/StrictLaneStagesPlugin` | 단계의 계획을 따라갈 때 included build 태스크(`ci`가 부르는 build-logic `test`)는 묻지 않는다. 템플릿 `ci`에는 그런 의존이 없어 드러나지 않았다. 템플릿에도 옮길 만한 수정이다 | | 새 `publishing/LibraryPublishingPlugin`(`ca.library-publishing`) | 모듈마다 Maven publication(sources·javadoc jar, 해석된 버전), 저장소 `gitea`·`staging`, `SIGNING_KEY`가 있으면 PGP 서명 | | 테스트 fixture | `source_path`를 Gradle 루트 기준으로, `PlatformModuleConventionTest`에 `libraryGroup` | diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistry.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistry.java index a917abb..4c292bf 100644 --- a/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistry.java +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistry.java @@ -108,7 +108,16 @@ public record ModuleRegistry(List modules, File source) { String id = requireNonBlankText(module, "id", index); String gradlePath = requireNonBlankText(module, "gradle_path", index); String sourcePath = requireNonBlankText(module, "source_path", index); - String buildName = module.has("build") ? requireNonBlankText(module, "build", id) : "main"; + // Every module belongs to the one build. A row naming any other build (a typo included) would + // be included by no settings and checked by no direction gate while ci stays green, so the + // field is refused rather than read (the template's optional build, which used it, is gone). + if (module.has("build")) { + throw new IllegalStateException( + "Module registry entry '" + + id + + "' has a 'build' field; every module belongs to the main build, so remove it."); + } + String buildName = "main"; List allowedDependencies = requireStringList(module.get("allowed_dependencies"), id, "allowed_dependencies"); diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/publishing/LibraryPublishingPlugin.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/publishing/LibraryPublishingPlugin.java index 9b32f94..2f42a9e 100644 --- a/build-logic/src/main/java/dev/caskeleton/buildlogic/publishing/LibraryPublishingPlugin.java +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/publishing/LibraryPublishingPlugin.java @@ -23,7 +23,7 @@ import org.gradle.plugins.signing.SigningExtension; * *