fastapi-easylimiter 0.2.8

High-performance async rate limiter for FastAPI with Redis or native in-memory backend

fastapi‑easylimiter

An ASGI async rate-limiting middleware for FastAPI with Redis or in-memory caching. Designed to handle auto-generated routes (such as those provided by FastAPI-Users) without requiring decorators, purely out of simplicity.

Features

• Async rate limiting
• Optional temporary IP bans
  • Configurable threshold (default 10 violations)
  • Sliding 30-min offense window
  • 5-min ban on repeat abuse
• Cache
  • Redis
  • In-Memory (single worker dev)
• Path Based Rules
• Multi-rule prefix matching
  • Capable of global rate-limits and per-route
• Standard rate-limit headers
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset
  • Retry-After on 429 responses
  • Tracking for remaining time sent in headers
• Proxy Aware
  • Uses 'X-Forwarded-For' only when the sender is trusted
  • Rejects spoofed XFF headers
  • Uses 'CF-Connecting-IP' and chekcks connection IP against CF CIDR list
  • Falls back to ASGI scope["client"] if no trusted headers exist
• Zero Dependencies Beyond Redis Client
  • Starlette-style ASGI middleware

Installation

pip install fastapi-easylimiter

---

Usage

from fastapi import FastAPI
from fastapi_easylimiter import AsyncRedisBackend, InMemoryBackend, RateLimiterMiddleware
import redis.asyncio as redis_async

app = FastAPI()

REDIS_URL = "redis://localhost:6379/0"

# Redis backend (recommended for multi-instance deployments)
redis_client = redis_async.from_url(REDIS_URL, decode_responses=True)
backend = AsyncRedisBackend(redis_client)

# Or for single-instance/local development:
# backend = InMemoryBackend()

rules = {
    "/": {"limit": 600, "period": 60},          # GLOBAL: 600 req/min per IP
    "/api/": {"limit": 10, "period": 1},
    "/api/users": {"limit": 1, "period": 2},
}

app.add_middleware(
    RateLimiterMiddleware,
    rules=rules,
    backend=backend,
    trusted_proxies=["127.0.0.1"],
    cloudflare=True, # enables CF-Connecting-IP
    enable_bans=True,         # ← new: turn on/off banning
    ban_threshold=15,         # ← violations before ban
    ban_duration=900,         # ← ban length in seconds
    offenses_ttl=1800,        # ← offense counting window
)

Rules are automatically sorted longest-first as seen in the code example.

A request to /api/users/me will match:

• /api/users
• /api

If ANY rule is exceeded → request becomes 429.

Uses Atomic LUA script:

local count = redis.call('INCR', key)
if count == 1 then redis.call('EXPIRE', key, period) end

Keys follow the pattern - rl:{client_ip}:{prefix}, which is saved as rl:203.0.113.5:/api

Parameter	Type	Description
app	ASGIApp	FastAPI/ASGI app
rules	dict	{ prefix: {"limit": int, "period": int} }
backend	Redis or InMemory backend	Rate-limit storage
trusted_proxies	list[str]	Proxies allowed to trust XFF headers
cloudflare	bool	Enable Cloudflare IP extraction
enable_bans	bool	Enable temporary IP bans
ban_threshold	int	Violations before ban
ban_duration	int	Ban length in seconds
offenses_ttl	int	Offense counting window in seconds

Contributing

Contributions and forks are always welcome! Feel free to adapt and improve for your own needs.

Support