Struct SubscriptionState 

pub struct SubscriptionState { /* private fields */ }

Tracks subscription intent and acknowledgment state for WebSocket connections.

State management

The tracker maintains desired subscription intent and three acknowledgment states:

• Desired: Topics that should be active, independent of response ordering or connection.
• Confirmed: Subscriptions acknowledged by the server and expected to stream data.
• Pending subscribe: Subscribe requests awaiting server acknowledgment.
• Pending unsubscribe: Unsubscribe requests awaiting server acknowledgment.

Late subscribe acknowledgments do not revive cancelled intent, and stale unsubscribe acknowledgments do not remove a later resubscription.

Reference counting

Reference counts remain independent of acknowledgment state. The first consumer tells the caller to send a subscribe request, while removing the last tells it to send an unsubscribe request. The tracker records these transitions but does not send protocol messages.

Topic format

Topics use channel{delimiter}symbol, with delimiters such as . or :. A topic without the delimiter represents a channel-level subscription.

Thread safety

Clones share all state. Operations are thread-safe and can run 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) -> SubscriptionSnapshot

Returns a read-only snapshot of confirmed subscriptions.

pub fn pending_subscribe(&self) -> SubscriptionSnapshot

Returns a read-only snapshot of pending subscriptions.

pub fn pending_unsubscribe(&self) -> SubscriptionSnapshot

Returns a read-only snapshot of pending unsubscriptions.

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 is_subscribed(&self, channel: &Ustr, symbol: &Ustr) -> bool

Returns true if a channel:symbol pair is subscribed (confirmed or pending subscribe).

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 after reconnect recovery.

The result includes confirmed and pending subscribe topics, but excludes pending unsubscribe topics.

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

Marks a topic as pending subscription.

Call this after sending a subscribe request. This operation is idempotent for a confirmed topic and cancels any pending unsubscription for the same topic.

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

Atomically tries to mark a topic as pending subscription.

Returns true if the topic was newly marked as pending (should send subscribe). Returns false if the topic was already confirmed or pending (skip sending).

The check and state transition are atomic across concurrent subscribe calls.

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

Confirms a subscription by moving it from pending to confirmed.

Call this when the server acknowledges a subscribe request. A late confirmation cannot restore a topic that is no longer desired.

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

Marks a topic as pending unsubscription.

Removes the topic from confirmed and pending_subscribe state before adding it to pending_unsubscribe. This also handles unsubscription before initial confirmation.

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

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

Call this when the server acknowledges an unsubscribe request. A stale acknowledgment is ignored if the topic is no longer pending unsubscription. pending_subscribe remains intact so an immediate resubscription survives a late unsubscribe acknowledgment.

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

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

This keeps failed subscriptions available for retry after reconnect. A topic pending unsubscription is unchanged because its subscription was cancelled.

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

Resets acknowledgment state for a replacement connection.

Returns the desired topics to replay. Confirmed topics become pending subscriptions, pending unsubscriptions are completed by the closed connection, and reference counts are preserved.

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 resets desired intent, acknowledgment state, and reference counts.

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.