Rate limiting¶
A rate limit caps the number of requests that one client can send to a route. Use it on routes that are expensive or easy to abuse, such as login, search or comment creation. Django-Bolt counts requests in Rust, before any Python code. A limit per IP address or per header runs before authentication. A limit per user or per API key runs after it.
Limit a route¶
Put @rate_limit below the route decorator:
from django_bolt import BoltAPI, rate_limit
api = BoltAPI()
@api.post("/comments")
@rate_limit(rps=2, burst=3)
async def create_comment() -> dict:
return {"created": True}
A client can send 3 requests at once. After that, it gets 2 more requests each second. Five quick requests from one address give 200, 200, 200, 429, 429:
HTTP/1.1 429 Too Many Requests
retry-after: 1
x-ratelimit-limit: 2
x-ratelimit-burst: 3
content-type: application/json
{"detail":"Rate limit exceeded. Try again in 1 seconds.","retry_after":1}
retry-after is the number of seconds to wait, at least 1. The handler does not run for a 429.
Bolt prints one line to stderr for each bucket and each second of rejections:
[django-bolt] Rate limit exceeded: POST /comments | key: 127.0.0.1 | limit: 2 rps (burst: 3) | retry after: 1s | suppressed: 0
The line names an address. It shows a hash in place of a header value or a user ID, so it never logs a credential.
Choose rps and burst¶
Bolt uses a token bucket for each client and route:
- The bucket holds up to
bursttokens, and it starts full. - Each request takes one token. A request that finds no token gets 429.
- The bucket gets
rpsnew tokens each second.
rps is the long-run rate. burst is the size of a short peak. The default is rps=100 and burst two times rps.
Both must be an int of 1 or more. Another value raises TypeError or ValueError when you decorate the handler.
Count per user, per API key or per header¶
key selects what Bolt counts:
key |
One bucket for each | Runs |
|---|---|---|
"ip" (default) |
Client address. An IPv6 client counts per /64 network. | Before authentication |
"user" |
Authenticated identity of any backend | After authentication |
"api_key" |
Authenticated API key | After authentication |
A header name, such as "x-tenant-id" |
Value of that header | Before authentication |
from django_bolt.auth import JWTAuthentication
@api.get("/feed", auth=[JWTAuthentication()])
@rate_limit(rps=1, burst=2, key="user")
async def feed() -> dict:
return {"articles": []}
@api.get("/search")
@rate_limit(rps=1, burst=1, key="x-tenant-id")
async def search() -> dict:
return {"results": []}
With key="user", each user has a bucket. The third quick request of ada gets 429, and the first request of bob gets 200.
A request with no identity counts per client address, for "user" and for "api_key".
A Django session has no identity that Rust can read, so a session request counts per address.
"user" and "api_key" need an auth backend on the route or in BOLT_AUTHENTICATION_CLASSES. Without one, startup fails with ValueError.
With a header key, the requests that do not send the header share one bucket. A client chooses the value of a header, so it can get a new bucket for each value. Use a header key only for a header that your proxy sets or checks.
Set the client address behind a proxy¶
With key="ip", Bolt counts the address of the TCP peer. Behind a proxy or a load balancer, that is the address of the proxy.
Then all clients share one bucket.
List your proxies in settings.py:
For a request from a listed proxy, Bolt reads X-Forwarded-For from the right. It takes the first address that is not a listed proxy.
A client cannot choose its bucket when the proxy appends the real address after the values that the client sent.
Configure the proxy to do this, for example proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; in nginx. A proxy that passes the header of the client with no change lets the client choose its bucket.
Bolt ignores X-Forwarded-For from a peer that is not in the list.
BOLT_RATE_LIMIT_IPV6_PREFIX sets the network size of an IPv6 client. The default is 64. Set 128 to count each IPv6 address.
See the settings reference.
Limit a group of routes¶
A BoltAPI or a Router takes a rate limit dict in middleware. Each of its routes gets its own bucket with that limit.
@skip_middleware("rate_limit") removes the limit from one route:
from django_bolt import Router, skip_middleware
public = Router(prefix="/public", middleware=[{"type": "rate_limit", "rps": 20, "burst": 40}])
@public.get("/articles")
async def public_articles() -> list:
return []
@public.get("/health")
@skip_middleware("rate_limit")
async def health() -> dict:
return {"status": "ok"}
api.include_router(public)
The most specific limit wins: the route, then the router, then the API. The outer limit does not also apply.
A route takes one limit. A second @rate_limit on the same function raises ValueError.
Know the limits¶
- Each
runboltprocess has its own buckets. With--processes 4, a client can get up to four times the limit, because the kernel spreads its connections over the processes. Divide the limit by the number of processes, or limit at the proxy. - A restart empties the buckets.
- Each process keeps up to 100,000 buckets. Above that number, Bolt deletes 20% of the buckets, in no fixed order.
- A 429 has the CORS headers of the route, so a browser page can read it.
TestClientcounts requests asrunboltdoes. EachTestClienthas its own buckets.
See also¶
- Middleware reference: the arguments of
@rate_limit. - Settings reference:
BOLT_TRUSTED_PROXIESandBOLT_RATE_LIMIT_IPV6_PREFIX. - Authentication: the backends that give
key="user"an identity. - Deployment: run
runboltbehind a proxy.