Struct Client 

pub struct Client<S> {
    state: ConnectionState,
    session: S,
    capabilities: ServerCapabilities,
    keep_alive: u16,
    send_quota: u16,
    recv_quota: u16,
    recv_max: u16,
    next_packet_id: PacketId,
    clean_start: bool,
}

Sans-io MQTT v5 client state machine.

The caller is responsible for:

• Encoding outgoing packets and writing them to the transport.
• Decoding incoming packets and feeding them to handle_packet.
• Driving timers for keep-alive (see keep_alive).

Fields

state: ConnectionState

session: S

capabilities: ServerCapabilities

keep_alive: u16

Keep-alive interval in seconds as negotiated.

send_quota: u16

Number of QoS > 0 publishes we can still send before hitting the server’s Receive Maximum.

recv_quota: u16

Number of QoS > 0 messages the client can still accept from the server before the server would violate our Receive Maximum.

recv_max: u16

The Receive Maximum value we advertise in CONNECT (§3.1.2.11.4). u16::MAX (65 535) means we never sent the property.

next_packet_id: PacketId

Monotonic packet ID counter (1..=65535, wraps around skipping 0).

clean_start: bool

Whether the last CONNECT used Clean Start = 1.

Implementations

impl<S: SessionState> Client<S>

pub fn new(session: S) -> Self

Create a new client with the given session state backend.

pub const fn connection_state(&self) -> ConnectionState

Current connection state.

pub const fn capabilities(&self) -> &ServerCapabilities

Server capabilities from the most recent CONNACK.

pub const fn keep_alive(&self) -> u16

Effective keep-alive interval in seconds.

pub const fn send_quota(&self) -> u16

Remaining send quota for QoS > 0 publishes.

pub const fn session(&mut self) -> &mut S

Mutable reference to the session state backend.

pub const fn set_receive_maximum(&mut self, max: u16)

Set the Receive Maximum value this client advertises in CONNECT.

Must be called before connect_sent to match the property actually sent in the CONNECT packet. The default is 65 535 (no limit).

pub fn connect_sent( &mut self, clean_start: bool, keep_alive: u16, ) -> Result<(), ClientError>

Record that a CONNECT packet has been sent.

The caller must construct and send the CONNECT packet themselves. This method transitions the client to ConnectionState::Connecting and records the clean_start flag and requested keep_alive.

Errors

Returns ClientError::InvalidState if the client is not disconnected.

pub fn connection_lost(&mut self)

Notify the state machine that the transport has been lost.

Resets connection-level state (quotas, capabilities) while preserving session state for reconnection.

pub fn handle_packet<'a>( &mut self, packet: &Packet<'a>, ) -> Result<HandleOutcome<'a>, ClientError>

Process an incoming decoded packet from the server.

Errors

Returns ClientError on invalid state or protocol violations.

fn handle_connack<'a>( &mut self, connack: &Connack<'a>, ) -> Result<HandleOutcome<'a>, ClientError>

fn parse_capabilities(props: &ConnackProperties) -> ServerCapabilities

fn handle_publish<'a>( &mut self, publish: &Publish<'a>, ) -> Result<HandleOutcome<'a>, ClientError>

fn handle_puback<'a>( &mut self, ack: Ack<'_>, ) -> Result<HandleOutcome<'a>, ClientError>

fn handle_pubrec<'a>( &mut self, ack: Ack<'_>, ) -> Result<HandleOutcome<'a>, ClientError>

fn handle_pubrel<'a>( &mut self, ack: Ack<'_>, ) -> Result<HandleOutcome<'a>, ClientError>

fn handle_pubcomp<'a>( &mut self, ack: Ack<'_>, ) -> Result<HandleOutcome<'a>, ClientError>

fn handle_suback<'a>( &self, suback: &Suback<'a>, ) -> Result<HandleOutcome<'a>, ClientError>

fn handle_unsuback<'a>( &self, unsuback: &Unsuback<'a>, ) -> Result<HandleOutcome<'a>, ClientError>

fn handle_pingresp<'a>(&self) -> Result<HandleOutcome<'a>, ClientError>

const fn handle_disconnect<'a>( &mut self, disconnect: &Disconnect<'a>, ) -> Result<HandleOutcome<'a>, ClientError>

const fn handle_auth<'a>(&mut self) -> Result<HandleOutcome<'a>, ClientError>

pub fn prepare_publish_qos1( &mut self, topic: &Topic, payload: &[u8], retain: bool, properties: &PublishProperties, ) -> Result<PacketId, ClientError>

Allocate a packet identifier and store a QoS 1 publish in the session for potential retransmission.

Returns the allocated packet_id. The caller must construct and send the PUBLISH packet using this ID.

Errors

Returns ClientError::InvalidState if not connected, or ClientError::QuotaExhausted if the send quota is exhausted.

pub fn prepare_publish_qos2( &mut self, topic: &Topic, payload: &[u8], retain: bool, properties: &PublishProperties, ) -> Result<PacketId, ClientError>

Allocate a packet identifier and store a QoS 2 publish in the session for potential retransmission.

Returns the allocated packet_id. The caller must construct and send the PUBLISH packet using this ID.

Errors

Returns ClientError::InvalidState if not connected, or ClientError::QuotaExhausted if the send quota is exhausted.

pub fn prepare_subscribe(&mut self) -> Result<PacketId, ClientError>

Allocate a packet identifier for a SUBSCRIBE.

The caller must construct the SUBSCRIBE packet using this ID.

Errors

Returns ClientError::InvalidState if not connected.

pub fn prepare_unsubscribe(&mut self) -> Result<PacketId, ClientError>

Allocate a packet identifier for an UNSUBSCRIBE.

The caller must construct the UNSUBSCRIBE packet using this ID.

Errors

Returns ClientError::InvalidState if not connected.

pub fn puback_sent(&mut self)

Notify the state machine that a PUBACK was sent for an incoming QoS 1 message.

Restores one unit of receive quota. Must be called after the PUBACK response packet has actually been written to the transport.

pub const fn check_subscribe_capabilities( &self, has_wildcard: bool, has_sub_id: bool, has_shared: bool, ) -> Result<(), ClientError>

Check whether a subscribe operation is compatible with server capabilities.

Errors

Returns an error if the subscribe would violate a server capability.

pub fn try_for_each_retransmit<B>( &self, f: &mut dyn FnMut(Retransmit<'_>) -> ControlFlow<B>, ) -> ControlFlow<B>

Iterate over all messages that need retransmission after a reconnect with Clean Start = 0.

The callback is invoked for each pending retransmission. The caller must reconstruct and send the appropriate packets:

• QoS 1 PUBLISH with DUP=1
• QoS 2 PUBLISH with DUP=1 (if still awaiting PUBREC)
• PUBREL (if awaiting PUBCOMP)
• PUBREC (for incoming QoS 2 messages awaiting PUBREL)

Return ControlFlow::Break from the callback to stop early.

fn alloc_packet_id(&mut self) -> Result<PacketId, ClientError>

const fn increment_send_quota(&mut self)