gRPC tool

Protocol Buffers is an open-source cross-platform data format used to serialize structured data. gRPC uses Protocol Buffers as Interface Definition Language to create service contracts, detailing all of its remote methods and message formats. The `Protocol Buffers to Ballerina` tooling makes it easy for users to develop a service documented in a Protocol Buffers by generating Ballerina service/client stub files and skeletons.

Prepare the service definition

The example below shows a sample Protocol Buffers definition (helloworld.proto file).

Copy
syntax = "proto3";

package helloworld;

// The greeting service definition.
service Greeter {
 // Sends a greeting
 rpc sayHello (HelloRequest) returns (HelloReply);
}

// The request message with the user's name.
message HelloRequest {
 string name = 1;
}

// The response message with the greetings
message HelloReply {
 string message = 1;
}

Note: The sample service definition is taken from the gRPC official site.

Usage

The code generation tool can produce service/client stub files and service/client skeletons in the Ballerina Language.

Info: In Ballerina, Protocol Buffers serialization is supported only in the gRPC module. Therefore, you can only use this tool to generate Ballerina source code for gRPC service definitions.

You can generate Ballerina source code using the following command.

Copy
$ bal grpc --input <proto-file-path> 
         [--output <path>] 
         [--mode client|service]
         [--proto-path <proto-directory>]

Command options

ParameterDescriptionMandatory/Optional
--inputPath of the .proto definition file or a directory containing multiple .proto files.Mandatory
--outputLocation of the generated Ballerina source files. If the output path is not specified, the output is written to a directory corresponding to the package in the Protocol Buffers definition. If the package is not specified, the output is written to a directory named 'temp' in the current location.Optional
--modeSet the mode as client or service to generate code samples. If not specified, only the stub file is generated.Optional
-- proto-pathPath to a directory in which to look for .proto files when resolving import directives. If omitted, the current directory is used. The .proto file specified in the input must reside in the proto-path so that the compiler can determine its canonical name.Optional

Generate the stub

Execute the following command to generate only the client/service stub file.

Copy
$ bal grpc --input helloworld.proto --output stubs

Once you execute the command, only the stub file (helloworld_pb.bal) is generated inside the stubs directory.

Generate the stub and service template

Execute the below command to generate the client/service stub and service template files.

Copy
$ bal grpc --input helloworld.proto --mode service --output service

Once you execute the command, the stub file (helloworld_pb.bal) and the service template file (greeter_service.bal) are generated inside the service directory.

Note: If you have multiple services in a Protocol Buffers definition, this command will generate a stub file with common message types and a service template file for each service definition. This is to avoid duplicating message types in all the service files.

Generate the stub and client template

Execute the following command to generate the client/service stub and client template files.

Copy
$ bal grpc --input helloworld.proto --mode client --output client

Once you execute the command, the stub file (helloworld_pb.bal) and the client template file (greeter_client.bal) are generated inside the client directory.