django-smart-ratelimit 0.7.3

A flexible and efficient rate limiting library for Django applications

Django Smart Ratelimit

A comprehensive rate limiting library for Django applications with multiple algorithms, backends, and flexible configuration options.

Why Rate Limiting Matters

Rate limiting helps protect your Django applications from:

• Resource exhaustion from excessive requests
• Brute force attacks on authentication endpoints
• API abuse and scraping attempts
• Unintentional traffic spikes that can overwhelm your server

Library Features

• Multiple algorithms: Token bucket, sliding window, and fixed window
• Backend flexibility: Redis, Database, Memory, and Multi-Backend support
• Atomic operations: Redis Lua scripts prevent race conditions
• Automatic failover: Graceful degradation between backends
• Type safety: Full mypy compatibility with strict type checking
• Framework integration: Native Django and Django REST Framework support
• Monitoring tools: Health checks and cleanup management commands
• Standard headers: X-RateLimit-* headers for client information

Quick Start

Installation

pip install django-smart-ratelimit[redis]

Basic Usage

from django_smart_ratelimit import rate_limit

# IP-based rate limiting
@rate_limit(key='ip', rate='100/h')
def api_endpoint(request):
    return JsonResponse({'data': 'protected'})

# User-based rate limiting
@rate_limit(key='user', rate='50/h')
def user_dashboard(request):
    return JsonResponse({'user_data': '...'})

Authentication Protection

@rate_limit(key='ip', rate='5/m', block=True)
def login_view(request):
    return authenticate_user(request)

Django REST Framework

from rest_framework import viewsets
from django_smart_ratelimit import rate_limit

class APIViewSet(viewsets.ViewSet):
    @rate_limit(key='ip', rate='100/h')
    def list(self, request):
        return Response({'data': 'list'})

Middleware Configuration

# settings.py
MIDDLEWARE = ['django_smart_ratelimit.middleware.RateLimitMiddleware']
RATELIMIT_MIDDLEWARE = {
    'DEFAULT_RATE': '1000/h',
    'RATE_LIMITS': {
        '/api/auth/': '10/m',
        '/api/': '500/h',
    }
}

Algorithm Comparison

Algorithm	Characteristics	Best For
token_bucket	Allows traffic bursts	APIs with variable load
sliding_window	Smooth request distribution	Consistent traffic control
fixed_window	Simple, predictable behavior	Basic rate limiting needs

Token Bucket Algorithm

The token bucket algorithm allows for burst traffic handling:

@rate_limit(
    key='user',
    rate='100/h',  # Base rate
    algorithm='token_bucket',
    algorithm_config={
        'bucket_size': 200,  # Allow bursts up to 200 requests
        'refill_rate': 2.0,  # Refill tokens at 2 per second
    }
)
def api_with_bursts(request):
    return JsonResponse({'data': 'handled'})

Common use cases:

• Mobile app synchronization after offline periods
• Batch file processing
• API retry mechanisms

Backend Configuration

Redis (Recommended)

RATELIMIT_BACKEND = 'redis'
RATELIMIT_REDIS = {
    'host': 'localhost',
    'port': 6379,
    'db': 0,
}

Database

RATELIMIT_BACKEND = 'database'
# Uses your default Django database

Multi-Backend with Failover

RATELIMIT_BACKENDS = [
    {
        'name': 'primary_redis',
        'backend': 'redis',
        'config': {'host': 'redis-primary.example.com'}
    },
    {
        'name': 'fallback_db',
        'backend': 'database',
        'config': {}
    }
]

Response Headers

The library adds standard rate limit headers to responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1642678800

Monitoring and Management

Health Checks

# Check backend health
python manage.py ratelimit_health

# Detailed status
python manage.py ratelimit_health --verbose

Cleanup (Database Backend)

# Clean expired entries
python manage.py cleanup_ratelimit

# Preview cleanup
python manage.py cleanup_ratelimit --dry-run

Library Features

• Multiple algorithms: Token bucket, sliding window, and fixed window
• Backend flexibility: Redis, Database, Memory, and Multi-Backend support
• Atomic operations: Redis Lua scripts prevent race conditions
• Automatic failover: Graceful degradation between backends
• Type safety: Full mypy compatibility with strict type checking
• Framework integration: Native Django and Django REST Framework support

Examples

The library includes comprehensive examples for various use cases:

• Basic Rate Limiting - IP and user-based limiting
• Custom Key Functions - Geographic and device-based keys
• JWT Rate Limiting - Token-based limiting
• DRF Integration - Django REST Framework examples
• Multi-tenant Applications - Tenant-aware rate limiting

Configuration Options

Decorator Parameters

@rate_limit(
    key='user',                    # Key function or string
    rate='100/h',                  # Rate limit (requests/period)
    algorithm='token_bucket',      # Algorithm choice
    algorithm_config={},           # Algorithm-specific config
    backend='redis',               # Backend override
    block=True,                    # Block vs. continue on limit
    skip_if=lambda req: req.user.is_staff,  # Skip condition
)

Testing

# Run tests
python -m pytest

# Run with coverage
python -m pytest --cov=django_smart_ratelimit

Decorator Examples

from django_smart_ratelimit import rate_limit

# Basic IP-based limiting
@rate_limit(key='ip', rate='10/m')
def public_api(request):
    return JsonResponse({'message': 'Hello World'})

# User-based limiting (automatically falls back to IP for anonymous users)
@rate_limit(key='user', rate='100/h')
def user_dashboard(request):
    return JsonResponse({'user_data': '...'})

# Custom key function for more control
@rate_limit(key=lambda req: f"user:{req.user.id}" if req.user.is_authenticated else f"ip:{req.META.get('REMOTE_ADDR')}", rate='50/h')
def flexible_api(request):
    return JsonResponse({'data': '...'})

# Block when limit exceeded (default is to continue)
@rate_limit(key='ip', rate='5/m', block=True)
def strict_api(request):
    return JsonResponse({'sensitive': 'data'})

# Skip rate limiting for staff users
@rate_limit(key='ip', rate='10/m', skip_if=lambda req: req.user.is_staff)
def staff_friendly_api(request):
    return JsonResponse({'data': 'staff can access unlimited'})

# Use sliding window algorithm
@rate_limit(key='user', rate='100/h', algorithm='sliding_window')
def smooth_api(request):
    return JsonResponse({'algorithm': 'sliding_window'})

# Use fixed window algorithm
@rate_limit(key='ip', rate='20/m', algorithm='fixed_window')
def burst_api(request):
    return JsonResponse({'algorithm': 'fixed_window'})

# Use token bucket algorithm (NEW!)
@rate_limit(
    key='api_key',
    rate='100/m',  # Base rate: 100 requests per minute
    algorithm='token_bucket',
    algorithm_config={
        'bucket_size': 200,  # Allow bursts up to 200 requests
        'refill_rate': 2.0,  # Refill at 2 tokens per second
    }
)
def api_with_bursts(request):
    return JsonResponse({'algorithm': 'token_bucket', 'burst_allowed': True})

Community & Support

• GitHub Discussions - Community support and questions
• Issues - Bug reports and feature requests
• Contributing - Contributing guidelines
• AI Usage Policy - Transparency about AI assistance in development

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

📚 Documentation • 💡 Examples • 🤝 Contributing • 💬 Discussions • 🤖 AI Usage