mashafrancis / mqttrs

Async Mqtt encoder and decoder for rust.

Rust Mqtt Encoding & Decoding

Mqttrs is a Rust crate (library) to write MQTT protocol clients and servers.

It is a codec-only library with very few dependencies and a straightforward and composable API, usable with rust's standard library or with async frameworks like tokio. It is strict when decoding (e.g. returns an error when encountering reserved values) and encoding (the API makes it impossible to generate an illegal packet).

Mqttrs currently requires Rust >= 1.39 and supports MQTT 3.1.1. Support for MQTT 5 is planned for a future version.

Usage

Add mqttrs = "0.4" and bytes = "1.0" to your Cargo.toml.

use mqttrs::*;
use bytes::BytesMut;

// Allocate write buffer.
let mut buf = BytesMut::with_capacity(1024);

// Encode an MQTT Connect packet.
let pkt = Packet::Connect(Connect { protocol: Protocol::MQTT311,
                                    keep_alive: 30,
                                    client_id: "doc_client".into(),
                                    clean_session: true,
                                    last_will: None,
                                    username: None,
                                    password: None });
assert!(encode(&pkt, &mut buf).is_ok());
assert_eq!(&buf[14..], "doc_client".as_bytes());
let mut encoded = buf.clone();

// Decode one packet. The buffer will advance to the next packet.
assert_eq!(Ok(Some(pkt)), decode(&mut buf));

// Example decode failures.
let mut incomplete = encoded.split_to(10);
assert_eq!(Ok(None), decode(&mut incomplete));
let mut garbage = BytesMut::from(&[0u8,0,0,0] as &[u8]);
assert_eq!(Err(Error::InvalidHeader), decode(&mut garbage));

Optional serde support.

Use mqttrs = { version = "0.4", features = [ "derive" ] } in your Cargo.toml.

Enabling this features adds #[derive(Deserialize, Serialize)] to some mqttrs types. This simplifies storing those structs in a database or file, typically to implement session support (qos, subscriptions...).

This doesn't add mqtt as a serde data format; you still need to use the mqttrs::{decode,encode} functions.

Optional #[no_std] support.

Use mqttrs = { version = "0.4", default-features = false } in your Cargo.toml to remove the default std feature.

Disabling this feature comes with the cost of not implementing the std::error::Error trait, as well as not supporting std::io read and write. This allows usage in embedded devices where the standard library is not available.