feat: Add rate limiting middleware with SlowAPI

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
2026-02-10 16:17:53 +00:00
parent 0b3f9212d1
commit 8d347e0a53
10 changed files with 659 additions and 0 deletions
@@ -7,6 +7,7 @@ DocuElevate provides a powerful REST API for programmatic access to all its feat
 - Base URL: `http://<your-docuelevate-instance>/api`
 - Authentication: OAuth2 (when enabled)
 - Response Format: JSON
+- Rate Limiting: Enabled by default (see Rate Limiting section below)

 ## Interactive API Documentation

@@ -16,6 +17,73 @@ The most up-to-date and interactive API documentation is available at:

 This Swagger UI provides a complete reference with the ability to try out API calls directly from your browser.

+## Rate Limiting
+
+DocuElevate implements rate limiting to protect against abuse and DoS attacks. Rate limits are enforced per IP address for unauthenticated requests and per user for authenticated requests.
+
+### Default Limits
+
+- **Default endpoints**: 100 requests per minute
+- **File upload**: 20 requests per minute
+- **Document processing**: 30 requests per minute
+- **Authentication**: 10 requests per minute
+
+### Rate Limit Headers
+
+When a rate limit is exceeded, the API returns a `429 Too Many Requests` response:
+
+```json
+{
+  "detail": "Rate limit exceeded: 100 per 1 minute"
+}
+```
+
+The response includes a `Retry-After` header indicating when the client can retry the request.
+
+### Configuration
+
+Rate limits can be configured via environment variables:
+
+```bash
+RATE_LIMITING_ENABLED=true
+RATE_LIMIT_DEFAULT=100/minute
+RATE_LIMIT_UPLOAD=20/minute
+RATE_LIMIT_PROCESS=30/minute
+RATE_LIMIT_AUTH=10/minute
+```
+
+See [Configuration Guide](ConfigurationGuide.md) for more details.
+
+### Best Practices
+
+1. **Respect rate limits**: Monitor your request rates and implement backoff strategies
+2. **Cache responses**: Reduce unnecessary API calls by caching responses when appropriate
+3. **Batch operations**: Use bulk endpoints when available instead of making multiple individual requests
+4. **Handle 429 responses**: Implement retry logic with exponential backoff when rate limits are exceeded
+
+### Example: Handling Rate Limits
+
+```python
+import requests
+import time
+
+def make_api_request(url, max_retries=3):
+    """Make API request with rate limit handling."""
+    for attempt in range(max_retries):
+        response = requests.get(url)
+        
+        if response.status_code == 429:
+            # Rate limit exceeded
+            retry_after = int(response.headers.get('Retry-After', 60))
+            print(f"Rate limit exceeded. Retrying after {retry_after} seconds...")
+            time.sleep(retry_after)
+            continue
+        
+        return response
+    
+    raise Exception("Max retries exceeded")
+```
+
 ## Authentication

 When authentication is enabled, you must include an authentication token in your requests:
@@ -102,6 +102,102 @@ DocuElevate can monitor multiple IMAP mailboxes for document attachments. Each m

 DocuElevate supports HTTP security headers to improve browser-side security. **These headers are disabled by default** since most deployments use a reverse proxy (Traefik, Nginx, etc.) that already adds them. Enable only if deploying directly without a reverse proxy. See [Deployment Guide - Security Headers](DeploymentGuide.md#security-headers) for detailed configuration examples.

+### Rate Limiting
+
+DocuElevate implements rate limiting to protect against DoS attacks and API abuse. **Rate limiting is enabled by default** and uses Redis for distributed rate limiting across multiple workers.
+
+#### Master Control
+
+| **Variable**              | **Description**                                                                    | **Default** |
+|---------------------------|------------------------------------------------------------------------------------|-------------|
+| `RATE_LIMITING_ENABLED`   | Enable/disable rate limiting middleware. Recommended for production.               | `true`      |
+
+#### Rate Limit Configuration
+
+Rate limits are specified in the format `count/period`, where:
+- `count` is the maximum number of requests allowed
+- `period` is one of: `second`, `minute`, `hour`, `day`
+
+| **Variable**           | **Description**                                                      | **Default**      | **Applies To**                          |
+|------------------------|----------------------------------------------------------------------|------------------|-----------------------------------------|
+| `RATE_LIMIT_DEFAULT`   | Default rate limit for all API endpoints                             | `100/minute`     | Most API endpoints                      |
+| `RATE_LIMIT_UPLOAD`    | Rate limit for file upload endpoints (prevents resource exhaustion)  | `20/minute`      | `/api/ui-upload` and similar            |
+| `RATE_LIMIT_PROCESS`   | Rate limit for processing endpoints (OCR, metadata extraction)       | `30/minute`      | `/api/process`, OCR endpoints           |
+| `RATE_LIMIT_AUTH`      | Stricter rate limit for authentication (prevents brute force)        | `10/minute`      | Login, authentication endpoints         |
+
+#### How Rate Limiting Works
+
+1. **Per-User Tracking**: For authenticated requests, limits are enforced per user ID
+2. **Per-IP Tracking**: For unauthenticated requests, limits are enforced per IP address
+3. **429 Response**: When limit is exceeded, API returns `429 Too Many Requests` with `Retry-After` header
+4. **Redis Backend**: Uses Redis for distributed rate limiting (required for multi-worker deployments)
+5. **In-Memory Fallback**: Falls back to in-memory storage if Redis is unavailable (not recommended for production)
+
+#### Configuration Example
+
+```bash
+# Enable rate limiting (recommended for production)
+RATE_LIMITING_ENABLED=true
+
+# Configure Redis for distributed rate limiting
+REDIS_URL=redis://redis:6379/0
+
+# Customize rate limits
+RATE_LIMIT_DEFAULT=100/minute     # 100 requests per minute per user/IP
+RATE_LIMIT_UPLOAD=20/minute       # 20 uploads per minute
+RATE_LIMIT_PROCESS=30/minute      # 30 processing requests per minute
+RATE_LIMIT_AUTH=10/minute         # 10 auth attempts per minute (brute force protection)
+```
+
+#### Recommended Limits by Deployment Size
+
+**Small Deployment (1-10 users)**:
+```bash
+RATE_LIMIT_DEFAULT=200/minute
+RATE_LIMIT_UPLOAD=50/minute
+RATE_LIMIT_PROCESS=50/minute
+RATE_LIMIT_AUTH=20/minute
+```
+
+**Medium Deployment (10-100 users)**:
+```bash
+RATE_LIMIT_DEFAULT=100/minute
+RATE_LIMIT_UPLOAD=20/minute
+RATE_LIMIT_PROCESS=30/minute
+RATE_LIMIT_AUTH=10/minute
+```
+
+**Large Deployment (100+ users)**:
+```bash
+RATE_LIMIT_DEFAULT=50/minute
+RATE_LIMIT_UPLOAD=10/minute
+RATE_LIMIT_PROCESS=15/minute
+RATE_LIMIT_AUTH=5/minute
+```
+
+#### Disabling Rate Limiting (Development Only)
+
+For development or testing, you can disable rate limiting:
+
+```bash
+RATE_LIMITING_ENABLED=false
+```
+
+**Warning**: Do not disable rate limiting in production environments.
+
+#### Monitoring Rate Limits
+
+When rate limits are exceeded, check application logs for details:
+
+```
+2024-02-10 16:00:00 - Rate limiting by user: testuser
+2024-02-10 16:00:01 - Rate limit exceeded: 100 per 1 minute
+```
+
+For more information on handling rate-limited responses in API clients, see [API Documentation - Rate Limiting](API.md#rate-limiting).
+
+#### Security Headers
+
 #### Master Control

 | **Variable**                | **Description**                                                         | **Default** |