# 设计

## 动机

增强系统的扩展性。包含的目的有：

- 完全支持各种钩子，能够根据其返回值修改 EMQ X 或者 Client 的行为。
  - 例如 `auth/acl`：可以查询数据库或者执行某种算法校验操作权限。然后返回 `false` 表示 `认证/ACL` 失败。
  - 例如 `message.publish`：可以解析 `消息/主题` 并将其存储至数据库中。

- 支持多种语言的扩展；并包含该语言的示例程序。
  - python
  - webhook
  - Java
  - Lua
  - c，go，.....
- 热操作
  - 允许在插件运行过程中，添加和移除 `Driver`。

- 需要 CLI ，甚至 API 来管理 `Driver`

注：`message` 类钩子仅包括在企业版中。

## 设计

架构如下：

```
 EMQ X                                      Third-party Runtimes
+========================+                 +====================+
|    Extension           |                 |                    |
|   +----------------+   |     Hooks       |  Python scripts /  |
|   |    Drivers     | ------------------> |  Java Classes   /  |
|   +----------------+   |     (pipe)      |  Others ...        |
|                        |                 |                    |
+========================+                 +====================+
```

### 配置文件示例

#### 驱动 配置

```properties
## Driver type
##
## Exmaples:
##   - python3                   --- 仅配置 python3
##   - python3, java, webhook    --- 配置多个 Driver
exhook.dirvers = python3, java, webhook

## --- 具体 driver 的配置详情

## Python
exhook.dirvers.python3.path = data/extension/python
exhook.dirvers.python3.call_timeout = 5s
exhook.dirvers.python3.pool_size = 8

## java
exhook.drivers.java.path = data/extension/java
...
```

#### 钩子配置

钩子支持配置在配置文件中，例如：

```properties
exhook.rule.python3.client.connected = {"module": "client", "callback": "on_client_connected"}
exhook.rule.python3.message.publish  = {"module": "client", "callback": "on_client_connected", "topics": ["#", "t/#"]}
```

***已废弃！！（冗余）***


###  驱动抽象

#### APIs

| 方法名                   | 说明     | 入参   | 返回   |
| ------------------------ | -------- | ------ | ------ |
| `init`                   | 初始化   | -      | 见下表 |
| `deinit`                 | 销毁     | -      | -      |
| `xxx `*(由init函数定义)* | 钩子回调 | 见下表 | 见下表 |



##### init 函数规格

```erlang
%% init 函数
%% HookSpec 			: 为用户在脚本中的 初始化函数指定的；他会与配置文件中的内容作为默认值，进行合并
%%          			  该参数的目的，用于 EMQ X 判断需要执行哪些 Hook 和 如何执行 Hook
%% State    			: 为用户自己管理的数据内容，EMQ X 不关心它，只来回透传
init() -> {HookSpec, State}.

%% 例如：
{[{client_connect, callback_m(), callback_f(),#{}, {}}]}

%%--------------------------------------------------------------
%% Type Defines

-tpye hook_spec() :: [{hookname(), callback_m(), callback_f(), hook_opts()}].

-tpye state :: any().

-type hookname() :: client_connect
                  | client_connack
                  | client_connected
                  | client_disconnected
                  | client_authenticate
                  | client_check_acl
                  | client_subscribe
                  | client_unsubscribe
                  | session_created
                  | session_subscribed
                  | session_unsubscribed
                  | session_resumed
                  | session_discarded      %% TODO: Should squash to `terminated` ?
                  | session_takeovered     %% TODO: Should squash to `terminated` ?
                  | session_terminated
                  | message_publish
                  | message_delivered
                  | message_acked
                  | message_dropped.

-type callback_m() :: atom().          -- 回调的模块名称；python 为脚本文件名称；java 为类名；webhook 为 URI 地址

-type callback_f() :: atom().          -- 回调的方法名称；python，java 等为方法名；webhook 为资源地址

-tpye hook_opts() :: [{hook_key(), any()}].  -- 配置项；配置该项钩子的行为

-type hook_key() :: topics | ...
```



##### deinit 函数规格

``` erlang
%% deinit 函数；不关心返回的任何内容
deinit() -> any().
```



##### 回调函数规格

| 钩子                 | 入参                                                  | 返回      |
| -------------------- | ----------------------------------------------------- | --------- |
| client_connect       | `connifno`<br />`props`                               | -         |
| client_connack       | `connifno`<br />`rc`<br />`props`                     | -         |
| client_connected     | `clientinfo`<br />                                    | -         |
| client_disconnected  | `clientinfo`<br />`reason`                            | -         |
| client_authenticate  | `clientinfo`<br />`result`                            | `result`  |
| client_check_acl     | `clientinfo`<br />`pubsub`<br />`topic`<br />`result` | `result`  |
| client_subscribe     | `clientinfo`<br />`props`<br />`topicfilters`         | -         |
| client_unsubscribe   | `clientinfo`<br />`props`<br />`topicfilters`         | -         |
| session_created      | `clientinfo`                                          | -         |
| session_subscribed   | `clientinfo`<br />`topic`<br />`subopts`              | -         |
| session_unsubscribed | `clientinfo`<br />`topic`                             | -         |
| session_resumed      | `clientinfo`                                          | -         |
| session_discared     | `clientinfo`                                          | -         |
| session_takeovered   | `clientinfo`                                          | -         |
| session_terminated   | `clientinfo`<br />`reason`                            | -         |
| message_publish      | `messsage`                                            | `message` |
| message_delivered    | `clientinfo`<br />`message`                           | -         |
| message_dropped      | `message`                                             | -         |
| message_acked        | `clientinfo`<br />`message`                           | -         |



上表中包含数据格式为：

```erlang
-type conninfo :: [ {node, atom()}
                  , {clientid, binary()}
                  , {username, binary()}
                  , {peerhost, binary()}
							    , {sockport, integer()}
                  , {proto_name, binary()}
                  , {proto_ver, integer()}
                  , {keepalive, integer()}
								  ].

-type clientinfo :: [ {node, atom()}
                    , {clientid, binary()}
                    , {username, binary()}
                    , {password, binary()}
                    , {peerhost, binary()}
							      , {sockport, integer()}
                    , {protocol, binary()}
                    , {mountpoint, binary()}
                    , {is_superuser, boolean()}
                    , {anonymous, boolean()}
								    ].

-type message :: [ {node, atom()}
                 , {id, binary()}
                 , {qos, integer()}
                 , {from, binary()}
                 , {topic, binary()}
                 , {payload, binary()}
                 , {timestamp, integer()}
                 ].

-type rc :: binary().
-type props :: [{key(), value()}]

-type topics :: [topic()].
-type topic :: binary().
-type pubsub :: publish | subscribe.
-type result :: true | false.
```



### 统计

在驱动运行过程中，应有对每种钩子调用计数，例如：

```
exhook.python3.check_acl               10
```



### 管理

**CLI 示例：**



**列出所有的驱动**

```
./bin/emqx_ctl exhook dirvers list
Drivers(xxx=yyy)
Drivers(aaa=bbb)
```



**开关驱动**

```
./bin/emqx_ctl exhook drivers enable python3
ok

./bin/emqx_ctl exhook drivers disable python3
ok

./bin/emqx_ctl exhook drivers stats
python3.client_connect     123
webhook.check_acl          20
```