Files
grpc-library/grpc-advanced/CLAUDE.md
T
DongHyeonka 96afc8647f fix!: 남은 리뷰 항목과 합친 뒤 드러난 결함을 고친다
문제: 앞 커밋 뒤에도 알림·파일 서버 묶음이 합쳐지지 않았고, 포트 다수에
fake와 실제 구현이 함께 통과하는 공유 계약이 없었고, SpotBugs가 신뢰도
HIGH만 봤고, application-core에 관계없는 클래스 묶음 패키지(outbound)가
있었다. 묶음을 합치자 lane·검사가 새로 드러낸 결함도 있었다(JpaOutbox
Store가 읽기 전용 트랜잭션에서 이벤트를 조용히 잃음, gRPC admission
controller가 public synchronized라 외부 lock에 막힘, 소비자 decode 타입
등록 경로 없음, compose Redis 익명 접근, local-fileserver lane DB 없음).

방법: 리뷰 README 15절에 남은 결정을 모두 적고 그대로 고쳤다. 트랜잭션·
멱등성·발행·notification 포트에 testFixtures 계약 키트를 두고 fake와
PG·Redis 구현이 상속한다(fake 변이로 계약이 잡는지 확인). SpotBugs는
MEDIUM으로 내리고 진짜 결함은 고치고 오탐은 위치·패턴별 이유를 단
제외로 처리했다. 업무 기능 패키지 규칙을 application-core/CLAUDE.md에
정본으로 두고 ArchUnit 2개와 생성 명령이 강제한다. compose Redis는
infra/redis-sdk ACL로 뜬다. 묶음별 결과는 리뷰 README 16절에 있다.

위험·한계: APP_FLYWAY_ENABLED가 dev·prod에도 적용된다. app.security
오타 키가 이제 기동을 막는다. SES 콜백 replay 창 기본값이 1시간이다.
템플릿 패키지 목록은 CLAUDE.md 표와 TemplatePackageOwnership 두 곳에
있고 일치 검사는 없다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, integrationCheck, -p optional-platforms ci
integrationCheck, performanceCheck, releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 통과. compose lane 실제 기동:
local-fileserver, notification ingest·serving·handoff, local-redis,
all-adapters(smoke 3개 포함).

Refs: docs/reviews/2026-11-01-maturity-review/README.md 15·16절
BREAKING CHANGE: APP_FLYWAY_ENABLED가 dev·prod 프로필에도 적용되고,
app.security의 모르는 키는 기동을 거부한다. MessageHandler에
schemaVersions()가 생겨 decode 목록을 handler 선언에서 만든다.
2026-11-03 19:52:06 +09:00

5.0 KiB

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만으로 기계 검증할 수 있게 하기 위해서다.

의존 방향

grpc-advanced:* → grpc:*        (허용)
grpc:*          → grpc-advanced:*  (금지 — registry가 거부한다)

grpc-spring-boot-starter의 registry 엔트리에는 어떤 advanced id도 없다. verifyCleanArchitectureDependencies가 build time에 이 규칙을 강제한다. runtime 검사는 없다.

공용 다이제스트 헬퍼를 복사해 두는 이유 (review 2026-11-01 01-11)

grpc-advanced(GrpcDiagnosticsRedactor)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이 grpc-advanced:* → grpc:*로 닫혀 있고 shared-contract edge가 없는 것은 의도다. grpc/CLAUDE.md의 같은 절과 이유가 같다(vendored 플랫폼, MSG-023 §6.2와 같은 배치).

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는 app.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로 인용하는 것.