Files
clean-architecture-backend-…/docs/adr/ADR-GRPC-005-server-streaming-single-writer-and-resume.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
  • 요약: 서버 스트림은 writer 하나, 제한된 큐, 추측하지 않는 resume로 다룬다는 결정이다.
  • 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다

ADR-GRPC-005: stream마다 쓰는 쪽 하나, 한계 있는 queue, 짐작하기를 거절하는 resume

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

배경

StreamObserver는 thread-safe가 아니다. 두 producer가 동시에 onNext를 부를 때의 실패는 예외가 아니다 — 섞인 바이트이고, client는 그것을 깨진 메시지로, 더 나쁘게는 받지 말았어야 할 유효한 메시지로 decode한다.

server stream에는 건강해 보이는 방식으로 틀리기 쉬운 성질이 둘 더 있다. 뒤처진 소비자는 stream을 끝내거나 메시지를 소리 없이 잃는데, 둘째는 client에게 멀쩡해 보이지만 변경이 빠진 stream을 남긴다. 그리고 재연결은 서버가 아직 재생할 수 있는 위치에서 이어 가거나, 더는 없는 것을 건너뛴다.

결정

쓰는 쪽 하나가 비우는 한계 있는 queue. GrpcSerializedStreamWriter는 어느 스레드에서든 메시지를 받고, synchronized인 flush에서만 전송에 넘긴다. write가 ACCEPTED를 돌려주는 것은 줄 세웠다는 뜻이고, 이름을 일부러 sent로 하지 않았다: 전송 호출은 바이트를 넘기자마자 돌아오므로, 여기 어떤 메서드도 전달을 정직하게 알릴 수 없다.

메시지 한계와 바이트 한계를 둘 다. 하나만 두면 다른 차원으로는 한계가 없다. GrpcFlowControlPolicy는 전송 자신의 readiness 신호도 받는다. queue 한계에만 기대는 쓰는 쪽은 메모리를 할당할 수 있는 만큼 빨리 만들어 내기 때문이다.

느린 소비자에게는 끝내기가 기본이다. GrpcSlowConsumerPolicy.DROP_OLDEST는 업무 뜻이 손실을 견디는 feed를 위해 있고 기본값이 아니다. client는 버려진 메시지를 알아챌 수 없기 때문이다: client가 보는 순번은 보내진 것의 순번이다.

resume은 꾸며 내지 않고 거절한다. GrpcStreamGapDetector는 서명됐고 만료되지 않았으며 호출자·필터 fingerprint가 지금 요청과 맞는 token을 요구하고, snapshot version이 움직인 token을 거절하며, cursor가 보존한 이력보다 앞서면 FULL_RESYNC_REQUIRED를 돌려준다. GrpcResumeToken은 key id를 싣는다. 그래서 서명 키를 바꿔도 아직 쓰이는 모든 token이 무효가 되지 않는다.

결과

stream은 맨 payload가 아니라 envelope을 싣는다. GrpcStreamEnvelope은 stream id, generation, 순번, snapshot version, resume token을 가진다. resume, 빈틈 찾기, 비우기가 모두 위치와 generation을 필요로 하기 때문이다.

시계는 하나가 아니라 넷이다. GrpcStreamLifetimePolicy는 준비 deadline, idle timeout, 최대 지속 시간, heartbeat 간격을 나누고, 하나가 절대 울릴 수 없는 조합을 거절한다. 어느 둘을 합치든 익숙한 결함이 나온다: 최대 지속 시간으로 쓴 idle timeout은 건강하게 바쁜 stream을 죽인다.

heartbeat는 살아 있다는 신호이고 그 밖의 무엇도 아니다. 애플리케이션 확인 응답도 순서 보장도 아니다. GrpcStreamHeartbeat가 누가 그것을 다르게 다시 쓸 법한 자리에서 그렇게 말한다.