Crate rumqttc 

rumqttc-v5-next

rumqttc-v5-next is the explicit MQTT 5 client crate in the rumqtt family. The rumqttc-next package is a facade that re-exports this crate unchanged.

This crate keeps the library target name as rumqttc so application code can stay familiar after migrating package names.

Installation

Use the facade package when you want the default MQTT 5 client:

cargo add rumqttc-next

Use this package directly when you want the protocol-scoped crate name:

cargo add rumqttc-v5-next

Examples

A simple synchronous publish and subscribe

use rumqttc::{MqttOptions, Client, QoS};
use std::time::Duration;
use std::thread;

let mut mqttoptions = MqttOptions::new("rumqtt-sync", "test.mosquitto.org");
mqttoptions.set_keep_alive(5);

let (mut client, mut connection) = Client::new(mqttoptions, 10);
client.subscribe("hello/rumqtt", QoS::AtMostOnce).unwrap();
thread::spawn(move || for i in 0..10 {
   client.publish("hello/rumqtt", QoS::AtLeastOnce, false, vec![i; i as usize]).unwrap();
   thread::sleep(Duration::from_millis(100));
});

// Iterate to poll the eventloop for connection progress
for (i, notification) in connection.iter().enumerate() {
    println!("Notification = {:?}", notification);
}

A simple asynchronous publish and subscribe

use rumqttc::{MqttOptions, AsyncClient, QoS};
use tokio::{task, time};
use std::time::Duration;

#[tokio::main(flavor = "current_thread")]
async fn main() {
let mut mqttoptions = MqttOptions::new("rumqtt-async", "test.mosquitto.org");
mqttoptions.set_keep_alive(5);

let (mut client, mut eventloop) = AsyncClient::new(mqttoptions, 10);
client.subscribe("hello/rumqtt", QoS::AtMostOnce).await.unwrap();

task::spawn(async move {
    for i in 0..10 {
        client.publish("hello/rumqtt", QoS::AtLeastOnce, false, vec![i; i as usize]).await.unwrap();
        time::sleep(Duration::from_millis(100)).await;
    }
});

while let Ok(notification) = eventloop.poll().await {
    println!("Received = {:?}", notification);
}
}

Quick overview of features

• Eventloop orchestrates outgoing/incoming packets concurrently and handles the state
• Pings the broker when necessary and detects client side half open connections as well
• Throttling of outgoing packets (todo)
• Queue size based flow control on outgoing packets
• Automatic reconnections by just continuing the eventloop.poll()/connection.iter() loop
• Natural backpressure to client APIs during bad network
• Support for WebSockets
• Secure transport using TLS
• Unix domain sockets on Unix targets
• MQTT 5 properties, reason codes, session controls, and topic aliases
• Optional SCRAM-based enhanced authentication support via auth-scram

In short, everything necessary to maintain a robust connection

Since the eventloop is externally polled (with iter()/poll() in a loop) out side the library and Eventloop is accessible, users can

• Distribute incoming messages based on topics
• Stop it when required
• Access internal state for use cases like graceful shutdown or to modify options before reconnection

Important notes

• Looping on connection.iter()/eventloop.poll() is necessary to run the event loop and make progress. It yields incoming and outgoing activity notifications which allows customization as you see fit.

• Blocking inside the connection.iter()/eventloop.poll() loop will block connection progress.

• Use client.disconnect()/try_disconnect() for MQTT-level graceful shutdown (sends DISCONNECT). Dropping all client handles ends polling with ConnectionError::RequestsDone and closes locally without sending DISCONNECT.

• This crate is MQTT 5-specific. If you need MQTT 3.1.1 instead, use rumqttc-v4-next.

• On Unix targets, local broker sockets are supported via MqttOptions::new(..., Broker::unix(...)). When the url feature is enabled, MqttOptions::parse_url("unix:///tmp/mqtt.sock?client_id=...") is also supported.

TLS Support

rumqttc supports two TLS backends:

• use-rustls (default): Uses rustls with aws-lc as the crypto provider and native platform certificates
• use-native-tls: Uses the platform’s native TLS implementation (Secure Transport on macOS, SChannel on Windows, OpenSSL on Linux)

TLS Feature Flags

Feature	Description
use-rustls	Enable rustls with aws-lc provider (recommended default)
use-rustls-no-provider	Enable rustls without selecting a crypto provider
use-rustls-aws-lc	Enable rustls with aws-lc provider
use-rustls-ring	Enable rustls with ring provider
use-native-tls	Enable native-tls backend

use-rustls-aws-lc and use-rustls-ring are mutually exclusive. Enabling both results in a compile error.

Important: Using Both TLS Features

When both use-rustls-no-provider and use-native-tls features are enabled:

• Configure TLS explicitly with MqttOptions::set_transport(Transport::tls_with_config(...))
• Configure secure websockets explicitly with Broker::websocket("ws://...") plus MqttOptions::set_transport(Transport::wss_with_config(...))

Secure websocket connections upgrade the TCP stream using the selected TlsConfiguration before the websocket handshake, so backend selection follows the provided TLS configuration.

In dual-backend dependency graphs, avoid relying on TlsConfiguration::default(), because default backend selection must be explicit. Use TlsConfiguration::default_rustls() or TlsConfiguration::default_native() (when available) or pass an explicit configuration to Transport::tls_with_config(...) / Transport::wss_with_config(...).

Native-tls WSS can use platform roots via TlsConfiguration::default_native() or a custom CA / identity via TlsConfiguration::simple_native(...).

Re-exports

pub use tokio_native_tls;use-native-tls

pub use tokio_rustls;use-rustls-no-provider

pub use mqttbytes::v5::*;

pub use mqttbytes::*;

Modules

mqttbytes

Structs

AsyncClient

An asynchronous client, communicates with MQTT EventLoop.

Broker

Broker target used to construct MqttOptions.

Client

A synchronous client, communicates with MQTT EventLoop.

Connection

MQTT connection. Maintains all the necessary state

EventLoop

Eventloop with all the state of a connection

InvalidTopic

An error returned when a topic string fails validation against the MQTT specification.

Iter

Iterator which polls the EventLoop for connection progress

MqttOptions

Options to configure the behaviour of MQTT connection

MqttState

State of the mqtt connection.

NetworkOptions

Provides a way to configure low level network connection configurations

Proxyproxy

PublishNotice

Wait handle returned by tracked publish APIs.

RecvError

Error type returned by Connection::recv

RequestNotice

Wait handle returned by tracked subscribe/unsubscribe APIs.

ValidatedTopic

A newtype wrapper that guarantees its inner String is a valid MQTT topic.

Enums

ClientError

Client Error

ConnectionError

Critical errors during eventloop polling

Event

Events which can be yielded by the event loop

IncomingPacketSizeLimit

Controls how incoming packet size limits are enforced locally.

ManualAck

Prepared acknowledgement packet for manual acknowledgement mode.

NoticeFailureReason

OptionError

Outgoing

Current outgoing activity on the eventloop

ProxyAuthproxy

ProxyTypeproxy

PublishNoticeError

PublishTopic

Topic argument accepted by publish APIs.

RecvTimeoutError

Error type returned by Connection::recv_timeout

Request

Requests by the client to mqtt event loop. Request are handled one by one.

RequestNoticeError

StateError

Errors during state handling

TlsConfigurationuse-rustls-no-provider or use-native-tls

TLS configuration method

TlsErroruse-rustls-no-provider or use-native-tls

Transport

Transport methods. Defaults to TCP.

TryRecvError

Error type returned by Connection::try_recv

Traits

AuthManager

Functions

default_socket_connect

Default TCP socket connection logic used by the MQTT event loop.

Type Aliases

Incoming