Crate finmqtt_tokio 

Session-oriented MQTT v5 client built on [tokio] and finmqtt-core.

Quick start

use finmqtt_tokio::transport::TcpTransport;
use finmqtt_tokio::{ClientOptions, MqttClient, QoS, Subscription};
use futures::StreamExt;

let transport = TcpTransport::new("broker.example.com", 1883);
let options = ClientOptions::new("my-client".parse()?).reconnect();

let (owner, client, mut messages) = MqttClient::builder(transport, options).start().await?;

// Subscribe: returns SUBACK reason codes.
let reason_codes = client
    .subscribe(Subscription::new("sensors/#".parse()?, QoS::AtLeastOnce))
    .send()
    .await?;

// Publish with v5 properties:
client
    .publish(
        "sensors/temp".parse()?,
        b"22.5".as_slice(),
        QoS::AtLeastOnce,
    )
    .message_expiry(60)
    .send()
    .await?;

// All messages arrive on the single message stream:
while let Some(msg) = messages.next().await {
    println!("{}: {:?}", msg.topic, msg.payload);
}

// The owner handle controls the session lifecycle.
owner.stop().await;

Feature flags

All features are disabled by default:

• tls: TLS transport via tokio-rustls (TlsTransport).
• turso: session persistence as queryable rows in a turso (SQLite-compatible) database (TursoPersistence).
• tracing: diagnostics via the tracing crate.

The tls and turso features expose types from tokio-rustls and turso, which have not reached 1.0 themselves. The API behind these features therefore tracks those crates’ versions and is exempt from this crate’s semver stability promise.

Re-exports

pub use self::builder::ClientBuilder;

pub use self::persistence::TursoPersistence;turso

pub use self::persistence::FilePersistence;

pub use self::persistence::SessionPersistence;

Modules

builder

Builder for configuring and connecting an MqttClient.

client 🔒

Session-oriented MQTT v5 client.

connection 🔒

Low-level single-connection driver.

dispatch 🔒

Shared dispatch machinery for the lazy publish, subscribe, and unsubscribe futures.

error

Error types for the MQTT tokio client.

handle 🔒

Owner handle for the connection event loop.

message 🔒

MQTT v5 message type with full property support.

options 🔒

Client options with MQTT v5 connect properties and reconnect configuration.

persistence

Session persistence: backend-agnostic configuration and runtime dispatch.

publish 🔒

status 🔒

Connection status monitoring.

subscribe 🔒

subscription 🔒

transport

Modular transport layer.

Structs

BackoffMultiplier

Exponential backoff multiplier, constrained to be finite and >= 1.0.

ClientOptions

Options for the MQTT v5 client.

ConnectionStateWatch

A handle for observing the connection status of an MqttClient.

ConnectionStatusStream

A stream of ConnectionStatus transitions.

EventLoopHandle

Owns the connection event loop and controls its lifecycle.

Jitter

Backoff jitter as a fraction of the delay, constrained to 0.0..=1.0.

Message

An incoming MQTT v5 message from the broker.

MessageStream

A stream of incoming MQTT messages.

MqttBytes

A byte slice that satisfies the MQTT v5 Binary Data length limit (at most 65 535 bytes).

MqttBytesBuf

Owned binary data that satisfies the MQTT v5 length limit.

MqttClient

A session-oriented MQTT v5 client.

MqttStr

A UTF-8 string that satisfies all MQTT v5 requirements:

MqttString

An owned UTF-8 string that satisfies all MQTT v5 requirements.

NonZeroVbi

Non-zero Variable Byte Integer.

PacketId

MQTT Packet Identifier (§2.2.1).

PublishBuilder

Builder for publishing a message with optional MQTT v5 properties.

PublishFuture

A pending publish operation.

PublishOptions

MQTT v5 properties to attach to an outgoing PUBLISH.

QueuedPublishFuture

Future returned by PublishFuture::queued.

QueuedSubscribeFuture

A lazy future that resolves as soon as the subscription is recorded locally.

QueuedUnsubscribeFuture

A lazy future that resolves as soon as the unsubscribe is recorded locally.

ReconnectOptions

Configuration for automatic reconnection with exponential backoff.

SubscribeBuilder

Builder for subscribing to one or more topic filters.

SubscribeFuture

A lazy future returned by SubscribeBuilder::send.

Subscription

A single topic filter with its associated subscription options.

Topic

A validated, borrowed MQTT topic name.

TopicBuf

An owned, validated MQTT topic name.

TopicFilter

A validated, borrowed MQTT topic filter.

TopicFilterBuf

An owned, validated MQTT topic filter.

UnsubscribeBuilder

Builder for unsubscribing from one or more topic filters.

UnsubscribeFuture

A lazy future returned by UnsubscribeBuilder::send.

WillOptions

Configuration for the MQTT will message (Last Will and Testament).

Enums

CleanStart

Whether to request a clean start on the initial connect (§3.1.2.4).

ConnectionStatus

The connection status of an MqttClient.

DisconnectCause

Why a connection went down, carried by Reconnecting. Deliberately coarse; the full error detail is available through tracing.

PayloadFormat

Payload format indicator (§3.3.2.3.2).

PublishProgress

Observable lifecycle of a publish operation.

QoS

Quality of Service level.

ReasonCode

All MQTT v5 reason codes.

RetainHandling

Retain handling option for SUBSCRIBE.

TopicError

Error returned when constructing a Topic, TopicFilter, or their owned counterparts.

Constants

DEFAULT_CONNECT_TIMEOUT

Default connect_timeout: 30 seconds.

DEFAULT_MAX_PACKET_SIZE

Default maximum_packet_size: 16 MiB.