Part 2 · 2 chapters · ~12 min

gRPC and Protobuf

Schema-first services in .proto files, field numbers and wire compatibility, Protobuf encoding, unary and streaming RPCs, deadlines and cancellation, status codes and rich errors, load balancing long-lived connections, gRPC-Web and Connect, and buf for linting and breaking-change detection.

Contracts on the wire

code

syntax = "proto3";
package bank.ledger.v1;

service LedgerService {
  rpc PostEntry(PostEntryRequest) returns (PostEntryResponse);
  rpc WatchAccount(WatchAccountRequest) returns (stream BalanceChanged);     // server streaming
}
message Money { int64 amount_minor = 1; string currency = 2; }
message Posting { string account_id = 1; Money amount = 2; }
message PostEntryRequest {
  string idempotency_key = 1;
  repeated Posting postings = 2;
  reserved 3;                       // removed field: number never reused
  map<string, string> metadata = 4;
}
message PostEntryResponse { string entry_id = 1; }

gRPC AND PROTOBUF

a schema-first contract, binary encoding and HTTP/2 streams

swipe the figure sideways, or tap expand for full screen

1/5

the schema

A .proto file defines messages (with numbered fields) and services (RPC methods). It is the contract; code is generated for each language.

messages and services in .protocode generated per language

Errors, deadlines and tooling

topic	practice
errors	gRPC status codes (INVALID_ARGUMENT, NOT_FOUND, ALREADY_EXISTS, FAILED_PRECONDITION, UNAVAILABLE) plus google.rpc error details for field violations
deadlines	every call sets one; servers check `ctx.Done()`; deadlines shrink as they propagate
retries	only on UNAVAILABLE and for idempotent methods; configure in the service config or mesh, once
load balancing	HTTP/2 connections are long-lived: use client-side balancing or a mesh, not plain L4
tooling	`buf lint` for style, `buf breaking` in CI to block incompatible changes, a schema registry (Buf Schema Registry)