Day 3: gRPC Concepts

Phase 3 · Jul 3, 2026

Agenda (2–3 hours)

• Read (45 min): gRPC core concepts documentation; HTTP/2 framing overview (RFC 7540 §4–5)
• Study (45 min): Trace a unary gRPC call at the HTTP/2 frame level; identify the DATA, HEADERS, and RST_STREAM frames
• Practice (45 min): Define a service with all four RPC types in proto3; use grpcurl to call a running tonic service
• Challenge (30 min): When would you choose server-streaming over a paginated REST endpoint? Design the tradeoffs

gRPC Service Types

service TaskService {
  // Unary: one request, one response
  rpc GetTask(GetTaskRequest) returns (Task);

  // Server streaming: one request, stream of responses
  rpc WatchTask(WatchTaskRequest) returns (stream TaskEvent);

  // Client streaming: stream of requests, one response
  rpc UploadLogs(stream LogEntry) returns (UploadResult);

  // Bidirectional streaming: stream in both directions
  rpc Chat(stream ChatMessage) returns (stream ChatMessage);
}

gRPC over HTTP/2

gRPC maps to HTTP/2:

• Method: always POST
• Path: /{package}.{ServiceName}/{MethodName}
• Content-Type: application/grpc (+ encoding)
• Headers: gRPC metadata → HTTP/2 HEADERS frame
• Body: length-prefix (5 bytes) + protobuf-encoded message

HTTP/2 enables:

• Multiplexing: multiple concurrent RPCs over one TCP connection
• Header compression (HPACK): repeated metadata is cheap
• Flow control: receiver controls how much data sender can send
• Server push: not used by gRPC but available

Why gRPC Over REST/JSON?

gRPC shines for:

• Internal microservice communication (both sides use gRPC)
• High-throughput or streaming workloads
• Strongly-typed interfaces between teams

grpcurl

# List services
grpcurl -plaintext localhost:50051 list

# Describe service
grpcurl -plaintext localhost:50051 describe myapp.v1.TaskService

# Unary call
grpcurl -plaintext -d '{"id": "42"}' localhost:50051 myapp.v1.TaskService/GetTask

# Server streaming
grpcurl -plaintext -d '{"task_id": "42"}' localhost:50051 \
    myapp.v1.TaskService/WatchTask

Requires the server to have server reflection enabled (tonic_reflection::server::Builder).

Key Takeaways

• Four service types: unary, server-streaming, client-streaming, bidirectional-streaming
• gRPC runs over HTTP/2: multiplexed, header-compressed, flow-controlled
• Protobuf + gRPC together provide: schema, codegen, streaming, performance, error details
• Use grpcurl for manual testing; enable server reflection for discoverability

Tomorrow: tonic server — implementing and serving gRPC services in Rust.