gRPC & Protobuf

The problem: services that talk a lot, and drift apart#

Picture a backend split into hundreds of small services. A checkout service calls a pricing service, which calls an inventory service, which calls three more. They talk constantly, and the calls are on the hot path, so every millisecond and every wasted byte is multiplied by a very large number of requests.

The common way to wire this up is REST over HTTP with JSON — the same style covered in the HTTP topic (/http/sim). It's a fine default, and for a public API it's often the right one. But inside a busy backend it starts to chafe in three specific ways.

• No enforced contract. The pricing service expects a field called `unit_price`. A caller sends `unitPrice`. Nothing checks this until it fails in production, because JSON has no shared, machine-checked definition of what a valid request looks like.
• JSON is bulky and slow. Every request re-sends the field names as text ("customer_id", "quantity") and every number as ASCII digits. The receiver then parses that text back into real values. Across millions of internal calls, that's a lot of bytes on the wire and CPU spent parsing.
• No real streaming. A call that returns a large or open-ended result — a live feed of price changes, a big export — has to be faked with polling or long-held connections, because plain request/response gives you exactly one response per request.

Google hit this at scale long before most: since around 2001 it ran an internal framework called Stubby to connect its services. gRPC, open-sourced in 2015, is the public rebuild of that idea. So the design goal is concrete — fast, typed, streaming calls between services you control — and every piece below is there to serve it.

Start with a contract, generate the code#

The first move is to stop describing the service in prose and a wiki page, and write it down in one file that both sides read. That file is written in an IDL — an interface definition language, a small language whose only job is to describe an interface. gRPC's IDL is Protocol Buffers, usually shortened to Protobuf.

Here's a slimmed-down version of a real one: the API that etcd — a distributed key-value store used by Kubernetes — exposes to its clients. It has a couple of methods and the messages they exchange.

service KV {
  rpc Put   (PutRequest)   returns (PutResponse);
  rpc Range (RangeRequest) returns (RangeResponse);
}

message PutRequest {
  bytes key   = 1;   // field number 1
  bytes value = 2;   // field number 2
}

Two things are being declared. A service is the set of methods a server offers — here `Put` to store a key and `Range` to read keys back. Each method is marked `rpc`, which stands for remote procedure call: a call to another machine written to look like an ordinary local function. That's the RPC in gRPC. A message is the shape of a request or response, a list of typed fields. And notice each field has a small number next to it. That number, not the name, is what actually goes on the wire — hold onto that, it's the key to the next section.

Now the payoff. You run a compiler over the `.proto` file: `protoc`, plus a plugin for your language. It reads the contract and generates code on both sides. For the client it generates a stub: an object with a real `Put(...)` method you call like any local function, which underneath serializes your message, sends it, and hands you back the reply. For the server it generates a skeleton: an interface you implement with the actual logic, wired to receive and decode incoming calls. You write neither the networking nor the parsing.

Protobuf on the wire: numbers, not names#

Now to why the bytes are small. Serializing that `PutRequest` as JSON would look like `{"key":"foo","value":"bar"}` — 27 characters, and the field names "key" and "value" are sent in full on every single request. Protobuf's insight is that both sides already have the contract, so the field names are redundant. It sends the field number instead.

Each field on the wire is a tiny tag followed by the value. The tag is a single number that packs two things: the field's number (which field is this?) and its wire type (how is the value encoded — is it an integer, or a length-prefixed chunk of bytes?). The receiver reads the tag, learns "this is field 1, and it's a length-delimited value," looks up field 1 in its copy of the contract, and knows it's the `key`. The name never travelled.

Integers get the same frugal treatment through varint encoding — "variable-length integer." Instead of always spending a fixed 4 or 8 bytes on a number, a varint uses one byte for small numbers and adds bytes only as the number grows. It works by taking 7 bits of the number per byte and using the 8th bit as a flag that means "there's another byte coming." So a small value like `5` fits in one byte; you only pay for the size you actually use.

There's a second, quieter payoff to identifying fields by number: it's what lets the contract change safely over time. A new field just gets a new, unused number. An old client that has never heard of that number reads the message, hits a tag it doesn't recognize, and simply skips it — no crash, no coordinated deploy. That property is called schema evolution, and it's the deeper reason services can be updated one at a time.

Riding HTTP/2: one connection, four call shapes#

A compact message still needs a way across the network, and gRPC doesn't invent one — it runs on HTTP/2, the transport covered in the HTTP/2 & HTTP/3 topic (/http2-3/sim). That choice matters for one reason above all: HTTP/2 multiplexes. Many independent calls share a single connection and travel at the same time, interleaved as separate streams, instead of each waiting for the last to finish. For a service making thousands of concurrent calls, opening one connection instead of thousands is a large saving on its own.

The connection itself is normally wrapped in TLS, so the traffic is encrypted and each side can verify who it's talking to — the handshake from the TLS topic (/tls/sim). In gRPC terms this secured connection is called a channel, and your stubs make their calls over it.

Because HTTP/2 streams can stay open and carry many messages, a gRPC method isn't limited to one-request-one-response. It can take one of four shapes, chosen in the `.proto` with the `stream` keyword. The etcd contract from earlier shows one: `Put` is a plain single call. Its `Watch` method (not shown in that snippet) is a long-lived two-way stream that pushes changes as they happen.

Unary is the ordinary function-call shape and covers most methods. The streaming shapes are what plain REST can only fake — and they cost nothing extra to set up, because they're just an HTTP/2 stream left open with more messages flowing through it.

The call itself: deadlines, cancellation, and status#

A remote call can hang — the far service is slow, or wedged, or the network dropped. gRPC bakes the answer into every call: a deadline. When you make a call you say "I'll wait at most 300 milliseconds." If the reply hasn't come by then, the call is abandoned and returns an error, and the client stops waiting.

The clever part is that the deadline travels with the call. Say the checkout service sets a 300 ms deadline on a call to pricing, and pricing has to call inventory to answer. gRPC forwards the remaining time — if 100 ms have already gone, inventory is told it has 200 ms left. It's sent as a remaining duration rather than a wall-clock time, so the two machines' clocks don't have to agree. When the deadline passes, every call in that chain is cancelled together, so no service keeps grinding on work whose answer nobody is waiting for anymore. That's deadline propagation, and it's how gRPC stops one slow service from tying up an entire call tree.

Every call ends with a status code: a small number saying how it went. `0` is OK. The rest name the failure in a way both sides agree on, so a caller can react to the kind of error, not parse a message. The common ones are worth knowing by name.

These codes carry real weight in practice. `UNAVAILABLE` tells a client the call is worth retrying (the request may never have landed), while `INVALID_ARGUMENT` says the opposite — retrying the same bad request just fails again. Getting retry logic right hangs on reading these codes correctly.