Files
grpc-library/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md
T
DongHyeonka 7e08fb46a2 docs(adr): 아키텍처 결정 기록 본문을 한국어로 옮긴다
문제: `docs/adr/`의 결정 기록 26개는 머리 블록만 한국어이고 본문이
영어다. 소유자는 2026-11-07에 결정 기록도 본문까지 한국어로 쓰기로
정했다(design-docs `repo-structure/README.md` 3.2절).

방법: 결정의 뜻을 바꾸지 않고 옮긴다. 머리 블록(상태·작성일·요약·
현재 정본·대체됨)은 한 글자도 바꾸지 않는다. 본문의 상태·날짜·범위
줄, 나중에 붙인 보완·대체 메모, 따져 본 대안도 함께 옮긴다. 코드·
명령·경로·식별자·설정 키·SQL·표 구조는 원문으로 둔다. 본문이 인용한
영어 원문(루트 CLAUDE.md의 한 문장, 플러그인 주석)은 원문을 두고 뜻을
괄호로 붙인다. 결정 기록은 본문을 고치지 않는 문서라서, 번역하며 본
지금 코드와 다른 점(예: ADR-MONGO-ADV-001은 지웠다고 적은
`scripts/verify-mongodb-advanced.sh`가 지금 있다)은 고치지 않고 보고에
남긴다.

위험: 머리 블록 둘째 줄 「본문은 결정한 때의 원문이다」는 번역한 뒤
문자 그대로는 맞지 않는다. 문구를 고칠지는 통합 단계에서 정한다.

검증: python3 scripts/check-docs.py rc=0(language 줄 26개 지움,
head 실패 0), 머리 블록이 HEAD와 같은지 26개 모두 diff로 대조,
check-work-docs.py --links(gates.md 범위) 깨진 링크 0.
2026-11-07 17:33:54 +09:00

3.9 KiB

결정 기록 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 채택
  • 작성일: 2026-08-30
  • 요약: gRPC 고급 기능마다 따로 플래그·등급·승격 기준을 둔다는 결정이다.
  • 현재 정본: docs/compatibility/grpc-advanced-support-matrix.md

ADR-GRPC-ADV-001: advanced capability마다 자기 flag, 자기 등급, 자기 승격이 있다

  • 상태: 채택
  • 날짜: 2026-08-30
  • 범위: :grpc-advanced:*

배경

advanced 계획은 capability 열여섯을 다룬다. 그것들이 함께 가져오는 것은 몇 자릿수씩 다르다. gRPC-Web은 proxy를 더한다. Reactor는 의존 하나를 더한다. xDS는 control plane, 그 장애 방식, 자기 보안 경계, 자기 버전 어긋남을 더한다. hedging은 운영 traffic을 겹친다.

그것들을 flag 하나로 묶으면 가장 싼 것을 켜는 일이 가장 무거운 것을 켜는 일과 같은 결정이 된다.

결정

capability마다 flag 하나. ca-skeleton.grpc.advanced.<capability>.enabled 아래에 있고, 기본은 모두 꺼짐이다.

등급 넷. ADVANCED_STABLE은 flag로 시작한다. EXPERIMENTAL은 따로 운영 승인도 필요하다. flag는 누가 그 기능을 원했다는 뜻이고, 승인은 누가 그 장애 방식이 다 밝혀지지 않았음을 받아들였다는 뜻이기 때문이다. WATCH는 아예 시작할 수 없다. DISABLED는 거둬들인 것이다.

GrpcAdvancedModuleGuard는 세 거절 — flag 없음, 시작할 수 없는 등급, 운영 승인 없음 — 을 구별한다. 경우마다 고치는 법이 다르기 때문이다.

승격 증거는 capability마다다. GrpcAdvancedPromotionEvidence는 capability마다 record 하나라서, 어떤 승격도 다른 것을 끌고 가지 못한다. GrpcAdvancedPromotionGate.capabilitiesDraggedAlong은 빈 목록을 돌려주고, 그것은 주장이 아니라 시험한 성질이다. (2026-09-28: gate 클래스는 자기 시험 밖에서 부르는 것이 없어서 지웠다 — review 2026-09-24 S5-lead-4. capability별 규칙은 docs/runbooks/grpc-advanced-capabilities.md의 리뷰 규칙으로 남는다.) 문턱은 둘이다: ADVANCED_STABLE에는 7일 soak와 완전한 증거, Stable 기본값에는 30일. 후자는 모든 배포가 그 capability의 의존과 장애 방식을 받는다는 뜻이기 때문이다.

기반 시설은 capability마다 이름으로 댄다. GrpcAdvancedInfrastructureTestkit은 gRPC-Web에는 proxy가, Servlet에는 container가, xDS에는 멈출 수 있는 control plane이, Kotlin에는 toolchain이 필요하다고 적는다. 기반 시설 없이 도는 suite는 통과하고 아무것도 세우지 않는다. 없는 것보다 나쁘다.

결과

Kotlin 어댑터는 여기서 실패하면 닫히고, 이유를 말한다. 이 저장소에는 Kotlin toolchain이 없어서 GrpcKotlinCompatibilityGate.supportableHere()가 false를 돌려준다. 계약 요구 넷 — schema 출처 하나, coroutine 취소 전파, Stable 한계 안의 Flow backpressure, 플랫폼 증거 타입 보존 — 은 검사할 수 있고 검사한다. 빠진 것은 compile lane뿐이다.

Edition 2026은 그 watch 보고가 무어라 하든 쓸 수 없다. GrpcEdition2026Guard는 보고에 따라 달라지지 않는다. 상태 기록이 사용까지 허락하게 두면, 누가 필드 넷을 SUPPORTED로 표시하는 순간 schema가 승격 결정도, 쓰는 쪽 옮기기도, ADR도 없이 그 edition으로 옮겨 가기 때문이다.

xDS는 Stable 지원 설명의 일부가 아니다. flag와 승인 뒤에서 동작한다. GrpcXdsStartupGuard.advertisableAsStableSupport()가 false를 돌려주므로 support matrix가 조용히 넓어질 수 없다.