Manticore Buddy: pluggable design v2

Manticore Buddy: pluggable design v2

已发布: Aug 05, 2023
自动翻译: Manticore Buddy: pluggable design v2

各位朋友。关于Manticore Buddy的激动人心的消息：我们已经完成了向插件化设计的迁移！这意味着你可以构建自己的Manticore Search SQL/JSON查询作为插件，在 packagist.org 上发布，并使用CREATE PLUGINSQL命令进行安装。让我们深入探讨插件系统的架构以及一个简单的教程，帮助你入门。

架构

简介

如果你不熟悉Buddy，我们建议阅读以下博客文章：

我们之前发布的文章。

最初，Buddy是用PHP开发的，所有扩展和额外命令处理器都在同一个代码库中。在 Manticore Search 6 发布后，我们收到了关于添加自定义功能的问题，并意识到当前系统缺乏灵活性。这就是为什么我们要迁移到插件化架构的原因。

我们认为软件开发中最重要的一条原则是不要重新发明轮子，保持简单。因此，我们没有花费太多时间进行权衡，而是选择了PHP世界中最知名和流行的包管理器—— Packagist 来管理插件系统。

插件类型

有三种类型的插件：

core - 默认包含在Buddy中，并且当你安装Manticore时会收到该插件包的一部分。
local - 用于开发和调试，然后发布。
external - 使用CREATE PLUGIN命令安装。

本教程将解释如何首先创建一个local插件，然后将其转换为external插件，使任何Manticore用户都可以通过使用你的插件来增强他们的设置。

请求 -> 响应流程

为了使其工作，我们将Buddy和所有插件中常用组件提取到一个新的包中—— Buddy Core 。在开发插件时，它应该被包含进来，以简化IDE中的操作并支持提示和自动完成。

使Buddy能够作为守护进程运行并执行内部任务（包括连接核心和插件源代码）的代码称为Buddy Base。这是一个ReactPHP应用程序，也使用 Buddy Core ，具有基本逻辑以使一切正常运行并在命令下找到正确的插件启动。

为了更清楚地理解过程，这里有一个示意图说明请求 → 响应流程：

Manticore Buddy 请求到响应流程

教程

为了让事情变得更容易，并深入开发自己的插件，请查看我们如何构建一个支持SHOW HOSTNAME命令并返回当前主机名的简单插件。这将帮助你了解创建自己插件时应遵循的过程，而且这也是一个非常简单的开始示例。如果我们先研究一下Manticore Search中SHOW HOSTNAME的功能，然后再实现其逻辑，我们可以期望得到类似的结果：

mysql> SHOW HOSTNAME;
ERROR 1064 (42000): sphinxql: syntax error, unexpected identifier, expecting VARIABLES near 'HOSTNAME'

准备工作

首先，我们应该准备我们的开发环境。你只需要这样做一次，之后可以从 ManticoreSearch-Buddy的GIT仓库更新Buddy以接收最新更新。让我们打开终端并克隆Buddy到我们的机器上的一个名为manticoresearch-buddy的文件夹中，然后导航到克隆的文件夹。

git clone --depth 1 https://github.com/manticoresoftware/manticoresearch-buddy.git
cd manticoresearch-buddy

现在你有了Buddy的整个源代码，但还没有安装任何包。Buddy使用Composer来管理其依赖项，我们需要先安装它们才能运行应用程序。但在那之前，我们将运行一个专门为开发准备的特殊Docker容器。Manticore Executor Kit镜像包括了Manticore Buddy开发所需的全部工具，无论是创建新插件还是贡献Buddy本身。

docker pull ghcr.io/manticoresoftware/manticoresearch:test-kit-latest
docker create --privileged --entrypoint bash \
  -v $(pwd):/workdir -w /workdir --name manticore-buddy \
  --network host -it ghcr.io/manticoresoftware/manticoresearch:test-kit-latest
docker start manticore-buddy

恭喜！你现在启动了一个包含Manticore Search和Manticore Executor的Docker容器来开发Buddy和插件。你当前所在的目录映射到了容器内的/workdir。你的下一步是安装Composer依赖项。请记住，所有后续命令都必须在manticore-buddy容器内执行。

docker exec -it manticore-buddy bash
composer install

你的Buddy现在可以使用、开发、调试和测试了。接下来，你需要完成两件事：

首先，在容器内编辑/etc/manticoresearch/manticore.conf，并在此处添加buddy_path，指向我们的源代码路径。这将让Manticore Search知道我们需要从源代码而不是已安装模块的路径运行Buddy。在searchd部分添加此内容：
```
buddy_path = manticore-executor /workdir/src/main.php --debug
```
第二步，尝试运行searchd（Manticore Search服务器），确保它能正常工作。
```
# Launch daemon inside the container and keep it foreground
searchd --nodetach
```
你应该看到几行以[BUDDY]开头的内容。

此时，一切都已准备好，可以为Buddy准备开发环境并开始实现新的插件。你可以继续实验并尝试执行一些查询以确保一切正常运行。例如，在另一个终端窗口中运行以下命令：

$ docker exec -it manticore-buddy mysql -h0 -P9306
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MySQL connection id is 6
Server version: 6.0.5 3bcbd00fa@230320 dev (columnar 2.0.5 8171c1a@230320) (secondary 2.0.5 8171c1a@230320) git branch HEAD (no branch)

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MySQL [(none)]> show queries;
+------+--------------+----------+-----------------+
| id   | query        | protocol | host            |
+------+--------------+----------+-----------------+
|   10 | select       | http     | 127.0.0.1:19148 |
|    9 | show queries | mysql    | 127.0.0.1:54484 |
+------+--------------+----------+-----------------+
2 rows in set (0.008 sec)

MySQL [(none)]>

你刚刚向Manticore Search发送了SHOW QUERIES命令，该命令随后被路由到Buddy并成功执行。你可以在第一个终端标签页中的搜索日志中看到Buddy接收到的内容及其响应。所以，我们可以确认Buddy正在正确运行并且一切设置正确。

当你想停止searchd进程时，只需在第一个终端窗口/标签页中按Ctrl + C即可。

插件模板

我们创建了一个特殊的GitHub模板仓库，强烈建议您使用它来创建任何Manticore Buddy插件。所有插件名称都应以buddy-plugin-[your-name]开头，其中[your-name]是您的插件名称。例如，由于我们正在开发一个主机名选择插件，我们将它命名为buddy-plugin-show-hostname。所以：

打开 https://github.com/manticoresoftware/buddy-plugin-template 。
点击Use this template，然后点击Create a new repository。
在表单中填写您的仓库名称并创建它。确保您的仓库名称以buddy-plugin-开头，这是强制要求的。
将您的新仓库git clone到之前部署的Manticore Buddy仓库的plugins目录中。请注意，最好在容器外部执行此操作，特别是如果您正在克隆私有仓库。

在 https://github.com/manticoresoftware/buddy-plugin-show-hostname ，您可以找到整个任务的实现。如果您不想深入细节，可以直接git clone该仓库，而不是您分叉的仓库。但是，如果您确实想掌握创建插件的技能，让我们继续。

添加真实代码

现在我们需要按照以下步骤更新我们的模板，以添加与新插件相关的内容。

首先，在您克隆的插件目录中打开composer.json，并更新插件的名称、描述和命名空间。最终，您的更改应如下所示（请确保使用您插件的仓库名称）：

diff --git a/composer.json b/composer.json
index 23c252b..f36cb6e 100644
--- a/composer.json
+++ b/composer.json
@@ -1,11 +1,11 @@
 {
- "name": "manticoresoftware/buddy-plugin-template",
- "description": "The Buddy template handler plugin",
+ "name": "manticoresoftware/buddy-plugin-show-hostname",
+ "description": "The Buddy SHOW hostname handler plugin",
  "type": "library",
  "license": "GPL-2.0-or-later",
  "autoload": {
    "psr-4": {
-     "Manticoresearch\\Buddy\\Plugin\\Template\\": "src/"
+     "Manticoresearch\\Buddy\\Plugin\\ShowHostname\\": "src/"
    }
  },
  "authors": [

我们还需要更新插件中两个类的命名空间——Payload和Handler。差异应如下所示：

diff --git a/src/Handler.php b/src/Handler.php
index 3756dc3..07fcfd0 100644
--- a/src/Handler.php
+++ b/src/Handler.php
@@ -8,7 +8,7 @@
   version. You should have received a copy of the GPL license along with this
   program; if you did not, you can find it at http://www.gnu.org/
 */
-namespace Manticoresearch\Buddy\Plugin\Template;
+namespace Manticoresearch\Buddy\Plugin\ShowHostname;

 use Manticoresearch\Buddy\Core\Plugin\BaseHandler;
 use Manticoresearch\Buddy\Core\Task\Task;
diff --git a/src/Payload.php b/src/Payload.php
index b170340..a35f201 100644
--- a/src/Payload.php
+++ b/src/Payload.php
@@ -8,7 +8,7 @@
   version. You should have received a copy of the GPL license along with this
   program; if you did not, you can find it at http://www.gnu.org/
 */
-namespace Manticoresearch\Buddy\Plugin\Template;
+namespace Manticoresearch\Buddy\Plugin\ShowHostname;

 use Manticoresearch\Buddy\Core\Network\Request;
 use Manticoresearch\Buddy\Core\Plugin\BasePayload;

作为最后一步，请不要忘记通过在容器内运行composer install来安装新依赖项（在/workdir中）。

从Manticore Search到您的插件及返回的请求流程

我们现在准备实现我们的逻辑。但首先，让我们了解一些关于其内部处理方式的更多信息。

Manticore Buddy请求到插件流程

假设我们使用MySQL客户端向启动的searchd进程发送SHOW HOSTNAME查询。Manticore Search无法处理它，会将其发送给Buddy以等待响应。Buddy可以返回确切的响应，该响应将简单地代理回MySQL客户端。

一旦Buddy从Manticore Search接收到查询，它会解析它，并在所有插件上运行验证：首先核心插件，然后外部插件。为了运行此验证，它会执行Payload::hasMatch($request)方法，将请求传递给它，其中包含查询和一些元数据，例如请求的端点、类型（JSON或SQL）等。

Payload表示包含处理命令所需所有数据的结构。如果插件的Payload在hasMatch方法中返回true，则表示我们将使用此插件来处理请求。它是从Request创建的，此时我们需要解析查询，提取有价值的信息，并将其设置到我们的payload数据中，这些数据将传递给Handler。

Handler是实际执行实现命令的类。它通过使用并行扩展在多线程环境中执行此操作，而不会阻塞主服务器循环。有一个简单的run方法，它创建一个闭包，必须执行任务并将响应返回给Manticore Search，然后该响应将被代理给用户。

在我们的情况下，我们只需要添加对支持SHOW HOSTNAME查询语法的检查，然后编写Handler逻辑以调用gethostname PHP函数并将其作为响应返回。就是这样！让我们从Payload开始。

实现Payload

当您打开src/Payload.php时，您会看到只有两个方法：fromRequest和hasMatch。我们用TODO注释标记了需要编辑的行，因此很容易找到需要执行的操作。在我们的情况下，查询非常简单且完全不灵活，因此我们不需要在fromRequest方法中进行任何更改。我们可以直接删除TODO注释。我们需要做的是更新静态函数hasMatch()。在那里，我们需要实现一个检查，以确保查询严格匹配字符串SHOW HOSTNAME（不区分大小写）。一旦匹配成功，我们应该返回true。否则，返回false。这就是基础系统理解在接收到显示主机名的查询时需要使用此插件的方式。

我们对Payload所做的最终差异应如下所示：

diff --git a/src/Payload.php b/src/Payload.php
index a35f201..bd0795e 100644
--- a/src/Payload.php
+++ b/src/Payload.php
@@ -26,7 +26,6 @@ final class Payload extends BasePayload {
   */
  public static function fromRequest(Request $request): static {
    $self = new static();
-   // TODO: add logic of parsing request into payload here
    // We just need to do something, but actually its' just for PHPstan
    $self->path = $request->path;
    return $self;
@@ -37,7 +36,6 @@ final class Payload extends BasePayload {
   * @return bool
   */
  public static function hasMatch(Request $request): bool {
-   // TODO: validate $request->payload and return true, if your plugin should handle it
-   return $request->payload === 'template';
+   return stripos($request->payload, 'show hostname') !== false;
  }
 }

我们完成了Payload的更改，可以继续到Handler中实现真正的逻辑。

实现Handler

现在，让我们打开src/Handler.php并查看TODO标记，以及简要描述正在发生的事情。我们需要导航到run方法并更新它。

我们可以看到一个返回TaskResult的闭包，这是一种特殊的结果类型，用于包装标准的JSON响应。

我们将包含一个gethostname()调用，并通过将其包装在将返回给客户端的TaskResult中来准备响应。最终差异将如下所示：

diff --git a/src/Handler.php b/src/Handler.php
index 07fcfd0..944899b 100644
--- a/src/Handler.php
+++ b/src/Handler.php
@@ -11,6 +11,7 @@
 namespace Manticoresearch\Buddy\Plugin\ShowHostname;

 use Manticoresearch\Buddy\Core\Plugin\BaseHandler;
+use Manticoresearch\Buddy\Core\Task\Column;
 use Manticoresearch\Buddy\Core\Task\Task;
 use Manticoresearch\Buddy\Core\Task\TaskResult;
 use RuntimeException;
@@ -33,9 +34,11 @@ final class Handler extends BaseHandler {
   * @throws RuntimeException
   */
  public function run(): Task {
-   // TODO: your logic goes into closure and should return TaskResult as response
    $taskFn = static function (): TaskResult {
-     return TaskResult::none();
+     $hostname = gethostname();
+     return TaskResult::withRow([
+       'hostname' => $hostname,
+     ])->column('hostname', Column::String);
    };

    return Task::create(

调试和开发

现在您已经完成了实现，是时候测试和调试（如果需要）您的插件了。有一种专门用于此目的的插件类型称为local。由于您的插件已经在plugins目录中，它会自动成为local插件。要使用它，只需：

在Buddy的根目录中，运行命令composer require [your-plugin-name]:dev-main以包含插件。your-plugin-name是您之前编辑的插件的composer.json中的名称。
重新启动searchd以确保代码已更新。

此方法允许您在不将插件推送到Git仓库并在 packagist.org 上发布的情况下，实时开发、调试、编辑和测试您的插件。

发布和安装

当你完成调试并准备好发布插件时，只需将更改提交到Git仓库，并在 packagist.org 上发布你的包。

之后，通过运行CREATE PLUGIN [your-plugin-name] TYPE 'buddy' VERSION 'dev-main'命令检查它是否按预期工作，这将尝试使用Composer下载插件并将其安装到plugin_dir。

像这样：

$ docker exec -it manticore-buddy mysql -h0 -P9306
MySQL [(none)]> CREATE PLUGIN manticoresoftware/buddy-plugin-show-hostname type 'buddy' VERSION 'dev-main';

Query OK, 0 rows affected (1 min 12.213 sec)

MySQL [(none)]> show hostname;
+----------+
| hostname |
+----------+
| dev      |
+----------+
1 row in set (0.011 sec)

MySQL [(none)]>

恭喜！您的插件运行良好，并且可以通过SHOW hostname查询来获取主机名。

结论

希望您喜欢这篇文章，并加深了对Manticore 6.0.4版本以来新增的Buddy可插拔架构的理解。您可以按照我们提供的说明立即开始开发自己的插件。虽然这是对可插拔系统的初步介绍，但我们计划创建并发布一篇关于开发复杂插件的更高级文章。不要犹豫在我们的 Slack 或 Telegram 聊天中向我们提问，并随时建议复杂插件教程的主题。

请记住，查看Buddy的 built-in plugin code 是一个好主意，以更深入地了解其在更复杂场景中的工作原理。

此致，
Manticore 团队。