Files
grpc-library/docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md
T
DongHyeonka f42737d3d6 ci(docs): 문서 검사에 문체를 더하고 번역한 결정 기록의 머리 문구를 맞춘다
문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 docs/README.md에 있지만
지키는 검사가 없어서, 번역 뒤에도 runbook 열 개에 높임 문장이 남았다.
그리고 결정 기록 머리 블록의 둘째 줄은 「본문은 결정한 때의 원문이다」인데,
2026-11-07에 본문을 한국어로 옮긴 ADR에는 맞지 않는다.

- check-docs.py `style`: 살아 있는 문서의 문장 끝이 높임(습니다·합니다·
  입니다·됩니다·십시오·하세요·주세요)이면 실패. 코드 블록, 인라인 코드,
  따옴표·낫표 안 인용, 「이력」 인용 블록은 보지 않는다.
- runbook 열 개의 「이 runbook은 다음 alert에서 발동됩니다.」를 「다음 alert가
  울리면 쓴다.」로 고쳤다. 지금 걸리는 곳은 이것뿐이었다.
- 결정 기록 표시 줄을 「본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지
  않았다)」로 바꿨다: check-docs.py의 DECISION_LABEL, docs/README.md 설명,
  docs/adr의 머리 블록 33개(기록은 머리 블록만 고친다는 규칙 안).
- docs/README.md 「문서 검사」에 앞 커밋이 더한 `link`와 이번 `style`을 적고,
  링크 검사 설명을 바로잡았다. 「모듈 README」 절(design-docs
  docs-system.md 6.2절 다섯 칸)을 더했다.

버린 대안: 문체를 리뷰로만 보기(번역 묶음 네 개를 거쳐도 남았다).

위험: design-docs docs-system.md 4.1절과 프론트의 같은 문구는 이 repo
밖이라 고치지 않았다(총괄에게 알린다).

검증: python3 -m unittest discover -s scripts/tests(문체 시험 5 포함),
check-docs.py, check-work-docs.py 모두 rc=0. 이 커밋의 트리만 얹은 임시
worktree에서 돌렸다. 검사 조건을 끈 사본 둘에서 문체 시험이 각각 2건,
1건 실패했다.
2026-11-07 22:20:18 +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는 그것을 푸는 일이 호출자에게 맡긴 숙제가 아니라 지원하는 경로가 되게 하려고 있다.