Understanding gRPC Fundamentals
1. Understanding gRPC Architecture
gRPC is a high-performance, open-source RPC framework built on HTTP/2 using Protocol Buffers as the interface definition language and on-the-wire format. A client invokes methods on a generated stub as if they were local; the framework handles serialization, network transport, multiplexing, and deserialization.
| Layer | Responsibility | Component |
|---|---|---|
| IDL | Service & message contract | .proto files |
| Codegen | Stub & skeleton generation | protoc, language plugins |
| Serialization | Binary message encoding | Protocol Buffers |
| Transport | Multiplexed framing & flow control | HTTP/2 |
| Channel | Connection abstraction | Client channel / server |
| Security | Auth & encryption | TLS, credentials, interceptors |
Client App Server App
│ │
[Stub] ─proto─► [Marshal] ─HTTP/2─► [Unmarshal] ─► [Service Impl]
▲ │
└────────── response stream ◄────────── [Marshal] ◄───┘
2. Understanding HTTP/2 Benefits
| Feature | Benefit for gRPC |
|---|---|
| Multiplexing | Many concurrent RPCs over a single TCP connection |
| Binary framing | Compact, fast to parse vs HTTP/1.1 text |
| Header compression (HPACK) | Reduces metadata overhead per call |
| Server push / streams | Enables true bidirectional streaming |
| Flow control | Per-stream backpressure |
| TLS by default | Encrypted transport with ALPN |
3. Comparing gRPC vs REST
| Aspect | gRPC | REST/JSON |
|---|---|---|
| Transport | HTTP/2 only | HTTP/1.1 or HTTP/2 |
| Payload | Protobuf binary | JSON text |
| Contract | Strongly typed .proto | OpenAPI (optional) |
| Streaming | Unary, server, client, bidi | Request/response (SSE/WS for stream) |
| Browser support | Via gRPC-Web proxy | Native |
| Performance | ~5–10× faster, smaller payloads | Slower, larger payloads |
| Tooling | grpcurl, reflection, codegen | cURL, Postman, Swagger |
| Best for | Microservices, polyglot internals | Public APIs, browsers |
4. Understanding Protocol Buffers
| Property | Value |
|---|---|
| Type | Language-neutral binary serialization format |
| Current version | proto3 (recommended) 2026 |
| Schema | Required — defined in .proto files |
| Wire format | Tag-length-value with varint encoding |
| Evolution | Field numbers (not names) define identity |
5. Understanding RPC Communication Patterns
| Pattern | Client → Server | Server → Client | Use Case |
|---|---|---|---|
| Unary | 1 message | 1 message | Standard request/response |
| Server streaming | 1 message | N messages | Feed, large result sets |
| Client streaming | N messages | 1 message | Uploads, aggregation |
| Bidirectional | N messages | N messages | Chat, real-time sync |
6. Understanding gRPC Service Definition
| Element | Syntax | Purpose |
|---|---|---|
| service | service Name { ... } | Groups related RPCs |
| rpc | rpc Method(Req) returns (Res); | Unary method |
| stream (req) | rpc M(stream Req) returns (Res); | Client streaming |
| stream (res) | rpc M(Req) returns (stream Res); | Server streaming |
| bidi | rpc M(stream Req) returns (stream Res); | Bidirectional |
Example: Minimal service definition
syntax = "proto3";
package user.v1;
option go_package = "example.com/api/user/v1;userv1";
service UserService {
rpc GetUser(GetUserRequest) returns (User);
rpc ListUsers(ListUsersRequest) returns (stream User);
}
message GetUserRequest { string id = 1; }
message User { string id = 1; string email = 2; }
message ListUsersRequest { int32 page_size = 1; }
7. Understanding Wire Format
| Component | Encoding | Notes |
|---|---|---|
| Tag | varint = (field_number << 3) | wire_type | Identifies field |
| Wire types | 0=varint, 1=64-bit, 2=length-delim, 5=32-bit | Defines length parsing |
| Varint | 7 bits/byte, MSB=continuation | Small ints = 1 byte |
| ZigZag | Used by sint32/sint64 | Efficient negative numbers |
| gRPC frame | 1-byte flag + 4-byte length + payload | Plus HTTP/2 framing |
8. Understanding Channel Abstraction
| Concept | Description |
|---|---|
| Channel | Client-side connection abstraction to a server |
| Subchannel | Per-address transport managed by the channel |
| Resolver | Translates target URI into address list |
| Load balancer | Picks subchannel for each RPC |
| Reusable | One channel → many concurrent RPCs |
Note: Create channels once and reuse them. Creating a new channel per RPC defeats HTTP/2 multiplexing and causes massive overhead.
9. Understanding Stub Generation
| Artifact | Side | Role |
|---|---|---|
| Stub / Client | Client | Local proxy invoking RPCs |
| Server / Skeleton | Server | Base type to implement service |
| Message types | Both | Strongly typed DTOs |
| Descriptors | Both | Used by reflection & tooling |
10. Understanding gRPC Ecosystem
| Tool | Purpose |
|---|---|
protoc | Protocol Buffer compiler |
| Buf MODERN | Linting, breaking-change detection, build |
| grpcurl | cURL-like CLI for gRPC |
| grpc-gateway | Generates REST/JSON ↔ gRPC proxy |
| gRPC-Web | Browser support via Envoy proxy |
| Envoy | L7 proxy with native gRPC support |
| protoc-gen-validate | Generates field validation |
| OpenTelemetry | Tracing & metrics instrumentation |