atp-client 0.1.0

Framework-neutral ATP billing SDK with optional Axum routes, guards, caching, and JWT claims enrichment
Documentation
use crate::{
    AtpClient, BillingProvider, BillingSnapshot, BillingStatus, SdkResult, SnapshotSource,
};
use async_trait::async_trait;
use std::{
    collections::HashMap,
    sync::Arc,
    time::{Duration, Instant},
};
use tokio::sync::{Mutex, RwLock};

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// Determines how a status lookup behaves when ATP cannot be reached.
pub enum FailureMode {
    /// Return the upstream error. Use this for authorization and paid operations.
    FailClosed,
    /// Return a cached value within `stale_ttl`, marked as degraded.
    UseStale,
    /// Return a synthetic Free-tier snapshot, marked as degraded.
    FreeTier,
}

#[derive(Debug, Clone)]
/// Bounds status-cache freshness, memory use, and outage behavior.
pub struct BillingCacheConfig {
    /// Age below which a cached status can be used without contacting ATP.
    pub fresh_ttl: Duration,
    /// Maximum total age of an entry eligible for [`FailureMode::UseStale`].
    pub stale_ttl: Duration,
    /// Maximum number of user entries and in-flight lookup locks retained locally.
    pub max_entries: usize,
    /// Behavior when both the fresh cache and ATP are unavailable.
    pub failure_mode: FailureMode,
}
impl Default for BillingCacheConfig {
    fn default() -> Self {
        Self {
            fresh_ttl: Duration::from_secs(30),
            stale_ttl: Duration::from_secs(300),
            max_entries: 10_000,
            failure_mode: FailureMode::FailClosed,
        }
    }
}
impl BillingCacheConfig {
    /// Safe preset for feature authorization: ATP failures deny access.
    pub fn authorization() -> Self {
        Self::default()
    }
    /// Login-continuity preset: ATP failures produce degraded Free claims.
    ///
    /// Do not use this preset to authorize paid work.
    pub fn authentication_fail_open() -> Self {
        Self {
            failure_mode: FailureMode::FreeTier,
            ..Self::default()
        }
    }
    /// UI preset: a recently expired status may be shown during an ATP outage.
    pub fn ui_read_optimized() -> Self {
        Self {
            failure_mode: FailureMode::UseStale,
            ..Self::default()
        }
    }
}

#[derive(Clone)]
struct Entry {
    loaded_at: Instant,
    status: BillingStatus,
}
#[derive(Clone)]
/// Bounded, process-local store for recent per-user billing status.
///
/// A cache instance belongs to exactly one ATP client/API key and must never be
/// shared across tenants.
pub struct BillingCache {
    config: BillingCacheConfig,
    entries: Arc<RwLock<HashMap<String, Entry>>>,
    flights: Arc<Mutex<HashMap<String, Arc<Mutex<()>>>>>,
}
impl BillingCache {
    /// Creates an empty cache using the supplied policy.
    pub fn new(config: BillingCacheConfig) -> Self {
        Self {
            config,
            entries: Default::default(),
            flights: Default::default(),
        }
    }
    /// Removes a user's cached status after a balance-changing operation.
    pub async fn invalidate(&self, user_id: &str) {
        self.entries.write().await.remove(user_id);
    }
    async fn entry(&self, user_id: &str) -> Option<Entry> {
        self.entries.read().await.get(user_id).cloned()
    }
    async fn put(&self, user_id: &str, status: BillingStatus) {
        let mut entries = self.entries.write().await;
        if entries.len() >= self.config.max_entries
            && !entries.contains_key(user_id)
            && let Some(oldest) = entries
                .iter()
                .min_by_key(|(_, value)| value.loaded_at)
                .map(|(key, _)| key.clone())
        {
            entries.remove(&oldest);
        }
        entries.insert(
            user_id.into(),
            Entry {
                loaded_at: Instant::now(),
                status,
            },
        );
    }
    async fn flight(&self, user_id: &str) -> Arc<Mutex<()>> {
        let mut flights = self.flights.lock().await;
        if flights.len() >= self.config.max_entries
            && !flights.contains_key(user_id)
            && let Some(key) = flights.keys().next().cloned()
        {
            flights.remove(&key);
        }
        flights.entry(user_id.into()).or_default().clone()
    }
}

#[derive(Clone)]
/// ATP client wrapper that caches status lookups but never caches writes.
pub struct CachedBillingClient {
    client: AtpClient,
    cache: BillingCache,
}
impl CachedBillingClient {
    /// Wraps a raw client with the supplied local cache policy.
    pub fn new(client: AtpClient, config: BillingCacheConfig) -> Self {
        Self {
            client,
            cache: BillingCache::new(config),
        }
    }
    /// Returns the underlying non-caching client.
    pub fn raw_client(&self) -> &AtpClient {
        &self.client
    }
    /// Removes a user's cached status.
    pub async fn invalidate(&self, user_id: &str) {
        self.cache.invalidate(user_id).await;
    }
    /// Returns a fresh, cached, stale, or fallback billing snapshot.
    pub async fn status(&self, user_id: &str) -> SdkResult<BillingSnapshot> {
        self.load(user_id).await
    }
    /// Atomically debits credits through ATP and invalidates cached status on success.
    pub async fn debit(
        &self,
        request: &crate::DebitRequest,
        idempotency_key: &str,
    ) -> SdkResult<crate::DebitResult> {
        let result = self.client.debit(request, idempotency_key).await?;
        self.invalidate(&request.user_id).await;
        Ok(result)
    }
    /// Refunds a prior debit through ATP and invalidates cached status on success.
    pub async fn refund(
        &self,
        request: &crate::RefundRequest,
        idempotency_key: &str,
    ) -> SdkResult<crate::DebitResult> {
        let result = self.client.refund(request, idempotency_key).await?;
        self.invalidate(&request.user_id).await;
        Ok(result)
    }
    async fn load(&self, user_id: &str) -> SdkResult<BillingSnapshot> {
        if let Some(entry) = self.cache.entry(user_id).await
            && entry.loaded_at.elapsed() < self.cache.config.fresh_ttl
        {
            return Ok(BillingSnapshot {
                status: entry.status,
                source: SnapshotSource::Cache,
                degraded: false,
            });
        }
        let flight = self.cache.flight(user_id).await;
        let _guard = flight.lock().await;
        if let Some(entry) = self.cache.entry(user_id).await
            && entry.loaded_at.elapsed() < self.cache.config.fresh_ttl
        {
            return Ok(BillingSnapshot {
                status: entry.status,
                source: SnapshotSource::Cache,
                degraded: false,
            });
        }
        match self.client.status(user_id).await {
            Ok(status) => {
                self.cache.put(user_id, status.clone()).await;
                Ok(BillingSnapshot {
                    status,
                    source: SnapshotSource::Fresh,
                    degraded: false,
                })
            }
            Err(error) => match self.cache.config.failure_mode {
                FailureMode::FailClosed => Err(error),
                FailureMode::UseStale => {
                    if let Some(entry) = self
                        .cache
                        .entry(user_id)
                        .await
                        .filter(|entry| entry.loaded_at.elapsed() < self.cache.config.stale_ttl)
                    {
                        Ok(BillingSnapshot {
                            status: entry.status,
                            source: SnapshotSource::Stale,
                            degraded: true,
                        })
                    } else {
                        Err(error)
                    }
                }
                FailureMode::FreeTier => Ok(BillingSnapshot {
                    status: BillingStatus::free_fallback(user_id),
                    source: SnapshotSource::FreeFallback,
                    degraded: true,
                }),
            },
        }
    }
}

#[async_trait]
impl BillingProvider for CachedBillingClient {
    async fn billing_snapshot(&self, user_id: &str) -> SdkResult<BillingSnapshot> {
        self.load(user_id).await
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn defaults_bound_memory_and_staleness() {
        let value = BillingCacheConfig::default();
        assert!(value.max_entries > 0);
        assert!(value.stale_ttl > value.fresh_ttl);
    }
}