Mental model
gRPC is a high-performance Remote Procedure Call (RPC) framework that uses Protocol Buffers (compact binary serialization) over HTTP/2 (multiplexed streams over a single TCP connection).
Compile .proto IDL to Client/Server Stub
Encode Data to Binary Protobuf Wire Format
Multiplex Streams over single HTTP/2 TCP Connection
gRPC Server Handler Execution
Theory
- Protocol Buffers: Strongly typed binary IDL (Interface Definition Language). Serializes data up to 10x faster and 5x smaller than JSON.
- HTTP/2 Transport: Supports binary framing, header compression (HPACK), and concurrent stream multiplexing over a single TCP socket.
protobuf(29 lines)
1// user_service.proto definition
2syntax = "proto3";
3
4package user;
5
6service UserService {
7 rpc GetUser (UserRequest) returns (UserResponse);
8 rpc StreamLogs (LogRequest) returns (stream LogResponse);
9}
10
11message UserRequest {
12 string user_id = 1;
13}
14
15message UserResponse {
16 string user_id = 1;
17 string email = 2;
18 bool is_active = 3;
19}
20
21message LogRequest {
22 string service_name = 1;
23}
24
25message LogResponse {
26 string timestamp = 1;
27 string message = 2;
28}
9 lines hidden
python(11 lines)
1# Python gRPC Client Invocation
2import grpc
3import user_service_pb2
4import user_service_pb2_grpc
5
6async def run_client():
7 async with grpc.aio.insecure_channel('localhost:50051') as channel:
8 stub = user_service_pb2_grpc.UserServiceStub(channel)
9 response = await stub.GetUser(user_service_pb2.UserRequest(user_id="usr_100"))
10 print(f"User Email: {response.email}")
Alternatives and trade-offs
- REST / JSON over HTTP/1.1: Human-readable, universal browser support; text parsing overhead, HTTP/1.1 head-of-line blocking.
- gRPC / Protobuf over HTTP/2: Ultra-fast binary serialization, bi-directional streaming, strict schema contracts; requires gRPC-Web proxies for direct browser clients.
Failure modes and misconceptions
- Changing Field Tag Numbers: In Protobuf, changing field tag numbers (
string email = 2tostring email = 3) breaks backward and forward compatibility for deployed clients. Field names can change, but tag numbers MUST remain immutable. - L4 Load Balancer Connection Sticking: Classic Layer 4 TCP load balancers route an entire HTTP/2 TCP connection to a single backend pod, causing unbalanced server load. Use Layer 7 gRPC load balancing (Envoy / Traefik).
Reflect before revealing the guide
Decision scenario
Use gRPC with Protocol Buffers for internal microservice-to-microservice communication requiring low latency, strict schema validation, and high throughput.
Learning outcomes
- Compile Protocol Buffer (
.proto) schemas into strongly typed client and server stubs. - Leverage HTTP/2 stream multiplexing for concurrent RPC invocations.
- Maintain backward compatibility when updating Protobuf message fields.
Trade-offs
gRPC delivers massive throughput and serialization efficiency for internal microservices, but requires gRPC-Web translation layers for browser clients.