[Network] gRPC: HTTP/2 + Protobuf, 4가지 streaming 패턴

gRPC, Protocol Buffers, Protobuf, gRPC streaming, unary RPC, bidirectional streaming, grpc-web

정의

gRPC 는 HTTP/2 위에서 Protobuf 직렬화 로 동작하는 고성능 RPC 프레임워크. Google 내부 Stubby 의 오픈소스 후계.

핵심 4가지:

1. Protobuf: IDL + binary 직렬화 (JSON 대비 수배 작고 빠름)
2. HTTP/2: multiplexing + binary framing
3. Streaming 4종: unary, server-stream, client-stream, bidi
4. Code generation: .proto → 다국어 stub 자동 생성

Proto 정의

syntax = "proto3";
package shop.v1;

service Shop {
  // Unary: 1 req → 1 res
  rpc GetItem(GetItemRequest) returns (Item);

  // Server streaming: 1 req → N res
  rpc ListItems(ListRequest) returns (stream Item);

  // Client streaming: N req → 1 res
  rpc UploadEvents(stream Event) returns (UploadAck);

  // Bidirectional: N req ↔ N res
  rpc Chat(stream Message) returns (stream Message);
}

message Item {
  string id = 1;
  string name = 2;
  int32 price_cents = 3;
}

4가지 Streaming 패턴

flowchart TB
    subgraph Unary["Unary RPC"]
        U1[Client] -->|1 request| U2[Server]
        U2 -->|1 response| U1
    end
    subgraph ServerStream["Server Streaming"]
        S1[Client] -->|1 request| S2[Server]
        S2 -->|stream of N| S1
    end
    subgraph ClientStream["Client Streaming"]
        C1[Client] -->|stream of N| C2[Server]
        C2 -->|1 response| C1
    end
    subgraph BiDi["Bidirectional Streaming"]
        B1[Client] -->|stream of N| B2[Server]
        B2 -->|stream of M| B1
    end

패턴	사용
Unary	일반 API
Server stream	라이브 피드, log tail, 실시간 시세
Client stream	파일 업로드, 이벤트 일괄 전송
Bidi stream	채팅, 게임, 협업

HTTP/2 위 동작

:method = POST
:scheme = https
:path = /shop.v1.Shop/GetItem
:authority = api.example.com
content-type = application/grpc
grpc-encoding = gzip
grpc-accept-encoding = identity,deflate,gzip
grpc-timeout = 1S

<protobuf-encoded body>

각 RPC = HTTP/2 stream 하나. Trailers 로 grpc-status, grpc-message 전달.

Status Code

코드	의미
0 OK	성공
1 CANCELLED	클라이언트가 cancel
2 UNKNOWN	정체불명 에러
3 INVALID_ARGUMENT	입력 오류
4 DEADLINE_EXCEEDED	timeout
5 NOT_FOUND	리소스 없음
6 ALREADY_EXISTS	중복
7 PERMISSION_DENIED	권한
8 RESOURCE_EXHAUSTED	quota 초과
9 FAILED_PRECONDITION	사전조건 위배
10 ABORTED	동시성 충돌
11 OUT_OF_RANGE	범위 외
12 UNIMPLEMENTED	구현 안됨
13 INTERNAL	내부 에러
14 UNAVAILABLE	일시 불가, retry 권장
15 DATA_LOSS	손실
16 UNAUTHENTICATED	인증 실패

Deadline (timeout)

# Python
response = stub.GetItem(req, timeout=1.0)  # 1초

# 또는 metadata
metadata = (("grpc-timeout", "1S"),)

클라이언트의 deadline 은 서버에 전파 (header). 서버가 더 깊은 RPC 를 부르면 남은 deadline 만 전달. 분산 timeout chaining.

gRPC vs REST

항목	gRPC	REST
Wire 포맷	Binary (Protobuf)	Text (JSON)
크기	수배 작음	크다
Schema	IDL 필수	옵션 (OpenAPI)
Streaming	4 모드	SSE / WebSocket 별도
브라우저 직접 호출	grpc-web 필요	기본 지원
Debugging	도구 필요	curl 가능
캐싱	직접 구현	HTTP cache
Mobile / IoT	유리	OK

내부 microservice 통신 → gRPC. 외부 public API → REST/GraphQL.

gRPC-Web

브라우저는 HTTP/2 trailer 미지원 → Envoy / proxy 가 gRPC ↔ gRPC-Web 변환:

flowchart LR
    Browser -->|gRPC-Web<br/>over HTTP/1.1| Envoy
    Envoy -->|gRPC<br/>over HTTP/2| Backend

흔한 함정

Interceptor (미들웨어)

# Python: 서버 interceptor, 인증 검사
class AuthInterceptor(grpc.ServerInterceptor):
    def intercept_service(self, continuation, handler_call_details):
        metadata = dict(handler_call_details.invocation_metadata)
        if metadata.get('authorization') != 'Bearer valid-token':
            def deny(request, context):
                context.abort(grpc.StatusCode.UNAUTHENTICATED, 'Invalid token')
            return grpc.unary_unary_rpc_method_handler(deny)
        return continuation(handler_call_details)

Interceptor = gRPC 의 미들웨어. 인증, 로깅, 메트릭, retry 등 횡단 관심사 처리. 체인 가능.

Metadata (Header 역할)

# 클라이언트: metadata 전송
metadata = [
    ('request-id', 'abc-123'),
    ('x-tenant-id', 'org-1'),
]
response = stub.GetItem(req, metadata=metadata)

# 서버: metadata 수신
def GetItem(self, request, context):
    md = dict(context.invocation_metadata())
    tenant = md.get('x-tenant-id')
    ...

Metadata = HTTP 헤더 역할. 요청마다 전달되며 Interceptor 에서도 읽기 가능.

Health Check Protocol

// grpc.health.v1.Health 표준
service Health {
  rpc Check(HealthCheckRequest) returns (HealthCheckResponse);
  rpc Watch(HealthCheckRequest) returns (stream HealthCheckResponse);
}

# K8s 1.24+ 네이티브 gRPC probe
livenessProbe:
  grpc:
    port: 50051
    service: shop.v1.Shop
  initialDelaySeconds: 5

grpc_health_probe -addr=:50051 -service=shop.v1.Shop

Load Balancing

flowchart LR
    Client --> Envoy["Envoy / L7 LB"]
    Envoy -->|round-robin| B1[Backend 1]
    Envoy -->|round-robin| B2[Backend 2]
    Envoy -->|round-robin| B3[Backend 3]

HTTP/2 multiplexing 때문에 TCP 레벨 (L4) LB 는 단일 서버로 몰림. L7 LB 또는 클라이언트 사이드 LB 필요.

방식	설명	사용
클라이언트 사이드	DNS 조회 후 round-robin	gRPC core 기본 지원
Envoy proxy	sidecar 패턴, Istio	서비스 메시 환경
K8s HeadlessService	Pod IP 직접 노출	클라이언트 LB 와 조합

ConnectRPC (gRPC 대안)

ConnectRPC (buf.build) = HTTP/1.1, HTTP/2 모두 지원. curl 로 테스트 가능. gRPC 호환. 브라우저 직접 호출 (grpc-web proxy 불필요). 2026 시점 생태계 성장 중.

관련 위키

• HTTP/2
• REST API Design
• GraphQL
• Microservices
• load-balancer
• jsonrpc-vs-grpc