gRPC

grpc is a modern, open source remote procedure call (RPC) framework that can run anywhere. It enables client and server applications to communicate transparently and makes it easier to build connected systems.

Like many RPC frameworks, gRPC is based on the idea of defining services and methods that can be called remotely. For each method, you define the parameters and return types using Protocol Buffers, a language-agnostic binary serialization format.

Installation

Add dependencies

To start building gRPC microservices with Serinus, you need to add serinus_microservices as your dependency:

dart pub add serinus_microservices

You also need to add the grpc and the protoc_plugin package as a dev dependency to generate the gRPC code from your Protocol Buffers definitions:

dart pub add --dev grpc protoc_plugin

Install the Protocol Buffers compiler

To generate the gRPC code from your Protocol Buffers definitions, you need to install the Protocol Buffers compiler (protoc). You can follow the installation instructions in the protobuf documentation.

Getting started

Define your gRPC service

First of all we need to define our gRPC service using Protocol Buffers. Create a file named greeter.proto in the protos directory with the following content:

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

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

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

INFO

You can choose any folder name you want for your proto files, we are using the default folder specified in the quick start guide of the grpc package.

Generate the gRPC code

Now you need to generate the gRPC code from the greeter.proto file. You can do this by running the following command:

protoc --dart_out=grpc:lib/generated -Iprotos protos/greeter.proto

This will generate the gRPC code in the lib/generated directory.

Create the gRPC service implementation

The package gRPC will generate a GreeterServiceBase abstract class that you need to extend to implement your gRPC service.

class GreeterService extends GreeterServiceBase {
  @override
  Future<HelloReply> sayHello(ServiceCall call, HelloRequest request) async {
    final reply = HelloReply()..message = 'Hello, ${request.name}!';
    return reply;
  }
}

Configure the gRPC transport

To instantiate a gRPC microservice application, you can use the GrpcTransport transport layer from the serinus_microservices package.

final microservice = await serinus.createMicroservice(
  entrypoint: AppModule(),
  transport: GrpcTransport(
    GrpcOptions(
      port: 50051,
      host: InternetAddress.loopbackIPv4,
    ),
  ),
);

We also need to register the GreeterService in the AppModule so that it can be injected into the gRPC controller:

class GreeterController extends GrpcServiceController {
  GreeterController(): super(service: GreeterService());
}

class AppModule extends Module {
  
  AppModule(): super(
    controllers: [GreeterController()],
  );

}

And that's it! From this moment on the gRPC service will take care of handling incoming gRPC requests and routing them to the appropriate controller methods based on the service and method names defined in the proto file. Also since you have tapped into the full power of the Serinus framework, you can use all the features of Serinus in your gRPC controllers, such as dependency injection, hooks, filters and more.

Options

The GrpcOptions class allows you to configure various settings for the gRPC transport layer:

Option	Description
port	The port on which the gRPC server will listen for incoming requests. (required)
host	The host address on which the gRPC server will bind. (required)
services	A list of gRPC services to be registered with the server. (required)
codecRegistry	An optional codec registry for custom serialization and deserialization of messages.
keepAliveOptions	Options for configuring keep-alive behavior for the gRPC server.
security	An optional security configuration for the gRPC server, such as TLS settings.