gRPC Deep Dive

gRPC (Google Remote Procedure Call) bắt đầu từ hệ thống nội bộ "Stubby" của Google, được open-source năm 2016. Thiết kế cho microservices: strongly-typed contracts, binary wire format, streaming built-in, và code generation cho 10+ ngôn ngữ.

gRPC dùng HTTP/2 làm transport (multiplexed streams, header compression, bidirectional) và Protocol Buffers làm serialization format mặc định (có thể thay bằng JSON, Thrift, v.v.).

Protocol Buffers (Protobuf) là ngôn ngữ định nghĩa schema và serialization format của Google. Proto3 là phiên bản hiện đại nhất, đơn giản hơn proto2 (bỏ required fields, default values, extensions).

syntax = "proto3";

package users.v1;

option go_package = "github.com/myorg/users/v1;usersv1";

import "google/protobuf/timestamp.proto";

// Scalar types: double, float, int32, int64, uint32, uint64,
// sint32, sint64, fixed32, fixed64, sfixed32, sfixed64, bool, string, bytes

message User {
  uint64 id           = 1;   // field number 1-15 = 1-byte tag (hot fields)
  string name         = 2;
  string email        = 3;
  UserStatus status   = 4;
  repeated string tags = 5;  // repeated = array/list
  map<string, string> metadata = 6;

  oneof contact {             // only one of these can be set
    string phone = 7;
    string slack = 8;
  }

  google.protobuf.Timestamp created_at = 9;

  reserved 10, 11;            // never reuse these numbers
  reserved "old_field";       // never reuse this name
}

enum UserStatus {
  USER_STATUS_UNSPECIFIED = 0;   // proto3: enum must start with 0
  USER_STATUS_ACTIVE = 1;
  USER_STATUS_SUSPENDED = 2;
}

Field Numbers

Field numbers là duy nhất và vĩnh viễn. Chúng xác định field trong wire format — không phải field name. Điều này cho phép rename field mà không breaking.

• 1–15: encode bằng 1 byte tag → dùng cho fields hot/phổ biến
• 16–2047: encode bằng 2 bytes tag
• 19000–19999: reserved for Protobuf internal
• Không bao giờ tái sử dụng số đã xóa → dùng reserved

Default Values trong Proto3

Protobuf serialize thành binary — compact và nhanh. Hiểu wire format giúp debug và hiểu tại sao Protobuf nhỏ hơn JSON.

Ví dụ thực tế — decode hexdump

Proto message: { name: "Alice", id: 1 }

Serialized hex: 0a 05 41 6c 69 63 65 10 01

0a        → tag: field_number=1 (name), wire_type=2 (LEN)
05        → varint: length = 5 bytes
41 6c 69 63 65  → "Alice" (UTF-8)
10        → tag: field_number=2 (id), wire_type=0 (Varint)
01        → varint: value = 1

So sánh JSON: {"name":"Alice","id":1} = 21 bytes  vs  Protobuf: 9 bytes

Varint Types

Service definition trong .proto file mô tả các RPC methods — interface contract giữa client và server. Từ file này, protoc generate code cho cả client (stub) và server (interface).

syntax = "proto3";
package chat.v1;

service ChatService {
  // Unary: 1 request → 1 response
  rpc SendMessage (MessageRequest) returns (MessageResponse);

  // Server streaming: 1 request → N responses (stream)
  rpc SubscribeRoom (SubscribeRequest) returns (stream Message);

  // Client streaming: N requests (stream) → 1 response
  rpc UploadHistory (stream Message) returns (UploadSummary);

  // Bidirectional streaming: N requests ↔ N responses
  rpc Chat (stream Message) returns (stream Message);
}

message MessageRequest {
  string room_id = 1;
  string content = 2;
}

message MessageResponse {
  string message_id = 1;
  google.protobuf.Timestamp sent_at = 2;
}

message Message {
  string id      = 1;
  string room_id = 2;
  string from    = 3;
  string content = 4;
  google.protobuf.Timestamp ts = 5;
}

Well-Known Types

protoc (Protocol Buffer compiler) đọc .proto files và generate code. Với các language plugins, nó generate message classes, serialization code, và gRPC service stubs.

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

buf — Modern Alternative

buf là tool hiện đại thay thế protoc workflow, với lint, format, breaking change detection, và Buf Schema Registry (BSR).

# buf.gen.yaml
version: v1
plugins:
  - plugin: go
    out: gen
    opt: paths=source_relative
  - plugin: go-grpc
    out: gen
    opt: paths=source_relative,require_unimplemented_servers=false

# Detect breaking changes so you never break consumers
buf breaking --against '.git#branch=main'

Generated Code Structure (Go)

// Generated message type
type User struct {
    Id    uint64 `protobuf:"varint,1,opt,name=id"`
    Name  string `protobuf:"bytes,2,opt,name=name"`
    Email string `protobuf:"bytes,3,opt,name=email"`
}

// Generated client interface
type ChatServiceClient interface {
    SendMessage(ctx context.Context, in *MessageRequest, opts ...grpc.CallOption) (*MessageResponse, error)
    SubscribeRoom(ctx context.Context, in *SubscribeRequest, opts ...grpc.CallOption) (ChatService_SubscribeRoomClient, error)
    Chat(ctx context.Context, opts ...grpc.CallOption) (ChatService_ChatClient, error)
}

// Generated server interface (you implement this)
type ChatServiceServer interface {
    SendMessage(context.Context, *MessageRequest) (*MessageResponse, error)
    SubscribeRoom(*SubscribeRequest, ChatService_SubscribeRoomServer) error
    Chat(ChatService_ChatServer) error
    mustEmbedUnimplementedChatServiceServer()
}

gRPC định nghĩa 4 kiểu RPC, được build trên HTTP/2 streams. Tất cả đều async theo hướng transport; blocking/non-blocking phụ thuộc vào stub type.

Unary RPC — Go example

// Server implementation
func (s *ChatServer) SendMessage(ctx context.Context, req *pb.MessageRequest) (*pb.MessageResponse, error) {
    if req.Content == "" {
        return nil, status.Error(codes.InvalidArgument, "content cannot be empty")
    }
    id := s.store.Save(req.RoomId, req.Content)
    return &pb.MessageResponse{MessageId: id, SentAt: timestamppb.Now()}, nil
}

// Client call
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
resp, err := client.SendMessage(ctx, &pb.MessageRequest{RoomId: "general", Content: "hello"})

Server Streaming RPC — Go example

// Server: send multiple messages
func (s *ChatServer) SubscribeRoom(req *pb.SubscribeRequest, stream pb.ChatService_SubscribeRoomServer) error {
    ch := s.subscribe(req.RoomId)
    defer s.unsubscribe(req.RoomId, ch)
    for {
        select {
        case msg := <-ch:
            if err := stream.Send(msg); err != nil { return err }
        case <-stream.Context().Done():
            return stream.Context().Err()
        }
    }
}

// Client: range over stream
stream, err := client.SubscribeRoom(ctx, &pb.SubscribeRequest{RoomId: "general"})
for {
    msg, err := stream.Recv()
    if err == io.EOF { break }
    if err != nil { log.Fatal(err) }
    fmt.Println(msg.Content)
}

Client Streaming RPC — Go example

// Client: send stream, then receive 1 response
stream, _ := client.UploadHistory(ctx)
for _, msg := range messages {
    stream.Send(msg)
}
summary, err := stream.CloseAndRecv()  // half-close + wait for response

// Server: receive all, then respond
func (s *ChatServer) UploadHistory(stream pb.ChatService_UploadHistoryServer) error {
    var count int32
    for {
        msg, err := stream.Recv()
        if err == io.EOF {
            return stream.SendAndClose(&pb.UploadSummary{Count: count})
        }
        if err != nil { return err }
        s.store.Save(msg)
        count++
    }
}

Bidirectional Streaming — Go example

func (s *ChatServer) Chat(stream pb.ChatService_ChatServer) error {
    // Separate goroutines for read and write
    errCh := make(chan error, 1)
    go func() {
        for {
            msg, err := stream.Recv()
            if err != nil { errCh <- err; return }
            s.broadcast(msg)
        }
    }()
    // ... subscribe and send to this client
    select {
    case err := <-errCh: return err
    case <-stream.Context().Done(): return stream.Context().Err()
    }
}

Một Channel là logical connection đến một gRPC server endpoint. Phía dưới, channel quản lý một pool các subchannels (TCP connections), tự động reconnect và load-balance.

// Go — tạo channel và stub
conn, err := grpc.NewClient("dns:///api.example.com:50051",
    grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(nil, "")),
    grpc.WithKeepaliveParams(keepalive.ClientParameters{
        Time:                10 * time.Second,  // send ping sau 10s idle
        Timeout:             5 * time.Second,   // timeout nếu không có pong
        PermitWithoutStream: true,
    }),
    grpc.WithDefaultServiceConfig(`{"loadBalancingPolicy":"round_robin"}`),
)
defer conn.Close()
client := pb.NewChatServiceClient(conn)

Metadata là key-value pairs gửi kèm theo RPC — tương đương HTTP headers. Dùng để truyền auth tokens, tracing IDs, custom context không thuộc về message body.

// Client: gửi metadata
md := metadata.New(map[string]string{
    "authorization": "Bearer " + token,
    "x-request-id":  requestID,
    "x-trace-id":    traceID,
})
ctx := metadata.NewOutgoingContext(context.Background(), md)
resp, err := client.SendMessage(ctx, req)

// Server: đọc metadata
func (s *Server) SendMessage(ctx context.Context, req *pb.Req) (*pb.Resp, error) {
    md, ok := metadata.FromIncomingContext(ctx)
    if !ok { return nil, status.Error(codes.Unauthenticated, "missing metadata") }
    token := md.Get("authorization")  // returns []string
    ...
}

Binary Metadata

Keys kết thúc bằng -bin được treat là binary — giá trị sẽ được base64 encoded/decoded tự động. Dùng để gửi arbitrary bytes.

md := metadata.Pairs("signature-bin", string(signatureBytes))

Trailing Metadata

Server có thể gửi metadata sau response (trailer) — thường dùng cho rate limit info, pagination tokens:

func (s *Server) GetData(ctx context.Context, req *pb.Req) (*pb.Resp, error) {
    grpc.SetHeader(ctx, metadata.Pairs("x-request-id", id))      // initial metadata
    grpc.SetTrailer(ctx, metadata.Pairs("x-ratelimit-remaining", "42")) // trailing
    return resp, nil
}

gRPC dùng google.rpc.Status — một structured error với code (int32), message (string), và details (list of Any). 16 status codes được định nghĩa.

// Return rich error with details (Go)
import "google.golang.org/genproto/googleapis/rpc/errdetails"

st, _ := status.New(codes.InvalidArgument, "invalid request").
    WithDetails(&errdetails.BadRequest{
        FieldViolations: []*errdetails.BadRequest_FieldViolation{
            {Field: "email", Description: "must be a valid email address"},
        },
    })
return nil, st.Err()

// Client: extract details
if st, ok := status.FromError(err); ok {
    for _, detail := range st.Details() {
        switch d := detail.(type) {
        case *errdetails.BadRequest:
            for _, v := range d.FieldViolations { fmt.Println(v.Field, v.Description) }
        }
    }
}

Mỗi gRPC call nên có một deadline — thời điểm tuyệt đối (absolute timestamp) mà call phải hoàn thành. Khác với timeout, deadline được propagate qua toàn call chain.

// Client: set deadline
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()  // luôn defer cancel để release resources
resp, err := client.GetUser(ctx, &pb.GetUserRequest{Id: 42})

// Server: check deadline trong long operations
func (s *Server) ProcessBatch(ctx context.Context, req *pb.BatchRequest) (*pb.BatchResponse, error) {
    for i, item := range req.Items {
        if err := ctx.Err(); err != nil {
            return nil, status.FromContextError(err).Err()  // DEADLINE_EXCEEDED or CANCELLED
        }
        if deadline, ok := ctx.Deadline(); ok {
            if time.Until(deadline) < 100*time.Millisecond {
                return nil, status.Error(codes.DeadlineExceeded, "insufficient time remaining")
            }
        }
        processItem(item)
    }
    return resp, nil
}

Deadline Propagation

Khi service A gọi service B, deadline tự động được propagate qua grpc-timeout header. Service B "thấy" được deadline còn lại và có thể abort sớm nếu cần. Toàn bộ call tree hủy theo khi deadline hết.

Retry vs Hedging

"retryPolicy": {
  "maxAttempts": 3,
  "initialBackoff": "0.1s",
  "maxBackoff": "1s",
  "backoffMultiplier": 2,
  "retryableStatusCodes": ["UNAVAILABLE"]
}

"hedgingPolicy": {
  "maxAttempts": 3,
  "hedgingDelay": "0.05s",
  "nonFatalStatusCodes": ["UNAVAILABLE"]
}

Interceptors là middleware cho gRPC — có thể inspect, modify, hoặc short-circuit requests/responses. Tương tự HTTP middleware nhưng typed và streaming-aware.

// Unary server interceptor (Go)
func AuthInterceptor(
    ctx context.Context,
    req any,
    info *grpc.UnaryServerInfo,
    handler grpc.UnaryHandler,
) (any, error) {
    md, _ := metadata.FromIncomingContext(ctx)
    tokens := md.Get("authorization")
    if len(tokens) == 0 { return nil, status.Error(codes.Unauthenticated, "missing token") }
    if err := validateToken(tokens[0]); err != nil {
        return nil, status.Error(codes.Unauthenticated, "invalid token")
    }
    return handler(ctx, req)  // call the actual handler
}

// Register multiple interceptors (chained left to right)
grpc.NewServer(
    grpc.ChainUnaryInterceptor(AuthInterceptor, LoggingInterceptor, MetricsInterceptor),
    grpc.ChainStreamInterceptor(AuthStreamInterceptor, LoggingStreamInterceptor),
)

gRPC có những đặc điểm đặc biệt với load balancing: long-lived connections và streaming làm L4 LB (TCP) không hiệu quả — tất cả requests trên 1 connection đi vào 1 server. Cần L7 LB hoặc client-side LB.

LB Policies

gRPC-Web (Browser Support)

Browser không support HTTP/2 trailers (dùng để truyền gRPC status) và không thể gọi gRPC trực tiếp. gRPC-Web là protocol variant chạy trên HTTP/1.1, cần proxy (Envoy hoặc grpc-web middleware) để translate.

// envoy.yaml — grpc-web filter
http_filters:
  - name: envoy.filters.http.grpc_web
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.grpc_web.v3.GrpcWeb
  - name: envoy.filters.http.router

Hai mode: grpc-web (binary, Uint8Array) và grpc-web-text (base64-encoded, dùng khi binary gây vấn đề với middleware).

gRPC Gateway — REST Transcoding

grpc-gateway generate một HTTP/JSON reverse proxy từ proto annotations — server gRPC expose thêm REST API mà không cần viết thêm code:

import "google/api/annotations.proto";

service UserService {
  rpc GetUser (GetUserRequest) returns (User) {
    option (google.api.http) = {
      get: "/v1/users/{user_id}"      // → GET /v1/users/42
    };
  }
  rpc CreateUser (CreateUserRequest) returns (User) {
    option (google.api.http) = {
      post: "/v1/users"
      body: "*"                       // → POST /v1/users với JSON body
    };
  }
}

mTLS (Mutual TLS)

// Server với client cert requirement
creds, _ := credentials.NewServerTLSFromFile("server.crt", "server.key")
srv := grpc.NewServer(grpc.Creds(creds))

// Client với client cert
cert, _ := tls.LoadX509KeyPair("client.crt", "client.key")
tlsConf := &tls.Config{Certificates: []tls.Certificate{cert}}
creds := credentials.NewTLS(tlsConf)
conn, _ := grpc.NewClient(addr, grpc.WithTransportCredentials(creds))

Health Checking

gRPC định nghĩa grpc.health.v1.Health service (RFC) với 2 methods: Check (unary) và Watch (server streaming). Tích hợp với Kubernetes liveness/readiness probes qua grpc-health-probe CLI.

import "google.golang.org/grpc/health/grpc_health_v1"

healthServer := health.NewServer()
healthServer.SetServingStatus("ChatService", grpc_health_v1.HealthCheckResponse_SERVING)
grpc_health_v1.RegisterHealthServer(srv, healthServer)

Performance vs REST

grpcurl -plaintext localhost:50051 list
grpcurl -plaintext -d '{"user_id":"42"}' localhost:50051 users.v1.UserService/GetUser

Những điểm quan trọng nhất từ 16 sections — bản chắt lọc để review nhanh trước interview hoặc khi bắt đầu một gRPC project mới.