fastapi-sluice 0.1.0__tar.gz

fastapi_sluice-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.3
+Name: fastapi-sluice
+Version: 0.1.0
+Summary: FastAPI rate limiter backed by Redis
+Author: Dennis Wainaina
+Author-email: Dennis Wainaina <dennis@byteslab.io>
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: redis>=4.5.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# FastAPI Sluice
+
+**Redis-backed, purely async rate limiting for FastAPI.**
+
+<p align="center">
+<img src="docs/assets/logo.svg" alt="logo" width="250" height="250">
+</p>
+
+[![CI](https://github.com/dennis-nw/fastapi-sluice/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/dennis-nw/fastapi-sluice/actions/workflows/ci.yml)
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue&logo=redis)](https://www.python.org/downloads/)
+[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v0.json)](https://astral.sh/ruff)
+[![Checked with ty](https://img.shields.io/badge/checked%20with-ty-262626?style=flat&logo=python&logoColor=3776AB)](https://github.com/astral-sh/ty)
+
+FastAPI Sluice is designed for modern async FastAPI applications,
+providing production-ready Redis-backed rate limiting with
+interchangeable algorithms and atomic Lua execution.
+
+## Features
+
+- ⚡️ **100% async** - built for FastAPI's async request lifecycle.
+- 🌍 **Global or per-route limits** — protect your entire API or individual
+  endpoints with the same API.
+- 🔒 **Atomic Redis operations** — Every rate-limiting decision executes
+  inside Redis using Lua, guaranteeing atomic updates under concurrent load
+  without race conditions.
+- 🔄 **Three Interchangeable algorithms** - Choose the algorithm that best matches
+  your traffic profile and resource constraints. Sluice ships out of the box with the
+  three widely used rate-limiting algorithms: Fixed window, sliding window log,
+  and token bucket, all swappable behind a single `RateLimiter` API.
+- 🧩 **Flexible identity** — Limit by IP, API key, or any other custom
+  attribute. You can also rate limit per-route or globally across your entire API.
+
+## Requirements
+
+| Dependency   | Supported Versions |
+|--------------|--------------------|
+| Python       | 3.10+              |
+| FastAPI      | 0.100+             |
+| Redis server | 7.4+               |
+| redis-py     | 4.5+               |
+
+## Installation
+
+Using uv (recommended):
+
+```bash
+uv add fastapi-sluice
+```
+
+Using pip:
+
+```bash
+pip install fastapi-sluice
+```
+
+Using Poetry:
+
+```bash
+poetry add fastapi-sluice
+```
+
+## Usage
+
+Start by connecting to a Redis server and creating a `RateLimiter` instance:
+
+```python
+from redis.asyncio import Redis
+from fastapi_sluice import RateLimiter, FixedWindow, SlidingWindow, TokenBucket
+
+redis = Redis(host="localhost", port=6379)
+limiter = RateLimiter(redis=redis)
+```
+
+### Per-route limiting
+
+Apply a limit to a specific route by passing `limiter.limit()` as a dependency.
+Each route gets its own counter, keyed by IP address by default.
+You can pass a `scope` string to group requests to use the same counter.
+By default, the request path is used. Use `scope` when you want multiple
+routes or parameterized URLs to share the same counter.
+
+```python
+from fastapi import FastAPI, Depends
+from fastapi_sluice import FixedWindow
+
+app = FastAPI()
+
+@app.get("/items")
+async def get_items(_=Depends(limiter.limit(algorithm=FixedWindow(limit=5, window_seconds=60), scope="items"))):
+    return {"items": []}
+```
+
+### Global limiting
+
+Use `RateLimitMiddleware` to enforce an API-wide cap that applies to every route.
+A single counter per identity is shared across all endpoints:
+
+```python
+from fastapi_sluice import RateLimitMiddleware, SlidingWindow
+
+app.add_middleware(
+    RateLimitMiddleware,
+    limiter=limiter,
+    algorithm=SlidingWindow(limit=500, window_seconds=60),
+)
+```
+
+### Choosing an algorithm
+
+Each algorithm suits a different traffic profile:
+
+```python
+from fastapi_sluice import FixedWindow, SlidingWindow, TokenBucket
+
+# Fixed window — simplest, cheapest. Best for low-stakes limits.
+FixedWindow(limit=100, window_seconds=60)
+
+# Sliding window — accurate per-second fairness, no boundary bursts.
+SlidingWindow(limit=100, window_seconds=60)
+
+# Token bucket — sustain a rate while allowing controlled bursts.
+TokenBucket(capacity=50, refill_rate=10)  # 10 req/s, burst up to 50
+```
+
+| Algorithm | Performance / Memory | Precision & Fairness | Best Used For |
+|---|---|---|---|
+| Fixed Window | `O(1)` time and space | Low — susceptible to boundary bursting | Standard API protection where perfection isn't critical |
+| Sliding Window | `O(N)` space per user, higher memory cost | Highest — accurate across shifting time windows | Critical or expensive endpoints (e.g. AI generation, payment processing) |
+| Token Bucket | `O(1)` time and space | High — allows controlled traffic bursts | General-purpose API protection and microservices |
+
+### Rate limit responses
+
+When a client exceeds the limit, Sluice returns a `429 Too Many Requests` response with the following headers:
+
+| Header | Description |
+|---|---|
+| `Retry-After` | Seconds to wait before retrying |
+| `X-RateLimit-Limit` | Maximum requests allowed in the window |
+| `X-RateLimit-Remaining` | Requests remaining in the current window |
+
+Example response:
+
+```http
+HTTP/1.1 429 Too Many Requests
+Retry-After: 30
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 0
+
+{"detail": "Too many requests"}
+```
+
+### Custom Client Identifier
+
+You can override the default IP-based key with any attribute like API key or
+user ID. The callable must return a **unique string** per identity since this value
+becomes the rate limit bucket key in Redis. Just create a sync or async callable:
+
+```python
+from fastapi import Request
+
+def get_api_key(request: Request) -> str:
+    api_key = request.headers.get("X-API-Key")
+    if api_key is None:
+        raise ValueError("X-API-Key header is missing")
+    return api_key
+
+@app.get("/items")
+async def get_items(_=Depends(limiter.limit(algorithm=FixedWindow(limit=30, window_seconds=60), key_func=get_api_key))):
+    return {"items": []}
+```

fastapi_sluice-0.1.0/README.md

@@ -0,0 +1,171 @@
+# FastAPI Sluice
+
+**Redis-backed, purely async rate limiting for FastAPI.**
+
+<p align="center">
+<img src="docs/assets/logo.svg" alt="logo" width="250" height="250">
+</p>
+
+[![CI](https://github.com/dennis-nw/fastapi-sluice/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/dennis-nw/fastapi-sluice/actions/workflows/ci.yml)
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue&logo=redis)](https://www.python.org/downloads/)
+[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v0.json)](https://astral.sh/ruff)
+[![Checked with ty](https://img.shields.io/badge/checked%20with-ty-262626?style=flat&logo=python&logoColor=3776AB)](https://github.com/astral-sh/ty)
+
+FastAPI Sluice is designed for modern async FastAPI applications,
+providing production-ready Redis-backed rate limiting with
+interchangeable algorithms and atomic Lua execution.
+
+## Features
+
+- ⚡️ **100% async** - built for FastAPI's async request lifecycle.
+- 🌍 **Global or per-route limits** — protect your entire API or individual
+  endpoints with the same API.
+- 🔒 **Atomic Redis operations** — Every rate-limiting decision executes
+  inside Redis using Lua, guaranteeing atomic updates under concurrent load
+  without race conditions.
+- 🔄 **Three Interchangeable algorithms** - Choose the algorithm that best matches
+  your traffic profile and resource constraints. Sluice ships out of the box with the
+  three widely used rate-limiting algorithms: Fixed window, sliding window log,
+  and token bucket, all swappable behind a single `RateLimiter` API.
+- 🧩 **Flexible identity** — Limit by IP, API key, or any other custom
+  attribute. You can also rate limit per-route or globally across your entire API.
+
+## Requirements
+
+| Dependency   | Supported Versions |
+|--------------|--------------------|
+| Python       | 3.10+              |
+| FastAPI      | 0.100+             |
+| Redis server | 7.4+               |
+| redis-py     | 4.5+               |
+
+## Installation
+
+Using uv (recommended):
+
+```bash
+uv add fastapi-sluice
+```
+
+Using pip:
+
+```bash
+pip install fastapi-sluice
+```
+
+Using Poetry:
+
+```bash
+poetry add fastapi-sluice
+```
+
+## Usage
+
+Start by connecting to a Redis server and creating a `RateLimiter` instance:
+
+```python
+from redis.asyncio import Redis
+from fastapi_sluice import RateLimiter, FixedWindow, SlidingWindow, TokenBucket
+
+redis = Redis(host="localhost", port=6379)
+limiter = RateLimiter(redis=redis)
+```
+
+### Per-route limiting
+
+Apply a limit to a specific route by passing `limiter.limit()` as a dependency.
+Each route gets its own counter, keyed by IP address by default.
+You can pass a `scope` string to group requests to use the same counter.
+By default, the request path is used. Use `scope` when you want multiple
+routes or parameterized URLs to share the same counter.
+
+```python
+from fastapi import FastAPI, Depends
+from fastapi_sluice import FixedWindow
+
+app = FastAPI()
+
+@app.get("/items")
+async def get_items(_=Depends(limiter.limit(algorithm=FixedWindow(limit=5, window_seconds=60), scope="items"))):
+    return {"items": []}
+```
+
+### Global limiting
+
+Use `RateLimitMiddleware` to enforce an API-wide cap that applies to every route.
+A single counter per identity is shared across all endpoints:
+
+```python
+from fastapi_sluice import RateLimitMiddleware, SlidingWindow
+
+app.add_middleware(
+    RateLimitMiddleware,
+    limiter=limiter,
+    algorithm=SlidingWindow(limit=500, window_seconds=60),
+)
+```
+
+### Choosing an algorithm
+
+Each algorithm suits a different traffic profile:
+
+```python
+from fastapi_sluice import FixedWindow, SlidingWindow, TokenBucket
+
+# Fixed window — simplest, cheapest. Best for low-stakes limits.
+FixedWindow(limit=100, window_seconds=60)
+
+# Sliding window — accurate per-second fairness, no boundary bursts.
+SlidingWindow(limit=100, window_seconds=60)
+
+# Token bucket — sustain a rate while allowing controlled bursts.
+TokenBucket(capacity=50, refill_rate=10)  # 10 req/s, burst up to 50
+```
+
+| Algorithm | Performance / Memory | Precision & Fairness | Best Used For |
+|---|---|---|---|
+| Fixed Window | `O(1)` time and space | Low — susceptible to boundary bursting | Standard API protection where perfection isn't critical |
+| Sliding Window | `O(N)` space per user, higher memory cost | Highest — accurate across shifting time windows | Critical or expensive endpoints (e.g. AI generation, payment processing) |
+| Token Bucket | `O(1)` time and space | High — allows controlled traffic bursts | General-purpose API protection and microservices |
+
+### Rate limit responses
+
+When a client exceeds the limit, Sluice returns a `429 Too Many Requests` response with the following headers:
+
+| Header | Description |
+|---|---|
+| `Retry-After` | Seconds to wait before retrying |
+| `X-RateLimit-Limit` | Maximum requests allowed in the window |
+| `X-RateLimit-Remaining` | Requests remaining in the current window |
+
+Example response:
+
+```http
+HTTP/1.1 429 Too Many Requests
+Retry-After: 30
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 0
+
+{"detail": "Too many requests"}
+```
+
+### Custom Client Identifier
+
+You can override the default IP-based key with any attribute like API key or
+user ID. The callable must return a **unique string** per identity since this value
+becomes the rate limit bucket key in Redis. Just create a sync or async callable:
+
+```python
+from fastapi import Request
+
+def get_api_key(request: Request) -> str:
+    api_key = request.headers.get("X-API-Key")
+    if api_key is None:
+        raise ValueError("X-API-Key header is missing")
+    return api_key
+
+@app.get("/items")
+async def get_items(_=Depends(limiter.limit(algorithm=FixedWindow(limit=30, window_seconds=60), key_func=get_api_key))):
+    return {"items": []}
+```

fastapi_sluice-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "fastapi-sluice"
+version = "0.1.0"
+description = "FastAPI rate limiter backed by Redis"
+readme = "README.md"
+authors = [
+    { name = "Dennis Wainaina", email = "dennis@byteslab.io" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.100.0",
+    "redis>=4.5.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.17,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[dependency-groups]
+dev = [
+    "fakeredis[lua]>=2.36.2",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.15.18",
+    "ty>=0.0.53",
+]

fastapi_sluice-0.1.0/src/fastapi_sluice/__init__.py

@@ -0,0 +1,19 @@
+"""
+Public API lives here so users do:
+    from fastapi_sluice import RateLimiter, TokenBucket, SlidingWindow
+instead of reaching into submodules.
+"""
+
+from fastapi_sluice.algorithms.fixed_window import FixedWindow
+from fastapi_sluice.algorithms.sliding_window import SlidingWindow
+from fastapi_sluice.algorithms.token_bucket import TokenBucket
+from fastapi_sluice.limiter import RateLimiter
+from fastapi_sluice.middleware import RateLimitMiddleware
+
+__all__ = [
+    "FixedWindow",
+    "RateLimitMiddleware",
+    "RateLimiter",
+    "SlidingWindow",
+    "TokenBucket",
+]

fastapi_sluice-0.1.0/src/fastapi_sluice/algorithms/base.py

@@ -0,0 +1,43 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+from redis.asyncio import Redis
+
+
+@dataclass(frozen=True)
+class RateLimitResult:
+    """
+    Outcome of a rate-limit check
+    """
+
+    allowed: bool
+    limit: int
+    remaining: int
+    retry_after: int  # seconds; 0 if allowed
+
+
+class RateLimitAlgorithm(ABC):
+    """
+    Base class for a rate-limiting algorithm
+    """
+
+    def __init__(self, limit: int, window_seconds: int) -> None:
+        """
+        Args:
+            limit: max requests allowed per window e.g. 5 for "5 per second"
+            window_seconds: window size in seconds e.g. 1 for "per second"
+        """
+        if limit <= 0:
+            raise ValueError("limit must be greater than 0")
+        if window_seconds <= 0:
+            raise ValueError("window_seconds must be greater than 0")
+        self.limit = limit
+        self.window_seconds = window_seconds
+
+    @abstractmethod
+    async def check(self, redis: Redis, key: str) -> RateLimitResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def peek(self, redis: Redis, key: str) -> RateLimitResult:
+        raise NotImplementedError

fastapi_sluice-0.1.0/src/fastapi_sluice/algorithms/fixed_window.py

@@ -0,0 +1,46 @@
+import time
+
+from redis.asyncio import Redis
+
+from fastapi_sluice.algorithms.base import RateLimitAlgorithm, RateLimitResult
+from fastapi_sluice.lua import get_script
+
+
+class FixedWindow(RateLimitAlgorithm):
+    def _window_key(self, key: str) -> str:
+        bucket = int(time.time() // self.window_seconds)
+        return f"{key}:{bucket}"
+
+    async def check(self, redis: Redis, key: str) -> RateLimitResult:
+        window_key = self._window_key(key=key)
+
+        script = get_script(redis=redis, name="fixed_window")
+        allowed, remaining, retry_after = await script(
+            keys=[window_key], args=[self.limit, self.window_seconds]
+        )
+
+        return RateLimitResult(
+            allowed=bool(allowed),
+            limit=self.limit,
+            remaining=int(remaining),
+            retry_after=int(retry_after),
+        )
+
+    async def peek(self, redis: Redis, key: str) -> RateLimitResult:
+        window_key = self._window_key(key=key)
+
+        count = int(await redis.get(window_key) or 0)
+        remaining = max(0, self.limit - count)
+
+        retry_after = 0
+        if remaining == 0:
+            ttl = await redis.ttl(window_key)
+            if ttl > 0:
+                retry_after = ttl
+
+        return RateLimitResult(
+            allowed=remaining > 0,
+            limit=self.limit,
+            remaining=remaining,
+            retry_after=retry_after,
+        )

fastapi_sluice-0.1.0/src/fastapi_sluice/algorithms/sliding_window.py

@@ -0,0 +1,48 @@
+import math
+import time
+
+from redis.asyncio import Redis
+
+from fastapi_sluice.algorithms.base import RateLimitAlgorithm, RateLimitResult
+from fastapi_sluice.lua import get_script
+
+
+class SlidingWindow(RateLimitAlgorithm):
+    async def check(self, redis: Redis, key: str) -> RateLimitResult:
+        script = get_script(redis=redis, name="sliding_window")
+        allowed, remaining, retry_after = await script(
+            keys=[key], args=[self.limit, self.window_seconds, int(time.time())]
+        )
+
+        return RateLimitResult(
+            allowed=bool(allowed),
+            limit=self.limit,
+            remaining=int(remaining),
+            retry_after=int(retry_after),
+        )
+
+    async def peek(self, redis: Redis, key: str) -> RateLimitResult:
+        now = int(time.time())
+        window_start = now - self.window_seconds
+
+        await redis.zremrangebyscore(key, 0, window_start)
+        count = int(await redis.zcard(key) or 0)
+        remaining = max(0, self.limit - count)
+
+        retry_after = 0
+        if remaining == 0:
+            oldest = await redis.zrange(key, 0, 0, withscores=True)
+            if oldest:
+                if isinstance(oldest[0][1], (int, float)):
+                    retry_after = max(
+                        0, math.ceil((oldest[0][1] + self.window_seconds) - now)
+                    )
+            else:
+                retry_after = self.window_seconds
+
+        return RateLimitResult(
+            allowed=remaining > 0,
+            limit=self.limit,
+            remaining=remaining,
+            retry_after=retry_after,
+        )

fastapi_sluice-0.1.0/src/fastapi_sluice/algorithms/token_bucket.py

@@ -0,0 +1,59 @@
+import math
+import time
+
+from redis.asyncio import Redis
+
+from fastapi_sluice.algorithms.base import RateLimitAlgorithm, RateLimitResult
+from fastapi_sluice.lua import get_script
+
+
+class TokenBucket(RateLimitAlgorithm):
+    def __init__(self, capacity: int, refill_rate: float) -> None:
+        """
+        Args:
+            capacity: maximum number of tokens the bucket holds
+            refill_rate: tokens added per second
+        """
+        if capacity <= 0:
+            raise ValueError("capacity must be greater than 0")
+        if refill_rate <= 0:
+            raise ValueError("refill_rate must be greater than 0")
+        self.capacity = capacity
+        self.refill_rate = refill_rate
+
+    async def check(self, redis: Redis, key: str) -> RateLimitResult:
+        script = get_script(redis=redis, name="token_bucket")
+        allowed, remaining, retry_after = await script(
+            keys=[key], args=[self.capacity, self.refill_rate, int(time.time())]
+        )
+
+        return RateLimitResult(
+            allowed=bool(allowed),
+            limit=self.capacity,
+            remaining=int(remaining),
+            retry_after=int(retry_after),
+        )
+
+    async def peek(self, redis: Redis, key: str) -> RateLimitResult:
+        now = int(time.time())
+
+        bucket = await redis.hmget(key, "tokens", "last_refill")
+        tokens = float(bucket[0]) if bucket[0] is not None else float(self.capacity)
+        last_refill = float(bucket[1]) if bucket[1] is not None else now
+
+        elapsed = now - last_refill
+        tokens = min(tokens + elapsed * self.refill_rate, self.capacity)
+
+        remaining = int(tokens)
+        allowed = remaining >= 1
+
+        retry_after = 0
+        if not allowed:
+            retry_after = math.ceil((1 - tokens) / self.refill_rate)
+
+        return RateLimitResult(
+            allowed=allowed,
+            limit=self.capacity,
+            remaining=remaining,
+            retry_after=retry_after,
+        )

fastapi_sluice-0.1.0/src/fastapi_sluice/limiter.py

@@ -0,0 +1,103 @@
+import asyncio
+from typing import Awaitable, Callable
+
+from fastapi import HTTPException, Request, status
+from redis.asyncio import Redis
+
+from fastapi_sluice.algorithms.base import RateLimitAlgorithm
+
+KeyFunc = Callable[[Request], Awaitable[str] | str]
+
+
+def _default_key_func(request: Request) -> str:
+    """
+    Default identifier: client IP address
+    """
+    forwarded = request.headers.get("X-Forwarded-For")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+    if request.client:
+        return request.client.host
+    raise ValueError("Could not determine client identity from request")
+
+
+class RateLimiter:
+    def __init__(self, redis: Redis, namespace: str = "sluice"):
+        self.redis = redis
+        self.namespace = namespace
+
+    def limit(
+        self,
+        algorithm: RateLimitAlgorithm,
+        scope: str | None = None,
+        key_func: KeyFunc = _default_key_func,
+    ) -> Callable[[Request], Awaitable[None]]:
+        """
+        Returns a FastAPI dependency that enforces a per-route rate limit.
+
+        Args:
+            algorithm: the rate limiting algorithm to use e.g. FixedWindow, SlidingWindow, TokenBucket
+            scope: optional string to group requests into a shared bucket e.g. "monitors".
+                   Defaults to the request URL path, giving each unique URL its own counter.
+            key_func: callable that extracts a unique identity from the request e.g. IP, user ID.
+                      Defaults to the client IP address.
+        """
+
+        async def dependency(request: Request) -> None:
+            if asyncio.iscoroutinefunction(key_func):
+                identity = await key_func(request)
+            else:
+                identity = key_func(request)
+
+            route_segment = scope or request.url.path
+            redis_key = f"{self.namespace}:{route_segment}:{identity}"
+
+            result = await algorithm.check(redis=self.redis, key=redis_key)
+
+            if not result.allowed:
+                headers = {
+                    "Retry-After": str(result.retry_after),
+                    "X-RateLimit-Limit": str(result.limit),
+                    "X-RateLimit-Remaining": str(result.remaining),
+                }
+                raise HTTPException(
+                    status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                    detail="Too many requests",
+                    headers=headers,
+                )
+
+        return dependency
+
+    async def limit_global(
+        self,
+        request: Request,
+        algorithm: RateLimitAlgorithm,
+        key_func: KeyFunc = _default_key_func,
+    ) -> tuple[bool, dict]:
+        """
+        Checks a global rate limit shared across all routes. Intended for use in middleware.
+
+        Args:
+            request: the incoming FastAPI/Starlette request
+            algorithm: the rate limiting algorithm to use e.g. FixedWindow, SlidingWindow, TokenBucket
+            key_func: callable that extracts a unique identity from the request e.g. IP, user ID.
+                      Defaults to the client IP address.
+
+        Returns:
+            A tuple of (allowed, headers) where headers contains the X-RateLimit-* and Retry-After values.
+        """
+        if asyncio.iscoroutinefunction(key_func):
+            identity = await key_func(request)
+        else:
+            identity = key_func(request)
+
+        redis_key = f"{self.namespace}:global:{identity}"
+        result = await algorithm.check(redis=self.redis, key=redis_key)
+
+        headers = {
+            "Retry-After": str(result.retry_after),
+            "X-RateLimit-Limit": str(result.limit),
+            "X-RateLimit-Remaining": str(result.remaining),
+        }
+
+        return result.allowed, headers

fastapi_sluice-0.1.0/src/fastapi_sluice/lua/__init__.py

@@ -0,0 +1,11 @@
+from pathlib import Path
+
+from redis.asyncio import Redis
+from redis.commands.core import AsyncScript
+
+LUA_DIR = Path(__file__).parent
+
+
+def get_script(redis: Redis, name: str) -> AsyncScript:
+    script = (LUA_DIR / f"{name}.lua").read_text()
+    return redis.register_script(script)

fastapi_sluice-0.1.0/src/fastapi_sluice/lua/fixed_window.lua

@@ -0,0 +1,31 @@
+-- Fixed window: atomic check-and-consume
+-- KEYS[1] = window key
+-- ARGV[1] = limit i.e. max requests per window
+-- ARGV[2] = window size in seconds
+--
+-- Returns: { allowed (0/1), remaining, retry_after_seconds }
+
+local limit = tonumber(ARGV[1])
+local window = tonumber(ARGV[2])
+
+local count = redis.call("INCR", KEYS[1])
+
+if count == 1 then
+    redis.call("EXPIRE", KEYS[1], window)
+end
+
+local allowed = 0   -- false
+local retry_after = 0
+
+if count <= limit then
+    allowed = 1
+else
+    retry_after = redis.call("TTL", KEYS[1])
+    if retry_after < 0 then
+        retry_after = window
+    end
+end
+
+local remaining = math.max(0, limit - count)
+
+return { allowed, remaining, retry_after }

fastapi_sluice-0.1.0/src/fastapi_sluice/lua/sliding_window.lua

@@ -0,0 +1,39 @@
+-- Sliding window log: atomic check-and-consume
+--
+-- KEYS[1] = rate limit key
+-- ARGV[1] = limit (max requests per window)
+-- ARGV[2] = window size in seconds
+-- ARGV[3] = now (unix timestamp)
+--
+-- Returns: { allowed (0/1), remaining, retry_after_seconds }
+
+local limit = tonumber(ARGV[1])
+local window_seconds = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+local window_start = now - window_seconds
+
+-- Evict expired entries then count what remains in the window
+redis.call("ZREMRANGEBYSCORE", KEYS[1], 0, window_start)
+
+local count = redis.call("ZCARD", KEYS[1])
+
+local allowed = 0
+local retry_after = 0
+local remaining = 0
+
+if count < limit then
+    allowed = 1
+    redis.call("ZADD", KEYS[1], now, tostring(now) .. ":" .. tostring(count))
+    redis.call("EXPIRE", KEYS[1], window_seconds)
+
+    remaining = limit - count - 1
+else
+    local oldest = redis.call("ZRANGE", KEYS[1], 0, 0, "WITHSCORES")
+    if oldest[2] then
+        retry_after = math.ceil((tonumber(oldest[2]) + window_seconds) - now)
+    else
+        retry_after = window_seconds
+    end
+end
+
+return { allowed, remaining, retry_after }

fastapi_sluice-0.1.0/src/fastapi_sluice/lua/token_bucket.lua

@@ -0,0 +1,46 @@
+-- Token Bucket
+--
+-- KEYS[1] = bucket key
+-- ARGV[1] = capacity (maximum number of tokens)
+-- ARGV[2] = refill_rate (tokens per second)
+-- ARGV[3] = now (unix timestamp)
+--
+-- Returns: { allowed (0/1), remaining_tokens, retry_after_seconds }
+
+local bucket_key = KEYS[1]
+local capacity = tonumber(ARGV[1])
+local refill_rate = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+
+local bucket = redis.call("HMGET", bucket_key, "tokens", "last_refill")
+
+local tokens = tonumber(bucket[1])
+local last_refill = tonumber(bucket[2])
+
+-- first request, bucket starts full
+if tokens == nil or last_refill == nil then
+    tokens = capacity
+    last_refill = now
+end
+
+-- refill
+local elapsed = now - last_refill
+local refill_tokens = elapsed * refill_rate
+tokens = math.min(tokens + refill_tokens, capacity)
+
+local allowed = 0   -- false
+local retry_after = 0
+
+if tokens >= 1 then
+    allowed = 1
+    tokens = tokens - 1
+
+    redis.call("HSET", bucket_key, "tokens", tokens, "last_refill", now)
+
+    local ttl = math.ceil(capacity / refill_rate) + 60
+    redis.call("EXPIRE", bucket_key, ttl)
+else
+    retry_after = math.ceil((1 - tokens) / refill_rate)
+end
+
+return { allowed, math.floor(tokens), retry_after }

fastapi_sluice-0.1.0/src/fastapi_sluice/middleware.py

@@ -0,0 +1,32 @@
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from fastapi_sluice.algorithms.base import RateLimitAlgorithm
+from fastapi_sluice.limiter import KeyFunc, RateLimiter, _default_key_func
+
+
+class RateLimitMiddleware(BaseHTTPMiddleware):
+    def __init__(
+        self,
+        app,
+        limiter: RateLimiter,
+        algorithm: RateLimitAlgorithm,
+        key_func: KeyFunc = _default_key_func,
+    ):
+        super().__init__(app)
+        self.limiter = limiter
+        self.algorithm = algorithm
+        self.key_func = key_func
+
+    async def dispatch(self, request: Request, call_next):
+        allowed, headers = await self.limiter.limit_global(
+            request, self.algorithm, self.key_func
+        )
+        if not allowed:
+            return JSONResponse(
+                status_code=429,
+                content={"detail": "Too many requests"},
+                headers=headers,
+            )
+        return await call_next(request)