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 & Moving window algorithms (Lua)
RateLimit, RateLimit-Policy, Retry-After headers
ASGI async middleware for FastAPI/Starlette
Asyncio Redis support
Easy to configure
No decorators needed
HTML/JSON error responses
Site-wide or per-endpoint bans, with configurable durations

TODO

In-memory option
X-Forwarded-For and X-Real-IP handling
Better websocket support
User specific banning

Rule Matching

Single Rule

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

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

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, "moving")

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.
Bans will double with each offense, up to the configured maximum ban length.

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, "moving"),
        "/api/auth/*": (3, 1, "fixed"),
        "/api/users/me": (1, 5, "fixed"),
    },
    exempt=[],
    ban_offenses=15,
    ban_length="3m",
    ban_max_length="30m",
    ban_counter_ttl="1h",
    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	Used For
`rl:fixe:{hash}:{limit}:{window}`	`rl:fixe:a1b2c3d4e5f6a7b8:100:60`	Fixed-window counter
`rl:movi:{hash}:{limit}:{window}:{window_id}`	`rl:movi:a1b2c3d4e5f6a7b8:100:60:12345`	Moving window per-subwindow counter
`{rl_key}:meta`	`rl:fixe:a1b2c3d4e5f6a7b8:100:60:meta`	Stores both: `offenses` & `ban_count` for doubling
`ban:{hash}`	`ban:a1b2c3d4e5f6a7b8`	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`	`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
`ban_counter_ttl`	`int`	No	TTL for ban metadata (default 3600s)
`site_ban`	`bool`	No	Enable site-wide bans or per-endpoint

Tests

Used Ratelimit Tester for testing rate-limit atomicity. Tested with 10 concurrent connections calling 10k requests each, no sleep timer. More testing in heavier environments is needed.

===== FLOOD TEST RESULTS =====
URL: http://localhost:8000/
Workers: 10
Requests per worker: 10000
Total Requests: 100000
Delay per request: 0.0 sec

--- IP 244.35.63.217 ---
200: 200
403: 9786
429: 14
Other: 0
ERR: 0
Latency avg: 7.29 ms
Latency min: 2 ms
Latency max: 3152 ms

--- IP 26.72.199.16 ---
200: 200
403: 9786
429: 14
Other: 0
ERR: 0
Latency avg: 7.20 ms
Latency min: 2 ms
Latency max: 2842 ms

--- IP 103.19.7.208 ---
200: 200
403: 9786
429: 14
Other: 0
ERR: 0
Latency avg: 7.11 ms
Latency min: 3 ms
Latency max: 2515 ms

--- IP 219.61.231.164 ---
200: 200
403: 9786
429: 14
Other: 0
ERR: 0
Latency avg: 7.19 ms
Latency min: 2 ms
Latency max: 2246 ms

--- IP 67.190.167.172 ---
200: 200
403: 9786
429: 14
Other: 0
ERR: 0
Latency avg: 7.16 ms
Latency min: 2 ms
Latency max: 1905 ms

--- IP 92.47.52.135 ---
200: 200
403: 9786
429: 14
Other: 0
ERR: 0
Latency avg: 7.08 ms
Latency min: 2 ms
Latency max: 1635 ms

--- IP 86.33.165.103 ---
200: 200
403: 9786
429: 14
Other: 0
ERR: 0
Latency avg: 7.07 ms
Latency min: 2 ms
Latency max: 1316 ms

--- IP 201.252.232.237 ---
200: 200
403: 9786
429: 14
Other: 0
ERR: 0
Latency avg: 7.05 ms
Latency min: 2 ms
Latency max: 947 ms

--- IP 153.64.165.188 ---
200: 200
403: 9786
429: 14
Other: 0
ERR: 0
Latency avg: 7.01 ms
Latency min: 2 ms
Latency max: 653 ms

--- IP 109.49.11.6 ---
200: 200
403: 9786
429: 14
Other: 0
ERR: 0
Latency avg: 6.95 ms
Latency min: 2 ms
Latency max: 401 ms

Limitations

Requires Redis; in-memory backend not yet implemented.
Limited WebSocket support.
No built-in handling for X-Forwarded-For and X-Real-IP headers.
Tested in light environments; may need optimization for very high traffic.
Bans are IP-based; no user-specific banning yet.

Screenshot

Contributing

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fastapi_easylimiter-0.5.0.tar.gz (13.9 kB view details)

Uploaded Nov 25, 2025 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

fastapi_easylimiter-0.5.0-py3-none-any.whl (11.5 kB view details)

Uploaded Nov 25, 2025 Python 3

File details

Details for the file fastapi_easylimiter-0.5.0.tar.gz.

File metadata

Download URL: fastapi_easylimiter-0.5.0.tar.gz
Upload date: Nov 25, 2025
Size: 13.9 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.1

File hashes

Hashes for fastapi_easylimiter-0.5.0.tar.gz
Algorithm	Hash digest
SHA256	`6b999a1cfd4c5ccfb1e2e617796eb91f3617bb87824629a02e3a33ae8b66edec`
MD5	`7cc7ff30192f89cd6a11ed5a4023eea5`
BLAKE2b-256	`fce9e35475df2e6f41d01f73c7baa25612331daef44e4361b820ba09ba174ade`

See more details on using hashes here.

File details

Details for the file fastapi_easylimiter-0.5.0-py3-none-any.whl.

File metadata

Download URL: fastapi_easylimiter-0.5.0-py3-none-any.whl
Upload date: Nov 25, 2025
Size: 11.5 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.1

File hashes

Hashes for fastapi_easylimiter-0.5.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`a6d254ff57b67f3b88b81df06262520af72ab5b5bf11bee81ec8a9a55c91bfcf`
MD5	`1e47db2941f032056150f648f0b6e999`
BLAKE2b-256	`a8ddeba855beb0dd720e8c36598cff4b4612d4b9119a2925daa283f18756579f`