多语言支持

从 4.1 开始,EMQ X 提供了专门的多语言支持插件:emqx_extension_hook多语言支持 - 图1 (opens new window) 以优化多语言的支持效果。

该插件允许你使用其它编程语言来处理 EMQ X 中的钩子事件,例如:

  • 认证某客户端的登录权限。
  • 校验某客户端的 PUB/SUB 的操作权限。
  • 处理 会话(Session) 和 消息(Message) 事件。

注:消息(Message) 类钩子,仅在企业版中支持。

架构

其整体的事件传递的架构如下:

  1. EMQ X
  2. +============================+
  3. | Extension |
  4. +----------+ CONNECT | Hooks +----------------+ |
  5. | Client | <===========> - - - ->| Drivers | |
  6. +----------+ PUB/SUB | +----------------+ |
  7. | | |
  8. +===============|============+
  9. |
  10. | Callbacks
  11. Third-party Runtimes |
  12. +=======================+ |
  13. | Python Script/ Java |<-----+
  14. | Classes/ Others |
  15. +=======================+
  • emqx_extension_hook 作为 EMQ X 的插件:

    • 它会接收 EMQ X 所有的钩子事件,并将其分发到对应的 驱动(Driver) 上。
    • 提供对驱动的管理、各个指标的统计。
  • 不同语言的支持,需要对应的驱动支持。

  • 三方语言的运行时和 Erlang 的运行时相互独立,他们仅通过操作系统提供的管道进行通信。

理论上,对于其他任意的编程语言都能通过该插件进行扩展,仅需完成对应的驱动即可。

目前仅提供 Python 和 Java 的支持,并提供了对应的 SDK 以方便开发。

快速使用

Python

Python 开发可参考:emqx-extension-python-sdk多语言支持 - 图2 (opens new window)

Java

Java 开发可参考:emqx-extension-java-sdk多语言支持 - 图3 (opens new window)

其他

在 EMQ X 4.1 之前。我们仅提供 Lua 的多语言支持。它的架构与上面提到的不同,它会将整个语言的运行时,包含在 Erlang VM 中:

Old Multiple Lang Arch

  • 多语言支持是作为一个插件出现,不同的语言环境,需要有不同的语言支持插件。
  • 该支持插件内嵌了该语言运行时的所有环境。

为了保持兼容,该插件仍然保留在 EMQ X 的发行版本中。

Lua

Lua 的支持由 emqx_lua_hook多语言支持 - 图5 (opens new window) 实现。它包括:

  • 一套 Lua 的运行时环境,由 luerl多语言支持 - 图6 (opens new window) 实现。
  • 一些控制命令,用于管理 Lua 的加载和卸载等。

示例

在 EMQ X 发行包中,用户自定义的 Lua 脚本文件应该放在 data/script/ 中。

以控制消息的发送内容为例,新增文件 data/script/test.lua

  1. function on_message_publish(clientid, username, topic, payload, qos, retain)
  2. return topic, "hello", qos, retain
  3. end
  4. function register_hook()
  5. return "on_message_publish"
  6. end

该脚本表明:

  • 实现了一个回调函数 on_message_publish,将所有发布消息的 payload 字段修改为 hello
  • register_hook 告诉 emqx_lua_hook,需要注册的回调函数名称列表。

值得注意的是,这些回调函数的名称、参数、返回值的数据类型和个数都是固定,必须与提供的示例一致。

脚本编写完成后,需要手动将其加载至 emqx_lua_hook 插件中:

首先确保 emqx_lua_hook 插件已经启动:

  1. ./bin/emqx_ctl plugins load emqx_lua_hook

加载 test.luaemqx_lua_hook 中:

  1. ./bin/emqx_ctl luahook load test.lua

执行成功,则表示脚本已成功加载。否则,请检查源文件的语法格式是否正确。

完成后,可以启动两个 MQTT 客户端,一个订阅主任意主题,另一个发布任意消息到刚刚订阅的主题上。可发现订阅端收到的消息内容都是 hello。证明 test.lua 脚本已经生效。

回调函数

支持的回调函数,及参数类型参考:emqx-lua-hook - README.md多语言支持 - 图7 (opens new window)

示例参考:examples.lua多语言支持 - 图8 (opens new window)

命令

加载指定 Lua 脚本:

  1. ## Script:脚本文件名称
  2. luahook load <Script>

卸载指定 Lua 脚本:

  1. luahook unload <Script>

重新加载指定 Lua 脚本:

  1. luahook reload <Script>

加载指定 Lua 脚本,并设置其跟随 emqx_lua_hook 启动时一同启动:

  1. luahook enable <Script>

卸载指定 Lua 脚本,并取消跟随 emqx_lua_hook 一同启动:

  1. luahook disable <Script>