Struct AuthTracker 

pub struct AuthTracker { /* private fields */ }

Tracks authentication state for WebSocket connections.

Each authentication attempt receives a dedicated oneshot channel that resolves when the server responds.

State management

The tracker maintains three states:

• AuthState::Unauthenticated: The initial state, the state after Self::begin, and the result of Self::invalidate from AuthState::Authenticated.
• AuthState::Authenticated: The state after Self::succeed.
• AuthState::Failed: The state after Self::fail. Authentication waiters return early in this state.

Superseding behavior

If a new authentication attempt begins while another remains pending, the old attempt is cancelled with an error. This prevents responses from an earlier attempt from racing with a later attempt during rapid reconnections.

Thread safety

Clones share the pending attempt and session state. All operations are thread-safe and can run concurrently from multiple tasks.

Implementations

impl AuthTracker

pub fn new() -> Self

Creates a new authentication tracker.

pub fn auth_state(&self) -> AuthState

Returns the current authentication state.

pub fn is_authenticated(&self) -> bool

Returns whether the client is currently authenticated.

pub fn invalidate(&self)

Clears authenticated state without affecting pending auth attempts.

Call this when a live connection drops and reconnect may authenticate again, so operations requiring authentication are properly guarded. A terminal AuthState::Failed state remains failed.

pub fn begin(&self) -> AuthResultReceiver

Begins a new authentication attempt.

Returns a receiver that will be notified when authentication completes. If a previous authentication attempt is still pending, it will be cancelled with an error message indicating it was superseded.

Transitions to Unauthenticated since a new attempt invalidates any previous status.

pub fn succeed(&self)

Marks the current authentication attempt as successful.

Transitions to Authenticated and notifies any waiting receiver with Ok(()). This should be called when the server sends a successful authentication response.

The state is always updated even if no receiver is waiting (e.g., after a timeout), since the server has confirmed authentication.

pub fn fail(&self, error: impl Into<String>)

Marks the current authentication attempt as failed.

Transitions to Failed and notifies any waiting receiver with Err(message). This should be called when the server sends an authentication error response, or on terminal client shutdown.

The state is always updated even if no receiver is waiting, since the server has rejected authentication or future auth is impossible.

pub async fn wait_for_result<E>( &self, timeout: Duration, receiver: AuthResultReceiver, ) -> Result<(), E>

where E: From<String>,

Waits for the authentication result with a timeout.

Returns Ok(()) if authentication succeeds, or an error if it fails, times out, or the channel is closed.

Type Parameters

• E: Error type that implements From<String> for error message conversion

Errors

Returns an error in the following cases:

• Authentication fails (server rejects credentials)
• Authentication times out (no response within timeout duration)
• Authentication channel closes unexpectedly
• Authentication attempt is superseded by a new attempt

pub async fn wait_for_authenticated(&self, timeout: Duration) -> bool

Waits for the tracker to enter the authenticated state.

Returns true if authenticated within the timeout, false if the timeout expires or authentication explicitly fails. Uses event-driven notification from succeed() / fail() / invalidate() to avoid polling.

Returns early with false when fail() is called (e.g., the exchange rejects credentials), so callers are not blocked for the full timeout on a definitive auth rejection.

This is intended for callers on a separate task who need to gate operations on authentication state (e.g., order sends that must wait for re-authentication after a WebSocket reconnection).

Trait Implementations

impl Clone for AuthTracker

fn clone(&self) -> AuthTracker

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AuthTracker

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

Formats the value using the given formatter.

impl Default for AuthTracker

fn default() -> Self

Returns the “default value” for a type.