README.md

Reliable MQTT clients for Rust

Rumqttc-next provides asynchronous and synchronous MQTT clients with a small, explicit API and close control over connection behavior. It supports MQTT 3.1.1 and MQTT 5, TLS, WebSockets, proxies, tracking notice API, persistent sessions, manual acknowledgements, request and network-read batching, graceful disconnect, and reconnect handling.

This repository is an actively maintained fork of rumqttc, started in response to a period of upstream inactivity. It preserves the original project's focus on simplicity and performance while continuing protocol hardening, operational tooling, and API development independently.

See the migration and API differences guide for a practical comparison with upstream, and the changelog for the complete list of additions and fixes. Highlights include:

• separate, intentionally versioned MQTT 3.1.1 and MQTT 5 clients;
• client operations can be tracked to their actual protocol outcome;
• manual and customizable acknowledgements;
• stricter packet and protocol-state validation, backed by spec-compliance references;
• persistent session APIs, structured diagnostics, lifecycle tracing, and explicit reconnect, acknowledgement, and topic-alias policies;
• Configurable request and network-read batching, which can substantially improve throughput under sustained load;
• HTTP and SOCKS5 proxies, TLS backends, and WebSocket transports, and opt-in Linux Multipath TCP;
• updated dependencies to address vulnerabilities reported in RUSTSEC advisories.

Choose a client

Use case	Cargo package	Rust crate
MQTT 5 (recommended entry point)	rumqttc-next	rumqttc
MQTT 5 (explicit package)	rumqttc-v5-next	rumqttc
MQTT 3.1.1	rumqttc-v4-next	rumqttc

The *-next names are the packages published on crates.io; each library target is still named rumqttc, so application imports remain familiar.

cargo add rumqttc-next@0.34.0-alpha

use rumqttc::{AsyncClient, MqttOptions};

let options = MqttOptions::new("client-id", "localhost");
let (client, mut eventloop) = AsyncClient::builder(options).capacity(10).build();

Use rumqttc-v4-next in the command above for MQTT 3.1.1. For complete setup and usage, see the rumqttc-next, rumqttc-v5-next, and rumqttc-v4-next crate documentation.

Using both MQTT versions

The explicit v4 and v5 packages both expose a library target named rumqttc. When one crate depends on both packages, give each dependency a distinct name in Cargo.toml:

[dependencies]
rumqttc_v4 = { package = "rumqttc-v4-next", version = "0.34.0-alpha" }
rumqttc_v5 = { package = "rumqttc-v5-next", version = "0.34.0-alpha" }

The dependency names become the paths used by Rust code:

use rumqttc_v4::{AsyncClient as V4Client, MqttOptions as V4Options};
use rumqttc_v5::{AsyncClient as V5Client, MqttOptions as V5Options};

Without distinct dependency names, both library targets would claim the rumqttc extern-crate name in the same target.

Shared transport and codec code is published as rumqttc-core-next and mqttbytes-core-next. Optional file-backed session stores live in the independent session-store-file workspace and do not add filesystem dependencies to the clients. Its protocol-neutral storage engine is maintained separately as atomic-blob-store.

Guides and ecosystem

The production recipes cover TLS, WebSockets, proxies, Notice API, persistent sessions, reconnect handling, bounded channels, manual ACKs, broker-specific configuration, and others.

Projects integrating this fork include mqtt-typed-client, a type-safe MQTT layer with an optional backend-rumqttc-next backend. See each package's crates.io page for current download and reverse-dependency data.

License

Licensed under the Apache License, Version 2.0.