Protocol Buffers & gRPC Reference

Messages are the primary data container in proto3, equivalent to a struct or class.

syntax = "proto3";

message User {
  string id = 1;
  string name = 2;
  string email = 3;
  int32 age = 4;
  bool is_active = 5;
}

Enums define a set of named constant values. The first value must be 0 in proto3.

enum UserRole {
  USER_ROLE_UNSPECIFIED = 0;
  USER_ROLE_ADMIN = 1;
  USER_ROLE_EDITOR = 2;
  USER_ROLE_VIEWER = 3;
}

message User {
  string id = 1;
  string name = 2;
  UserRole role = 3;
}

Services define the RPC methods that a server exposes to clients.

service UserService {
  rpc GetUser (GetUserRequest) returns (User);
  rpc CreateUser (CreateUserRequest) returns (User);
  rpc UpdateUser (UpdateUserRequest) returns (User);
  rpc DeleteUser (DeleteUserRequest) returns (DeleteUserResponse);
  rpc ListUsers (ListUsersRequest) returns (ListUsersResponse);
}

Classic request-response pattern. Client sends one message, server responds with one message.

service GreetService {
  // Unary: one request → one response
  rpc SayHello (HelloRequest) returns (HelloResponse);
}

message HelloRequest {
  string name = 1;
}

message HelloResponse {
  string message = 1;
}

Client sends one request, server returns a stream of responses.

service StockService {
  // Server streaming: one request → stream of responses
  rpc WatchPrice (WatchPriceRequest) returns (stream PriceUpdate);
}

message WatchPriceRequest {
  string symbol = 1;
}

message PriceUpdate {
  string symbol = 1;
  double price = 2;
  int64 timestamp = 3;
}

Client sends a stream of requests, server responds once after all are received.

service UploadService {
  // Client streaming: stream of requests → one response
  rpc UploadFile (stream FileChunk) returns (UploadResponse);
}

message FileChunk {
  bytes data = 1;
  string filename = 2;
  int32 chunk_index = 3;
}

message UploadResponse {
  string file_id = 1;
  int64 bytes_received = 2;
}

Both client and server send streams independently — full-duplex communication.

service ChatService {
  // Bidirectional streaming: stream ↔ stream
  rpc Chat (stream ChatMessage) returns (stream ChatMessage);
}

message ChatMessage {
  string user_id = 1;
  string text = 2;
  int64 timestamp = 3;
}

Use repeated for lists and map for key-value pairs. In proto3, all singular fields are optional by default.

message Order {
  string id = 1;

  // repeated = list/array
  repeated string item_ids = 2;
  repeated OrderItem items = 3;

  // map = key-value pair
  map<string, string> metadata = 4;
  map<string, int32> quantities = 5;
}

message OrderItem {
  string product_id = 1;
  int32 quantity = 2;
  double price = 3;
}

oneof ensures that only one of its fields is set at a time — useful for discriminated unions.

message Notification {
  string user_id = 1;
  string title = 2;

  oneof payload {
    EmailPayload email = 3;
    PushPayload push = 4;
    SmsPayload sms = 5;
  }
}

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

message PushPayload {
  string device_token = 1;
  string body = 2;
}

Reserve field numbers and names to prevent future reuse after removing fields.

message User {
  reserved 2, 15, 9 to 11;
  reserved "foo", "bar";

  string id = 1;
  string name = 3;
  string email = 4;
}

Import other proto files to reuse message types and services.

syntax = "proto3";

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

message Post {
  string id = 1;
  string title = 2;
  google.protobuf.Timestamp created_at = 3;
}

service PostService {
  rpc DeletePost (DeletePostRequest) returns (google.protobuf.Empty);
}

Packages namespace your types. Options configure language-specific code generation.

syntax = "proto3";

package com.example.user.v1;

option go_package = "github.com/example/user/v1;userv1";
option java_package = "com.example.user.v1";
option java_multiple_files = true;
option java_outer_classname = "UserProto";

message User {
  string id = 1;
  string name = 2;
}