Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

16.2 KB
Raw Blame
//! The current-user cache: the last `/auth/me` answer, served fresh within a
//! short TTL, stale-while-revalidate after it, and a negative cache with a
//! bounded backoff so an unreachable backend is not re-paid the fetch timeout
//! on every poll (#5624, #5930, #6180).
//!
//! Ported from the core's `desktop::app_state::ops::{current_user,
//! current_user_generation, staleness, auth_timeout}`. Keyed on
//! `(base_url, secret)` throughout so one identity's freshness or outage is
//! never reported as another's.

use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

use serde_json::Value;

use crate::session::client::{FetchMeError, SessionClient};
use crate::session::credential::Credential;

const LOG_PREFIX: &str = "[session][cache]";

/// How long a positive `/auth/me` answer is served without asking again.
pub const REFRESH_TTL: Duration = Duration::from_secs(5);
/// Ceiling on the negative-cache backoff.
pub const BACKOFF_MAX: Duration = Duration::from_secs(60);
/// Floor under the first backoff step, independent of the fetch timeout.
const BACKOFF_BASE_FLOOR: Duration = Duration::from_secs(10);

/// Wall-clock budget for one refresh when nothing overrides it.
pub const DEFAULT_FETCH_TIMEOUT_SECS: u64 = 5;
pub const MIN_FETCH_TIMEOUT_SECS: u64 = 2;
pub const MAX_FETCH_TIMEOUT_SECS: u64 = 12;
/// Operator override for the refresh budget, in seconds (clamped 2..=12).
pub const FETCH_TIMEOUT_ENV: &str = "OPENHUMAN_AUTH_FETCH_TIMEOUT_SECS";

/// Parse a raw override into a bounded timeout in seconds.
pub fn parse_fetch_timeout_secs(raw: Option<&str>) -> u64 {
    raw.map(str::trim)
        .and_then(|s| s.parse::<u64>().ok())
        .filter(|n| (MIN_FETCH_TIMEOUT_SECS..=MAX_FETCH_TIMEOUT_SECS).contains(n))
        .unwrap_or(DEFAULT_FETCH_TIMEOUT_SECS)
}

/// The effective refresh budget.
pub fn fetch_timeout() -> Duration {
    Duration::from_secs(parse_fetch_timeout_secs(
        std::env::var(FETCH_TIMEOUT_ENV).ok().as_deref(),
    ))
}

/// First backoff step: at least the floor, and at least twice the fetch
/// timeout, so widening the timeout cannot re-open the poll treadmill.
pub fn backoff_base_for(fetch_timeout: Duration) -> Duration {
    BACKOFF_BASE_FLOOR.max(fetch_timeout.saturating_mul(2))
}

/// How long a run of `consecutive` failures suppresses the next live attempt.
pub fn backoff_for(consecutive: u32, fetch_timeout: Duration) -> Duration {
    let steps = consecutive.saturating_sub(1).min(16);
    backoff_base_for(fetch_timeout)
        .saturating_mul(2u32.saturating_pow(steps))
        .min(BACKOFF_MAX)
}

/// What the cache hands back: the user (if the backend returned one) and
/// how stale the data being served is.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
#[serde(rename_all = "camelCase")]
pub struct CachedUser {
    pub user: Option<Value>,
    /// The backend could not refresh this identity recently.
    pub stale: bool,
    /// Seconds since the backend last returned a user for this identity;
    /// `None` when it never has in this process.
    pub stale_seconds: Option<u64>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
struct Key {
    base: String,
    secret: String,
}

#[derive(Debug, Clone)]
struct Positive {
    key: Key,
    fetched_at: Instant,
    user: Value,
}

#[derive(Debug, Clone)]
struct Failure {
    key: Key,
    failed_at: Instant,
    consecutive: u32,
    error: FetchMeError,
}

#[derive(Debug, Default)]
struct State {
    positive: Option<Positive>,
    failure: Option<Failure>,
    last_success: Option<(Key, Instant)>,
    /// Bumped by [`CurrentUserCache::forget`]; a refresh that started under an
    /// older generation must not commit.
    generation: u64,
}

struct Inner {
    state: Mutex<State>,
    /// Single-flight gate for the background refresh.
    inflight: tokio::sync::Mutex<()>,
}

/// Cheap to clone: every clone shares the same cache.
#[derive(Clone)]
pub struct CurrentUserCache {
    inner: Arc<Inner>,
}

impl Default for CurrentUserCache {
    fn default() -> Self {
        Self::new()
    }
}

impl CurrentUserCache {
    pub fn new() -> Self {
        Self {
            inner: Arc::new(Inner {
                state: Mutex::new(State::default()),
                inflight: tokio::sync::Mutex::new(()),
            }),
        }
    }

    fn lock(&self) -> std::sync::MutexGuard<'_, State> {
        self.inner.state.lock().unwrap_or_else(|p| p.into_inner())
    }

    fn key(client: &SessionClient, credential: &Credential) -> Key {
        Key {
            base: client.base_url().to_string(),
            secret: credential.secret.clone(),
        }
    }

    /// Drop everything and bump the generation, so a refresh already in flight
    /// for the previous identity cannot commit. Call on logout.
    pub fn forget(&self) {
        let mut state = self.lock();
        state.generation = state.generation.wrapping_add(1);
        state.positive = None;
        state.failure = None;
        state.last_success = None;
    }

    /// Seed the positive entry with a user just fetched elsewhere (store-time
    /// validation), so the next poll is served from cache instead of paying a
    /// second round trip for the same answer.
    pub fn seed(&self, client: &SessionClient, credential: &Credential, user: Value) {
        let key = Self::key(client, credential);
        let mut state = self.lock();
        state.generation = state.generation.wrapping_add(1);
        state.positive = Some(Positive {
            key: key.clone(),
            fetched_at: Instant::now(),
            user,
        });
        state.failure = None;
        state.last_success = Some((key, Instant::now()));
    }

    /// The cached user regardless of TTL or identity. For prompt/identity
    /// peeks where a slightly stale answer is fine.
    pub fn peek(&self) -> Option<Value> {
        self.lock().positive.as_ref().map(|p| p.user.clone())
    }

    fn cached(&self, key: &Key) -> Option<(Value, Duration)> {
        let state = self.lock();
        let entry = state.positive.as_ref()?;
        (entry.key == *key).then(|| (entry.user.clone(), entry.fetched_at.elapsed()))
    }

    fn suppressed(&self, key: &Key) -> Option<(FetchMeError, u32, Duration)> {
        let state = self.lock();
        let entry = state.failure.as_ref()?;
        if entry.key != *key {
            return None;
        }
        let window = backoff_for(entry.consecutive, fetch_timeout());
        let elapsed = entry.failed_at.elapsed();
        (elapsed < window).then(|| (entry.error.clone(), entry.consecutive, window - elapsed))
    }

    /// [`Self::suppressed`], mapped to the error a caller should see: a
    /// rejection is authoritative and returned as-is (a stale-while-revalidate
    /// caller cannot observe a background result directly, so it must be
    /// retained until the next read hands it to the owner); anything else
    /// suppressed under the backoff window comes back as
    /// [`FetchMeError::Suppressed`].
    fn suppressed_error(&self, key: &Key) -> Option<FetchMeError> {
        let (error, consecutive, retry_in) = self.suppressed(key)?;
        if matches!(error, FetchMeError::Rejected(_)) {
            return Some(error);
        }
        Some(FetchMeError::Suppressed {
            message: error.message().to_string(),
            consecutive,
            retry_in,
        })
    }

    fn staleness(&self, key: &Key) -> (bool, Option<u64>) {
        let state = self.lock();
        let stale = state.failure.as_ref().is_some_and(|f| f.key == *key);
        let age = state
            .last_success
            .as_ref()
            .filter(|(k, _)| k == key)
            .map(|(_, at)| at.elapsed().as_secs());
        (stale, age)
    }

    fn record_failure(&self, generation: u64, key: &Key, error: FetchMeError) {
        let mut state = self.lock();
        if state.generation != generation {
            log::debug!("{LOG_PREFIX} discarding failure that raced sign-out");
            return;
        }
        let consecutive = match state.failure.as_ref() {
            Some(f) if f.key == *key => f.consecutive.saturating_add(1),
            _ => 1,
        };
        state.failure = Some(Failure {
            key: key.clone(),
            failed_at: Instant::now(),
            consecutive,
            error,
        });
    }

    fn with_result(&self, key: &Key, user: Option<Value>) -> CachedUser {
        let (stale, stale_seconds) = self.staleness(key);
        CachedUser {
            user,
            stale,
            stale_seconds,
        }
    }

    /// The user for `credential`, from cache when fresh, else from the backend.
    ///
    /// * fresh positive entry → served as-is;
    /// * expired positive entry → served stale while a background refresh runs;
    /// * open backoff window → [`FetchMeError::Suppressed`] without a request;
    /// * otherwise a blocking refresh bounded by [`fetch_timeout`].
    ///
    /// `force` skips every cache and goes to the network.
    pub async fn get_or_refresh(
        &self,
        client: &SessionClient,
        credential: &Credential,
        force: bool,
    ) -> Result<CachedUser, FetchMeError> {
        let key = Self::key(client, credential);
        let generation = self.lock().generation;

        if !force {
            // A rejection is authoritative regardless of what else is cached:
            // a stale-while-revalidate caller cannot observe a background
            // rejection directly, so it must be surfaced now rather than
            // served through on a positive entry that predates it.
            if let Some((error, _, _)) = self.suppressed(&key) {
                if matches!(error, FetchMeError::Rejected(_)) {
                    return Err(error);
                }
            }
            if let Some((user, age)) = self.cached(&key) {
                if age < REFRESH_TTL {
                    return Ok(self.with_result(&key, Some(user)));
                }
                self.spawn_refresh(client, credential, generation);
                log::debug!(
                    "{LOG_PREFIX} serving expired current user age_ms={} while refreshing",
                    age.as_millis()
                );
                return Ok(self.with_result(&key, Some(user)));
            }
            // No positive entry to fall back on: only now does an open
            // availability-backoff window turn into an error, instead of
            // pre-empting perfectly good cached data for the whole window
            // (#6318 review follow-up).
            if let Some(error) = self.suppressed_error(&key) {
                return Err(error);
            }
        }

        // The first caller owns the network refresh. Concurrent cache misses
        // (including forced refreshes) wait for it, then reuse its result.
        // This avoids multiplying `/auth/me` requests during startup/polling.
        let waited_for_refresh = self.inner.inflight.try_lock().is_err();
        let _refresh_guard = self.inner.inflight.lock().await;
        if waited_for_refresh {
            if let Some((user, _)) = self.cached(&key) {
                return Ok(self.with_result(&key, Some(user)));
            }
            // The caller we waited behind may have failed rather than
            // succeeded — its failure is recorded under the same lock this
            // caller just acquired. Recheck suppression before starting a
            // second sequential request: without this, every waiter behind a
            // failed first refresh redoes the same doomed call instead of
            // observing the backoff window that call just opened, turning
            // one outage into N serialized timeouts (#6318).
            if let Some(error) = self.suppressed_error(&key) {
                return Err(error);
            }
        }
        let timeout = fetch_timeout();
        match tokio::time::timeout(
            timeout,
            self.refresh_now(client, credential, generation, false),
        )
        .await
        {
            Ok(Ok(user)) => Ok(self.with_result(&key, user)),
            Ok(Err(error)) => Err(error),
            Err(_) => {
                let error = FetchMeError::Transport(format!(
                    "request timed out after {}s",
                    timeout.as_secs()
                ));
                self.record_failure(generation, &key, error.clone());
                Err(error)
            }
        }
    }

    fn spawn_refresh(&self, client: &SessionClient, credential: &Credential, generation: u64) {
        let key = Self::key(client, credential);
        if let Some((error, consecutive, remaining)) = self.suppressed(&key) {
            log::debug!(
                "{LOG_PREFIX} not refreshing behind the poll; backend failed {consecutive}x, retrying in {}ms: {}",
                remaining.as_millis(),
                error.message()
            );
            return;
        }
        let Ok(guard) = self.inner.inflight.try_lock() else {
            return;
        };
        // Move the guard into the task by re-taking it there; `try_lock` guards
        // borrow `self.inner`, so hand over an owned lock instead.
        drop(guard);
        let cache = self.clone();
        let client = client.clone();
        let credential = credential.clone();
        tokio::spawn(async move {
            let Ok(_guard) = cache.inner.inflight.try_lock() else {
                return;
            };
            let timeout = fetch_timeout();
            match tokio::time::timeout(
                timeout,
                cache.refresh_now(&client, &credential, generation, true),
            )
            .await
            {
                Ok(Ok(_)) => {}
                Ok(Err(error)) => log::debug!(
                    "{LOG_PREFIX} background refresh failed; serving stale entry: {}",
                    error.message()
                ),
                Err(_) => {
                    let key = Self::key(&client, &credential);
                    cache.record_failure(
                        generation,
                        &key,
                        FetchMeError::Transport(format!(
                            "request timed out after {}s",
                            timeout.as_secs()
                        )),
                    );
                }
            }
        });
    }

    /// Go to the backend and reconcile the caches with what came back.
    async fn refresh_now(
        &self,
        client: &SessionClient,
        credential: &Credential,
        generation: u64,
        background: bool,
    ) -> Result<Option<Value>, FetchMeError> {
        let key = Self::key(client, credential);
        // The TTL clock starts when the request goes out, not when it lands,
        // so the refresh cadence is not stretched by the round trip.
        let started_at = Instant::now();
        let fetched = match client.fetch_me(credential).await {
            Ok(user) => sanitize_user(Some(user)),
            Err(error) => {
                self.record_failure(generation, &key, error.clone());
                return Err(error);
            }
        };

        let committed = {
            let mut state = self.lock();
            if state.generation != generation {
                false
            } else {
                let moved_on = state.positive.as_ref().is_some_and(|p| p.key != key);
                if background && moved_on {
                    false
                } else {
                    state.positive = fetched.clone().map(|user| Positive {
                        key: key.clone(),
                        fetched_at: started_at,
                        user,
                    });
                    state.failure = None;
                    if fetched.is_some() {
                        state.last_success = Some((key.clone(), Instant::now()));
                    }
                    true
                }
            }
        };
        if !committed {
            log::debug!(
                "{LOG_PREFIX} discarding refresh that raced sign-out or an identity switch"
            );
        }
        if committed {
            Ok(fetched)
        } else {
            Err(FetchMeError::Superseded)
        }
    }
}

fn sanitize_user(user: Option<Value>) -> Option<Value> {
    match user {
        Some(Value::Object(map)) if map.is_empty() => None,
        Some(Value::Null) => None,
        other => other,
    }
}

#[cfg(test)]
#[path = "cache_tests.rs"]
mod tests;