Plugin Configuration

YedMQ's plugin system is process-based. The broker discovers plugin directories, starts child processes, and communicates with them over a local socket.

Broker-side settings

[plugin]
dir = "./plugins"
local_socket_path = "/tmp/yedmq_plugin.sock"
default_authorize_result = false
default_authenticate_result = false

Configuration Item	Description
dir	Root directory scanned for plugin subdirectories. Each plugin must live in its own first-level directory.
local_socket_path	Local IPC address used between the broker and plugin host. On Windows you can use a named-pipe style path or let YedMQ derive one from the configured value.
default_authorize_result	Fallback authorization result when no plugin answers the request.
default_authenticate_result	Fallback authentication result when no plugin answers the request.

The shipped example keeps both fallback values set to false. With the current broker behavior, that means MQTT clients are rejected until you install an authentication or ACL plugin, or temporarily opt into a local-only development fallback.

Directory layout

plugins/
  my-plugin/
    plugin.toml
    my-plugin

The directory name should match plugin.name in practice, because the current loader resolves the runtime executable relative to that plugin directory.

Bundled example plugin

The main repository includes a file-based ACL example plugin in example_plugins/acl_file.

• On Unix-like systems, make build-all stages the debug broker binary and the bundled acl_file plugin under target/debug/
• make build-all-release does the same for target/release/
• The staged plugin manifest passes --acl-file ./acl.json to the example plugin process

Plugin manifest

[plugin]
name = "my-plugin"
version = "0.1.0"
description = "Example YedMQ plugin"
author = "Your Name"
license = "Apache-2.0"

[runtime]
type = "process"
executable = "my-plugin"
working_dir = "."
timeout_secs = 12

Runtime notes

• Only process runtime is supported today.
• The executable path is resolved relative to the plugin directory.
• Plugins connect back to the host over the configured local socket.
• The current runtime uses built-in request and heartbeat timeouts, so timeout_secs should be treated as descriptive metadata rather than a complete runtime policy switch.

Current integration model

Plugins declare hooks during initialization, and YedMQ orders them by priority. The current broker-side integration focuses on:

• authentication
• authorization
• message publish policy handling through OnMessagePublish
• subscription policy handling through OnMessageSubscribe
• disconnect, message lifecycle, subscription lifecycle, and related event-style flows

For protocol details and hook definitions, continue with the Plugin Developer Guide.

Policy hooks

OnMessagePublish

YedMQ calls OnMessagePublish after publish authorization succeeds and before retained-message storage, QoS state persistence, and message routing.

A plugin can:

• allow the publish unchanged
• reject the publish
• rewrite the topic, payload, retain flag, or dup flag
• continue or stop the hook chain

When multiple plugins handle this hook, YedMQ passes the modified message from one plugin to the next plugin in priority order. If a plugin rejects the publish, the broker accepts the MQTT packet at the protocol level but does not retain, persist, or route the message.

Inbound MQTT QoS and packet identifiers remain controlled by the original client packet so PUBACK/PUBREC handling stays consistent with the MQTT session.

OnMessageSubscribe

YedMQ calls OnMessageSubscribe after topic validation and authorization and before subscription storage and retained-message delivery.

A plugin can:

• allow a topic filter
• reject a topic filter
• downgrade the granted QoS

Rejected topic filters receive the MQTT 5 NotAuthorized reason code. Granted QoS is capped to the requested QoS and to the MQTT maximum of QoS 2. Retained-message delivery uses the final granted QoS.

Event hooks

Event-style hooks are notifications after broker actions have happened. They are useful for audit logs, external indexing, and integration workflows, but they are not the place to deny or rewrite a request.

Current event-style integrations include message published, client disconnected, subscription added, and subscription removed flows. Some hook names already exist in the protocol for future expansion, but broker-side request policy currently centers on Authenticate, Authorize, OnMessagePublish, and OnMessageSubscribe.