Configuration¶

The following django settings are honored by the middleware.

RATELIMIT_GLOBAL

A comma (or some other delimiter) separated string that will be used to apply a global limit on all routes. Rate limit string notation for details.

RATELIMIT_CALLBACK

The callback which will be called when a rate limit is hit. Defaults to a 429 status code being returned.

RATELIMIT_KEY_FUNCTION

The default callable to use to derive the context of a request. This can either be the callable itself or a fully qualified path to a callable. The callable to accept a single request object as a parameter and return a string. Defaults to the ip address of the requesting user.

RATELIMIT_STORAGE_URL

One of memory://, redis://host:port or memcached://host:port. Using the redis storage requires the installation of the redis package while memcached relies on pymemcache.

RATELIMIT_STRATEGY

The rate limiting strategy to use. Rate limiting strategies for details.

RATELIMIT_HEADERS_ENABLED

Enables returning Rate-limiting Headers. Defaults to False

RATELIMIT_ENABLED

Overall kill switch for rate limits. Defaults to True

RATELIMIT_HEADER_LIMIT

Header for the current rate limit. Defaults to X-RateLimit-Limit

RATELIMIT_HEADER_RESET

Header for the reset time of the current rate limit. Defaults to X-RateLimit-Reset

RATELIMIT_HEADER_REMAINING

Header for the number of requests remaining in the current rate limit. Defaults to X-RateLimit-Remaining

Rate limit string notation¶

Rate limits are specified as strings following the format:

[count] [per|/] [n (optional)] [second|minute|hour|day|month|year]

You can combine multiple rate limits by separating them with a delimiter of your choice.

Decorators¶

The decorators made available as instance methods of the Limiter instance are

limit()

There are a few ways of using this decorator depending on your preference and use-case.

Single decorator

The limit string can be a single limit or a delimiter separated string

@limit("100/day;10/hour;1/minute")
def my_view(request)
  ...

Multiple decorators

The limit string can be a single limit or a delimiter separated string or a combination of both.

@limit("100/day")
@limit("10/hour")
@limit("1/minute")
def my_view(request):
  ...

Custom keying function

By default rate limits are applied on per remote address basis. You can implement your own function to retrieve the key to rate limit by.

def my_key_func(request):
  ...

@limit("100/day", my_key_func)
def my_view(request):
  ...

Note

The key function must accept one argument which is a django.http.HttpRequest object

Dynamically loaded limit string(s)

There may be situations where the rate limits need to be retrieved from sources external to the code (database, remote api, etc...). This can be achieved by providing a callable (which takes a single parameter - the django.http.HttpRequest object) to the decorator. The callable should return a rate limit string in the Rate limit string notation.

from django.conf import settings

def rate_limit_from_config(request):
    return settings.CUSTOM_LIMIT

@limit(rate_limit_from_config)
def my_view(request):
    ...

Danger

The provided callable will be called for every request on the decorated route. For expensive retrievals, consider caching the response.

shared_limit()

For scenarios where a rate limit should be shared by multiple views (For example when you want to protect views using the same resource with an umbrella rate limit).

Named shared limit

mysql_limit = shared_limit("100/hour", scope="mysql")

@mysql_limit
def my_view_1(request):
   ...

@mysql_limit
def my_view_2(request):
   ...

Dynamic shared limit: when a callable is passed as scope, the return value of the function will be used as the scope.

def host_scope(request):
    return request.META['HTTP_HOST']

host_limit = limiter.shared_limit("100/hour", scope=host_scope)

@host_limit
def my_view_1():
   ...

@host_limit
def my_view_2():
   ...

Note

Shared rate limits provide the same conveniences as individual rate limits

• Can be chained with other shared limits or individual limits
• Accept keying functions
• Accept callables to determine the rate limit value

exempt()

This decorator simply marks a view as being exempt from any rate limits.

Rate limiting strategies¶

djlimiter comes with three different rate limiting strategies built-in. Pick the one that works for your use-case by specifying it in your django settings as RATELIMIT_STRATEGY (one of fixed-window, fixed-window-elastic-expiry, or moving-window). The default configuration is fixed-window.

Rate-limiting Headers¶

If the configuration is enabled, information about the rate limit with respect to the route being requested will be added to the response headers. Since multiple rate limits can be active for a given route - the rate limit with the lowest time granularity will be used in the scenario when the request does not breach any rate limits.

The header names can be customised if required by using django settings (Configuration).

Recipes¶

class MyView(django.views.generic):
    def get(self):
        return HttpResponse("get")

    def put(self):
        return HttpResponse("put")

urlpatterns = patterns('',
    (r'^myview/', limit("2/second")(MyView.as_view())),
)

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'stream': {
            'level': 'DEBUG',
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        'djlimiter': {
            'handlers': ['stream'],
            'level': 'INFO',
            'propagate': True,
        },
    },
}

API¶