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.
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.
Practice what you learned
1. In a .proto service definition, what determines whether an RPC method is client-streaming?
2. Why should field numbers 1 through 15 be reserved for the most frequently used fields in a message?
3. What is the purpose of the 'reserved' keyword in a .proto message?
4. Which gRPC status codes are generally considered safe to retry automatically with backoff?
5. What does the command `grpcurl -plaintext host:port list` do?
Was this page helpful?
You May Also Like
gRPC Interview Questions
A curated set of common gRPC interview questions covering fundamentals, streaming modes, error handling, and performance, with model answers.
gRPC with Node.js or Go
How to build gRPC servers and clients using the official Node.js (@grpc/grpc-js) and Go (google.golang.org/grpc) libraries, and where their concurrency models diverge.
gRPC Performance Considerations
Key factors that determine gRPC throughput and latency: connection reuse, message size, streaming versus unary trade-offs, and serialization overhead.
Testing gRPC Services
Strategies and tools for unit testing, integration testing, and manually exercising gRPC services, including grpcurl, in-process servers, and mocking generated clients.
Related Reading
Related Study Notes in Web Development
Browse all study notesWebSockets Study Notes
Web Development · 30 topics
Web DevelopmentWebAssembly Study Notes
WebAssembly · 30 topics
Web DevelopmentSpring Boot Study Notes
Java · 30 topics
Web DevelopmentFlask Study Notes
Python · 30 topics
Web DevelopmentDjango Study Notes
Python · 30 topics
Web DevelopmentNext.js Study Notes
JavaScript · 30 topics