Skip to main content

auth_framework/utils/
rate_limit.rs

1//! Rate limiting utilities for the AuthFramework.
2
3use crate::errors::{AuthError, Result};
4use std::collections::HashMap;
5use std::sync::{Arc, Mutex};
6use std::time::{Duration, Instant};
7
8/// Rate limiter implementation.
9///
10/// # Example
11/// ```rust
12/// use auth_framework::utils::rate_limit::RateLimiter;
13/// use std::time::Duration;
14/// let limiter = RateLimiter::new(5, Duration::from_secs(60));
15/// assert!(limiter.is_allowed("client-1"));
16/// ```
17#[derive(Clone)]
18pub struct RateLimiter {
19    max_requests: u32,
20    window: Duration,
21    requests: Arc<Mutex<HashMap<String, Vec<Instant>>>>,
22    now: Arc<dyn Fn() -> Instant + Send + Sync>,
23}
24
25impl std::fmt::Debug for RateLimiter {
26    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
27        f.debug_struct("RateLimiter")
28            .field("max_requests", &self.max_requests)
29            .field("window", &self.window)
30            .field("requests", &crate::utils::redact::redacted(&self.requests))
31            .finish_non_exhaustive()
32    }
33}
34
35impl RateLimiter {
36    /// Create a new rate limiter.
37    ///
38    /// # Example
39    /// ```rust
40    /// use auth_framework::utils::rate_limit::RateLimiter;
41    /// use std::time::Duration;
42    /// let limiter = RateLimiter::new(100, Duration::from_secs(60));
43    /// ```
44    pub fn new(max_requests: u32, window: Duration) -> Self {
45        Self::with_clock(max_requests, window, Instant::now)
46    }
47
48    /// Create a new rate limiter with an injectable clock.
49    ///
50    /// This is a genuine testing seam, not a workaround: it lets callers
51    /// (this crate's own tests, or a consumer's) assert window-expiry
52    /// behavior by advancing a controlled clock instead of racing real
53    /// wall-clock sleeps against unpredictable scheduling or
54    /// instrumentation overhead.
55    ///
56    /// # Example
57    /// ```rust
58    /// use auth_framework::utils::rate_limit::RateLimiter;
59    /// use std::time::{Duration, Instant};
60    /// let limiter = RateLimiter::with_clock(100, Duration::from_secs(60), Instant::now);
61    /// ```
62    pub fn with_clock(
63        max_requests: u32,
64        window: Duration,
65        now: impl Fn() -> Instant + Send + Sync + 'static,
66    ) -> Self {
67        Self {
68            max_requests,
69            window,
70            requests: Arc::new(Mutex::new(HashMap::new())),
71            now: Arc::new(now),
72        }
73    }
74
75    /// Check if a request is allowed for the given key.
76    ///
77    /// # Example
78    /// ```rust
79    /// use auth_framework::utils::rate_limit::RateLimiter;
80    /// use std::time::Duration;
81    /// let limiter = RateLimiter::new(2, Duration::from_secs(60));
82    /// assert_eq!(limiter.check_rate_limit("k").unwrap(), true);
83    /// assert_eq!(limiter.check_rate_limit("k").unwrap(), true);
84    /// assert_eq!(limiter.check_rate_limit("k").unwrap(), false);
85    /// ```
86    pub fn check_rate_limit(&self, key: &str) -> Result<bool> {
87        let mut requests = self
88            .requests
89            .lock()
90            .map_err(|_| AuthError::internal("Failed to acquire rate limiter lock".to_string()))?;
91
92        let now = (self.now)();
93        let entry = requests.entry(key.to_string()).or_insert_with(Vec::new);
94
95        // Remove expired requests
96        entry.retain(|&request_time| now.duration_since(request_time) < self.window);
97
98        if entry.len() >= self.max_requests as usize {
99            return Ok(false); // Rate limit exceeded
100        }
101
102        // Add current request
103        entry.push(now);
104        Ok(true)
105    }
106
107    /// Alias for check_rate_limit for compatibility.
108    ///
109    /// # Example
110    /// ```rust
111    /// use auth_framework::utils::rate_limit::RateLimiter;
112    /// use std::time::Duration;
113    /// let limiter = RateLimiter::new(1, Duration::from_secs(60));
114    /// assert!(limiter.is_allowed("k"));
115    /// assert!(!limiter.is_allowed("k"));
116    /// ```
117    pub fn is_allowed(&self, key: &str) -> bool {
118        self.check_rate_limit(key).unwrap_or(false)
119    }
120
121    /// Alias for get_remaining_requests for compatibility.
122    ///
123    /// # Example
124    /// ```rust
125    /// use auth_framework::utils::rate_limit::RateLimiter;
126    /// use std::time::Duration;
127    /// let limiter = RateLimiter::new(5, Duration::from_secs(60));
128    /// assert_eq!(limiter.remaining_requests("k").unwrap(), 5);
129    /// ```
130    pub fn remaining_requests(&self, key: &str) -> Result<u32> {
131        self.get_remaining_requests(key)
132    }
133
134    /// Get the number of requests for a key.
135    ///
136    /// # Example
137    /// ```rust
138    /// use auth_framework::utils::rate_limit::RateLimiter;
139    /// use std::time::Duration;
140    /// let limiter = RateLimiter::new(10, Duration::from_secs(60));
141    /// limiter.is_allowed("k");
142    /// assert_eq!(limiter.get_request_count("k").unwrap(), 1);
143    /// ```
144    pub fn get_request_count(&self, key: &str) -> Result<usize> {
145        let requests = self
146            .requests
147            .lock()
148            .map_err(|_| AuthError::internal("Failed to acquire rate limiter lock".to_string()))?;
149
150        let now = (self.now)();
151        if let Some(entry) = requests.get(key) {
152            let valid_requests = entry
153                .iter()
154                .filter(|&&request_time| now.duration_since(request_time) < self.window)
155                .count();
156            Ok(valid_requests)
157        } else {
158            Ok(0)
159        }
160    }
161
162    /// Clean up expired entries.
163    ///
164    /// # Example
165    /// ```rust
166    /// use auth_framework::utils::rate_limit::RateLimiter;
167    /// use std::time::Duration;
168    /// let limiter = RateLimiter::new(10, Duration::from_secs(60));
169    /// let removed = limiter.cleanup().unwrap();
170    /// assert_eq!(removed, 0);
171    /// ```
172    pub fn cleanup(&self) -> Result<usize> {
173        let mut requests = self
174            .requests
175            .lock()
176            .map_err(|_| AuthError::internal("Failed to acquire rate limiter lock".to_string()))?;
177
178        let now = (self.now)();
179        let mut removed_count = 0;
180
181        requests.retain(|_, entry| {
182            entry.retain(|&request_time| now.duration_since(request_time) < self.window);
183            if entry.is_empty() {
184                removed_count += 1;
185                false
186            } else {
187                true
188            }
189        });
190
191        Ok(removed_count)
192    }
193
194    /// Reset rate limit for a specific key.
195    ///
196    /// # Example
197    /// ```rust
198    /// use auth_framework::utils::rate_limit::RateLimiter;
199    /// use std::time::Duration;
200    /// let limiter = RateLimiter::new(1, Duration::from_secs(60));
201    /// limiter.is_allowed("k");
202    /// limiter.reset("k").unwrap();
203    /// assert!(limiter.is_allowed("k"));
204    /// ```
205    pub fn reset(&self, key: &str) -> Result<()> {
206        let mut requests = self
207            .requests
208            .lock()
209            .map_err(|_| AuthError::internal("Failed to acquire rate limiter lock".to_string()))?;
210
211        requests.remove(key);
212        Ok(())
213    }
214
215    /// Get remaining requests for a key.
216    ///
217    /// # Example
218    /// ```rust
219    /// use auth_framework::utils::rate_limit::RateLimiter;
220    /// use std::time::Duration;
221    /// let limiter = RateLimiter::new(5, Duration::from_secs(60));
222    /// limiter.is_allowed("k");
223    /// assert_eq!(limiter.get_remaining_requests("k").unwrap(), 4);
224    /// ```
225    pub fn get_remaining_requests(&self, key: &str) -> Result<u32> {
226        let count = self.get_request_count(key)?;
227        Ok(self.max_requests.saturating_sub(count as u32))
228    }
229}
230
231#[cfg(test)]
232mod tests {
233    use super::*;
234    use std::thread;
235
236    #[test]
237    fn test_rate_limiter() {
238        let limiter = RateLimiter::new(3, Duration::from_secs(1));
239        let key = "test_key";
240
241        // First 3 requests should be allowed
242        assert!(limiter.check_rate_limit(key).unwrap());
243        assert!(limiter.check_rate_limit(key).unwrap());
244        assert!(limiter.check_rate_limit(key).unwrap());
245
246        // 4th request should be denied
247        assert!(!limiter.check_rate_limit(key).unwrap());
248
249        // Wait for window to expire
250        thread::sleep(Duration::from_millis(1100));
251
252        // Should be allowed again
253        assert!(limiter.check_rate_limit(key).unwrap());
254    }
255
256    #[test]
257    fn test_cleanup() {
258        let limiter = RateLimiter::new(10, Duration::from_millis(100));
259
260        limiter.check_rate_limit("key1").unwrap();
261        limiter.check_rate_limit("key2").unwrap();
262
263        thread::sleep(Duration::from_millis(150));
264
265        let removed = limiter.cleanup().unwrap();
266        assert_eq!(removed, 2);
267    }
268
269    #[test]
270    fn test_zero_max_requests_denies_all() {
271        let limiter = RateLimiter::new(0, Duration::from_secs(60));
272        assert!(!limiter.check_rate_limit("key").unwrap());
273        assert!(!limiter.is_allowed("key"));
274    }
275
276    #[test]
277    fn test_single_request_limit() {
278        let limiter = RateLimiter::new(1, Duration::from_secs(60));
279        assert!(limiter.check_rate_limit("key").unwrap());
280        assert!(!limiter.check_rate_limit("key").unwrap());
281    }
282
283    #[test]
284    fn test_independent_keys() {
285        let limiter = RateLimiter::new(1, Duration::from_secs(60));
286        assert!(limiter.check_rate_limit("key1").unwrap());
287        assert!(limiter.check_rate_limit("key2").unwrap());
288        // key1 is exhausted, key2 is exhausted
289        assert!(!limiter.check_rate_limit("key1").unwrap());
290        assert!(!limiter.check_rate_limit("key2").unwrap());
291    }
292
293    #[test]
294    fn test_empty_key() {
295        let limiter = RateLimiter::new(2, Duration::from_secs(60));
296        assert!(limiter.check_rate_limit("").unwrap());
297        assert!(limiter.check_rate_limit("").unwrap());
298        assert!(!limiter.check_rate_limit("").unwrap());
299    }
300
301    #[test]
302    fn test_remaining_requests_decrements() {
303        let limiter = RateLimiter::new(3, Duration::from_secs(60));
304        assert_eq!(limiter.get_remaining_requests("k").unwrap(), 3);
305        limiter.check_rate_limit("k").unwrap();
306        assert_eq!(limiter.get_remaining_requests("k").unwrap(), 2);
307        limiter.check_rate_limit("k").unwrap();
308        assert_eq!(limiter.get_remaining_requests("k").unwrap(), 1);
309        limiter.check_rate_limit("k").unwrap();
310        assert_eq!(limiter.get_remaining_requests("k").unwrap(), 0);
311    }
312
313    #[test]
314    fn test_remaining_requests_for_unknown_key() {
315        let limiter = RateLimiter::new(5, Duration::from_secs(60));
316        assert_eq!(limiter.get_remaining_requests("unknown").unwrap(), 5);
317    }
318
319    #[test]
320    fn test_get_request_count_unknown_key() {
321        let limiter = RateLimiter::new(5, Duration::from_secs(60));
322        assert_eq!(limiter.get_request_count("unknown").unwrap(), 0);
323    }
324
325    #[test]
326    fn test_reset_clears_count() {
327        let limiter = RateLimiter::new(2, Duration::from_secs(60));
328        limiter.check_rate_limit("k").unwrap();
329        limiter.check_rate_limit("k").unwrap();
330        assert!(!limiter.is_allowed("k"));
331
332        limiter.reset("k").unwrap();
333        assert!(limiter.is_allowed("k"));
334        assert_eq!(limiter.get_request_count("k").unwrap(), 1);
335    }
336
337    #[test]
338    fn test_reset_nonexistent_key_is_ok() {
339        let limiter = RateLimiter::new(5, Duration::from_secs(60));
340        assert!(limiter.reset("nonexistent").is_ok());
341    }
342
343    #[test]
344    fn test_cleanup_empty_limiter() {
345        let limiter = RateLimiter::new(5, Duration::from_secs(60));
346        assert_eq!(limiter.cleanup().unwrap(), 0);
347    }
348
349    #[test]
350    fn test_clone_shares_state() {
351        let limiter = RateLimiter::new(2, Duration::from_secs(60));
352        let limiter2 = limiter.clone();
353        limiter.check_rate_limit("k").unwrap();
354        // Clone should see the same request count
355        assert_eq!(limiter2.get_request_count("k").unwrap(), 1);
356    }
357
358    #[test]
359    fn test_concurrent_access() {
360        let limiter = RateLimiter::new(100, Duration::from_secs(60));
361        let mut handles = vec![];
362
363        for i in 0..10 {
364            let l = limiter.clone();
365            handles.push(thread::spawn(move || {
366                for _ in 0..10 {
367                    let _ = l.check_rate_limit(&format!("thread-{}", i));
368                }
369            }));
370        }
371
372        for h in handles {
373            h.join().unwrap();
374        }
375
376        // Each thread made 10 requests under its own key
377        for i in 0..10 {
378            assert_eq!(
379                limiter.get_request_count(&format!("thread-{}", i)).unwrap(),
380                10
381            );
382        }
383    }
384
385    #[test]
386    fn test_remaining_alias_matches() {
387        let limiter = RateLimiter::new(5, Duration::from_secs(60));
388        limiter.check_rate_limit("k").unwrap();
389        assert_eq!(
390            limiter.remaining_requests("k").unwrap(),
391            limiter.get_remaining_requests("k").unwrap()
392        );
393    }
394
395    #[test]
396    fn test_is_allowed_alias_matches() {
397        // is_allowed is an alias for check_rate_limit that returns false on error
398        let limiter = RateLimiter::new(2, Duration::from_secs(60));
399        // Both should return true for fresh key
400        assert!(limiter.is_allowed("a"));
401        assert!(limiter.check_rate_limit("b").unwrap());
402    }
403
404    #[test]
405    fn test_many_keys_cleanup() {
406        let limiter = RateLimiter::new(1, Duration::from_millis(50));
407        for i in 0..100 {
408            limiter.check_rate_limit(&format!("key-{}", i)).unwrap();
409        }
410        thread::sleep(Duration::from_millis(100));
411        let removed = limiter.cleanup().unwrap();
412        assert_eq!(removed, 100);
413    }
414}