Trait AuthStrategy 

pub trait AuthStrategy: Send {
    // Required method
    fn get_token(
        self,
    ) -> impl Future<Output = Result<ServiceToken, AuthError>> + Send;
}

A strategy for obtaining access tokens.

Implementations handle all details of authentication, token caching, and refresh. Callers just call get_token whenever they need a valid token.

The trait is designed to be implemented for &T, so that callers can use shared references (e.g. &OAuthStrategy) without consuming the strategy.

Token refresh

All strategies that cache tokens (AccessKeyStrategy, OAuthStrategy, AutoStrategy) share the same internal refresh engine. Understanding the refresh model helps predict how get_token behaves under concurrent access.

Expiry vs usability

A token has two time thresholds:

• Expired — the token is within 90 seconds of its expires_at timestamp. This triggers a preemptive refresh attempt.
• Usable — the token has not yet reached its expires_at timestamp. A token can be “expired” (in the preemptive sense) but still “usable” (the server will still accept it).

Concurrent refresh strategies

The gap between “expired” and “unusable” enables two refresh modes:

1. Expiring but still usable — The first caller triggers a background refresh. Concurrent callers receive the current (still-valid) token immediately without blocking.
2. Fully expired — The first caller blocks while refreshing. Concurrent callers wait until the refresh completes, then all receive the new token.

Only one refresh runs at a time, regardless of how many callers request a token concurrently.

Flow diagram

flowchart TD Start["get_token()"] --> Lock["Acquire lock"] Lock --> Cached{Token cached?} Cached -- No --> InitAuth["Authenticate (lock held)"] InitAuth -- OK --> ReturnNew["Return new token"] InitAuth -- NotFound --> ErrNotFound["NotAuthenticated"] InitAuth -- Err --> ErrAuth["Return error"] Cached -- Yes --> CheckRefresh{Expired?} CheckRefresh -- "No (fresh)" --> ReturnOk["Return cached token"] CheckRefresh -- "Yes (needs refresh)" --> InProgress{Refresh in progress?} InProgress -- Yes --> WaitOrReturn["Return token if usable, else wait for refresh"] WaitOrReturn -- OK --> ReturnOk WaitOrReturn -- "refresh failed" --> ErrExpired["TokenExpired"] InProgress -- No --> HasCred{Refresh credential?} HasCred -- None --> CheckUsable["Return token if usable, else TokenExpired"] HasCred -- Yes --> Usable{Still usable?} Usable -- "Yes (preemptive)" --> NonBlocking["Refresh in background (lock released)"] NonBlocking --> ReturnOld["Return current token"] Usable -- "No (fully expired)" --> Blocking["Refresh (lock held)"] Blocking -- OK --> ReturnNew2["Return new token"] Blocking -- Err --> ErrExpired["TokenExpired"]

Required Methods

fn get_token( self, ) -> impl Future<Output = Result<ServiceToken, AuthError>> + Send

Retrieve a valid access token, refreshing or re-authenticating as needed.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl AuthStrategy for &AutoStrategy

impl AuthStrategy for &OAuthStrategy

impl<F, Fut> AuthStrategy for &AuthStrategyFn<F>

where F: Fn() -> Fut + Send + Sync, Fut: Future<Output = Result<ServiceToken, AuthError>> + Send,

Available on non-WebAssembly only.

impl<S: TokenStore> AuthStrategy for &AccessKeyStrategy<S>