Struct SubscriptionState 

pub struct SubscriptionState { /* private fields */ }

Generic subscription state tracker for WebSocket connections.

Maintains three separate states for subscriptions:

• Confirmed: Successfully subscribed and actively streaming data.
• Pending Subscribe: Subscription requested but not yet confirmed by server.
• Pending Unsubscribe: Unsubscription requested but not yet confirmed by server.

Reference Counting

The tracker maintains reference counts for each topic. When multiple components subscribe to the same topic, only the first subscription sends a message to the server. Similarly, only the last unsubscription sends an unsubscribe message.

Thread Safety

All operations are thread-safe and can be called concurrently from multiple tasks.

Implementations

impl SubscriptionState

pub fn new(delimiter: char) -> Self

Creates a new subscription state tracker with the specified topic delimiter.

pub fn delimiter(&self) -> char

Returns the delimiter character used for topic splitting.

pub fn confirmed(&self) -> Arc<DashMap<Ustr, AHashSet<Ustr>>>

Returns a clone of the confirmed subscriptions map.

pub fn pending_subscribe(&self) -> Arc<DashMap<Ustr, AHashSet<Ustr>>>

Returns a clone of the pending subscribe map.

pub fn pending_unsubscribe(&self) -> Arc<DashMap<Ustr, AHashSet<Ustr>>>

Returns a clone of the pending unsubscribe map.

pub fn len(&self) -> usize

Returns the number of confirmed subscriptions.

Counts both channel-level and symbol-level subscriptions.

pub fn is_empty(&self) -> bool

Returns true if there are no subscriptions (confirmed or pending).

pub fn mark_subscribe(&self, topic: &str)

Marks a topic as pending subscription.

This should be called after sending a subscribe request to the server. Idempotent: if topic is already confirmed, this is a no-op. If topic is pending unsubscription, removes it.

pub fn mark_unsubscribe(&self, topic: &str)

Marks a topic as pending unsubscription.

This removes the topic from both confirmed and pending_subscribe, then adds it to pending_unsubscribe. This handles the case where a user unsubscribes before the initial subscription is confirmed.

pub fn confirm_subscribe(&self, topic: &str)

Confirms a subscription by moving it from pending to confirmed.

This should be called when the server acknowledges a subscribe request. Ignores the confirmation if the topic is pending unsubscription (handles late confirmations after user has already unsubscribed).

pub fn confirm_unsubscribe(&self, topic: &str)

Confirms an unsubscription by removing it from pending and confirmed state.

This should be called when the server acknowledges an unsubscribe request. Removes the topic from pending_unsubscribe and confirmed. Does NOT clear pending_subscribe to support immediate re-subscribe patterns (e.g., user calls subscribe() before unsubscribe ack arrives).

Stale ACK handling: Ignores unsubscribe ACKs if the topic is no longer in pending_unsubscribe (meaning user has already re-subscribed). This prevents stale ACKs from removing topics that were re-confirmed after the re-subscribe.

pub fn mark_failure(&self, topic: &str)

Marks a subscription as failed, moving it from confirmed back to pending.

This is useful when a subscription fails but should be retried on reconnect. Ignores the failure if the topic is pending unsubscription (user cancelled it).

pub fn pending_subscribe_topics(&self) -> Vec<String>

Returns all pending subscribe topics as strings.

pub fn pending_unsubscribe_topics(&self) -> Vec<String>

Returns all pending unsubscribe topics as strings.

pub fn all_topics(&self) -> Vec<String>

Returns all topics that should be active (confirmed + pending_subscribe).

This is the key method for reconnection: it returns all topics that should be resubscribed after a connection is re-established.

Note: Does NOT include pending_unsubscribe topics, as those are being removed.

pub fn add_reference(&self, topic: &str) -> bool

Increments the reference count for a topic.

Returns true if this is the first subscription (caller should send subscribe message to server).

Panics

Panics if the reference count exceeds usize::MAX subscriptions for a single topic.

pub fn remove_reference(&self, topic: &str) -> bool

Decrements the reference count for a topic.

Returns true if this was the last subscription (caller should send unsubscribe message to server).

Panics

Panics if the internal reference count state becomes inconsistent (should never happen if the API is used correctly).

pub fn get_reference_count(&self, topic: &str) -> usize

Returns the current reference count for a topic.

Returns 0 if the topic has no references.

pub fn clear(&self)

Clears all subscription state.

This is useful when reconnecting or resetting the client.

Trait Implementations

impl Clone for SubscriptionState

fn clone(&self) -> SubscriptionState

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SubscriptionState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.