문제: `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.
3.7 KiB
결정 기록 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-30
- 요약: 서버 스트림은 writer 하나, 제한된 큐, 추측하지 않는 resume로 다룬다는 결정이다.
- 현재 정본:
docs/compatibility/grpc-support-matrix.md
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가 누가 그것을 다르게 다시 쓸 법한 자리에서 그렇게 말한다.