Quick Start

Prerequisites

Before starting plugin development, you need to install the RUST development environment on your operating system. You can find more details by visiting the RUST official website.

After installing the RUST development environment, run the following command to install cargo-generate, which allows you to quickly generate a foundational project for plugin development:

cargo install cargo-generate

Develop

Quick Project Creation

You can quickly create the entire plugin framework using the following command:

cargo generate --git https://github.com/designershao/YedMQ-Plugin-Template.git

⚠️ Favorite `YedMQ_Plugin_Template` not found in config, using it as a local path: YedMQ_Plugin_Template  
🤷 Project Name: example-plugin  
🔧 Destination: /home/yedmq/example-plugin ...  
🔧 project-name: example-plugin ...  
🔧 Generating template ...  
🤷 Your plugin name?: example-plugin  
🤷 Description for the crate?: just an example  
7:1 | "plugin_name: ExamplePlugin"  
🔧 Moving generated files into: `/home/yedmq/example-plugin`...  
🔧 Initializing a fresh Git repository  
✨ Done! New project created /home/yedmq/example-plugin

The structure of the generated plugin folder will be as follows:

.
├── Cargo.lock  
├── Cargo.toml  
├── plugin.toml  
├── README.md  
└── src  
     └── lib.rs

• plugin.toml: Metadata file describing the YedMQ plugin.
• lib.rs: File for the plugin implementation.

Sample plugin.toml:

[plugin]
name = "example-plugin"
author = "shaoyan"
description = "just an example"
version = "0.0.1"
entry = "./libexample_plugin.so"
priority = 1000

Key	Description
name	Plugin name
author	Author information
description	Plugin description
version	Plugin version
entry	Path to the plugin's dynamic library
priority	Plugin priority; plugins with higher priority are executed first

When you open lib.rs with an editor, you will see the corresponding basic framework implementation:

use anyhow::Result;

use yedmq_plugin::{plugin::{AuthenticationResult, AuthenticationResultValue, AuthorizationResult}, register_plugin};

pub struct ExamplePlugin {}

impl ExamplePlugin {
    pub fn new(_context: yedmq_plugin::context::Context) -> Result<ExamplePlugin, anyhow::Error> {
        Ok(
            ExamplePlugin {}
        )
    }
}

impl yedmq_plugin::plugin::Plugin for ExamplePlugin {

    fn on_activate(&mut self) -> Result<()> {
        println!("example plugin on_activate example-plugin");
        Ok(())
    }

    fn on_deactivate(&self) -> Result<()> {
        println!("example plugin on_deactivate");
        Ok(())
    }

    fn connect_authenticate(&self, _packet: &yedmq_mqtt::v3::connect::ConnectPacket) -> Result<AuthenticationResult> {
        return Ok(AuthenticationResult::Result(AuthenticationResultValue::Success("tenant_id".into())));
    }

    fn authorizate_acl_check(&self, _client: &yedmq_plugin::plugin::Client, _topic: &String, _action: yedmq_plugin::plugin::Action) -> Result<AuthorizationResult> {
        return Ok(AuthorizationResult::Result(true));
    }

    fn on_publish(&self, client: &yedmq_plugin::plugin::Client, packet: &yedmq_mqtt::v3::publish::PublishPacket) {
        println!("client {} receive publish packet {:?}", client.client_identifier, packet)
    }
    
    fn on_disconnect(&self, client: &yedmq_plugin::plugin::Client) {

        println!("client {} disconnect", client.client_identifier)

    }

}

impl Drop for ExamplePlugin {

    fn drop(&mut self) {
        println!("example plugin drop");
    }

}
register_plugin!(ExamplePlugin, ExamplePlugin::new);

The core part is implementing the yedmq_plugin::plugin::Plugin trait. Below is an explanation of the relevant trait functions:

Function	Description
on_activate	Executes when the plugin is loaded and initialized.
on_deactivate	Executes when the plugin is unloaded.
connect_authenticate	Executes when the client connects to the broker and requires authentication.
authorizate_acl_check	Executes when the client publishes or subscribes to a specific topic.
on_publish	Executes when the client publishes a message.
on_disconnect	Executes when the client disconnects.

To compile:

cargo build

In the YedMQ plugin directory, create a new plugin folder and copy the plugin metadata and dynamic library into it. The file structure should look like this:

.  
├── libexample_plugin.so  
└── plugin.toml