gRPC Quick Reference

Analogy categoryAnalogies

RPC Types and .proto Essentials at a Glance

Every gRPC service is defined in a .proto file using the proto3 syntax by default, declaring message types with numbered fields and a service block listing its RPC methods; the four RPC shapes are distinguished purely by where the stream keyword appears in the method signature, none for unary, on the response for server-streaming, on the request for client-streaming, and on both for bidirectional streaming. Field numbers 1 through 15 use a single byte in the wire encoding and should be reserved for the most frequently set fields, since they're the cheapest to encode, while field numbers above 15 cost an extra byte, a detail worth knowing when designing high-throughput message schemas.

🏏

Cricket analogy: Reserving field numbers 1-15 for common fields is like batting your strongest, most reliable players at the top of the order where they'll face the most deliveries, maximizing value from the most-used slots.

protobuf

syntax = "proto3";
package order;

service OrderService {
  rpc GetOrder (OrderRequest) returns (Order);                     // unary
  rpc ListOrders (ListRequest) returns (stream Order);              // server-streaming
  rpc UploadReceipts (stream Receipt) returns (UploadSummary);      // client-streaming
  rpc Chat (stream ChatMessage) returns (stream ChatMessage);       // bidirectional
}

message OrderRequest {
  string id = 1;
}

message Order {
  string id = 1;
  string status = 2;
  reserved 3, 4;        // previously removed fields, never reuse
  reserved "legacy_sku";
}

Status Codes and CLI Tooling Cheat Sheet

The gRPC status code set is small and standardized, so knowing the common ones cold saves debugging time: OK (0) for success, CANCELLED (1) when the caller cancelled the call, INVALID_ARGUMENT (3) for malformed requests, DEADLINE_EXCEEDED (4) when a call's timeout expired before completion, NOT_FOUND (5), ALREADY_EXISTS (6), PERMISSION_DENIED (7) for authorization failures, RESOURCE_EXHAUSTED (8) for rate limiting or quota, UNAUTHENTICATED (16) for missing/invalid credentials, and UNAVAILABLE (14) for transient failures that are typically safe to retry. On the tooling side, grpcurl -plaintext host:port list enumerates services via reflection, grpcurl -plaintext -d '{"id":"1"}' host:port order.OrderService/GetOrder invokes a specific method, and protoc --go_out=. --go-grpc_out=. file.proto is the standard Go code-generation invocation.

🏏

Cricket analogy: DEADLINE_EXCEEDED mapping to a timed-out call is like a bowler's over being called dead after the time allotted for an innings expires before all overs are bowled, a clear, rule-based cutoff.

Quick command reference: grpcurl -plaintext host:port list — enumerate services (needs reflection enabled); grpcurl -plaintext host:port describe order.OrderService — show method signatures; grpcurl -plaintext -d '{...}' host:port order.OrderService/Method — invoke an RPC; protoc --go_out=. --go-grpc_out=. order.proto — generate Go stubs; protoc --js_out=import_style=commonjs:. --grpc-web_out=import_style=commonjs,mode=grpcwebtext:. order.proto — generate grpc-web browser stubs.

Do not confuse gRPC status codes with HTTP status codes when reading logs or writing client retry logic. UNAVAILABLE (14) and DEADLINE_EXCEEDED (4) are generally safe to retry with backoff, but INVALID_ARGUMENT (3), NOT_FOUND (5), and PERMISSION_DENIED (7) indicate the request itself is wrong and should never be blindly retried without changing something first.

RPC shape is determined by where 'stream' appears in the method signature: none, response-only, request-only, or both.
Field numbers 1-15 encode in a single byte on the wire; reserve them for the most frequently set fields.
Use 'reserved' for removed field numbers/names to prevent accidental reuse that would break wire compatibility.
Know the core status codes cold: OK, CANCELLED, INVALID_ARGUMENT, DEADLINE_EXCEEDED, NOT_FOUND, PERMISSION_DENIED, UNAVAILABLE, UNAUTHENTICATED.
UNAVAILABLE and DEADLINE_EXCEEDED are generally retry-safe; INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED are not.
grpcurl is the go-to CLI for listing, describing, and invoking RPCs via reflection or explicit .proto files.
protoc with language-specific plugins (--go_out, --go-grpc_out, --grpc-web_out, etc.) is the standard code-generation invocation.