🔌

gRPC 시작하기 - Server Streaming RPC

최민석·2026-04-14

gRPC 시작하기 - Server Streaming RPC

gRPC

🔌 gRPC with Go 시리즈

이전 글에서는 gRPC의 개요와 Unary RPC를 구현해보았습니다. 이번 글에서는 gRPC의 4가지 통신 패턴 중 Server Streaming RPC를 다룹니다. 서버가 하나의 요청에 대해 여러 응답을 순차적으로 스트림으로 보내는 패턴입니다.


Server Streaming이란

Unary RPC는 요청 하나에 응답 하나였습니다. Server Streaming은 요청 하나에 응답이 여러 개 스트림으로 전송됩니다.

sequenceDiagram participant C as 클라이언트 participant S as 서버 C->>S: CountRequest (max=5) S-->>C: CountResponse (0) S-->>C: CountResponse (1) S-->>C: CountResponse (2) S-->>C: CountResponse (3) S-->>C: CountResponse (4) Note over S,C: 서버가 스트림 종료

사용 예시로는 검색 결과를 한 건씩 스트리밍하거나, 실시간 로그를 전송하는 경우가 있습니다.


proto 파일 정의

syntax = "proto3";

package count.v1;

option go_package = "/pb";

message CountRequest {
  int32 max = 1;
}

message CountResponse {
  int32 number = 1;
}

service CountService {
  rpc Count(CountRequest) returns (stream CountResponse);
}

핵심은 returns 앞에 붙은 stream 키워드입니다. 이것만으로 gRPC가 이 메서드를 Server Streaming으로 인식합니다.


Unary와 Server Streaming의 차이

protoc이 생성하는 서버 인터페이스의 시그니처가 달라집니다.

Unary:

GetTodo(context.Context, *GetTodoRequest) (*GetTodoResponse, error)
  • context와 request를 받고, response와 error를 반환

Server Streaming:

Count(*CountRequest, grpc.ServerStreamingServer[CountResponse]) error
  • context 대신 stream 객체가 인자로 옴 (context는 stream.Context()로 접근)
  • response를 반환하지 않음 — stream.Send()로 여러 번 전송
  • 반환값은 error만

함수가 return nil하면 gRPC 프레임워크가 클라이언트에게 스트림 종료 신호를 보내고, 클라이언트의 Recv()가 io.EOF를 반환합니다.


서버 구현

type countServer struct {
    pb.UnimplementedCountServiceServer
}

func (*countServer) Count(cr *pb.CountRequest, stream grpc.ServerStreamingServer[pb.CountResponse]) error {
    maxCount := int(cr.GetMax())
    if maxCount < 0 {
        return errors.New("max must be equal or bigger than 0")
    }
    for i := range maxCount {
        time.Sleep(time.Second * 3)
        stream.Send(&pb.CountResponse{Number: int32(i)})
    }
    return nil
}

stream.Send()를 반복 호출하여 응답을 하나씩 전송합니다. 각 전송 사이에 3초의 Sleep을 넣어 스트리밍이 순차적으로 전달되는 것을 확인할 수 있도록 했습니다.

return nil이 호출되면 스트림이 종료됩니다. 에러를 반환하면 클라이언트에게 에러가 전달됩니다.

main 함수는 Unary RPC와 동일한 패턴으로, gRPC 서버를 생성하고 서비스를 등록한 뒤 Serve합니다.


클라이언트 구현

type clientPort struct {
    pb.CountServiceClient
}

func (cp *clientPort) Count(req *pb.CountRequest) error {
    stream, err := cp.CountServiceClient.Count(context.Background(), req)
    if err != nil {
        return err
    }

    for {
        resp, err := stream.Recv()
        if err != nil {
            if errors.Is(err, io.EOF) {
                slog.Info("stream finished")
                break
            } else {
                return err
            }
        }
        slog.Info(fmt.Sprintf("number received: %v", resp.Number))
    }
    return nil
}

클라이언트에서 Count를 호출하면 stream 객체가 반환됩니다. 이후 for 루프에서 stream.Recv()를 반복 호출하여 응답을 하나씩 수신합니다.

  • stream.Recv()는 서버가 Send할 때까지 블로킹됩니다
  • 서버가 스트림을 종료하면(return nil) io.EOF 에러가 반환됩니다
  • io.EOF이면 정상 종료이므로 루프를 탈출합니다

clientPort 구조체에 CountServiceClient를 임베딩하고, context 생성과 스트림 소비를 래핑하여 호출하는 쪽에서는 request만 넘기면 되도록 추상화했습니다.


실행 결과

# 터미널 1 — 서버 시작
$ go run server/main.go
16:32:51 INFO server starting...

# 터미널 2 — 클라이언트 실행
$ go run client/main.go
16:33:00 INFO number received: 0
16:33:03 INFO number received: 1
16:33:06 INFO number received: 2
16:33:09 INFO number received: 3
16:33:12 INFO number received: 4
16:33:12 INFO stream finished
16:33:12 INFO client terminating...

3초 간격으로 서버에서 숫자가 스트리밍되어 오는 것을 확인할 수 있습니다. 모든 응답이 전송된 후 서버가 스트림을 종료하면, 클라이언트가 io.EOF를 수신하고 루프를 탈출합니다.

다음 글에서는 Client Streaming RPC를 다뤄보겠습니다.

관련 포스트