blog-post

Manticore Buddy: pluggable design v2

नमस्ते दोस्तों। Manticore Buddy के बारे में रोमांचक समाचार: हमने प्लगएबल डिज़ाइन में माइग्रेशन पूरा कर लिया है! इसका मतलब है कि आप एक प्लगइन के रूप में अपना खुद का Manticore Search SQL/JSON क्वेरी बना सकते हैं, उसे packagist.org पर प्रकाशित कर सकते हैं, और CREATE PLUGIN SQL कमांड का उपयोग करके उसे स्थापित कर सकते हैं। चलिए प्लगएबल सिस्टम की आर्किटेक्चर और एक सरल ट्यूटोरियल में गोता लगाते हैं जो आपको शुरुआत करने में मदद करेगा।

आर्किटेक्चर

परिचय

यदि आप 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 Request to Response Flow

ट्यूटोरियल

आपके लिए चीज़ों को आसान बनाने और अपना खुद का प्लगइन विकसित करने के लिए, आइए हम एक सरल प्लगइन बनाने पर विचार करें जो Buddy के लिए SHOW HOSTNAME कमांड का समर्थन करता है और वर्तमान होस्ट मशीन का होस्टनेम लौटाता है। यह आपको समझने में मदद करेगा कि जब आप अपना खुद का प्लगइन बनाएंगे तो आपको कौन-सी प्रक्रिया का पालन करना चाहिए, और यह एक शानदार सरल उदाहरण भी है। यदि हम Manticore Search में SHOW HOSTNAME कैसे कार्य करता है, इसकी कार्यप्रणाली का अध्ययन करें, तो हम परिणाम की उम्मीद कर सकते हैं जैसे:

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

तैयारी

हमें सबसे पहले हमारी विकास पर्यावरण को तैयार करना चाहिए। आपको इसे केवल एक बार करना है और बाद में आप Buddy को GIT repository से अपडेट कर सकते हैं ताकि नवीनतम अपडेट प्राप्त कर सकें। चलिए टर्मिनल खोलते हैं और 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 के साथ Buddy और प्लगइनों का विकास करने के लिए एक Docker कंटेनर शुरू किया है। आप वर्तमान में जिस कार्यशील निर्देशिका में हैं, वह कंटेनर के अंदर /workdir में मैप की गई है। आपका अगला कदम Composer निर्भरताएँ स्थापित करना है। याद रखें, यह और सभी आगे के कमांड manticore-buddy कंटेनर के अंदर निष्पादित किए जाने चाहिए।

docker exec -it manticore-buddy bash
composer install

आपका Buddy अब उपयोग, विकास, डिबगिंग, और परीक्षण के लिए तैयार है। अगला, आपको दो चीजें पूरी करनी हैं:

  1. पहले, कंटेनर के अंदर /etc/manticoresearch/manticore.conf संपादित करें और वहां buddy_path को हमारे स्रोतों के साथ जोड़ें। यह Manticore Search को बताने में मदद करेगा कि हमें स्रोतों से Buddy को चलाने के कस्टम पथ का उपयोग करना है, स्थापित मॉड्यूल से नहीं। इसे searchd अनुभाग में जोड़ें:
    buddy_path = manticore-executor /workdir/src/main.php --debug
  2. दूसरे, searchd (Manticore Search सर्वर) को चलाने का प्रयास करें और सुनिश्चित करें कि यह काम करता है।
    # कंटेनर के अंदर डेमन लॉन्च करें और इसेForeground में रखें
searchd --nodetach
    आपको [BUDDY] से शुरू होने वाली कुछ पंक्तियाँ दिखाई देनी चाहिए।

At this point, everything is set for preparing your development environment for Buddy and beginning the implementation of a new plugin. You can still experiment with it and attempt to execute some queries to ensure it’s functioning properly. For instance, open another terminal window and run the following:

$ 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)]>

You’ve just sent the command SHOW QUERIES to Manticore Search, which was then routed to Buddy and executed successfully. You can see what Buddy received and its response in the searchd log in the first terminal tab. So, we can confirm that Buddy is functioning correctly and everything has been set up right.

When you want to stop the searchd process, simply press Ctrl + C in the first terminal window/tab.

Plugin Template

We’ve created a special GitHub template repository that we highly recommend using to create any Manticore Buddy plugin. All plugins should be prefixed with buddy-plugin-[your-name], where [your-name] is the name of your plugin. For example, since we’re developing a hostname selection plugin, we’ll name it buddy-plugin-show-hostname. So:

  1. Open https://github.com/manticoresoftware/buddy-plugin-template .
  2. Click Use this template and then Create a new repository.
  3. Fill out the form with your repository’s name and create it. Make sure your repo name starts with buddy-plugin- as it’s mandatory.
  4. git clone your new repo to the plugins directory of the Manticore Buddy repo you previously deployed. Note that it’s better to do this outside the container, especially if you’re cloning from a private repository.

In https://github.com/manticoresoftware/buddy-plugin-show-hostname , you can find the entire task implemented. If you don’t want to delve into the details, you can simply git clone that instead of your forked repo. However, if you do want to master creating a plugin, let’s continue.

Add real code

Now we need to follow the next steps and update our template with the related data to our new plugin.

  1. First, open composer.json in your cloned plugin’s directory and update the plugin’s name, description, and namespaces. So finally, your changes should look like this (ensure you use your plugin’s repository name):
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": [
  1. We also need to update the namespaces of two classes in your plugin – Payload and Handler. The diff should look like this:
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;
  1. As a final step, do not forget to install the new dependency by running composer install inside the container (in /workdir).

The request flow from Manticore Search to your plugin and back

We are ready to implement our logic now. But first, let’s learn a little bit more about how it’s handled internally.

Manticore Buddy Request to Plugin Flow

Let’s assume we’re sending a SHOW HOSTNAME query to the launched searchd process using a MySQL client. Manticore Search can’t handle it and sends it to Buddy to await a response. Buddy can return the exact response, which will simply be proxied back to the MySQL client.

Once Buddy receives the query from Manticore Search, it parses it and runs validation across all plugins: first core plugins, and then external plugins. To run this validation, it executes the Payload::hasMatch($request) method, passing the request to it, which contains the query and some metadata, such as the requested endpoint, type (JSON or SQL), and so on.

Payload कमांड को संभालने के लिए सभी आवश्यक डेटा को शामिल करने वाली संरचना का प्रतिनिधित्व करता है। यदि एक प्लगइन का Payload hasMatch विधि में सत्य लौटाता है, तो इसका मतलब है कि हम इस प्लगइन का उपयोग अनुरोध को संभालने के लिए करेंगे। इसे Request से बनाया गया है, और इस चरण में, हमें क्वेरी को पार्स करना, मूल्यवान जानकारी को निकालना और उसे हमारे पेलोड डेटा में सेट करना होगा, जिसे Handler को पास किया जाएगा।

Handler वह वर्ग है जो वास्तव में कार्यान्वित कमांड को निष्पादित करता है। यह मुख्य सर्वर लूप को अवरुद्ध किए बिना समांतर विस्तार का उपयोग करके धागे (थ्रेडेड) वातावरण में ऐसा करता है। एक सरल विधि run है जो एक क्लोजर बनाती है, जिसे एक कार्य करना चाहिए और उत्तर को Manticore Search को वापस लौटाना चाहिए, जिसे फिर उपयोगकर्ता को प्रॉक्सी किया जाएगा।

हमारे मामले में, हमें केवल SHOW HOSTNAME क्वेरी सिंटैक्स का समर्थन करने के लिए एक जांच जोड़ने की आवश्यकता है और फिर gethostname PHP फ़ंक्शन को कॉल करने और इसे उत्तर के रूप में लौटाने के लिए Handler तर्क लिखना है। बस इतना ही! आइए Payload के साथ शुरू करें।

Payload लागू करना

जब आप src/Payload.php खोलते हैं, तो आप देखेंगे कि यहां केवल दो विधियाँ हैं: fromRequest और hasMatch। हमने उन पंक्तियों को चिह्नित किया है जिनमें हमें संपादित करने की आवश्यकता है TODO टिप्पणियों के साथ, इसलिए हमें यह पता लगाने में आसान होना चाहिए कि हमें क्या करना है। हमारे मामले में, क्वेरी बहुत सरल और बिल्कुल भी लचीली नहीं है, इसलिए हमें fromRequest विधि में कुछ भी बदलने की आवश्यकता नहीं है। हम बस TODO टिप्पणियों को हटा सकते हैं। हमें जो करने की आवश्यकता है वह स्थिर फ़ंक्शन hasMatch() को अपडेट करना है। वहां हमें यह सुनिश्चित करने के लिए एक जांच लागू करने की आवश्यकता है कि क्वेरी कड़ाई से SHOW HOSTNAME स्ट्रिंग से मेल खाती है, एक केस-ईंसेंसटिव तरीके से। एक बार जब यह मेल खाता है, तो हमें सत्य लौटाना चाहिए। अन्यथा, हमें असत्य लौटाना चाहिए। ऐसा ही बेस सिस्टम समझता है कि उसे इस प्लगइन का उपयोग करना चाहिए यदि हमें क्वेरी मिलती है जो होस्टनेम प्रदर्शित करती है।

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 प्लगइन बन जाता है। इसका उपयोग करने के लिए, बस:

  1. रूट बडी निर्देशिका में, composer require [your-plugin-name]:dev-main कमांड चलाएं ताकि प्लगइन शामिल हो सके। your-plugin-name वह नाम है जो आप अपने प्लगइन के composer.json में पहले संपादित करेंगे।
  2. सुनिश्चित करें कि कोड अपडेटेड है, इसके लिए 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 क्वेरी का उपयोग करके होस्टनेम लाने की अनुमति देता है।

निष्कर्ष

हम आशा करते हैं कि आपको यह लेख पसंद आया और मंटिकोर संस्करण 6.0.4 से उपलब्ध नए बडी प्लगिन योग्य वास्तुकला के बारे में गहरी समझ मिली। आप हमारे द्वारा दी गई निर्देशों का पालन करके अपने प्लगइन को तुरंत विकसित करना शुरू कर सकते हैं। जबकि यह प्लगइन प्रणाली का एक बुनियादी परिचय है, हम एक जटिल प्लगइन के विकास पर एक अधिक उन्नत लेख बनाने और प्रकाशित करने की योजना बना रहे हैं। हमारे Slack या Telegram चैट में हमसे सवाल पूछने में संकोच न करें, और जटिल प्लगइन ट्यूटोरियल के लिए विषय सुझाने में स्वतंत्र महसूस करें।

याद रखें, बडी के बिल्ट-इन प्लगइन कोड को देखना एक अच्छा विचार है ताकि अधिक जटिल परिदृश्यों में इसके काम करने की गहरी समझ प्राप्त की जा सके।

ईमानदारी से आपका,
मंटिकोर टीम।

Read also

मैंटीकोर सर्च इंस्टॉल करें

मैंटीकोर सर्च इंस्टॉल करें

© 2017-2025 Manticore Software Ltd. नियम एवं शर्तें गोपनीयता नीति