3 unstable releases
0.2.0 | Mar 19, 2023 |
---|---|
0.1.1 | Jan 2, 2023 |
0.1.0 | Jan 2, 2023 |
#25 in #mqtt-client
29 downloads per month
330KB
4.5K
SLoC
LMC - A Lightweight MQTT Client for Rust
LMC is a MQTT client implementation designed to be small (the "active" code fits in less than 1k lines, including documentation), minimize memory allocations, use as few crates as possible, and be asynchronous (through tokio). The project is under the MIT license or the apache license, whichever you prefer.
There are a few existing MQTT client crates out there but most of them are wrappers for a C/C++ library, and those which are pure Rust have a basics APIs that don't allow you to, for instance, await the server's response when subscribing to a topic. This crate gives you fine control over all of its aspects, but also provides no-headaches, easy-to-use functions if all you need is an MQTT client with no concerns for performance.
Example use
First, add the crate to your dependencies in Cargo.toml
:
[dependencies.lmc]
version = "^0.2"
features = ["tls"] # See below for available features
Then, you can use the following code to get started. Note that this example assumes the following:
- Your broker is hosted on your local machine
- Your broker uses TLS on port 8883
- Your broker's certificate was signed by one of the Certificate Authorities in your system's CA store
- You can log-in using the username
username
and passwordpassword
- You can subscribe and publish to the
my_topic
topic
use lmc::{Options, Client, QoS};
#[tokio::main]
async fn main()
{
//You can disable TLS by skipping `.enable_tls().unwrap()`
let mut opts = Options::new("client_id").enable_tls().unwrap();
opts.set_username("username").set_password(b"password");
//Connect to localhost using the default TLS port (8883)
let (client, shutdown_handle) = Client::connect("localhost", opts).await.unwrap();
//Subscribe to 'my_topic' using an unbounded Tokio MPSC channel
let (subscription, sub_qos) = client.subscribe_unbounded("my_topic", QoS::AtLeastOnce).await.unwrap();
println!("Subscribed to topic with QoS {:?}", sub_qos);
client.publish_qos_1("my_topic", b"it works!", false, true).await.unwrap();
let msg = subscription.recv().await.expect("Failed to await message");
println!("Received {}", msg.payload_as_utf8().unwrap());
shutdown_handle.disconnect().await.expect("Could not disconnect gracefully");
}
Feature list
The following features can be enabled/disabled:
fxhash
(default) To use faster hash maps thanks to the fxhash crateparking_lot
(default) To use faster, non-failing mutexes thanks to the parking_lot cratetls
(non-default) for TLS supportdangerous_tls
(non-default) to allow dangerous TLS functions, such as the one that enables you to bypass server certificate verification
Philosophy
- Less dependencies: Avoid using crates, unless it can improve performances. Make dependencies optional through features as often as possible.
- Unsafe code: Use unsafe code to improve performances, provided the unsafe code can be proven to be safe trivially.
Missing features
For now, the following features are not available in LMC. They may be implemented later as required:
- Websocket transport
- Multiple subscriptions using a single call/packet
Dependencies
~3–14MB
~186K SLoC