fluxlimit 0.1.0__py3-none-any.whl

fluxlimit/__init__.py

@@ -0,0 +1,74 @@
+"""fluxlimit - Distributed rate limiting with fairness for Python.
+
+A production-ready rate limiting library supporting:
+- Token bucket, leaky bucket, fixed window, sliding window algorithms
+- Distributed fairness via Redis (Lua scripts) and PostgreSQL (advisory locks)
+- Cost-based limiting for different endpoint weights
+- FastAPI/Starlette and Flask middleware integrations
+- Prometheus metrics export
+"""
+
+__version__ = "0.1.0"
+
+from .core import RateLimiter, LimitRule
+from .exceptions import (
+    FluxlimitError,
+    RateLimitExceeded,
+    BackendError,
+    ConfigurationError,
+)
+from .algorithms import (
+    TokenBucket,
+    TokenBucketConfig,
+    LeakyBucket,
+    LeakyBucketConfig,
+    FixedWindow,
+    FixedWindowConfig,
+    SlidingWindow,
+    SlidingWindowConfig,
+    LimitResult,
+)
+from .backends import (
+    MemoryBackend,
+    RedisBackend,
+    PostgresBackend,
+)
+
+
+def __getattr__(name: str):
+    if name in ("RateLimitMiddleware", "rate_limit", "Fluxlimit", "init_fluxlimit"):
+        from . import middleware
+
+        return getattr(middleware, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    # Core
+    "RateLimiter",
+    "LimitRule",
+    # Exceptions
+    "FluxlimitError",
+    "RateLimitExceeded",
+    "BackendError",
+    "ConfigurationError",
+    # Algorithms
+    "TokenBucket",
+    "TokenBucketConfig",
+    "LeakyBucket",
+    "LeakyBucketConfig",
+    "FixedWindow",
+    "FixedWindowConfig",
+    "SlidingWindow",
+    "SlidingWindowConfig",
+    "LimitResult",
+    # Backends
+    "MemoryBackend",
+    "RedisBackend",
+    "PostgresBackend",
+    # Middleware
+    "RateLimitMiddleware",
+    "rate_limit",
+    "Fluxlimit",
+    "init_fluxlimit",
+]

fluxlimit/algorithms/__init__.py

@@ -0,0 +1,22 @@
+"""Rate limiting algorithms."""
+
+from .token_bucket import TokenBucket, TokenBucketConfig
+from .leaky_bucket import LeakyBucket, LeakyBucketConfig
+from .fixed_window import FixedWindow, FixedWindowConfig
+from .sliding_window import SlidingWindow, SlidingWindowConfig
+from .base import BaseAlgorithm, LimitResult, AlgorithmConfig
+
+__all__ = [
+    "TokenBucket",
+    "TokenBucketConfig",
+    "LeakyBucket",
+    "LeakyBucketConfig",
+    "FixedWindow",
+    "FixedWindowConfig",
+    "SlidingWindow",
+    "SlidingWindowConfig",
+
+    "BaseAlgorithm",
+    "LimitResult",
+    "AlgorithmConfig",
+]

fluxlimit/algorithms/base.py

@@ -0,0 +1,64 @@
+"""Base class for rate limiting algorithms."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class LimitResult:
+    """Result of a rate limit check.
+    
+    Attributes:
+        allowed: Whether the request is allowed.
+        remaining: Number of requests remaining in the current window.
+        reset_after: Seconds until the limit resets.
+        retry_after: Seconds until the request can be retried (only if not allowed).
+    """
+    allowed: bool
+    remaining: int
+    reset_after: float
+    retry_after: float = 0.0
+
+
+@dataclass(frozen=True)
+class AlgorithmConfig:
+    """Configuration for a rate limiting algorithm."""
+    key: str
+    
+
+class BaseAlgorithm(ABC):
+    """Abstract base class for rate limiting algorithms."""
+    
+    def __init__(self, key_prefix: str = "fluxlimit"):
+        self.key_prefix = key_prefix
+    
+    def _make_key(self, identifier: str, config: AlgorithmConfig) -> str:
+        """Generate a storage key for the given identifier and config."""
+        return f"{self.key_prefix}:{config.key}:{identifier}"
+    
+    @abstractmethod
+    async def check(
+        self, 
+        backend, 
+        identifier: str, 
+        config: AlgorithmConfig,
+        cost: int = 1
+    ) -> LimitResult:
+        """Check if a request is allowed under the rate limit.
+        
+        Args:
+            backend: The storage backend to use.
+            identifier: Unique identifier for the client (IP, API key, user ID).
+            config: Algorithm-specific configuration.
+            cost: How many tokens/credits this request consumes.
+            
+        Returns:
+            LimitResult indicating whether the request is allowed.
+        """
+        pass
+    
+    @abstractmethod
+    def get_config_class(self) -> type:
+        """Return the configuration dataclass for this algorithm."""
+        pass

fluxlimit/algorithms/fixed_window.py

@@ -0,0 +1,64 @@
+"""Fixed window rate limiting algorithm."""
+
+from dataclasses import dataclass
+import time
+import math
+
+from .base import BaseAlgorithm, LimitResult, AlgorithmConfig
+
+
+@dataclass(frozen=True)
+class FixedWindowConfig(AlgorithmConfig):
+    """Configuration for fixed window algorithm.
+    
+    Attributes:
+        key: Unique key for this limit configuration.
+        max_requests: Maximum requests allowed per window.
+        window_seconds: Duration of each window in seconds.
+    """
+    max_requests: int = 100
+    window_seconds: int = 60
+
+
+class FixedWindow(BaseAlgorithm):
+    """Fixed window rate limiter.
+    
+    Counts requests in fixed time windows. Simple but can allow
+    bursts at window boundaries (2x the limit in a short period).
+    
+    Use for simple cases where boundary bursts are acceptable.
+    """
+    
+    def __init__(self, key_prefix: str = "fluxlimit:fixed_window"):
+        super().__init__(key_prefix)
+    
+    def get_config_class(self) -> type:
+        return FixedWindowConfig
+    
+    async def check(
+        self,
+        backend,
+        identifier: str,
+        config: FixedWindowConfig,
+        cost: int = 1
+    ) -> LimitResult:
+        """Check if request is allowed using fixed window algorithm."""
+        key = self._make_key(identifier, config)
+        now = time.time()
+        window_start = math.floor(now / config.window_seconds) * config.window_seconds
+        window_key = f"{key}:{int(window_start)}"
+        
+        result = await backend.fixed_window_increment(
+            key=window_key,
+            max_requests=config.max_requests,
+            window_seconds=config.window_seconds,
+            cost=cost,
+            now=now
+        )
+        
+        return LimitResult(
+            allowed=result["allowed"],
+            remaining=result["remaining"],
+            reset_after=result["reset_after"],
+            retry_after=result.get("retry_after", 0.0)
+        )

fluxlimit/algorithms/leaky_bucket.py

@@ -0,0 +1,64 @@
+"""Leaky bucket rate limiting algorithm."""
+
+from dataclasses import dataclass
+import time
+
+from .base import BaseAlgorithm, LimitResult, AlgorithmConfig
+
+
+@dataclass(frozen=True)
+class LeakyBucketConfig(AlgorithmConfig):
+    """Configuration for leaky bucket algorithm.
+    
+    Attributes:
+        key: Unique key for this limit configuration.
+        rate: Requests processed per second (leak rate).
+        capacity: Maximum queue size.
+    """
+    rate: float = 10.0
+    capacity: int = 100
+
+
+class LeakyBucket(BaseAlgorithm):
+    """Leaky bucket rate limiter.
+    
+    Requests are queued and processed at a constant rate.
+    If the queue is full, requests are rejected.
+    
+    This provides:
+    - Strict rate enforcement (no bursts allowed)
+    - Smooth output traffic
+    - Protection against traffic spikes
+    """
+    
+    def __init__(self, key_prefix: str = "fluxlimit:leaky_bucket"):
+        super().__init__(key_prefix)
+    
+    def get_config_class(self) -> type:
+        return LeakyBucketConfig
+    
+    async def check(
+        self,
+        backend,
+        identifier: str,
+        config: LeakyBucketConfig,
+        cost: int = 1
+    ) -> LimitResult:
+        """Check if request is allowed using leaky bucket algorithm."""
+        key = self._make_key(identifier, config)
+        now = time.time()
+        
+        result = await backend.leaky_bucket_request(
+            key=key,
+            rate=config.rate,
+            capacity=config.capacity,
+            cost=cost,
+            now=now
+        )
+        
+        return LimitResult(
+            allowed=result["allowed"],
+            remaining=result["remaining"],
+            reset_after=result["reset_after"],
+            retry_after=result.get("retry_after", 0.0)
+        )

fluxlimit/algorithms/sliding_window.py

@@ -0,0 +1,64 @@
+"""Sliding window rate limiting algorithm."""
+
+from dataclasses import dataclass
+import time
+
+from .base import BaseAlgorithm, LimitResult, AlgorithmConfig
+
+
+@dataclass(frozen=True)
+class SlidingWindowConfig(AlgorithmConfig):
+    """Configuration for sliding window algorithm.
+    
+    Attributes:
+        key: Unique key for this limit configuration.
+        max_requests: Maximum requests allowed in the window.
+        window_seconds: Duration of the sliding window in seconds.
+    """
+    max_requests: int = 100
+    window_seconds: int = 60
+
+
+class SlidingWindow(BaseAlgorithm):
+    """Sliding window rate limiter.
+    
+    Uses a sliding time window to count requests. More accurate
+    than fixed window but requires more storage (tracking timestamps).
+    
+    This provides:
+    - No boundary burst issues
+    - Smooth rate limiting over time
+    - Higher accuracy at the cost of storage
+    """
+    
+    def __init__(self, key_prefix: str = "fluxlimit:sliding_window"):
+        super().__init__(key_prefix)
+    
+    def get_config_class(self) -> type:
+        return SlidingWindowConfig
+    
+    async def check(
+        self,
+        backend,
+        identifier: str,
+        config: SlidingWindowConfig,
+        cost: int = 1
+    ) -> LimitResult:
+        """Check if request is allowed using sliding window algorithm."""
+        key = self._make_key(identifier, config)
+        now = time.time()
+        
+        result = await backend.sliding_window_check(
+            key=key,
+            max_requests=config.max_requests,
+            window_seconds=config.window_seconds,
+            cost=cost,
+            now=now
+        )
+        
+        return LimitResult(
+            allowed=result["allowed"],
+            remaining=result["remaining"],
+            reset_after=result["reset_after"],
+            retry_after=result.get("retry_after", 0.0)
+        )

fluxlimit/algorithms/token_bucket.py

@@ -0,0 +1,67 @@
+"""Token bucket rate limiting algorithm."""
+
+from dataclasses import dataclass
+from typing import Optional
+import time
+import math
+
+from .base import BaseAlgorithm, LimitResult, AlgorithmConfig
+
+
+@dataclass(frozen=True)
+class TokenBucketConfig(AlgorithmConfig):
+    """Configuration for token bucket algorithm.
+    
+    Attributes:
+        key: Unique key for this limit configuration.
+        rate: Tokens added per second (sustained rate).
+        burst: Maximum bucket size (burst capacity).
+    """
+    rate: float = 10.0
+    burst: int = 20
+
+
+class TokenBucket(BaseAlgorithm):
+    """Token bucket rate limiter.
+    
+    The bucket starts full. Each request consumes tokens.
+    Tokens are replenished at a constant rate up to the burst capacity.
+    
+    This provides:
+    - Smooth traffic shaping (requests are spread out)
+    - Bursty traffic tolerance (up to burst capacity)
+    - Distributed fairness when used with a shared backend
+    """
+    
+    def __init__(self, key_prefix: str = "fluxlimit:token_bucket"):
+        super().__init__(key_prefix)
+    
+    def get_config_class(self) -> type:
+        return TokenBucketConfig
+    
+    async def check(
+        self,
+        backend,
+        identifier: str,
+        config: TokenBucketConfig,
+        cost: int = 1
+    ) -> LimitResult:
+        """Check if request is allowed using token bucket algorithm."""
+        key = self._make_key(identifier, config)
+        now = time.time()
+        
+        # Use backend's atomic compare-and-swap or Lua script for distributed fairness
+        result = await backend.token_bucket_consume(
+            key=key,
+            rate=config.rate,
+            burst=config.burst,
+            cost=cost,
+            now=now
+        )
+        
+        return LimitResult(
+            allowed=result["allowed"],
+            remaining=result["remaining"],
+            reset_after=result["reset_after"],
+            retry_after=result.get("retry_after", 0.0)
+        )

fluxlimit/backends/__init__.py

@@ -0,0 +1,13 @@
+"""Storage backends for fluxlimit."""
+
+from .base import BaseBackend
+from .memory import MemoryBackend
+from .redis import RedisBackend
+from .postgres import PostgresBackend
+
+__all__ = [
+    "BaseBackend",
+    "MemoryBackend",
+    "RedisBackend",
+    "PostgresBackend",
+]

fluxlimit/backends/base.py

@@ -0,0 +1,79 @@
+"""Base class for rate limiter backends."""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional
+
+
+class BaseBackend(ABC):
+    """Abstract base class for rate limiter storage backends.
+    
+    All backends must implement atomic operations for each algorithm
+    to ensure distributed fairness.
+    """
+    
+    @abstractmethod
+    async def connect(self) -> None:
+        """Establish connection to the backend."""
+        pass
+    
+    @abstractmethod
+    async def disconnect(self) -> None:
+        """Close connection to the backend."""
+        pass
+    
+    @abstractmethod
+    async def token_bucket_consume(
+        self,
+        key: str,
+        rate: float,
+        burst: int,
+        cost: int,
+        now: float
+    ) -> Dict[str, Any]:
+        """Atomically consume tokens from a bucket.
+        
+        Returns dict with keys: allowed (bool), remaining (int), 
+        reset_after (float), retry_after (float).
+        """
+        pass
+    
+    @abstractmethod
+    async def leaky_bucket_request(
+        self,
+        key: str,
+        rate: float,
+        capacity: int,
+        cost: int,
+        now: float
+    ) -> Dict[str, Any]:
+        """Atomically request space in leaky bucket."""
+        pass
+    
+    @abstractmethod
+    async def fixed_window_increment(
+        self,
+        key: str,
+        max_requests: int,
+        window_seconds: int,
+        cost: int,
+        now: float
+    ) -> Dict[str, Any]:
+        """Atomically increment counter for fixed window."""
+        pass
+    
+    @abstractmethod
+    async def sliding_window_check(
+        self,
+        key: str,
+        max_requests: int,
+        window_seconds: int,
+        cost: int,
+        now: float
+    ) -> Dict[str, Any]:
+        """Atomically check sliding window."""
+        pass
+    
+    @abstractmethod
+    async def health_check(self) -> bool:
+        """Check if backend is healthy."""
+        pass