NestJS gRPC

gRPC 통신은 proto 계약, deadline, status code가 한 경로로 검증된다

gRPC 호출은 함수 호출처럼 보이지만 실제 운영에서는 proto 호환성, client stub 설정, metadata, deadline 예산, status code 매핑이 같은 trace 안에서 맞아야 한다.

proto에서 handler까지 책임 지도

proto → stub → handler → status

proto package, service, field number 고정

삭제 대신 reserved를 쓰고 생성된 client/server 코드가 같은 계약을 보게 한다.

stub ClientsModule과 @GrpcMethod 연결

package, protoPath, url, service 이름이 양쪽에서 같은지 확인한다.

deadline metadata와 남은 시간 전달

요청 ID, 인증 컨텍스트, deadline을 trace 안에서 함께 추적한다.

status gRPC status로 장애 경계 분리

INVALID_ARGUMENT, NOT_FOUND, UNAVAILABLE, DEADLINE_EXCEEDED를 구분한다.

compatibility

field no.

필드 번호는 wire format의 실제 주소 이름만 바꾼 변경과 번호 재사용은 영향 범위가 다르다.

reserved 7;

package

service 이름과 package가 stub 연결 키 package/protoPath/url 불일치는 런타임 UNIMPLEMENTED로 보인다.

hero.HeroService

status

도메인 실패와 통신 실패를 분리 validation은 INVALID_ARGUMENT, 일시 장애는 UNAVAILABLE에 가깝다.

RpcException

deadline

호출자 예산을 서버 작업에 전달 DB query와 downstream 호출이 남은 시간을 넘지 않게 자른다.

metadata

same trace, different cause

OK 응답 message와 trailer에 같은 requestId가 남는다.

DEADLINE_EXCEEDED 서버 작업이 호출자 예산을 넘었는지 duration을 함께 본다.

INVALID_ARGUMENT message shape와 validation 실패를 proto 계약 기준으로 설명한다.

UNAVAILABLE 일시 장애는 retry 대상이지만 mutation은 idempotency가 필요하다.

proto drift 필드 삭제와 번호 재사용 새 client가 보낸 값이 예전 server에서 다른 의미로 해석될 수 있다.

config miss package/protoPath 불일치 handler가 있어도 stub이 다른 service를 찾으면 UNIMPLEMENTED로 보인다.

deadline leak timeout 없는 내부 호출 client는 이미 포기했는데 DB와 downstream 작업은 계속 돈다.

retry duplicate mutation 재시도 중복 UNAVAILABLE 재시도는 안전하지만 결제/주문 생성은 중복 방지가 필요하다.

검증 질문

gRPC 운영 품질은 양쪽 코드가 같은 계약과 같은 시간 예산을 보는지로 확인한다.