System Design HLD-03.05
gRPC and Protocol Buffers
Service definitions and generated code, compact binary messages, four streaming modes over HTTP/2, deadlines, and why gRPC suits internal traffic.
The big idea
Inside a large system, services call each other constantly: a single user request can trigger dozens of internal calls. For that traffic, human-readable JSON and hand-written HTTP clients become a cost. JSON is verbose and slow to parse, every team writes its own client code, and nothing checks that the caller and the server agree on field names until something breaks in production.
gRPCA remote procedure call framework from Google that defines services in Protocol Buffers, generates client and server code, and sends binary messages over HTTP/2. treats a remote call like a local function call with a strict contract. You define the service and its messages once in a schema file, a compiler generates typed client and server code in each language, and calls travel as compact binary Protocol BuffersGoogle's language-neutral format for defining structured messages and encoding them as compact binary. over HTTP/2. Mismatches are caught at compile time, payloads shrink, and streaming comes built in.
Think of the difference between two offices exchanging handwritten letters and two offices using pre-printed forms with numbered boxes. The forms are less flexible, but nobody misreads a field, and they are much faster to process.
How it works
Step 1: Define the contract
syntax = "proto3";
service UserService {
rpc GetUser (GetUserRequest) returns (User);
rpc ListUsers (ListUsersRequest) returns (stream User);
}
message GetUserRequest { int32 id = 1; }
message User {
int32 id = 1;
string name = 2;
bool active = 3;
repeated int32 roles = 4;
}
The numbers are field tags, not values. They identify fields on the wire, so names can change freely, but a tag must never be reused for a different meaning. The protoc compiler generates a UserServiceClient with a GetUser method in Go, Java, Python, TypeScript and more, and a server interface to implement.
Step 2: Compact binary encoding
Instead of repeating field names as text, protobuf writes each field as a small tag followed by its value, using variable-length integers where small numbers take one byte:
import json
# message User { int32 id = 1; string name = 2; bool active = 3; repeated int32 roles = 4; }
user = {"id": 150, "name": "Ada", "active": True, "roles": [1, 2, 3]}
def varint(n):
out = bytearray()
while True:
byte, n = n & 0x7F, n >> 7
out.append(byte | (0x80 if n else 0)) # high bit = "more bytes follow"
if not n:
return bytes(out)
def field(num, wire_type):
return varint(num << 3 | wire_type) # tag = field number + wire type
def encode(u):
name = u["name"].encode()
packed = b"".join(varint(r) for r in u["roles"])
return (field(1, 0) + varint(u["id"])
+ field(2, 2) + varint(len(name)) + name
+ field(3, 0) + varint(int(u["active"]))
+ field(4, 2) + varint(len(packed)) + packed)
pb = encode(user)
js = json.dumps(user, separators=(",", ":")).encode()
print("JSON ", len(js), "bytes:", js.decode())
print("protobuf", len(pb), "bytes:", pb.hex(" "))
print(f"protobuf is {len(pb) / len(js):.0%} of the JSON size")Output
JSON 53 bytes: {"id":150,"name":"Ada","active":true,"roles":[1,2,3]}
protobuf 15 bytes: 08 96 01 12 03 41 64 61 18 01 22 03 01 02 03
protobuf is 28% of the JSON size The same user is 53 bytes as compact JSON and 15 bytes as protobuf: 08 means field 1 as an integer, 96 01 is 150 as a varint, 12 03 41 64 61 is field 2, three bytes, "Ada", and so on. Parsing is also cheaper, because there is no text to scan.
Step 3: Four kinds of call
Because gRPC runs on HTTP/2 streams, a call can carry one message or many in either direction:
Step 4: Deadlines that travel
Every gRPC call can carry a deadlineAn absolute time by which a call must finish. gRPC passes it along to downstream calls, which can give up early once it has passed.. If the edge service gives a request 300 ms and has already spent 120 ms, the downstream call it makes inherits the remaining 180 ms. Services deep in the call chain stop working on requests whose caller has already given up, instead of wasting capacity on answers nobody will read. This is one of gRPC's most valuable features in large systems.
Going deeper
Evolving messages safely
Protobuf is designed for compatibility. Old readers skip fields they do not know, and new readers use defaults for fields that are missing, so you can add fields without coordinating every deployment. The rules: never change a field's tag or type, never reuse a deleted tag (mark it reserved), and treat every field as optional. Break those rules and old and new services silently misread each other's data.
Browsers and public APIs
Browsers cannot speak raw gRPC, because they do not give JavaScript control over HTTP/2 framing and trailers. gRPC-Web and translating proxies exist, but most teams keep REST or GraphQL at the public edge and use gRPC between their own services, often with a gateway translating between the two ( API gateway and backend-for-frontend ).
Trade-offs
| Option | Wins when | Loses when |
|---|---|---|
| gRPC with Protocol Buffers | Internal service-to-service calls: typed contracts, small fast messages, streaming, deadlines | Browsers and third parties, ad hoc debugging with curl, human-readable payloads |
| REST with JSON | Public APIs, browsers, simple integrations, easy debugging | High-volume internal traffic where size, parsing cost and contracts matter |
| GraphQL | Client-facing aggregation across many services | Service-to-service calls, where its flexibility adds cost without benefit |
Common mistakes
- Reusing or renumbering field tags, which silently corrupts data between old and new versions.
- Making calls without deadlines, so a slow dependency ties up threads all the way up the chain.
- Exposing gRPC directly to browsers and fighting the tooling instead of using a gateway.
- Assuming binary means secure. Protobuf is an encoding, not encryption; use TLS.
Check yourself
-
What do the numbers in a protobuf message definition, like name = 2, mean?
Show answer
B. Field tags used to identify fields on the wire Tags, not values. They must stay stable, because the binary encoding uses them instead of names.
-
Why are protobuf messages usually smaller than JSON?
Show answer
B. Field names are replaced by small numeric tags and numbers use compact varints Binary tags and varints avoid repeating field names and digits as text.
-
A client wants a live stream of price updates after one subscription request. Which call type fits?
Show answer
B. Server streaming One request, then many responses from the server over the same stream.
-
What problem do propagated deadlines solve?
Show answer
B. Downstream services wasting work on requests the caller has already abandoned Each hop knows how much time is left and stops early once the deadline has passed.
Recap
- gRPC defines services and messages in Protocol Buffers and generates typed clients and servers.
- Binary encoding with field tags and varints makes messages small and fast to parse.
- On HTTP/2, calls can be unary, server streaming, client streaming or bidirectional.
- Deadlines propagate down the call chain so abandoned work stops early.
- Use gRPC inside your system and REST or GraphQL at the public edge.
Next up
- Crack the system design round learning path