p-redis-limiter 0.1.0__tar.gz

p_redis_limiter-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: p-redis-limiter
+Version: 0.1.0
+Summary: A fast, atomic, multi-tier Token Bucket rate limiter for Python and FastAPI using Redis.
+Author: Mehran
+License: MIT
+Keywords: redis,rate-limiter,token-bucket,fastapi,throttling
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: redis>=4.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
+Requires-Dist: httpx>=0.23.0; extra == "dev"
+Requires-Dist: fastapi>=0.70.0; extra == "dev"
+
+# p-redis-limiter
+
+Redis token bucket rate limiter for Python and FastAPI.
+
+## Installation
+
+```bash
+pip install git+https://github.com/mehranpng/p-redis-limiter.git
+```
+
+## Usage
+
+### 1. Global Middleware (All Endpoints)
+
+Apply a rate limit across all endpoints:
+
+```python
+from fastapi import FastAPI
+from redis import Redis
+from p_redis_limiter import RateLimitMiddleware, Rate
+
+app = FastAPI()
+r = Redis(host="localhost", port=6379, decode_responses=True)
+
+# 40 requests per 60 seconds
+app.add_middleware(
+    RateLimitMiddleware,
+    redis=r,
+    rates=Rate(40, 60),
+)
+
+@app.get("/")
+def index():
+    return {"ok": True}
+```
+
+### 2. Specific Endpoint Only
+
+To rate limit a specific route instead of the whole application, use `RateLimiter` with `Depends`:
+
+```python
+from fastapi import FastAPI, Depends
+from redis import Redis
+from p_redis_limiter import RateLimiter, Rate
+
+app = FastAPI()
+r = Redis(host="localhost", port=6379, decode_responses=True)
+
+# 5 requests per 60 seconds for login only
+login_limiter = RateLimiter(r, Rate(5, 60), prefix="rate:login")
+
+@app.get("/")
+def home():
+    return {"message": "unlimited"}
+
+@app.post("/login", dependencies=[Depends(login_limiter.as_dependency())])
+def login():
+    return {"message": "login successful"}
+```
+
+### 3. Multiple Rate Limits
+
+You can define multiple rules (e.g. 5 req/sec burst limit and 100 req/min). If one rule fails, tokens are not deducted from the others:
+
+```python
+rates = [
+    Rate(5, 1),    # 5 requests per 1 second
+    Rate(100, 60), # 100 requests per 60 seconds
+]
+
+# Or string shorthand:
+rates = ["5/s", "100/m"]
+```
+
+### 4. Cache TTL
+
+By default, Redis keys expire automatically after `max(window * 2, 60)` seconds. You can specify a custom TTL:
+
+```python
+# Per rate rule:
+Rate(40, 60, ttl=120)
+
+# Disable TTL (persist in Redis forever):
+Rate(40, 60, ttl=-1)
+
+# Or globally on middleware / limiter:
+RateLimitMiddleware(redis=r, rates=Rate(40, 60), ttl=120)
+```
+
+### 5. Manual Usage (Specify IP Yourself)
+
+If you prefer to get the IP yourself, simply pass your IP variable directly:
+
+```python
+from p_redis_limiter import RateLimiter, Rate
+
+limiter = RateLimiter(r, Rate(5, 60))
+
+@app.post("/login")
+def login(request: Request):
+    user_ip = get_my_ip(request)  # your own IP variable
+
+    # Simple boolean check:
+    if not limiter.is_allowed(user_ip):
+        return JSONResponse({"detail": "Too many requests"}, status_code=429)
+
+    return {"ok": True}
+```
+
+Or get full details (`remaining`, `retry_after`):
+
+```python
+result = limiter.check(user_ip)
+if not result.allowed:
+    print(f"Blocked! Retry after {result.retry_after}s")
+```
+
+## Options
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `redis` | `Redis` | Required | Redis client instance (`redis.Redis` or `redis.asyncio.Redis`) |
+| `rates` | `Rate` / `list` / `str` | Required | Rate rules, e.g. `Rate(40, 60)` or `["5/s", "100/m"]` |
+| `ttl` | `int` | Auto | Custom Redis key TTL in seconds |
+| `prefix` | `str` | `"rate"` | Prefix for Redis keys |
+| `identifier` | `Callable` / `str` | Client IP | Custom function or header name (auto-detects Cloudflare, Nginx, ALB, direct IP) |
+| `exclude_paths` | `list[str]` | `None` | List of paths to exclude from rate limiting |
+| `error_detail` | `str` | `"Too many requests"` | Response detail message on 429 |

p_redis_limiter-0.1.0/README.md

@@ -0,0 +1,128 @@
+# p-redis-limiter
+
+Redis token bucket rate limiter for Python and FastAPI.
+
+## Installation
+
+```bash
+pip install git+https://github.com/mehranpng/p-redis-limiter.git
+```
+
+## Usage
+
+### 1. Global Middleware (All Endpoints)
+
+Apply a rate limit across all endpoints:
+
+```python
+from fastapi import FastAPI
+from redis import Redis
+from p_redis_limiter import RateLimitMiddleware, Rate
+
+app = FastAPI()
+r = Redis(host="localhost", port=6379, decode_responses=True)
+
+# 40 requests per 60 seconds
+app.add_middleware(
+    RateLimitMiddleware,
+    redis=r,
+    rates=Rate(40, 60),
+)
+
+@app.get("/")
+def index():
+    return {"ok": True}
+```
+
+### 2. Specific Endpoint Only
+
+To rate limit a specific route instead of the whole application, use `RateLimiter` with `Depends`:
+
+```python
+from fastapi import FastAPI, Depends
+from redis import Redis
+from p_redis_limiter import RateLimiter, Rate
+
+app = FastAPI()
+r = Redis(host="localhost", port=6379, decode_responses=True)
+
+# 5 requests per 60 seconds for login only
+login_limiter = RateLimiter(r, Rate(5, 60), prefix="rate:login")
+
+@app.get("/")
+def home():
+    return {"message": "unlimited"}
+
+@app.post("/login", dependencies=[Depends(login_limiter.as_dependency())])
+def login():
+    return {"message": "login successful"}
+```
+
+### 3. Multiple Rate Limits
+
+You can define multiple rules (e.g. 5 req/sec burst limit and 100 req/min). If one rule fails, tokens are not deducted from the others:
+
+```python
+rates = [
+    Rate(5, 1),    # 5 requests per 1 second
+    Rate(100, 60), # 100 requests per 60 seconds
+]
+
+# Or string shorthand:
+rates = ["5/s", "100/m"]
+```
+
+### 4. Cache TTL
+
+By default, Redis keys expire automatically after `max(window * 2, 60)` seconds. You can specify a custom TTL:
+
+```python
+# Per rate rule:
+Rate(40, 60, ttl=120)
+
+# Disable TTL (persist in Redis forever):
+Rate(40, 60, ttl=-1)
+
+# Or globally on middleware / limiter:
+RateLimitMiddleware(redis=r, rates=Rate(40, 60), ttl=120)
+```
+
+### 5. Manual Usage (Specify IP Yourself)
+
+If you prefer to get the IP yourself, simply pass your IP variable directly:
+
+```python
+from p_redis_limiter import RateLimiter, Rate
+
+limiter = RateLimiter(r, Rate(5, 60))
+
+@app.post("/login")
+def login(request: Request):
+    user_ip = get_my_ip(request)  # your own IP variable
+
+    # Simple boolean check:
+    if not limiter.is_allowed(user_ip):
+        return JSONResponse({"detail": "Too many requests"}, status_code=429)
+
+    return {"ok": True}
+```
+
+Or get full details (`remaining`, `retry_after`):
+
+```python
+result = limiter.check(user_ip)
+if not result.allowed:
+    print(f"Blocked! Retry after {result.retry_after}s")
+```
+
+## Options
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `redis` | `Redis` | Required | Redis client instance (`redis.Redis` or `redis.asyncio.Redis`) |
+| `rates` | `Rate` / `list` / `str` | Required | Rate rules, e.g. `Rate(40, 60)` or `["5/s", "100/m"]` |
+| `ttl` | `int` | Auto | Custom Redis key TTL in seconds |
+| `prefix` | `str` | `"rate"` | Prefix for Redis keys |
+| `identifier` | `Callable` / `str` | Client IP | Custom function or header name (auto-detects Cloudflare, Nginx, ALB, direct IP) |
+| `exclude_paths` | `list[str]` | `None` | List of paths to exclude from rate limiting |
+| `error_detail` | `str` | `"Too many requests"` | Response detail message on 429 |

p_redis_limiter-0.1.0/p_redis_limiter/__init__.py

@@ -0,0 +1,16 @@
+"""p-redis-limiter: Atomic Token Bucket Rate Limiter with Redis for Python & FastAPI."""
+
+from p_redis_limiter.limiter import RateLimitResult, RateLimiter
+from p_redis_limiter.middleware import RateLimitMiddleware, default_client_ip
+from p_redis_limiter.rate import Rate
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Rate",
+    "RateLimiter",
+    "RateLimitResult",
+    "RateLimitMiddleware",
+    "default_client_ip",
+    "__version__",
+]

p_redis_limiter-0.1.0/p_redis_limiter/limiter.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import math
+import time
+from dataclasses import dataclass
+from typing import Any, Callable, Iterable, List, Optional, Union
+
+from p_redis_limiter.lua import TOKEN_BUCKET_LUA
+from p_redis_limiter.rate import Rate
+
+try:
+    from starlette.requests import Request
+    from starlette.exceptions import HTTPException
+except ImportError:
+    Request = Any
+    HTTPException = Exception
+
+
+@dataclass(frozen=True)
+class RateLimitResult:
+    """Result of a rate limit check.
+
+    Attributes:
+        allowed: True if request is allowed, False if rate limited.
+        remaining: Remaining tokens in the bucket (minimum across all tiers).
+        retry_after: Seconds to wait before retrying (0.0 if allowed).
+        reset_in: Seconds until all buckets are fully refilled to capacity.
+    """
+
+    allowed: bool
+    remaining: int
+    retry_after: float
+    reset_in: float
+
+
+def _default_key_builder(prefix: str, identifier: str, rate: Rate, is_multi: bool) -> str:
+    if not is_multi:
+        return f"{prefix}:{identifier}"
+    return f"{prefix}:{identifier}:{rate.window_tag}"
+
+
+def _is_async_redis_client(client: Any) -> bool:
+    try:
+        from redis.asyncio import Redis as AsyncRedis, RedisCluster as AsyncRedisCluster
+        if isinstance(client, (AsyncRedis, AsyncRedisCluster)):
+            return True
+    except ImportError:
+        pass
+
+    module_name = getattr(client.__class__, "__module__", "")
+    if "asyncio" in module_name:
+        return True
+
+    for attr in ("execute_command", "eval", "evalsha"):
+        func = getattr(client, attr, None)
+        if func and inspect.iscoroutinefunction(func):
+            return True
+
+    return False
+
+
+class RateLimiter:
+    """Atomic Token Bucket Rate Limiter powered by Redis.
+
+    Supports single or multiple rate limits, automatic/custom TTL, and both
+    synchronous and asynchronous Redis clients.
+
+    Usage examples:
+        limiter = RateLimiter(r, 40, 60)
+        limiter = RateLimiter(r, Rate(40, 60))
+        limiter = RateLimiter(r, "40/m")
+
+        limiter = RateLimiter(r, rates=[Rate(5, 1), Rate(100, 60)])
+        limiter = RateLimiter(r, rates=["5/s", "100/m"])
+    """
+
+    def __init__(
+        self,
+        redis: Any,
+        *args: Any,
+        rates: Optional[Union[Rate, str, tuple[int, Union[int, float]], Iterable[Any]]] = None,
+        requests: Optional[int] = None,
+        window: Optional[Union[int, float]] = None,
+        prefix: str = "rate",
+        ttl: Optional[int] = None,
+        key_builder: Optional[Callable[[str, str, Rate, bool], str]] = None,
+    ) -> None:
+        self.redis = redis
+        self.prefix = prefix
+        self.ttl = ttl
+        self._key_builder = key_builder or _default_key_builder
+        self._is_async = _is_async_redis_client(redis)
+
+        parsed_rates: List[Rate] = []
+
+        if len(args) == 2 and isinstance(args[0], int) and isinstance(args[1], (int, float)):
+            parsed_rates.append(Rate(requests=args[0], window=float(args[1]), ttl=ttl))
+        elif len(args) == 1:
+            rates = args[0]
+
+        if rates is not None:
+            if isinstance(rates, (Rate, str, tuple)):
+                parsed_rates.append(Rate.of(rates, default_ttl=ttl))
+            elif isinstance(rates, Iterable):
+                for r in rates:
+                    parsed_rates.append(Rate.of(r, default_ttl=ttl))
+        elif requests is not None and window is not None:
+            parsed_rates.append(Rate(requests=requests, window=float(window), ttl=ttl))
+
+        if not parsed_rates:
+            raise ValueError(
+                "At least one rate must be provided. "
+                "E.g.: RateLimiter(r, 40, 60) or RateLimiter(r, rates=[Rate(5, 1), Rate(100, 60)])"
+            )
+
+        self.rates: tuple[Rate, ...] = tuple(parsed_rates)
+        self.is_multi: bool = len(self.rates) > 1
+
+        if hasattr(self.redis, "register_script"):
+            self._script = self.redis.register_script(TOKEN_BUCKET_LUA)
+        else:
+            self._script = None
+
+    @property
+    def primary_rate(self) -> Rate:
+        """The primary (first) rate configured."""
+        return self.rates[0]
+
+    def get_key(self, identifier: str, rate: Rate) -> str:
+        """Build the Redis key for an identifier and rate tier."""
+        return self._key_builder(self.prefix, identifier, rate, self.is_multi)
+
+    def _prepare_call(self, identifier: str, cost: int) -> tuple[list[str], list[Any]]:
+        if cost <= 0:
+            raise ValueError("cost must be a positive integer >= 1")
+
+        now = time.time()
+        keys = [self.get_key(identifier, r) for r in self.rates]
+
+        args: list[Any] = [now, cost]
+        for r in self.rates:
+            effective_ttl_s = r.effective_ttl(self.ttl)
+            ttl_ms = int(effective_ttl_s * 1000)
+            args.extend([r.requests, r.window, ttl_ms])
+
+        return keys, args
+
+    def _parse_result(self, raw: Any) -> RateLimitResult:
+        allowed = bool(raw[0])
+        remaining = int(raw[1])
+        retry_after = round(float(raw[2]), 4)
+        reset_in = round(float(raw[3]), 4)
+
+        return RateLimitResult(
+            allowed=allowed,
+            remaining=remaining,
+            retry_after=retry_after,
+            reset_in=reset_in,
+        )
+
+    def check(self, identifier: str, cost: int = 1) -> RateLimitResult:
+        """Check and consume rate limit synchronously.
+
+        Raises RuntimeError if initialized with an async Redis client.
+        """
+        if self._is_async:
+            raise RuntimeError(
+                "Cannot use synchronous check() with an async Redis client. "
+                "Use 'await limiter.check_async(...)' instead."
+            )
+
+        keys, args = self._prepare_call(identifier, cost)
+
+        if self._script is not None:
+            raw = self._script(keys=keys, args=args)
+        else:
+            raw = self.redis.eval(TOKEN_BUCKET_LUA, len(keys), *keys, *args)
+
+        return self._parse_result(raw)
+
+    async def check_async(self, identifier: str, cost: int = 1) -> RateLimitResult:
+        """Check and consume rate limit asynchronously.
+
+        Works with both async Redis clients (native await) and sync Redis clients
+        (dispatched to thread pool).
+        """
+        keys, args = self._prepare_call(identifier, cost)
+
+        if self._is_async:
+            if self._script is not None:
+                raw = await self._script(keys=keys, args=args)
+            else:
+                raw = await self.redis.eval(TOKEN_BUCKET_LUA, len(keys), *keys, *args)
+        else:
+            if self._script is not None:
+                raw = await asyncio.to_thread(self._script, keys=keys, args=args)
+            else:
+                raw = await asyncio.to_thread(
+                    self.redis.eval, TOKEN_BUCKET_LUA, len(keys), *keys, *args
+                )
+
+        return self._parse_result(raw)
+
+    def is_allowed(self, identifier: str, cost: int = 1) -> bool:
+        """Convenience method returning True if request is allowed, False otherwise."""
+        return self.check(identifier, cost).allowed
+
+    async def is_allowed_async(self, identifier: str, cost: int = 1) -> bool:
+        """Async convenience method returning True if request is allowed, False otherwise."""
+        res = await self.check_async(identifier, cost)
+        return res.allowed
+
+    def check_request(
+        self, request: Any, ip: Optional[str] = None, cost: int = 1
+    ) -> RateLimitResult:
+        from p_redis_limiter.middleware import default_client_ip
+        ident = ip if ip is not None else default_client_ip(request)
+        return self.check(ident, cost=cost)
+
+    async def check_request_async(
+        self, request: Any, ip: Optional[str] = None, cost: int = 1
+    ) -> RateLimitResult:
+        from p_redis_limiter.middleware import default_client_ip
+        ident = ip if ip is not None else default_client_ip(request)
+        return await self.check_async(ident, cost=cost)
+
+    def as_dependency(
+        self,
+        cost: int = 1,
+        identifier: Optional[Union[str, Callable[[Any], str]]] = None,
+        identifier_func: Optional[Callable[[Any], str]] = None,
+        error_detail: str = "Too many requests",
+    ):
+        from p_redis_limiter.middleware import default_client_ip
+
+        target_ident = identifier or identifier_func
+        if callable(target_ident):
+            ident_fn = target_ident
+        elif isinstance(target_ident, str):
+            ident_fn = lambda req: req.headers.get(target_ident) or default_client_ip(req)
+        else:
+            ident_fn = default_client_ip
+
+        async def _rate_limit_dependency(request: Request):
+            ident = ident_fn(request)
+            result = await self.check_async(ident, cost=cost)
+
+            if not result.allowed:
+                headers = {
+                    "Retry-After": str(max(1, int(math.ceil(result.retry_after)))),
+                    "X-RateLimit-Limit": str(self.primary_rate.requests),
+                    "X-RateLimit-Remaining": "0",
+                    "X-RateLimit-Reset": str(max(1, int(math.ceil(result.reset_in)))),
+                }
+                raise HTTPException(
+                    status_code=429,
+                    detail=error_detail,
+                    headers=headers,
+                )
+            return result
+
+        return _rate_limit_dependency

p_redis_limiter-0.1.0/p_redis_limiter/lua.py

@@ -0,0 +1,99 @@
+"""Atomic Multi-tier Token Bucket Lua Script for Redis."""
+
+TOKEN_BUCKET_LUA = """
+local now = tonumber(ARGV[1])
+local cost = tonumber(ARGV[2])
+local num_keys = #KEYS
+
+local allowed = 1
+local min_remaining = 999999999
+local max_retry_after = 0
+local max_reset_in = 0
+
+local buckets_tokens = {}
+local buckets_last_refill = {}
+local capacities = {}
+local windows = {}
+local ttls = {}
+
+for i = 1, num_keys do
+    local offset = 2 + (i - 1) * 3
+    local capacity = tonumber(ARGV[offset + 1])
+    local window = tonumber(ARGV[offset + 2])
+    local ttl_ms = tonumber(ARGV[offset + 3])
+
+    capacities[i] = capacity
+    windows[i] = window
+    ttls[i] = ttl_ms
+
+    local key = KEYS[i]
+    local bucket = redis.call('HMGET', key, 'tokens', 'last_refill')
+    local tokens = tonumber(bucket[1])
+    local last_refill = tonumber(bucket[2])
+
+    if tokens == nil or last_refill == nil then
+        tokens = capacity
+        last_refill = now
+    else
+        local time_passed = now - last_refill
+        if time_passed > 0 then
+            local refill_rate = capacity / window
+            tokens = math.min(capacity, tokens + (time_passed * refill_rate))
+            last_refill = now
+        end
+    end
+
+    buckets_tokens[i] = tokens
+    buckets_last_refill[i] = last_refill
+
+    if tokens < cost then
+        allowed = 0
+        local needed = cost - tokens
+        local refill_rate = capacity / window
+        local retry_after = needed / refill_rate
+        if retry_after > max_retry_after then
+            max_retry_after = retry_after
+        end
+    end
+end
+
+for i = 1, num_keys do
+    local key = KEYS[i]
+    local tokens = buckets_tokens[i]
+    local last_refill = buckets_last_refill[i]
+    local capacity = capacities[i]
+    local window = windows[i]
+    local ttl_ms = ttls[i]
+
+    if allowed == 1 then
+        tokens = tokens - cost
+        local rem = math.floor(tokens)
+        if rem < min_remaining then
+            min_remaining = rem
+        end
+    else
+        min_remaining = 0
+    end
+
+    local missing = capacity - tokens
+    if missing > 0 then
+        local reset_in = missing / (capacity / window)
+        if reset_in > max_reset_in then
+            max_reset_in = reset_in
+        end
+    end
+
+    redis.call('HSET', key, 'tokens', tostring(tokens), 'last_refill', tostring(last_refill))
+    if ttl_ms > 0 then
+        redis.call('PEXPIRE', key, ttl_ms)
+    else
+        redis.call('PERSIST', key)
+    end
+end
+
+if min_remaining == 999999999 then
+    min_remaining = 0
+end
+
+return {allowed, min_remaining, tostring(max_retry_after), tostring(max_reset_in)}
+"""

p_redis_limiter-0.1.0/p_redis_limiter/middleware.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import inspect
+import math
+from typing import Any, Awaitable, Callable, Iterable, Optional, Set, Union
+
+try:
+    from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+    from starlette.requests import Request
+    from starlette.responses import JSONResponse, Response
+    from starlette.types import ASGIApp
+    STARLETTE_AVAILABLE = True
+except ImportError:
+    STARLETTE_AVAILABLE = False
+    BaseHTTPMiddleware = object
+    RequestResponseEndpoint = Any
+    Request = Any
+    Response = Any
+    JSONResponse = Any
+    ASGIApp = Any
+
+from p_redis_limiter.limiter import RateLimitResult, RateLimiter
+from p_redis_limiter.rate import Rate
+
+
+def default_client_ip(request: Request) -> str:
+    cf_ip = request.headers.get("CF-Connecting-IP")
+    if cf_ip:
+        return cf_ip.strip()
+
+    true_client_ip = request.headers.get("True-Client-IP")
+    if true_client_ip:
+        return true_client_ip.strip()
+
+    real_ip = request.headers.get("X-Real-IP")
+    if real_ip:
+        return real_ip.strip()
+
+    forwarded = request.headers.get("X-Forwarded-For")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+
+    if request.client and request.client.host:
+        return request.client.host
+
+    return "127.0.0.1"
+
+
+class RateLimitMiddleware(BaseHTTPMiddleware):
+    """FastAPI & Starlette Middleware for Token Bucket Rate Limiting.
+
+    Usage:
+        app.add_middleware(
+            RateLimitMiddleware,
+            redis=r,
+            rates=[Rate(5, 1), Rate(40, 60)],
+        )
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        redis: Any,
+        rates: Optional[Union[Rate, str, tuple[int, Union[int, float]], Iterable[Any]]] = None,
+        *,
+        requests: Optional[int] = None,
+        window: Optional[Union[int, float]] = None,
+        prefix: str = "rate",
+        ttl: Optional[int] = None,
+        identifier: Optional[Union[str, Callable[[Request], str]]] = None,
+        error_detail: str = "Too many requests",
+        status_code: int = 429,
+        set_headers: bool = True,
+        exclude_paths: Optional[Iterable[str]] = None,
+        on_blocked: Optional[
+            Callable[[Request, RateLimitResult], Union[Response, Awaitable[Response]]]
+        ] = None,
+    ) -> None:
+        if not STARLETTE_AVAILABLE:
+            raise ImportError(
+                "Starlette/FastAPI is required to use RateLimitMiddleware. "
+                "Install it with: pip install fastapi"
+            )
+        super().__init__(app)
+
+        if isinstance(redis, RateLimiter):
+            self.limiter = redis
+        else:
+            self.limiter = RateLimiter(
+                redis=redis,
+                rates=rates,
+                requests=requests,
+                window=window,
+                prefix=prefix,
+                ttl=ttl,
+            )
+
+        if callable(identifier):
+            self.identifier = identifier
+        elif isinstance(identifier, str):
+            self.identifier = lambda req: req.headers.get(identifier) or default_client_ip(req)
+        else:
+            self.identifier = default_client_ip
+        self.error_detail = error_detail
+        self.status_code = status_code
+        self.set_headers = set_headers
+        self.exclude_paths: Set[str] = set(exclude_paths) if exclude_paths else set()
+        self.on_blocked = on_blocked
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        if self.exclude_paths and request.url.path in self.exclude_paths:
+            return await call_next(request)
+
+        ident = self.identifier(request)
+        result = await self.limiter.check_async(ident)
+
+        if not result.allowed:
+            if self.on_blocked is not None:
+                custom_resp = self.on_blocked(request, result)
+                if inspect.isawaitable(custom_resp):
+                    return await custom_resp
+                return custom_resp
+
+            headers = {}
+            if self.set_headers:
+                headers = {
+                    "Retry-After": str(max(1, int(math.ceil(result.retry_after)))),
+                    "X-RateLimit-Limit": str(self.limiter.primary_rate.requests),
+                    "X-RateLimit-Remaining": "0",
+                    "X-RateLimit-Reset": str(max(1, int(math.ceil(result.reset_in)))),
+                }
+
+            return JSONResponse(
+                {"detail": self.error_detail},
+                status_code=self.status_code,
+                headers=headers if headers else None,
+            )
+
+        response = await call_next(request)
+
+        if self.set_headers:
+            response.headers["X-RateLimit-Limit"] = str(self.limiter.primary_rate.requests)
+            response.headers["X-RateLimit-Remaining"] = str(result.remaining)
+            response.headers["X-RateLimit-Reset"] = str(max(1, int(math.ceil(result.reset_in))))
+
+        return response

p_redis_limiter-0.1.0/p_redis_limiter/rate.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass
+from typing import Any, Optional, Union
+
+_TIME_UNITS = {
+    "s": 1.0,
+    "sec": 1.0,
+    "second": 1.0,
+    "seconds": 1.0,
+    "m": 60.0,
+    "min": 60.0,
+    "minute": 60.0,
+    "minutes": 60.0,
+    "h": 3600.0,
+    "hr": 3600.0,
+    "hour": 3600.0,
+    "hours": 3600.0,
+    "d": 86400.0,
+    "day": 86400.0,
+    "days": 86400.0,
+}
+
+_RATE_REGEX = re.compile(
+    r"^\s*(\d+)\s*\/\s*(?:(\d+(?:\.\d+)?)\s*)?([a-zA-Z]+)?\s*$"
+)
+
+
+@dataclass(frozen=True)
+class Rate:
+    """Represents a rate limit rule: allowed `requests` within `window` seconds.
+
+    Args:
+        requests: Number of requests allowed within the window.
+        window: Window duration in seconds (int or float).
+        ttl: Optional custom TTL in seconds for Redis cache.
+             If not set, defaults to max(ceil(window * 2), 60).
+    """
+
+    requests: int
+    window: float
+    ttl: Optional[int] = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.requests, int) or self.requests <= 0:
+            raise ValueError(f"requests must be a positive integer > 0, got: {self.requests}")
+        if self.window <= 0:
+            raise ValueError(f"window must be a positive number > 0, got: {self.window}")
+        if self.ttl is not None and self.ttl < -1:
+            raise ValueError(f"ttl must be a positive integer, 0, or -1 (to disable TTL), got: {self.ttl}")
+
+    def effective_ttl(self, default_ttl: Optional[int] = None) -> int:
+        target = self.ttl if self.ttl is not None else default_ttl
+        if target is not None:
+            return 0 if target in (0, -1) else int(target)
+        return max(int(math.ceil(self.window * 2)), 60)
+
+    @property
+    def window_tag(self) -> str:
+        """Compact string representation of the window duration for key suffix."""
+        if float(self.window).is_integer():
+            return f"{int(self.window)}s"
+        return f"{self.window}s"
+
+    @classmethod
+    def parse(cls, rate_str: str, ttl: Optional[int] = None) -> Rate:
+        """Parse human-friendly rate string such as '5/s', '40/minute', '100/10s'.
+
+        Examples:
+            Rate.parse("5/s") -> Rate(requests=5, window=1.0)
+            Rate.parse("40/minute") -> Rate(requests=40, window=60.0)
+            Rate.parse("10/2m") -> Rate(requests=10, window=120.0)
+            Rate.parse("100/30s", ttl=120) -> Rate(requests=100, window=30.0, ttl=120)
+        """
+        match = _RATE_REGEX.match(rate_str.strip())
+        if not match:
+            raise ValueError(
+                f"Invalid rate limit string: '{rate_str}'. "
+                "Expected format like '5/s', '40/minute', '100/30s', etc."
+            )
+
+        req_str, mult_str, unit_str = match.groups()
+        requests = int(req_str)
+
+        multiplier = float(mult_str) if mult_str else 1.0
+
+        if unit_str:
+            unit_lower = unit_str.lower()
+            if unit_lower not in _TIME_UNITS:
+                valid = ", ".join(_TIME_UNITS.keys())
+                raise ValueError(
+                    f"Unknown time unit '{unit_str}' in rate '{rate_str}'. Valid units: {valid}"
+                )
+            base_seconds = _TIME_UNITS[unit_lower]
+        else:
+            base_seconds = 1.0
+
+        window = multiplier * base_seconds
+        return cls(requests=requests, window=window, ttl=ttl)
+
+    @classmethod
+    def of(cls, value: Union[Rate, str, tuple[int, Union[int, float]], list[Any]], default_ttl: Optional[int] = None) -> Rate:
+        """Convert various input types into a Rate instance."""
+        if isinstance(value, Rate):
+            if value.ttl is None and default_ttl is not None:
+                return cls(requests=value.requests, window=value.window, ttl=default_ttl)
+            return value
+        if isinstance(value, str):
+            return cls.parse(value, ttl=default_ttl)
+        if isinstance(value, (tuple, list)) and len(value) >= 2:
+            custom_ttl = value[2] if len(value) > 2 else default_ttl
+            return cls(requests=int(value[0]), window=float(value[1]), ttl=custom_ttl)
+        raise TypeError(
+            f"Cannot convert {type(value).__name__} to Rate. "
+            "Pass a Rate instance, a string (e.g. '40/m'), or a (requests, window) tuple."
+        )
+
+    def __str__(self) -> str:
+        return f"{self.requests}/{self.window_tag}"

p_redis_limiter-0.1.0/p_redis_limiter.egg-info/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: p-redis-limiter
+Version: 0.1.0
+Summary: A fast, atomic, multi-tier Token Bucket rate limiter for Python and FastAPI using Redis.
+Author: Mehran
+License: MIT
+Keywords: redis,rate-limiter,token-bucket,fastapi,throttling
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: redis>=4.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
+Requires-Dist: httpx>=0.23.0; extra == "dev"
+Requires-Dist: fastapi>=0.70.0; extra == "dev"
+
+# p-redis-limiter
+
+Redis token bucket rate limiter for Python and FastAPI.
+
+## Installation
+
+```bash
+pip install git+https://github.com/mehranpng/p-redis-limiter.git
+```
+
+## Usage
+
+### 1. Global Middleware (All Endpoints)
+
+Apply a rate limit across all endpoints:
+
+```python
+from fastapi import FastAPI
+from redis import Redis
+from p_redis_limiter import RateLimitMiddleware, Rate
+
+app = FastAPI()
+r = Redis(host="localhost", port=6379, decode_responses=True)
+
+# 40 requests per 60 seconds
+app.add_middleware(
+    RateLimitMiddleware,
+    redis=r,
+    rates=Rate(40, 60),
+)
+
+@app.get("/")
+def index():
+    return {"ok": True}
+```
+
+### 2. Specific Endpoint Only
+
+To rate limit a specific route instead of the whole application, use `RateLimiter` with `Depends`:
+
+```python
+from fastapi import FastAPI, Depends
+from redis import Redis
+from p_redis_limiter import RateLimiter, Rate
+
+app = FastAPI()
+r = Redis(host="localhost", port=6379, decode_responses=True)
+
+# 5 requests per 60 seconds for login only
+login_limiter = RateLimiter(r, Rate(5, 60), prefix="rate:login")
+
+@app.get("/")
+def home():
+    return {"message": "unlimited"}
+
+@app.post("/login", dependencies=[Depends(login_limiter.as_dependency())])
+def login():
+    return {"message": "login successful"}
+```
+
+### 3. Multiple Rate Limits
+
+You can define multiple rules (e.g. 5 req/sec burst limit and 100 req/min). If one rule fails, tokens are not deducted from the others:
+
+```python
+rates = [
+    Rate(5, 1),    # 5 requests per 1 second
+    Rate(100, 60), # 100 requests per 60 seconds
+]
+
+# Or string shorthand:
+rates = ["5/s", "100/m"]
+```
+
+### 4. Cache TTL
+
+By default, Redis keys expire automatically after `max(window * 2, 60)` seconds. You can specify a custom TTL:
+
+```python
+# Per rate rule:
+Rate(40, 60, ttl=120)
+
+# Disable TTL (persist in Redis forever):
+Rate(40, 60, ttl=-1)
+
+# Or globally on middleware / limiter:
+RateLimitMiddleware(redis=r, rates=Rate(40, 60), ttl=120)
+```
+
+### 5. Manual Usage (Specify IP Yourself)
+
+If you prefer to get the IP yourself, simply pass your IP variable directly:
+
+```python
+from p_redis_limiter import RateLimiter, Rate
+
+limiter = RateLimiter(r, Rate(5, 60))
+
+@app.post("/login")
+def login(request: Request):
+    user_ip = get_my_ip(request)  # your own IP variable
+
+    # Simple boolean check:
+    if not limiter.is_allowed(user_ip):
+        return JSONResponse({"detail": "Too many requests"}, status_code=429)
+
+    return {"ok": True}
+```
+
+Or get full details (`remaining`, `retry_after`):
+
+```python
+result = limiter.check(user_ip)
+if not result.allowed:
+    print(f"Blocked! Retry after {result.retry_after}s")
+```
+
+## Options
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `redis` | `Redis` | Required | Redis client instance (`redis.Redis` or `redis.asyncio.Redis`) |
+| `rates` | `Rate` / `list` / `str` | Required | Rate rules, e.g. `Rate(40, 60)` or `["5/s", "100/m"]` |
+| `ttl` | `int` | Auto | Custom Redis key TTL in seconds |
+| `prefix` | `str` | `"rate"` | Prefix for Redis keys |
+| `identifier` | `Callable` / `str` | Client IP | Custom function or header name (auto-detects Cloudflare, Nginx, ALB, direct IP) |
+| `exclude_paths` | `list[str]` | `None` | List of paths to exclude from rate limiting |
+| `error_detail` | `str` | `"Too many requests"` | Response detail message on 429 |

p_redis_limiter-0.1.0/p_redis_limiter.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+p_redis_limiter/__init__.py
+p_redis_limiter/limiter.py
+p_redis_limiter/lua.py
+p_redis_limiter/middleware.py
+p_redis_limiter/py.typed
+p_redis_limiter/rate.py
+p_redis_limiter.egg-info/PKG-INFO
+p_redis_limiter.egg-info/SOURCES.txt
+p_redis_limiter.egg-info/dependency_links.txt
+p_redis_limiter.egg-info/requires.txt
+p_redis_limiter.egg-info/top_level.txt

p_redis_limiter-0.1.0/p_redis_limiter.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

p_redis_limiter-0.1.0/p_redis_limiter.egg-info/requires.txt

@@ -0,0 +1,7 @@
+redis>=4.2.0
+
+[dev]
+pytest>=7.0.0
+pytest-asyncio>=0.20.0
+httpx>=0.23.0
+fastapi>=0.70.0

p_redis_limiter-0.1.0/p_redis_limiter.egg-info/top_level.txt

@@ -0,0 +1 @@
+p_redis_limiter

p_redis_limiter-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "p-redis-limiter"
+version = "0.1.0"
+description = "A fast, atomic, multi-tier Token Bucket rate limiter for Python and FastAPI using Redis."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Mehran" }
+]
+keywords = ["redis", "rate-limiter", "token-bucket", "fastapi", "throttling"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Framework :: FastAPI",
+]
+dependencies = [
+    "redis>=4.2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.20.0",
+    "httpx>=0.23.0",
+    "fastapi>=0.70.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["p_redis_limiter*"]
+
+[tool.setuptools.package-data]
+p_redis_limiter = ["py.typed"]

p_redis_limiter-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+