go gRPC package

go gRPC package에서 client에 필요한 타입, 메소드만 가져와 정리

type ClientConn

• gRPC 엔드포인트에 대한 가상 연결 생성
• TCP 연결 설정, TLS 핸드셰이크 등 기능 포함

NewClient

NewClient(target string, opts ...DialOption) (conn *ClientConn, err error)

• 새로운 gRPC 채널 생성
• 내부적으로 네트워크 연결, 인증(TLS/SSL), 로드밸런싱 등 다양한 설정을 처리
• 메소드 실행 시 자동으로 연결 생성
  • 연결은 비동기적으로 설정될 수 있으므로 연결 완료까지 대기 필요
• 하나의 ClientConn을 여러 gRPC 클라이언트에서 재사용하는 것이 권장

Close

(*ClientConn) Close() error

• 모든 연결을 종료
• 연결을 종료한 뒤에는 해당 ClientConn을 사용하는 모든 RPC 호출이 실패

NewStream

(*ClientConn) NewStream(ctx context.Context, desc *StreamDesc, method string, opts ...CallOption) (ClientStream, error)

• 클라이언트 측의 새로운 스트림 생성
• 일반적으로 생성된 코드 grpc.pb.go에 의해 호출됨

Invoke

(*ClientConn) Invoke(ctx context.Context, method string, args, reply any, opts ...CallOption) error

• 단항 RPC에서 사용
• RPC 요청을 전송하고 응답이 수신된 후 반환 → 스트리밍 RPC에는 사용 안함
• 일반적으로 생성된 코드 grpc.pb.go에 의해 호출됨
  
  

---

type ClientStream

CloseSend

CloseSend() error

• 스트림의 수신 방향을 닫음(half-close)
  • 클라이언트 측에서 더 이상 메시지를 송신하지 않겠다는(SendMsg) 신호를 서버에 보냄
  • 클라이언트 수신(RecvMsg)은 가능함

SendMsg

SendMsg(m any) error

• 메시지 전송
• 일반적으로 생성된 코드에 의해 호출됨
• 오류 발생 시 스트림 중단
• 메시지 전송 보장이 안됨

RecvMsg

RecvMsg(m any) error

• 서버로부터 메시지를 수신할 때까지 또는 스트림이 완료될 때까지 대기
• 스트림이 성공적으로 완료되면 io.EOF를 반환
• 오류 발생 시, 스트림은 중단되며 오류에는 gRPC 상태 코드가 포함
  
  

---

type BidiStreamingClient

Send

Send(*Req) error

• 서버로 요청 메시지를 전송
• 여러 번 호출 가능(스트리밍)
• 오류 발생 시, 스트림이 중단

Recv

Recv() (*Res, error)

• 서버로부터 응답 메시지를 수신
• 여러 번 호출 가능(스트리밍)
• io.EOF 반환 시 스트림이 정상 종료
• Recv에서 에러가 발생하면 스트림 처리 중단 필요
  
  

---

DialOption

• gRPC 연결 생성 시 사용할 옵션 지정

인증

WithPerRPCCredentials(creds credentials.PerRPCCredentials) DialOption

• 각 RPC 호출마다 적용할 인증 정보를 지정

WithTransportCredentials(creds credentials.TransportCredentials) DialOption 

• TLS 등 전송 계층 인증 정보를 지정

인터셉터

• 프로토콜 수준의 공통 작업에서 사용
  • 모든 메시지의 송수신을 감시(로깅, 모니터링 등)
  • 공통적으로 필요한 메타데이터 삽입/추출
  • 트래픽 제어, 인증 체크 등
• 인터셉터를 메소드로 지정 가능

연결 설정

WithConnectParams(p ConnectParams) DialOption

• 연결 재시도, 백오프, keepalive 등 연결 관련 파라미터를 설정

WithDefaultCallOptions(cos ...CallOption) DialOption

• 모든 RPC 호출에 기본적으로 적용할 CallOption을 지정

WithIdleTimeout(d time.Duration) DialOption

• 연결이 유휴 상태일 때 자동으로 종료되는 시간(타임아웃)을 설정(기본값: 30분)
  
  

---

CallOption

• 개별 RPC 호출에 대한 옵션 지정

MaxCallRecvMsgSize(bytes int) CallOption

• 해당 호출에서 수신할 수 있는 최대 메시지 크기를 바이트 단위로 지정(기본값: 4MB)

MaxCallSendMsgSize(bytes int) CallOption

• 해당 호출에서 전송할 수 있는 최대 메시지 크기를 바이트 단위로 지정(기본값: math.MaxInt32)

OnFinish(onFinish func(err error)) CallOption

• RPC 호출이 끝났을 때 실행할 콜백 함수를 지정

PerRPCCredentials(creds credentials.PerRPCCredentials) CallOption

• 해당 호출에만 적용할 인증 정보를 지정(예: 토큰, 세션 등)

WaitForReady(waitForReady bool) CallOption

• 서버가 준비될 때까지 RPC를 대기시킬지 여부를 지정(기본값: false, 즉시 실패)