gRPC 101 with Go

A comprehensive and practical guide to building gRPC applications in Go (Golang). This repository covers everything from the absolute basics (Unary RPCs) to advanced production-ready patterns, including Interceptors, Security (mTLS), gRPC Gateway, Observability, Rate Limiting and Production-Ready Cluster on Minikube with Kubernetes.

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following tools installed:

• Go: Version 1.20 or higher.
• buf: A modern and fast tool for working with Protocol Buffers. This repository uses buf (instead of the traditional protoc) to manage, lint, and generate Go code.
  • Installation: buf Installation Guide
• Docker & Docker Compose (Optional): Required only if you want to run the Observability example (Prometheus & Jaeger).
• kubectl (Optional): Required only if you want to run the Production-Ready Cluster example.
• helm (Optional): Required only if you want to run the Production-Ready Cluster example.
• minikube (Optional): Required only if you want to run the Production-Ready Cluster example.
• k6 (Optional): Required only if you want to run the Production-Ready Cluster example.

🛠️ Setup

1. Clone the repository:

   git clone <repo-url>
   cd go-grpc-101

2. Install dependencies:

   make tidy

3. Generate Go code from .proto files:

   make gen

   (Note: This uses the Makefile to run buf generate proto, which reads buf.gen.yaml to generate the necessary Go gRPC stubs).

📂 Project Structure

go-grpc-101/
├── README.md                  # general instructions, learning roadmap & tool installation
├── Makefile                   # command collection for generating protoc code, running, testing
├── go.mod
├── go.sum
│
├── proto/                     # Protocol Buffer definitions (*.proto files)
│   ├── user/
│   ├── order/
│   └── buf.yaml               # Buf configuration file
│
├── pb/                        # Generated Go source code from the .proto files
│   ├── user/
│   └── order/
│
├── 01-unary-rpc/              # Topic 1: basic Unary RPC
│   ├── client/
│   │   └── main.go
│   └── server/
│       └── main.go
│
├── 02-streaming-rpc/          # Topic 2: Server, Client & Bi-directional Streaming
│   ├── client/
│   │   └── main.go
│   └── server/
│       └── main.go
│
├── 03-metadata-context/       # Topic 3: Passing Metadata (Header/Trailer) & Timeout   
│   ├── client/
│   │   └── main.go
│   └── server/
│       └── main.go
│
├── 04-error-handling/         # Topic 4: gRPC Status Codes & Error Details
│   ├── client/
│   │   └── main.go
│   └── server/
│       └── main.go
│
├── 05-interceptors/           # Topic 5: Middleware (Auth, Logging, Recovery)
│   ├── middleware/            # place to write reusable Middleware functions
│   │   ├── auth.go            # Recovery (Panic handling) -> Logging/Tracing -> Authentication -> Validation
│   │   └── logging.go
│   ├── client/
│   └── server/
│
├── 06-security/               # Topic 6: TLS/mTLS & Token Authentication
│   ├── certs/                 # Contains demo SSL certificate files (.crt, .key) 
│   ├── client/
│   └── server/
│
├── 07-reflection-health/      # Topic 7: gRPC Reflection & Health Check API
│   └── server/
│       └── main.go
│
├── 08-grpc-gateway/           # Topic 8: Convert gRPC to RESTful JSON API
│   └── server/                # gRPC server
│
├── 09-load-balancing/         # Topic 9: Client-side Load Balancing & Resolver
│   ├── client/
│   └── server/
│
├── 10-unit-testing/           # Topic 10: Testing with `bufconn` (In-memory) & Mock  
│   ├── service_test.go
│   └── service.go
│
├── 11-observability/          # Topic 11: Prometheus Metrics & OpenTelemetry Tracing
│   ├── docker-compose.yml     # Running Prometheus, Jaeger
│   ├── client/
│   └── server/
│
├── 12-rate-limiting/          # Topic 12: Rate Limiting (Token Bucket & Interceptors)
│   ├── client/
│   └── server/
│
├── 13-keepalive-config/       # Topic 13: Keepalive & Connection Management
│   ├── client/
│   └── server/
│
├── 14-payload-compression/    # Topic 14: Payload Compression (Gzip)
│   ├── client/
│   └── server/
│
├── 15-multiplexing/           # Topic 15: Multiplexing gRPC and HTTP on a single port (cmux)
│   └── server/
│
├── 16-circuit-breaking/       # Topic 16: Circuit Breaker Pattern (Cascading Failure Prevention)
│   ├── client/
│   └── server/
│
├── 17-retries/                # Topic 17: Transparent Retries & Hedging
│   ├── client/
│   └── server/
│
├── 18-client-mocking/         # Topic 18: Client Mocking with gomock (Dependency Isolation)
│   ├── mocks/                 # Auto-generated mock clients from mockgen
│   ├── order.go               # Business logic (depends on UserServiceClient)
│   └── order_test.go          # Unit tests using the mock client
│
├── 19-docker-distroless/      # Topic 19: Docker Distroless Image
│   ├── Dockerfile             # Dockerfile for distroless image
│   └── README.md              # Detailed explanation of distroless image
│ 
├── 20-protobuf-validation/    # Topic 20: Protobuf Validation
│   ├── server/                # gRPC server
│   ├── client/                # gRPC client
│   └── README.md              # Detailed explanation of protobuf validation
│ 
├── 21-custom-lb/              # Topic 21: Custom Load Balancing
│   ├── client/                # gRPC client
│   ├── server/                # gRPC server
│   └── README.md              # Detailed explanation of custom load balancing
│ 
├── 22-xds/                    # Topic 22: xDS (Experimental)
│   ├── client/                # gRPC client
│   ├── server/                # gRPC server
│   └── README.md              # Detailed explanation of xDS
│ 
├── 23-c10k-problem/           # Topic 23: C10k problem
│   ├── optimized-sysctl.conf  # Optimized sysctl configuration for C10k problem
│   └── README.md              # Detailed explanation of c10k problem
│ 
├── 26-graceful-shutdown/      # Topic 26: Graceful Shutdown & Drain Protection
│   ├── client/
│   ├── server/
│   └── README.md              # Detailed explanation of Graceful Shutdown
│
└── 99-production-ready-cluster/    # Topic 99: Production-Ready Microservices on Minikube + K6
   ├── README.md
   │
   ├── api-gateway/
   │   └── main.go
   │
   ├── order-service/
   │   └── main.go
   │
   ├── user-service/
   │   └── main.go
   │
   ├── xds-control-plane/
   │   └── main.go                  # Watches K8s Endpoints API, serves both order + user snapshots
   │
   ├── k8s/
   │   ├── namespace.yaml              # Monitoring namespace
   │   ├── xds-bootstrap-config.yaml   # Shared xDS bootstrap config (mounted as volume)
   │   ├── xds-rbac.yaml               # ServiceAccount + ClusterRole for xDS to read Endpoints
   │   ├── xds-control-plane.yaml      # Deployment (1 replica)
   │   ├── user-service.yaml           # Deployment (1 replica) + Service + ServiceMonitor
   │   ├── order-service.yaml          # Deployment (1 replica) + Service + ServiceMonitor
   │   ├── api-gateway.yaml            # Deployment (1 replica) + NodePort Service + ServiceMonitor
   │   ├── ingress.yaml                # Nginx Ingress (api.grpc-cluster.local → api-gateway)
   │   ├── network-policy.yaml         # Zero-Trust: strict service-to-service traffic rules
   │   └── monitoring/
   │       ├── prometheus-values.yaml
   │       └── jaeger-values.yaml
   │
   └── loadtest/
      └── k6-script.js