跳到主要内容

插件基本概念

整体架构​

YedMQ 插件系统采用语言无关和进程隔离的架构设计，以确保最大程度的灵活性和稳定性。

  • 语言无关: 您可以使用任何支持网络套接字通信的编程语言来开发插件。
  • 进程隔离: 每个插件都在其自己的子进程中运行，由 YedMQ 主代理程序管理。这确保了插件中的崩溃或错误不会影响代理程序或其他插件的稳定性。
  • 跨平台: 通信机制建立在大多数操作系统上可用的标准技术之上（Linux/Unix 上的 Unix 域套接字，Windows 上的命名管道）。

通信​

YedMQ 代理和其插件通过进程间通信（IPC）进行通信。

  • 传输层:
    • Linux/Unix: Unix Domain Sockets
    • Windows: Named Pipes
  • 协议: 通信遵循自定义的二进制协议。协议消息的有效载荷使用 Protocol Buffers (Protobuf) 进行序列化，提供了一种定义良好、高效且语言无关的数据结构化方式。

协议帧​

通信帧的基本结构如下：

* +-----------+--------+----------------------+----------------------+
* | Magic     | Version| Length               | Payload              |
* | Number    |        | (4 bytes)            | (Protobuf)           |
* | (4 bytes) |(1 byte)| (Big Endian)         |                      |
* +-----------+--------+----------------------+----------------------+
* 0           4        5                      9                      9+N
  • 魔数 (Magic Number): 0x5514
  • 版本 (Version): 0x01
  • 长度 (Length): 一个4字节的整数，表示有效载荷的大小。
  • 有效载荷 (Payload): Protobuf 序列化的 ProtocolMessage。

所有通信，无论是请求、响应还是通知，都被包装在 ProtocolMessage 中。有关详细的消息定义，请参阅 协议定义 页面或 yedmq_plugin_protocol.proto 文件。

插件配置​

每个插件都需要一个 plugin.toml 文件，用于描述其元数据和运行时配置。该文件告诉 YedMQ 如何启动和管理插件进程。

plugin.toml 示例：

[plugin]
name = "my_auth_plugin"
version = "0.1.0"
description = "一个认证插件"
author = "我的公司"
license = "MIT"
homepage = "http://example.com"
repository = "https://github.com/example/my-plugin"

[runtime]
type = "process"
executable = "./my_auth_plugin_executable" # 插件可执行文件的路径
args = ["--config", "/etc/yedmq/my_plugin.json"] # 可选参数
env = { LOG_LEVEL = "info" } # 可选环境变量
working_dir = "." # 可选工作目录
timeout_secs = 12 # 启动超时时间（秒）
  • [plugin] 部分: 包含有关插件的通用元数据。
  • [runtime] 部分:
    • type: 必须是 "process"。
    • executable: 插件可执行文件的路径。
    • args: 启动插件时传递的命令行参数数组。
    • env: 为插件进程设置的环境变量映射。
    • working_dir: 插件进程的工作目录。
    • timeout_secs: YedMQ 在插件初始化超时前等待的时间。

插件生命周期​

插件在其生命周期中会经历几个状态，由 YedMQ 代理管理。

graph TD
    Discovered[已发现] -->|加载| Starting[启动中]
    Starting -->|初始化完成| Running[运行中]
    Starting -->|启动异常| Failed[失败]
    Running -->|停止指令| Stopping[停止中]
    Stopping -->|资源已释放| Stopped[已停止]
    Stopped -->|重新启动| Starting
    Failed -->|重试| Starting
  1. 已发现 (Discovered): YedMQ 已找到插件的配置文件，但尚未启动它。
  2. 启动中 (Starting): 代理已为插件派生一个新进程，并等待其初始化。
  3. 运行中 (Running): 插件已成功初始化并正在积极处理钩子。
  4. 停止中 (Stopping): 插件已收到关闭信号并正在进行清理。
  5. 已停止 (Stopped): 插件进程已正常终止。
  6. 失败 (Failed): 插件在启动或运行期间失败或崩溃。

健康检查​

代理定期向正在运行的插件发送 Ping 消息。插件必须以 Pong 消息响应。如果代理在一定次数的重试后未能收到响应，它将认为插件不健康并尝试重新启动它。

安全性​

为防止未经授权的进程连接到代理，YedMQ 使用安全令牌机制。

  1. 当代理启动插件进程时，它会传递一个唯一的 --auth-code 作为命令行参数。
  2. 插件必须在其返回给代理的 InitializeResponse 消息中包含此 auth-code。
  3. 如果 auth-code 缺失或不正确，代理将立即终止连接。

执行优先级​

您可以在 plugin.toml 的 [plugin] 部分定义一个 priority。这个整数值决定了由多个插件实现的钩子的执行顺序。

  • 数字越小，优先级越高。优先级为 100 的插件将在优先级为 1000 的插件之前运行。
  • 对于可以终止执行链的钩子（例如，认证），第一个处理请求的插件可能会阻止其他插件运行。
  • 对于在链中修改数据的钩子，执行顺序至关重要。