Struct TokenManager 

pub struct TokenManager {
    pub token_data: Arc<Mutex<Option<TokenData>>>,
    pub retry_client: RetryClient,
    /* private fields */
}

Core token manager with proactive refresh and secure storage

Fields

token_data: Arc<Mutex<Option<TokenData>>>

retry_client: RetryClient

Implementations

impl TokenManager

pub async fn get_global_instance() -> Result<Arc<Self>, Error>

Gets the global singleton instance of TokenManager

This ensures all ApiClient instances share the same token storage, preventing multiple token acquisition attempts in concurrent tests.

Errors

Returns an error if the TokenManager cannot be initialized

pub async fn new() -> Result<Self, Error>

Creates a new TokenManager with default configuration

Errors

Returns an error if the base URL cannot be obtained from environment variables

pub async fn with_config(config: RetryConfig) -> Result<Self, Error>

Creates a new TokenManager with the specified retry configuration

Errors

Returns an error if the base URL cannot be obtained from environment variables

pub async fn with_config_and_base_url( config: RetryConfig, base_url: Url, ) -> Result<Self, Error>

Creates a new TokenManager with the specified configuration and base URL (for testing)

Errors

This method is infallible but returns Result for API consistency

pub fn with_mock_token( config: RetryConfig, base_url: Url, mock_token: String, ) -> Result<Self, Error>

Creates a new TokenManager with a pre-set mock token (for testing)

Errors

This method is infallible but returns Result for API consistency

pub async fn get_token(&self) -> Result<String, Error>

Gets a valid authentication token with proactive refresh logic

This method implements thread-safe token management logic:

1. Check if a valid token exists and is not expiring soon (within 5 minutes)
2. If token needs refresh/obtain, acquire semaphore to prevent concurrent operations
3. Double-check token state after acquiring semaphore (another thread may have updated it)
4. Perform atomic token update operations
5. Return the valid token

Thread Safety

This method is fully thread-safe and prevents race conditions by:

• Using a semaphore to ensure only one token operation at a time
• Double-checking token state after acquiring the semaphore
• Performing atomic token updates within the critical section

Errors

Returns a TokenError if token acquisition or refresh fails after all retries

pub async fn obtain_token(&self) -> Result<String, Error>

Obtains a new authentication token using environment credentials with retry logic

This method:

1. Reads credentials from environment variables
2. Makes a token request with retry logic
3. Stores the new token with 24-hour expiry
4. Returns the token string

Thread Safety

This method acquires the token operation semaphore to ensure thread-safe operation. For internal use within already-synchronized contexts, use obtain_token_internal().

Errors

Returns an error if:

• Environment variables are missing
• All retry attempts fail
• Response parsing fails

pub async fn refresh_token(&self) -> Result<String, Error>

Refreshes the current authentication token with fallback to obtain on failure

This method:

1. Uses the existing token to request a refresh
2. Updates the stored token data on success
3. Falls back to obtaining a new token if refresh fails

Thread Safety

This method acquires the token operation semaphore to ensure thread-safe operation. For internal use within already-synchronized contexts, use refresh_token_internal().

Errors

Returns an error if both refresh and obtain operations fail

pub async fn get_token_info(&self) -> Result<Option<TokenInfo>, Error>

Gets current token information for debugging and monitoring

Returns detailed information about the current token including:

• Expiry time and remaining duration
• Token age since acquisition
• Expiry status flags

Returns

Some(TokenInfo) if a token exists, None if no token is stored

Errors

Returns an error if token information retrieval fails

pub async fn clear_token(&self) -> Result<(), Error>

Clears the stored token (useful for testing scenarios)

This method removes the current token from storage, forcing the next get_token() call to obtain a fresh token.

Errors

Returns an error if token clearing fails

pub async fn force_refresh(&self) -> Result<String, Error>

Forces a token refresh regardless of current token status

This method bypasses the normal proactive refresh logic and immediately attempts to refresh the current token. If no token exists or refresh fails, it falls back to obtaining a new token.

Thread Safety

This method is fully thread-safe and uses the same semaphore-based synchronization as other token operations to prevent race conditions.

Errors

Returns an error if both refresh and obtain operations fail

pub async fn force_cleanup_token_files() -> Result<(), Error>

Forces cleanup of token persistence files (useful for testing) This method removes token files regardless of persistence settings

Errors

Returns an error if:

• File system permissions prevent deletion of the token file
• I/O errors occur during file deletion operations
• The token file is locked by another process

pub async fn reset_global_instance() -> Result<(), Error>

Resets the global TokenManager singleton (useful for testing)

This method clears the global singleton instance, forcing the next call to get_global_instance() to create a fresh TokenManager. Primarily intended for test scenarios where a clean state is needed.

Errors

Returns an error if:

• Token clearing operations fail during the reset process
• File system errors occur when clearing persistent token data
• The global instance is in an invalid state that prevents cleanup

Trait Implementations

impl Debug for TokenManager

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

Formats the value using the given formatter.