Skip to main content

mqtt_glide/
lib.rs

1//! MQTT 5 Tokio client.
2//!
3//! Application-facing types live at the crate root; the wire codec (packet types, framing,
4//! encode helpers) is internal. Connection options, error
5//! types, credential/reconnect hooks, and the [`connect`] entry point define the
6//! public application contract. For a higher-level connect path with defaults, see
7//! [`ClientBuilder`]. Session I/O is driven by [`Connection::run`], backed by the
8//! internal connection read/write loops.
9//!
10//! # TLS crypto provider
11//!
12//! TLS uses rustls. Enable at least one Cargo feature:
13//!
14//! - `tls-rustls-aws-lc` (default) — rustls + aws-lc-rs
15//! - `tls-rustls-ring` — rustls + ring
16//!
17//! With both enabled (another crate in the build left the default on, or `--all-features`),
18//! ring is used: it is only ever enabled on purpose. The client builds its `ClientConfig` with
19//! that provider explicitly (`builder_with_provider`), so MQTT TLS does not depend on a
20//! process-global rustls default. To build without aws-lc-rs, use
21//! `mqtt-glide = { ..., default-features = false, features = ["tls-rustls-ring"] }`.
22//!
23//! # Other features
24//!
25//! - `websocket`: `ws://` / `wss://` broker URLs (MQTT over WebSocket).
26//! - `testing`: the in-process `testing::TestBroker` and `testing::FaultProxy` for tests of
27//!   applications; meant for `[dev-dependencies]`.
28//! - `stats`: `MqttClient::stats` returns counters of what the connection did.
29//! - `flume`: `InboundSink` for `flume::Sender<InboundMessage>`; ties your build to flume 0.12.
30//! - `async-channel`: `InboundSink` for `async_channel::Sender<InboundMessage>`; ties your build
31//!   to async-channel 2.
32//!
33//! # Stability
34//!
35//! Everything documented here follows Semantic Versioning. Features whose names start with
36//! `__` (`__internals`, `__bench`) are not: they exist for the crate's own tests, benches and
37//! fuzz target, and what they expose can change or disappear in any release.
38//!
39//! Crate overview: see the [repository README](https://github.com/justeff/mqtt-glide).
40//! Spec coverage: `CONFORMANCE.md` in the repository.
41
42#[cfg(not(any(feature = "tls-rustls-aws-lc", feature = "tls-rustls-ring")))]
43compile_error!("enable `tls-rustls-aws-lc` or `tls-rustls-ring`");
44
45mod ack;
46mod auth;
47pub mod builder;
48mod client;
49// The wire layer is internal; `__internals` opens it for the crate's own tests, benches
50// and fuzz target only.
51#[cfg(feature = "__internals")]
52#[doc(hidden)]
53pub mod codec;
54#[cfg(not(feature = "__internals"))]
55mod codec;
56#[cfg(feature = "__internals")]
57#[doc(hidden)]
58pub mod connection;
59#[cfg(not(feature = "__internals"))]
60mod connection;
61mod error;
62mod inbound_sink;
63mod options;
64mod policies;
65mod publish;
66mod publish_window;
67mod request;
68mod stats;
69#[cfg(test)]
70mod test_util;
71#[cfg(feature = "testing")]
72pub mod testing;
73mod tls;
74mod util;
75
76pub use client::{
77    AnonymousCredentials, ClientBuilder, CredentialsProvider, MqttClient, NoReconnect, Password, Publish,
78    PublishBuilder, PublishCompletion, PublishWindow, ReconnectPolicy, StaticCredentials, Subscription, connect,
79};
80// Application-facing message and option types. Wire-level packet types, the codec and the
81// encode helpers stay internal.
82pub use ack::{
83    Delivery, PublishError, PublishRejection, PublishResponse, RefusedSubscription, SubscribeResponse,
84    UnsubscribeResponse,
85};
86pub use auth::{AuthExchange, Authenticator};
87pub use codec::{
88    ConnectAckReason, DEFAULT_MAX_PACKET_SIZE, DisconnectReasonCode, InboundMessage, Properties, PublishAckReason,
89    PublishMessage, PublishProperties, QoS, RetainHandling, SubscribeAckReason, SubscriptionOptions, UnknownCode,
90    UnsubscribeAckReason, UserProperties, UserProperty, WillMessage,
91};
92pub use connection::{Connection, LifecycleHook, NoopLifecycle, SessionParams, SessionPhase};
93pub use error::{AppError, AuthError, ConnectError, ConnectionOutcome, ProtocolError, ShutdownError, TransportError};
94pub use inbound_sink::{InboundSink, InboundSinkClosed, InboundTrySendError, OnInboundSink};
95pub use options::{
96    COMMAND_CHANNEL_CAPACITY, ConnectOptions, DEFAULT_ACK_TIMEOUT, DEFAULT_CONNECT_TIMEOUT,
97    DEFAULT_GRACEFUL_DISCONNECT_TIMEOUT, DEFAULT_RECEIVE_MAXIMUM,
98};
99pub use policies::{
100    DEFAULT_AUTH_FAILURE_THRESHOLD, DEFAULT_MAX_AUTH_BACKOFF, DEFAULT_RECONNECT_DELAY, StandardReconnectPolicy,
101};
102pub use request::{DEFAULT_REQUEST_TIMEOUT, RequestBuilder, Requester};
103#[cfg(feature = "stats")]
104pub use stats::{ClientStats, ConnectionStats, InboundStats, OutboundStats};
105pub use tls::{TlsConfig, TlsConfigError};
106pub use util::{
107    BrokerUrl, BrokerUrlError, ClientId, ClientIdError, HttpProxy, ShareNameError, is_shared_subscription_filter,
108    shared_filter, topic_matches, validate_share_name,
109};
110
111// Compile README code samples as doctests (`cargo test --doc`).
112#[cfg(doctest)]
113#[doc = include_str!("../README.md")]
114mod readme_doctests {}