Files
clean-architecture-backend-…/docs/adr/ADR-GRPC-003-three-axis-execution-evidence.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

3.9 KiB

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

  • 상태: 채택
  • 작성일: 2026-08-30
  • 요약: 전송·업무·스트림 증거를 서로 대신하지 않는 세 축으로 본다는 결정이다.
  • 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다

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는 그것을 푸는 일이 호출자에게 맡긴 숙제가 아니라 지원하는 경로가 되게 하려고 있다.