use std::sync::Arc;
use tokio::sync::Semaphore as TokioSemaphore;
use tokio::time::{interval, Duration as TokioDuration};
pub struct RateLimiter {
permits: Arc<TokioSemaphore>,
capacity: usize,
rps: u32,
_shutdown: tokio_util::sync::CancellationToken,
}
impl std::fmt::Debug for RateLimiter {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("RateLimiter")
.field("capacity", &self.capacity)
.field("rps", &self.rps)
.finish_non_exhaustive()
}
}
pub(crate) fn compute_refill_permits(
current_rps: u32,
elapsed: std::time::Duration,
available: usize,
capacity: usize,
fractional_permits: f64,
) -> (usize, f64) {
if current_rps == 0 || available >= capacity {
return (0, 0.0);
}
#[allow(clippy::cast_precision_loss)]
let permits_to_add_f64 = f64::from(current_rps) * elapsed.as_secs_f64() + fractional_permits;
#[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
let whole_permits = permits_to_add_f64.floor() as usize;
let permits_to_restore = capacity.saturating_sub(available);
let permits_to_add = whole_permits.min(permits_to_restore);
let new_fractional = if permits_to_add == permits_to_restore {
0.0
} else {
#[allow(clippy::cast_precision_loss)]
{
permits_to_add_f64 - whole_permits as f64
}
};
(permits_to_add, new_fractional)
}
impl RateLimiter {
pub async fn acquire(&self) {
match self.permits.acquire().await {
Ok(permit) => {
permit.forget();
}
Err(_) => {
log::warn!("Rate limiter semaphore closed, skipping throttle");
}
}
}
#[must_use]
pub fn current_rps(&self) -> u32 {
self.rps
}
}
#[must_use]
pub fn init_rate_limiter(
rps: u32,
burst: usize,
) -> Option<(Arc<RateLimiter>, tokio_util::sync::CancellationToken)> {
if rps == 0 {
return None;
}
let capacity = burst;
let shutdown = tokio_util::sync::CancellationToken::new();
let shutdown_clone = shutdown.clone();
let limiter = Arc::new(RateLimiter {
permits: Arc::new(TokioSemaphore::new(capacity)),
capacity,
rps,
_shutdown: shutdown_clone.clone(),
});
let permits = limiter.permits.clone();
let mut ticker = interval(TokioDuration::from_millis(100));
tokio::spawn(async move {
let mut last_time = tokio::time::Instant::now();
let mut fractional_permits = 0.0f64; loop {
tokio::select! {
_ = ticker.tick() => {
let now = tokio::time::Instant::now();
let elapsed = now.duration_since(last_time);
if rps > 0 {
let available = permits.available_permits();
let (permits_to_add, new_fractional_permits) = compute_refill_permits(
rps,
elapsed,
available,
capacity,
fractional_permits,
);
fractional_permits = new_fractional_permits;
if permits_to_add > 0 {
permits.add_permits(permits_to_add);
}
}
last_time = now;
}
() = shutdown_clone.cancelled() => {
log::debug!("Rate limiter background task shutting down");
break;
}
}
}
});
Some((limiter, shutdown))
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::Arc;
use std::time::Duration;
use tokio::time::timeout;
#[test]
fn test_init_rate_limiter_disabled() {
let result = init_rate_limiter(0, 10);
assert!(
result.is_none(),
"Rate limiter should be disabled when RPS is 0"
);
}
#[tokio::test]
async fn test_init_rate_limiter_enabled() {
let result = init_rate_limiter(10, 20);
assert!(
result.is_some(),
"Rate limiter should be enabled when RPS > 0"
);
let (limiter, _shutdown) = result.unwrap();
tokio::time::sleep(Duration::from_millis(10)).await;
assert_eq!(limiter.current_rps(), 10);
}
#[tokio::test(start_paused = true)]
async fn test_rate_limiter_acquire_consumes_burst_capacity() {
let (limiter, _shutdown) = init_rate_limiter(1, 2).unwrap();
limiter.acquire().await;
limiter.acquire().await;
let blocked = timeout(Duration::from_millis(1), limiter.acquire()).await;
assert!(blocked.is_err(), "third acquire should block until refill");
}
#[tokio::test(start_paused = true)]
async fn test_rate_limiter_token_replenishment_unblocks_waiter() {
let (limiter, _shutdown) = init_rate_limiter(10, 1).unwrap();
limiter.acquire().await;
let acquire = tokio::spawn({
let limiter = Arc::clone(&limiter);
async move { limiter.acquire().await }
});
tokio::time::advance(Duration::from_millis(90)).await;
assert!(
!acquire.is_finished(),
"waiter should still be blocked before refill"
);
tokio::time::advance(Duration::from_millis(20)).await;
acquire.await.expect("waiter task should complete");
}
#[tokio::test(start_paused = true)]
async fn test_rate_limiter_concurrent_acquire_with_cancellation_does_not_deadlock() {
let (limiter, _shutdown) = init_rate_limiter(20, 4).unwrap();
for _ in 0..4 {
limiter.acquire().await;
}
let mut waiters: Vec<tokio::task::JoinHandle<()>> = (0..8)
.map(|_| {
let limiter = Arc::clone(&limiter);
tokio::spawn(async move {
limiter.acquire().await;
})
})
.collect();
tokio::task::yield_now().await;
for w in waiters.drain(..4) {
w.abort();
let _ = w.await;
}
tokio::time::advance(Duration::from_millis(250)).await;
let join_all = futures::future::join_all(waiters);
timeout(Duration::from_secs(2), join_all)
.await
.expect("surviving acquirers should complete after refill")
.into_iter()
.for_each(|res| res.expect("waiter task panicked"));
}
#[tokio::test]
async fn test_rate_limiter_shutdown() {
let (limiter, shutdown) = init_rate_limiter(10, 5).unwrap();
shutdown.cancel();
tokio::time::sleep(Duration::from_millis(50)).await;
let _ = timeout(Duration::from_millis(10), limiter.acquire()).await;
}
#[tokio::test(start_paused = true)]
async fn test_rate_limiter_burst_capacity_is_capped() {
let (permits_to_add, fractional) =
compute_refill_permits(1, Duration::from_secs(5), 2, 3, 0.0);
assert_eq!(
permits_to_add, 1,
"bucket should only refill the missing slot"
);
assert!(
fractional.abs() < f64::EPSILON,
"overflow beyond burst capacity should be discarded"
);
}
#[tokio::test]
async fn test_rate_limiter_multiple_instances() {
let (limiter1, _shutdown1) = init_rate_limiter(10, 5).unwrap();
let (limiter2, _shutdown2) = init_rate_limiter(20, 10).unwrap();
tokio::time::sleep(Duration::from_millis(10)).await;
assert_eq!(limiter1.current_rps(), 10);
assert_eq!(limiter2.current_rps(), 20);
}
#[test]
fn test_compute_refill_permits_accumulates_fractional_tokens() {
let (permits_to_add, fractional) =
compute_refill_permits(3, Duration::from_millis(100), 0, 5, 0.0);
assert_eq!(permits_to_add, 0);
assert!(fractional > 0.29 && fractional < 0.31);
let (permits_to_add, fractional) =
compute_refill_permits(3, Duration::from_millis(300), 0, 5, fractional);
assert_eq!(permits_to_add, 1);
assert!(fractional > 0.19 && fractional < 0.21);
}
}