Project Awesome project awesome
♥

Rust > mqtt5

Complete async MQTT v5.0 client and broker library for Rust with TCP, TLS, WebSocket, and QUIC support.

Package 46 stars GitHub

Complete MQTT Platform

Crates.io Documentation Rust CI License Ask DeepWiki

A production-ready MQTT v5.0 and v3.1.1 platform that ships a client library, a multi-transport broker, and a protocol crate for embedded systems — all from the same codebase. Whether you need a cloud-connected IoT client, a self-hosted broker with QUIC multistream, or a no_std packet parser for bare-metal firmware, this platform covers it.

Dual Architecture: Client + Broker

Component Use Case Key Features
MQTT Broker Run your own MQTT infrastructure TLS, WebSocket, QUIC, Authentication, Bridging, Monitoring
MQTT Client Connect to any MQTT broker Cloud compatible, QUIC multistream, Auto-reconnect, Mock testing
Protocol (no_std) Embedded IoT devices ARM Cortex-M, RISC-V, ESP32, bare-metal compatible

Installation

Library Crate

[dependencies]
mqtt5 = "0.31"

CLI Tool

cargo install mqttv5-cli

Crate Organization

The platform is organized into four crates:

  • mqtt5-protocol - Platform-agnostic MQTT v5.0 core (packets, types, Transport trait). Supports no_std for embedded targets.
  • mqtt5 - Native client and broker for Linux, macOS, Windows
  • mqtt5-wasm - WebAssembly client and broker for browsers
  • mqtt5-conformance - OASIS specification conformance test suite (183 automated tests, 247 normative statements)

Quick Start

Start an MQTT Broker

use mqtt5::broker::{BrokerConfig, MqttBroker};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut broker = MqttBroker::bind("0.0.0.0:1883").await?;

    println!("MQTT broker running on port 1883");

    broker.run().await?;
    Ok(())
}

Connect a Client

use mqtt5::{MqttClient, QoS};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = MqttClient::new("my-device-001");

    // Multiple transport options:
    client.connect("mqtt://localhost:1883").await?;        // TCP
    // client.connect("mqtts://localhost:8883").await?;    // TLS
    // client.connect("ws://localhost:8080/mqtt").await?;  // WebSocket
    // client.connect("quic://localhost:14567").await?;    // QUIC

    // Subscribe with callback
    client.subscribe("sensors/+/data", |msg| {
        println!("{}: {}", msg.topic, String::from_utf8_lossy(&msg.payload));
    }).await?;

    // Publish a message
    client.publish("sensors/temp/data", b"25.5°C").await?;

    tokio::time::sleep(tokio::time::Duration::from_secs(5)).await;
    Ok(())
}

Command Line Interface (mqttv5)

Single binary with pub, sub, broker, bench, passwd, acl, and scram commands. Supports interactive prompts, input validation, and all transport types.

cargo install mqttv5-cli

mqttv5 broker --host 0.0.0.0:1883
mqttv5 pub --topic "sensors/temperature" --message "23.5"
mqttv5 sub --topic "sensors/+" --verbose

See the CLI Crate Reference and CLI Usage Guide for the full command reference.

Features at a Glance

Broker

The broker supports multiple transports (TCP, TLS, WebSocket, QUIC) in a single binary, built-in authentication (password, SCRAM, JWT, federated JWT), resource monitoring, change-only delivery, load balancer mode, broker-to-broker bridging with loop prevention, event hooks, and OpenTelemetry distributed tracing.

See the mqtt5 Crate Reference for detailed broker capabilities and configuration examples.

Client

The client supports automatic reconnection with exponential backoff, cloud MQTT broker compatibility (AWS IoT, Azure IoT Hub), QUIC multistream with connection migration, mockable client interface for unit testing, and callback-based message handling.

See the mqtt5 Crate Reference for detailed client capabilities, AWS IoT examples, and mock testing patterns.

QUIC Transport

MQTT over QUIC provides built-in TLS 1.3, multistream support with configurable strategies (ControlOnly, DataPerPublish, DataPerTopic), connection migration for mobile clients, and flow headers for session state recovery.

See the QUIC Transport Guide for stream strategies, configuration, and migration usage.

WASM Browser Support

WebAssembly builds for browser environments with three deployment modes: external broker (WebSocket), in-tab broker (MessagePort), and cross-tab communication (BroadcastChannel).

See the mqtt5-wasm Crate Reference and WASM Usage Guide for API reference and framework integration.

Embedded Support (no_std)

The mqtt5-protocol crate supports no_std environments for embedded systems including ARM Cortex-M, RISC-V, and ESP32 targets with configurable time provider for hardware timers.

See the mqtt5-protocol Crate Reference for embedded usage and time provider setup.

Authentication & Security

Four authentication methods (Password, SCRAM-SHA-256, JWT, Federated JWT), role-based access control with topic-level permissions, composite auth provider chaining, session-to-user binding, and comprehensive transport security.

See the Authentication & Authorization Guide for configuration details and security hardening.

Conformance Testing

The conformance test suite validates any MQTT v5.0 broker against the OASIS specification. Create a TOML descriptor for your broker and run the CLI runner:

cargo build --release -p mqtt5-conformance-cli
./target/release/mqtt5-conformance --sut your-broker.toml --report report.json

See the Conformance Test Suite for test organization and architecture, and the CLI Reference for the full SUT descriptor schema and report format.

Publications

  • Evaluating Stream Mapping Strategies for MQTT over QUIC — Computer Networks (Elsevier), 2026. Defines three stream mapping strategies (control-only, per-topic, per-publish) and evaluates them across five experiments on GCP infrastructure. Experiment data archived at Zenodo. See the paper directory on GitHub for the paper, experiment scripts, and reproduction guide.

License

This project is licensed under either of

at your option.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Documentation

Back to MQTT