A Rust interface to the Mosquitto MQTT broker client

Mosquitto is a popular MQTT broker implemented in C. Although there are pure Rust MQTT clients, it is still useful to have a binding to the Mosquitto client.

The basic story is that you connect to a broker, subscribing to topics that interest you and publishing messages on a particular topic. The messages may be any arbitrary bytes, but this implementation does require that the topics themselves be UTF-8. The C API is based on callbacks, which are mapped onto Rust closures.

The Mosquitto client is thread-safe, so you can publish from one thread and listen for the messages on another. This example demonstrates mosquitto-client usage:

extern crate mosquitto_client as mosq;
use mosq::Mosquitto;
use std::{thread, time};

fn main() {
    let m = Mosquitto::new("test");

    m.connect("localhost",1883).expect("can't connect");
    m.subscribe("bilbo/#",1).expect("can't subscribe to bonzo");

    let mt = m.clone();
    thread::spawn(move || {
        let timeout = time::Duration::from_millis(500);
        for _ in 0..5 {
            mt.publish("bilbo/baggins","hello dolly".as_bytes(), 1, false).unwrap();
            thread::sleep(timeout);
        }
        mt.disconnect().unwrap();
    });

    let mut mc = m.callbacks(0);
    mc.on_message(|data,msg| {
        println!("bilbo {:?}",msg);
        *data += 1;
    });

    m.loop_until_disconnect(200).expect("broken loop");
    println!("received {} messages",mc.data);
}

The Mosquitto struct is a thin wrapper around the C pointer we get from the client. It is Clone + Send + Sync, so we can pass it to a thread which simply publishes some bytes and waits; at the end of the thread we explicitly disconnect.

The Callbacks handler struct is separate, to avoid antagonizing the borrow checker. It is created by the callbacks method and is generic over some data (accessed as the data field) Whenever an event occurs, the callback will be passed a mutable reference to that data, and event-specific data - in this case a message struct.

loop_until_disconnect is a relative of loop_forever which ends without error if we explicitly disconnect from the broker.

Prerequisites

On Debian/Ubuntu systems, will require the client libmosquitto1 to be installed (the dev package is not needed). (On RPM-based systems, it will just be libmosquitto).

You will also need the broker mosquitto package for testing.

For MacOS, Mosquitto is available through brew:

brew install mosquitto