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 straightworward 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.
Add mqttrs = "0.2"
and bytes = "0.5"
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.2", 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.
Use mqttrs = { version = "0.2", 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.