gRPC Design Primer

Why gRPC

gRPC replaces hand-rolled JSON endpoints with strongly-typed contracts. HTTP/2 multiplexing, binary framing, and native streaming eliminate the overhead of REST round-trips. A single.protofile becomes the source of truth for every client and server in your stack.

Service definition

Define messages and RPCs in protobuf. Unary calls handle request-response. Server streaming pushes a sequence of replies over a single connection. Client streaming collects input before the server responds. Bidirectional streaming opens a persistent channel for real-time protocols.

service LicenseService {
  rpc Validate(ValidateReq) returns (ValidateResp);
  rpc WatchRevocations(WatchReq) returns (stream RevokeEvent);
}

Contract-first workflow

Write the proto first. Generate server stubs and client SDKs with protoc. Never hand-write serialization. Backward compatibility is enforced by field numbering — add new fields, deprecate old ones, never reuse a number. Breaking changes require a new major API version surfaced as a separate service.

Interceptors & deadlines

Middleware lives in interceptors: auth, logging, rate limiting, tracing. Every RPC must carry a deadline. Without one, a hung downstream service consumes resources indefinitely. Set context deadlines at the outermost caller and propagate them through every hop.