rate_guard/

lib.rs

//! Rate-Guard: A flexible and type-safe rate limiting library for Rust.
//!
//! Rate-Guard provides a unified interface for multiple rate limiting algorithms
//! with Duration-based configuration, type-safe time handling, and comprehensive
//! error reporting. It's designed to integrate seamlessly with Rust's async
//! ecosystem while maintaining high performance through zero-cost abstractions.
//!
//! Key Features:
//! - Duration-Based Configuration: All timing parameters use std::time::Duration
//! - Multiple Algorithms: Token bucket, fixed window counter, sliding window counter, and approximate sliding window
//! - Time Source Abstraction: Pluggable time sources (mock, std::time, etc.)
//! - Precision Control: Compile-time precision selection for optimal performance
//! - Builder Pattern: Fluent configuration API with compile-time validation
//! - Zero-Cost Abstractions: High-level ergonomics without runtime overhead
//! - Comprehensive Testing: Built-in mock time source for deterministic testing
//!
//! 
//! # Feature Flags
//!
//! ## Time Sources (Optional)
//! - `std-time` - Standard library time source (recommended for production)
//! - `tokio-time` - Tokio time source (for async environments)
//!
//! ## Precision Types (Mutually Exclusive, defaults to u64)
//! - `tick-u64` (default) - 64-bit precision, suitable for most scenarios
//! - `tick-u128` - 128-bit precision, for extreme long-duration use cases
//!
//! ```toml
//! # Default configuration
//! rate-guard = "0.1.0"
//!
//! # Production recommended
//! rate-guard = { version = "0.1.0", features = ["std-time"] }
//!
//! # Special requirements: high precision
//! rate-guard = { version = "0.1.0", features = ["std-time", "tick-u128"] }
//! ```
//! 
//! 
//! # Quick Start
//!
//! ```rust
//! use rate_guard::{Nanos, MockTimeSource, RateLimit};
//! use rate_guard::limits::TokenBucketBuilder;
//! use std::time::Duration;
//!
//! // Create a token bucket using the builder pattern
//! let bucket = TokenBucketBuilder::builder()
//!     .capacity(100)
//!     .refill_amount(10)
//!     .refill_every(Duration::from_millis(100))
//!     .with_time(MockTimeSource::new())
//!     .with_precision::<Nanos>()
//!     .build()
//!     .unwrap();
//!
//! // Use the rate limiter
//! match bucket.try_acquire(50) {
//!     Ok(()) => println!("Request allowed"),
//!     Err(_) => println!("Rate limited"),
//! }
//! ```
//!
//! # Testing with Mock Time
//!
//! ```rust
//! use rate_guard::{Millis, MockTimeSource, RateLimit};
//! use rate_guard::limits::TokenBucketBuilder;
//! use std::time::Duration;
//!
//! let time_source = MockTimeSource::new();
//! let bucket = TokenBucketBuilder::builder()
//!     .capacity(50)
//!     .refill_amount(5)
//!     .refill_every(Duration::from_millis(200))
//!     .with_time(time_source.clone())
//!     .with_precision::<Millis>()
//!     .build()
//!     .unwrap();
//!
//! // Use all tokens
//! assert!(bucket.try_acquire(50).is_ok());
//! assert_eq!(bucket.capacity_remaining().unwrap(), 0);
//!
//! // Advance time to trigger refill
//! time_source.advance(Duration::from_millis(200));
//! assert_eq!(bucket.capacity_remaining().unwrap(), 5);
//! ```
//!
//! # All Rate Limiter Types
//!
//! ```rust
//! use rate_guard::{
//!     Millis, MockTimeSource, RateLimit
//! };
//! use rate_guard::limits::{
//!     TokenBucketBuilder, FixedWindowCounterBuilder,
//!     SlidingWindowCounterBuilder, ApproximateSlidingWindowBuilder
//! };
//! use std::time::Duration;
//!
//! let time_source = MockTimeSource::new();
//!
//! // Token Bucket - allows bursts
//! let token_bucket = TokenBucketBuilder::builder()
//!     .capacity(100)
//!     .refill_amount(10)
//!     .refill_every(Duration::from_millis(100))
//!     .with_time(time_source.clone())
//!     .with_precision::<Millis>()
//!     .build()
//!     .unwrap();
//!
//!
//! // Fixed Window Counter
//! let fixed_window = FixedWindowCounterBuilder::builder()
//!     .capacity(100)
//!     .window_duration(Duration::from_secs(60))
//!     .with_time(time_source.clone())
//!     .with_precision::<Millis>()
//!     .build()
//!     .unwrap();
//!
//! // Sliding Window Counter
//! let sliding_window = SlidingWindowCounterBuilder::builder()
//!     .capacity(100)
//!     .bucket_duration(Duration::from_secs(10))
//!     .bucket_count(6)
//!     .with_time(time_source.clone())
//!     .with_precision::<Millis>()
//!     .build()
//!     .unwrap();
//!
//! // Approximate Sliding Window
//! let approx_window = ApproximateSlidingWindowBuilder::builder()
//!     .capacity(100)
//!     .window_duration(Duration::from_secs(60))
//!     .with_time(time_source)
//!     .with_precision::<Millis>()
//!     .build()
//!     .unwrap();
//! ```

// Re-export core types
pub use rate_guard_core::types::Uint;

// Precision system
pub mod precision;
pub use precision::{Precision, Nanos, Micros, Millis, Secs};

// Time source abstraction
pub mod time_source;
pub use time_source::{TimeSource, MockTimeSource};
#[cfg(feature = "std-time")]
pub use time_source::StdTimeSource;

#[cfg(feature = "tokio-time")]
pub use time_source::TokioTimeSource;

// Error types with Duration-based retry timing and builder validation
pub mod error;
pub use error::{
    RateLimitError, RateLimitResult, BuildError, BuildResult,
};

// Rate limiter implementations
pub mod limits;
pub use limits::{
    RateLimit,
    TokenBucket, TokenBucketBuilder,
    FixedWindowCounter, FixedWindowCounterBuilder,
    SlidingWindowCounter, SlidingWindowCounterBuilder,
    ApproximateSlidingWindow, ApproximateSlidingWindowBuilder,
    // Backward compatibility aliases
    PrecisionFixedWindowCounter,
    PrecisionSlidingWindowCounter, 
    PrecisionApproximateSlidingWindow,
};

// Configuration types (keeping for backward compatibility)
pub mod types;
pub use types::*;


// Standard rate limiter type aliases for backward compatibility

/// Type alias for a fixed window counter with standard nanosecond precision.
pub type FixedWindowCounterNanos = FixedWindowCounter<Nanos, MockTimeSource>;

/// Type alias for a sliding window counter with standard nanosecond precision.
pub type SlidingWindowCounterNanos = SlidingWindowCounter<Nanos, MockTimeSource>;

/// Type alias for an approximate sliding window with standard nanosecond precision.
pub type ApproximateSlidingWindowNanos = ApproximateSlidingWindow<Nanos, MockTimeSource>;

// Type aliases for common configurations (users can define their own)
/// Common configuration: Token bucket with nanosecond precision and standard time.
#[cfg(feature = "std-time")]
pub type StdTokenBucket = TokenBucket<Nanos, StdTimeSource>;

/// Common configuration: Token bucket with nanosecond precision and mock time for testing.
pub type MockTokenBucket = TokenBucket<Nanos, MockTimeSource>;

/// Common configuration: Token bucket with millisecond precision and standard time.
#[cfg(feature = "std-time")]
pub type MillisTokenBucket = TokenBucket<Millis, StdTimeSource>;

/// Common configuration: Token bucket with millisecond precision and mock time for testing.
pub type MillisMockTokenBucket = TokenBucket<Millis, MockTimeSource>;

#[cfg(feature = "std-time")]
pub type StdFixedWindowCounter = FixedWindowCounter<Nanos, StdTimeSource>;
pub type MockFixedWindowCounter = FixedWindowCounter<Nanos, MockTimeSource>;

#[cfg(feature = "std-time")]
pub type StdSlidingWindowCounter = SlidingWindowCounter<Nanos, StdTimeSource>;
pub type MockSlidingWindowCounter = SlidingWindowCounter<Nanos, MockTimeSource>;

#[cfg(feature = "std-time")]
pub type StdApproximateSlidingWindow = ApproximateSlidingWindow<Nanos, StdTimeSource>;
pub type MockApproximateSlidingWindow = ApproximateSlidingWindow<Nanos, MockTimeSource>;