Website 🌐 | Documentation 📚

---

YedMQ

YedMQ is a high-performance, distributed MQTT broker written in Rust, specifically designed for modern IoT infrastructure. It is built for scalability, security, and extreme efficiency.

⚠️ This project is still under development and is not yet suitable for production use.

✨ Key Features

• MQTT v3.1.1 and MQTT 5.0 Support: MQTT v3.1.1 remains supported, and MQTT 5.0 clients can use normal CONNECT, publish/subscribe, QoS 0/1/2, retained messages, persistent sessions, session expiry, message expiry, shared subscriptions, TCP, TLS, WS, and WSS flows.
• High Performance: Leveraging Rust's memory safety and zero-cost abstractions for low latency and high throughput.
• Multiple Tenant Support: Built-in isolation for multiple organizations. Each tenant has its own namespace, sessions, and topics, ensuring data privacy and security.
• Clustering & High Availability: Distributed architecture based on the Raft consensus algorithm for reliable state synchronization and fault tolerance.
• Powerful Plugin System: Extend the broker with out-of-process plugins managed by the built-in plugin host. Plugins are started as child processes and communicate with YedMQ over the local plugin protocol, making them language-agnostic and crash-isolated.
• Security First:
  • Transport Layer Security via TLS/SSL.
  • Secure WebSocket (WSS) support.
  • Fine-grained access control (ACL) via plugins.
• RESTful Management API: A comprehensive set of APIs for managing clients, monitoring metrics, and controlling cluster state.
• Cross-Platform: Native support for X86_64 and AARCH64 (ARM) architectures.

🚀 Quick Start

Prerequisites

• Rust (1.75 or later)
• Protocol Buffers compiler (protoc)
• OpenSSL development headers (libssl-dev on Ubuntu/Debian)
• Make (optional, Unix-like convenience only)

On Ubuntu/Debian, you can install the common system dependencies with:

sudo apt-get update
sudo apt-get install -y protobuf-compiler pkg-config libssl-dev

On Windows, install these build dependencies before running cargo build:

• protoc
• LLVM/Clang

Some native dependencies in this workspace rely on Clang being discoverable during the build. In PowerShell, a typical setup looks like:

$env:LIBCLANG_PATH = "C:\Program Files\LLVM\bin"
$env:PATH = "$env:LIBCLANG_PATH;$env:PATH"

If your protoc.exe directory is not already on PATH, add it as well before building.

Installation

From Source

git clone https://github.com/designershao/YedMQ.git
cd YedMQ
cargo build --release -p yedmq

Using Docker

docker pull yedmq/yedmq:latest

The published image ships with the locked-down example configuration from this repository. Mount your own yedmq.toml into /opt/yedmq/yedmq.toml when you want to enable client access or expose the management API.

Running YedMQ

1. Copy the example configuration:

   cp yedmq.toml.example yedmq.toml

   Windows PowerShell:

   Copy-Item yedmq.toml.example yedmq.toml

2. Edit the configuration before first start:

   vim yedmq.toml

   The example file is intentionally locked down:

   • Client access is deny-by-default unless an auth plugin approves the request or you opt into the local fallback below
   • The management API binds to 127.0.0.1
   • No management API users are created automatically

   For a local smoke test without any auth plugin, temporarily change this block:

   [plugin]
   default_authorize_result = true
   default_authenticate_result = true

   Do not use that fallback in shared or production environments.

   If you need the management API, also add at least one user under [listener.api.auth].

3. Start the broker:

   RUST_LOG=info ./target/release/yedmq start -c yedmq.toml

   Running ./target/release/yedmq without a subcommand is still supported and starts the broker with the default configuration search path.

   Windows PowerShell:

   $env:RUST_LOG = "info"
   .\target\release\yedmq.exe start -c yedmq.toml

   Docker:

   docker run --rm \
     -p 1883:1883 \
     -v "$(pwd)/yedmq.toml:/opt/yedmq/yedmq.toml:ro" \
     yedmq/yedmq:latest

4. Test the connection after enabling the local development fallback above or installing an auth plugin:

   # Using mosquitto_pub/sub
   mosquitto_sub -h localhost -t test/topic
   mosquitto_pub -h localhost -t test/topic -m "Hello YedMQ"

Authentication And First Run

YedMQ currently has two separate authentication surfaces:

• [listener.api.auth].users protects the REST management API only.
• MQTT client login and topic authorization are evaluated through the plugin hook chain.

That means adding a REST API user does not create a MQTT username/password login.

For the current broker behavior, the effective MQTT fallback on first run is controlled by:

[plugin]
default_authenticate_result = false
default_authorize_result = false

With the shipped defaults, if you start YedMQ without any authentication or ACL plugin, MQTT clients will be rejected. This is expected and is meant to prevent accidentally exposing an open broker.

For an initial local evaluation, pick one of these approaches:

1. Install an authentication/ACL plugin and let the plugin decide who can connect.
2. On a local machine only, temporarily set:

[plugin]
default_authenticate_result = true
default_authorize_result = true

Use the second option only for local smoke tests. For any shared, staged, or production deployment, keep the defaults locked down and use a real authentication plugin.

MQTT Protocol Support

YedMQ supports MQTT v3.1.1 and a conservative MQTT 5.0 surface. The MQTT 5.0 implementation covers the common broker path: CONNECT/CONNACK, PUBLISH, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBSCRIBE/SUBACK, UNSUBSCRIBE/UNSUBACK, PING, DISCONNECT, QoS 0/1/2, retained messages, session expiry, message expiry, shared subscriptions, mixed v3/v5 delivery, REST-published messages, $SYS topics, and TCP/TLS/WS/WSS listeners.

The first MQTT 5.0 release explicitly rejects unsupported features with MQTT 5 reason codes where possible. Enhanced authentication, Topic Alias, Subscription Identifier, and protocol-version-specific metric breakdowns are not implemented yet.

CLI Operations

The yedmq binary also provides basic operational commands:

./target/release/yedmq version
./target/release/yedmq config check -c yedmq.toml

Status commands call the REST management API, which listens on 127.0.0.1:3456 by default and requires a user under [listener.api.auth].users.

export YEDMQ_API_USER=admin
export YEDMQ_API_PASSWORD=replace_me

./target/release/yedmq node status
./target/release/yedmq cluster status
./target/release/yedmq broker stats --output json

For scripts that should avoid putting the password in process arguments:

printf '%s' 'replace_me' | \
  ./target/release/yedmq cluster status --user admin --password-stdin

📖 Documentation

For detailed guides, please visit our Official Documentation:

• Getting Started
• Configuration Guide
• Cluster Setup
• Plugin Development
• REST API Reference
• Observability

🏗️ Architecture

YedMQ is designed with an actor-based concurrency model (via Actix) to handle millions of concurrent connections efficiently. Its distributed state is managed by a robust implementation of the Raft consensus protocol, ensuring consistency across the cluster.

┌─────────────────────────────────────────────────────────┐
│                    MQTT Clients                         │
└────────────┬────────────────────────────┬───────────────┘
             │                            │
    ┌────────▼────────┐          ┌───────▼────────┐
    │  YedMQ Node 1   │◄────────►│  YedMQ Node 2  │
    │  (Raft Leader)  │   Raft   │  (Follower)    │
    └────────┬────────┘          └───────┬────────┘
             │                            │
             └────────────┬───────────────┘
                          │
                  ┌───────▼────────┐
                  │  YedMQ Node 3  │
                  │  (Follower)    │
                  └────────────────┘

🔌 Plugin System

YedMQ uses a process-based plugin system. Each plugin lives in its own directory, is described by a plugin.toml manifest, and is launched by the broker as a separate process. The broker and plugin communicate through a local socket-based IPC channel, which keeps plugin crashes isolated from the broker process.

# Example plugin layout
plugins/
└── my-plugin/
    ├── plugin.toml
    └── my-plugin-binary

Example plugin.toml:

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

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

Typical flow:

1. Build your plugin as an executable.
2. Place the executable and plugin.toml in a subdirectory under the configured plugin directory.
3. Start YedMQ and let the plugin host discover, launch, and health-check the plugin.

See the Plugin Configuration and Plugin Development Guide for details.

✅ Release Gate

Before publishing a release candidate or validating a risky cluster change, run the documented release gate from the repository root:

./scripts/run_release_gate.sh

For extended cluster smoke validation, run it with:

RUN_CLUSTER_SMOKE=1 ./scripts/run_release_gate.sh

See Release Gate for the fast check set, the optional cluster smoke harness, and how to interpret environmental failures.

📈 Observability

$SYS/broker/* topics and GET /metrics are node-local. Scrape every broker node and aggregate cluster-wide views outside YedMQ with labels such as cluster and node_id.

See Observability for the $SYS payload format, the OpenMetrics endpoint, and the recommended aggregation model.

🤝 Contributing

Bug reports, feature requests, documentation fixes, and pull requests are welcome. For larger changes, open a GitHub issue or discussion first so the scope is clear before implementation.

📊 Roadmap

• MQTT v3.1.1 support
• MQTT v5.0 support
• Raft-based clustering
• Plugin system
• Shared subscriptions
• Message persistence (disk-based)
• Prometheus metrics
• WebUI dashboard

See the full Roadmap for details.

📄 License

YedMQ is released under the Apache-2.0 License.

🙏 Acknowledgments

YedMQ is built with excellent open-source projects:

• Actix - Actor framework
• OpenRaft - Raft consensus
• Tokio - Async runtime
• RocksDB - Persistent storage

📞 Contact

• Website: www.yedmq.com
• GitHub Issues: github.com/designershao/YedMQ/issues

---

Made with ❤️ by the YedMQ Team