fastapi-easylimiter 0.4.5

Async ASGI rate limiter for FastAPI with Redis.

fastapi‑easylimiter

---

An ASGI async rate-limiting middleware for FastAPI with Redis, designed to handle auto-generated routes (e.g., FastAPI-Users) without decorators, for simplicity and ease of use.

---

Features

• Path based rules (/api/*, /auth/*, /api/users/me, etc)
• Fixed, Sliding & Moving window algorithms (Lua)
• RateLimit, RateLimit-Policy, Retry-After headers
• Bans with back-off per IP with configurable window
• ASGI async middleware for FastAPI/Starlette
• Asyncio Redis support
• Easy to configure
• No decorators needed
• HTML/JSON error responses
• XFF Header Support when enabled

---

TODO

• In-memory option

Rule Matching

Single Rule

Use these when you want a rule to apply to one specific endpoint only.

"/api/users/me": (20, 60, "sliding")

This applies only to requests where the normalized path is exactly:

/api/users/me

Nothing else matches. Not /api/users/me/profile, not /api/users/me/123, not /api/users.

Prefix Wildcards

A rule ending with /* applies to all sub-paths under a given prefix, as one shared rate-limit bucket.

"/api/*": (100, 60, "sliding")

This matches:

/api
/api/
/api/users
/api/users/123
/api/anything/here/nested

How Rule applies

Rules are normalized and sorted so that:

• Exact matches come before wildcard matches.
• Longer prefixes take priority over shorter prefixes (so /api/users/* overrides /api/*)
• A request may match multiple rules, if so, ALL matching rules run, and the strictest one determines whether the request is allowed.

Installation

pip install fastapi-easylimiter

---

Usage

from fastapi import FastAPI
import redis.asyncio as redis
from middleware.rate import RateLimitMiddleware

app = FastAPI()

redis_client = redis.from_url("redis://localhost:6379/0")

app.add_middleware(
    RateLimitMiddleware,
    redis=redis,
    rules={
        "/*": (200, 60, "moving"),           
        "/api/*": (10, 1, "sliding"),
        "/api/auth/*": (3, 1, "sliding"),
        "/api/users/me": (3, 30, "fixed"),
    },
    exempt=[],
    ban_offenses=15,
    ban_length="3m",
    ban_max_length="30m",
    enable_xff=False,
    site_ban=True
    )

Example: /api/auth/login matches /api/auth and /api. If any rule is exceeded → 429 returned. If banned → 403 returned.

---

Redis Key Patterns

Key Pattern	Example	Type	Used For
rl:Fixe:{hash}:{limit}:{window}	rl:Fixe:a1b2c3d4e5f6a7b8:100:60	String	Fixed-window counter
rl:Slid:{hash}:{limit}:{window}	rl:Slid:a1b2c3d4e5f6a7b8:60:60	ZSET	Sliding window request log
offense:{hash}	offense:{a1b2c3d4e5f6a7b8}	ZSET	Offense tracking for ban escalation
ban:{hash}	ban:{a1b2c3d4e5f6a7b8}	String+TTL	Active ban flag

---

Middleware Parameters

Parameter	Type	Required	Description
redis	redis.asyncio.Redis	Yes	Redis async client
rules	Dict[str, Tuple[int, int, str]]	Yes	Path → (limit, period, strategy)
exempt	Optional[List[str]]	No	Paths that bypass rate limits
ban_offenses	int	No	Offenses before ban triggers
ban_length	str	No	Initial ban length
ban_max_length	str	No	Maximum exponential ban ceiling
enable_xff	bool	No	Enable X-Forwarded-For support
site_ban	bool	No	Enable site-wide bans or per-endpoint

---

Tests

Used Ratelimit Tester for testing rate-limit atomicity.

Screenshot

---

Contributing

Contributions and forks are always welcome! Adapt, improve, or extend for your own needs.