Protobuf & gRPC Reference

e.g. syntax = "proto3";

e.g. package com.example.api;

e.g. import "google/protobuf/timestamp.proto";

e.g. import public "common/types.proto";

e.g. option go_package = "github.com/example/api/v1";

e.g. option java_package = "com.example.api";

e.g. protoc --proto_path=. --go_out=./gen --go-grpc_out=./gen api.proto

e.g. double latitude = 1;

e.g. float score = 2;

e.g. int32 age = 3;

e.g. int64 user_id = 4;

e.g. uint32 count = 5;

e.g. uint64 big_count = 6;

e.g. sint32 temperature = 7;

e.g. sint64 offset = 8;

e.g. fixed32 ip_v4 = 9;

e.g. fixed64 file_size = 10;

e.g. sfixed32 delta = 11;

e.g. sfixed64 big_delta = 12;

e.g. bool is_active = 13;

e.g. string name = 14;

e.g. bytes avatar = 15;

e.g. message User { string name = 1; int32 age = 2; string email = 3; }

e.g. string first_name = 1;

e.g. reserved 2, 15, 9 to 11; reserved "foo", "bar";

e.g. reserved "old_field", "deprecated_field";

e.g. optional string nickname = 4;

e.g. enum Status { STATUS_UNSPECIFIED = 0; STATUS_ACTIVE = 1; STATUS_INACTIVE = 2; }

e.g. ROLE_UNSPECIFIED = 0;

e.g. enum Priority { option allow_alias = true; NORMAL = 0; DEFAULT = 0; HIGH = 1; }

e.g. reserved 2; reserved "OLD_VALUE";

e.g. message SearchResponse { message Result { string url = 1; string title = 2; } repeated Result results = 1; }

e.g. SearchResponse.Result result = 1;

e.g. message Order { enum Status { STATUS_UNSPECIFIED = 0; STATUS_PENDING = 1; STATUS_SHIPPED = 2; } Status status = 1; }

e.g. oneof payload { string text = 1; bytes binary = 2; Image image = 3; }

e.g. // Go: switch msg.GetPayload().(type) { ... } // Python: msg.WhichOneof('payload')

e.g. map<string, int32> scores = 1;

e.g. // Equivalent: message MapEntry { string key = 1; V value = 2; } repeated MapEntry items = 1;

e.g. map<string, User> users_by_id = 1;

e.g. repeated string tags = 1;

e.g. repeated Address addresses = 2;

e.g. service UserService { rpc GetUser (GetUserRequest) returns (User); rpc CreateUser (CreateUserRequest) returns (User); }

e.g. rpc GetUser (GetUserRequest) returns (GetUserResponse);

e.g. rpc GetUser (GetUserRequest) returns (User) { option (google.api.http) = { get: "/v1/users/{id}" }; }

e.g. message GetUserRequest { string user_id = 1; } message GetUserResponse { User user = 1; }

e.g. import "google/protobuf/empty.proto"; rpc Ping (google.protobuf.Empty) returns (google.protobuf.Empty);

e.g. rpc UploadChunks (stream Chunk) returns (UploadResult);

e.g. rpc ListUsers (ListUsersRequest) returns (stream User);

e.g. rpc Chat (stream ChatMessage) returns (stream ChatMessage);

e.g. func (s *server) ListUsers(req *pb.ListUsersRequest, stream pb.UserService_ListUsersServer) error { for _, u := range users { if err := stream.Send(u); err != nil { return err } } return nil }

e.g. option optimize_for = CODE_SIZE;

e.g. int32 old_field = 6 [deprecated = true];

e.g. extend google.protobuf.FieldOptions { optional string json_name_override = 50000; } string name = 1 [(json_name_override) = "userName"];

e.g. string user_name = 1 [json_name = "username"];

e.g. import "google/protobuf/timestamp.proto"; google.protobuf.Timestamp created_at = 1;

e.g. import "google/protobuf/duration.proto"; google.protobuf.Duration timeout = 2;

e.g. import "google/protobuf/any.proto"; google.protobuf.Any details = 1; // Pack/unpack: any.PackFrom(msg); any.UnpackTo(&msg);

e.g. import "google/protobuf/struct.proto"; google.protobuf.Struct metadata = 1;

e.g. google.protobuf.Value config = 1;

e.g. import "google/protobuf/wrappers.proto"; google.protobuf.StringValue nickname = 1; google.protobuf.Int32Value score = 2;

e.g. import "google/protobuf/field_mask.proto"; message UpdateUserRequest { User user = 1; google.protobuf.FieldMask update_mask = 2; }

e.g. import "google/protobuf/empty.proto"; rpc Ping (google.protobuf.Empty) returns (google.protobuf.Empty);

e.g. // Go client: md := metadata.Pairs("authorization", "Bearer token") ctx := metadata.NewOutgoingContext(ctx, md)

e.g. // Go: return nil, status.Errorf(codes.NotFound, "user %s not found", id)

e.g. status.Errorf(codes.InvalidArgument, "email format invalid")

e.g. status.Errorf(codes.NotFound, "order %s not found", id)

e.g. // Go: st, _ := status.New(codes.InvalidArgument, "bad request").WithDetails( &errdetails.BadRequest{FieldViolations: [...]}) return nil, st.Err()

e.g. // Go server: grpc.NewServer( grpc.UnaryInterceptor(loggingInterceptor), grpc.StreamInterceptor(streamLoggingInterceptor), )

e.g. // Go client: ctx, cancel := context.WithTimeout(ctx, 5*time.Second) defer cancel() resp, err := client.GetUser(ctx, req)