Crate mqrstt 

A pure rust MQTT client which is easy to use, efficient and provides both sync and async options.

Because this crate aims to be runtime agnostic the user is required to provide their own data stream. For an async approach the stream has to implement the AsyncRead and AsyncWrite traits. That is ::tokio::io::AsyncRead and ::tokio::io::AsyncWrite for tokio and ::smol::io::AsyncRead and ::smol::io::AsyncWrite for smol.

Features:

• MQTT v5
• Runtime agnostic (Smol, Tokio)
• Sync
• TLS/TCP
• Lean
• Keep alive depends on actual communication
• This tokio implemention has been fuzzed using cargo-fuzz!

To do:

• Even More testing
• Add TLS examples to repository

Minimum Supported Rust Version (MSRV):

From 0.3 the tokio and smol variants will require MSRV: 1.75 due to async fn in trait feature.

Notes:

• Your handler should not wait too long
• Create a new connection when an error or disconnect is encountered
• Handlers only get incoming packets

Smol example:

use mqrstt::{example_handlers::NOP, NetworkBuilder, NetworkStatus};

smol::block_on(async {
    // Construct a no op handler
    let mut nop = NOP {};

    // In normal operations you would want to loop this connection
    // To reconnect after a disconnect or error
    let (mut network, client) = NetworkBuilder::new_from_client_id("mqrsttSmolExample").smol_network();
    let stream = smol::net::TcpStream::connect(("broker.emqx.io", 1883)).await.unwrap();
    network.connect(stream, &mut nop).await.unwrap();

    // This subscribe is only processed when we run the network
    client.subscribe("mqrstt").await.unwrap();

    let (result, _) = futures::join!(network.run(&mut nop), async {
        smol::Timer::after(std::time::Duration::from_secs(30)).await;
        client.disconnect().await.unwrap();
    });
    assert!(result.is_ok());
    assert_eq!(result.unwrap(), NetworkStatus::OutgoingDisconnect);
});

Tokio example:

use mqrstt::{
    example_handlers::NOP,
    NetworkBuilder, NetworkStatus,
};

use tokio::time::Duration;

#[tokio::main]
async fn main() {
    let (mut network, client) = NetworkBuilder::new_from_client_id("TokioTcpPingPongExample").tokio_network();
    // Construct a no op handler
    let mut nop = NOP {};
    // In normal operations you would want to loop this connection
    // To reconnect after a disconnect or error
    let stream = tokio::net::TcpStream::connect(("broker.emqx.io", 1883)).await.unwrap();
    network.connect(stream, &mut nop).await.unwrap();

    client.subscribe("mqrstt").await.unwrap();
    // Run the network
    let network_handle = tokio::spawn(async move { network.run(&mut nop).await });

    tokio::time::sleep(Duration::from_secs(30)).await;
    client.disconnect().await.unwrap();
    let result = network_handle.await;
    assert!(result.is_ok());
    assert_eq!(result.unwrap().unwrap(), NetworkStatus::OutgoingDisconnect);
}

Modules

error

Error types that the user can see during operation of the client.

example_handlers

packets

All MQTT packets are defined here

smol

Contains the reader writer parts for the smol runtime.

tokio

Contains the reader and writer parts for the tokio runtime.

Macros

reason_code_match_write

Structs

ConnectOptions

Options for the connection to the MQTT broker

MqttClient

A Clonable client that can be used to send MQTT messages.

NetworkBuilder

Enums

NetworkStatus

NetworkStatus Represents status of the Network object. It is returned when the run handle returns from performing an operation.

Traits

AsyncEventHandler

Handlers are used to deal with packets before they are acknowledged to the broker. This guarantees that the end user has handlded the packet. Additionally, handlers only deal with incoming packets.

EventHandler