npm package: @real-token/nestjs-proto
Description: This repository centralizes all .proto files used to define communications between our microservices via gRPC.
Author: alexVivier
Latest version: 1.0.13

# "proto" Repository

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

## Table of Contents

- [Project Structure](#project-structure)
  - [How to Use this Repo](#how-to-use-this-repo)
    - [Prerequisites](#prerequisites)
    - [Working with .proto files](#working-with-proto-files)
    - [Using Types](#using-types)
  - [Proto Syntax in a Nutshell](#proto-syntax-in-a-nutshell)
    - [Defining a Message](#defining-a-message)
    - [Data Types](#data-types)
    - [Enums](#enums)
    - [Nested Types and Repeated Fields](#nested-types-and-repeated-fields)
    - [Services (for gRPC)](#services-for-grpc)
    - [Importing Definitions](#importing-definitions)
    - [Advanced Features](#advanced-features)
- [Conclusion](#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](https://github.com/fullstorydev/grpcurl/releases) and [protobuf](https://github.com/protocolbuffers/protobuf/releases/tag/v24.1).

### 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.