Files
clean-architecture-backend-…/docs/history/plans/2026-08-30-grpc-platform-implementation.md
T
DongHyeonka 5e204e6a43 refactor(platforms)!: gRPC 플랫폼을 별도 repo grpc-library로 옮기고 지운다
템플릿 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단계
2026-11-08 11:29:47 +09:00

7.6 KiB
Raw Blame History

기록 · 계획서 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 끝남
  • 작성일: 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

원본:

  • 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 — 레지스트리와 스캐폴딩

  • src/config/architecture/modules.json에 18개 leaf 등록 (grpc:* 12, grpc-advanced:* 6)
  • leaf별 build.gradle 18개. io.grpc를 쓰는 leaf는 grpc-bom을 module scope로 import
  • src/build.gradle: :grpc: / :grpc-advanced: 를 plain JUnit+AssertJ 테스트 분기에 추가 (messaging:*와 같은 이유 — core-api가 Spring도 io.grpc도 이름 부르지 않는다는 주장을 검증 가능하게 만든다)
  • ./gradlew --write-locks ...resolveAndLockAll 로 lockfile 18개 생성
  • verifyCleanArchitectureDependencies 통과

Phase 1 — Foundation (grpc-core-api, Stable Task 1–7 + ledger port)

  • Task 1 GrpcStableModuleCatalog / GrpcStableBuildInvariant
  • Task 2 GrpcMethodName / GrpcServiceName / GrpcChannelProfileName / RpcType / GrpcStatusCode
  • Task 3 RpcIdempotencyProfile / WaitForReadyPolicy / GrpcMethodPolicy / GrpcMethodPolicyCatalog
  • Task 4 GrpcTransportEvidence / GrpcBusinessEvidence / GrpcStreamEvidence / GrpcExecutionEvidence
  • Task 5 GrpcFailureCategory / GrpcCompletionOutcome / GrpcFailureContext / GrpcPlatformException
  • Task 6 GrpcDeadlineProfile / GrpcDeadlineBudget / GrpcCancellationToken / GrpcDeadlineExceededException
  • Task 7 GrpcRequestContext / GrpcMetadataKey / GrpcMetadataBudget / GrpcClientIdentity
  • 추가: dev.caskeleton.grpc.ledger port (GrpcOperationLedger 외 3) — 정책 계층이 DB에 의존하지 않고 durable idempotency를 요구할 수 있게 하기 위해 core-api에 둔다

Phase 2 — Contract governance (grpc-proto-contract, grpc-codegen, Task 8–11)

  • Task 8 .proto 2개 + buf.yaml + GrpcProtoStyleManifest / GrpcProtoRuleViolation / GrpcProtoContractValidator
  • Task 9 GrpcBufPolicy / GrpcBreakingCategory / GrpcSchemaBaseline
  • Task 10 GrpcCodegenManifest / GrpcGeneratedPackagePolicy / GrpcCodegenOutput
  • 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)

  • Task 12 validation, Task 16 context propagation, Task 17 status/rich error, Task 20 TLS/credential rotation
  • Task 28 deadline calculator, Task 29 cancellation coordinator
  • Task 30 service config/retry owner, Task 31 retry eligibility/budget/coordinator, Task 42 wait-for-ready
  • Task 33 idempotency interceptor, Task 34 completion reconciliation
  • Task 37–41 stream envelope·writer·flow control·resume token·lifetime
  • Task 43 message size / compression / payload boundary

Phase 4 — Server boundary (grpc-server, Task 13–15·18–19)

  • Task 13 boundary rules + raw API import rule, Task 14 typed service adapter SPI
  • Task 15 interceptor 순서 계약, Task 18 Netty profile/executor/admission, Task 19 shaded parity

Phase 5 — Client / discovery / admin / observability / ledger

  • grpc-client Task 24–27
  • grpc-discovery Task 35–36
  • grpc-admin Task 21–23·45
  • grpc-observability Task 44
  • grpc-operation-ledger-jpa Task 32 (entity + repository + migration + port impl)

Phase 6 — Composition과 인증 (grpc-spring-boot-starter, grpc-testkit)

  • Task 52 properties / auto-configuration / startup validator
  • Task 46 in-process fixture, Task 47 실제 Netty + TLS/mTLS fixture
  • Task 48 fault point / scenario / evidence classifier
  • Task 49–50 unary·streaming contract suite, Task 51 performance budget/gate
  • Task 53 compatibility matrix / release evidence / release gate
  • strict test lane 4개 등록 및 실행: grpcInProcessContractTest, grpcNettyContractTest, grpcFaultTest, grpcPerformanceTest

Phase 7 — Advanced (grpc-advanced:*, Advanced Task 1–18)

  • A1·A18 grpc-advanced-bootstrap
  • A2·A3 grpc-advanced-edition
  • A4–A7 grpc-advanced-streaming
  • A8–A11 grpc-advanced-resilience
  • A12–A16 grpc-advanced-compat
  • A17 grpc-advanced-diagnostics

Phase 8 — 문서와 게이트

  • src/grpc/CLAUDE.md, src/grpc-advanced/CLAUDE.md
  • ADR-GRPC-001..005, ADR-GRPC-ADV-001
  • docs/runbooks/grpc-platform-operations.md, docs/runbooks/grpc-advanced-capabilities.md
  • docs/compatibility/grpc-support-matrix.md, docs/compatibility/grpc-advanced-support-matrix.md
  • verifyRunbookReferences, verifyDocumentedLeafCount 통과

Phase 9 — 2026-08-31 계획 대조 감사

사용자가 "빠짐없이 반영한게 맞나"를 물어 계획의 Files: 절 전체를 기계 대조했다. 결과와 조치는 설계 문서 §6이 SSOT다. 요약:

  • 대조 스크립트 실행 → 초기 결과 present=316 / missing=38
  • 실제 누락 6건 보완: GrpcKubernetesProfileValidator, ADR-GRPC-006(discovery/Kubernetes), xDS bootstrap.json, control-plane-snapshot.json, DocumentClientFixture, buf.gen.yaml+buf.lock
  • 추가한 픽스처는 전부 실제 검사에 물렸다 — 장식이 되지 않도록: GrpcXdsStartupGuard.bootstrapMismatches(namespace 불일치·비TLS control plane), redactor가 실제 모양의 CSDS 데이터로 검증, GrpcConsumerFixture.fromJavaSource가 fixture 소스에서 요구사항을 역산
  • 테스트 클래스 17건을 계획이 명시한 이름으로 분리
  • 재대조 → 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를 만든다.