AimRT/document/sphinx-cn/tutorials/plugins/net_plugin.md

Net 插件

相关链接

参考示例：

• {{ 'net_plugin'.format(code_site_root_path_url) }}

插件概述

net_plugin是一个基于 boost asio/beast 库实现的网络传输插件，此插件提供了以下组件：

• http类型 RPC 后端
• http类型 Channel 后端
• tcp类型 Channel 后端
• udp类型 Channel 后端

插件的配置项如下：

节点	类型	是否可选	默认值	作用
thread_num	int	必选	2	net 插件需要使用的线程数
http_options	map	可选	-	http 相关选项
http_options.listen_ip	string	可选	"0.0.0.0"	http 监听 IP
http_options.listen_port	int	必选	-	http 监听端口，端口不能被占用
tcp_options	map	可选	-	tcp 相关选项
tcp_options.listen_ip	string	可选	"0.0.0.0"	tcp 监听 IP
tcp_options.listen_port	int	必选	-	tcp 监听端口，端口不能被占用
udp_options	map	可选	-	udp 相关选项
udp_options.listen_ip	string	可选	"0.0.0.0"	udp 监听 IP
udp_options.listen_port	int	必选	-	udp 监听端口，端口不能被占用
udp_options.max_pkg_size	int	可选	1024	udp 包最大尺寸，理论上最大不能超过 65515

关于net_plugin的配置，使用注意点如下：

• thread_num表示 net 插件使用的线程数。
• http_options是可选的，但只有当该节点被配置时，才能开启与 http 相关的功能，如 http Channel 后端、http RPC 后端。
  • http_options.listen_ip用于配置 http 服务监听的地址，默认是"0.0.0.0"，如果仅想在指定网卡上监听，可以将其改为指定 IP。
  • http_options.listen_port用于配置 http 服务监听的端口，此项为必填项，使用者必须确保端口未被占用，否则插件会初始化失败。
• tcp_options是可选的，但只有当该节点被配置时，才能开启与 tcp 相关的功能，如 tcp Channel 后端。
  • tcp_options.listen_ip用于配置 tcp 服务监听的地址，默认是"0.0.0.0"，如果仅想在指定网卡上监听，可以将其改为指定 IP。
  • tcp_options.listen_port用于配置 tcp 服务监听的端口，此项为必填项，使用者必须确保端口未被占用，否则插件会初始化失败。
• udp_options是可选的，但只有当该节点被配置时，才能开启与 udp 相关的功能，如 udp Channel 后端。
  • udp_options.listen_ip用于配置 udp 服务监听的地址，默认是"0.0.0.0"，如果仅想在指定网卡上监听，可以将其改为指定 IP。
  • udp_options.listen_port用于配置 udp 服务监听的端口，此项为必填项，使用者必须确保端口未被占用，否则插件会初始化失败。
  • udp_options.max_pkg_size用于配置 udp 包最大尺寸，理论上最大不能超过 65515。发布的消息序列化之后必须小于这个值，否则会发布失败。

此外，在使用net_plugin时，Channel 订阅回调、RPC Server 处理回调、RPC Client 返回时，使用的都是net_plugin提供的自有线程执行器，当使用者在回调中阻塞了线程时，有可能导致net_plugin线程池耗尽，从而无法继续接收/发送消息。正如 Module 接口文档中所述，一般来说，如果回调中的任务非常轻量，那就可以直接在回调里处理；但如果回调中的任务比较重，那最好调度到其他专门执行任务的执行器里处理。

以下是一个简单的示例：

aimrt:
  plugin:
    plugins:
      - name: net_plugin
        path: ./libaimrt_net_plugin.so
        options:
          thread_num: 4
          http_options:
            listen_ip: 127.0.0.1
            listen_port: 50080
          tcp_options:
            listen_ip: 127.0.0.1
            listen_port: 50081
          udp_options:
            listen_ip: 127.0.0.1
            listen_port: 50082
            max_pkg_size: 1024

http 类型 RPC 后端

http类型的 RPC 后端是net_plugin中提供的一种 RPC 后端，用于通过 HTTP 的方式来调用和处理 RPC 请求。其所有的配置项如下：

节点	类型	是否可选	默认值	作用
clients_options	array	可选	[]	客户端发起 RPC 请求时的规则
clients_options[i].func_name	string	必选	""	RPC Func 名称，支持正则表达式
clients_options[i].server_url	string	必选	""	RPC Func 发起调用时请求的 url

以下是一个简单的客户端的示例：

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

以下则是一个简单的服务端的示例：

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

以上示例中，Server 端监听了本地的 50080 端口，Client 端则配置了所有的 RPC 请求都通过 http 后端请求到http://127.0.0.1:50080这个地址，也就是服务端监听的地址，从而完成 RPC 的调用闭环。

Client 端向 Server 端发起调用时，遵循的格式如下：

• 使用 HTTP POST 方式发送，Body 中填充消息序列化后的请求包数据或回包数据；
• 由content-type Header 来定义 Body 内容的序列化方式，例如：
  • content-type:application/json
  • content-type:application/protobuf
• URL 的编码方式：http://{IP:PORT}/rpc/{FUNC_NAME}：
  • {IP:PORT}：对端的网络地址；
  • {FUNC_NAME}：URL 编码后的 RPC func 名称，以注册 RPC 时传入的为准；

只要遵循这个格式，使用者可以基于 PostMan 或者 Curl 等工具发起调用，以 JSON 作为序列化方式来提高可读性，例如通过以下命令，即可发送一个消息到指定模块上去触发对应的回调：

curl -i \
    -H 'content-type:application/json' \
    -X POST 'http://127.0.0.1:50080/rpc/aimrt.protocols.example.ExampleService/GetFooData' \
    -d '{"msg": "test msg"}'

基于这个特性，http类型的 RPC 后端常用于调试开发或测试阶段，可以通过辅助工具快速触发某个 Server 处理函数，或通过抓包工具来检查上下游之间的通信内容。

http 类型 Channel 后端

http类型的 Channel 后端是net_plugin中提供的一种 Channel 后端，用于将消息通过 HTTP 的方式来发布和订阅消息。其所有的配置项如下：

节点	类型	是否可选	默认值	作用
pub_topics_options	array	可选	[]	发布 Topic 时的规则
pub_topics_options[i].topic_name	string	必选	""	Topic 名称，支持正则表达式
pub_topics_options[i].server_url_list	string array	必选	[]	Topic 需要被发送的 url 列表

以下是一个简单的发布端的示例：

aimrt:
  plugin:
    plugins:
      - name: net_plugin 
        path: ./libaimrt_net_plugin.so
        options:
          thread_num: 4
          http_options:
            listen_ip: 127.0.0.1
            listen_port: 50081
  channel:
    backends:
      - type: http
        options:
          pub_topics_options:
            - topic_name: "(.*)"
              server_url_list: ["127.0.0.1:50080"]
    pub_topics_options:
      - topic_name: "(.*)"
        enable_backends: [http]

以下则是一个简单的订阅端的示例：

aimrt:
  plugin:
    plugins:
      - name: net_plugin 
        path: ./libaimrt_net_plugin.so
        options:
          thread_num: 4
          http_options:
            listen_ip: 127.0.0.1
            listen_port: 50080
  channel:
    backends:
      - type: http
    sub_topics_options:
      - topic_name: "(.*)"
        enable_backends: [http]

以上示例中，订阅端监听了本地的 50080 端口，发布端则配置了所有的 Topic 消息都通过 http 后端请求到127.0.0.1:50080这个地址，也就是服务端监听的地址，订阅端也配置了所有消息都可以从 http 后端触发回调，从而打通消息发布订阅的链路。

发布端向订阅端发布消息时，遵循的格式如下：

• 使用 HTTP POST 方式发送，Body 中填充消息序列化后的数据；
• 由content-type Header 来定义 Body 内容的序列化方式，例如：
  • content-type:application/json
  • content-type:application/protobuf
• URL的编码方式：http://{IP:PORT}/channel/{TOPIC_NAME}/{MSG_TYPE}：
  • {IP:PORT}：对端的网络地址；
  • {TOPIC_NAME}：URL 编码后的 Topic 名称；
  • {MSG_TYPE}：URL 编码后的消息类型名称，消息类型名称以 TypeSupport 中定义的为准；

只要遵循这个格式，使用者可以基于 PostMan 或者 Curl 等工具发起调用，以 JSON 作为序列化方式来提高可读性，例如通过以下命令，即可发送一个消息到指定模块上去触发对应的回调：

curl -i \
    -H 'content-type:application/json' \
    -X POST 'http://127.0.0.1:50080/channel/test_topic/pb%3Aaimrt.protocols.example.ExampleEventMsg' \
    -d '{"msg": "test msg", "num": 123}'

基于这个特性，http类型的 Channel 后端常用于调试开发或测试阶段，可以通过辅助工具快速触发某个回调，或通过抓包工具来检查上下游之间的通信内容。

tcp 类型 Channel后端

tcp类型的 Channel 后端是net_plugin中提供的一种 Channel 后端，用于将消息通过 tcp 的方式来发布和订阅消息。其所有的配置项如下：

节点	类型	是否可选	默认值	作用
pub_topics_options	array	可选	[]	发布 Topic 时的规则
pub_topics_options[i].topic_name	string	必选	""	Topic 名称，支持正则表达式
pub_topics_options[i].server_url_list	string array	必选	[]	Topic 需要被发送的 url 列表

以下是一个简单的发布端的示例：

aimrt:
  plugin:
    plugins:
      - name: net_plugin 
        path: ./libaimrt_net_plugin.so
        options:
          thread_num: 4
          tcp_options:
            listen_ip: 127.0.0.1
            listen_port: 50081
  channel:
    backends:
      - type: tcp
        options:
          pub_topics_options:
            - topic_name: "(.*)"
              server_url_list: ["127.0.0.1:50080"]
    pub_topics_options:
      - topic_name: "(.*)"
        enable_backends: [tcp]

以下则是一个简单的订阅端的示例：

aimrt:
  plugin:
    plugins:
      - name: net_plugin 
        path: ./libaimrt_net_plugin.so
        options:
          thread_num: 4
          tcp_options:
            listen_ip: 127.0.0.1
            listen_port: 50080
  channel:
    backends:
      - type: tcp
    sub_topics_options:
      - topic_name: "(.*)"
        enable_backends: [tcp]

以上示例中，订阅端监听了本地的 50080 端口，发布端则配置了所有的 Topic 消息都通过 tcp 后端请求到127.0.0.1:50080这个地址，也就是服务端监听的地址，从而打通消息发布订阅的链路。

注意，使用 tcp 后端传输消息时，数据格式是私有的，但数据格式将保持版本兼容。

udp 类型 Channel后端

udp类型的 Channel 后端是net_plugin中提供的一种 Channel 后端，用于将消息通过 udp 的方式来发布和订阅消息。其所有的配置项如下：

节点	类型	是否可选	默认值	作用
pub_topics_options	array	可选	[]	发布 Topic 时的规则
pub_topics_options[i].topic_name	string	必选	""	Topic 名称，支持正则表达式
pub_topics_options[i].server_url_list	string array	必选	[]	Topic 需要被发送的 url 列表

以下是一个简单的发布端的示例：

aimrt:
  plugin:
    plugins:
      - name: net_plugin 
        path: ./libaimrt_net_plugin.so
        options:
          thread_num: 4
          udp_options:
            listen_ip: 127.0.0.1
            listen_port: 50081
  channel:
    backends:
      - type: udp
        options:
          pub_topics_options:
            - topic_name: "(.*)"
              server_url_list: ["127.0.0.1:50080"]
    pub_topics_options:
      - topic_name: "(.*)"
        enable_backends: [udp]

以下则是一个简单的订阅端的示例：

aimrt:
  plugin:
    plugins:
      - name: net_plugin 
        path: ./libaimrt_net_plugin.so
        options:
          thread_num: 4
          udp_options:
            listen_ip: 127.0.0.1
            listen_port: 50080
  channel:
    backends:
      - type: udp
    sub_topics_options:
      - topic_name: "(.*)"
        enable_backends: [udp]

以上示例中，订阅端监听了本地的 50080 端口，发布端则配置了所有的 Topic 消息都通过udp后端请求到127.0.0.1:50080这个地址，也就是服务端监听的地址，从而打通消息发布订阅的链路。

注意，使用 udp 后端传输消息时，数据格式是私有的，但数据格式将保持版本兼容。