Skip to main content

atp_client/
cache.rs

1use crate::{
2    AtpClient, BillingProvider, BillingSnapshot, BillingStatus, SdkResult, SnapshotSource,
3};
4use async_trait::async_trait;
5use std::{
6    collections::HashMap,
7    sync::Arc,
8    time::{Duration, Instant},
9};
10use tokio::sync::{Mutex, RwLock};
11
12#[derive(Debug, Clone, Copy, PartialEq, Eq)]
13/// Determines how a status lookup behaves when ATP cannot be reached.
14pub enum FailureMode {
15    /// Return the upstream error. Use this for authorization and paid operations.
16    FailClosed,
17    /// Return a cached value within `stale_ttl`, marked as degraded.
18    UseStale,
19    /// Return a synthetic Free-tier snapshot, marked as degraded.
20    FreeTier,
21}
22
23#[derive(Debug, Clone)]
24/// Bounds status-cache freshness, memory use, and outage behavior.
25pub struct BillingCacheConfig {
26    /// Age below which a cached status can be used without contacting ATP.
27    pub fresh_ttl: Duration,
28    /// Maximum total age of an entry eligible for [`FailureMode::UseStale`].
29    pub stale_ttl: Duration,
30    /// Maximum number of user entries and in-flight lookup locks retained locally.
31    pub max_entries: usize,
32    /// Behavior when both the fresh cache and ATP are unavailable.
33    pub failure_mode: FailureMode,
34}
35impl Default for BillingCacheConfig {
36    fn default() -> Self {
37        Self {
38            fresh_ttl: Duration::from_secs(30),
39            stale_ttl: Duration::from_secs(300),
40            max_entries: 10_000,
41            failure_mode: FailureMode::FailClosed,
42        }
43    }
44}
45impl BillingCacheConfig {
46    /// Safe preset for feature authorization: ATP failures deny access.
47    pub fn authorization() -> Self {
48        Self::default()
49    }
50    /// Login-continuity preset: ATP failures produce degraded Free claims.
51    ///
52    /// Do not use this preset to authorize paid work.
53    pub fn authentication_fail_open() -> Self {
54        Self {
55            failure_mode: FailureMode::FreeTier,
56            ..Self::default()
57        }
58    }
59    /// UI preset: a recently expired status may be shown during an ATP outage.
60    pub fn ui_read_optimized() -> Self {
61        Self {
62            failure_mode: FailureMode::UseStale,
63            ..Self::default()
64        }
65    }
66}
67
68#[derive(Clone)]
69struct Entry {
70    loaded_at: Instant,
71    status: BillingStatus,
72}
73#[derive(Clone)]
74/// Bounded, process-local store for recent per-user billing status.
75///
76/// A cache instance belongs to exactly one ATP client/API key and must never be
77/// shared across tenants.
78pub struct BillingCache {
79    config: BillingCacheConfig,
80    entries: Arc<RwLock<HashMap<String, Entry>>>,
81    flights: Arc<Mutex<HashMap<String, Arc<Mutex<()>>>>>,
82}
83impl BillingCache {
84    /// Creates an empty cache using the supplied policy.
85    pub fn new(config: BillingCacheConfig) -> Self {
86        Self {
87            config,
88            entries: Default::default(),
89            flights: Default::default(),
90        }
91    }
92    /// Removes a user's cached status after a balance-changing operation.
93    pub async fn invalidate(&self, user_id: &str) {
94        self.entries.write().await.remove(user_id);
95    }
96    async fn entry(&self, user_id: &str) -> Option<Entry> {
97        self.entries.read().await.get(user_id).cloned()
98    }
99    async fn put(&self, user_id: &str, status: BillingStatus) {
100        let mut entries = self.entries.write().await;
101        if entries.len() >= self.config.max_entries
102            && !entries.contains_key(user_id)
103            && let Some(oldest) = entries
104                .iter()
105                .min_by_key(|(_, value)| value.loaded_at)
106                .map(|(key, _)| key.clone())
107        {
108            entries.remove(&oldest);
109        }
110        entries.insert(
111            user_id.into(),
112            Entry {
113                loaded_at: Instant::now(),
114                status,
115            },
116        );
117    }
118    async fn flight(&self, user_id: &str) -> Arc<Mutex<()>> {
119        let mut flights = self.flights.lock().await;
120        if flights.len() >= self.config.max_entries
121            && !flights.contains_key(user_id)
122            && let Some(key) = flights.keys().next().cloned()
123        {
124            flights.remove(&key);
125        }
126        flights.entry(user_id.into()).or_default().clone()
127    }
128}
129
130#[derive(Clone)]
131/// ATP client wrapper that caches status lookups but never caches writes.
132pub struct CachedBillingClient {
133    client: AtpClient,
134    cache: BillingCache,
135}
136impl CachedBillingClient {
137    /// Wraps a raw client with the supplied local cache policy.
138    pub fn new(client: AtpClient, config: BillingCacheConfig) -> Self {
139        Self {
140            client,
141            cache: BillingCache::new(config),
142        }
143    }
144    /// Returns the underlying non-caching client.
145    pub fn raw_client(&self) -> &AtpClient {
146        &self.client
147    }
148    /// Removes a user's cached status.
149    pub async fn invalidate(&self, user_id: &str) {
150        self.cache.invalidate(user_id).await;
151    }
152    /// Returns a fresh, cached, stale, or fallback billing snapshot.
153    pub async fn status(&self, user_id: &str) -> SdkResult<BillingSnapshot> {
154        self.load(user_id).await
155    }
156    /// Atomically debits credits through ATP and invalidates cached status on success.
157    pub async fn debit(
158        &self,
159        request: &crate::DebitRequest,
160        idempotency_key: &str,
161    ) -> SdkResult<crate::DebitResult> {
162        let result = self.client.debit(request, idempotency_key).await?;
163        self.invalidate(&request.user_id).await;
164        Ok(result)
165    }
166    /// Refunds a prior debit through ATP and invalidates cached status on success.
167    pub async fn refund(
168        &self,
169        request: &crate::RefundRequest,
170        idempotency_key: &str,
171    ) -> SdkResult<crate::DebitResult> {
172        let result = self.client.refund(request, idempotency_key).await?;
173        self.invalidate(&request.user_id).await;
174        Ok(result)
175    }
176    async fn load(&self, user_id: &str) -> SdkResult<BillingSnapshot> {
177        if let Some(entry) = self.cache.entry(user_id).await
178            && entry.loaded_at.elapsed() < self.cache.config.fresh_ttl
179        {
180            return Ok(BillingSnapshot {
181                status: entry.status,
182                source: SnapshotSource::Cache,
183                degraded: false,
184            });
185        }
186        let flight = self.cache.flight(user_id).await;
187        let _guard = flight.lock().await;
188        if let Some(entry) = self.cache.entry(user_id).await
189            && entry.loaded_at.elapsed() < self.cache.config.fresh_ttl
190        {
191            return Ok(BillingSnapshot {
192                status: entry.status,
193                source: SnapshotSource::Cache,
194                degraded: false,
195            });
196        }
197        match self.client.status(user_id).await {
198            Ok(status) => {
199                self.cache.put(user_id, status.clone()).await;
200                Ok(BillingSnapshot {
201                    status,
202                    source: SnapshotSource::Fresh,
203                    degraded: false,
204                })
205            }
206            Err(error) => match self.cache.config.failure_mode {
207                FailureMode::FailClosed => Err(error),
208                FailureMode::UseStale => {
209                    if let Some(entry) = self
210                        .cache
211                        .entry(user_id)
212                        .await
213                        .filter(|entry| entry.loaded_at.elapsed() < self.cache.config.stale_ttl)
214                    {
215                        Ok(BillingSnapshot {
216                            status: entry.status,
217                            source: SnapshotSource::Stale,
218                            degraded: true,
219                        })
220                    } else {
221                        Err(error)
222                    }
223                }
224                FailureMode::FreeTier => Ok(BillingSnapshot {
225                    status: BillingStatus::free_fallback(user_id),
226                    source: SnapshotSource::FreeFallback,
227                    degraded: true,
228                }),
229            },
230        }
231    }
232}
233
234#[async_trait]
235impl BillingProvider for CachedBillingClient {
236    async fn billing_snapshot(&self, user_id: &str) -> SdkResult<BillingSnapshot> {
237        self.load(user_id).await
238    }
239}
240
241#[cfg(test)]
242mod tests {
243    use super::*;
244    #[test]
245    fn defaults_bound_memory_and_staleness() {
246        let value = BillingCacheConfig::default();
247        assert!(value.max_entries > 0);
248        assert!(value.stale_ttl > value.fresh_ttl);
249    }
250}