Trait SessionState 

pub trait SessionState {
    // Required methods
    fn apply(&mut self, op: SessionOp<'_>) -> Applied;
    fn reset_outbox_sent_flags(&mut self);
    fn for_each_outbox_entry(
        &self,
        f: &mut dyn FnMut(PacketId, OutboxEntry<'_>),
    );
    fn drain_outbox(
        &mut self,
        visit: &mut dyn FnMut(PacketId, OutboxEntry<'_>) -> DrainAction,
    );
    fn reset_in_flight(&mut self);
    fn has_pubrel_pending(&self, packet_id: PacketId) -> bool;
    fn for_each_pubrel_pending(&self, f: &mut dyn FnMut(PacketId));
    fn drain_pubrel(&mut self, visit: &mut dyn FnMut(PacketId) -> DrainAction);
    fn has_incoming_qos2(&self, packet_id: PacketId) -> bool;
    fn clear_incoming_qos2(&mut self);
    fn for_each_incoming_qos2(&self, f: &mut dyn FnMut(PacketId));
    fn get_filter_entry(&self, filter: &TopicFilter) -> Option<FilterEntry<'_>>;
    fn resolve_pending(
        &mut self,
        packet_id: PacketId,
        decide: &mut dyn FnMut(FilterEntry<'_>) -> Resolution,
    );
    fn for_each_active_subscription(&self, f: &mut dyn FnMut(Subscription<'_>));
    fn for_each_filter_entry(&self, f: &mut dyn FnMut(FilterEntry<'_>));
    fn first_pending_group(&self) -> Option<PendingMeta>;
    fn pending_subscribe_filters(
        &self,
        packet_id: PacketId,
    ) -> impl Iterator<Item = (&TopicFilter, SubscriptionOptions)>;
    fn pending_unsubscribe_filters(
        &self,
        packet_id: PacketId,
    ) -> impl Iterator<Item = &TopicFilter>;
    fn mark_subscription_in_flight(&mut self, packet_id: PacketId);
    fn is_packet_id_in_use(&self, packet_id: PacketId) -> bool;
}

Persistent session state that must survive across network connections.

This trait follows the repository pattern: each method is a mechanical storage primitive. All MQTT protocol logic lives in Client; its decisions reach the session as DrainAction/Resolution values.

Contract

Implementors must persist state durably when Session Expiry Interval > 0 (§3.1.2.11.2). When the interval is 0 (or absent), state only needs to live for the duration of the network connection.

Adding a method to this trait is a breaking change by design.

Required Methods

fn apply(&mut self, op: SessionOp<'_>) -> Applied

Applies a single operation to this session.

This is the single write entry point. Applied reports whether the mutation took effect; for remove ops, Applied::Absent signals that the op should not be persisted.

fn reset_outbox_sent_flags(&mut self)

Resets was_sent to false on every outbox entry.

Called after a broker-initiated session loss to ensure all resends are treated as first deliveries (DUP=0) on the new connection.

fn for_each_outbox_entry(&self, f: &mut dyn FnMut(PacketId, OutboxEntry<'_>))

Iterates over every outbox entry.

Used for snapshotting (compaction) and capability re-checks; the send path uses drain_outbox instead.

fn drain_outbox( &mut self, visit: &mut dyn FnMut(PacketId, OutboxEntry<'_>) -> DrainAction, )

Visits each outbox entry not already in flight on the current connection, in packet-id order, applying the DrainAction the visitor returns: Sent marks it in-flight and was_sent; Discard removes it; Stop halts the walk. This is the single outbound send path, so the visitor is the only place a publish reaches the wire.

fn reset_in_flight(&mut self)

Clears the in-flight marker on every outbox entry, PUBREL-pending entry, and in-flight SUBSCRIBE/UNSUBSCRIBE request.

Called when a connection is established (every connect, resumed or reset) so the next drain_outbox / drain_pubrel / subscription drain (peeked via first_pending_group) retransmits everything once. Re-arming subscription requests here is what makes an unacknowledged SUBSCRIBE re-send on a resumed session too: brokers do not retransmit SUBACK/UNSUBACK as resumable session state. This is per-connection scratch state and is never persisted.

fn has_pubrel_pending(&self, packet_id: PacketId) -> bool

Returns true if a PUBREL is pending for packet_id (the QoS 2 publish is in the awaiting-PUBCOMP phase).

Lets the client answer a duplicate PUBREC idempotently (re-send PUBREL) instead of treating it as an unknown identifier.

fn for_each_pubrel_pending(&self, f: &mut dyn FnMut(PacketId))

Iterates over every PUBREL-pending packet identifier.

Used during reconnect to fail awaiting-PUBCOMP futures on session loss and for snapshotting; the resend path uses drain_pubrel.

fn drain_pubrel(&mut self, visit: &mut dyn FnMut(PacketId) -> DrainAction)

Visits each PUBREL-pending entry not already in flight on the current connection, applying the returned DrainAction. Mirrors drain_outbox for the QoS 2 PUBREL resend.

fn has_incoming_qos2(&self, packet_id: PacketId) -> bool

Checks whether an incoming QoS 2 packet identifier is stored (i.e., PUBREC was already sent for this packet ID).

fn clear_incoming_qos2(&mut self)

Clears all incoming QoS 2 packet identifiers.

Called as part of session-lost handling: the broker has no record of our PUBREC acknowledgements, so they are discarded.

fn for_each_incoming_qos2(&self, f: &mut dyn FnMut(PacketId))

Iterates over every stored incoming QoS 2 packet identifier.

fn get_filter_entry(&self, filter: &TopicFilter) -> Option<FilterEntry<'_>>

Returns the stored entry for a single topic filter, or None if it has not been touched. Used by the client to determine the filter’s current state before recording an UNSUBSCRIBE transition.

fn resolve_pending( &mut self, packet_id: PacketId, decide: &mut dyn FnMut(FilterEntry<'_>) -> Resolution, )

Visits every filter entry pending (Subscribing or Unsubscribing) under packet_id and applies the returned Resolution, dropping the entry’s pending-order slot for every decision other than Resolution::Keep.

fn for_each_active_subscription(&self, f: &mut dyn FnMut(Subscription<'_>))

Iterates over every Subscribed filter (the application’s active subscriptions). In-flight Subscribing/ Unsubscribing entries are skipped.

fn for_each_filter_entry(&self, f: &mut dyn FnMut(FilterEntry<'_>))

Iterates over every filter entry with its full state, for snapshotting (compaction/persistence).

fn first_pending_group(&self) -> Option<PendingMeta>

Returns the pending SUBSCRIBE/UNSUBSCRIBE group with the lowest packet id that is not already in flight on the current connection, or None when none remain. This is a read-only peek; the caller iterates the group’s filters (pending_subscribe_filters / pending_unsubscribe_filters), enqueues the packet, then commits the group with mark_subscription_in_flight.

Looping over this is the single send path for subscription state, mirroring drain_outbox for publishes.

fn pending_subscribe_filters( &self, packet_id: PacketId, ) -> impl Iterator<Item = (&TopicFilter, SubscriptionOptions)>

Iterates the filters of the pending SUBSCRIBE under packet_id, in packet order (their position in the SUBACK), each with its subscription options. Empty unless packet_id is a pending SUBSCRIBE.

fn pending_unsubscribe_filters( &self, packet_id: PacketId, ) -> impl Iterator<Item = &TopicFilter>

Iterates the filters of the pending UNSUBSCRIBE under packet_id, in packet order. Empty unless packet_id is a pending UNSUBSCRIBE.

fn mark_subscription_in_flight(&mut self, packet_id: PacketId)

Marks every filter under packet_id in flight and drops the group from the pending set, so the next first_pending_group skips it until reset_in_flight re-arms it. Called once the group’s packet has been enqueued.

fn is_packet_id_in_use(&self, packet_id: PacketId) -> bool

Returns true if packet_id is currently occupied by any tracked operation: an outbox entry, a PUBREL-pending entry, or an in-flight SUBSCRIBE/UNSUBSCRIBE.

Used by the client to skip identifiers that are already in use during packet ID allocation.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl SessionState for JournaledSession

Available on crate feature alloc only.

impl SessionState for InMemorySession

Available on crate feature alloc only.