gRPC

Try it: gRPC deadline budget across hops

Step through gateway, service, and leaf RPC hops. Each stage spends time on auth and serialization, then passes the remaining deadline downstream.

What actually happens in a gRPC call

Why gRPC was introduced

How to choose gRPC

Where gRPC belongs: REST at the edge, gRPC inside

The rule of thumb draws the line at the gateway. This is what the two sides of that line look like in a real deployment.

External clients

browsers, partners, mobile

→ REST / JSON →API / BFF edge

auth, rate limits, translation

→ gRPC / Protobuf →

User ServiceOrder ServiceInventory Service

Public and browser clients speak REST (or GraphQL) to the API or BFF edge (a backend-for-frontend layer that handles auth, rate limits, and translation). Inside the datacenter, services speak gRPC to each other: binary, fast, typed, and stream-friendly. gRPC fits inside because you control both clients and servers, schemas evolve with reserved fields, and latency and CPU matter. REST fits outside because it is curl-friendly, GETs are CDN-cacheable, JSON tooling is universal, and partners never have to install a protobuf toolchain.

External traffic (REST/HTTP) enters via web servers. Internal microservices communicate via gRPC: binary Protobuf over HTTP/2.

Protocol Buffers on the wire

The pattern above calls gRPC compact and typed, and both words come from Protocol Buffers. gRPC is not a brand-new wire protocol: it is HTTP/2 as the transport, Protobuf for serialization (turning objects into bytes), and .proto files as the contract. This section opens a message up and shows the bytes.

The same user record in JSON and in Protobuf

{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "roles": ["admin", "user"],
  "active": true
}

// Total: ~95 bytes on the wire
// Every key is a string: "id", "name", "email"
// Repeated in EVERY message
// Parser must scan character-by-character

message User {
  int32 id = 1;        // field number, not value
  string name = 2;
  string email = 3;
  repeated string roles = 4;
  bool active = 5;
}

// Total: ~31 bytes on the wire!
// No field names sent: just field numbers
// Varint encoding: small ints = 1 byte
// Parser reads tag → type → value (zero scanning)

Worked example: Protobuf bytes at internal QPS

Those per-message savings look tiny until you multiply them by internal call volume.

Performance benchmarks vs REST

The benchmark table puts the same comparison side by side and adds latency, throughput, and CPU, measured on workloads where serialization cost actually matters.

Repeated JSON field names consume bytes, and parsing text has a CPU cost. A binary schema can reduce both for suitable message shapes, while generated clients provide an explicit contract across languages. The size and CPU savings depend on payloads, compression, libraries, and hardware; benchmark representative traffic rather than assuming a universal speedup. REST APIs can also use schemas and generated clients, so type safety is not exclusive to gRPC.

The .proto file: schema, streaming modes, and safe evolution

Generated code catches many contract mistakes before deployment, but it does not remove distributed-systems failures. A method can time out after the server has committed a change, and an older client may interpret a newly optional field differently from a newer one. Test the compatibility of message shapes and business meaning separately. Reserve removed field numbers and names so old bytes cannot later acquire an unrelated interpretation.

Every number above depends on the .proto file, so here is a realistic one, what its five methods mean, and how to change it later without breaking anyone.

reserved 3, 8; // never reuse these numbers
reserved "old_field_name"; // document removed fields

Operating gRPC: load balancing, meshes, and browsers

A working .proto is only half the job. The long-lived HTTP/2 connections that make gRPC fast also change how traffic is spread across servers, how it is secured, and how a browser can reach it at all.

Deadlines, metadata, interceptors, and errors

A deadline limits how long a caller is willing to wait for the overall operation. If an incoming request has 300 milliseconds left and local work uses 80, a downstream call must fit inside the remaining budget with room to return the result. Propagate cancellation so timed-out requests stop consuming resources, but do not interpret cancellation as rollback: a completed database write or external side effect may already exist. Language runtimes differ in automatic propagation, so verify configuration. See gRPC deadline documentation for the precise contract.

With traffic reaching the right servers, the next concern is what travels alongside each call: a time budget, headers, middleware, and a status when something fails. Propagating timeouts and auth headers through middleware is what makes cascading latency fail fast instead of hanging.

Client sets deadline: 500ms
→ Service A receives: 480ms remaining
→ Service B receives: 420ms remaining
→ Service C receives: 350ms remaining
→ If exceeded: DEADLINE_EXCEEDED propagates back (fail fast!)

metadata.put("authorization", "Bearer token123")
metadata.put("x-request-id", "req-abc-456")
metadata.put("x-trace-id", "trace-789")

intercept(request, handler) {
  start = now()
  validateAuth(request.metadata)
  response = handler(request)
  recordMetric("latency", now() - start)
  return response
}

service Health {
  rpc Check(HealthCheckReq) returns (HealthCheckResp);
  rpc Watch(HealthCheckReq) returns (stream HealthCheckResp);
}

$ grpcurl -plaintext localhost:50051 list
  → userservice.UserService
  → grpc.health.v1.Health
 
$ grpcurl -plaintext localhost:50051 describe userservice.User
  → message User { int32 id = 1; string name = 2; }

Error model and status codes

A status such as UNAVAILABLE describes the observed failure, not proof that a write had no effect. Retry only operations whose semantics make repetition safe, and keep attempts inside a shared time and retry budget. If the application, proxy, and client library each retry three times independently, downstream attempts can multiply. Record attempts and final outcomes separately so a superficially good success rate does not conceal overload.

When a call fails, gRPC returns one of these structured codes in the trailers instead of REST's mix of HTTP codes plus ad hoc bodies. The retry-safe ones matter most for the failure timeline in the next section.

A status can also carry typed details, so the client learns which field was wrong rather than parsing a free-text message:

status {
  code: INVALID_ARGUMENT
  message: "Email format invalid"
  details: [BadRequest { field_violations: [
    { field: "email", description: "Must contain @" }
  ] }]
}

Failure timeline, limits, and trade-offs

T0  Checkout → Inventory (no deadline) → Inventory slow under load
T1  Checkout threads block; client SDK retries UNAVAILABLE ×3
T2  Mesh retry policy also retries → 9× attempts per user click
T3  Inventory queue deepens; DEADLINE never fires → cascade to Cart
T4  Fix: propagate deadline, one retry budget, retry only idempotent RPCs

gRPC deadlines and contract evolution

Payload and bandwidth budget

How to choose REST, gRPC, or GraphQL

Choose the API style by client type, payload shape, caching needs, and operational maturity.

Wrap-up