1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
|
.. _keys-chapter:
==============
Ratelimit Keys
==============
The ``key=`` argument to the decorator takes either a string or a
callable.
.. _keys-common:
Common keys
===========
The following string values for ``key=`` provide shortcuts to commonly
used ratelimit keys:
- ``'ip'`` - Use the request IP address (i.e.
``request.META['REMOTE_ADDR']``)
.. note::
If you are using a reverse proxy, make sure this value is correct
or use an appropriate ``header:`` value. See the :ref:`security
<security-chapter>` notes.
- ``'get:X'`` - Use the value of ``request.GET.get('X', '')``.
- ``'post:X'`` - Use the value of ``request.POST.get('X', '')``.
- ``'header:x-x'`` - Use the value of
``request.META.get('HTTP_X_X', '')``.
.. note::
The value right of the colon will be translated to all-caps and
any dashes will be replaced with underscores, e.g.: x-client-ip
=> X_CLIENT_IP.
- ``'user'`` - Use an appropriate value from ``request.user``. Do not use
with unauthenticated users.
- ``'user_or_ip'`` - Use an appropriate value from ``request.user`` if
the user is authenticated, otherwise use
``request.META['REMOTE_ADDR']`` (see the note above about reverse
proxies).
.. note::
Missing headers, GET, and POST values will all be treated as empty
strings, and ratelimited in the same bucket.
.. warning::
Using user-supplied data, like data from GET and POST or headers
directly from the User-Agent can allow users to trivially opt out of
ratelimiting. See the note in :ref:`the security chapter
<security-user-supplied>`.
.. _keys-strings:
String values
=============
Other string values not from the list above will be treated as the
dotted Python path to a callable. See :ref:`below <keys-callable>` for
more on callables.
.. _keys-callable:
Callable values
===============
.. versionadded:: 0.3
.. versionchanged:: 0.5
Added support for python path to callables.
.. versionchanged:: 0.6
Callable was mistakenly only passed the ``request``, now also gets ``group`` as documented.
If the value of ``key=`` is a callable, or the path to a callable, that
callable will be called with two arguments, the :ref:`group
<usage-chapter>` and the ``request`` object. It should return a
bytestring or unicode object, e.g.::
def my_key(group, request):
return request.META['REMOTE_ADDR'] + request.user.username
|
