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-rstls-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-processtesting::TestBrokerandtesting::FaultProxyfor tests of applications; meant for[dev-dependencies].stats:MqttClient::statsreturns counters of what the connection did.flume:InboundSinkforflume::Sender<InboundMessage>; ties your build to flume 0.12.async-channel:InboundSinkforasync_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
ClientBuilderover theconnect_with_shareddriver entry. - shared_
filter - Shared-subscription topic helper (
$share/{group}/{topic}). - testing
- Test helpers for applications built on this client (
testingfeature).
Structs§
- Anonymous
Credentials - CONNECT without username or password (anonymous session).
- Broker
Url - Parsed MQTT broker endpoint (host, port, TLS requirement, WebSocket path).
- Client
Id - Unique MQTT client identifier sent in CONNECT.
- Client
Stats - A snapshot of what a client’s connection has done since
connect, across reconnects. - Connect
Options - Broker endpoint and session parameters for
crate::connect. - Connection
- I/O driver: connect, read/write tasks, reconnect until shutdown.
- Connection
Stats - Connection counters of a
ClientStats. - Http
Proxy - 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. - Inbound
Message - An inbound application message as delivered to the
InboundSink. - Inbound
Sink Closed - The publish-sink consumer is gone; further pushes fail.
- Inbound
Stats - Inbound counters of a
ClientStats. - Mqtt
Client - Cloneable command handle — sends application commands over a bounded channel.
- NoReconnect
- Never reconnects — a single connect attempt then stop.
- Noop
Lifecycle - No-op
LifecycleHookwhen the caller only observesSessionPhase. - OnInbound
Sink - Inline inbound handoff: runs
handleron the connection read task (no app queue). - Outbound
Stats - Outbound counters of a
ClientStats. - Password
- A password, for CONNECT or an HTTP proxy.
- Properties
- The
PublishPropertiesof a message, allocated only when it has some. - Publish
- One outbound PUBLISH: topic, payload, QoS, retain flag and MQTT 5 properties.
- Publish
Builder - Fluent PUBLISH returned by
MqttClient::publish. - Publish
Completion - Completion handle for an outbound PUBLISH started by
MqttClient::try_start_publish. - Publish
Error - A publish that did not complete: the cause plus whether the broker can have it.
- Publish
Message - Application PUBLISH message: topic, payload, and transferable v5 properties.
- Publish
Properties - Transferable MQTT v5 PUBLISH properties (no Topic Alias, no Subscription Identifiers).
- Publish
Rejection - A QoS 1 PUBLISH the broker refused (PUBACK reason code 0x80 or higher), carried by
AppError::PublishRejected. - Publish
Response - 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.
- Publish
Window - Bounded in-flight window over
MqttClient::start_publish. - Refused
Subscription - A subscription the broker refused to restore after a reconnect, as listed by
MqttClient::refused_subscriptions. - Request
Builder - 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.
- Session
Params - Session parameters captured from a successful CONNACK.
- Standard
Reconnect Policy - Fixed reconnect delay, one immediate transport retry after a live session, and capped auth backoff.
- Static
Credentials - Fixed username/password credentials that never invalidate.
- Subscribe
Response - Result of
MqttClient::subscribe: the SUBACK. - Subscription
- One topic filter + options for
MqttClient::subscribe. - Subscription
Options - Per-filter Subscription Options byte (§3.8.3.1).
- TlsConfig
- How the client authenticates the broker over TLS, and how it authenticates itself.
- Unknown
Code - A byte that is not a defined value of the code type it was converted to:
crate::QoS,crate::RetainHandlingor one of the reason code enums. - Unsubscribe
Response - Result of
MqttClient::unsubscribe: the UNSUBACK. - User
Property - One MQTT User Property (§2.2.2.2 / UTF-8 String Pair §1.5.7).
- Will
Message - 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).
- Auth
Error - Authentication failure (CONNACK NotAuthorized, credentials provider or authenticator error, etc.).
- Broker
UrlError - Errors returned when a broker URL cannot be parsed.
- Client
IdError - Invalid Client Identifier for CONNECT ([MQTT-1.5.4], [MQTT-3.1.3]).
- Connect
AckReason - CONNACK reason codes (§3.2.2.2). Unlisted wire values decode as
Unknown. - Connect
Error - Error returned by
crate::connectwhen the initial session cannot be established. - Connection
Outcome - 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. - Disconnect
Reason Code - DISCONNECT Reason Codes (§3.14.2.1).
- Inbound
TrySend Error - Failure of a non-blocking
InboundSink::try_send. - Protocol
Error - MQTT protocol violation or unexpected control packet.
- Publish
AckReason - PUBACK / PUBREC Reason Codes (§3.4.2.1 / §3.5.2.1).
- QoS
- Quality of Service (§4.3).
- Retain
Handling - Retain Handling values in the Subscription Options byte (§3.8.3.1).
- Session
Phase - Current session phase — single type for the connect-time
tokio::sync::watchchannel and forLifecycleHookcallbacks. - Share
Name Error - ShareName validation failure ([MQTT-4.8.2-1], [MQTT-4.8.2-2]).
- Shutdown
Error - Graceful or requested shutdown.
- Subscribe
AckReason - SUBACK Reason Codes (§3.9.3).
- TlsConfig
Error - Why certificate, key or TLS settings handed to
TlsConfigare unusable. - Transport
Error - Transport-level failure (TCP, TLS, DNS), or the broker refusing or ending the connection.
- Unsubscribe
AckReason - 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
RequestBuilderwaits for the response unlessRequestBuilder::timeoutsays otherwise.
Traits§
- Auth
Exchange - 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
AUTHpackets. - Credentials
Provider - Supplies MQTT username and password for CONNECT.
- Inbound
Sink - Injectable sink for inbound
InboundMessagedelivery. - Lifecycle
Hook - Synchronous side effects for lifecycle transitions.
- Reconnect
Policy - 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
filteris a shared-subscription topic filter ($share/...). - shared_
filter - Builds an MQTT 5 shared-subscription filter string.
- topic_
matches - Whether
topicmatches the Topic Filterfilterby 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§
- User
Properties - List of User Properties on an MQTT v5 packet.