Skip to main content

mytheclipse_queue/
rate_limited.rs

1//! Rate-limited queue wrapper.
2//!
3//! [`RateLimitedQueue`] wraps any [`Queue`] implementation and applies a
4//! token-bucket rate limiter before enqueuing. If the bucket is empty the
5//! enqueue is rejected with [`RateLimitQueueError::RateLimited`] instead of
6//! blocking.
7
8use std::sync::Arc;
9use std::time::Duration;
10
11use tokio::sync::Mutex;
12use tokio::time::Instant;
13
14use crate::error::QueueError;
15use crate::traits::Queue;
16use async_trait::async_trait;
17
18/// Error returned by [`RateLimitedQueue::enqueue`].
19#[derive(Debug)]
20pub enum RateLimitQueueError {
21    RateLimited,
22    Other(QueueError),
23}
24
25impl std::fmt::Display for RateLimitQueueError {
26    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
27        match self {
28            Self::RateLimited => write!(f, "rate limited: capacity exhausted"),
29            Self::Other(e) => write!(f, "queue error: {e}"),
30        }
31    }
32}
33
34impl std::error::Error for RateLimitQueueError {}
35
36impl From<QueueError> for RateLimitQueueError {
37    fn from(e: QueueError) -> Self {
38        Self::Other(e)
39    }
40}
41
42impl From<RateLimitQueueError> for QueueError {
43    fn from(e: RateLimitQueueError) -> Self {
44        match e {
45            RateLimitQueueError::RateLimited => Self::RateLimit("capacity exhausted".into()),
46            RateLimitQueueError::Other(e) => e,
47        }
48    }
49}
50
51/// Token-bucket rate limiter (no extra deps beyond tokio).
52struct TokenBucket {
53    /// Maximum burst capacity.
54    capacity: u32,
55    /// Current tokens (float for fractional refill).
56    tokens: f64,
57    /// Refill rate (tokens per second).
58    rate: f64,
59    /// Last refill timestamp.
60    last: Instant,
61}
62
63impl TokenBucket {
64    fn new(rate_per_sec: f64, burst: u32) -> Self {
65        Self {
66            capacity: burst.max(1),
67            tokens: burst as f64,
68            rate: rate_per_sec.max(0.0),
69            last: Instant::now(),
70        }
71    }
72
73    /// Attempts to consume one token. Returns true on success.
74    fn try_consume(&mut self) -> bool {
75        let now = Instant::now();
76        let elapsed = now.saturating_duration_since(self.last).as_secs_f64();
77        self.tokens = (self.tokens + elapsed * self.rate).min(self.capacity as f64);
78        self.last = now;
79        if self.tokens >= 1.0 {
80            self.tokens -= 1.0;
81            true
82        } else {
83            false
84        }
85    }
86}
87
88/// A queue decorator that enforces a rate limit on enqueue.
89pub struct RateLimitedQueue<Q: ?Sized> {
90    inner: Arc<Q>,
91    bucket: Arc<Mutex<TokenBucket>>,
92}
93
94impl<Q: Queue + 'static> RateLimitedQueue<Q> {
95    /// Creates a new rate-limited wrapper around `inner`.
96    pub fn new(inner: Q, rate_per_sec: f64, burst: u32) -> Self {
97        Self {
98            inner: Arc::new(inner),
99            bucket: Arc::new(Mutex::new(TokenBucket::new(rate_per_sec, burst))),
100        }
101    }
102}
103
104#[async_trait]
105impl<Q: Queue + ?Sized> Queue for RateLimitedQueue<Q> {
106    async fn enqueue(&self, topic: &str, payload: Vec<u8>) -> Result<(), QueueError> {
107        let mut b = self.bucket.lock().await;
108        if !b.try_consume() {
109            return Err(RateLimitQueueError::RateLimited.into());
110        }
111        self.inner.enqueue(topic, payload).await
112    }
113
114    async fn dequeue(
115        &self,
116        topic: &str,
117        timeout: Duration,
118    ) -> Result<Option<crate::job::Job>, QueueError> {
119        self.inner.dequeue(topic, timeout).await
120    }
121
122    async fn ack(&self, job: &crate::job::Job) -> Result<(), crate::error::JobError> {
123        self.inner.ack(job).await
124    }
125
126    async fn nack(
127        &self,
128        job: &crate::job::Job,
129        requeue: bool,
130    ) -> Result<(), crate::error::JobError> {
131        self.inner.nack(job, requeue).await
132    }
133
134    async fn dlq_move(&self, topic: &str, job: crate::job::Job) -> Result<(), QueueError> {
135        self.inner.dlq_move(topic, job).await
136    }
137
138    async fn len(&self, topic: &str) -> Result<u64, QueueError> {
139        self.inner.len(topic).await
140    }
141}
142
143#[cfg(test)]
144mod tests {
145    use super::*;
146    use crate::in_memory::InMemoryQueue;
147
148    #[tokio::test]
149    async fn allows_enqueue_within_rate() {
150        let inner = InMemoryQueue::new();
151        let rl = RateLimitedQueue::new(inner, 100.0, 10);
152        assert!(rl.enqueue("t", b"x".to_vec()).await.is_ok());
153    }
154
155    #[tokio::test]
156    async fn rejects_when_bucket_empty() {
157        let inner = InMemoryQueue::new();
158        let rl = RateLimitedQueue::new(inner, 0.0, 1); // 0 tokens/sec, 1 burst
159                                                       // consume the single burst token
160        let _ = rl.enqueue("t", b"x".to_vec()).await;
161        // next should be rate limited (no refill)
162        let result = rl.enqueue("t", b"y".to_vec()).await;
163        assert!(matches!(result, Err(QueueError::RateLimit(_))));
164    }
165}