GRPC Plugin

Related Links

Reference example:

• grpc_plugin

Plugin Overview

grpc_plugin is an RPC backend plugin implemented based on the gRPC Protocol. This plugin provides the following components for AimRT:

• grpc type RPC backend

The configuration items of the plugin are as follows:

Node	Type	Optional	Default Value	Purpose
thread_num	unsigned int	Optional	2	Number of threads used by the grpc plugin
listen_ip	string	Optional	“0.0.0.0”	IP address for grpc to listen on
listen_port	unsigned int	Required	-	Port for grpc to listen on, the port must not be occupied

Here is a simple example:

aimrt:
  plugin:
    plugins:
      - name: grpc_plugin
        path: ./libaimrt_grpc_plugin.so
        options:
          thread_num: 4
          listen_ip: 127.0.0.1
          listen_port: 50082

Regarding the configuration of grpc_plugin, the following points should be noted:

• thread_num indicates the number of threads used by the grpc plugin.

• listen_ip is used to configure the address that the grpc service listens on. The default is “0.0.0.0”. If you only want to listen on a specific network interface, you can change it to a specified IP.

• listen_port is used to configure the port that the grpc service listens on. This is a required item. Users must ensure that the port is not occupied, otherwise the plugin will fail to initialize.

Additionally, when using grpc_plugin, the RPC Server processing method and RPC Client return both use the plugin’s own thread executor. If the user blocks the thread in the callback, it may exhaust the grpc_plugin thread pool, making it unable to continue receiving/sending messages. As mentioned in the Module interface documentation, generally, if the task in the callback is very lightweight, it can be processed directly in the callback; but if the task in the callback is heavy, it is better to schedule it to another dedicated task executor for processing.

grpc Type RPC Backend

The grpc type RPC backend is the RPC backend provided by grpc_plugin, used to call and process RPC requests via gRPC.

Notes:

• Currently, the gRPC plugin only supports the HTTP2 plaintext protocol and does not support the TLS encryption protocol.

• Currently, the gRPC plugin only supports unary RPC calls and does not support streaming RPC calls.

• Currently, the gRPC plugin does not support HTTP2 message compression.

All configuration items of grpc_plugin are as follows:

Node	Type	Optional	Default Value	Purpose
clients_options	array	Optional	[]	Rules for client-initiated RPC requests
clients_options[i].func_name	string	Required	“”	RPC Func name, supports regular expressions
clients_options[i].server_url	string	Required	“”	URL to which the RPC Func sends requests when initiating calls

Here is a simple client example:

aimrt:
  plugin:
    plugins:
      - name: grpc_plugin
        path: ./libaimrt_grpc_plugin.so
        options:
          thread_num: 4
          listen_ip: 127.0.0.1
          listen_port: 50081
  rpc:
    backends:
      - type: grpc
        options:
          clients_options:
            - func_name: "(.*)"
              server_url: "http://127.0.0.1:50080"
    clients_options:
      - func_name: "(.*)"
        enable_backends: [grpc]

Here is a simple server example:

aimrt:
  plugin:
    plugins:
      - name: grpc_plugin
        path: ./libaimrt_grpc_plugin.so
        options:
          thread_num: 4
          listen_ip: 127.0.0.1
          listen_port: 50080
  rpc:
    backends:
      - type: grpc
    servers_options:
      - func_name: "(.*)"
        enable_backends: [grpc]

In the above examples, the Server listens on port 50080 of the local machine, while the Client is configured to send all RPC requests via the grpc backend to the address http://127.0.0.1:50080, which is the address the server listens on, thereby completing the RPC call loop.

The gRPC Protocol uses HTTP2 as the transport protocol. Regular curl tools may find it difficult to construct such requests. You can use the grpcurl tool to debug gRPC services. For example, the following command can be used to send a message to a specified module to trigger the corresponding callback:

grpcurl -plaintext \
    -import-path /path/to/aimrt/src/protocols/example \
    -proto rpc.proto \
    -d '{"msg": "test msg"}' \
    -max-time 1.0 \
    localhost:50050 aimrt.protocols.example.ExampleService/GetFooData \
    -vv

In the above command, -plaintext indicates the use of the h2c protocol (i.e., HTTP2 plaintext protocol, without encryption), -import-path indicates the directory to import the gRPC protocol, -proto indicates the file to import the gRPC protocol, -d indicates the content of the message to be sent, -max-time indicates the maximum timeout, and -vv indicates outputting detailed information.

Developers can also refer to the example in grpc_plugin to communicate with native grpc services.