rateforge 0.1.0__py3-none-any.whl

rateforge/__init__.py

@@ -0,0 +1,32 @@
+from .rate_limit import (
+    RateLimiter,
+    RateLimitResult,
+    RateLimitContext,
+    RateLimitPolicy,
+    RateLimitExceeded,
+    get_default_limiter,
+    configure_limiter,
+    rate_limit,
+)
+from .logging_config import setup_logging
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core
+    "RateLimiter",
+    "RateLimitResult",
+    "RateLimitContext",
+    "RateLimitPolicy",
+    "RateLimitExceeded",
+    
+    # Global limiter
+    "get_default_limiter",
+    "configure_limiter",
+    
+    # Decorator
+    "rate_limit",
+    
+    # Logging
+    "setup_logging",
+]

rateforge/health/__init__.py

@@ -0,0 +1,5 @@
+"""RateForge health module."""
+
+from .checks import HealthChecker, HealthCheckResult
+
+__all__ = ["HealthChecker", "HealthCheckResult"]

rateforge/health/checks.py

@@ -0,0 +1,286 @@
+"""
+RateForge health module.
+
+Provides:
+- Five health checks (Redis, Database, Filesystem, Memory, Config)
+- Health check results with status and latency
+- Framework-agnostic health checker
+"""
+
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class HealthCheckResult:
+    """Result of a single health check."""
+
+    name: str
+    status: str  # "healthy", "unhealthy", "degraded"
+    latency_ms: float | None = None
+    error: str | None = None
+    details: dict[str, Any] = field(default_factory=dict)
+    timestamp: float = field(default_factory=time.time)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        result = {
+            "status": self.status,
+            "timestamp": self.timestamp,
+        }
+
+        if self.latency_ms is not None:
+            result["latency_ms"] = self.latency_ms
+
+        if self.error:
+            result["error"] = self.error
+
+        if self.details:
+            result["details"] = self.details
+
+        return result
+
+
+class HealthChecker:
+    """
+    Perform health checks for RateForge.
+
+    Five checks:
+    1. Redis connectivity and latency
+    2. Database (placeholder for future)
+    3. Filesystem write permissions
+    4. Memory usage
+    5. Configuration validity
+
+    Example:
+        >>> checker = HealthChecker()
+        >>> results = checker.run_all_checks()
+        >>> print(results["redis"].status)
+        "healthy"
+    """
+
+    def check_redis(self) -> HealthCheckResult:
+        """
+        Check Redis connectivity and latency.
+
+        Returns:
+            HealthCheckResult with status and latency
+        """
+        start = time.time()
+
+        try:
+            from rateforge import get_default_limiter
+
+            limiter = get_default_limiter()
+            is_connected = limiter.backend.ping()
+            latency = (time.time() - start) * 1000
+
+            if is_connected:
+                return HealthCheckResult(
+                    name="redis",
+                    status="healthy",
+                    latency_ms=round(latency, 2),
+                    details={"message": "Redis connection successful"},
+                )
+            else:
+                return HealthCheckResult(
+                    name="redis",
+                    status="unhealthy",
+                    latency_ms=round(latency, 2),
+                    error="Redis ping failed",
+                )
+
+        except Exception as exc:
+            latency = (time.time() - start) * 1000
+            return HealthCheckResult(
+                name="redis",
+                status="unhealthy",
+                latency_ms=round(latency, 2),
+                error=str(exc),
+            )
+
+    def check_database(self) -> HealthCheckResult:
+        """
+        Check database connectivity (placeholder for future).
+
+        RateForge currently doesn't use a database, but this check
+        is included for future extensibility.
+
+        Returns:
+            HealthCheckResult with placeholder status
+        """
+        return HealthCheckResult(
+            name="database",
+            status="healthy",
+            details={"note": "Database not configured in RateForge"},
+        )
+
+    def check_filesystem(self) -> HealthCheckResult:
+        """
+        Check filesystem write permissions.
+
+        Tests ability to write to temporary directory.
+
+        Returns:
+            HealthCheckResult with status
+        """
+        import tempfile
+
+        try:
+            # Test write to temp directory
+            with tempfile.NamedTemporaryFile(delete=True) as f:
+                f.write(b"rateforge_health_check")
+                f.flush()
+
+            return HealthCheckResult(
+                name="filesystem",
+                status="healthy",
+                details={"message": "Filesystem write test successful"},
+            )
+
+        except Exception as exc:
+            return HealthCheckResult(
+                name="filesystem",
+                status="unhealthy",
+                error=f"Filesystem write failed: {exc}",
+            )
+
+    def check_memory(self) -> HealthCheckResult:
+        """
+        Check memory usage.
+
+        Uses psutil if available, otherwise returns degraded status.
+
+        Returns:
+            HealthCheckResult with memory usage details
+        """
+        try:
+            import psutil
+
+            memory = psutil.virtual_memory()
+            usage_percent = memory.percent
+
+            # Determine status based on usage
+            if usage_percent < 70:
+                status = "healthy"
+            elif usage_percent < 90:
+                status = "degraded"
+            else:
+                status = "unhealthy"
+
+            return HealthCheckResult(
+                name="memory",
+                status=status,
+                details={
+                    "usage_percent": usage_percent,
+                    "available_mb": round(memory.available / (1024 * 1024), 2),
+                    "total_mb": round(memory.total / (1024 * 1024), 2),
+                },
+            )
+
+        except ImportError:
+            # psutil not installed
+            return HealthCheckResult(
+                name="memory",
+                status="degraded",
+                details={"note": "psutil not installed, cannot check memory"},
+            )
+
+        except Exception as exc:
+            return HealthCheckResult(
+                name="memory",
+                status="unhealthy",
+                error=str(exc),
+            )
+
+    def check_config(self) -> HealthCheckResult:
+        """
+        Check configuration validity.
+
+        Validates environment variables and configuration.
+
+        Returns:
+            HealthCheckResult with configuration status
+        """
+        try:
+            redis_url = os.getenv("RATEFORGE_REDIS_URL")
+            fail_open_str = os.getenv("RATEFORGE_FAIL_OPEN", "true")
+            fail_open = fail_open_str.lower() == "true"
+
+            details = {
+                "fail_open": fail_open,
+            }
+
+            if not redis_url:
+                return HealthCheckResult(
+                    name="config",
+                    status="degraded",
+                    error="RATEFORGE_REDIS_URL not set, using default",
+                    details=details,
+                )
+
+            # Validate Redis URL format
+            if not redis_url.startswith(("redis://", "rediss://")):
+                return HealthCheckResult(
+                    name="config",
+                    status="unhealthy",
+                    error="Invalid Redis URL format (must start with redis:// or rediss://)",
+                    details=details,
+                )
+
+            details["redis_url_configured"] = True
+
+            return HealthCheckResult(
+                name="config",
+                status="healthy",
+                details=details,
+            )
+
+        except Exception as exc:
+            return HealthCheckResult(
+                name="config",
+                status="unhealthy",
+                error=str(exc),
+            )
+
+    def run_all_checks(self) -> dict[str, HealthCheckResult]:
+        """
+        Run all health checks and return results.
+
+        Returns:
+            Dictionary mapping check names to results
+
+        Example:
+            >>> checker = HealthChecker()
+            >>> results = checker.run_all_checks()
+            >>> results["redis"].status
+            "healthy"
+        """
+        return {
+            "redis": self.check_redis(),
+            "database": self.check_database(),
+            "filesystem": self.check_filesystem(),
+            "memory": self.check_memory(),
+            "config": self.check_config(),
+        }
+
+    def get_overall_status(self, results: dict[str, HealthCheckResult]) -> str:
+        """
+        Determine overall health status from individual checks.
+
+        Args:
+            results: Dictionary of health check results
+
+        Returns:
+            Overall status: "healthy", "degraded", or "unhealthy"
+        """
+        statuses = [r.status for r in results.values()]
+
+        if "unhealthy" in statuses:
+            return "unhealthy"
+        elif "degraded" in statuses:
+            return "degraded"
+        else:
+            return "healthy"

rateforge/integrations/__init__.py

@@ -0,0 +1,35 @@
+from .django import (
+    HealthCheckView as DjangoHealthCheckView,
+)
+from .django import (
+    RateLimitMiddleware,
+)
+from .django import (
+    rate_limit as django_rate_limit,
+)
+from .django import (
+    rate_limit_exception_handler as django_rate_limit_handler,
+)
+from .fastapi import (
+    create_health_endpoint,
+    rate_limit_dependency,
+    setup_rate_limiting,
+)
+from .fastapi import (
+    rate_limit as fastapi_rate_limit,
+)
+from .fastapi import (
+    rate_limit_exception_handler as fastapi_rate_limit_handler,
+)
+
+__all__ = [
+    "django_rate_limit",
+    "RateLimitMiddleware",
+    "django_rate_limit_handler",
+    "DjangoHealthCheckView",
+    "fastapi_rate_limit",
+    "rate_limit_dependency",
+    "fastapi_rate_limit_handler",
+    "setup_rate_limiting",
+    "create_health_endpoint",
+]

rateforge/integrations/django.py

@@ -0,0 +1,340 @@
+"""
+Django integration for RateForge.
+
+Provides:
+- @rate_limit decorator for Django views
+- RateLimitMiddleware for automatic rate limiting
+- Exception handler for 429 responses
+- Identity extraction from Django requests
+- Health check endpoint
+"""
+
+import time
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+import structlog
+from django.conf import settings
+from django.http import HttpRequest, JsonResponse
+from django.views import View
+
+from rateforge import (
+    RateLimitExceeded,
+    RateLimitResponseHandler,
+    get_default_limiter,
+)
+from rateforge.health import HealthChecker
+
+logger = structlog.get_logger()
+
+
+def rate_limit(
+    rate: str,
+    *,
+    identity: str = "ip",
+    bypass_if_authenticated: bool = False,
+) -> Callable:
+    """
+    Django rate limit decorator.
+
+    Args:
+        rate: Human-readable rate (e.g., "100/minute", "1000/hour")
+        identity: Identity type ("ip", "user", "api_key", "plan")
+        bypass_if_authenticated: Skip rate limiting for authenticated users
+
+    Returns:
+        Decorated Django view function
+
+    Example:
+        >>> from rateforge.django import rate_limit
+        >>>
+        >>> @rate_limit("100/minute")
+        ... def home(request):
+        ...     return HttpResponse("Hello!")
+        >>>
+        >>> @rate_limit("10/minute", identity="user")
+        ... @login_required
+        ... def create_order(request):
+        ...     ...
+    """
+
+    def decorator(view_func: Callable) -> Callable:
+        @wraps(view_func)
+        def wrapper(request: HttpRequest, *args: Any, **kwargs: Any) -> Any:
+            limiter = get_default_limiter()
+
+            # Check bypass condition
+            if bypass_if_authenticated and request.user.is_authenticated:
+                return view_func(request, *args, **kwargs)
+
+            # Extract identity
+            try:
+                identity_value = _extract_identity(request, identity)
+            except ValueError as exc:
+                logger.error(
+                    "identity_extraction_failed",
+                    error=str(exc),
+                    endpoint=request.path,
+                )
+                if not limiter.fail_open:
+                    raise
+                identity_value = "unknown"
+
+            # Check rate limit
+            try:
+                result = limiter.check(
+                    identity=identity_value,
+                    endpoint=request.path,
+                    rate=rate,
+                )
+
+                # Store result in request for middleware
+                request._rate_limit_result = result
+
+                if not result.allowed:
+                    logger.warning(
+                        "rate_limit_exceeded",
+                        identity=identity_value,
+                        endpoint=request.path,
+                        limit=result.limit,
+                        remaining=0,
+                        retry_after=result.retry_after,
+                    )
+                    raise RateLimitExceeded(result)
+
+                return view_func(request, *args, **kwargs)
+
+            except RateLimitExceeded:
+                raise
+
+            except Exception as exc:
+                logger.error(
+                    "rate_limit_error",
+                    identity=identity_value,
+                    endpoint=request.path,
+                    error=str(exc),
+                )
+                if not limiter.fail_open:
+                    raise
+                return view_func(request, *args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def _extract_identity(request: HttpRequest, identity_type: str) -> str:
+    """
+    Extract identity from Django request.
+
+    Args:
+        request: Django HttpRequest
+        identity_type: Type of identity ("ip", "user", "api_key", "plan")
+
+    Returns:
+        Identity string (e.g., "ip:192.168.1.1")
+    """
+    if identity_type == "ip":
+        forwarded = request.META.get("HTTP_X_FORWARDED_FOR", "")
+        if forwarded:
+            ip = forwarded.split(",")[0].strip()
+            return f"ip:{ip}"
+
+        ip = request.META.get("REMOTE_ADDR", "unknown")
+        return f"ip:{ip}"
+
+    elif identity_type == "user":
+        if hasattr(request, "user") and request.user.is_authenticated:
+            user_id = getattr(request.user, "id", None) or getattr(request.user, "pk", None)
+            if user_id:
+                return f"user:{user_id}"
+            raise ValueError("User authenticated but no ID available")
+        raise ValueError("User not authenticated")
+
+    elif identity_type == "api_key":
+        api_key = request.headers.get("X-API-Key", "")
+        if api_key:
+            return f"api_key:{api_key}"
+        raise ValueError("API key not provided")
+
+    elif identity_type == "plan":
+        if hasattr(request, "user"):
+            plan = getattr(request.user, "plan", None)
+            if plan:
+                return f"plan:{plan}"
+            raise ValueError("User has no plan")
+        raise ValueError("Cannot extract plan from request")
+
+    else:
+        raise ValueError(f"Unknown identity type: {identity_type}")
+
+
+def rate_limit_exception_handler(exc: RateLimitExceeded) -> JsonResponse:
+    """
+    Build 429 response for RateLimitExceeded exception.
+
+    Args:
+        exc: RateLimitExceeded exception
+
+    Returns:
+        JsonResponse with 429 status and rate limit headers
+    """
+    return RateLimitResponseHandler.build_429_response(exc.result)
+
+
+class RateLimitMiddleware:
+    """
+    Django middleware for automatic rate limiting.
+
+    Add to MIDDLEWARE in settings.py:
+        MIDDLEWARE = [
+            ...
+            "rateforge.integrations.django.RateLimitMiddleware",
+        ]
+
+    Configuration in settings.py (optional):
+        RATEFORGE_CONFIG = {
+            "default_rate": "100/minute",
+            "identity": "ip",
+        }
+    """
+
+    def __init__(self, get_response: Callable):
+        self.get_response = get_response
+        self.limiter = get_default_limiter()
+
+        # Optional configuration from settings
+        config = getattr(settings, "RATEFORGE_CONFIG", {})
+        self.default_rate = config.get("default_rate", "100/minute")
+        self.default_identity = config.get("identity", "ip")
+
+    def __call__(self, request: HttpRequest) -> Any:
+        # Apply rate limiting before view
+        try:
+            identity_value = _extract_identity(request, self.default_identity)
+
+            result = self.limiter.check(
+                identity=identity_value,
+                endpoint=request.path,
+                rate=self.default_rate,
+            )
+
+            # Store result for later use
+            request._rate_limit_result = result
+
+            if not result.allowed:
+                logger.warning(
+                    "rate_limit_exceeded",
+                    identity=identity_value,
+                    endpoint=request.path,
+                    limit=result.limit,
+                    remaining=0,
+                    retry_after=result.retry_after,
+                )
+                return RateLimitResponseHandler.build_429_response(result)
+
+        except ValueError as exc:
+            logger.error(
+                "identity_extraction_failed",
+                error=str(exc),
+                endpoint=request.path,
+            )
+            if not self.limiter.fail_open:
+                raise
+
+        except Exception as exc:
+            logger.error(
+                "rate_limit_error",
+                endpoint=request.path,
+                error=str(exc),
+            )
+            if not self.limiter.fail_open:
+                raise
+
+        # Get response from view
+        response = self.get_response(request)
+
+        # Add rate limit headers to response
+        if hasattr(request, "_rate_limit_result"):
+            RateLimitResponseHandler.add_rate_limit_headers(
+                response,
+                request._rate_limit_result,
+            )
+
+        return response
+
+
+def handle_exception(get_response: Callable) -> Callable:
+    """
+    Decorator to handle RateLimitExceeded exceptions.
+
+    Usage:
+        @handle_exception
+        def my_view(request):
+            ...
+    """
+
+    @wraps(get_response)
+    def wrapper(request: HttpRequest, *args: Any, **kwargs: Any) -> Any:
+        try:
+            return get_response(request, *args, **kwargs)
+        except RateLimitExceeded as exc:
+            return rate_limit_exception_handler(exc)
+
+    return wrapper
+
+
+class HealthCheckView(View):
+    """
+    Django health check endpoint.
+
+    Returns JSON response with health status and individual check results.
+
+    Usage:
+        # urls.py
+        from rateforge.django import HealthCheckView
+
+        urlpatterns = [
+            path('health', HealthCheckView.as_view(), name='health'),
+            path('healthz', HealthCheckView.as_view(), name='healthz'),
+        ]
+
+    Response format:
+        {
+            "status": "healthy",
+            "timestamp": 1723456789.123,
+            "checks": {
+                "redis": {"status": "healthy", "latency_ms": 1.4},
+                "database": {"status": "healthy", "details": {...}},
+                ...
+            }
+        }
+
+    HTTP Status Codes:
+        200: healthy or degraded
+        503: unhealthy
+    """
+
+    def get(self, request: HttpRequest) -> JsonResponse:
+        """Handle GET request for health check."""
+        checker = HealthChecker()
+        results = checker.run_all_checks()
+
+        # Determine overall status
+        overall_status = checker.get_overall_status(results)
+
+        # Set status code based on health
+        status_code = 503 if overall_status == "unhealthy" else 200
+
+        # Format response
+        response_data = {
+            "status": overall_status,
+            "timestamp": time.time(),
+            "checks": {name: result.to_dict() for name, result in results.items()},
+        }
+
+        return JsonResponse(response_data, status=status_code)
+
+
+