Foundations · Lesson 08

Remote procedure calls (RPC)

RPC is a style of API with one goal: make calling a function on another machine feel exactly like calling one in your own code — user = getUser(42), no URLs in sight. It's a powerful illusion. Knowing where the illusion leaks is what separates a working system from a fragile one.

The illusion: a local call that isn't

In ordinary code you call add(2, 3) and get 5. RPC lets you write what looks like that, but the function runs on a server somewhere else. The machinery that sells the illusion is a pair of stubs — small auto-generated shims on each side:

Marshalling (a.k.a. serialization) is turning in-memory values into a byte stream the network can carry; unmarshalling rebuilds them on the other side. The caller writes a normal-looking function call and never touches sockets — that's the whole appeal.

Where the illusion leaks

A local function call is fast, always returns, and can't half-happen. A remote one can't promise any of that. These are the leaks every RPC system must face:

gRPC: the modern, fast RPC

The most common RPC framework today is gRPC. Its two big ideas:

• Protocol Buffers (protobuf) — you define your messages and methods once in a .proto schema; tooling generates the stubs in many languages and serializes to a compact binary format (smaller and faster to parse than JSON text).
• Runs over HTTP/2 — so it inherits multiplexed streams (Lesson 02), enabling efficient streaming RPCs, not just one-shot request/response.

// a tiny .proto contract — the source of truth for both sides
service Users {
  rpc GetUser (GetUserRequest) returns (User);
}
message GetUserRequest { int64 id = 1; }
message User { int64 id = 1; string name = 2; }

Under the hood: how it actually works

Two mechanisms make gRPC work: protobuf wire encoding (how arguments become bytes) and HTTP/2 framing (how those bytes travel and return).

Protobuf wire encoding

Protobuf uses a compact binary format. Every field in a message is identified by a small integer field tag (not by name — that's why field numbers must never change). Each encoded value is a tag-wire-type varint followed by the value. For the proto definition:

message GetUserRequest { int64 id = 1; }
// Encoding GetUserRequest { id: 42 }:
//   field 1, wire type 0 (varint) → tag byte = (1 << 3) | 0 = 0x08
//   value 42 encoded as varint → 0x2A
//   total: 2 bytes  [0x08, 0x2A]

message User { int64 id = 1; string name = 2; }
// Encoding User { id: 42, name: "Ada" }:
//   field 1 varint 42   → 0x08 0x2A
//   field 2 length-delimited "Ada" → tag = (2<<3)|2 = 0x12,
//                                     length = 0x03, bytes = 0x41 0x64 0x61
//   total: 7 bytes vs ~22 bytes for {"id":42,"name":"Ada"} in JSON

The field name is never in the wire format — only the number. This makes the binary compact and fast to parse (no string comparisons), but it means a schema (.proto file) is required to decode arbitrary messages.

How a gRPC call maps onto HTTP/2 frames

A unary gRPC call (GetUser) runs entirely inside a single HTTP/2 stream. Here is the exact frame sequence:

The gRPC-specific layer sits inside HTTP/2 DATA frames: a 5-byte framing prefix ([1-byte compressed flag][4-byte message length]) wraps each protobuf message. The grpc-status code arrives in HTTP/2 trailers (headers sent after the body), not in the initial response headers — this is why the client must read the full stream to know if the call succeeded.

How to debug & inspect it

gRPC's binary format can't be read with plain curl, but grpcurl (a curl-equivalent for gRPC) makes it easy — especially with server reflection enabled.

Debug checklist:

1. Enable server reflection in development — it lets grpcurl list and describe work without needing the .proto file.
2. Read grpc-status in trailers first — it's the equivalent of the HTTP status code for gRPC calls.
3. Use grpcurl -v to see raw headers and trailers including grpc-message (human-readable error detail).
4. If you can't connect at all, check that the server is listening on the correct port with grpc+http2 (not plain HTTP/1.1).
5. For "works locally, fails in prod" — check TLS: production gRPC servers require a valid cert; use grpcurl without -plaintext for TLS.

Sources & further reading

• gRPC — Introduction · Protocol Buffers
• Fallacies of distributed computing
• Birrell & Nelson — Implementing Remote Procedure Calls (1984)
• grpcurl — command-line tool for gRPC services
• gRPC status codes reference
• Protocol Buffers — wire format encoding