Falcon-Limiter
This library provides advanced rate limiting support for the Falcon web framework.
Rate limiting is provided with the help of the popular Limits library.
This library aims to be compatible with CPython 3.6+ and PyPy 3.5+.
Documentation
You can find the documentation of this library on Read the Docs.
Quickstart
WSGI
Quick example - using fixed-window strategy and storing the hits against limits in the memory:
import falcon
from falcon_limiter import Limiter
from falcon_limiter.utils import get_remote_addr
limiter = Limiter(
key_func=get_remote_addr,
default_limits="5 per minute,2 per second"
)
# use the default limit for all methods of this class
@limiter.limit()
class ThingsResource:
def on_get(self, req, resp):
resp.body = 'Hello world!'
# add the limiter middleware to the Falcon app
app = falcon.API(middleware=limiter.middleware)
things = ThingsResource()
app.add_route('/things', things)
ASGI (Async)
Quick example - using fixed-window strategy and storing the hits against limits in the memory:
import falcon.asgi
from falcon_limiter import AsyncLimiter
from falcon_limiter.utils import get_remote_addr
limiter = AsyncLimiter(
key_func=get_remote_addr,
default_limits="5 per minute,2 per second"
)
# use the default limit for all methods of this class
@limiter.limit()
class ThingsResource:
async def on_get(self, req, resp):
resp.body = 'Hello world!'
# add the limiter middleware to the Falcon app
app = falcon.asgi.App(middleware=limiter.middleware)
things = ThingsResource()
app.add_route('/things', things)
See documentation for more about Async.
A more complicated example
When making calls against this app, above >5 calls per minute or >2 per seconds you will receive
an HTTP 429 error response with message: "Reached allowed limit 5 hits per 1 minute!"
A second, more complicated example - using the moving-window strategy with a shared Redis backend
and running the application behind a reverse proxy behind a reverse proxy:
import falcon
from falcon_limiter import Limiter
# a custom key function
def get_access_route_addr(req, resp, resource, params) -> str:
""" Get the requestor's IP by discounting 1 reverse proxy
"""
return req.access_route[-2]
limiter = Limiter(
key_func=get_access_route_addr,
default_limits="5 per minute,2 per second",
# only count HTTP 200 responses against the limit:
default_deduct_when=lambda req, resp, resource, req_succeeded:
resp.status == falcon.HTTP_200,
config={
'RATELIMIT_KEY_PREFIX': 'myapp', # to allow multiple apps in the same Redis db
'RATELIMIT_STORAGE_URL': f'redis://:{REDIS_PSW}@{REDIS_HOST}:{REDIS_PORT}',
'RATELIMIT_STRATEGY': 'moving-window'
}
)
class ThingsResource:
# no rate limit on this method
def on_get(self, req, resp):
resp.body = 'Hello world!'
# a more strict rate limit applied to this method
# with a custom key function serving up the user_id
# from the request context as key
@limiter.limit(limits="3 per minute,1 per second",
key_func=lambda req, resp, resource, params: req.context.user_id)
def on_post(self, req, resp):
resp.body = 'Hello world!'
class SpecialResource:
# dynamic_limits allowing the 'admin' user a higher limit than others
@limiter.limit(dynamic_limits=lambda req, resp, resource, params:
'999/minute,9999/second' if req.context.user == 'admin'
else '5 per minute,2/second')
def on_get(self, req, resp):
resp.body = 'Hello world!'
# add the limiter middleware to the Falcon app
app = falcon.API(middleware=limiter.middleware)
things = ThingsResource()
special = SpecialResource()
app.add_route('/things', things)
app.add_route('/special', special)
For more details please read the documentation at Read the Docs
Development
For the development environment we use Pipenv and for packaging we use Flit.
Documentation
The documentation is built via Sphinx following the Google docstring style and hosted on Read the Docs.
To review the documentation locally before committing:
$ make docs
$ cd docs
$ python -m http.server 8088
Now you can access the documentation locally under http://127.0.0.1:8088/_build/html/
Development environment
You will need Python 3.6-3.9 and PyPy3 and its source package installed to run
tox in all environments.
We do use type hinting and run MyPy on those, but unfortunately MyPy currently breaks
the PyPy tests due to the typed-ast package's "bug" (see
python/typed_ast#97). Also with Pipenv you can't
have a second Pipfile. This is why for now we don't have mypy listed as a dev package
in the Pipfile.
Credits
Our library uses the popular Limits library for most of the backend operations.
