- 결정 4: JPA evidence·qualification manifest 폐기 → persistence-jpa 테스트, build-tools included build 비움(verifyEnvKeys는 app-bootstrap 태스크, 구현은 build-logic `ca.config-contract`), gRPC release gate 삭제 - 결정 20: API surface 검사를 leaf `check`로, JPA adopter 검사를 `ca.api-surface`로 합침(구현 하나) - 레인 단계 정리(문서 대조 레인은 `mainStage()`), integrationCheck가 입력 없는 레인을 이름과 함께 제외 → 로컬 통과(NEW-16) - release workflow 통합, releaseCheck는 tag 전용, build-logic 비핵심 플러그인 정리, sample을 ArchUnit 대상에 - 보류 4행(B3 변경 모듈만 실행, C 이미지 서명, messaging 카드 검증 이동 2행 — 결정 필요), 남음 2행(O3-5 나머지) - 통합: P17이 옮긴 gRPC release gate 사본 삭제, `grpc-proto-buf`를 release-gate needs에(P17-new-3) 검증: ./gradlew ci verifyDependencyLocks --warning-mode=fail 통과(685 task), mainCheck 통과(268 task), -p optional-platforms ci 통과, -p build-logic test 78건 통과(손상된 TestKit 캐시 삭제 후) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
83 lines
4.6 KiB
Markdown
83 lines
4.6 KiB
Markdown
# grpc-advanced — local authority for the advanced gRPC capabilities
|
|
|
|
이 문서는 `grpc-advanced:*` family의 **local authority**다. leaf 목록·gradle path·허용 의존성은
|
|
`src/config/architecture/modules.json`이 SSOT다. Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면
|
|
root가 이긴다.
|
|
|
|
이 family는 Stable gRPC 플랫폼(`grpc:*`)이 **의도적으로 제외한** 능력들을 담는다. 별도 디렉터리와
|
|
별도 Gradle prefix인 이유는 하나다: "Stable starter가 advanced module을 참조하면 build가 실패한다"는
|
|
불변 조건을 registry의 `allowed_dependencies`만으로 기계 검증할 수 있게 하기 위해서다.
|
|
|
|
## 의존 방향
|
|
|
|
```text
|
|
grpc-advanced:* → grpc:* (허용)
|
|
grpc:* → grpc-advanced:* (금지 — registry가 거부한다)
|
|
```
|
|
|
|
`grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다.
|
|
`verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다.
|
|
|
|
## Capability grade와 feature flag
|
|
|
|
capability마다 별도 flag를 갖는다. 하나의 "advanced" 스위치로 묶지 않는 이유는, gRPC-Web을 켜는
|
|
결정(프록시 하나)과 xDS를 켜는 결정(control plane과 그 장애 모드 전체)이 같은 결정이 아니기
|
|
때문이다. 하나의 스위치는 두 번째 결정을 실수로 내리게 만든다.
|
|
|
|
| grade | 시작 가능 | production 추가 승인 |
|
|
| --- | --- | --- |
|
|
| `ADVANCED_STABLE` | O | 불필요 |
|
|
| `EXPERIMENTAL` | O | **필요** |
|
|
| `WATCH` | X (추적만) | — |
|
|
| `DISABLED` | X | — |
|
|
|
|
property key는 `ca-skeleton.grpc.advanced.<capability>.enabled`이고 전부 기본 off다.
|
|
`GrpcAdvancedModuleGuard`가 세 조건(flag 미설정 / grade가 시작 불가 / production 승인 없음)을
|
|
구분해서 거부하며, 세 경우의 조치가 다르므로 메시지도 다르다.
|
|
|
|
## Leaf별 담당 capability
|
|
|
|
| leaf | 패키지(`dev.caskeleton.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 |
|
|
| `grpc-advanced` | `streaming` | client streaming(session/dedup/checkpoint), bidi(dual sequence), manual flow control |
|
|
| `grpc-advanced` | `resilience`·`discovery`·`xds` | read-only hedging, custom name resolver SPI, custom load balancer SPI, proxyless xDS |
|
|
| `grpc-advanced` | `diagnostics` | Channelz/CSDS 진단 |
|
|
| `grpc-advanced-compat` | `web`·`integration`·`reactor`·`kotlin` | gRPC-Web, Spring Integration bridge, Reactor adapter, Kotlin coroutine 취소 bridge |
|
|
|
|
`grpc-advanced-compat`만 따로 있는 이유는 Reactor·Spring Integration이라는 실제 의존성 경계다. 나머지
|
|
다섯 capability는 framework 의존이 없어 한 leaf에 있다(2026-09-28까지는 leaf 다섯 개). capability별
|
|
독립은 leaf 경계가 아니라 capability flag와 promotion 레코드가 보장한다. 참조 Envoy 설정은 jar에 싣지
|
|
않는 테스트 fixture(`grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`)다.
|
|
|
|
## Promotion은 capability별로 독립이다
|
|
|
|
승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른
|
|
것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고
|
|
호출처가 없어 삭제했다(리뷰 2026-09-24 S5-lead-4). 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의
|
|
리뷰 규칙이다.
|
|
|
|
승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가
|
|
더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다.
|
|
|
|
## 이 저장소에서 검증할 수 없는 것
|
|
|
|
capability별로 필요한 실제 인프라가 이 저장소에 없다.
|
|
|
|
- `grpc-web` → gRPC-Web 프록시
|
|
- `servlet-compat` → Servlet 컨테이너
|
|
- `xds` → 중지 가능한 xDS control plane
|
|
- `kotlin` → Kotlin 툴체인
|
|
|
|
인프라 없이 도는 suite는 통과하면서 아무것도 증명하지 않으므로, suite가 없는 것보다 나쁘다.
|
|
이 사실을 상수로 반환하던 gate 클래스(`GrpcKotlinCompatibilityGate`, `GrpcAdvancedInfrastructureTestkit`
|
|
등)는 2026-09-25 삭제됐다 — 지원 여부는 이 문서와 support matrix가 적는다.
|
|
|
|
## 금지
|
|
|
|
- Stable leaf(`grpc:*`)가 이 family를 참조하는 것.
|
|
- capability grade 없이, 또는 flag 없이 advanced 코드 경로를 실행하는 것.
|
|
- `WATCH` capability를 스키마 소스로 사용하는 것.
|
|
- 실제 인프라 없이 실행한 suite를 promotion evidence로 인용하는 것.
|