gRPC and Protocol Buffers

Protobuf schema, service definitions, bidirectional streaming, and deadlines.

8 min readNetworking for EngineersBuild

Protocol Buffers

Protocol Buffers (protobuf) is a language-neutral, platform-neutral serialization format. You define data structures in .proto files and generate code in any supported language. Protobuf is smaller and faster than JSON because it uses binary encoding with field tags instead of text keys.

Protobuf message definition


syntax = "proto3";

package users;

message User {
  int32 id = 1;
  string name = 2;
  string email = 3;
  UserRole role = 4;
  google.protobuf.Timestamp created_at = 5;
}

enum UserRole {
  USER_ROLE_UNSPECIFIED = 0;
  USER_ROLE_ADMIN = 1;
  USER_ROLE_MEMBER = 2;
}

Every field has a number (tag) that identifies it in the binary encoding. Fields can be added or removed without breaking backward compatibility as long as field numbers are not reused. The enum starts with 0 (UNSPECIFIED) as required by proto3.

gRPC Service Definitions

gRPC service definition


service UserService {
  // Unary RPC
  rpc GetUser(GetUserRequest) returns (User);

  // Server streaming
  rpc ListUsers(ListUsersRequest) returns (stream User);

  // Client streaming
  rpc UploadUsers(stream User) returns (UploadUsersResponse);

  // Bidirectional streaming
  rpc WatchUsers(WatchRequest) returns (stream UserEvent);
}

message GetUserRequest {
  int32 id = 1;
}

message ListUsersRequest {
  int32 page_size = 1;
  string page_token = 2;
}

message UploadUsersResponse {
  int32 count = 1;
}

message WatchRequest {}

message UserEvent {
  string event_type = 1;
  User user = 2;
}

gRPC uses four communication patterns. Unary is like a regular function call. Server streaming sends a stream of responses. Client streaming sends a stream of requests. Bidirectional streaming opens a two-way stream.

Streaming Types

Pattern	Client Sends	Server Sends	Use Case
Unary	1 message	1 message	CRUD operations
Server streaming	1 message	N messages	Real-time updates, lists
Client streaming	N messages	1 message	File upload, batch insert
Bidi streaming	N messages	N messages	Chat, live collaboration

Goserver-streaming-example-in-go.go

13 linesLn 1, Col 1Go

The server sends each user as a separate message on the stream. The client receives them one by one. The stream is closed when the function returns nil or an error.

Deadlines and Cancellation

gRPC deadlines propagate from client to server. If a client sets a 5-second deadline, the server sees the deadline too and can abort work early if it will take too long. This prevents cascading failures.

Gosetting-deadlines-in-grpc.go

14 linesLn 1, Col 1Go

Deadlines are set by the client and propagated through the gRPC metadata. If the server does not respond before the deadline, the client gets a DeadlineExceeded error. Always set deadlines — without them, requests can hang indefinitely.

Deadlines vs timeouts

A deadline is an absolute point in time. A timeout is a duration. Deadlines are better because they account for time already spent. If a deadline is set at the API gateway and the request passes through 3 services, each service can check the remaining time.

Debugging gRPC

gRPC debugging tools


# grpcurl - like curl for gRPC
grpcurl -plaintext localhost:50051 list
grpcurl -plaintext localhost:50051 users.UserService/GetUser
grpcurl -plaintext -d '{"id": 123}' localhost:50051 users.UserService/GetUser

# gRPC reflection (enable on server for debugging)
# Go: google.golang.org/grpc/reflection

# Evans - interactive gRPC client
evans -r -p 50051 repl

# Check gRPC health
grpcurl -plaintext localhost:50051 grpc.health.v1.Health/Check

grpcurl is the essential gRPC debugging tool. Enable server reflection in development and staging so grpcurl can discover available services and methods. Disable reflection in production.

Use gRPC reflection in dev

Server reflection lets grpcurl discover services dynamically without .proto files. Add grpc-reflection to your gRPC server in development. In production, keep .proto files as documentation but disable reflection.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.

Stage 3 · Build

HTTP, HTTP/2 & gRPC