django-ratelimit

Critical Requirement: Atomic Increment

django_ratelimit requires a Django cache backend that supports atomic increment operations.

• Supported: Memcached and Redis backends.
• Not Supported: The Django database backend.

Deployment Considerations

Before activating django-ratelimit, ensure your cache backend is:

1. Persistent: Data survives restarts.
2. Distributed: Works across multiple deployment worker instances (e.g., multiple UWSGI workers).

In modern versions (0.5+), rate limits are not shared between different views/methods by default, even if they use the same keys and rates. This prevents one view from accidentally exhausting the quota for another.

To explicitly force multiple views to share the same rate limit, use the group argument in the @ratelimit decorator.

# These two views share a limit because they belong to the same group
@ratelimit(group='lists', key='user', rate='100/h')
def user_list(request):
    pass

@ratelimit(group='lists', key='user', rate='100/h')
def group_list(request):
    pass

# This view is limited separately, even though it uses the same key and rate
@ratelimit(key='user', rate='100/h')
def another_view(request):
    pass

Using data directly from the client to generate rate limit keys introduces risks:

1. Trivial Circumvention: Clients can easily change values in GET parameters (key='get:X'), POST data (key='post:X'), or headers (key='header:x-x') on every request to bypass limits.
2. Dangerous Headers: The User-Agent header is particularly dangerous because attackers can rotate it constantly, and many legitimate users may share the same value.

Best Practice: Only use headers that are guaranteed to be set by your trusted web server or reverse proxy and cannot be manipulated by the client.

Simple rates use the format X/Yu, where X is the number of requests, Y is the number of units, and u is the time unit. If the unit u is omitted, it defaults to seconds (s).

Supported units:

• s: second
• m: minute
• h: hour
• d: day

Special values:

• 0/u: Disallows all requests (e.g., 0/s).
• None: Indicates no limit; usage will not be tracked.

Examples:

• 5/s: Five requests per second.
• 100/5m: One hundred requests per five minutes.
• 100/300: One hundred requests per 300 seconds (equivalent to 100/5m).

django_ratelimit retrieves the client IP address from request.META['REMOTE_ADDR'].

If your application is behind a reverse proxy (like nginx or HAProxy), REMOTE_ADDR will contain the IP address of the proxy rather than the actual client. You must configure your web server or application to ensure the correct client IP is available in REMOTE_ADDR to avoid ratelimiting the proxy itself.

Since version 0.5, Django Ratelimit uses fixed windows instead of sliding windows.

• Sliding Windows (Old): The window moves with every request, which could unfairly catch good actors in a continuous loop of rate limiting.
• Fixed Windows (New): Limits are calculated against fixed time periods. These windows are automatically staggered based on the key value to prevent all limits from expiring at the exact same time (e.g., at the top of the hour).

Warning: Because windows are fixed, you may occasionally see up to 2 * X requests in a short period if the rate is X/u. Adjust your rate settings accordingly.

Instead of using a single decorator with multiple keys (which was deprecated in 0.5), you should now stack multiple @ratelimit decorators. This allows for complex patterns like burst limits (e.g., a high rate per minute combined with a lower rate per hour) or different limits for different HTTP methods.

# Example: Hourly rate limit with a per-minute burst limit
@ratelimit(key='ip', rate='100/m')
@ratelimit(key='ip', rate='1000/h')
def myview(request):
    pass

# Example: Different limits for GET and POST
@ratelimit(key='ip', method='GET', rate='1000/h')
@ratelimit(key='ip', method='POST', rate='100/h')
def maybe_expensive(request):
    pass

In version 3.0+, RatelimitMixin was removed. You should migrate to using the @ratelimit decorator combined with @method_decorator. This allows you to apply multiple limits to the same method, which was not possible with the mixin.

# Old way (RatelimitMixin)
class MyView(RatelimitMixin, View):
    ratelimit_key = 'ip'
    ratelimit_rate = '10/m'
    ratelimit_method = 'GET'

    def get(self, request):
        pass

# New way (@method_decorator)
class MyView(View):
    @method_decorator(ratelimit(key='ip', rate='10/m', method='GET'))
    def get(self, request):
        pass

django_ratelimit requires a cache backend that is shared across all worker threads, processes, and application servers, and supports atomic increment operations.

Supported backends:

• Redis
• Memcached

Unsupported backends:

• local memory (not shared across processes/servers)
• filesystem (not shared across processes/servers)
• database (does not support atomic increments)

Warning: Using a backend without atomic increment operations can cause race conditions, leading to undercounting usage and allowing more traffic than intended.