템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리가 있었다. gRPC 플랫폼 (src/platforms/grpc, grpc-advanced)과 그것만을 위한 두 번째 Gradle 빌드 (src/platforms/optional-build)는 템플릿 어느 leaf도 쓰지 않는데, registry 9행, workflow job 넷과 단계 하나, build-logic 플러그인 둘, 카탈로그·SpotBugs 항목, 문서 열두 개를 템플릿이 함께 지고 있었다. 소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.5절, 05-library-repos.md Q1~Q17 승인)대로 라이브러리마다 별도 repo로 옮긴다. gRPC는 템플릿 소비자가 없어 먼저 옮기고, 템플릿은 지우기만 한다(Q13). 코드와 이력은 grpc-library repo에 filter-repo로 옮겼다(옮긴 폴더의 트리 해시가 이 기준 커밋 22df3525와 같다). 지운 것: - src/platforms/grpc, grpc-advanced, optional-build(343파일) - registry의 "build": "optional-grpc" 9행 - ci-quality-gates.yml job optional-platforms·grpc-proto-buf와 그 needs, integration-main.yml optional 성능 단계와 job grpc-optional-platform-integration, release.yml job grpc-stable-release-gate와 이미지 job의 needs 한 줄 - build-logic ca.grpc-platform-module·ca.optional-architecture-registry, MainBuild(두 번째 빌드에서 주 빌드를 찾던 것)와 ArchitecturePlugin의 optional 분기. 도구 설정·이미지 목록·registry는 Gradle 루트에서 찾는다 - 카탈로그 protobufPlugin·protobuf-java-grpc·protoc·plugin protobuf(Q14: 채택 전이라 grpc-library 좌표도 넣지 않는다), SpotBugs 제외의 gRPC 줄 - 옮긴 문서: ADR-GRPC 7개, docs/compatibility/(폴더째), gRPC runbook 둘, gRPC 설계서. 리뷰·기록 본문은 고치지 않았다(Q15). 기록 하나의 머리 블록 「현재 정본」만 새 자리를 말하게 했다 - DeveloperExperienceContractTest의 optional 빌드 lane 계약 시험, adopter API 표면 검사의 optional-build 제외 경로 남긴 것: adapter:inbound:grpc(io.grpc를 직접 쓰고 플랫폼을 쓰지 않는다), src/platforms/messaging(다음 분리 작업), registry의 build 칸 지원 (ModuleRegistry, 일반 기능). 살아 있는 문서: README, docs 지도, capability-status, work/delegate· gates·decisions(새 행 「라이브러리 repo」)·defect-patterns· review-criteria(경계 밖 파일을 경로로 읽는 결합을 결함 후보로), manual 04, jpa migration-guide, build-logic AGENTS·README, testkit 주석. 새 docs/work/reference/related-repos.md가 라이브러리 repo 목록과 같이 고치는 법을 둔다. 파생 서비스 안내는 docs/upgrade 3.8절 B-55·B-56. 위험: 파생 서비스가 이 경로를 고쳤으면 수정 대 삭제 충돌이 난다 (tech-log-backend는 플랫폼을 받은 적이 없다, 설계 12절). 분리 직전 커밋 태그 pre-library-split(설계 12.2절)은 이 브랜치 권한 밖이라 달지 않았다. 검증: desktop 게이트 결과는 PR 본문(ci, mainCheck 계열, releaseCheck, compose smoke, 빠른 시작). 문서 검사 셋 rc=0. BREAKING CHANGE: src/platforms/grpc*·optional-build, :grpc:*·:grpc-advanced:* 프로젝트, ca.grpc-platform-module, 카탈로그 protoc·protobuf-java-grpc·plugin protobuf가 없다. 쓰던 서비스는 grpc-library 좌표 com.hyeonworks.grpc로 받는다(docs/upgrade/2026-11-maturity-review.md 3.8절). Refs: design-docs repo-structure/05-library-repos.md 13.1절 1·2단계
127 lines
7.6 KiB
Markdown
127 lines
7.6 KiB
Markdown
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||
|
||
- 상태: 끝남
|
||
- 작성일: 2026-08-30
|
||
- 요약: 타입 안전 gRPC 실행 플랫폼의 실행 계획과 실행 결과다.
|
||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md다
|
||
<!-- 머리 블록 끝 -->
|
||
|
||
# 타입 안전 gRPC 실행 플랫폼 — 실행 계획과 실행 결과
|
||
|
||
설계 SSOT: [docs/superpowers/specs/2026-08-30-grpc-platform-adaptation-design.md](../../design/2026-08-30-grpc-platform-adaptation-design.md)
|
||
|
||
원본:
|
||
- `docs/2026-08-13-grpc-type-safe-rpc-platform-implementation-plan.md` (Stable, Task 1–53)
|
||
- `docs/2026-08-13-grpc-advanced-capabilities-expansion-plan.md` (Advanced, Task 1–18)
|
||
|
||
이 문서는 실행 전 계획이자 실행 결과 기록이다. 각 phase는 leaf 단위로 닫혔고, 닫힘 조건은
|
||
`./gradlew <gradle-path>:check` 통과다 — 즉 test + spotless + checkstyle + SpotBugs(HIGH) +
|
||
Error Prone/`-Werror` + 저장소 전역 게이트 전이 실행이다.
|
||
|
||
## Phase 0 — 레지스트리와 스캐폴딩
|
||
|
||
- [x] `src/config/architecture/modules.json`에 18개 leaf 등록 (`grpc:*` 12, `grpc-advanced:*` 6)
|
||
- [x] leaf별 `build.gradle` 18개. io.grpc를 쓰는 leaf는 `grpc-bom`을 module scope로 import
|
||
- [x] `src/build.gradle`: `:grpc:` / `:grpc-advanced:` 를 plain JUnit+AssertJ 테스트 분기에 추가
|
||
(`messaging:*`와 같은 이유 — core-api가 Spring도 io.grpc도 이름 부르지 않는다는 주장을
|
||
검증 가능하게 만든다)
|
||
- [x] `./gradlew --write-locks ...resolveAndLockAll` 로 lockfile 18개 생성
|
||
- [x] `verifyCleanArchitectureDependencies` 통과
|
||
|
||
## Phase 1 — Foundation (`grpc-core-api`, Stable Task 1–7 + ledger port)
|
||
|
||
- [x] Task 1 `GrpcStableModuleCatalog` / `GrpcStableBuildInvariant`
|
||
- [x] Task 2 `GrpcMethodName` / `GrpcServiceName` / `GrpcChannelProfileName` / `RpcType` / `GrpcStatusCode`
|
||
- [x] Task 3 `RpcIdempotencyProfile` / `WaitForReadyPolicy` / `GrpcMethodPolicy` / `GrpcMethodPolicyCatalog`
|
||
- [x] Task 4 `GrpcTransportEvidence` / `GrpcBusinessEvidence` / `GrpcStreamEvidence` / `GrpcExecutionEvidence`
|
||
- [x] Task 5 `GrpcFailureCategory` / `GrpcCompletionOutcome` / `GrpcFailureContext` / `GrpcPlatformException`
|
||
- [x] Task 6 `GrpcDeadlineProfile` / `GrpcDeadlineBudget` / `GrpcCancellationToken` / `GrpcDeadlineExceededException`
|
||
- [x] Task 7 `GrpcRequestContext` / `GrpcMetadataKey` / `GrpcMetadataBudget` / `GrpcClientIdentity`
|
||
- [x] 추가: `dev.caskeleton.grpc.ledger` port (`GrpcOperationLedger` 외 3) — 정책 계층이 DB에 의존하지
|
||
않고 durable idempotency를 요구할 수 있게 하기 위해 core-api에 둔다
|
||
|
||
## Phase 2 — Contract governance (`grpc-proto-contract`, `grpc-codegen`, Task 8–11)
|
||
|
||
- [x] Task 8 `.proto` 2개 + `buf.yaml` + `GrpcProtoStyleManifest` / `GrpcProtoRuleViolation` / `GrpcProtoContractValidator`
|
||
- [x] Task 9 `GrpcBufPolicy` / `GrpcBreakingCategory` / `GrpcSchemaBaseline`
|
||
- [x] Task 10 `GrpcCodegenManifest` / `GrpcGeneratedPackagePolicy` / `GrpcCodegenOutput`
|
||
- [x] Task 11 `GrpcDescriptorArtifact` / `GrpcConsumerFixture` / `GrpcSchemaArtifactPublisher`
|
||
- 편차: protoc·Buf CLI 미실행. 근거는 ADR-GRPC-002
|
||
|
||
## Phase 3 — Policy (`grpc-policy`, Task 12·16·17·20·28–31·33·34·37–43)
|
||
|
||
- [x] Task 12 validation, Task 16 context propagation, Task 17 status/rich error, Task 20 TLS/credential rotation
|
||
- [x] Task 28 deadline calculator, Task 29 cancellation coordinator
|
||
- [x] Task 30 service config/retry owner, Task 31 retry eligibility/budget/coordinator, Task 42 wait-for-ready
|
||
- [x] Task 33 idempotency interceptor, Task 34 completion reconciliation
|
||
- [x] Task 37–41 stream envelope·writer·flow control·resume token·lifetime
|
||
- [x] Task 43 message size / compression / payload boundary
|
||
|
||
## Phase 4 — Server boundary (`grpc-server`, Task 13–15·18–19)
|
||
|
||
- [x] Task 13 boundary rules + raw API import rule, Task 14 typed service adapter SPI
|
||
- [x] Task 15 interceptor 순서 계약, Task 18 Netty profile/executor/admission, Task 19 shaded parity
|
||
|
||
## Phase 5 — Client / discovery / admin / observability / ledger
|
||
|
||
- [x] `grpc-client` Task 24–27
|
||
- [x] `grpc-discovery` Task 35–36
|
||
- [x] `grpc-admin` Task 21–23·45
|
||
- [x] `grpc-observability` Task 44
|
||
- [x] `grpc-operation-ledger-jpa` Task 32 (entity + repository + migration + port impl)
|
||
|
||
## Phase 6 — Composition과 인증 (`grpc-spring-boot-starter`, `grpc-testkit`)
|
||
|
||
- [x] Task 52 properties / auto-configuration / startup validator
|
||
- [x] Task 46 in-process fixture, Task 47 실제 Netty + TLS/mTLS fixture
|
||
- [x] Task 48 fault point / scenario / evidence classifier
|
||
- [x] Task 49–50 unary·streaming contract suite, Task 51 performance budget/gate
|
||
- [x] Task 53 compatibility matrix / release evidence / release gate
|
||
- [x] strict test lane 4개 등록 및 실행: `grpcInProcessContractTest`, `grpcNettyContractTest`,
|
||
`grpcFaultTest`, `grpcPerformanceTest`
|
||
|
||
## Phase 7 — Advanced (`grpc-advanced:*`, Advanced Task 1–18)
|
||
|
||
- [x] A1·A18 `grpc-advanced-bootstrap`
|
||
- [x] A2·A3 `grpc-advanced-edition`
|
||
- [x] A4–A7 `grpc-advanced-streaming`
|
||
- [x] A8–A11 `grpc-advanced-resilience`
|
||
- [x] A12–A16 `grpc-advanced-compat`
|
||
- [x] A17 `grpc-advanced-diagnostics`
|
||
|
||
## Phase 8 — 문서와 게이트
|
||
|
||
- [x] `src/grpc/CLAUDE.md`, `src/grpc-advanced/CLAUDE.md`
|
||
- [x] ADR-GRPC-001..005, ADR-GRPC-ADV-001
|
||
- [x] `docs/runbooks/grpc-platform-operations.md`, `docs/runbooks/grpc-advanced-capabilities.md`
|
||
- [x] `docs/compatibility/grpc-support-matrix.md`, `docs/compatibility/grpc-advanced-support-matrix.md`
|
||
- [x] `verifyRunbookReferences`, `verifyDocumentedLeafCount` 통과
|
||
|
||
## Phase 9 — 2026-08-31 계획 대조 감사
|
||
|
||
사용자가 "빠짐없이 반영한게 맞나"를 물어 계획의 `Files:` 절 전체를 기계 대조했다. 결과와 조치는
|
||
설계 문서 §6이 SSOT다. 요약:
|
||
|
||
- [x] 대조 스크립트 실행 → 초기 결과 present=316 / missing=38
|
||
- [x] 실제 누락 6건 보완: `GrpcKubernetesProfileValidator`, `ADR-GRPC-006`(discovery/Kubernetes),
|
||
xDS `bootstrap.json`, `control-plane-snapshot.json`, `DocumentClientFixture`,
|
||
`buf.gen.yaml`+`buf.lock`
|
||
- [x] 추가한 픽스처는 전부 실제 검사에 물렸다 — 장식이 되지 않도록:
|
||
`GrpcXdsStartupGuard.bootstrapMismatches`(namespace 불일치·비TLS control plane),
|
||
redactor가 실제 모양의 CSDS 데이터로 검증, `GrpcConsumerFixture.fromJavaSource`가 fixture
|
||
소스에서 요구사항을 역산
|
||
- [x] 테스트 클래스 17건을 계획이 명시한 이름으로 분리
|
||
- [x] 재대조 → present=341 / missing=13, 잔여 13건은 전부 §6.1–6.4의 기록된 편차
|
||
(ADR 파일명 6, codegen convention plugin 3, TLS 인증서 3, Kotlin `.kt` 1)
|
||
|
||
## 남은 작업 (이 계획 범위 밖, 별도 결정 필요)
|
||
|
||
1. **런타임 투입.** 신규 leaf 전부 `runtime_memberships: []`다. `app-bootstrap`에 배선하려면 registry
|
||
membership 변경 + `verifyRuntimeModuleMembership` 통과가 선행이며, 그것은 별도 결정이다.
|
||
2. **`adapter:inbound:grpc` 브리지.** registry의 `allowed_dependencies`에 `grpc-core-api`·`grpc-server`를
|
||
추가하고 typed service adapter를 배선하는 작업. 플랫폼이 green이 된 지금이 시작점이다.
|
||
3. **protoc / Buf CLI 활성화.** ADR-GRPC-002가 조건과 비용을 기록한다.
|
||
4. **performance baseline 기록.** 현재 lane은 shape만 검증한다. 알려진 runner에서의 baseline이
|
||
regression gate를 만든다.
|