moderato 0.3.0__py3-none-any.whl

moderato/__init__.py

@@ -0,0 +1,75 @@
+"""
+Moderato - Async Redis-backed rate limiting for Python
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A high-performance, Redis-backed rate limiting library with async support.
+
+Basic usage:
+    >>> from moderato import RateLimiter
+    >>> limiter = RateLimiter(redis_url="redis://localhost:6379")
+    >>> await limiter.connect()
+    >>> await limiter.check(key="user:123", rate="100/minute")
+
+FastAPI integration:
+    >>> from fastapi import FastAPI, Request
+    >>> from moderato import RateLimiter
+    >>>
+    >>> app = FastAPI()
+    >>> limiter = RateLimiter()
+    >>>
+    >>> @app.get("/api/data")
+    >>> @limiter.limit("100/minute")
+    >>> async def get_data(request: Request):
+    >>>     return {"data": "..."}
+"""
+
+from .exceptions import BackendError, RateLimitConfigError, RateLimitExceeded
+from .limiter import RateLimiter
+from .models import CheckResult, RateLimitConfig
+
+# Framework integration (Starlette middleware) is optional - only import
+# if starlette is available. Install with: pip install 'moderato[fastapi]'
+try:
+    from .middleware import RateLimitHeadersMiddleware
+
+    _FRAMEWORK_AVAILABLE = True
+except ModuleNotFoundError as exc:
+    # Hide only a missing starlette; a defect inside middleware.py or its
+    # other dependencies must surface instead of being swallowed.
+    if exc.name is None or not (exc.name == "starlette" or exc.name.startswith("starlette.")):
+        raise
+    _FRAMEWORK_AVAILABLE = False
+    RateLimitHeadersMiddleware = None  # type: ignore[misc, assignment]
+
+# Metrics are optional - only import if prometheus_client is available
+try:
+    from .metrics import RateLimitMetrics as RateLimitMetrics
+    from .metrics import init_metrics as init_metrics
+
+    _METRICS_AVAILABLE = True
+except ModuleNotFoundError as exc:
+    if exc.name is None or not (
+        exc.name == "prometheus_client" or exc.name.startswith("prometheus_client.")
+    ):
+        raise
+    _METRICS_AVAILABLE = False
+
+__version__ = "0.3.0"
+__author__ = "Arjun Aravind"
+__email__ = "arjunaravind748@gmail.com"
+
+__all__ = [
+    "RateLimiter",
+    "RateLimitExceeded",
+    "RateLimitConfigError",
+    "BackendError",
+    "RateLimitConfig",
+    "CheckResult",
+]
+
+if _FRAMEWORK_AVAILABLE:
+    __all__.append("RateLimitHeadersMiddleware")
+
+# Add metrics to exports if available
+if _METRICS_AVAILABLE:
+    __all__.extend(["RateLimitMetrics", "init_metrics"])

moderato/algorithms/__init__.py

@@ -0,0 +1,49 @@
+"""
+Rate limiting algorithms module.
+
+DEPRECATION NOTICE:
+These algorithm classes are provided for reference and educational purposes.
+The main RateLimiter class uses the Redis backend directly and does not use
+these classes. For production use, always use the RateLimiter class:
+
+    from moderato import RateLimiter
+
+    limiter = RateLimiter(redis_url="redis://localhost:6379")
+    await limiter.check(key="user:123", rate="100/minute", algorithm="sliding_window")
+
+The algorithm parameter in RateLimiter.check() accepts:
+- "fixed_window" (default) - Simple fixed time windows
+- "token_bucket" - Token bucket with smooth refill
+- "sliding_window" - Weighted sliding window (most accurate)
+"""
+
+import warnings
+from typing import Any
+
+from .base import RateLimitAlgorithm
+
+
+def _deprecated_import(name: str) -> None:
+    warnings.warn(
+        f"{name} algorithm class is deprecated and may be removed in a future version. "
+        f"Use RateLimiter.check(algorithm='{name.lower()}') instead.",
+        DeprecationWarning,
+        stacklevel=3,
+    )
+
+
+def __getattr__(name: str) -> Any:
+    if name == "TokenBucket":
+        _deprecated_import("TokenBucket")
+        from .token_bucket import TokenBucket
+
+        return TokenBucket
+    elif name == "SlidingWindow":
+        _deprecated_import("SlidingWindow")
+        from .sliding_window import SlidingWindow
+
+        return SlidingWindow
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = ["RateLimitAlgorithm", "TokenBucket", "SlidingWindow"]

moderato/algorithms/base.py

@@ -0,0 +1,62 @@
+"""
+Base class for rate limiting algorithms.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, NamedTuple, Optional
+
+
+class RateLimitResult(NamedTuple):
+    """Result of a rate limit check."""
+
+    allowed: bool  # Whether the request is allowed
+    remaining: int  # Number of requests remaining (with multiplier)
+    retry_after: int  # Milliseconds until rate limit resets
+    reset_at: Optional[int] = None  # Unix timestamp when limit resets
+
+
+class RateLimitAlgorithm(ABC):
+    """Abstract base class for rate limiting algorithms."""
+
+    @abstractmethod
+    async def check(self, key: str, max_requests: int, window_seconds: int) -> RateLimitResult:
+        """
+        Check if a request is allowed under the rate limit.
+
+        Args:
+            key: Unique identifier for the rate limit
+            max_requests: Maximum allowed requests (with multiplier)
+            window_seconds: Time window in seconds
+
+        Returns:
+            RateLimitResult with status and metadata
+        """
+        pass
+
+    @abstractmethod
+    async def reset(self, key: str) -> bool:
+        """
+        Reset the rate limit for a specific key.
+
+        Args:
+            key: Unique identifier for the rate limit
+
+        Returns:
+            True if reset was successful
+        """
+        pass
+
+    @abstractmethod
+    async def get_usage(self, key: str, *args: Any, **kwargs: Any) -> dict[str, Any]:
+        """
+        Get current usage statistics for a key.
+
+        Args:
+            key: Unique identifier for the rate limit
+            *args: Additional positional arguments (algorithm-specific)
+            **kwargs: Additional keyword arguments (algorithm-specific)
+
+        Returns:
+            Dictionary with usage statistics
+        """
+        pass

moderato/algorithms/sliding_window.py

@@ -0,0 +1,292 @@
+"""
+Sliding Window rate limiting algorithm implementation.
+
+The sliding window algorithm provides the most accurate rate limiting
+by combining the current window with a weighted portion of the previous window.
+"""
+
+import logging
+import time
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..backends.redis import RedisBackend
+
+from .base import RateLimitAlgorithm, RateLimitResult
+
+logger = logging.getLogger(__name__)
+
+
+class SlidingWindow(RateLimitAlgorithm):
+    """
+    Sliding Window algorithm implementation.
+
+    How it works:
+    - Maintains counts for current and previous time windows
+    - Calculates weighted average based on position in current window
+    - Weight = (1 - progress_through_window)
+    - Example: 30s into 60s window = 50% from previous + 50% from current
+
+    Mathematical Formula:
+        weighted_count = previous_count * (1 - t/T) + current_count
+        where:
+        - t = time elapsed in current window
+        - T = total window duration
+        - previous_count = requests in previous window
+        - current_count = requests in current window
+
+    Example (100 requests/minute):
+        Time: 14:35:30 (30 seconds into minute)
+        Previous window (14:34): 80 requests
+        Current window (14:35): 40 requests
+
+        Weight for previous = 1 - (30/60) = 0.5
+        Weighted count = 80 * 0.5 + 40 = 40 + 40 = 80 requests
+
+        Can accept: 100 - 80 = 20 more requests
+
+    Advantages over Fixed Window:
+    - No boundary bursts (smooths across window edges)
+    - More accurate distribution
+    - Better user experience
+    - Fairer rate limiting
+
+    Advantages over Token Bucket:
+    - Simpler to understand
+    - More predictable
+    - Lower memory usage
+    - Easier to debug
+
+    Disadvantages:
+    - Requires two Redis keys (current + previous)
+    - Slightly more complex than Fixed Window
+    - Not as smooth as Token Bucket for bursts
+    """
+
+    def __init__(self, backend: "RedisBackend") -> None:
+        """
+        Initialize Sliding Window algorithm.
+
+        Args:
+            backend: Redis backend for executing Lua scripts
+        """
+        self.backend = backend
+        logger.debug("Initialized SlidingWindow algorithm")
+
+    async def check(
+        self,
+        key: str,
+        max_requests: int,
+        window_seconds: int,
+        cost: int = 1000,
+    ) -> RateLimitResult:
+        """
+        Check if a request is allowed under sliding window rate limit.
+
+        Args:
+            key: Base identifier for the rate limit (without time suffix)
+            max_requests: Maximum requests (with multiplier)
+            window_seconds: Time window in seconds
+            cost: Number of requests to consume (with multiplier)
+
+        Returns:
+            RateLimitResult with allowed status and metadata
+
+        Example:
+            For "100/minute":
+            - max_requests = 100000 (100 * 1000)
+            - window_seconds = 60
+            - At 14:35:30:
+              - Current window: ratelimit:user:default:14:35
+              - Previous window: ratelimit:user:default:14:34
+              - Weight: 0.5 (30 seconds into current window)
+        """
+        # Get current timestamp
+        current_time = int(time.time())
+
+        # Calculate current window start time
+        window_start = current_time - (current_time % window_seconds)
+
+        # Calculate previous window start time
+        previous_window_start = window_start - window_seconds
+
+        # Generate keys for current and previous windows
+        # We'll append the window start timestamp to ensure uniqueness
+        current_key = f"{key}:{window_start}"
+        previous_key = f"{key}:{previous_window_start}"
+
+        # Execute sliding window Lua script
+        result = await self.backend.check_sliding_window(
+            current_key=current_key,
+            previous_key=previous_key,
+            max_requests=max_requests,
+            window_seconds=window_seconds,
+            current_time=current_time,
+            cost=cost,
+        )
+
+        # Calculate reset timestamp (start of next window)
+        reset_at = window_start + window_seconds
+
+        return RateLimitResult(
+            allowed=result.allowed,
+            remaining=result.remaining,
+            retry_after=result.retry_after,
+            reset_at=reset_at,
+        )
+
+    async def reset(self, key: str) -> bool:
+        """
+        Reset sliding window for a specific key.
+
+        This removes both current and previous window data.
+
+        Args:
+            key: Base identifier for the rate limit
+
+        Returns:
+            True if reset was successful
+        """
+        # For sliding window, we need to reset multiple keys
+        # We'll try to delete keys for recent windows
+        current_time = int(time.time())
+
+        # Try to delete current and recent windows
+        success = False
+        for offset in [0, 60, 3600, 86400]:  # Now, minute, hour, day ago
+            window_start = current_time - (current_time % offset) if offset > 0 else current_time
+            test_key = f"{key}:{window_start}"
+            if await self.backend.reset(test_key):
+                success = True
+
+            # Also try previous window
+            if offset > 0:
+                prev_key = f"{key}:{window_start - offset}"
+                if await self.backend.reset(prev_key):
+                    success = True
+
+        return success
+
+    async def get_usage(self, key: str, *args: Any, **kwargs: Any) -> dict[str, Any]:
+        """
+        Get current usage statistics for sliding window.
+
+        Args:
+            key: Base identifier for the rate limit
+            *args: Expected to contain max_requests and window_seconds
+            **kwargs: Not used
+
+        Returns:
+            Dictionary with:
+            - current: Weighted current usage (without multiplier)
+            - limit: Maximum requests (without multiplier)
+            - remaining: Requests remaining (without multiplier)
+            - current_window: Requests in current window
+            - previous_window: Requests in previous window
+            - weight: Weight applied to previous window (0.0 to 1.0)
+        """
+        max_requests: int = args[0] if len(args) > 0 else kwargs.get("max_requests", 0)
+        window_seconds: int = args[1] if len(args) > 1 else kwargs.get("window_seconds", 60)
+        current_time = int(time.time())
+        window_start = current_time - (current_time % window_seconds)
+        previous_window_start = window_start - window_seconds
+
+        current_key = f"{key}:{window_start}"
+        previous_key = f"{key}:{previous_window_start}"
+
+        # Get counts from Redis
+        current_usage = await self.backend.get_usage(current_key)
+        previous_usage = await self.backend.get_usage(previous_key)
+
+        current_count = current_usage.get("current", 0)
+        previous_count = previous_usage.get("current", 0)
+
+        # Calculate weight using integer math (consistent with Lua script)
+        elapsed_in_window = current_time - window_start
+        remaining_in_window = window_seconds - elapsed_in_window
+
+        # Use fixed-point weight (0-1000 scale) for consistency with Lua
+        prev_weight_fp = (remaining_in_window * 1000) // window_seconds if window_seconds > 0 else 0
+
+        # Calculate weighted count using integer math
+        # Formula: weighted = current + (previous * weight)
+        # Note: counts already have 1000x multiplier, weight is 0-1000
+        weighted_previous = (previous_count * prev_weight_fp) // 1000
+        weighted_count = (current_count + weighted_previous) // 1000  # Divide by 1000 for display
+
+        max_requests_display = max_requests // 1000
+        remaining = max(0, max_requests_display - weighted_count)
+
+        return {
+            "current": weighted_count,
+            "limit": max_requests_display,
+            "remaining": remaining,
+            "current_window": current_count // 1000,
+            "previous_window": previous_count // 1000,
+            "weight": prev_weight_fp / 1000,  # Convert fixed-point to float for display
+            "window_seconds": window_seconds,
+        }
+
+
+def calculate_sliding_window_count(
+    current_count: int,
+    previous_count: int,
+    window_seconds: int,
+    elapsed_seconds: int,
+) -> float:
+    """
+    Calculate weighted count for sliding window.
+
+    This is the core formula used by the sliding window algorithm.
+
+    Args:
+        current_count: Requests in current window
+        previous_count: Requests in previous window
+        window_seconds: Total window duration
+        elapsed_seconds: Time elapsed in current window
+
+    Returns:
+        Weighted count as float
+
+    Examples:
+        >>> # 30 seconds into 60-second window
+        >>> calculate_sliding_window_count(
+        ...     current_count=40,
+        ...     previous_count=80,
+        ...     window_seconds=60,
+        ...     elapsed_seconds=30
+        ... )
+        80.0  # 40 + (80 * 0.5)
+
+        >>> # Start of window (0 seconds elapsed)
+        >>> calculate_sliding_window_count(
+        ...     current_count=10,
+        ...     previous_count=90,
+        ...     window_seconds=60,
+        ...     elapsed_seconds=0
+        ... )
+        100.0  # 10 + (90 * 1.0)
+
+        >>> # End of window (60 seconds elapsed)
+        >>> calculate_sliding_window_count(
+        ...     current_count=50,
+        ...     previous_count=100,
+        ...     window_seconds=60,
+        ...     elapsed_seconds=60
+        ... )
+        50.0  # 50 + (100 * 0.0)
+    """
+    if window_seconds <= 0:
+        raise ValueError("Window seconds must be positive")
+
+    if elapsed_seconds < 0 or elapsed_seconds > window_seconds:
+        raise ValueError(f"Elapsed seconds must be between 0 and {window_seconds}")
+
+    # Calculate weight for previous window
+    progress = elapsed_seconds / window_seconds
+    previous_weight = 1 - progress
+
+    # Apply weighted formula
+    weighted_count = current_count + (previous_count * previous_weight)
+
+    return weighted_count

moderato/algorithms/token_bucket.py

@@ -0,0 +1,226 @@
+"""
+Token Bucket rate limiting algorithm implementation.
+
+The token bucket algorithm provides smoother rate limiting compared to
+fixed window, with better handling of bursty traffic.
+"""
+
+import logging
+import time
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..backends.redis import RedisBackend
+
+from .base import RateLimitAlgorithm, RateLimitResult
+
+logger = logging.getLogger(__name__)
+
+
+class TokenBucket(RateLimitAlgorithm):
+    """
+    Token Bucket algorithm implementation.
+
+    How it works:
+    - A bucket holds tokens up to a maximum capacity
+    - Tokens are continuously added at a fixed refill rate
+    - Each request consumes one or more tokens
+    - If not enough tokens, request is denied
+    - Provides smooth rate limiting without boundary bursts
+
+    Example:
+        100 requests/minute = 100 max tokens, ~1.67 refill rate/second
+        Allows bursts up to 100 requests, then sustained 1.67 req/sec
+
+    Advantages over Fixed Window:
+    - No burst at window boundaries
+    - Smoother traffic distribution
+    - Better for bursty workloads
+    - Allows controlled bursts within capacity
+
+    Disadvantages:
+    - Slightly more complex
+    - Uses more Redis memory (stores tokens + timestamp)
+    - Can allow more requests in first window
+    """
+
+    def __init__(self, backend: "RedisBackend") -> None:
+        """
+        Initialize Token Bucket algorithm.
+
+        Args:
+            backend: Redis backend for executing Lua scripts
+        """
+        self.backend = backend
+        logger.debug("Initialized TokenBucket algorithm")
+
+    async def check(
+        self,
+        key: str,
+        max_requests: int,
+        window_seconds: int,
+        cost: int = 1000,
+    ) -> RateLimitResult:
+        """
+        Check if a request is allowed under token bucket rate limit.
+
+        Args:
+            key: Unique identifier for the rate limit
+            max_requests: Maximum tokens (bucket capacity, with multiplier)
+            window_seconds: Time window to spread requests over
+            cost: Number of tokens to consume (with multiplier)
+
+        Returns:
+            RateLimitResult with allowed status and metadata
+
+        Example:
+            For "100/minute":
+            - max_requests = 100000 (100 * 1000)
+            - window_seconds = 60
+            - refill_rate = 100000 / 60 = 1666.67 tokens/sec
+            - Bucket starts full (100000 tokens)
+            - Refills at 1666.67 tokens/sec
+            - Max capacity: 100000 tokens
+        """
+        # Preserve fractional refill rates so limits such as 1/hour can recover.
+        refill_rate_per_second = max_requests / window_seconds
+
+        # Get current timestamp in milliseconds
+        current_time_ms = int(time.time() * 1000)
+
+        # Execute token bucket Lua script
+        result = await self.backend.check_token_bucket(
+            key=key,
+            max_tokens=max_requests,
+            refill_rate_per_second=refill_rate_per_second,
+            window_seconds=window_seconds,
+            current_time_ms=current_time_ms,
+            cost=cost,
+        )
+
+        # Calculate reset timestamp (when bucket would be full)
+        # If tokens remaining, no reset needed
+        # If denied, reset_at = current_time + retry_after
+        reset_at = None
+        if not result.allowed:
+            reset_at = (current_time_ms // 1000) + (result.retry_after // 1000)
+
+        return RateLimitResult(
+            allowed=result.allowed,
+            remaining=result.remaining,
+            retry_after=result.retry_after,
+            reset_at=reset_at,
+        )
+
+    async def reset(self, key: str) -> bool:
+        """
+        Reset token bucket for a specific key.
+
+        This removes the bucket data, causing the next request
+        to start with a full bucket.
+
+        Args:
+            key: Unique identifier for the rate limit
+
+        Returns:
+            True if reset was successful
+        """
+        return await self.backend.reset(key)
+
+    async def get_usage(self, key: str, *args: Any, **kwargs: Any) -> dict[str, Any]:
+        """
+        Get current usage statistics for a token bucket.
+
+        Args:
+            key: Unique identifier for the rate limit
+            *args: Expected to contain max_requests as first argument
+            **kwargs: Not used
+
+        Returns:
+            Dictionary with:
+            - current: Current token count (without multiplier)
+            - limit: Maximum tokens (without multiplier)
+            - remaining: Tokens remaining (without multiplier)
+            - last_refill: Unix timestamp of last refill
+
+        Note: For token bucket, "current" means tokens available,
+        not requests consumed (inverse of fixed window).
+        """
+        max_requests: int = args[0] if args else kwargs.get("max_requests", 0)
+        usage = await self.backend.get_token_bucket_usage(key)
+
+        # Convert from integer math (divide by 1000)
+        current_tokens = usage.get("tokens", max_requests) // 1000
+        max_tokens_display = max_requests // 1000
+
+        return {
+            "current": current_tokens,
+            "limit": max_tokens_display,
+            "remaining": current_tokens,
+            "last_refill": usage.get("last_refill", 0),
+        }
+
+
+def calculate_refill_rate(requests: int, window_seconds: int) -> float:
+    """
+    Calculate token refill rate for token bucket.
+
+    Args:
+        requests: Number of requests allowed in window
+        window_seconds: Time window in seconds
+
+    Returns:
+        Refill rate in tokens per second
+
+    Examples:
+        >>> calculate_refill_rate(100, 60)  # 100/minute
+        1.6666666666666667
+
+        >>> calculate_refill_rate(1000, 3600)  # 1000/hour
+        0.2777777777777778
+
+        >>> calculate_refill_rate(10, 1)  # 10/second
+        10.0
+    """
+    if window_seconds <= 0:
+        raise ValueError("Window seconds must be positive")
+
+    return requests / window_seconds
+
+
+def calculate_bucket_capacity(requests: int, burst_factor: float = 1.0) -> int:
+    """
+    Calculate bucket capacity with optional burst allowance.
+
+    By default, bucket capacity equals the rate limit. You can
+    increase capacity to allow larger bursts.
+
+    Args:
+        requests: Base number of requests allowed
+        burst_factor: Multiplier for bucket capacity (>= 1.0)
+                     1.0 = no extra burst (default)
+                     2.0 = allow 2x burst
+                     0.5 = not recommended (less than rate)
+
+    Returns:
+        Bucket capacity in tokens
+
+    Examples:
+        >>> calculate_bucket_capacity(100, 1.0)  # Standard
+        100
+
+        >>> calculate_bucket_capacity(100, 1.5)  # Allow 50% burst
+        150
+
+        >>> calculate_bucket_capacity(100, 2.0)  # Allow 2x burst
+        200
+
+    Note: Burst factor is not currently exposed in the main API,
+    but is available for advanced use cases.
+    """
+    if burst_factor < 1.0:
+        logger.warning(
+            f"Burst factor {burst_factor} < 1.0 may cause issues. " "Consider using >= 1.0"
+        )
+
+    return int(requests * burst_factor)