gRPC and Protobuf Contracts

syntax = "proto3";

message Order {
  string order_id    = 1;  // numbers 1-15 encode in a single tag byte
  int64  total_cents = 2;
  repeated LineItem items = 5;

  reserved 3, 4;         // numbers of deleted fields — never reused
  reserved "legacy_note"; // so the name cannot come back either
}

Protobuf encodes each field as a tag followed by a value, where the tag is (field_number << 3) | wire_type. That makes the field number the field's identity on the wire; the name exists only for generated code and the proto3-JSON mapping. Several production rules fall straight out of it.

Renumbering a field is the classic outage. The writer tags bytes as field 7; readers compiled against the new file expect field 7 to be absent and decode the value into whatever now owns that slot — or skip it entirely. Never renumber a deployed field. Deleting without reserved is a slower time bomb: months later someone adds a new field that lands on the vacated number, and old payloads decode garbage into it. reserved blocks both the numbers and the name from reuse.

Renaming is the subtle case: wire-compatible, because the number still identifies the field, but source-breaking and JSON-breaking — generated members rename, and any system speaking proto3-JSON sees the key change (order_id to orderId). Rename during a planned client release, never as a cosmetic commit.

That last row deserves emphasis: proto3 scalars have no presence by default, so a server cannot tell unset from set-to-zero. Money should be optional or a dedicated message — absent must never mean $0.00. Adding optional later changes what old code observes, so decide presence per field at design time.

This is also where the codegen payoff lives: one order.proto compiles into typed clients and servers across many languages — Go structs and clients, Java classes, TypeScript types — from a single contract. Regeneration is the workflow (buf generate in CI), and hand-editing generated code is never the fix.

Interviews love the phrasing "how do you evolve a proto in production?" Answer with: new numbers only, reserved on every deletion, widen rather than narrow, review value ranges, and run buf breaking against the last release in CI — the exact analogue of the spec diff in Contract-First with OpenAPI, which we will contrast with client-driven flexibility in GraphQL Trade-offs.

The JSON bridge deserves its own warning, because gateways, logs, and browser tools speak proto3-JSON: names map to camelCase, int64 serializes as a string (JavaScript numbers lose precision past 2^53), and enums become their names. Any system that round-trips through JSON must hold those rules too — the classic incident is a JSON consumer parsing a 64-bit id as a number and corrupting it silently. Keep identifiers as strings at every JSON boundary and state the mapping in the contract docs.

service OrderService {
  rpc GetOrder (GetOrderRequest) returns (Order);             // unary
  rpc WatchOrder (WatchRequest) returns (stream OrderEvent);  // server stream
  rpc ImportOrders (stream Order) returns (ImportSummary);    // client stream
  rpc Negotiate (stream Msg) returns (stream Msg);            // bidirectional
}

gRPC runs over HTTP/2, and two properties of that transport shape every design decision here. A single TCP connection multiplexes many concurrent RPCs without HTTP/1 head-of-line stalls, and per-stream flow control gives backpressure that reaches the producer: when a consumer stops reading, the sender's window fills and it blocks instead of buffering without limit. That is the property a naive socket-based protocol never gives you.

Choose the shape by who talks first and who finishes last:

Default to unary. Streaming complicates retries, load balancing, and observability (one RPC carries thousands of messages — count both), and a stream that fails after 10,000 messages leaves partial side effects that a single atomic outcome would not.

Three mechanics separate senior answers from basic ones. First, deadlines: the caller sets one, gRPC ships it as a grpc-timeout header, and the server must propagate it into its own downstream calls. Skip that and calls hang until thread pools drain — DEADLINE_EXCEEDED should be a designed outcome, not a surprise. Second, status codes: gRPC uses a canonical enum of fifteen values (NOT_FOUND, FAILED_PRECONDITION, RESOURCE_EXHAUSTED, ABORTED, UNAVAILABLE, DEADLINE_EXCEEDED...) instead of HTTP's loose collection, and clients switch on them — so choose deliberately. ABORTED tells a transactional client to retry after backoff; FAILED_PRECONDITION tells it not to bother; UNAVAILABLE is the signal a retry policy keys on. Third, retries live in the gRPC service config with retryableStatusCodes, capped by a retry budget — and only methods that are idempotent may be listed, the same rule that governs retries in REST Design and Versioning.

Beware one class of bug that only appears under streaming: flow control prevents unbounded buffering in the network layer, but a server that reads eagerly and hands work to an unbounded queue has simply moved the memory problem. Backpressure must propagate through your own code, not just the transport.

Metadata runs alongside every shape: gRPC carries custom headers before the message and trailers after it, so tracing context, tenant ids, and auth claims travel without polluting the message schema — but they are HTTP/2 headers, which means size limits apply and secrets should stay short-lived. Observability needs the pairing too: one RPC can carry ten thousand stream messages, so record both the RPC count and the message count, and treat a healthy RPC whose message rate has stalled as the failure it is.

Streams also complicate rebalancing. A unary call round-robins cleanly across resolved backends, while a long-lived stream opened before a new instance joined keeps its messages on the old one; rebalancing means closing and re-establishing streams. Design every consumer to reconnect with backoff and to resume from a cursor rather than assuming continuity — a subscription that cannot reconnect is a subscription that will eventually stop receiving updates while reporting no errors.

Unary gRPC is the default for internal service calls: compact binary payloads, generated typed clients in every language, deadlines as a first-class concept, and streams when you need them. The boundary question is where it stops working, and the answers are contractual, not religious.

Browsers. Web APIs expose neither HTTP/2 trailers — where gRPC places grpc-status — nor the flow-control surface gRPC-Web requires, so a browser cannot speak native gRPC. The options: gRPC-Web, where the client speaks a trimmed protocol and a proxy such as Envoy translates to full gRPC behind it; or the Connect protocol (connect-es and friends), which runs over ordinary fetch with JSON or protobuf and typically needs no sidecar. Plenty of teams skip all of it and serve REST/JSON to the web tier — a defensible answer, not a shortcut.

Public and mobile clients. gRPC works over hostile networks, but debugging binary frames with curl gets you nothing, middlebox behavior around HTTP/2 varies, and partner developers expect JSON they can read. The standard architecture keeps directions separate: east-west traffic inside the mesh is gRPC; north-south traffic at the edge is REST/JSON (or GraphQL), translated by grpc-gateway (HTTP reverse proxy generated from proto annotations), Envoy's HTTP/2-to-gRPC transcoding, or a hand-written facade owned by a backend-for-frontend.

Load balancing. This is the gotcha interviewers enjoy. A layer-4 balancer sees one connection; with HTTP/2, all streams land on one backend until that connection closes. Fixes: client-side round_robin over a resolvable endpoint list, an L7 balancer or mesh data plane that opens fresh upstream connections per request, or proxy-less discovery via xDS. Whatever you pick, choose it deliberately — the default quietly defeats your carefully built fleet.

Evolution tooling. buf lint enforces naming and package rules; buf breaking --against compares against the last release and fails on incompatible changes — mechanically the same guardrail as the OpenAPI diff in Contract-First with OpenAPI, applied to binary compatibility instead of HTTP shapes.

Pick gRPC when calls are internal, chatty, latency-sensitive, multi-language, and deadline-aware. Skip it for browser-facing reads (no CDN caching of POST bodies), file downloads over flaky links, and partners who just want JSON. Once clients get query-shaped flexibility instead of fixed endpoints, the trade-off set changes again — that is GraphQL Trade-offs.

Contract distribution is the operational half people forget. Generated code stays in step only if every language pulls from one registry: publish .proto files to a schema registry (Buf Schema Registry, a versioned repository, or an artifact store), version them with semver, and fail CI when a service's generated stubs lag the published schema. Without that, each team vendors its own copy and the contract layer rebuilds the monolith problem in miniature.

Security at the edge differs from REST in mechanics only: tokens and tracing arrive as gRPC metadata, the gateway validates them and forwards trusted claims downstream, and mesh traffic is typically mTLS. The gateway's job remains the uniform edge policy from any API tier, translated into the gRPC status model — UNAUTHENTICATED for a missing or expired token, PERMISSION_DENIED for a valid identity lacking scope — each carrying a message a client can act on.

Testing gets cheaper with interceptors: one middleware layer records deadlines, retries, and status codes for every call, which is where your configured retry and deadline discipline actually becomes visible. Pairing buf breaking in CI with interceptor-based metrics shows an interviewer two things at once — the contract is enforced before merge, and the runtime is observed after deploy.

One boundary worth naming: teams that want a single protocol from browser to backend often standardize on Connect, which speaks protobuf or JSON over ordinary HTTP and runs in browsers without a sidecar, while still generating typed clients from the same .proto. It trades a few gRPC-specific mechanics for one toolchain across every surface — a trade-off to state explicitly rather than a default to assume.