118 lines
7.0 KiB
Markdown
118 lines
7.0 KiB
Markdown
# 타입 안전 gRPC 실행 플랫폼 — 실행 계획과 실행 결과
|
||
|
||
설계 SSOT: [docs/superpowers/specs/2026-08-30-grpc-platform-adaptation-design.md](../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 — 레지스트리와 스캐폴딩
|
||
|
||
- [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를 만든다.
|