Add FastAPI integration, tracer, and utils

Add FastAPI middleware and decorator for rate limiting (ratelink/integrations/fastapi.py) including a RateLimitExceeded exception and an exception handler. Introduce observability/tracer.py with a Tracer protocol, NoOpTracer, OpenTelemetryTracer (conditional), RateLimiterTracer helpers, and create_tracer factory. Add package-level exports and version in ratelink/utils/__init__.py to re-export core types, algorithms, backends, rate limiter classes, observability tools, and integrations. Add common key generator utilities in ratelink/utils/key_generators.py (by_ip, by_user_id, by_api_key, by_route, by_endpoint, composite_key, by_session, custom_key) to standardize rate-limiting keys.

Author: vladlen-codes

ratelink/integrations/fastapi.py

@@ -0,0 +1,132 @@
+import functools
+from typing import Any, Callable, Optional
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+from ratelink.utils.key_generators import KeyGeneratorFunc, by_ip
+
+class FastAPIRateLimitMiddleware(BaseHTTPMiddleware):    
+    def __init__(
+        self,
+        app,
+        limiter: Any,
+        key_generator: Optional[KeyGeneratorFunc] = None,
+        skip_paths: Optional[list] = None
+    ):
+        super().__init__(app)
+        self.limiter = limiter
+        self.key_generator = key_generator or by_ip()
+        self.skip_paths = set(skip_paths or [])
+    
+    async def dispatch(self, request: Request, call_next):
+        if request.url.path in self.skip_paths:
+            return await call_next(request)
+        
+        key = self.key_generator(request)
+        
+        allowed, state = self.limiter.check(key)
+        
+        if not allowed:
+            retry_after = state.get('retry_after', 0)
+            return JSONResponse(
+                status_code=429,
+                content={
+                    "error": "Rate limit exceeded",
+                    "limit": state.get('limit', 0),
+                    "remaining": 0,
+                    "retry_after": retry_after
+                },
+                headers={
+                    "Retry-After": str(int(retry_after)),
+                    "X-RateLimit-Limit": str(state.get('limit', 0)),
+                    "X-RateLimit-Remaining": "0",
+                    "X-RateLimit-Reset": str(int(retry_after))
+                }
+            )
+        
+        response = await call_next(request)
+        
+        response.headers["X-RateLimit-Limit"] = str(state.get('limit', 0))
+        response.headers["X-RateLimit-Remaining"] = str(state.get('remaining', 0))
+        if state.get('reset_after'):
+            response.headers["X-RateLimit-Reset"] = str(int(state.get('reset_after', 0)))
+        
+        return response
+
+
+def rate_limit(
+    limiter: Any,
+    limit: Optional[int] = None,
+    window: Optional[int] = None,
+    key_generator: Optional[KeyGeneratorFunc] = None
+):
+    if key_generator is None:
+        key_generator = by_ip()
+    
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        async def wrapper(*args, **kwargs):
+            request = None
+            for arg in args:
+                if isinstance(arg, Request):
+                    request = arg
+                    break
+            
+            if request is None and 'request' in kwargs:
+                request = kwargs['request']
+            
+            if request is None:
+                return await func(*args, **kwargs)
+
+            key = key_generator(request)
+            
+            allowed, state = limiter.check(key)
+            
+            if not allowed:
+                retry_after = state.get('retry_after', 0)
+                return JSONResponse(
+                    status_code=429,
+                    content={
+                        "error": "Rate limit exceeded",
+                        "limit": state.get('limit', 0),
+                        "remaining": 0,
+                        "retry_after": retry_after
+                    },
+                    headers={
+                        "Retry-After": str(int(retry_after)),
+                        "X-RateLimit-Limit": str(state.get('limit', 0)),
+                        "X-RateLimit-Remaining": "0",
+                    }
+                )
+            
+            return await func(*args, **kwargs)
+        
+        return wrapper
+    
+    return decorator
+
+class RateLimitExceeded(Exception):
+    def __init__(self, state: dict):
+        self.state = state
+        self.retry_after = state.get('retry_after', 0)
+        self.limit = state.get('limit', 0)
+        self.remaining = state.get('remaining', 0)
+        super().__init__(f"Rate limit exceeded. Retry after {self.retry_after}s")
+
+def setup_exception_handler(app):
+    @app.exception_handler(RateLimitExceeded)
+    async def rate_limit_exception_handler(request: Request, exc: RateLimitExceeded):
+        return JSONResponse(
+            status_code=429,
+            content={
+                "error": "Rate limit exceeded",
+                "limit": exc.limit,
+                "remaining": exc.remaining,
+                "retry_after": exc.retry_after
+            },
+            headers={
+                "Retry-After": str(int(exc.retry_after)),
+                "X-RateLimit-Limit": str(exc.limit),
+                "X-RateLimit-Remaining": str(exc.remaining),
+            }
+        )

ratelink/observability/tracer.py

@@ -0,0 +1,152 @@
+from contextlib import contextmanager
+from typing import Any, Iterator, Optional, Protocol
+
+class Tracer(Protocol):
+    @contextmanager
+    def span(
+        self,
+        name: str,
+        **attributes: Any
+    ) -> Iterator[None]:
+        """
+        Create a tracing span.
+        
+        Args:
+            name: Span name
+            **attributes: Span attributes
+        
+        Yields:
+            None
+        """
+        ...
+
+
+class NoOpTracer:
+    @contextmanager
+    def span(
+        self,
+        name: str,
+        **attributes: Any
+    ) -> Iterator[None]:
+        """Create a no-op span."""
+        yield
+
+
+try:
+    from ratelink.m import trace
+    from openteletry.trace import Status, StatusCode
+    OTEL_AVAILABLE = True
+except ImportError:
+    OTEL_AVAILABLE = False
+
+
+class OpenTelemetryTracer:
+    def __init__(
+        self,
+        service_name: str = "rate-limiter",
+        tracer_provider: Optional[Any] = None
+    ):
+        if not OTEL_AVAILABLE:
+            raise ImportError(
+                "opentelemetry-api is required for OpenTelemetryTracer. "
+                "Install with: pip install opentelemetry-api opentelemetry-sdk"
+            )
+        
+        if tracer_provider:
+            self._tracer = tracer_provider.get_tracer(service_name)
+        else:
+            self._tracer = trace.get_tracer(service_name)
+    
+    @contextmanager
+    def span(
+        self,
+        name: str,
+        **attributes: Any
+    ) -> Iterator[None]:
+        with self._tracer.start_as_current_span(name) as span:
+            for key, value in attributes.items():
+                if value is not None:
+                    span.set_attribute(key, value)
+            try:
+                yield
+            except Exception as e:
+                span.set_status(Status(StatusCode.ERROR))
+                span.record_exception(e)
+                raise
+
+
+class RateLimiterTracer:
+    def __init__(self, tracer: Optional[Tracer] = None):
+        self._tracer = tracer or NoOpTracer()
+    
+    @contextmanager
+    def trace_check(
+        self,
+        key: str,
+        algorithm: str,
+        backend: str,
+        weight: int = 1
+    ) -> Iterator[None]:
+        with self._tracer.span(
+            "rate_limit.check",
+            key=key,
+            algorithm=algorithm,
+            backend=backend,
+            weight=weight
+        ):
+            yield
+    
+    @contextmanager
+    def trace_backend_operation(
+        self,
+        backend: str,
+        operation: str,
+        key: Optional[str] = None
+    ) -> Iterator[None]:
+        attrs = {
+            "backend": backend,
+            "operation": operation,
+        }
+        if key:
+            attrs["key"] = key
+        
+        with self._tracer.span(
+            f"rate_limit.backend.{operation}",
+            **attrs
+        ):
+            yield
+    
+    @contextmanager
+    def trace_algorithm(
+        self,
+        algorithm: str,
+        key: str
+    ) -> Iterator[None]:
+        with self._tracer.span(
+            f"rate_limit.algorithm.{algorithm}",
+            algorithm=algorithm,
+            key=key
+        ):
+            yield
+
+
+def create_tracer(
+    enabled: bool = True,
+    service_name: str = "rate-limiter",
+    tracer_provider: Optional[Any] = None
+) -> Tracer:
+    if not enabled:
+        return NoOpTracer()
+    
+    if not OTEL_AVAILABLE:
+        import warnings
+        warnings.warn(
+            "OpenTelemetry not available. Install with: "
+            "pip install opentelemetry-api opentelemetry-sdk"
+        )
+        return NoOpTracer()
+    
+    return OpenTelemetryTracer(
+        service_name=service_name,
+        tracer_provider=tracer_provider
+    )

ratelink/utils/__init__.py

@@ -0,0 +1,98 @@
+from ..core.types import (
+    AlgorithmType,
+    BackendType,
+    WindowType,
+    RateLimitState,
+    RateLimitResult,
+    RateLimitException,
+    LimitExceeded,
+    BackendError,
+    ConfigError,
+    TimeoutError,
+)
+from ..core.abstractions import Algorithm, Backend, RateLimiter as RateLimiterABC
+from ..algorithms.token_bucket import TokenBucketAlgorithm
+from ..algorithms.sliding_window import SlidingWindowAlgorithm
+from ..algorithms.leaky_bucket import LeakyBucketAlgorithm
+from ..algorithms.fixed_window import FixedWindowAlgorithm
+from ..algorithms.gcra import GCRAAlgorithm
+from ..algorithms.hierarchical import HierarchicalTokenBucket, FairQueueingAlgorithm
+from ..backends.memory import MemoryBackend
+from ..backends.multi_region import MultiRegionBackend
+from ..backends.custom import CustomBackendInterface
+try:
+    from ..backends.redis import RedisBackend
+except ImportError:
+    pass
+try:
+    from ..backends.postgresql import PostgreSQLBackend
+except ImportError:
+    pass
+try:
+    from ..backends.dynamodb import DynamoDBBackend
+except ImportError:
+    pass
+try:
+    from ..backends.mongodb import MongoDBBackend
+except ImportError:
+    pass
+from ..rate_limiter import RateLimiter
+from ..config import ConfigLoader, RuleEngine
+from ..priority_limiter import PriorityRateLimiter
+from ..quota_pool import QuotaPool, SharedQuotaManager
+from ..adaptive_limiter import AdaptiveRateLimiter
+from ..observability.metrics import (
+    MetricsCollector,
+    MetricValue,
+    HistogramBucket,
+    PrometheusExporter,
+    create_prometheus_exporter,
+)
+from ..observability.logging import AuditLogger
+from ..integrations.statsd import StatsDExporter
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "RateLimiter",
+    "ConfigLoader",
+    "RuleEngine",
+    "PriorityRateLimiter",
+    "QuotaPool",
+    "SharedQuotaManager",
+    "AdaptiveRateLimiter",
+    "AlgorithmType",
+    "BackendType",
+    "WindowType",
+    "RateLimitState",
+    "RateLimitResult",
+    "RateLimitException",
+    "LimitExceeded",
+    "BackendError",
+    "ConfigError",
+    "TimeoutError",
+    "Algorithm",
+    "Backend",
+    "RateLimiterABC",
+    "TokenBucketAlgorithm",
+    "SlidingWindowAlgorithm",
+    "LeakyBucketAlgorithm",
+    "FixedWindowAlgorithm",
+    "GCRAAlgorithm",
+    "HierarchicalTokenBucket",
+    "FairQueueingAlgorithm",
+    "MemoryBackend",
+    "MultiRegionBackend",
+    "CustomBackendInterface",
+    "RedisBackend",
+    "PostgreSQLBackend",
+    "DynamoDBBackend",
+    "MongoDBBackend",
+    "MetricsCollector",
+    "MetricValue",
+    "HistogramBucket",
+    "PrometheusExporter",
+    "create_prometheus_exporter",
+    "AuditLogger",
+    "StatsDExporter",
+]