Files
grpc-library/docs/adr/ADR-GRPC-003-three-axis-execution-evidence.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.7 KiB

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

  • 상태: 채택
  • 작성일: 2026-08-30
  • 요약: 전송·업무·스트림 증거를 서로 대신하지 않는 세 축으로 본다는 결정이다.
  • 현재 정본: docs/compatibility/grpc-support-matrix.md

ADR-GRPC-003: 전송·업무·stream 증거는 세 축이고, 어느 것도 다른 것을 뜻하지 않는다

  • 상태: 채택
  • 날짜: 2026-08-30
  • 범위: :grpc:grpc-core-api, :grpc:grpc-runtime(예전 grpc-policy), :grpc:grpc-testkit

배경

실패한 RPC는 status code를 낸다. 그리고 status code는 호출자가 실제로 가진 질문의 답이 아니다. 변경 요청의 DEADLINE_EXCEEDED는 변경이 일어났는지 말하지 않는다. 요청을 보낸 뒤의 UNAVAILABLE은 서버가 그것을 한 번도 보지 않았다고 말하지 않는다. 응답 header가 도착했다고 트랜잭션이 커밋된 것은 아니다.

그 하나하나가 그럴듯한 추론이 중복 쓰기나 잃은 쓰기를 낳는 자리이고, 성공 경로만 시험하는 시험에서는 하나도 보이지 않는다.

결정

일어난 일을 서로 독립인 세 축으로 모델링하고, 축 사이의 추론을 거절한다.

GrpcTransportEvidence는 client가 wire에서 본 것을 기록하고, NOT_SENT — client가 자기 보내기가 실패하는 것을 봤다 — 와, 아무것도 모르는 다른 모든 경우인 UNOBSERVED를 구별한다. GrpcBusinessEvidence는 애플리케이션이 확인한 것을 기록하고, COMMIT_UNKNOWN은 자리표시가 아니라 실제 상태다. GrpcStreamEvidence는 sealed 계층이고, 비어 있지 않은 경우는 모두 위치를 싣는다. 마지막 순번 없는 「부분」은 이어 가지도 맞춰 보지도 못하기 때문이다.

GrpcExecutionEvidence는 셋을 모두 가지고, 아무도 볼 수 없었을 조합을 거절한다: stream 증거가 있는 unary 호출, 또는 client가 보내기 실패를 봤는데도 업무 증거를 실은 요청. 응답 header를 확인된 커밋으로 올리는 것은 withResponseHeadersSeen을 고쳐야만 할 수 있다. 그것은 interceptor 안의 그럴듯한 한 줄이 아니라 메서드 하나다.

GrpcCompletionOutcome.forMutation이 호출자가 결론 내릴 수 있는 것을 끌어내고, 변경 요청의 DEADLINE_EXCEEDED와 보낸 뒤의 UNAVAILABLE을 기본으로 COMPLETION_UNKNOWN으로 둔다.

실패 모델과 관측 규약이 같은 타입을 쓰므로, 사고 때 호출 하나에 대한 설명이 둘이 아니라 하나다.

결과

재시도 결함의 한 종류를 아예 나타낼 수 없게 된다. GrpcRetryEligibility는 세 축 모두와 멱등성 profile을 읽는다. status만으로는 입력이 아니므로, 호출자는 status만 보고 「재시도」에 닿을 수 없다.

장애 lane에 검사할 것이 생긴다. GrpcTransportEvidenceClassifier가 client의 관찰을 증거로 바꾸고, 관찰하지 않은 상태에서 NOT_SENT를 추론하기를 거절한다 — 그리고 lane은 mock이 아니라 호출 중간에 끊은 실제 연결에 대고 그것을 시험한다.

호출자는 세 번째 결과를 다뤄야 한다. COMPLETION_UNKNOWN은 실패도 성공도 아니고, 둘 중 하나로 다루는 호출자는 틀렸다. GrpcOperationStatusQuery와 GrpcCompletionReconciler는 그것을 푸는 일이 호출자에게 맡긴 숙제가 아니라 지원하는 경로가 되게 하려고 있다.