Skip to main content

gRPC (gRPC Remote Procedure Calls)

gRPC is a high-performance, open-source universal RPC framework developed by Google. It uses Protocol Buffers (protobuf) as its interface definition language and enables efficient communication between services with features like bidirectional streaming, flow control, authentication, and more.

Overview​

gRPC is designed for modern distributed systems where performance, type safety, and language interoperability are crucial. It generates client and server code from service definitions written in Protocol Buffers, ensuring consistency across different programming languages and platforms.

Core Features​

  1. Protocol Buffers: Efficient binary serialization with schema evolution
  2. HTTP/2: Multiplexing, server push, and header compression
  3. Streaming: Unary, server streaming, client streaming, and bidirectional streaming
  4. Language Agnostic: Support for 10+ programming languages
  5. Authentication: Built-in support for SSL/TLS and OAuth2
  6. Load Balancing: Client-side load balancing and health checking

Communication Patterns​

service UserService {
  // Unary RPC: Single request, single response
  rpc GetUser(GetUserRequest) returns (User);
  
  // Server streaming: Single request, multiple responses
  rpc ListUsers(ListUsersRequest) returns (stream User);
  
  // Client streaming: Multiple requests, single response
  rpc CreateUsers(stream CreateUserRequest) returns (CreateUsersResponse);
  
  // Bidirectional streaming: Multiple requests and responses
  rpc ChatStream(stream ChatMessage) returns (stream ChatMessage);
}

When to Use gRPC​

Ideal for:​

  • Microservices Communication: High-performance service-to-service calls
  • Real-time Applications: Streaming data and low-latency requirements
  • Polyglot Environments: Multiple programming languages in the same system
  • API-First Development: Strong typing and contract-first approach
  • Internal Services: Where you control both client and server
  • High Throughput Systems: Better performance than REST for large volumes

Consider REST/GraphQL When:​

  • Browser Support: Limited browser support (requires grpc-web proxy)
  • Public APIs: REST/GraphQL have better ecosystem support
  • Simple CRUD: REST might be more straightforward
  • Caching Requirements: HTTP caching is more mature
  • Debugging: Text-based protocols are easier to debug
  • Legacy Integration: Existing systems expect HTTP/JSON

Protocol Buffer Definitions​

Basic Service Definition​

syntax = "proto3";

package user.v1;

option go_package = "github.com/company/api/user/v1;userv1";

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

// User message definition
message User {
  string id = 1;
  string email = 2;
  string name = 3;
  string avatar_url = 4;
  UserRole role = 5;
  google.protobuf.Timestamp created_at = 6;
  google.protobuf.Timestamp updated_at = 7;
}

// Enums for type safety
enum UserRole {
  USER_ROLE_UNSPECIFIED = 0;
  USER_ROLE_MEMBER = 1;
  USER_ROLE_ADMIN = 2;
  USER_ROLE_OWNER = 3;
}

// Request/Response messages
message GetUserRequest {
  string id = 1;
}

message ListUsersRequest {
  int32 page_size = 1;
  string page_token = 2;
  string filter = 3;  // e.g., "role=ADMIN"
}

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

message CreateUserRequest {
  string email = 1;
  string name = 2;
  UserRole role = 3;
}

message UpdateUserRequest {
  string id = 1;
  User user = 2;
  // Field mask for partial updates
  google.protobuf.FieldMask update_mask = 3;
}

message DeleteUserRequest {
  string id = 1;
}

// Service definition
service UserService {
  // Unary RPCs
  rpc GetUser(GetUserRequest) returns (User);
  rpc CreateUser(CreateUserRequest) returns (User);
  rpc UpdateUser(UpdateUserRequest) returns (User);
  rpc DeleteUser(DeleteUserRequest) returns (google.protobuf.Empty);
  
  // Server streaming RPC
  rpc ListUsers(ListUsersRequest) returns (stream User);
  
  // Client streaming RPC
  rpc CreateBulkUsers(stream CreateUserRequest) returns (CreateBulkUsersResponse);
  
  // Bidirectional streaming RPC
  rpc UserUpdates(stream UserUpdateEvent) returns (stream UserUpdateEvent);
}

message CreateBulkUsersResponse {
  repeated User users = 1;
  int32 created_count = 2;
  repeated string errors = 3;
}

message UserUpdateEvent {
  string user_id = 1;
  UserUpdateType type = 2;
  User user = 3;
}

enum UserUpdateType {
  USER_UPDATE_TYPE_UNSPECIFIED = 0;
  USER_UPDATE_TYPE_CREATED = 1;
  USER_UPDATE_TYPE_UPDATED = 2;
  USER_UPDATE_TYPE_DELETED = 3;
}

Advanced Protobuf Patterns​

// Using oneof for union types
message NotificationPayload {
  oneof payload {
    EmailPayload email = 1;
    PushPayload push = 2;
    SMSPayload sms = 3;
  }
}

message EmailPayload {
  string subject = 1;
  string body = 2;
  repeated string recipients = 3;
}

// Using maps for flexible data
message UserMetadata {
  map<string, string> labels = 1;
  map<string, UserPreference> preferences = 2;
}

message UserPreference {
  string value = 1;
  bool enabled = 2;
}

// Well-known types for common patterns
message UserActivity {
  string user_id = 1;
  string action = 2;
  google.protobuf.Timestamp timestamp = 3;
  google.protobuf.Duration duration = 4;
  google.protobuf.Struct metadata = 5;  // Flexible JSON-like data
}

Implementation Examples​

Go Server Implementation​

package main

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

    "google.golang.org/grpc"
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
    "google.golang.org/protobuf/types/known/emptypb"
    "google.golang.org/protobuf/types/known/timestamppb"
    
    userv1 "github.com/company/api/user/v1"
)

type userServer struct {
    userv1.UnimplementedUserServiceServer
    users map[string]*userv1.User
}

func newUserServer() *userServer {
    return &userServer{
        users: make(map[string]*userv1.User),
    }
}

// Unary RPC implementation
func (s *userServer) GetUser(ctx context.Context, req *userv1.GetUserRequest) (*userv1.User, error) {
    if req.Id == "" {
        return nil, status.Error(codes.InvalidArgument, "user ID is required")
    }

    user, exists := s.users[req.Id]
    if !exists {
        return nil, status.Error(codes.NotFound, "user not found")
    }

    return user, nil
}

func (s *userServer) CreateUser(ctx context.Context, req *userv1.CreateUserRequest) (*userv1.User, error) {
    // Validation
    if req.Email == "" {
        return nil, status.Error(codes.InvalidArgument, "email is required")
    }
    if req.Name == "" {
        return nil, status.Error(codes.InvalidArgument, "name is required")
    }

    // Check for existing user
    for _, user := range s.users {
        if user.Email == req.Email {
            return nil, status.Error(codes.AlreadyExists, "user with this email already exists")
        }
    }

    // Create new user
    user := &userv1.User{
        Id:        generateID(),
        Email:     req.Email,
        Name:      req.Name,
        Role:      req.Role,
        CreatedAt: timestamppb.Now(),
        UpdatedAt: timestamppb.Now(),
    }

    s.users[user.Id] = user
    return user, nil
}

// Server streaming RPC implementation
func (s *userServer) ListUsers(req *userv1.ListUsersRequest, stream userv1.UserService_ListUsersServer) error {
    for _, user := range s.users {
        // Apply filtering if specified
        if req.Filter != "" {
            if !s.matchesFilter(user, req.Filter) {
                continue
            }
        }

        if err := stream.Send(user); err != nil {
            return status.Error(codes.Internal, "failed to send user")
        }
    }

    return nil
}

func main() {
    lis, err := net.Listen("tcp", ":50051")
    if err != nil {
        log.Fatalf("Failed to listen: %v", err)
    }

    s := grpc.NewServer()
    userv1.RegisterUserServiceServer(s, newUserServer())

    log.Println("gRPC server listening on :50051")
    if err := s.Serve(lis); err != nil {
        log.Fatalf("Failed to serve: %v", err)
    }
}

Node.js Implementation​

import * as grpc from '@grpc/grpc-js';
import * as protoLoader from '@grpc/proto-loader';

// Load proto file
const packageDefinition = protoLoader.loadSync('./user.proto', {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
});

const userProto = grpc.loadPackageDefinition(packageDefinition).user.v1 as any;

// Server implementation
class UserServiceImpl {
  private users = new Map<string, any>();

  async getUser(call: any, callback: any) {
    const { id } = call.request;
    
    if (!id) {
      return callback({
        code: grpc.status.INVALID_ARGUMENT,
        message: 'User ID is required'
      });
    }

    const user = this.users.get(id);
    if (!user) {
      return callback({
        code: grpc.status.NOT_FOUND,
        message: 'User not found'
      });
    }

    callback(null, user);
  }

  async createUser(call: any, callback: any) {
    const { email, name, role } = call.request;

    if (!email || !name) {
      return callback({
        code: grpc.status.INVALID_ARGUMENT,
        message: 'Email and name are required'
      });
    }

    const user = {
      id: `user_${Date.now()}`,
      email,
      name,
      role: role || 'USER_ROLE_MEMBER',
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString()
    };

    this.users.set(user.id, user);
    callback(null, user);
  }

  listUsers(call: any) {
    for (const user of this.users.values()) {
      call.write(user);
    }
    call.end();
  }
}

// Server setup
function startServer() {
  const server = new grpc.Server();
  
  server.addService(userProto.UserService.service, new UserServiceImpl());

  const port = '0.0.0.0:50051';
  server.bindAsync(port, grpc.ServerCredentials.createInsecure(), (err, boundPort) => {
    if (err) {
      console.error('Failed to bind server:', err);
      return;
    }

    console.log(`gRPC server listening on ${boundPort}`);
    server.start();
  });
}

if (require.main === module) {
  startServer();
}

Best Practices​

1. API Design​

// Use clear, consistent naming
rpc CreateUser(CreateUserRequest) returns (User);
rpc GetUser(GetUserRequest) returns (User);
rpc UpdateUser(UpdateUserRequest) returns (User);
rpc DeleteUser(DeleteUserRequest) returns (google.protobuf.Empty);

// Version your APIs
package user.v1;
package user.v2;

// Use standard field types
google.protobuf.Timestamp created_at = 1;
google.protobuf.Duration timeout = 2;
google.protobuf.FieldMask update_mask = 3;

2. Error Handling​

// Use appropriate gRPC status codes
return status.Error(codes.InvalidArgument, "user ID is required")
return status.Error(codes.NotFound, "user not found")
return status.Error(codes.AlreadyExists, "user already exists")
return status.Error(codes.PermissionDenied, "insufficient permissions")

3. Security​

// Always validate input
if req.GetEmail() == "" {
    return status.Error(codes.InvalidArgument, "email is required")
}

// Use TLS in production
creds, _ := credentials.NewServerTLSFromFile("cert.pem", "key.pem")
s := grpc.NewServer(grpc.Creds(creds))

4. Performance​

// Use connection pooling
// Implement proper timeouts
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

// Use streaming for large datasets
// Implement proper pagination

Testing gRPC Services​

func TestUserService(t *testing.T) {
    // Create in-memory server
    lis := bufconn.Listen(1024 * 1024)
    s := grpc.NewServer()
    userv1.RegisterUserServiceServer(s, newUserServer())

    go func() {
        if err := s.Serve(lis); err != nil {
            t.Errorf("Server exited with error: %v", err)
        }
    }()
    defer s.Stop()

    // Test cases...
}