Architectural Styles · Lesson 05

The gRPC framework

gRPC treats a remote call like a local function call — but compiles the contract into type-safe client and server code, then sends everything as compact binary over HTTP/2. The result is a style purpose-built for internal service meshes that need speed and strict contracts.

RPC — the original idea

Remote Procedure Call (RPC) is the idea of calling a function on a different machine as if it were local. Your code writes payments.charge(amount, card); the network layer transparently serialises the arguments, sends them to the payments service, executes the function there, and returns the result. The network is meant to be invisible.

The concept dates to the 1970s. Early implementations (CORBA, XML-RPC, SOAP) were famously complex. gRPC, released by Google in 2016, took the core idea and rebuilt it with modern primitives: Protocol Buffers for the contract, HTTP/2 for the transport, and code generation for every popular language.

Protocol Buffers — the contract language

Everything in gRPC starts with a .proto file. It defines messages (typed data structures, like database rows with field numbers) and services (groups of RPC methods). The proto compiler (protoc) reads the file and generates client stubs and server skeletons in your language of choice.

// user_service.proto
syntax = "proto3";

// Message definitions
message GetUserRequest {
  string user_id = 1;
}

message User {
  string id    = 1;
  string name  = 2;
  string email = 3;
}

// Service definition
service UserService {
  rpc GetUser (GetUserRequest) returns (User);
  rpc ListUsers (ListUsersRequest) returns (stream User);
}

The field numbers (1, 2, 3) are how protobuf encodes data on the wire — not the field names. This is why you can rename a field safely; you must never reuse a field number.

HTTP/2 — the transport advantage

gRPC runs over HTTP/2, not HTTP/1.1. The key difference: HTTP/2 supports multiplexing — many concurrent request/response streams share one TCP connection without blocking each other (no head-of-line blocking). Combined with binary framing and header compression (HPACK), this gives gRPC substantially lower latency and higher throughput than HTTP/1.1 REST for high-frequency internal traffic.

The four streaming modes

RPC doesn't have to be a single call-and-response. gRPC's streaming modes map to different communication patterns:

Code generation — strong typing across languages

The proto file is the single source of truth. Run protoc against it and you get fully typed client stubs and server interfaces in Go, Java, Python, TypeScript, C++, and more. If the server adds a required field to a message, the generated client code won't compile until it provides that field. This catches whole classes of integration bugs at compile time rather than production time.

# Generate Go code from the proto file
protoc --go_out=. --go-grpc_out=. user_service.proto

# Generated client usage (Go)
conn, _ := grpc.Dial("user-svc:50051", grpc.WithTransportCredentials(...))
client  := pb.NewUserServiceClient(conn)
user, _ := client.GetUser(ctx, &pb.GetUserRequest{UserId: "42"})
fmt.Println(user.Name)  // type-checked at compile time

Browser limitations — where grpc-web fits in

Browsers cannot speak raw HTTP/2 framing directly to a gRPC server. This is a hard constraint — the browser's Fetch/XHR APIs don't expose the low-level HTTP/2 stream primitives that gRPC requires. The solution is grpc-web: a lightweight adaptation layer. The browser talks to an envoy proxy (or similar) over HTTP/1.1 or HTTP/2 using the grpc-web wire format; the proxy translates to native gRPC on the back-end.

This adds operational complexity (the proxy is another moving part). For this reason, many teams use REST or GraphQL at the browser edge and gRPC only for internal service-to-service calls.

Under the hood: how a gRPC call travels on the wire

A gRPC call is not magic — it is a precisely structured sequence of HTTP/2 frames carrying a Protobuf-encoded message, with the gRPC status carried back in HTTP/2 trailers rather than headers. Here is what actually happens, byte by byte.

Step 1 — Protobuf encoding

The request message is serialised into Protobuf's binary tag-length-value (TLV) format. Each field is encoded as a varint combining its field number (from the .proto file) and a wire type. A string field (user_id = "42") with field number 1 encodes like this:

// GetUserRequest { user_id = "42" }
// Field 1, wire type 2 (length-delimited) → tag byte = (1 << 3) | 2 = 0x0a
// Value: 0x0a 0x02 0x34 0x32
//         ^tag ^len '4'  '2'
encoded bytes (hex): 0a 02 34 32   (4 bytes total)

Contrast with JSON {"user_id":"42"} at 16 bytes. For deeply nested messages with many fields, the ratio improves dramatically — protobuf routinely produces 3–10× smaller payloads than JSON for the same data.

Step 2 — gRPC message framing (the 5-byte prefix)

Before the Protobuf bytes are handed to HTTP/2, gRPC wraps them in a 5-byte length-prefix frame:

// gRPC message frame layout
Byte 0:     Compression flag (0 = not compressed, 1 = compressed)
Bytes 1–4:  Big-endian uint32 — length of the Protobuf message that follows
Bytes 5…N:  The Protobuf-encoded message bytes

// For GetUserRequest { user_id="42" } (4 bytes of protobuf):
00  00 00 00 04  0a 02 34 32
^   ^-------^   ^---------^
flag  length=4   protobuf payload

This framing allows multiple messages to be sent on the same HTTP/2 stream (as in streaming RPCs) — the receiver reads 5 bytes, parses the length, reads exactly that many bytes as one message, then reads the next 5-byte header, and so on. There is no delimiter character to scan for, just a length to count.

Step 3 — HTTP/2 HEADERS frame

The gRPC client opens an HTTP/2 stream and sends a HEADERS frame with these pseudo-headers and custom headers:

// HTTP/2 HEADERS frame for a unary gRPC call
:method  = POST
:scheme  = https
:path    = /user.UserService/GetUser    ← always /{package}.{Service}/{Method}
:authority = user-svc:50051
content-type   = application/grpc      ← must be present; +proto or +json variant
te             = trailers               ← mandatory; tells HTTP/2 proxies to preserve trailers
grpc-timeout   = 500m                  ← optional; 500 milliseconds deadline
authorization  = Bearer <token>        ← standard auth metadata

Step 4 — HTTP/2 DATA frame

Immediately after (or in the same write), the client sends a DATA frame carrying the 5-byte-prefixed Protobuf message. For a unary call the DATA frame has the END_STREAM flag set — no more data from the client on this stream:

// HTTP/2 DATA frame carrying the gRPC message
Stream ID:   3  (odd = client-initiated; each new call gets the next odd number)
Flags:       END_STREAM=1 (unary: client is done after one message)
Payload:     00 00 00 00 04 0a 02 34 32   (framing + protobuf)

Step 5 — server response HEADERS + DATA

The server sends its response HEADERS frame (with HTTP status 200 — note: gRPC always sends HTTP 200 even for errors; the real status is in trailers), followed by a DATA frame with the response message:

// Server response HEADERS frame
:status         = 200
content-type    = application/grpc+proto

// Server response DATA frame — the User message serialised
00 00 00 00 0c <protobuf bytes for User{id="42",name="Ada",email="..."}>

Step 6 — gRPC status in HTTP/2 TRAILERS

After the DATA frame, the server sends an HTTP/2 HEADERS frame with the END_STREAM flag — this is the trailers frame. It carries the definitive gRPC outcome:

// Trailers frame (HEADERS with END_STREAM set)
grpc-status   = 0       ← 0 = OK; non-zero = error
grpc-message  =         ← empty on success; URL-percent-encoded error description on failure

// Example error trailer — user not found
grpc-status   = 5       ← NOT_FOUND
grpc-message  = user%2042%20does%20not%20exist

This trailer-based status is why you cannot use a plain HTTP proxy for gRPC: the proxy must support and forward HTTP/2 trailers. It is also why curl --http2 alone won't work for gRPC — the 5-byte framing and trailer convention sit on top of HTTP/2, not inside it.

The four call types — what changes on the wire

The common gRPC status codes

Why a browser needs grpc-web — the framing constraint

Browsers expose HTTP as a high-level fetch/XHR API and deliberately hide the HTTP/2 framing layer. JavaScript cannot set HTTP/2 trailer frames, cannot read them, and cannot control the stream-level END_STREAM flag. gRPC's entire status model depends on trailers. The grpc-web protocol works around this by mapping trailers into the body of a regular HTTP response, framed with a special 5-byte prefix byte (the high bit of the compression flag set to 1). An Envoy proxy on the server side unpacks the grpc-web frames into real gRPC over HTTP/2 toward the upstream service.

How to debug & inspect it

gRPC's binary encoding means you cannot casually curl it — but with the right tools you can inspect calls as easily as REST.

grpcurl — the curl for gRPC

Reading the raw frames with Wireshark / tcpdump

Symptom → cause → fix

Debug checklist:

1. Confirm server reflection is enabled (grpcurl list should return your service name).
2. Use grpcurl describe to verify the method signature matches your client code.
3. Check the grpc-status in the trailing metadata — it is always there, not in HTTP status.
4. Look at the grpc-message trailer — it often contains a human-readable error description.
5. For browser-to-service failures, confirm the Envoy proxy has the grpc_web filter and is not stripping te: trailers.
6. Enable gRPC access logging on the server to see per-method latency, error rate, and message sizes.

syntax = "proto3";

message Order {
  string id          = 1;
  string customer_id = 2;
  double total       = 3;
  string status      = 4;
}

message GetOrderRequest       { string order_id    = 1; }
message ListOrdersRequest     { string customer_id = 1; }
message CreateOrderRequest    { string customer_id = 1; double total = 2; }

service OrderService {
  rpc GetOrder    (GetOrderRequest)    returns (Order);
  rpc ListOrders  (ListOrdersRequest)  returns (stream Order);
  rpc CreateOrder (CreateOrderRequest) returns (Order);
}

Sources & further reading

• grpc.io — Introduction to gRPC
• protobuf.dev — Protocol Buffers overview
• grpc.io — gRPC-Web
• MDN — HTTP/2
• grpcurl — command-line tool for gRPC servers
• gRPC over HTTP2 — wire protocol specification
• gRPC status codes reference