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