symqtt 0.1.1

Synchronous MQTT 3.1.1/5.0 client — blocking API, no async runtime
Documentation

symqtt

Blocking MQTT 3.1.1 / 5.0 client. No async runtime.

TCP/TLS live in symqtt-transport. Packet codec is symqtt-codec.

Why this crate

Most Rust MQTT clients sit on Tokio or C bindings. This crate is for sync apps, CLIs, and anything that should not pull an async runtime.

  • Blocking I/O on the caller thread
  • Client is Send + Sync (not Clone; uniquely owns one connection)
  • 2–3 OS threads per connection
  • Depends on bytes, log, smallvec, thiserror, and symqtt-codec

If you already run Tokio, use rumqttc.

Thread model

  • Caller thread(s): encode and write. Concurrent calls are serialized by an internal mutex.
  • Read thread: decode inbound packets, complete ACK tokens, invoke InboundHandler.
  • Keepalive thread: PINGREQ when idle; drop the connection if PINGRESP times out.

Features

  • MQTT 3.1.1 and 5.0
  • QoS 0 / 1 / 2
  • Session state that survives reconnect (inflight retransmission)
  • MQTT 5.0: topic alias, enhanced auth, reason codes, server properties
  • Last Will and Testament
  • Pluggable Transport

Quick start

[dependencies]
symqtt = "0.1"
symqtt-transport = "0.1"
bytes = "1"
use std::time::Duration;
use bytes::Bytes;
use symqtt::v3::{Client, ConnectOptions, InboundHandler, Publish, PublishMessage, QoS, Session};
use symqtt_transport::tcp::TcpTransport;

struct Handler;

impl InboundHandler for Handler {
    fn on_publish(&self, msg: &Publish) {
        println!("topic={} payload={:?}", msg.topic, msg.payload);
    }
}

fn main() {
    let opts = ConnectOptions {
        client_id: "my-client".to_string(),
        clean_session: true,
        keep_alive: Duration::from_secs(30),
        will: None,
        username: None,
        password: None,
        connect_timeout: Some(Duration::from_secs(5)),
        ping_timeout: None,
    };

    let session = Session::new();
    let transport = TcpTransport::builder("127.0.0.1:1883")
        .connect().expect("tcp connect failed");
    let client = Client::connect(opts, Handler, session, transport)
        .expect("mqtt connect failed");

    client.subscribe(&[("sensor/#", QoS::AtLeastOnce)], None).unwrap()
        .wait_timeout(Duration::from_secs(5)).unwrap();

    let msg = PublishMessage::new("sensor/temp", Bytes::from("25.3"))
        .qos(QoS::AtLeastOnce);
    if let Some(token) = client.publish(&msg).unwrap() {
        token.wait_timeout(Duration::from_secs(5)).unwrap();
    }

    client.disconnect(Some(Duration::from_secs(5)));
}

MQTT 5.0 uses SubscribeFilter, message properties, and a reason code on disconnect. v5 ACK tokens return Ok even when the broker rejects the request — check ReasonCode::is_success on the returned code(s). Examples: examples/v3/, examples/v5/.

Reconnect

Session outlives Client. Keep the same session across reconnects so QoS 1/2 inflight is retransmitted with DUP=1.

let session = Session::new();

loop {
    let transport = TcpTransport::builder("127.0.0.1:1883")
        .connect().expect("tcp connect failed");
    let client = Client::connect(opts.clone(), handler.clone(), session.clone(), transport)
        .expect("mqtt connect failed");
    // ...
    std::thread::sleep(Duration::from_secs(5));
}

Custom transport

pub trait Transport: Send + 'static {
    type Read: io::Read + Send + 'static;
    type Write: io::Write + WriteTimeout + Send + 'static;

    fn split(self) -> (Self::Read, Self::Write);
}

split() must yield independent halves. Ready-made TCP/TLS: symqtt-transport.

Logging

Uses the log crate. No output unless you install a backend.

RUST_LOG=symqtt=debug cargo run

License

Licensed under Apache License, Version 2.0.