Protocol Buffers & gRPC

From .proto files to production gRPC services in Go — the complete guide to high-performance RPC.

01 What is Protocol Buffers

JSON vs Protobuf — Size Comparison

The same user object in JSON vs Protobuf wire format:

// JSON — 74 bytes (human readable, lots of overhead)
{
  "name": "John Doe",
  "age": 30,
  "email": "john@example.com",
  "active": true
}

// Protobuf binary — ~32 bytes (not human readable, minimal overhead)
// Field 1 (string): "John Doe"
// Field 2 (varint): 30
// Field 3 (string): "john@example.com"
// Field 4 (varint): 1
// 0a 08 4a 6f 68 6e 20 44 6f 65 10 1e 1a 10 6a 6f ...

02 Proto File Syntax

Every .proto file follows a specific structure. Let's break down every element:

// user.proto
syntax = "proto3";           // MUST be first non-comment line

package user.v1;                // prevents naming conflicts between projects

option go_package = "github.com/yourorg/project/gen/user/v1;userv1";

import "google/protobuf/timestamp.proto";  // import well-known types

// A message is like a struct in Go or a class in Java
message User {
  string id       = 1;         // field_number = 1 (NOT the value, it's the tag)
  string name     = 2;
  string email    = 3;
  int32  age      = 4;
  bool   active   = 5;
  google.protobuf.Timestamp created_at = 6;
}

// A service defines RPC methods
service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
  rpc ListUsers(ListUsersRequest) returns (stream User);
}

message GetUserRequest {
  string id = 1;
}

message GetUserResponse {
  User user = 1;
}

Naming Conventions

03 Scalar Types

Protobuf has a fixed set of scalar (primitive) types. Each maps to a specific type in Go:

04 Messages & Enums

Messages

A message is the protobuf equivalent of a Go struct. Messages can be nested, reference each other, and contain any combination of fields.

message Address {
  string street   = 1;
  string city     = 2;
  string state    = 3;
  string zip_code = 4;
  string country  = 5;
}

message User {
  string  id       = 1;
  string  name     = 2;
  string  email    = 3;
  Address address  = 4;     // nested message reference
  repeated string tags = 5; // repeated = slice/array

  // Nested message — only accessible as User.PhoneNumber
  message PhoneNumber {
    string number = 1;
    PhoneType type = 2;
  }
  repeated PhoneNumber phones = 6;
}

Generated Go code:

// Auto-generated — DO NOT EDIT
type User struct {
    Id      string              `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
    Name    string              `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
    Email   string              `protobuf:"bytes,3,opt,name=email,proto3" json:"email,omitempty"`
    Address *Address            `protobuf:"bytes,4,opt,name=address,proto3" json:"address,omitempty"`
    Tags    []string            `protobuf:"bytes,5,rep,name=tags,proto3" json:"tags,omitempty"`
    Phones  []*User_PhoneNumber `protobuf:"bytes,6,rep,name=phones,proto3" json:"phones,omitempty"`
}

// Getters are generated — safe to call on nil receivers
func (x *User) GetName() string {
    if x != nil {
        return x.Name
    }
    return ""
}

func (x *User) GetAddress() *Address {
    if x != nil {
        return x.Address
    }
    return nil
}

Enums

Enums define a fixed set of constants. The first value MUST be 0 and serves as the default.

enum PhoneType {
  PHONE_TYPE_UNSPECIFIED = 0;  // MUST have 0 value — it's the default
  PHONE_TYPE_MOBILE      = 1;
  PHONE_TYPE_HOME        = 2;
  PHONE_TYPE_WORK        = 3;
}

enum UserStatus {
  USER_STATUS_UNSPECIFIED = 0;
  USER_STATUS_ACTIVE     = 1;
  USER_STATUS_INACTIVE   = 2;
  USER_STATUS_BANNED     = 3;
}

message User {
  string     id     = 1;
  string     name   = 2;
  UserStatus status = 3;
}

Generated Go enum code:

type UserStatus int32

const (
    UserStatus_USER_STATUS_UNSPECIFIED UserStatus = 0
    UserStatus_USER_STATUS_ACTIVE      UserStatus = 1
    UserStatus_USER_STATUS_INACTIVE    UserStatus = 2
    UserStatus_USER_STATUS_BANNED      UserStatus = 3
)

// Usage in Go:
user := &pb.User{
    Id:     "u-123",
    Name:   "Alice",
    Status: pb.UserStatus_USER_STATUS_ACTIVE,
}

if user.Status == pb.UserStatus_USER_STATUS_BANNED {
    // handle banned user
}

Enum Aliases

You can give multiple enum values the same number with allow_alias:

enum Priority {
  option allow_alias = true;
  PRIORITY_UNSPECIFIED = 0;
  PRIORITY_LOW         = 1;
  PRIORITY_P3          = 1;  // alias for LOW
  PRIORITY_MEDIUM      = 2;
  PRIORITY_P2          = 2;  // alias for MEDIUM
  PRIORITY_HIGH        = 3;
  PRIORITY_P1          = 3;  // alias for HIGH
}

05 Oneof, Maps & Any

Oneof — Mutually Exclusive Fields

oneof means "exactly one of these fields can be set at a time." Setting one automatically clears the others. Think TypeScript union types or Go interfaces.

message NotificationTarget {
  string notification_id = 1;

  oneof target {
    string email      = 2;  // send via email
    string phone      = 3;  // send via SMS
    string slack_id   = 4;  // send via Slack
    string webhook_url = 5; // send via webhook
  }
}

message PaymentMethod {
  oneof method {
    CreditCard   credit_card   = 1;
    BankTransfer bank_transfer = 2;
    CryptoWallet crypto_wallet = 3;
  }
}

message CreditCard {
  string number     = 1;
  string expiry     = 2;
  string cvv        = 3;
}

Generated Go uses an interface pattern:

type NotificationTarget struct {
    NotificationId string
    // oneof target
    Target isNotificationTarget_Target  // interface
}

// Each option implements the interface
type NotificationTarget_Email struct { Email string }
type NotificationTarget_Phone struct { Phone string }
type NotificationTarget_SlackId struct { SlackId string }

// Usage — type switch to determine which is set
switch t := notification.Target.(type) {
case *pb.NotificationTarget_Email:
    sendEmail(t.Email)
case *pb.NotificationTarget_Phone:
    sendSMS(t.Phone)
case *pb.NotificationTarget_SlackId:
    sendSlack(t.SlackId)
case nil:
    // not set
}

Maps

map fields are key-value pairs, equivalent to Go's map[K]V:

message Project {
  string id   = 1;
  string name = 2;

  // map<key_type, value_type>
  map<string, string> labels     = 3;  // map[string]string
  map<string, int32>  priorities = 4;  // map[string]int32
  map<int32, User>   members    = 5;  // map[int32]*User
}

// Key type MUST be integral or string — NOT float, bytes, or message
// Value type can be anything EXCEPT another map

google.protobuf.Any — Dynamic Typing

Any holds an arbitrary serialized message along with a URL that describes its type. It's protobuf's escape hatch for dynamic typing.

import "google/protobuf/any.proto";

message Event {
  string                id        = 1;
  string                type      = 2;
  google.protobuf.Any   payload   = 3;  // can hold ANY message
  google.protobuf.Timestamp time   = 4;
}

// Go usage — packing and unpacking Any
import "google.golang.org/protobuf/types/known/anypb"

// Pack a User into Any
user := &pb.User{Id: "u-1", Name: "Alice"}
anyPayload, err := anypb.New(user)

event := &pb.Event{
    Id:      "evt-1",
    Type:    "user.created",
    Payload: anyPayload,
}

// Unpack Any back to a specific type
var unpacked pb.User
if err := event.Payload.UnmarshalTo(&unpacked); err != nil {
    log.Fatal(err)
}
fmt.Println(unpacked.Name) // "Alice"

06 Imports & Packages

Imports

Use import to reference types defined in other .proto files:

// common/types.proto
syntax = "proto3";
package common.v1;
option go_package = "github.com/org/project/gen/common/v1;commonv1";

message Pagination {
  int32  page      = 1;
  int32  page_size = 2;
  string cursor    = 3;
}

message ErrorDetail {
  string code    = 1;
  string message = 2;
  map<string, string> metadata = 3;
}

// user/v1/user.proto
syntax = "proto3";
package user.v1;
option go_package = "github.com/org/project/gen/user/v1;userv1";

import "common/types.proto";  // import the common types

message ListUsersRequest {
  common.v1.Pagination pagination = 1;  // use fully qualified name
  string filter = 2;
}

message ListUsersResponse {
  repeated User users = 1;
  int32 total_count    = 2;
}

Public vs Weak Imports

// Regular import — only this file can use the imported types
import "common/types.proto";

// Public import — anyone who imports THIS file also gets common/types.proto
// Useful when re-exporting / moving types between files
import public "common/types.proto";

Package Versioning Strategy

07 Well-Known Types

Google provides a set of well-known types (WKTs) — standard protobuf messages for common patterns. Always use these instead of inventing your own.

Timestamp & Duration

import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";

message Session {
  string                       id         = 1;
  google.protobuf.Timestamp    created_at = 2;
  google.protobuf.Timestamp    expires_at = 3;
  google.protobuf.Duration     ttl        = 4;
}

// Go usage
import (
    "time"
    "google.golang.org/protobuf/types/known/timestamppb"
    "google.golang.org/protobuf/types/known/durationpb"
)

session := &pb.Session{
    Id:        "sess-1",
    CreatedAt: timestamppb.Now(),                          // time.Now() → Timestamp
    ExpiresAt: timestamppb.New(time.Now().Add(24 * time.Hour)),
    Ttl:       durationpb.New(24 * time.Hour),             // time.Duration → Duration
}

// Convert back to Go types
goTime := session.CreatedAt.AsTime()      // → time.Time
goDuration := session.Ttl.AsDuration()    // → time.Duration

FieldMask — Partial Updates

import "google/protobuf/field_mask.proto";

message UpdateUserRequest {
  User                         user        = 1;
  google.protobuf.FieldMask    update_mask = 2;
}

// Client sends: update_mask.paths = ["name", "email"]
// → Server only updates name and email, ignores all other fields
// This is how Google APIs implement PATCH semantics

// Go server-side handling
func (s *server) UpdateUser(ctx context.Context, req *pb.UpdateUserRequest) (*pb.User, error) {
    existing, err := s.db.GetUser(ctx, req.User.Id)
    if err != nil {
        return nil, err
    }

    // Apply only the fields specified in the mask
    for _, path := range req.UpdateMask.GetPaths() {
        switch path {
        case "name":
            existing.Name = req.User.Name
        case "email":
            existing.Email = req.User.Email
        case "address.city":
            existing.Address.City = req.User.Address.City
        }
    }

    return s.db.SaveUser(ctx, existing)
}

Wrapper Types — Nullable Scalars

import "google/protobuf/wrappers.proto";

message SearchFilter {
  string                          query     = 1;
  google.protobuf.Int32Value      min_age   = 2;  // nil = no filter, 0 = filter for age 0
  google.protobuf.Int32Value      max_age   = 3;
  google.protobuf.BoolValue      is_active = 4;  // nil = no filter, false = filter for inactive
  google.protobuf.StringValue    country   = 5;  // nil = no filter, "" = filter for empty country
}

08 Field Numbers & Wire Format

Wire Types

Field Number Ranges

message Example {
  // 1-15:  Tag encoded in 1 byte → USE THESE for frequently-set fields
  string id   = 1;   // 1 byte tag
  string name = 2;   // 1 byte tag

  // 16-2047: Tag encoded in 2 bytes
  string description = 16;  // 2 byte tag

  // 2048-262143: Tag encoded in 3 bytes
  // ... and so on

  // 19000-19999: RESERVED by protobuf implementation — DO NOT USE
  // Max field number: 536,870,911 (2^29 - 1)
}

Reserved Fields

When you remove a field, reserve its number and name to prevent future developers from accidentally reusing them (which would break backward compatibility):

message User {
  reserved 4, 7, 9 to 11;              // reserve field numbers
  reserved "old_field", "legacy_name";   // reserve field names

  string id    = 1;
  string name  = 2;
  string email = 3;
  // field 4 was 'phone' — removed in v2
  int32  age   = 5;
}

09 Backward & Forward Compatibility

Safe Changes (DO)

• Add new fields with new field numbers
• Remove fields (but reserve their numbers and names)
• Rename fields (wire format only uses numbers, not names)
• Add new enum values
• Add new RPC methods to a service
• Change int32 to int64 (or uint32 to uint64) — widening is safe
• Change string to bytes (if the string was valid UTF-8)

Breaking Changes (DON'T)

• Change a field number — old clients will read the wrong data
• Change a field's type to an incompatible type (e.g., string to int32)
• Reuse a field number that was previously used (even if the old field was removed)
• Change the name of a package (affects generated code imports)
• Remove an enum value — old clients may still send it
• Change a repeated field to a scalar or vice versa
• Change oneof to regular fields or vice versa

10 Protoc & Code Generation

Installing the Toolchain

# 1. Install the protoc compiler
# macOS
brew install protobuf

# Linux (Ubuntu/Debian)
apt install -y protobuf-compiler

# Verify
protoc --version   # libprotoc 27.x

# 2. Install Go plugins for protoc
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# Make sure $GOPATH/bin is in your PATH
export PATH="$PATH:$(go env GOPATH)/bin"

Running protoc

# Generate Go code from a single .proto file
protoc \
  --go_out=. \
  --go_opt=paths=source_relative \
  --go-grpc_out=. \
  --go-grpc_opt=paths=source_relative \
  proto/user/v1/user.proto

# What each flag means:
# --go_out=.                    → generate message structs, put output relative to current dir
# --go_opt=paths=source_relative → output file path mirrors the .proto file path
# --go-grpc_out=.               → generate gRPC service stubs
# --go-grpc_opt=paths=source_relative → same path strategy for gRPC files

# Generate all .proto files in a directory tree
protoc \
  --go_out=. --go_opt=paths=source_relative \
  --go-grpc_out=. --go-grpc_opt=paths=source_relative \
  --proto_path=proto \
  proto/**/*.proto

Output Files

For each .proto file, protoc generates two Go files:

Buf — Modern Protobuf Tooling

buf is the modern alternative to raw protoc. It handles linting, breaking change detection, code generation, and dependency management.

# Install buf
brew install bufbuild/buf/buf

# Initialize a buf project
buf mod init

# buf.yaml — module configuration
version: v2
modules:
  - path: proto
    name: buf.build/yourorg/project
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE

# buf.gen.yaml — code generation config
version: v2
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen
    opt: paths=source_relative
  - remote: buf.build/grpc/go
    out: gen
    opt: paths=source_relative

# Generate code
buf generate

# Lint your proto files
buf lint

# Check for breaking changes against the main branch
buf breaking --against '.git#branch=main'

11 What is gRPC

12 gRPC vs REST

13 Service Definition

A service in a .proto file defines the RPC methods that a server implements and a client can call.

syntax = "proto3";
package product.v1;
option go_package = "github.com/org/shop/gen/product/v1;productv1";

import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";

// ============ Messages ============

message Product {
  string  id          = 1;
  string  name        = 2;
  string  description = 3;
  int64   price_cents = 4;     // store money as cents to avoid float issues
  string  currency    = 5;
  repeated string categories = 6;
  ProductStatus status = 7;
  google.protobuf.Timestamp created_at = 8;
  google.protobuf.Timestamp updated_at = 9;
}

enum ProductStatus {
  PRODUCT_STATUS_UNSPECIFIED = 0;
  PRODUCT_STATUS_DRAFT      = 1;
  PRODUCT_STATUS_ACTIVE     = 2;
  PRODUCT_STATUS_ARCHIVED   = 3;
}

// ============ Request/Response Messages ============

message CreateProductRequest {
  string  name        = 1;
  string  description = 2;
  int64   price_cents = 3;
  string  currency    = 4;
  repeated string categories = 5;
}

message GetProductRequest {
  string id = 1;
}

message UpdateProductRequest {
  Product                      product     = 1;
  google.protobuf.FieldMask    update_mask = 2;
}

message DeleteProductRequest {
  string id = 1;
}

message ListProductsRequest {
  int32  page_size   = 1;
  string page_token  = 2;   // cursor-based pagination
  string filter      = 3;   // e.g., "status=ACTIVE AND price_cents>1000"
  string order_by    = 4;   // e.g., "created_at desc"
}

message ListProductsResponse {
  repeated Product products       = 1;
  string            next_page_token = 2;
  int32             total_count     = 3;
}

message WatchProductsRequest {
  repeated string product_ids = 1;
}

// ============ Service ============

service ProductService {
  // Unary — one request, one response
  rpc CreateProduct(CreateProductRequest) returns (Product);
  rpc GetProduct(GetProductRequest) returns (Product);
  rpc UpdateProduct(UpdateProductRequest) returns (Product);
  rpc DeleteProduct(DeleteProductRequest) returns (google.protobuf.Empty);

  // Server streaming — one request, stream of responses
  rpc ListProducts(ListProductsRequest) returns (ListProductsResponse);

  // Server streaming — watch for real-time updates
  rpc WatchProducts(WatchProductsRequest) returns (stream Product);

  // Client streaming — stream of requests, one response
  rpc BulkCreateProducts(stream CreateProductRequest) returns (ListProductsResponse);

  // Bidirectional streaming — stream both ways
  rpc SyncProducts(stream Product) returns (stream Product);
}

14 The 4 RPC Types

// Node.js gRPC server (using nice-grpc)
import { createServer } from 'nice-grpc';
import { ProductServiceDefinition } from './gen/product';

const server = createServer();
server.add(ProductServiceDefinition, {
  async getProduct(request) {
    return { id: request.id, name: 'Widget', priceCents: 999 };
  },
  async *watchProducts(request) {   // server streaming = async generator
    while (true) {
      yield { id: '1', name: 'Updated Widget' };
      await sleep(1000);
    }
  }
});
await server.listen('0.0.0.0:50051');

15 Project Setup

Directory Structure

Go Module Setup

# Initialize the module
mkdir grpc-demo && cd grpc-demo
go mod init github.com/yourorg/grpc-demo

# Install gRPC Go dependencies
go get google.golang.org/grpc
go get google.golang.org/protobuf

The Proto File

// proto/user/v1/user.proto
syntax = "proto3";
package user.v1;
option go_package = "github.com/yourorg/grpc-demo/gen/user/v1;userv1";

import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";

message User {
  string  id    = 1;
  string  name  = 2;
  string  email = 3;
  int32   age   = 4;
  google.protobuf.Timestamp created_at = 5;
}

message CreateUserRequest {
  string name  = 1;
  string email = 2;
  int32  age   = 3;
}

message GetUserRequest {
  string id = 1;
}

message ListUsersRequest {
  int32 page_size = 1;
}

message ListUsersResponse {
  repeated User users = 1;
}

message DeleteUserRequest {
  string id = 1;
}

service UserService {
  rpc CreateUser(CreateUserRequest) returns (User);
  rpc GetUser(GetUserRequest) returns (User);
  rpc ListUsers(ListUsersRequest) returns (stream User);
  rpc DeleteUser(DeleteUserRequest) returns (google.protobuf.Empty);
}

Makefile for Code Generation

# Makefile
.PHONY: proto clean

proto:
	protoc \
		--go_out=gen --go_opt=paths=source_relative \
		--go-grpc_out=gen --go-grpc_opt=paths=source_relative \
		--proto_path=proto \
		proto/user/v1/user.proto

clean:
	rm -rf gen/

Line-by-line breakdown

16 Unary Server & Client

Server Implementation

// internal/service/user.go
package service

import (
    "context"
    "fmt"
    "sync"

    "github.com/google/uuid"
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
    "google.golang.org/protobuf/types/known/emptypb"
    "google.golang.org/protobuf/types/known/timestamppb"

    pb "github.com/yourorg/grpc-demo/gen/user/v1"
)

// UserServer implements the generated UserServiceServer interface
type UserServer struct {
    pb.UnimplementedUserServiceServer  // embed for forward compatibility
    mu    sync.RWMutex
    users map[string]*pb.User
}

func NewUserServer() *UserServer {
    return &UserServer{
        users: make(map[string]*pb.User),
    }
}

// CreateUser — Unary RPC
func (s *UserServer) CreateUser(ctx context.Context, req *pb.CreateUserRequest) (*pb.User, error) {
    // Validate input
    if req.Name == "" {
        return nil, status.Error(codes.InvalidArgument, "name is required")
    }
    if req.Email == "" {
        return nil, status.Error(codes.InvalidArgument, "email is required")
    }

    user := &pb.User{
        Id:        uuid.New().String(),
        Name:      req.Name,
        Email:     req.Email,
        Age:       req.Age,
        CreatedAt: timestamppb.Now(),
    }

    s.mu.Lock()
    s.users[user.Id] = user
    s.mu.Unlock()

    return user, nil
}

// GetUser — Unary RPC
func (s *UserServer) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.User, error) {
    if req.Id == "" {
        return nil, status.Error(codes.InvalidArgument, "id is required")
    }

    s.mu.RLock()
    user, ok := s.users[req.Id]
    s.mu.RUnlock()

    if !ok {
        return nil, status.Errorf(codes.NotFound, "user %s not found", req.Id)
    }

    return user, nil
}

// DeleteUser — Unary RPC
func (s *UserServer) DeleteUser(ctx context.Context, req *pb.DeleteUserRequest) (*emptypb.Empty, error) {
    s.mu.Lock()
    defer s.mu.Unlock()

    if _, ok := s.users[req.Id]; !ok {
        return nil, status.Errorf(codes.NotFound, "user %s not found", req.Id)
    }

    delete(s.users, req.Id)
    return &emptypb.Empty{}, nil
}

Server main.go

// cmd/server/main.go
package main

import (
    "log"
    "net"

    "google.golang.org/grpc"
    "google.golang.org/grpc/reflection"

    pb "github.com/yourorg/grpc-demo/gen/user/v1"
    "github.com/yourorg/grpc-demo/internal/service"
)

func main() {
    // 1. Create a TCP listener
    lis, err := net.Listen("tcp", ":50051")
    if err != nil {
        log.Fatalf("failed to listen: %v", err)
    }

    // 2. Create a gRPC server
    grpcServer := grpc.NewServer()

    // 3. Register our service implementation
    userService := service.NewUserServer()
    pb.RegisterUserServiceServer(grpcServer, userService)

    // 4. Enable server reflection (for grpcurl / grpcui debugging)
    reflection.Register(grpcServer)

    // 5. Start serving
    log.Printf("gRPC server listening on %s", lis.Addr())
    if err := grpcServer.Serve(lis); err != nil {
        log.Fatalf("failed to serve: %v", err)
    }
}

Client Implementation

// cmd/client/main.go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"

    pb "github.com/yourorg/grpc-demo/gen/user/v1"
)

func main() {
    // 1. Create a connection to the gRPC server
    conn, err := grpc.NewClient(
        "localhost:50051",
        grpc.WithTransportCredentials(insecure.NewCredentials()),  // no TLS for dev
    )
    if err != nil {
        log.Fatalf("failed to connect: %v", err)
    }
    defer conn.Close()

    // 2. Create a client stub
    client := pb.NewUserServiceClient(conn)

    // 3. Set a deadline/timeout
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    // 4. Call the RPC — looks like a local function call!
    user, err := client.CreateUser(ctx, &pb.CreateUserRequest{
        Name:  "Alice",
        Email: "alice@example.com",
        Age:   28,
    })
    if err != nil {
        log.Fatalf("CreateUser failed: %v", err)
    }
    fmt.Printf("Created user: %s (id: %s)\n", user.Name, user.Id)

    // 5. Get the user back
    fetched, err := client.GetUser(ctx, &pb.GetUserRequest{Id: user.Id})
    if err != nil {
        log.Fatalf("GetUser failed: %v", err)
    }
    fmt.Printf("Fetched: %s, email: %s, created: %s\n",
        fetched.Name, fetched.Email, fetched.CreatedAt.AsTime())
}

17 Server Streaming RPC

The client sends one request, and the server sends back a stream of responses. The server calls Send() for each message, and the client calls Recv() in a loop.

// Server-side: ListUsers streams all users one by one
func (s *UserServer) ListUsers(req *pb.ListUsersRequest, stream pb.UserService_ListUsersServer) error {
    s.mu.RLock()
    defer s.mu.RUnlock()

    count := 0
    for _, user := range s.users {
        // Check if client cancelled
        if err := stream.Context().Err(); err != nil {
            return status.FromContextError(err).Err()
        }

        // Send each user as a separate message in the stream
        if err := stream.Send(user); err != nil {
            return err
        }

        count++
        if req.PageSize > 0 && int32(count) >= req.PageSize {
            break
        }
    }

    return nil // returning nil closes the stream successfully
}

// Client-side: receiving the stream
func listUsers(client pb.UserServiceClient, ctx context.Context) {
    stream, err := client.ListUsers(ctx, &pb.ListUsersRequest{PageSize: 10})
    if err != nil {
        log.Fatalf("ListUsers failed: %v", err)
    }

    // Read messages until the stream ends
    for {
        user, err := stream.Recv()
        if err == io.EOF {
            break // stream finished
        }
        if err != nil {
            log.Fatalf("error receiving: %v", err)
        }
        fmt.Printf("User: %s (%s)\n", user.Name, user.Email)
    }
}

18 Client Streaming RPC

Let's add a BulkCreateUsers method where the client streams user creation requests and the server responds with a summary.

// In the .proto file:
// rpc BulkCreateUsers(stream CreateUserRequest) returns (BulkCreateResponse);

message BulkCreateResponse {
  int32           created_count = 1;
  repeated string user_ids      = 2;
}

// Server-side: receive a stream of create requests
func (s *UserServer) BulkCreateUsers(stream pb.UserService_BulkCreateUsersServer) error {
    var ids []string

    for {
        req, err := stream.Recv()
        if err == io.EOF {
            // Client finished sending — send back the response
            return stream.SendAndClose(&pb.BulkCreateResponse{
                CreatedCount: int32(len(ids)),
                UserIds:      ids,
            })
        }
        if err != nil {
            return err
        }

        // Create each user
        user := &pb.User{
            Id:        uuid.New().String(),
            Name:      req.Name,
            Email:     req.Email,
            Age:       req.Age,
            CreatedAt: timestamppb.Now(),
        }

        s.mu.Lock()
        s.users[user.Id] = user
        s.mu.Unlock()

        ids = append(ids, user.Id)
    }
}

// Client-side: send a stream of create requests
func bulkCreate(client pb.UserServiceClient, ctx context.Context) {
    stream, err := client.BulkCreateUsers(ctx)
    if err != nil {
        log.Fatal(err)
    }

    // Send multiple users
    users := []struct{ name, email string }{
        {"Alice", "alice@example.com"},
        {"Bob", "bob@example.com"},
        {"Charlie", "charlie@example.com"},
    }

    for _, u := range users {
        if err := stream.Send(&pb.CreateUserRequest{
            Name:  u.name,
            Email: u.email,
        }); err != nil {
            log.Fatal(err)
        }
    }

    // Close the stream and get the response
    resp, err := stream.CloseAndRecv()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Created %d users: %v\n", resp.CreatedCount, resp.UserIds)
}

19 Bidirectional Streaming RPC

Both the client and server independently send streams of messages. A real-world example: a chat service.

// chat.proto
syntax = "proto3";
package chat.v1;

message ChatMessage {
  string user    = 1;
  string content = 2;
  int64  sent_at = 3;
}

service ChatService {
  rpc Chat(stream ChatMessage) returns (stream ChatMessage);
}

// Server-side: bidirectional chat
func (s *ChatServer) Chat(stream pb.ChatService_ChatServer) error {
    for {
        // Receive a message from the client
        msg, err := stream.Recv()
        if err == io.EOF {
            return nil
        }
        if err != nil {
            return err
        }

        log.Printf("[%s]: %s", msg.User, msg.Content)

        // Echo back (in real app, you'd broadcast to all connected clients)
        resp := &pb.ChatMessage{
            User:    "server",
            Content: fmt.Sprintf("Echo: %s", msg.Content),
            SentAt:  time.Now().Unix(),
        }

        if err := stream.Send(resp); err != nil {
            return err
        }
    }
}

// Client-side: bidirectional chat
func chat(client pb.ChatServiceClient, ctx context.Context) {
    stream, err := client.Chat(ctx)
    if err != nil {
        log.Fatal(err)
    }

    // Goroutine to receive messages
    go func() {
        for {
            msg, err := stream.Recv()
            if err == io.EOF {
                return
            }
            if err != nil {
                log.Printf("receive error: %v", err)
                return
            }
            fmt.Printf("[%s]: %s\n", msg.User, msg.Content)
        }
    }()

    // Send messages
    messages := []string{"Hello!", "How are you?", "Goodbye!"}
    for _, text := range messages {
        if err := stream.Send(&pb.ChatMessage{
            User:    "alice",
            Content: text,
            SentAt:  time.Now().Unix(),
        }); err != nil {
            log.Fatal(err)
        }
        time.Sleep(500 * time.Millisecond)
    }

    stream.CloseSend() // signal we're done sending
    time.Sleep(time.Second) // wait for remaining responses
}

20 Error Handling & Status Codes

gRPC Status Codes

Returning Errors

import (
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)

// Simple error with code + message
return nil, status.Error(codes.NotFound, "user not found")

// Formatted error message
return nil, status.Errorf(codes.InvalidArgument, "name must be at least %d characters", 3)

// Wrapping an existing error
if err := db.Query(ctx); err != nil {
    return nil, status.Errorf(codes.Internal, "database error: %v", err)
}

Rich Error Details

import (
    "google.golang.org/genproto/googleapis/rpc/errdetails"
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)

func validateCreateUser(req *pb.CreateUserRequest) error {
    var violations []*errdetails.BadRequest_FieldViolation

    if req.Name == "" {
        violations = append(violations, &errdetails.BadRequest_FieldViolation{
            Field:       "name",
            Description: "name is required",
        })
    }
    if len(req.Name) > 100 {
        violations = append(violations, &errdetails.BadRequest_FieldViolation{
            Field:       "name",
            Description: "name must be under 100 characters",
        })
    }
    if req.Email == "" {
        violations = append(violations, &errdetails.BadRequest_FieldViolation{
            Field:       "email",
            Description: "email is required",
        })
    }

    if len(violations) > 0 {
        st := status.New(codes.InvalidArgument, "validation failed")
        st, _ = st.WithDetails(&errdetails.BadRequest{
            FieldViolations: violations,
        })
        return st.Err()
    }

    return nil
}

Handling Errors on the Client

// Client-side error handling
user, err := client.GetUser(ctx, &pb.GetUserRequest{Id: "bad-id"})
if err != nil {
    // Extract the gRPC status from the error
    st, ok := status.FromError(err)
    if !ok {
        log.Fatalf("not a gRPC error: %v", err)
    }

    // Check the status code
    switch st.Code() {
    case codes.NotFound:
        fmt.Println("User not found")
    case codes.InvalidArgument:
        fmt.Printf("Bad request: %s\n", st.Message())

        // Extract rich error details
        for _, detail := range st.Details() {
            if badReq, ok := detail.(*errdetails.BadRequest); ok {
                for _, v := range badReq.FieldViolations {
                    fmt.Printf("  - %s: %s\n", v.Field, v.Description)
                }
            }
        }
    case codes.Unavailable:
        fmt.Println("Service unavailable — retrying...")
    default:
        fmt.Printf("RPC error: [%s] %s\n", st.Code(), st.Message())
    }
}

21 Metadata (Headers)

gRPC metadata is equivalent to HTTP headers. It carries key-value pairs alongside RPC calls — authentication tokens, request IDs, tracing info, etc.

import "google.golang.org/grpc/metadata"

// ============ CLIENT SIDE: Sending metadata ============

// Create metadata
md := metadata.New(map[string]string{
    "authorization": "Bearer eyJhbGciOi...",
    "x-request-id":  "req-abc-123",
})

// Attach to context
ctx := metadata.NewOutgoingContext(context.Background(), md)

// Or append to existing metadata
ctx = metadata.AppendToOutgoingContext(ctx,
    "x-custom-header", "value1",
    "x-another", "value2",
)

// Make the call — metadata is sent automatically
user, err := client.GetUser(ctx, req)

// ============ CLIENT SIDE: Reading response metadata ============

var header, trailer metadata.MD
user, err := client.GetUser(ctx, req,
    grpc.Header(&header),   // captures response headers
    grpc.Trailer(&trailer), // captures response trailers
)
fmt.Println("Server version:", header.Get("x-server-version"))

// ============ SERVER SIDE: Reading incoming metadata ============

func (s *UserServer) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.User, error) {
    // Extract metadata from the incoming context
    md, ok := metadata.FromIncomingContext(ctx)
    if !ok {
        return nil, status.Error(codes.Internal, "no metadata")
    }

    // Read a specific header
    authHeader := md.Get("authorization")
    if len(authHeader) == 0 {
        return nil, status.Error(codes.Unauthenticated, "missing auth token")
    }

    requestID := md.Get("x-request-id")
    log.Printf("Request ID: %s", requestID)

    // ============ SERVER SIDE: Sending response metadata ============

    // Send headers (before the response)
    header := metadata.Pairs(
        "x-server-version", "1.2.0",
        "x-request-id", requestID[0],
    )
    grpc.SendHeader(ctx, header)

    // Send trailers (after the response)
    trailer := metadata.Pairs("x-processing-time-ms", "42")
    grpc.SetTrailer(ctx, trailer)

    // ... return the response
    return user, nil
}

22 Interceptors (Middleware)

Unary Server Interceptor

// Logging interceptor — logs every RPC call
func loggingInterceptor(
    ctx context.Context,
    req interface{},
    info *grpc.UnaryServerInfo,
    handler grpc.UnaryHandler,
) (interface{}, error) {
    start := time.Now()

    // Call the actual handler
    resp, err := handler(ctx, req)

    // Log after the call
    duration := time.Since(start)
    st, _ := status.FromError(err)

    log.Printf("method=%s duration=%s code=%s error=%v",
        info.FullMethod, duration, st.Code(), err)

    return resp, err
}

Auth Interceptor

// Authentication interceptor
func authInterceptor(
    ctx context.Context,
    req interface{},
    info *grpc.UnaryServerInfo,
    handler grpc.UnaryHandler,
) (interface{}, error) {
    // Skip auth for health check
    if info.FullMethod == "/grpc.health.v1.Health/Check" {
        return handler(ctx, req)
    }

    // Extract token from metadata
    md, ok := metadata.FromIncomingContext(ctx)
    if !ok {
        return nil, status.Error(codes.Unauthenticated, "no metadata")
    }

    tokens := md.Get("authorization")
    if len(tokens) == 0 {
        return nil, status.Error(codes.Unauthenticated, "missing token")
    }

    // Validate the token
    claims, err := validateJWT(tokens[0])
    if err != nil {
        return nil, status.Error(codes.Unauthenticated, "invalid token")
    }

    // Add user info to context for downstream handlers
    ctx = context.WithValue(ctx, "user_id", claims.UserID)
    ctx = context.WithValue(ctx, "user_role", claims.Role)

    return handler(ctx, req)
}

Recovery Interceptor (Panic Handler)

// Recover from panics — prevents a single bad request from crashing the server
func recoveryInterceptor(
    ctx context.Context,
    req interface{},
    info *grpc.UnaryServerInfo,
    handler grpc.UnaryHandler,
) (resp interface{}, err error) {
    defer func() {
        if r := recover(); r != nil {
            log.Printf("PANIC in %s: %v\n%s", info.FullMethod, r, debug.Stack())
            err = status.Errorf(codes.Internal, "internal error")
        }
    }()
    return handler(ctx, req)
}

Chaining Interceptors

// Register multiple interceptors — they execute in order
grpcServer := grpc.NewServer(
    grpc.ChainUnaryInterceptor(
        recoveryInterceptor,   // 1st: catch panics
        loggingInterceptor,    // 2nd: log the call
        authInterceptor,       // 3rd: authenticate
    ),
    grpc.ChainStreamInterceptor(
        streamLoggingInterceptor,
        streamAuthInterceptor,
    ),
)

Stream Server Interceptor

// Stream interceptor has a slightly different signature
func streamLoggingInterceptor(
    srv interface{},
    ss grpc.ServerStream,
    info *grpc.StreamServerInfo,
    handler grpc.StreamHandler,
) error {
    start := time.Now()
    log.Printf("Stream started: %s", info.FullMethod)

    err := handler(srv, ss)

    log.Printf("Stream ended: %s duration=%s error=%v",
        info.FullMethod, time.Since(start), err)

    return err
}

Client-Side Interceptor

// Client interceptor — add auth token to every outgoing call
func clientAuthInterceptor(
    ctx context.Context,
    method string,
    req, reply interface{},
    cc *grpc.ClientConn,
    invoker grpc.UnaryInvoker,
    opts ...grpc.CallOption,
) error {
    // Inject auth token into metadata
    ctx = metadata.AppendToOutgoingContext(ctx,
        "authorization", "Bearer "+getToken(),
    )
    return invoker(ctx, method, req, reply, cc, opts...)
}

// Use it when creating the client connection
conn, err := grpc.NewClient(
    "localhost:50051",
    grpc.WithTransportCredentials(insecure.NewCredentials()),
    grpc.WithChainUnaryInterceptor(clientAuthInterceptor),
)

23 Deadlines & Timeouts

// CLIENT: Set a timeout (most common)
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
user, err := client.GetUser(ctx, req)

// CLIENT: Set an absolute deadline
ctx, cancel := context.WithDeadline(context.Background(), time.Now().Add(5*time.Second))
defer cancel()
user, err := client.GetUser(ctx, req)

// Check error type
if err != nil {
    st, _ := status.FromError(err)
    if st.Code() == codes.DeadlineExceeded {
        fmt.Println("Request timed out!")
    }
}

// SERVER: Check remaining deadline
func (s *UserServer) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.User, error) {
    // Check if there's a deadline
    deadline, ok := ctx.Deadline()
    if ok {
        remaining := time.Until(deadline)
        log.Printf("Time remaining: %v", remaining)

        if remaining < 100*time.Millisecond {
            return nil, status.Error(codes.DeadlineExceeded, "not enough time")
        }
    }

    // Long operation — check context periodically
    select {
    case <-ctx.Done():
        return nil, status.FromContextError(ctx.Err()).Err()
    case result := <-doExpensiveWork(ctx):
        return result, nil
    }
}

24 TLS & mTLS

Server-Side TLS

// Server with TLS
import "google.golang.org/grpc/credentials"

func main() {
    // Load server certificate and key
    creds, err := credentials.NewServerTLSFromFile("certs/server.crt", "certs/server.key")
    if err != nil {
        log.Fatalf("failed to load certs: %v", err)
    }

    grpcServer := grpc.NewServer(
        grpc.Creds(creds),
    )

    // ... register services and serve
}

// Client connecting with TLS
creds, err := credentials.NewClientTLSFromFile("certs/ca.crt", "server.example.com")
if err != nil {
    log.Fatal(err)
}

conn, err := grpc.NewClient(
    "server.example.com:50051",
    grpc.WithTransportCredentials(creds),
)

Mutual TLS (mTLS)

// mTLS — both server AND client present certificates
import (
    "crypto/tls"
    "crypto/x509"
    "os"
    "google.golang.org/grpc/credentials"
)

// Server with mTLS
func newMTLSServer() *grpc.Server {
    // Load server certificate
    serverCert, err := tls.LoadX509KeyPair("certs/server.crt", "certs/server.key")
    if err != nil {
        log.Fatal(err)
    }

    // Load CA certificate to verify clients
    caCert, err := os.ReadFile("certs/ca.crt")
    if err != nil {
        log.Fatal(err)
    }

    caPool := x509.NewCertPool()
    caPool.AppendCertsFromPEM(caCert)

    tlsConfig := &tls.Config{
        Certificates: []tls.Certificate{serverCert},
        ClientAuth:   tls.RequireAndVerifyClientCert,  // ← require client cert
        ClientCAs:    caPool,
        MinVersion:   tls.VersionTLS13,
    }

    creds := credentials.NewTLS(tlsConfig)
    return grpc.NewServer(grpc.Creds(creds))
}

25 Health Checking & Reflection

Health Checking

gRPC has a standard health checking protocol. Kubernetes, load balancers, and service meshes use it to determine if your service is ready.

import (
    "google.golang.org/grpc/health"
    healthpb "google.golang.org/grpc/health/grpc_health_v1"
)

func main() {
    grpcServer := grpc.NewServer()

    // Create and register health server
    healthServer := health.NewServer()
    healthpb.RegisterHealthServer(grpcServer, healthServer)

    // Set service status
    healthServer.SetServingStatus(
        "user.v1.UserService",             // service name
        healthpb.HealthCheckResponse_SERVING, // status
    )

    // Set overall server status
    healthServer.SetServingStatus(
        "",                                   // empty string = overall server
        healthpb.HealthCheckResponse_SERVING,
    )

    // When shutting down or during maintenance:
    // healthServer.SetServingStatus("", healthpb.HealthCheckResponse_NOT_SERVING)
}

# Test health from command line
grpcurl -plaintext localhost:50051 grpc.health.v1.Health/Check

# Check specific service
grpcurl -plaintext -d '{"service": "user.v1.UserService"}' \
  localhost:50051 grpc.health.v1.Health/Check

Server Reflection

Reflection lets clients (like grpcurl) discover your services and methods at runtime, without having the .proto files.

import "google.golang.org/grpc/reflection"

func main() {
    grpcServer := grpc.NewServer()

    // Register your services...
    pb.RegisterUserServiceServer(grpcServer, userService)

    // Enable reflection — only for dev/staging, disable in prod
    reflection.Register(grpcServer)

    // ...
}

grpcurl & grpcui — Debugging Tools

# Install
brew install grpcurl grpcui

# List all services
grpcurl -plaintext localhost:50051 list

# Describe a service
grpcurl -plaintext localhost:50051 describe user.v1.UserService

# Describe a message
grpcurl -plaintext localhost:50051 describe user.v1.User

# Call an RPC
grpcurl -plaintext -d '{"name": "Alice", "email": "alice@example.com", "age": 28}' \
  localhost:50051 user.v1.UserService/CreateUser

# grpcui — web-based UI for gRPC (like Postman for gRPC)
grpcui -plaintext localhost:50051
# Opens a browser with a form-based UI for making RPC calls

26 gRPC Gateway (REST Proxy)

Annotating your Proto for REST

syntax = "proto3";
package user.v1;

import "google/api/annotations.proto";

service UserService {
  rpc CreateUser(CreateUserRequest) returns (User) {
    option (google.api.http) = {
      post: "/v1/users"
      body: "*"
    };
  }

  rpc GetUser(GetUserRequest) returns (User) {
    option (google.api.http) = {
      get: "/v1/users/{id}"     // {id} maps to GetUserRequest.id
    };
  }

  rpc UpdateUser(UpdateUserRequest) returns (User) {
    option (google.api.http) = {
      patch: "/v1/users/{user.id}"
      body: "user"
    };
  }

  rpc DeleteUser(DeleteUserRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1/users/{id}"
    };
  }

  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse) {
    option (google.api.http) = {
      get: "/v1/users"           // query params: ?page_size=10&page_token=abc
    };
  }
}

Gateway Server

// cmd/gateway/main.go
package main

import (
    "context"
    "log"
    "net/http"

    "github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"

    gw "github.com/yourorg/grpc-demo/gen/user/v1"
)

func main() {
    ctx := context.Background()

    // Create a gRPC-Gateway mux
    mux := runtime.NewServeMux()

    // Register the gRPC service endpoint
    opts := []grpc.DialOption{grpc.WithTransportCredentials(insecure.NewCredentials())}
    err := gw.RegisterUserServiceHandlerFromEndpoint(ctx, mux, "localhost:50051", opts)
    if err != nil {
        log.Fatal(err)
    }

    // Start HTTP server
    log.Println("REST gateway listening on :8080")
    if err := http.ListenAndServe(":8080", mux); err != nil {
        log.Fatal(err)
    }
}

// Now you can:
// curl -X POST http://localhost:8080/v1/users -d '{"name":"Alice","email":"alice@example.com"}'
// curl http://localhost:8080/v1/users/u-123
// curl http://localhost:8080/v1/users?page_size=10

27 Testing gRPC Services

In-Process Testing (No Network)

// internal/service/user_test.go
package service

import (
    "context"
    "net"
    "testing"

    "google.golang.org/grpc"
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/credentials/insecure"
    "google.golang.org/grpc/status"
    "google.golang.org/grpc/test/bufconn"

    pb "github.com/yourorg/grpc-demo/gen/user/v1"
)

const bufSize = 1024 * 1024

// Setup: create an in-memory gRPC server (no real TCP)
func setupTest(t *testing.T) (pb.UserServiceClient, func()) {
    t.Helper()

    // bufconn creates an in-memory listener — no network needed
    lis := bufconn.Listen(bufSize)

    srv := grpc.NewServer()
    pb.RegisterUserServiceServer(srv, NewUserServer())

    go srv.Serve(lis)

    // Create client that connects through bufconn
    conn, err := grpc.NewClient(
        "passthrough://bufnet",
        grpc.WithContextDialer(func(ctx context.Context, addr string) (net.Conn, error) {
            return lis.DialContext(ctx)
        }),
        grpc.WithTransportCredentials(insecure.NewCredentials()),
    )
    if err != nil {
        t.Fatalf("failed to dial: %v", err)
    }

    client := pb.NewUserServiceClient(conn)

    cleanup := func() {
        conn.Close()
        srv.Stop()
    }

    return client, cleanup
}

// Test: CreateUser success
func TestCreateUser(t *testing.T) {
    client, cleanup := setupTest(t)
    defer cleanup()

    ctx := context.Background()

    user, err := client.CreateUser(ctx, &pb.CreateUserRequest{
        Name:  "Alice",
        Email: "alice@example.com",
        Age:   28,
    })

    if err != nil {
        t.Fatalf("CreateUser failed: %v", err)
    }
    if user.Name != "Alice" {
        t.Errorf("expected name Alice, got %s", user.Name)
    }
    if user.Id == "" {
        t.Error("expected non-empty ID")
    }
}

// Test: GetUser not found
func TestGetUser_NotFound(t *testing.T) {
    client, cleanup := setupTest(t)
    defer cleanup()

    _, err := client.GetUser(context.Background(), &pb.GetUserRequest{
        Id: "nonexistent",
    })

    if err == nil {
        t.Fatal("expected error, got nil")
    }

    st, ok := status.FromError(err)
    if !ok {
        t.Fatalf("expected gRPC status error, got: %v", err)
    }
    if st.Code() != codes.NotFound {
        t.Errorf("expected NotFound, got %s", st.Code())
    }
}

// Test: CreateUser validation
func TestCreateUser_Validation(t *testing.T) {
    client, cleanup := setupTest(t)
    defer cleanup()

    tests := []struct {
        name    string
        req     *pb.CreateUserRequest
        wantCode codes.Code
    }{
        {
            name:     "missing name",
            req:      &pb.CreateUserRequest{Email: "a@b.com"},
            wantCode: codes.InvalidArgument,
        },
        {
            name:     "missing email",
            req:      &pb.CreateUserRequest{Name: "Alice"},
            wantCode: codes.InvalidArgument,
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            _, err := client.CreateUser(context.Background(), tt.req)
            if err == nil {
                t.Fatal("expected error")
            }
            st, _ := status.FromError(err)
            if st.Code() != tt.wantCode {
                t.Errorf("expected %s, got %s", tt.wantCode, st.Code())
            }
        })
    }
}

28 Best Practices

Proto Design

// BAD — reusing User as both input and output
rpc CreateUser(User) returns (User);
rpc UpdateUser(User) returns (User);

// GOOD — dedicated messages per RPC
rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse);

message UpdateUserRequest {
  User                          user        = 1;
  google.protobuf.FieldMask     update_mask = 2;
}

// BAD — ACTIVE could conflict with another enum
enum UserStatus { UNSPECIFIED = 0; ACTIVE = 1; }
enum OrderStatus { UNSPECIFIED = 0; ACTIVE = 1; }  // CONFLICT!

// GOOD — prefixed, no conflicts
enum UserStatus { USER_STATUS_UNSPECIFIED = 0; USER_STATUS_ACTIVE = 1; }
enum OrderStatus { ORDER_STATUS_UNSPECIFIED = 0; ORDER_STATUS_ACTIVE = 1; }

Server Implementation

// Always do this
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
resp, err := client.GetUser(ctx, req)

func (s *Server) HeavyOperation(ctx context.Context, req *pb.Request) (*pb.Response, error) {
    // Step 1
    result1, err := s.db.Query(ctx, ...)
    if ctx.Err() != nil {
        return nil, status.FromContextError(ctx.Err()).Err()
    }

    // Step 2
    result2, err := s.externalAPI.Call(ctx, ...)
    if ctx.Err() != nil {
        return nil, status.FromContextError(ctx.Err()).Err()
    }

    // ...
}

func main() {
    grpcServer := grpc.NewServer()
    // ... register services

    // Graceful shutdown on signal
    go func() {
        sigCh := make(chan os.Signal, 1)
        signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
        <-sigCh

        log.Println("Shutting down gracefully...")
        grpcServer.GracefulStop()
    }()

    grpcServer.Serve(lis)
}

Production Checklist