cloudiful-rate-limiter 0.1.0

Reusable async resource throttling with local and Valkey-backed backends.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

//! Async resource throttling by explicit key.
//!
//! This crate decides whether a keyed access is allowed now and how long the
//! caller must wait otherwise. It does not schedule jobs, retry requests, or
//! infer business scopes.

mod error;
mod local;
mod policy;
#[cfg(feature = "valkey")]
mod valkey;
#[cfg(feature = "valkey")]
mod valkey_scripts;

#[cfg(feature = "valkey")]
pub use error::ValkeyError;
pub use error::{InvalidPolicyError, InvalidPolicyKind, RateLimitError, RateLimitErrorKind};
pub use local::LocalRateLimiter;
pub use policy::RateLimitPolicy;
#[cfg(feature = "valkey")]
pub use valkey::ValkeyRateLimiter;

use async_trait::async_trait;
use std::time::Duration;

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AcquireResult {
    pub key: String,
    pub waited: Duration,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum TryAcquireResult {
    Acquired,
    Limited { wait_duration: Duration },
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PeekResult {
    pub allowed: bool,
    pub wait_duration: Duration,
}

#[async_trait]
pub trait RateLimiter: Send + Sync {
    async fn acquire(&self, key: &str) -> Result<AcquireResult, RateLimitError>;
    async fn try_acquire(&self, key: &str) -> Result<TryAcquireResult, RateLimitError>;
    async fn peek(&self, key: &str) -> Result<PeekResult, RateLimitError>;
}