Files
clean-architecture-backend-…/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md
T
DongHyeonka 91804ec182 fix(docs): 옮긴 gRPC 기록은 템플릿에 남기고 머리 블록만 고친다
앞 커밋이 ADR-GRPC 7개와 gRPC 설계서를 살아 있는 문서와 함께 지웠다.
그러자 기록 docs/history/plans/2026-08-30-grpc-platform-implementation.md의
상대 링크가 깨졌다(desktop: check-work-docs --links broken 1, lychee
Error 1). 기록 본문은 고치지 않는다는 규칙이라 링크를 고칠 수 없다.
기록은 그때 템플릿 안 코드를 두고 한 결정·설계이므로 템플릿에도 남는
것이 맞다(설계 Q15 「리뷰 기록은 템플릿에 남김」과 같은 이유).

- ADR-GRPC 7개와 설계서를 22df3525에서 되살리고, 머리 블록 「현재 정본」을
  「없음 — grpc-library로 옮겼다」로 바꿨다. 사본은 grpc-library에도 있다.
- 업그레이드 안내 B-55의 지운 목록에서 그 기록들을 뺐다.
- persistence-jpa testkit 주석 둘을 Spotless 줄바꿈대로 다시 쌌다
  (desktop ci의 spotlessJavaCheck 실패).

검증(로컬, 문서만): check-docs.py rc=0, check-work-docs.py --links
broken 0. Gradle 게이트는 desktop에서 다시 돈다.
2026-11-08 13:05:03 +09:00

4.1 KiB

결정 기록 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 채택
  • 작성일: 2026-08-30
  • 요약: gRPC 고급 기능마다 따로 플래그·등급·승격 기준을 둔다는 결정이다.
  • 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-advanced-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다

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가 조용히 넓어질 수 없다.