gRPC basics: protobuf contracts, streaming and where it fits

What it is

The gRPC introduction (cited) describes the model: a service and its methods are defined in a .proto file, protoc generates client stubs and server interfaces per language, and a client calls a method on a remote server as if it were a local object; Protocol Buffers serve by default as both the Interface Definition Language and the message format. The core-concepts page (cited) lists four kinds of method: unary, server-streaming, client-streaming and bidirectional streaming. Every call can carry a deadline, after which it fails with DEADLINE_EXCEEDED; either side can cancel; metadata travels as key-value pairs alongside the call; and calls end with a status from a fixed set (OK, NOT_FOUND, UNAVAILABLE and others). The FAQ (cited) states that gRPC follows HTTP semantics over HTTP/2 but explicitly allows full-duplex streaming, uses static paths for dispatch, and formalises its own error set instead of HTTP status codes.

Why it matters

Generated, typed clients in many languages plus streaming and deadlines that propagate through call chains remove a class of hand-written client code and timeout bugs. The price is binary payloads, HTTP/2 end to end, and tooling that plain curl does not have.

How to apply

• Use gRPC for internal service-to-service calls where both ends are generated from the same .proto files, for streams (telemetry, subscriptions, large result sets) and for mobile clients, where the FAQ cites bandwidth and connection savings.
• Set a deadline on every client call and pass the remaining deadline to downstream calls; make servers check cancellation in long loops.
• Map errors to the standard status codes and put specifics in the message or error details; do not invent codes.
• Keep .proto files in one package with a compatibility check on change; field numbers are the contract.
• For browsers, use gRPC-Web, which the FAQ describes as generally available; for public partner APIs, offer JSON over HTTP instead of, or transcoded from, the gRPC definitions.
• Confirm that every load balancer and proxy in the path carries HTTP/2 through to the backend; gRPC needs it end to end.

Pitfalls

Assuming gRPC is automatically fast: serialisation is cheap, but a chatty design stays chatty. Long-lived streams that pin a connection to one backend and defeat load balancing. Retrying INVALID_ARGUMENT like UNAVAILABLE because the client does not distinguish retryable codes. Exposing gRPC to integrators who only have HTTP tooling.