PML 2 Plugin Development Guide

Plugin Event Triggers

This document describes every trigger available in the PML 2 plugin system.

1. Plugin Event Triggers

Plugins subscribe to the events below through triggers.on in YAML. The data carried by an event can be referenced in action parameters through the template {{ctx.data.fieldName}}.

Event overview

Event	Fired when	Fired from	Payload	Execution
`app.startup`	The main window has initialised and the application starts	`MainWindow.axaml.cs`	`version`, `os`	await
`app.exit`	The application exits (before logs are released)	`App.axaml.cs`	`version`, `os`	await
`app.update.available`	A new version is detected	`MainWindow.axaml.cs`	`currentVersion`, `latestVersion`	fire-and-forget
`user.login`	A user signs in successfully	`LoginPage.axaml.cs`	`username`, `group`	fire-and-forget
`user.logout`	After the user confirms sign-out, before the app restarts	`UserCenterPage.axaml.cs`	`username`	await
`proxy.start`	A tunnel starts (a terminal tab running the mefrpc command is created)	`TerminalPage.axaml.cs`	`proxyName`, `command`	fire-and-forget
`proxy.stop`	A terminal tab is closed (paired with `proxy.start`)	`TerminalPage.axaml.cs`	`proxyName`	fire-and-forget
`page.navigate`	The main page changes	`MainPageFrameViewModel.cs`	`page`	fire-and-forget
`plugin.install`	A plugin file is installed successfully	`PluginService.cs`	`file`	fire-and-forget
`plugin.uninstall`	A plugin is uninstalled successfully	`PluginService.cs`	`pluginId`, `pluginName`	fire-and-forget
`plugin.enable`	A plugin is enabled	`PluginService.cs`	`pluginId`	fire-and-forget
`plugin.disable`	A plugin is disabled	`PluginService.cs`	`pluginId`	fire-and-forget

Application lifecycle events. app.startup fires after the main window has loaded and the privacy policy check has completed; app.exit fires before the process exits and waits for plugin actions to finish before releasing log resources.

Field	Description	Example
`version`	Application version	`26.2.0`
`os`	Operating system platform	`Win32NT` / `Unix`

app.update.available

Fired the first time a new version is detected after startup (only once per run).

Field	Description
`currentVersion`	The current version
`latestVersion`	The newest version detected

user.login / user.logout

Field	Description
`username`	The user name that signed in/out
`group`	The user group (only for `user.login`)

The application restarts immediately after user.logout, so it is dispatched with await to make sure plugin actions (such as notifications and reporting) complete.

proxy.start / proxy.stop

Field	Description
`proxyName`	Tunnel / terminal tab name
`command`	The launch command (only for `proxy.start`)

page.navigate

Values of the page field: Home, CreateProxy, ManageProxy, NodesMonitoring, UserCenter, Settings, About, Terminal, Update, Theme, Plugin

plugin.install / plugin.uninstall / plugin.enable / plugin.disable

Plugin self-management events. Note that plugins may subscribe to these events to build chains, but a plugin that subscribes to plugin.uninstall will not receive any further events once it has been uninstalled.

2. Writing a Plugin YAML

Plugin files live in Config/Plugins/*.yaml and support hot reload (a changed file is reloaded automatically within 1 second).

id: my-plugin
name: Example Plugin
description: Sends a notification when a tunnel starts
author: Your Name
version: "1.0"

triggers:
  - on: proxy.start                          # Event name to subscribe to
    condition: "ctx.data.proxyName != ''"    # Optional, a condition expression
    actions:
      - name: notify
        params:
          msg: "Tunnel {{ctx.data.proxyName}} has started"

functions:
  my_func:                                   # A reusable function, invoked with call_function
    - name: log
      params:
        msg: "hello"

Built-in actions

Action	Parameters	Description
`log`	`msg`	Writes a log entry (console + application log file, module "Plugin")
`notify`	`msg`	Sends a system notification (titled `pluginId \| PML 2`)
`http_request`	`url`, `method` (default GET), `body`	Performs an HTTP request; the response body is stored in `ctx.variables.http_response`
`python_run`	`script`, `input`	Runs a Python script (requires `python3` on PATH); the returned JSON is merged into the variables
`call_function`	`func`, `args`	Calls a function defined under `functions`
`conditional`	`condition`, `if_true`	Runs a group of actions conditionally

Template variables

{{...}} inside parameters is replaced before execution:

{{ctx.data.xxx}} —— data carried by the event
{{ctx.variables.xxx}} —— variables produced during execution (such as http_response)

Edit this pageorReport an issue

Plugin Development Overview

A brief introduction to the PML 2 plugin system.

Plugin Operators

This document describes the operators available in the PML 2 plugin system.