gRPC — Remote Procedure Call Framework

Last reviewed: 2026-09-17

gRPC is a high-performance, open-source universal RPC framework initially developed by Google. It uses HTTP/2 for transport, Protocol Buffers (protobuf) for serialization, and enables client-server communication across languages and platforms.

---

Overview

gRPC is designed for low-latency, high-throughput communication, especially between microservices. It supports four communication patterns:

Pattern	Description
Unary RPC	Client sends one request, server returns one response (like HTTP/REST)
Server Streaming	Client sends one request, server streams multiple responses
Client Streaming	Client streams multiple requests, server returns one response
Bidirectional Streaming	Both sides send/receive streams concurrently

---

Topics Covered

• Protocol Buffers service and message definitions (.proto)
• Code generation with protoc and language plugins
• Unary and streaming RPC patterns
• gRPC server and client implementation in Go
• gRPC implementation in Python
• Interceptors / middleware
• Error handling and deadline propagation
• TLS and mTLS for secure connections
• gRPC Gateway (REST ↔ gRPC transcoding)

---

Protocol Buffers Definition

syntax = "proto3";

package order;

service OrderService {
  rpc CreateOrder (CreateOrderRequest) returns (Order);
  rpc GetOrder (GetOrderRequest) returns (Order);
  rpc ListOrders (ListOrdersRequest) returns (stream Order);  // Server streaming
}

message CreateOrderRequest {
  string user_id = 1;
  repeated string item_ids = 2;
}

message Order {
  string id = 1;
  string user_id = 2;
  repeated string item_ids = 3;
  double total = 4;
  int64 created_at = 5;
}

Generate stubs from the definition:

# Go: protoc + the Go plugins produce types and client/server stubs
protoc --go_out=. --go-grpc_out=. order.proto

# Python
python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. order.proto

---

gRPC vs REST

Feature	gRPC	REST
Transport	HTTP/2	HTTP/1.1, HTTP/2
Serialization	Protocol Buffers (binary)	JSON, XML (text)
Contract	Required .proto schema	Optional (OpenAPI)
Streaming	Native bidirectional	SSE, WebSocket add-ons
Performance	~5–10× faster than JSON	Slower due to text parsing
Browser support	Requires gRPC-Web	Native
Code generation	Built-in (protoc)	Manual or OpenAPI generators
Human readability	Low (binary wire format)	High (readable JSON)

---

Key Concepts

HTTP/2 Benefits

• Multiplexing — Multiple requests over a single TCP connection
• Header compression (HPACK) — Reduces overhead
• Server push — Server sends resources before requested
• Flow control — Per-stream control

Proto3 Features

• Strong typing — Compile-time type checking
• Backward compatibility — Field numbers allow evolution
• Cross-language — Code generation for Go, Python, Java, C++, etc.
• Small payloads — Binary encoding ≈ 10× smaller than JSON
• Fast serialization — Up to 100× faster than JSON parsing

gRPC Ecosystem

Component	Description
protoc	Protocol Buffers compiler
protoc-gen-go / protoc-gen-go-grpc	Go code generation plugins
grpc-gateway	REST ↔ gRPC transcoding proxy
gRPC-Web	Browser client support
Envoy proxy	gRPC load balancing (L7)
gRPC health probe	gRPC health checking protocol

Deadlines, Errors and Interceptors

• Every call carries a deadline that propagates across services; a DEADLINE_EXCEEDED status must not be retried blindly.
• Status codes are canonical (OK, INVALID_ARGUMENT, NOT_FOUND, UNAVAILABLE) and travel with optional metadata.
• Interceptors wrap calls on the client or server side — the standard place for auth, logging, metrics and retries.
• Streaming calls should always be driven by a context.Context so a cancelled client cancels server work.

---

Authentication

// TLS connection (recommended)
creds, _ := credentials.NewClientTLSFromFile(certFile, "")
conn, _ := grpc.NewClient(address, grpc.WithTransportCredentials(creds))

// With JWT token (interceptor metadata)
// Client adds token to context:
ctx := metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer <token>")

// Server validates via interceptor

For service-to-service traffic, mTLS (client certificates verified by the server) is the usual choice; bearer tokens remain convenient for user-facing clients.

---

Resources

• gRPC Documentation
• Protocol Buffers Guide
• gRPC Go Quickstart
• gRPC Python Quickstart
• gRPC Gateway
• gRPC Best Practices

---

To-do

Status: incomplete. Still to write:

• Implement the 'gRPC server and client in Go' promised in Topics Covered — only the .proto definition and the protoc command are shown, with no service implementation.
• Implement the 'gRPC implementation in Python' promised in Topics Covered — only the grpc_tools.protoc invocation is shown.
• Show a working interceptor example (client- or server-side) for auth/logging — interceptors are promised and currently only described in prose.
• Expand 'Error handling and deadline propagation' with code: status codes, metadata and how a deadline is set on a call.