Struct ClientOptions 

#[non_exhaustive]
pub struct ClientOptions {

    pub client_id: MqttString,
    pub keep_alive: u16,
    pub clean_start: CleanStart,
    pub username: Option<MqttString>,
    pub password: Option<MqttBytesBuf>,
    pub session_expiry: Option<u32>,
    pub receive_maximum: Option<NonZeroU16>,
    pub topic_alias_maximum: Option<u16>,
    pub maximum_packet_size: Option<NonZeroU32>,
    pub connect_timeout: Option<Duration>,
    pub ack_timeout: Option<Duration>,
    pub will: Option<WillOptions>,
    pub reconnect: Option<ReconnectOptions>,
}

Options for the MQTT v5 client.

Controls the CONNECT packet fields, v5 session properties, and automatic reconnection behaviour.

Construct it with ClientOptions::new and the builder methods.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

client_id: MqttString

Client identifier. An empty string lets the broker assign one.

keep_alive: u16

Keep-alive interval in seconds. 0 disables keep-alive.

clean_start: CleanStart

Whether to request a clean start on the initial connect.

username: Option<MqttString>

Optional username for authentication.

password: Option<MqttBytesBuf>

Optional password for authentication.

session_expiry: Option<u32>

Session expiry interval in seconds (property 0x11). None = not sent; Some(0) = session ends on disconnect.

receive_maximum: Option<NonZeroU16>

Maximum number of in-flight QoS 1/2 messages this client can handle (property 0x21).

topic_alias_maximum: Option<u16>

Maximum topic alias value this client supports (property 0x22). None or Some(0) = topic aliases disabled.

maximum_packet_size: Option<NonZeroU32>

Maximum packet size this client is willing to accept (property 0x27).

Advertised to the broker and enforced on receive: an inbound packet whose declared size exceeds this is rejected with DISCONNECT (PacketTooLarge) before its body is buffered, so a peer cannot force an unbounded allocation. Defaults to DEFAULT_MAX_PACKET_SIZE; raise it for large-payload workloads.

connect_timeout: Option<Duration>

Deadline for a single connection attempt: TCP connect plus the CONNECT / CONNACK handshake. If it elapses the attempt is abandoned (and retried when reconnection is enabled), so a broker that accepts the socket but never answers cannot hang the client. None disables it.

ack_timeout: Option<Duration>

Deadline for an in-flight QoS >= 1 operation to be acknowledged. If a PUBACK/PUBCOMP (publish) or SUBACK/UNSUBACK (subscribe/unsubscribe) does not arrive within this duration of the packet being written, the connection is treated as dead and torn down; reconnection then resumes the session and retransmits the unacknowledged operations.

This is a liveness signal tied to real traffic, independent of keep_alive: it detects a broker that keeps the socket alive (and may even send unrelated inbound traffic) but never acknowledges your operations, which the keep-alive probe cannot.

It only provides coverage while operations are in flight. With no outstanding QoS >= 1 operation there is nothing to time out, so an idle gap is not covered. Setting keep_alive to 0 and relying solely on this is therefore safe only under a workload with continuous QoS >= 1 traffic. None disables it (the default).

will: Option<WillOptions>

Will message configuration. None = no will message.

reconnect: Option<ReconnectOptions>

Reconnect strategy. None disables automatic reconnection.

Implementations

impl ClientOptions

pub const fn new(client_id: MqttString) -> Self

Creates minimal options with a client ID.

Defaults: keep-alive 60 s, CleanStart::Auto, no auth, no reconnect, a DEFAULT_MAX_PACKET_SIZE inbound bound, and a DEFAULT_CONNECT_TIMEOUT handshake deadline.

pub const fn connect_timeout(self, timeout: Duration) -> Self

Sets the connection-attempt deadline (TCP connect + CONNACK handshake).

pub const fn keep_alive(self, secs: u16) -> Self

Sets the keep-alive interval in seconds.

pub const fn ack_timeout(self, timeout: Duration) -> Self

Sets the ack_timeout for in-flight QoS >= 1 operations.

pub const fn clean_start(self, clean_start: CleanStart) -> Self

Sets whether to request a clean start on the initial connect.

pub fn username(self, user: MqttString) -> Self

Sets the username for authentication.

pub fn password(self, pass: MqttBytesBuf) -> Self

Sets the password for authentication.

pub const fn session_expiry(self, seconds: u32) -> Self

Sets the session expiry interval in seconds (v5 property 0x11).

pub const fn receive_maximum(self, max: NonZeroU16) -> Self

Sets the receive maximum (v5 property 0x21).

pub const fn topic_alias_maximum(self, max: u16) -> Self

Sets the topic alias maximum this client supports (v5 property 0x22).

pub const fn maximum_packet_size(self, max: NonZeroU32) -> Self

Sets the maximum packet size this client will accept (v5 property 0x27).

pub fn will(self, topic: TopicBuf, payload: MqttBytesBuf) -> Self

Sets a will message (Last Will and Testament).

The broker publishes this message if the client disconnects ungracefully.

pub fn will_with(self, will: WillOptions) -> Self

Sets a will message with full configuration.

pub fn reconnect(self) -> Self

Enables automatic reconnection with default settings.

pub const fn reconnect_with(self, opts: ReconnectOptions) -> Self

Enables automatic reconnection with custom settings.

fn iter_connect_properties(&self) -> impl Iterator<Item = Property<'_>>

pub(crate) fn to_connect_properties( &self, ) -> Result<ConnectPropertiesBuf, PropertiesBufError>