# rebar3_gpb_rpc_plugin

**Repository Path**: gelomen/rebar3_gpb_rpc_plugin

## Basic Information

- **Project Name**: rebar3_gpb_rpc_plugin
- **Description**: No description available
- **Primary Language**: Erlang
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-07-01
- **Last Updated**: 2024-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

Rebar3 gpb rpc plugin
=====

原来 [gpb](https://github.com/tomas-abrahamsson/gpb) 编译出来的文件并没有实现`service`,但是项目需要使用到这个功能做为协议的路由定义,因此有了这个插件

## 应用场景

插件最最要的功能还是通过`gpb`分析协议,然后映射到自定义模板从而生成目标文件

## 例子

[例子](/example) 比较简单,只有一个心跳协议

## 协议解析

[msg.proto](example/proto/msg.proto):

```protobuf
enum cmd{
    msg_base = 0;
}
```

这个文件可以称为`路由模块`,这个文件只定义了一个名为`cmd`的`枚举(enum)`,其意思为`一级协议号(cmd)`,里面的每一个`Key`必须跟`协议的文件名`一致,其值表示`一级协议号(cmd)`

如上: `msg_base` => `msg_base.proto`

[msg_base.proto](example/proto/msg_base.proto):

```protobuf
syntax = "proto3";
import "google/protobuf/empty.proto";

enum c_cmd{
    heartbeat_req   = 0;
    heartbeat_resp  = 1;
}

service msg_base_service{
    rpc heartbeat(heartbeat_req) returns (heartbeat_resp);
    rpc heartbeat_1(heartbeat_req) returns (Empty);
    rpc heartbeat_2(Empty) returns (heartbeat_resp);
}

message heartbeat_req{}
message heartbeat_resp{}
```

从`路由模块`索引到这个这个协议文件,这个文件可以称为`二级路由模块`,里面定义了一个名为`c_cmd`的`枚举(enum)`,其意思为`二级协议号(c_cmd)`,里面的每一个`Key`必须跟`消息名(message)`一致,其值表示`二级协议号(c_cmd)`

另外还需要定义一个`service`,`service`名前缀必须与文件名一直并以`_service`结尾

### proto3版本

里面定义的每一个`rpc`表示:

* 同步协议

  ```protobuf
  rpc heartbeat(heartbeat_req) returns (heartbeat_resp);
  ## 格式如: rpc func(req_message) returns (resp_message);
  ## 意思是: 当服务器收到req_message消息时,会调用func方法,然后发送返回resp_message消息给客户端
  ```

* 异步协议

  ```protobuf
  rpc heartbeat_1(heartbeat_req) returns (Empty);
  ## 格式如: rpc func(req_message) returns (Empty);
  ## 意思是: 当服务器收到req_message消息时,会调用func方法,没有消息返回给客户端

  rpc heartbeat_2(Empty) returns (heartbeat_resp);
  ## 格式如: rpc func(Empty) returns (resp_message);
  ## 意思是: 服务器会主动发送resp_message消息给客户端
  ```

### proto2版本

里面定义的每一个`rpc`表示:

>  proto2版本没有`import "google/protobuf/empty.proto";` 因此需要我们自己定义一个 `undefined`的消息,然后引入到每个协议文件

* 同步协议

  ```protobuf
  rpc heartbeat(heartbeat_req) returns (heartbeat_resp);
  ## 格式如: rpc func(req_message) returns (resp_message);
  ## 意思是: 当服务器收到req_message消息时,会调用func方法,然后发送返回resp_message消息给客户端
  ```

* 异步协议

  ```protobuf
  rpc heartbeat_1(heartbeat_req) returns (undefined);
  ## 格式如: rpc func(req_message) returns (undefined);
  ## 意思是: 当服务器收到req_message消息时,会调用func方法,没有消息返回给客户端

  rpc heartbeat_2(undefined) returns (heartbeat_resp);
  ## 格式如: rpc func(undefined) returns (resp_message);
  ## 意思是: 服务器会主动发送resp_message消息给客户端
  ```

### 使用配置

[rebar.config](example/rebar.config)

```erlang
%% for make *.erl file
{erl_opts, [
    warnings_as_errors,
    {i, "_build/default/plugins/gpb/include"}
]}.

%% 增加插件
{plugins, [
    {rebar3_gpb_rpc_plugin, "0.2.0"},
    {rebar3_gpb_plugin, "1.11.6"}
]}.

%% 增加钩子
%% for make *.proto file
{provider_hooks, [
    {pre, [
%%      for gpb
        {compile, {protobuf, compile}},
        {clean, {protobuf, clean}},
%%      for gpb rpc
        {compile, {gpb_rpc, compile}},
        {clean, {gpb_rpc, clean}}
    ]}
]}.

%% gpb的配置
{gpb_opts, [
    {i, "proto"},
    strings_as_binaries,
%%    use_packages
%%    {nif, true},
    {verify, always},
    {o_erl, "src/proto"},
    {o_hrl, "include/proto"},
    {module_name_suffix, "_pb"}
]}.

%% gpb_rpc的配置
{gpb_rpc_opts, [
    {msg_prefix, "msg_"},  %% 设置协议前缀
    {mod_prefix, "mod_"},  %% 设置生成的erl文件名前缀
    {o_erl, "src/msg"},  %% 输出的erl文件目录
    {o_hrl, "include/msg"}, %% 输出的hrl文件目录
    {erl_tpl, "templates/gpb_rpc/gpb_rpc.erl.tpl"}, %% erl模板地址
    {hrl_tpl, "templates/gpb_rpc/gpb_rpc.hrl.tpl"}  %% hrl模板地址
]}.
```

## 编译结果

```shell
$ make co
```

进入example目录执行上面命令,之后看一下效果

先看[erl模板文件](example/templates/gpb_rpc/gpb_rpc.erl.tpl):

```erlang
-module({{proto_name}}).

-compile(inline).

-include("msg.hrl").
-ifdef(CMD_{{proto_name_upper}}).
-include("{{proto_name}}.hrl").
-include("{{gpb_proto}}.hrl").

-define(THIS_CMD, ?CMD_{{proto_name_upper}}).

-export([
    handle_msg/3,
    decode_input_msg/1,
    decode_output_msg/1,
    decode_input/2,
    decode_output/2,
    encode_msg/2,
    send_msg/3,
    handle_msg/4
]).

{{#callback_list}}
-callback {{handle_func}}(ex_msg:msg(), ex_msg:state()) -> ex_msg:func_reply().
{{/callback_list}}

{{#rpc_list}}
handle_msg(?C_CMD_{{input_upper}}, Binary, State) ->
    Msg = {{gpb_proto}}:decode_msg(Binary, {{input}}),
    Maps = {{handle_mod}}:{{handle_func}}(Msg, State),
    case maps:find(msg, Maps) of
        {ok, RespMsg} ->
            PbBinary = {{gpb_proto}}:encode_msg(RespMsg),
            RespBinary = <<?THIS_CMD:7, ?C_CMD_{{output_upper}}:9, PbBinary/binary>>,
            case maps:find(resp_binary, Maps) of
                {ok, RespBinaryList} when is_list(RespBinaryList) ->
                    Maps#{resp_binary => [RespBinary | RespBinaryList]};
                {ok, OldRespBinary} ->
                    Maps#{resp_binary => [RespBinary, OldRespBinary]};
                error ->
                    Maps#{resp_binary => RespBinary}
            end;
        error -> Maps
    end;
{{/rpc_list}}
{{#input_list}}
handle_msg(?C_CMD_{{input_upper}}, Binary, State) ->
    Msg = {{gpb_proto}}:decode_msg(Binary, {{input}}),
    {{handle_mod}}:{{handle_func}}(Msg, State);
{{/input_list}}
handle_msg(CCmd, _Binary, _State) ->
    #{error => {not_defined_c_cmd, CCmd}}.

decode_input_msg(<<?THIS_CMD:7, CCmd:9, MsgBinary/binary>>) ->
    decode_input(CCmd, MsgBinary).

decode_output_msg(<<?THIS_CMD:7, CCmd:9, MsgBinary/binary>>) ->
    decode_output(CCmd, MsgBinary).

{{#rpc_list}}
handle_msg(?C_CMD_{{input_upper}}, MsgType, Binary, State) ->
    Msg = {{gpb_proto}}:decode_msg(Binary, {{input}}),
    {{handle_mod}}:{{handle_func}}({MsgType, Msg}, State);
{{/rpc_list}}
{{#input_list}}
handle_msg(?C_CMD_{{input_upper}}, MsgType, Binary, State) ->
    Msg = {{gpb_proto}}:decode_msg(Binary, {{input}}),
    {{handle_mod}}:{{handle_func}}({MsgType, Msg}, State);
{{/input_list}}
handle_msg(CCmd, _Msg, _Binary, _State) ->
    {error, {not_defined_c_cmd, CCmd}}.

{{#rpc_list}}
decode_input(?C_CMD_{{input_upper}}, MsgBinary) ->
    {{{handle_mod}}, {{handle_func}}, {{gpb_proto}}:decode_msg(MsgBinary, {{input}})};
{{/rpc_list}}
{{#input_list}}
decode_input(?C_CMD_{{input_upper}}, MsgBinary) ->
    {{{handle_mod}}, {{handle_func}}, {{gpb_proto}}:decode_msg(MsgBinary, {{input}})};
{{/input_list}}
decode_input(CCmd, _MsgBinary) ->
    {error, {not_defined_c_cmd, CCmd}}.

{{#output_list}}
decode_output(?C_CMD_{{output_upper}}, MsgBinary) ->
    {{gpb_proto}}:decode_msg(MsgBinary, {{output}});
{{/output_list}}
decode_output(CCmd, _MsgBinary) ->
    {error, {not_defined_c_cmd, CCmd}}.

encode_msg(CCmd, RespMsg) ->
    RespBinary = {{gpb_proto}}:encode_msg(RespMsg),
    <<?THIS_CMD:7, CCmd:9, RespBinary/binary>>.

send_msg(undefined, _CCmd, _Msg) -> undefined;
send_msg(Pid, CCmd, Msg) ->
    Binary = encode_msg(CCmd, Msg),
    Pid ! {send, Binary},
    ok.

-endif.
```

再来看看生成的文件`src/msg/msg_base.erl`:

```erlang
%% -*- coding: utf-8 -*-
%% Automatically generated, do not edit
%% Generated by gpb_rpc_compile
-module(msg_base).

-compile(inline).

-include("msg.hrl").
-ifdef(CMD_MSG_BASE).
-include("msg_base.hrl").
-include("msg_base_pb.hrl").

-define(THIS_CMD, ?CMD_MSG_BASE).

-export([
    handle_msg/3,
    decode_input_msg/1,
    decode_output_msg/1,
    decode_input/2,
    decode_output/2,
    encode_msg/2,
    send_msg/3,
    handle_msg/4
]).

-callback heartbeat(ex_msg:msg(), ex_msg:state()) -> ex_msg:func_reply().
-callback heartbeat_1(ex_msg:msg(), ex_msg:state()) -> ex_msg:func_reply().

handle_msg(?C_CMD_HEARTBEAT_REQ, Binary, State) ->
    Msg = msg_base_pb:decode_msg(Binary, heartbeat_req),
    Maps = mod_base:heartbeat(Msg, State),
    case maps:find(msg, Maps) of
        {ok, RespMsg} ->
            PbBinary = msg_base_pb:encode_msg(RespMsg),
            RespBinary = <<?THIS_CMD:7, ?C_CMD_HEARTBEAT_RESP:9, PbBinary/binary>>,
            case maps:find(resp_binary, Maps) of
                {ok, RespBinaryList} when is_list(RespBinaryList) ->
                    Maps#{resp_binary => [RespBinary | RespBinaryList]};
                {ok, OldRespBinary} ->
                    Maps#{resp_binary => [RespBinary, OldRespBinary]};
                error ->
                    Maps#{resp_binary => RespBinary}
            end;
        error -> Maps
    end;
handle_msg(?C_CMD_HEARTBEAT_REQ, Binary, State) ->
    Msg = msg_base_pb:decode_msg(Binary, heartbeat_req),
    mod_base:heartbeat_1(Msg, State);
handle_msg(CCmd, _Binary, _State) ->
    #{error => {not_defined_c_cmd, CCmd}}.

decode_input_msg(<<?THIS_CMD:7, CCmd:9, MsgBinary/binary>>) ->
    decode_input(CCmd, MsgBinary).

decode_output_msg(<<?THIS_CMD:7, CCmd:9, MsgBinary/binary>>) ->
    decode_output(CCmd, MsgBinary).

handle_msg(?C_CMD_HEARTBEAT_REQ, MsgType, Binary, State) ->
    Msg = msg_base_pb:decode_msg(Binary, heartbeat_req),
    mod_base:heartbeat({MsgType, Msg}, State);
handle_msg(?C_CMD_HEARTBEAT_REQ, MsgType, Binary, State) ->
    Msg = msg_base_pb:decode_msg(Binary, heartbeat_req),
    mod_base:heartbeat_1({MsgType, Msg}, State);
handle_msg(CCmd, _Msg, _Binary, _State) ->
    {error, {not_defined_c_cmd, CCmd}}.

decode_input(?C_CMD_HEARTBEAT_REQ, MsgBinary) ->
    {mod_base, heartbeat, msg_base_pb:decode_msg(MsgBinary, heartbeat_req)};
decode_input(?C_CMD_HEARTBEAT_REQ, MsgBinary) ->
    {mod_base, heartbeat_1, msg_base_pb:decode_msg(MsgBinary, heartbeat_req)};
decode_input(CCmd, _MsgBinary) ->
    {error, {not_defined_c_cmd, CCmd}}.

decode_output(?C_CMD_HEARTBEAT_RESP, MsgBinary) ->
    msg_base_pb:decode_msg(MsgBinary, heartbeat_resp);
decode_output(CCmd, _MsgBinary) ->
    {error, {not_defined_c_cmd, CCmd}}.

encode_msg(CCmd, RespMsg) ->
    RespBinary = msg_base_pb:encode_msg(RespMsg),
    <<?THIS_CMD:7, CCmd:9, RespBinary/binary>>.

send_msg(undefined, _CCmd, _Msg) -> undefined;
send_msg(Pid, CCmd, Msg) ->
    Binary = encode_msg(CCmd, Msg),
    Pid ! {send, Binary},
    ok.
```

-----

再看看[hrl模板文件](example/templates/gpb_rpc/gpb_rpc.hrl.tpl):

```erl
-ifndef({{proto_name_upper}}_H).
-define({{proto_name_upper}}_H, true).

{{#enums_list}}
%% {{enum_name}}
{{#enum_list}}
-define({{enum_name_upper}}_{{enum_key_upper}}, {{enum_value}}). %% {{enum_key}}
-define({{enum_name_upper}}_{{enum_key_upper}}_KEY, '{{enum_key}}'). %% {{enum_value}}
{{/enum_list}}

{{/enums_list}}
-endif.
```

看看生成的文件:

`msg.hrl`:

```erlang
%% -*- coding: utf-8 -*-
%% Automatically generated, do not edit
%% Generated by gpb_rpc_compile
-ifndef(MSG_H).
-define(MSG_H, true).

%% cmd
-define(CMD_MSG_BASE, 0). %% msg_base
-define(CMD_MSG_BASE_KEY, 'msg_base'). %% 0
```

`msg_base.hrl`:

```erlang
%% -*- coding: utf-8 -*-
%% Automatically generated, do not edit
%% Generated by gpb_rpc_compile
-ifndef(MSG_BASE_H).
-define(MSG_BASE_H, true).

%% c_cmd
-define(C_CMD_HEARTBEAT_REQ, 0). %% heartbeat_req
-define(C_CMD_HEARTBEAT_REQ_KEY, 'heartbeat_req'). %% 0
-define(C_CMD_HEARTBEAT_RESP, 1). %% heartbeat_resp
-define(C_CMD_HEARTBEAT_RESP_KEY, 'heartbeat_resp'). %% 1
```

## 使用

`example.erl`:

```erlang
-module(example).

%% API exports
-export([
    handle_msg/2,
    mk_resp/0
]).

-include("msg_base.hrl").
-include("msg_base_pb.hrl").

%%====================================================================
%% API functions
%%====================================================================

handle_msg(<<Cmd:7, CCmd:9, Binary/binary>>, State) ->
    MsgMod = msg_pb:enum_symbol_by_value_cmd(Cmd),
    MsgMod:handle_msg(CCmd, Binary, State).

mk_resp() ->
    msg_base:encode_msg(?C_CMD_HEARTBEAT_RESP, #heartbeat_resp{}).
```

当外部需要处理消息是,只需要调用`example:handle_msg(Binary, State)`之后会根据之前定义好的协议头和方法去分发消息处理,以上面心跳的例子来说,当收到`<<0:7, 0:9, Binary/binary>>`的协议时,`Cmd=0`, `CCmd=0`,转换成枚举就是`Cmd=msg_base`,`CCmd=heartbeat_req`,然后会分发到处理函数`mod_base:heartbeat(#heartbeat_req{}, State)`

`mod_base.erl`:

```erlang
-module(mod_base).
-behavior(msg_base).
%% API
-export([
    heartbeat/2,
    heartbeat_1/2
]).

-include("msg_base.hrl").
-include("msg_base_pb.hrl").

heartbeat(#heartbeat_req{}, _State) ->
    #{msg => #heartbeat_resp{}}.

heartbeat_1(#heartbeat_req{}, _State) ->
    #{}.
```