gRPC Best Practices — Production-Ready gRPC Service Design and Operations

syntax = "proto3";

package threat.v1;

import "google/protobuf/field_mask.proto";
import "google/api/annotations.proto";

// ✅ GOOD: Specific service with clear boundaries
service ThreatService {
  // Use explicit RPC names (verb + noun)
  rpc ListThreats(ListThreatsRequest) returns (ListThreatsResponse);
  rpc GetThreat(GetThreatRequest) returns (Threat);
  rpc CreateThreat(CreateThreatRequest) returns (Threat);
  rpc UpdateThreat(UpdateThreatRequest) returns (Threat);
  rpc DeleteThreat(DeleteThreatRequest) returns (DeleteThreatResponse);
  
  // Batch operations where atomicity matters
  rpc BatchCreateThreats(BatchCreateThreatsRequest)
      returns (BatchCreateThreatsResponse);
  
  // Long-running operations
  rpc AnalyzeThreat(AnalyzeThreatRequest)
      returns (google.longrunning.Operation);
}

// ✅ GOOD: Small, focused request messages
message ListThreatsRequest {
  int32 page_size = 1;  // Use int32, not uint32
  string page_token = 2;
  string filter = 3;    // AIP-160 filter syntax
  string order_by = 4;  // "severity desc, name asc"
}

// ✅ GOOD: Response includes next page token
message ListThreatsResponse {
  repeated Threat threats = 1;
  string next_page_token = 2;
  int32 total_size = 3;
}

// ❌ BAD: Single message with everything
message BadRequest {
  string query = 1;
  int64 user_id = 2;       // Don't expose internal IDs
  int32 limit = 3;
  int32 offset = 4;         // Use cursor, not offset
  string sort = 5;
  bool include_deleted = 6;
  bool include_archived = 7;
  string device_id = 8;
  string threat_type = 9;
  // ... 40 more fields
}

package main

func performanceBestPractices() {
    // 1. Reuse channels across requests
    conn := getSharedChannel()
    
    // 2. Set proper timeouts
    ctx, cancel := context.WithTimeout(
        context.Background(), 5*time.Second)
    defer cancel()
    
    // 3. Configure keepalive
    grpc.Dial("target",
        grpc.WithKeepaliveParams(keepalive.ClientParameters{
            Time: 30 * time.Second,
            Timeout: 10 * time.Second,
            PermitWithoutStream: true,
        }),
    )
    
    // 4. Use streaming for bulk data
    // Instead of: for each item { unaryCall(item) }
    // Use: stream := client.BulkUpload(ctx)
    //       for each item { stream.Send(item) }
    
    // 5. Enable compression for large payloads
    // grpc.UseCompressor(gzip.Name)
    
    // 6. Set appropriate message sizes
    // grpc.WithMaxMsgSize(4 * 1024 * 1024)
    
    // 7. Use client-side load balancing
    // grpc.WithDefaultServiceConfig(`{
    //   "loadBalancingConfig": [{"round_robin": {}}]
    // }`)
    
    // 8. Use protobuf field numbers 1-15 for hot fields
    // (They encode in 1 byte instead of 2+)
}

// 9. Server-side streaming for large responses
// Good: Paginate with cursor (ListThreats)
// Better: Stream results for >100 items
// Best: Stream with configurable batch size

// 10. Use async/streaming for fire-and-forget
// Don't: Wait for ack on each log entry
// Do: Use client-streaming to batch logs

# Health check runbook
function health_check() {
  SERVICE=$1
  echo "Checking $SERVICE..."
  
  # 1. Check gRPC health probe
  grpcurl -plaintext localhost:50051 \
    grpc.health.v1.Health/Check
  
  # 2. Check Prometheus metrics
  curl -s localhost:9090/metrics | grep grpc_requests
  
  # 3. Check recent error logs
  kubectl logs -l app=$SERVICE --tail=50 | grep '"level":"error"'
  
  # 4. Check active connections
  kubectl exec deploy/$SERVICE -- ss -tan | grep 50051
}

# Deployment checklist
function deploy_service() {
  SERVICE=$1
  TAG=$2
  
  echo "=== Pre-deployment checks ==="
  # Verify health checks pass
  # Verify benchmark results
  # Verify no breaking protobuf changes
  # Verify migration scripts
  
  echo "=== Deploying $SERVICE:$TAG ==="
  kubectl set image deploy/$SERVICE \
    $SERVICE=dodatech/$SERVICE:$TAG
  
  echo "=== Post-deployment checks ==="
  # Wait for rollout
  kubectl rollout status deploy/$SERVICE
  
  # Verify health
  health_check $SERVICE
  
  # Verify metrics
  echo "Check error rate < 0.1%"
  echo "Check p99 latency < baseline + 10%"
}