gRPC Development

This skill covers best practices for building gRPC-based services and APIs using Protocol Buffers, including service design, streaming patterns, interceptors, security, and observability.

Workflow for Building a gRPC Service

1. Define the service contract — Write .proto files with service definitions, RPC methods, and message types following the style and naming conventions below.
2. Generate language stubs — Run protoc with the appropriate language plugin (e.g., protoc-gen-go-grpc, grpcio-tools) to produce server and client code.
3. Implement the server — Create handler functions for each RPC method, register them with a gRPC server, and configure TLS, interceptors, and health checks.
4. Implement the client — Create a channel to the server, instantiate the generated client stub, and call RPC methods with proper deadlines and error handling.
5. Add interceptors — Wire in server and client interceptors for logging, authentication, metrics, and tracing.
6. Write tests — Unit-test handlers with mocked dependencies; integration-test with a real gRPC connection.
7. Deploy and observe — Enable distributed tracing (OpenTelemetry), structured logging, and metrics dashboards before going to production.

Core Principles

• gRPC uses Protocol Buffers as both its Interface Definition Language (IDL) and message interchange format
• Design services around the idea of defining methods that can be called remotely with their parameters and return types
• Prioritize type safety, performance, and backward compatibility
• Leave NO todos, placeholders, or missing pieces in the implementation

Protocol Buffer Best Practices

File Organization (1-1-1 Pattern)

• Structure definitions with one top-level entity (message, enum, or extension) per .proto file
• Correspond each .proto file to a single build rule
• This promotes small, modular proto definitions
• Benefits include simplified refactoring, improved build times, and smaller binary sizes

Message Design

• Use structured messages for extensibility - Protocol Buffers supports adding fields without breaking existing clients
• Be careful to use structs in places you may want to add fields later
• Don't re-use messages across RPCs - APIs may change over time, avoid coupling separate RPC calls tightly together
• Fields should always be independent of each other - don't have one field influence the semantic meaning of another

Field Guidelines

• Use descriptive field names with underscore_separated_names
• Reserve field numbers for deleted fields to prevent future conflicts
• Use optional for fields that may not always be present
• Consider using oneof when users need to choose between mutually exclusive options

Enum Best Practices

• Ensure the first value is always 0
• Use an "UNSPECIFIED" default value (e.g., STATUS_UNSPECIFIED = 0)
• Use prefixes to avoid naming collisions (e.g., ORDER_STATUS_CREATED vs STATUS_PENDING)
• Reserve enum values that are removed to prevent accidental reuse

Style Guidelines

• Keep line length to 80 characters
• Prefer double quotes for strings
• Package names should be in lowercase
• Use CamelCase (with initial capital) for message names
• Use underscore_separated_names for field names
• Use CamelCase for service and RPC method names

Service Design

RPC Patterns

• Unary RPC: Client sends single request, server responds with single response
• Server Streaming: Client sends request, server responds with stream of messages
• Client Streaming: Client sends stream of messages, server responds with single response
• Bidirectional Streaming: Both sides send streams of messages

Example: Proto Definition

syntax = "proto3";

package order.v1;

option go_package = "gen/order/v1;orderv1";

// OrderService manages customer orders.
service OrderService {
  // Creates a new order and returns the created resource.
  rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
  // Streams real-time status updates for an order.
  rpc WatchOrder(WatchOrderRequest) returns (stream OrderStatus);
}

message CreateOrderRequest {
  string customer_id = 1;
  repeated OrderItem items = 2;
}

message CreateOrderResponse {
  string order_id = 1;
  OrderStatus status = 2;
}

message WatchOrderRequest {
  string order_id = 1;
}

message OrderItem {
  string product_id = 1;
  int32 quantity = 2;
}

message OrderStatus {
  string order_id = 1;
  OrderState state = 2;
  string updated_at = 3;
}

enum OrderState {
  ORDER_STATE_UNSPECIFIED = 0;
  ORDER_STATE_CREATED = 1;
  ORDER_STATE_PROCESSING = 2;
  ORDER_STATE_SHIPPED = 3;
  ORDER_STATE_DELIVERED = 4;
}

Example: Go Server Implementation

package main

import (
	"context"
	"log"
	"net"
	"time"

	"google.golang.org/grpc"
	"google.golang.org/grpc/codes"
	"google.golang.org/grpc/status"

	pb "example.com/gen/order/v1"
)

type orderServer struct {
	pb.UnimplementedOrderServiceServer
}

func (s *orderServer) CreateOrder(ctx context.Context, req *pb.CreateOrderRequest) (*pb.CreateOrderResponse, error) {
	if req.GetCustomerId() == "" {
		return nil, status.Error(codes.InvalidArgument, "customer_id is required")
	}
	orderID := "ord-" + time.Now().Format("20060102150405")
	return &pb.CreateOrderResponse{
		OrderId: orderID,
		Status: &pb.OrderStatus{
			OrderId: orderID,
			State:   pb.OrderState_ORDER_STATE_CREATED,
		},
	}, nil
}

func (s *orderServer) WatchOrder(req *pb.WatchOrderRequest, stream pb.OrderService_WatchOrderServer) error {
	for i, state := range []pb.OrderState{
		pb.OrderState_ORDER_STATE_PROCESSING,
		pb.OrderState_ORDER_STATE_SHIPPED,
		pb.OrderState_ORDER_STATE_DELIVERED,
	} {
		select {
		case <-stream.Context().Done():
			return stream.Context().Err()
		case <-time.After(time.Duration(i) * time.Second):
			if err := stream.Send(&pb.OrderStatus{
				OrderId:   req.GetOrderId(),
				State:     state,
				UpdatedAt: time.Now().Format(time.RFC3339),
			}); err != nil {
				return err
			}
		}
	}
	return nil
}

func main() {
	lis, err := net.Listen("tcp", ":50051")
	if err != nil {
		log.Fatalf("failed to listen: %v", err)
	}
	srv := grpc.NewServer(
		grpc.UnaryInterceptor(loggingUnaryInterceptor),
	)
	pb.RegisterOrderServiceServer(srv, &orderServer{})
	log.Println("serving on :50051")
	if err := srv.Serve(lis); err != nil {
		log.Fatalf("failed to serve: %v", err)
	}
}

// loggingUnaryInterceptor logs each unary RPC call.
func loggingUnaryInterceptor(
	ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler,
) (any, error) {
	start := time.Now()
	resp, err := handler(ctx, req)
	log.Printf("method=%s duration=%s err=%v", info.FullMethod, time.Since(start), err)
	return resp, err
}

API Design

• Design clear, intuitive service interfaces
• Group related methods in the same service
• Use meaningful method names that describe the action
• Document each RPC with comments describing behavior, parameters, and return values

Performance Optimization

Channel Management

• Reuse channels when working with gRPC
• Creating a gRPC channel is costly as it creates a new HTTP/2 connection
• Implement connection pooling for high-throughput scenarios
• Configure keepalive settings appropriately

Message Optimization

• Keep messages reasonably sized - large messages impact performance
• Consider streaming for large data transfers
• Use compression for bandwidth-constrained environments
• Avoid deeply nested message structures

Error Handling

Status Codes

• Use appropriate gRPC status codes (OK, INVALID_ARGUMENT, NOT_FOUND, etc.)
• Include meaningful error messages in status details
• Use rich error details for complex error scenarios
• Document expected error conditions in service definitions

Retry Logic

• Implement retry with exponential backoff for transient failures
• Use deadlines/timeouts for all RPC calls
• Handle UNAVAILABLE and RESOURCE_EXHAUSTED with retries
• Don't retry non-idempotent operations blindly

Security

Authentication

• Use TLS for transport security in production
• Implement per-RPC authentication using metadata/headers
• Support multiple authentication mechanisms (JWT, OAuth2, mTLS)
• Validate credentials on every request

Authorization

• Implement method-level access control
• Use interceptors for centralized authorization logic
• Validate all input data regardless of authentication status
• Follow the principle of least privilege

Interceptors and Middleware

Server Interceptors

• Use interceptors for cross-cutting concerns (logging, auth, metrics)
• Order interceptors carefully - execution order matters
• Keep interceptors focused on single responsibilities
• Handle errors gracefully within interceptors

Client Interceptors

• Add metadata (headers) for tracing and authentication
• Implement request/response logging
• Add automatic retry logic
• Collect client-side metrics

Testing

Unit Testing

• Mock gRPC services for isolated testing
• Test message serialization/deserialization
• Verify error handling paths
• Test interceptor logic independently

Integration Testing

• Test with real gRPC connections where possible
• Verify streaming behavior end-to-end
• Test timeout and cancellation scenarios
• Load test with realistic traffic patterns

Observability

Distributed Tracing

• Use OpenTelemetry for distributed tracing across service boundaries
• Propagate trace context in metadata
• Instrument both client and server sides
• Start spans for each RPC call

Metrics

• Track RPC latency histograms
• Monitor error rates by method and status code
• Count active connections and streams
• Alert on anomalies and SLA violations

Logging

• Use structured logging with consistent fields
• Log RPC method, duration, and status
• Include trace IDs for correlation
• Avoid logging sensitive data

Language-Specific Guidelines

Go

• Use the official google.golang.org/grpc package
• Implement services as interface types
• Use context for cancellation and deadlines
• Leverage code generation with protoc-gen-go-grpc

Python

• Use grpcio and grpcio-tools packages
• Implement async services with grpcio-aio for better concurrency
• Use type hints with generated stubs
• Handle blocking calls appropriately in async contexts

Node.js/TypeScript

• Use @grpc/grpc-js (pure JavaScript implementation)
• Consider using nice-grpc for better TypeScript support
• Leverage async/await patterns
• Use static codegen for type safety