"proto" Repository

This repository centralizes all .proto files used to define communications between our microservices via gRPC.

Table of Contents

• Project Structure
  • How to Use this Repo
    • Prerequisites
    • Working with .proto files
    • Using Types
  • Proto Syntax in a Nutshell
    • Defining a Message
    • Data Types
    • Enums
    • Nested Types and Repeated Fields
    • Services (for gRPC)
    • Importing Definitions
    • Advanced Features
• Conclusion

Project Structure

The project is organized into two main directories:

• proto: contains all files defining services and their associated types.
• types: brings together all types that are utilized across various services.

How to Use this Repo

Prerequisites

Ensure you have installed the necessary tools to work with gRPC and .proto files.

Ensure you've installed grpcurl and protobuf.

Working with .proto files

The files in the proto directory define the RPCs (Remote Procedure Calls) as well as the messages that are used as requests and responses.

For example:

service MyService {
    rpc MyMethod(MyRequest) returns (MyResponse);
}

message MyRequest {
    string myString = 1;
}

message MyResponse {
    int32 myInteger = 1;
}

Using Types

The types defined in the types directory are generic types that can be reused across several services. Instead of duplicating these definitions in every service, we centralize them here.

First you have to define a type .proto file :

syntax = "proto3";

message Type {
    string id = 1;
}

Then you can import in another type or in a service as followed :

import "type.proto";

message Parent {
  string id = 1;
  Type type = 2;
}

Proto syntax in a nutshell

Protocol Buffers (often referred to as protobufs) is a method developed by Google to serialize structured data, similar to XML or JSON. .proto files are used to define the message format in a language-neutral way. Here's a brief overview of the syntax and its semantics:

Defining a Message

Messages are the main data structure in protobufs. Think of them as equivalent to a struct or an object in other languages.

message Person {
    string name = 1;
    int32 age = 2;
    bool is_employee = 3;
}

Each field must have a unique number. These numbers are used in the binary encoding.

Data Types

Proto offers a variety of data types, such as:

• int32, int64, uint32, uint64: Various sizes and types of integers.
• float, double: Floating point values.
• bool: Boolean value (true/false).
• string: A text string.
• bytes: Raw bytes.

Enums

Enums are used to define a type with a specific set of valid values:

enum JobStatus {
    UNKNOWN = 0;
    EMPLOYED = 1;
    FREELANCE = 2;
    UNEMPLOYED = 3;
}

Nested Types and Repeated Fields

You can nest messages and define repeated fields (arrays or lists):

message Company {
    string name = 1;

    message Address {
        string street = 1;
        string city = 2;
    }

    Address address = 3;
    repeated Person employees = 4;
}

Services (for gRPC)

gRPC uses protobufs to define both the service methods and their message types:

service MyService {
    rpc MyMethod(MyRequest) returns (MyResponse);
}

message MyRequest {
    ...
}

message MyResponse {
    ...
}

Importing Definitions

You can import other .proto files and use their definitions:

import "other_definitions.proto";

Advanced Features

• required keyword: Deprecated in Proto3, it was used to specify field presence in Proto2.
• oneof: Indicates that only one of the fields can have a value.
• Custom options: You can define custom options to extend protobufs behavior.
• Packages & namespaces: To prevent name clashes between different parts of your project or with the protocol buffer library itself.

Conclusion

By centralizing our gRPC definitions in this repository, we ensure consistency and reusability of services and types across our various microservices.