Grpc Development

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