fastapi-rate-limiter-plugin 1.0.0__tar.gz

fastapi_rate_limiter_plugin-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 K1 Core Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_rate_limiter_plugin-1.0.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: fastapi-rate-limiter-plugin
+Version: 1.0.0
+Summary: Redis backed rate limiting dependency for FastAPI and Starlette
+Keywords: fastapi,starlette,rate-limit,throttling,redis
+Author: bb-soft
+Author-email: bb-soft <noreply@k1core.tech>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Dist: redis>=5
+Requires-Dist: starlette>=0.37
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/k1core-ltd/fastapi-rate-limiter
+Description-Content-Type: text/markdown
+
+# fastapi-rate-limiter-plugin
+
+Redis backed rate limiting for FastAPI and Starlette, as a dependency on the
+endpoints that need it.
+
+## Install
+
+```bash
+pip install fastapi-rate-limiter-plugin
+```
+
+## Use
+
+Point the backend at redis once, from the lifespan of the application:
+
+```python
+import contextlib
+
+import redis.asyncio
+from fastapi import Depends, FastAPI
+from fastapi_rate_limiter import RateLimiter, RateLimiterBackend
+
+
+@contextlib.asynccontextmanager
+async def lifespan(_: FastAPI):
+    await RateLimiterBackend.setup(redis.asyncio.from_url("redis://localhost"))
+    yield
+    await RateLimiterBackend.close()
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.post("/resend", dependencies=[Depends(RateLimiter(times=5, seconds=60))])
+async def resend() -> dict:
+    return {"sent": True}
+```
+
+A caller over the limit gets a `429` with a `Retry-After` header. A request that
+gets through leaves `request.state.rate_limit_reset_in_seconds`, so an endpoint
+can tell the caller when the window resets.
+
+Callers are told apart by `X-Forwarded-For`, falling back to the peer address,
+together with the path. Pass `identifier` to `setup` or to a single limiter to
+count by something else, such as a tenant or an API key:
+
+```python
+async def by_tenant(connection: HTTPConnection) -> str:
+    return connection.headers.get("X-Tenant-Id", "unknown")
+
+
+RateLimiter(times=100, hours=1, identifier=by_tenant)
+```
+
+## Websockets
+
+`WebSocketRateLimiter` counts messages rather than connections, and takes a
+context key so one socket can hold several independent limits:
+
+```python
+limiter = WebSocketRateLimiter(times=10, seconds=5)
+
+
+@app.websocket("/ws")
+async def ws(websocket: WebSocket):
+    await websocket.accept()
+    while True:
+        message = await websocket.receive_text()
+        await limiter(websocket, context_key=message)
+```
+
+## Notes
+
+Counting is a single Lua script, so a window is counted atomically and every
+instance of the service counts one caller together. The script is reloaded by
+itself when redis drops its cache after a restart.
+
+## License
+
+MIT

fastapi_rate_limiter_plugin-1.0.0/README.md

@@ -0,0 +1,80 @@
+# fastapi-rate-limiter-plugin
+
+Redis backed rate limiting for FastAPI and Starlette, as a dependency on the
+endpoints that need it.
+
+## Install
+
+```bash
+pip install fastapi-rate-limiter-plugin
+```
+
+## Use
+
+Point the backend at redis once, from the lifespan of the application:
+
+```python
+import contextlib
+
+import redis.asyncio
+from fastapi import Depends, FastAPI
+from fastapi_rate_limiter import RateLimiter, RateLimiterBackend
+
+
+@contextlib.asynccontextmanager
+async def lifespan(_: FastAPI):
+    await RateLimiterBackend.setup(redis.asyncio.from_url("redis://localhost"))
+    yield
+    await RateLimiterBackend.close()
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.post("/resend", dependencies=[Depends(RateLimiter(times=5, seconds=60))])
+async def resend() -> dict:
+    return {"sent": True}
+```
+
+A caller over the limit gets a `429` with a `Retry-After` header. A request that
+gets through leaves `request.state.rate_limit_reset_in_seconds`, so an endpoint
+can tell the caller when the window resets.
+
+Callers are told apart by `X-Forwarded-For`, falling back to the peer address,
+together with the path. Pass `identifier` to `setup` or to a single limiter to
+count by something else, such as a tenant or an API key:
+
+```python
+async def by_tenant(connection: HTTPConnection) -> str:
+    return connection.headers.get("X-Tenant-Id", "unknown")
+
+
+RateLimiter(times=100, hours=1, identifier=by_tenant)
+```
+
+## Websockets
+
+`WebSocketRateLimiter` counts messages rather than connections, and takes a
+context key so one socket can hold several independent limits:
+
+```python
+limiter = WebSocketRateLimiter(times=10, seconds=5)
+
+
+@app.websocket("/ws")
+async def ws(websocket: WebSocket):
+    await websocket.accept()
+    while True:
+        message = await websocket.receive_text()
+        await limiter(websocket, context_key=message)
+```
+
+## Notes
+
+Counting is a single Lua script, so a window is counted atomically and every
+instance of the service counts one caller together. The script is reloaded by
+itself when redis drops its cache after a restart.
+
+## License
+
+MIT

fastapi_rate_limiter_plugin-1.0.0/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "fastapi-rate-limiter-plugin"
+version = "1.0.0"
+description = "Redis backed rate limiting dependency for FastAPI and Starlette"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+keywords = [
+    "fastapi",
+    "starlette",
+    "rate-limit",
+    "throttling",
+    "redis",
+]
+classifiers = [
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    "redis>=5",
+    "starlette>=0.37",
+]
+
+[[project.authors]]
+name = "bb-soft"
+email = "noreply@k1core.tech"
+
+[project.urls]
+Repository = "https://github.com/k1core-ltd/fastapi-rate-limiter"
+
+[build-system]
+requires = ["uv_build>=0.9,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "fastapi_rate_limiter"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+extend-select = [
+    "UP",
+    "E",
+    "W",
+    "I",
+    "N",
+    "ANN",
+    "B",
+    "C4",
+    "RET",
+    "SIM",
+    "TID",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pre-commit>=4.6.2",
+    "ruff>=0.13",
+]

fastapi_rate_limiter_plugin-1.0.0/pyproject.toml.orig

@@ -0,0 +1,48 @@
+[project]
+name = "fastapi-rate-limiter-plugin"
+version = "1.0.0"
+description = "Redis backed rate limiting dependency for FastAPI and Starlette"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "bb-soft", email = "noreply@k1core.tech" },
+]
+requires-python = ">=3.12"
+keywords = ["fastapi", "starlette", "rate-limit", "throttling", "redis"]
+classifiers = [
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    "redis>=5",
+    "starlette>=0.37",
+]
+
+[project.urls]
+Repository = "https://github.com/k1core-ltd/fastapi-rate-limiter"
+
+[build-system]
+requires = ["uv_build>=0.9,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "fastapi_rate_limiter"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pre-commit>=4.6.2",
+    "ruff>=0.13",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+extend-select = ["UP", "E", "W", "I", "N", "ANN", "B", "C4", "RET", "SIM", "TID"]

fastapi_rate_limiter_plugin-1.0.0/src/fastapi_rate_limiter/__init__.py

@@ -0,0 +1,21 @@
+from fastapi_rate_limiter.backend import (
+    COUNT_SCRIPT,
+    Identifier,
+    RateLimiterBackend,
+    client_ip_and_path,
+)
+from fastapi_rate_limiter.depends import (
+    BaseRateLimiter,
+    RateLimiter,
+    WebSocketRateLimiter,
+)
+
+__all__ = [
+    "COUNT_SCRIPT",
+    "BaseRateLimiter",
+    "Identifier",
+    "RateLimiter",
+    "RateLimiterBackend",
+    "WebSocketRateLimiter",
+    "client_ip_and_path",
+]

fastapi_rate_limiter_plugin-1.0.0/src/fastapi_rate_limiter/backend.py

@@ -0,0 +1,80 @@
+from collections.abc import Awaitable, Callable
+
+from redis.asyncio import Redis
+from redis.exceptions import NoScriptError
+from starlette.requests import HTTPConnection
+
+COUNT_SCRIPT = """
+local key = KEYS[1]
+local limit = tonumber(ARGV[1])
+local window_ms = ARGV[2]
+
+local current = tonumber(redis.call('GET', key) or "0")
+if current >= limit then
+    return redis.call('PTTL', key)
+end
+
+if current == 0 then
+    redis.call('SET', key, 1, 'PX', window_ms)
+else
+    redis.call('INCR', key)
+end
+return 0
+"""
+
+Identifier = Callable[[HTTPConnection], Awaitable[str]]
+
+
+async def client_ip_and_path(connection: HTTPConnection) -> str:
+    forwarded = connection.headers.get("X-Forwarded-For")
+    if forwarded:
+        host = forwarded.split(",")[0].strip()
+    elif connection.client is not None:
+        host = connection.client.host
+    else:
+        host = "unknown"
+    return f"{host}:{connection.scope['path']}"
+
+
+class RateLimiterBackend:
+    redis: Redis | None = None
+    prefix: str = "rate-limit"
+    identifier: Identifier = client_ip_and_path
+    _script_sha: str | None = None
+
+    @classmethod
+    async def setup(
+        cls,
+        redis: Redis,
+        prefix: str = "rate-limit",
+        identifier: Identifier | None = None,
+    ) -> None:
+        cls.redis = redis
+        cls.prefix = prefix
+        cls.identifier = identifier or client_ip_and_path
+        cls._script_sha = await redis.script_load(COUNT_SCRIPT)
+
+    @classmethod
+    async def close(cls) -> None:
+        cls.redis = None
+        cls._script_sha = None
+
+    @classmethod
+    async def count(cls, key: str, times: int, window_ms: int) -> int:
+        if cls.redis is None or cls._script_sha is None:
+            raise RuntimeError(
+                "RateLimiterBackend.setup() has to run before the first request, "
+                "usually from the lifespan of the application.",
+            )
+
+        try:
+            return await cls.redis.evalsha(cls._script_sha, 1, key, str(times), str(window_ms))
+        except NoScriptError:
+            cls._script_sha = await cls.redis.script_load(COUNT_SCRIPT)
+            return await cls.redis.evalsha(cls._script_sha, 1, key, str(times), str(window_ms))
+
+    @classmethod
+    async def reset_in_ms(cls, key: str) -> int:
+        if cls.redis is None:
+            return 0
+        return max(await cls.redis.pttl(key), 0)

fastapi_rate_limiter_plugin-1.0.0/src/fastapi_rate_limiter/depends.py

@@ -0,0 +1,62 @@
+import math
+
+from starlette.exceptions import HTTPException
+from starlette.requests import HTTPConnection, Request
+from starlette.responses import Response
+from starlette.status import HTTP_429_TOO_MANY_REQUESTS
+from starlette.websockets import WebSocket
+
+from fastapi_rate_limiter.backend import Identifier, RateLimiterBackend
+
+
+class BaseRateLimiter:
+    def __init__(
+        self,
+        times: int = 1,
+        milliseconds: int = 0,
+        seconds: int = 0,
+        minutes: int = 0,
+        hours: int = 0,
+        identifier: Identifier | None = None,
+    ) -> None:
+        window_ms = milliseconds + 1000 * seconds + 60_000 * minutes + 3_600_000 * hours
+        if times < 1:
+            raise ValueError("times has to be at least 1")
+        if window_ms < 1:
+            raise ValueError("the window has to be at least one millisecond")
+
+        self.times = times
+        self.window_ms = window_ms
+        self.identifier = identifier
+
+    async def key_for(self, connection: HTTPConnection) -> str:
+        identifier = self.identifier or RateLimiterBackend.identifier
+        caller = await identifier(connection)
+        return f"{RateLimiterBackend.prefix}:{caller}:{self.times}:{self.window_ms}"
+
+    async def spend(self, key: str) -> None:
+        retry_after_ms = await RateLimiterBackend.count(key, self.times, self.window_ms)
+        if retry_after_ms:
+            raise HTTPException(
+                status_code=HTTP_429_TOO_MANY_REQUESTS,
+                detail="Too Many Requests",
+                headers={"Retry-After": str(math.ceil(retry_after_ms / 1000))},
+            )
+
+
+class RateLimiter(BaseRateLimiter):
+    async def __call__(self, request: Request, response: Response) -> None:
+        key = await self.key_for(request)
+        await self.spend(key)
+
+        reset_in_ms = await RateLimiterBackend.reset_in_ms(key)
+        request.state.rate_limit_reset_in_seconds = math.ceil(reset_in_ms / 1000)
+        response.headers["X-RateLimit-Limit"] = str(self.times)
+
+
+class WebSocketRateLimiter(BaseRateLimiter):
+    async def __call__(self, websocket: WebSocket, context_key: str = "") -> None:
+        key = await self.key_for(websocket)
+        if context_key:
+            key = f"{key}:{context_key}"
+        await self.spend(key)