Skip to main content

hyprstream_core/services/oauth/
cimd_cache.rs

1//! Client ID Metadata Document cache.
2//!
3//! Spec: draft-ietf-oauth-client-id-metadata-document-00 §6.2 — servers
4//! SHOULD cache metadata respecting HTTP cache headers. MCP 2025-11-25
5//! authorization spec (§ Client ID Metadata Documents → Authorization
6//! Servers) lifts this requirement verbatim.
7//!
8//! Design:
9//!
10//! This cache is a thin OAuth-specific wrapper over the shared
11//! [`TtlCache`](hyprstream_util::TtlCache) substrate (extracted in
12//! #524). `TtlCache` provides the eviction machinery — per-entry TTL,
13//! lazy version-tagged deletion on re-insert, bounded inline reaping and
14//! a capacity bound (next-to-expire victim). This wrapper adds:
15//!
16//! * **TTL clamping**: HTTP `Cache-Control: max-age` / `Expires` is
17//!   clamped to `[min_ttl, max_ttl]` (default `[5min, 24h]`) before the
18//!   entry is inserted. Defends against thundering-herd refetch (`max-age=0`)
19//!   and unbounded staleness.
20//! * **`RegisteredClient` keying** by `client_id` URL.
21//!
22//! The public API remains `async` for call-site compatibility; the
23//! underlying `TtlCache` is synchronous (operations are short, in-memory
24//! and never span an `.await`).
25
26use std::time::Duration;
27
28use hyprstream_util::TtlCache;
29
30use super::state::RegisteredClient;
31
32/// Cache configuration. Defaults documented per field.
33#[derive(Debug, Clone)]
34pub struct CimdCacheConfig {
35    /// Minimum TTL applied to any cached entry, regardless of upstream
36    /// cache headers. Defends against thundering-herd refetch when an
37    /// upstream returns `max-age=0`.
38    pub min_ttl: Duration,
39    /// Maximum TTL applied to any cached entry. Bounds the staleness of
40    /// CIMD metadata when an upstream returns aggressive Cache-Control.
41    pub max_ttl: Duration,
42    /// Maximum number of cached entries. Defends against DoS amplification
43    /// where an attacker forces the AS to register unique client_id URLs.
44    pub max_entries: usize,
45    /// Maximum number of heap pops per inline reap. Bounds tail latency
46    /// at cache access while still amortizing cleanup.
47    pub reap_budget: usize,
48}
49
50impl Default for CimdCacheConfig {
51    fn default() -> Self {
52        Self {
53            min_ttl: Duration::from_secs(300),    // 5 min
54            max_ttl: Duration::from_secs(86_400), // 24 h
55            max_entries: 10_000,
56            reap_budget: 16,
57        }
58    }
59}
60
61/// CIMD metadata cache. Thread-safe; cheap to share via `Arc`.
62pub struct CimdCache {
63    cache: TtlCache<String, RegisteredClient>,
64    config: CimdCacheConfig,
65}
66
67impl CimdCache {
68    #[must_use]
69    pub fn new(config: CimdCacheConfig) -> Self {
70        let cache = TtlCache::new(config.max_entries, config.reap_budget);
71        Self { cache, config }
72    }
73
74    /// Compute a clamped TTL from an optional upstream `max-age` value.
75    /// `None` (no cache header) yields `min_ttl`.
76    #[must_use]
77    pub fn clamp_ttl(&self, http_max_age: Option<Duration>) -> Duration {
78        let ttl = http_max_age.unwrap_or(self.config.min_ttl);
79        ttl.clamp(self.config.min_ttl, self.config.max_ttl)
80    }
81
82    /// Look up a cached CIMD client by its `client_id` URL.
83    ///
84    /// Performs a bounded inline reap before the lookup. Returns `None`
85    /// if absent or expired.
86    pub async fn get(&self, client_id: &str) -> Option<RegisteredClient> {
87        self.cache.get(client_id)
88    }
89
90    /// Insert (or replace) a cached CIMD client with the given TTL.
91    ///
92    /// If the cache is at capacity, the next-to-expire entry is evicted
93    /// first. Re-inserting an existing `client_id` refreshes it (bumps
94    /// the version tag); the prior heap node is reaped lazily.
95    pub async fn insert(&self, client: RegisteredClient, ttl: Duration) {
96        let client_id = client.client_id.clone();
97        self.cache.insert(client_id, client, ttl);
98    }
99
100    /// Current cache size (for metrics / tests).
101    pub async fn len(&self) -> usize {
102        self.cache.len()
103    }
104
105    /// True when no entries are cached. Mostly for tests.
106    pub async fn is_empty(&self) -> bool {
107        self.cache.is_empty()
108    }
109}
110
111#[cfg(test)]
112#[allow(clippy::unwrap_used, clippy::expect_used)]
113mod tests {
114    use super::*;
115    use std::time::Instant;
116
117    fn make_client(id: &str) -> RegisteredClient {
118        RegisteredClient {
119            client_id: id.to_owned(),
120            redirect_uris: vec!["http://localhost/cb".to_owned()],
121            client_name: None,
122            client_uri: None,
123            logo_uri: None,
124            grant_types: vec![],
125            response_types: vec![],
126            token_endpoint_auth_method: None,
127            jwks: None,
128            jwks_uri: None,
129            hyprstream_node_did: None,
130            scope: None,
131            dpop_bound_access_tokens: None,
132            is_cimd: true,
133            registered_at: Instant::now(),
134        }
135    }
136
137    #[tokio::test]
138    async fn insert_and_get_roundtrip() {
139        let cache = CimdCache::new(CimdCacheConfig::default());
140        cache
141            .insert(make_client("https://a.test/c"), Duration::from_secs(60))
142            .await;
143        let got = cache.get("https://a.test/c").await;
144        assert!(got.is_some());
145        assert_eq!(got.unwrap().client_id, "https://a.test/c");
146    }
147
148    #[tokio::test]
149    async fn expired_entry_returns_none() {
150        let cache = CimdCache::new(CimdCacheConfig::default());
151        cache
152            .insert(make_client("https://a.test/c"), Duration::from_millis(10))
153            .await;
154        tokio::time::sleep(Duration::from_millis(50)).await;
155        assert!(cache.get("https://a.test/c").await.is_none());
156    }
157
158    #[tokio::test]
159    async fn ttl_is_clamped_to_min_and_max() {
160        let cache = CimdCache::new(CimdCacheConfig {
161            min_ttl: Duration::from_secs(60),
162            max_ttl: Duration::from_secs(3600),
163            ..CimdCacheConfig::default()
164        });
165        // None → min_ttl
166        assert_eq!(cache.clamp_ttl(None), Duration::from_secs(60));
167        // Below min → min
168        assert_eq!(
169            cache.clamp_ttl(Some(Duration::from_secs(10))),
170            Duration::from_secs(60)
171        );
172        // Within range → as-is
173        assert_eq!(
174            cache.clamp_ttl(Some(Duration::from_secs(600))),
175            Duration::from_secs(600)
176        );
177        // Above max → max
178        assert_eq!(
179            cache.clamp_ttl(Some(Duration::from_secs(99_999))),
180            Duration::from_secs(3600)
181        );
182    }
183
184    #[tokio::test]
185    async fn reinsert_does_not_leak_heap_after_reap() {
186        let cache = CimdCache::new(CimdCacheConfig {
187            reap_budget: 32,
188            ..CimdCacheConfig::default()
189        });
190        // Insert 5 versions of the same key, each with a short TTL.
191        for _ in 0..5 {
192            cache
193                .insert(make_client("https://a.test/c"), Duration::from_millis(10))
194                .await;
195        }
196        // After expiry + reap, only one map entry exists (or zero), and
197        // the heap should not grow without bound: subsequent inserts
198        // should still resolve.
199        tokio::time::sleep(Duration::from_millis(50)).await;
200        cache
201            .insert(make_client("https://a.test/c"), Duration::from_secs(60))
202            .await;
203        assert_eq!(cache.len().await, 1);
204        assert!(cache.get("https://a.test/c").await.is_some());
205    }
206
207    #[tokio::test]
208    async fn evict_one_terminates_under_stale_heap_pressure() {
209        // Repeatedly re-insert the same key with bumped versions to
210        // accumulate stale heap nodes, then trigger evict_one by
211        // overfilling. Must terminate (not infinite-loop) and must
212        // actually evict the right entry.
213        let cache = CimdCache::new(CimdCacheConfig {
214            max_entries: 2,
215            reap_budget: 4, // small budget keeps reap from clearing the stale nodes
216            min_ttl: Duration::from_secs(60),
217            max_ttl: Duration::from_secs(3600),
218        });
219
220        // 50 stale heap nodes for client A, all "live" entry version.
221        for _ in 0..50 {
222            cache
223                .insert(make_client("https://a.test/c"), Duration::from_secs(120))
224                .await;
225        }
226        // One entry for client B at capacity.
227        cache
228            .insert(make_client("https://b.test/c"), Duration::from_secs(60))
229            .await;
230        assert_eq!(cache.len().await, 2, "A + B at capacity");
231
232        // Insert C — triggers evict_one which must walk past stale A
233        // heap nodes to find a fresh victim and terminate.
234        cache
235            .insert(make_client("https://c.test/c"), Duration::from_secs(180))
236            .await;
237        assert_eq!(cache.len().await, 2, "still 2 after eviction");
238        // B had the shortest TTL among current map entries, so should be evicted.
239        assert!(
240            cache.get("https://b.test/c").await.is_none(),
241            "B (shortest TTL) should have been the victim"
242        );
243        assert!(
244            cache.get("https://a.test/c").await.is_some(),
245            "A still present"
246        );
247        assert!(
248            cache.get("https://c.test/c").await.is_some(),
249            "C just inserted"
250        );
251    }
252
253    #[tokio::test]
254    async fn capacity_bound_evicts_next_to_expire() {
255        let cache = CimdCache::new(CimdCacheConfig {
256            max_entries: 2,
257            ..CimdCacheConfig::default()
258        });
259        cache
260            .insert(make_client("https://a.test/c1"), Duration::from_secs(10))
261            .await;
262        cache
263            .insert(make_client("https://b.test/c2"), Duration::from_secs(60))
264            .await;
265        // Capacity reached. Inserting a 3rd evicts the next-to-expire (c1).
266        cache
267            .insert(make_client("https://c.test/c3"), Duration::from_secs(30))
268            .await;
269        assert_eq!(cache.len().await, 2);
270        assert!(cache.get("https://a.test/c1").await.is_none());
271        assert!(cache.get("https://b.test/c2").await.is_some());
272        assert!(cache.get("https://c.test/c3").await.is_some());
273    }
274}