Skip to main content

Crate mqtt_glide

Crate mqtt_glide 

Source
Expand description

MQTT 5 Tokio client.

Application-facing types live at the crate root; the wire codec (packet types, framing, encode helpers) is internal. Connection options, error types, credential/reconnect hooks, and the connect entry point define the public application contract. For a higher-level connect path with defaults, see ClientBuilder. Session I/O is driven by Connection::run, backed by the internal connection read/write loops.

§TLS crypto provider

TLS uses rustls. Enable at least one Cargo feature:

  • tls-rustls-aws-lc (default) — rustls + aws-lc-rs
  • tls-rustls-ring — rustls + ring

With both enabled (another crate in the build left the default on, or --all-features), ring is used: it is only ever enabled on purpose. The client builds its ClientConfig with that provider explicitly (builder_with_provider), so MQTT TLS does not depend on a process-global rustls default. To build without aws-lc-rs, use mqtt-glide = { ..., default-features = false, features = ["tls-rustls-ring"] }.

§Other features

  • websocket: ws:// / wss:// broker URLs (MQTT over WebSocket).
  • testing: the in-process testing::TestBroker and testing::FaultProxy for tests of applications; meant for [dev-dependencies].
  • stats: MqttClient::stats returns counters of what the connection did.
  • flume: InboundSink for flume::Sender<InboundMessage>; ties your build to flume 0.12.
  • async-channel: InboundSink for async_channel::Sender<InboundMessage>; ties your build to async-channel 2.

§Stability

Everything documented here follows Semantic Versioning. Features whose names start with __ (__internals, __bench) are not: they exist for the crate’s own tests, benches and fuzz target, and what they expose can change or disappear in any release.

Crate overview: see the repository README. Spec coverage: CONFORMANCE.md in the repository.

Re-exports§

pub use client::AnonymousCredentials;
pub use client::ClientBuilder;
pub use client::CredentialsProvider;
pub use client::MqttClient;
pub use client::NoReconnect;
pub use client::Password;
pub use client::Publish;
pub use client::PublishBuilder;
pub use client::PublishCompletion;
pub use client::PublishWindow;
pub use client::ReconnectPolicy;
pub use client::StaticCredentials;
pub use client::Subscription;
pub use client::connect;

Modules§

builder
Ergonomic ClientBuilder over the connect_with_shared driver entry.
shared_filter
Shared-subscription topic helper ($share/{group}/{topic}).
testing
Test helpers for applications built on this client (testing feature).

Structs§

AnonymousCredentials
CONNECT without username or password (anonymous session).
BrokerUrl
Parsed MQTT broker endpoint (host, port, TLS requirement, WebSocket path).
ClientId
Unique MQTT client identifier sent in CONNECT.
ClientStats
A snapshot of what a client’s connection has done since connect, across reconnects.
ConnectOptions
Broker endpoint and session parameters for crate::connect.
Connection
I/O driver: connect, read/write tasks, reconnect until shutdown.
ConnectionStats
Connection counters of a ClientStats.
HttpProxy
An HTTP proxy the broker connection goes through, via CONNECT host:port (RFC 9110 §9.3.6), for networks that only let traffic out through one.
InboundMessage
An inbound application message as delivered to the InboundSink.
InboundSinkClosed
The publish-sink consumer is gone; further pushes fail.
InboundStats
Inbound counters of a ClientStats.
MqttClient
Cloneable command handle — sends application commands over a bounded channel.
NoReconnect
Never reconnects — a single connect attempt then stop.
NoopLifecycle
No-op LifecycleHook when the caller only observes SessionPhase.
OnInboundSink
Inline inbound handoff: runs handler on the connection read task (no app queue).
OutboundStats
Outbound counters of a ClientStats.
Password
A password, for CONNECT or an HTTP proxy.
Properties
The PublishProperties of a message, allocated only when it has some.
Publish
One outbound PUBLISH: topic, payload, QoS, retain flag and MQTT 5 properties.
PublishBuilder
Fluent PUBLISH returned by MqttClient::publish.
PublishCompletion
Completion handle for an outbound PUBLISH started by MqttClient::try_start_publish.
PublishError
A publish that did not complete: the cause plus whether the broker can have it.
PublishMessage
Application PUBLISH message: topic, payload, and transferable v5 properties.
PublishProperties
Transferable MQTT v5 PUBLISH properties (no Topic Alias, no Subscription Identifiers).
PublishRejection
A QoS 1 PUBLISH the broker refused (PUBACK reason code 0x80 or higher), carried by AppError::PublishRejected.
PublishResponse
What the broker answered to a publish that completed: the PUBACK of a QoS 1 publish (MQTT 5 §3.4.2), or nothing for QoS 0, which has no acknowledgement.
PublishWindow
Bounded in-flight window over MqttClient::start_publish.
RefusedSubscription
A subscription the broker refused to restore after a reconnect, as listed by MqttClient::refused_subscriptions.
RequestBuilder
One request, returned by Requester::request. Awaiting it publishes the request and resolves with the response.
Requester
Sends requests and awaits their responses on one response topic. Cheap to clone and safe to use from many tasks at once.
SessionParams
Session parameters captured from a successful CONNACK.
StandardReconnectPolicy
Fixed reconnect delay, one immediate transport retry after a live session, and capped auth backoff.
StaticCredentials
Fixed username/password credentials that never invalidate.
SubscribeResponse
Result of MqttClient::subscribe: the SUBACK.
Subscription
One topic filter + options for MqttClient::subscribe.
SubscriptionOptions
Per-filter Subscription Options byte (§3.8.3.1).
TlsConfig
How the client authenticates the broker over TLS, and how it authenticates itself.
UnknownCode
A byte that is not a defined value of the code type it was converted to: crate::QoS, crate::RetainHandling or one of the reason code enums.
UnsubscribeResponse
Result of MqttClient::unsubscribe: the UNSUBACK.
UserProperty
One MQTT User Property (§2.2.2.2 / UTF-8 String Pair §1.5.7).
WillMessage
Will Message fields carried in CONNECT (§3.1.2.5, §3.1.3.2–§3.1.3.4).

Enums§

AppError
Application-level failure (inbound sink closed, command channel closed).
AuthError
Authentication failure (CONNACK NotAuthorized, credentials provider or authenticator error, etc.).
BrokerUrlError
Errors returned when a broker URL cannot be parsed.
ClientIdError
Invalid Client Identifier for CONNECT ([MQTT-1.5.4], [MQTT-3.1.3]).
ConnectAckReason
CONNACK reason codes (§3.2.2.2). Unlisted wire values decode as Unknown.
ConnectError
Error returned by crate::connect when the initial session cannot be established.
ConnectionOutcome
Outcome of a connection attempt or session end, fed to crate::ReconnectPolicy.
Delivery
Whether a failed publish can have reached the broker, carried by PublishError.
DisconnectReasonCode
DISCONNECT Reason Codes (§3.14.2.1).
InboundTrySendError
Failure of a non-blocking InboundSink::try_send.
ProtocolError
MQTT protocol violation or unexpected control packet.
PublishAckReason
PUBACK / PUBREC Reason Codes (§3.4.2.1 / §3.5.2.1).
QoS
Quality of Service (§4.3).
RetainHandling
Retain Handling values in the Subscription Options byte (§3.8.3.1).
SessionPhase
Current session phase — single type for the connect-time tokio::sync::watch channel and for LifecycleHook callbacks.
ShareNameError
ShareName validation failure ([MQTT-4.8.2-1], [MQTT-4.8.2-2]).
ShutdownError
Graceful or requested shutdown.
SubscribeAckReason
SUBACK Reason Codes (§3.9.3).
TlsConfigError
Why certificate, key or TLS settings handed to TlsConfig are unusable.
TransportError
Transport-level failure (TCP, TLS, DNS), or the broker refusing or ending the connection.
UnsubscribeAckReason
UNSUBACK Reason Codes (§3.11.3).

Constants§

COMMAND_CHANNEL_CAPACITY
Default capacity of the bounded application command/data path to the write task.
DEFAULT_ACK_TIMEOUT
Default deadline waiting for PUBACK / SUBACK / UNSUBACK after the matching request.
DEFAULT_AUTH_FAILURE_THRESHOLD
Consecutive auth failures before switching to the max auth backoff delay.
DEFAULT_CONNECT_TIMEOUT
Default budget for TCP dial + optional TLS + CONNACK (ConnectOptions::connect_timeout).
DEFAULT_GRACEFUL_DISCONNECT_TIMEOUT
Default budget for PUBACK + DISCONNECT flush during graceful shutdown.
DEFAULT_MAX_AUTH_BACKOFF
Long delay of StandardReconnectPolicy::default, after repeated auth failures and after a session takeover.
DEFAULT_MAX_PACKET_SIZE
Default Maximum Packet Size (1 MiB) the client advertises in CONNECT and enforces on inbound packets; see ConnectOptions::max_packet_size.
DEFAULT_RECEIVE_MAXIMUM
Default inbound QoS-1 pipelining window (ConnectOptions::receive_maximum).
DEFAULT_RECONNECT_DELAY
Reconnect delay of StandardReconnectPolicy::default.
DEFAULT_REQUEST_TIMEOUT
How long RequestBuilder waits for the response unless RequestBuilder::timeout says otherwise.

Traits§

AuthExchange
One exchange started by Authenticator::start; dropped when it ends.
Authenticator
Enhanced authentication (§4.12): SCRAM, Kerberos or a broker’s own scheme, run as a challenge / response exchange in AUTH packets.
CredentialsProvider
Supplies MQTT username and password for CONNECT.
InboundSink
Injectable sink for inbound InboundMessage delivery.
LifecycleHook
Synchronous side effects for lifecycle transitions.
ReconnectPolicy
Decides reconnect delay after a connection outcome.

Functions§

connect
Establishes an MQTT 5 session and returns a client handle, driver, and phase watch.
is_shared_subscription_filter
Returns true when filter is a shared-subscription topic filter ($share/...).
shared_filter
Builds an MQTT 5 shared-subscription filter string.
topic_matches
Whether topic matches the Topic Filter filter by the MQTT rules (§4.7).
validate_share_name
Validates a ShareName segment for shared_filter ([MQTT-4.8.2-1], [MQTT-4.8.2-2]).

Type Aliases§

UserProperties
List of User Properties on an MQTT v5 packet.