Trait AuthStrategy

Source

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

Expand description

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:

Expiring but still usable — The first caller triggers a background refresh. Concurrent callers receive the current (still-valid) token immediately without blocking.
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"]