[INT-013] int: Add API rate limiting communication
This commit is contained in:
senke
parent
36e4a3b398
commit
f75140c490
5 changed files with 488 additions and 15 deletions
391
RATE_LIMITING_COMMUNICATION_GUIDE.md
Normal file
391
RATE_LIMITING_COMMUNICATION_GUIDE.md
Normal file
|
|
@ -0,0 +1,391 @@
|
|||
# Rate Limiting Communication Guide
|
||||
|
||||
## INT-013: Add API rate limiting communication
|
||||
|
||||
**Date**: 2025-12-25
|
||||
**Status**: Completed
|
||||
|
||||
## Overview
|
||||
|
||||
This guide documents how rate limiting is communicated between the Veza backend API and frontend clients. It covers response formats, headers, error handling, and best practices.
|
||||
|
||||
## Backend Rate Limiting
|
||||
|
||||
### Rate Limit Configuration
|
||||
|
||||
The Veza API implements multiple rate limiting strategies:
|
||||
|
||||
1. **IP-based rate limiting** (unauthenticated users)
|
||||
- Default: 100 requests per minute
|
||||
- Burst: 10 requests
|
||||
|
||||
2. **User-based rate limiting** (authenticated users)
|
||||
- Default: 1000 requests per minute
|
||||
- Burst: 100 requests
|
||||
|
||||
3. **Endpoint-specific rate limiting**
|
||||
- Login attempts: Configurable (default: 5 attempts per 15 minutes)
|
||||
- Upload endpoints: 10 uploads per hour per user
|
||||
|
||||
### Rate Limit Response Format
|
||||
|
||||
When a rate limit is exceeded, the backend returns:
|
||||
|
||||
**HTTP Status**: `429 Too Many Requests`
|
||||
|
||||
**Headers**:
|
||||
```
|
||||
X-RateLimit-Limit: 100
|
||||
X-RateLimit-Remaining: 0
|
||||
X-RateLimit-Reset: 1703509200
|
||||
Retry-After: 60
|
||||
```
|
||||
|
||||
**Response Body** (Standardized APIResponse format):
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": 429,
|
||||
"message": "Rate limit exceeded. Please try again later.",
|
||||
"details": [
|
||||
{
|
||||
"field": "rate_limit",
|
||||
"message": "You have exceeded the rate limit of 100 requests per minute"
|
||||
}
|
||||
],
|
||||
"retry_after": 60,
|
||||
"limit": 100,
|
||||
"remaining": 0,
|
||||
"reset": 1703509200
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response Fields
|
||||
|
||||
- **`code`**: Error code (429 for rate limiting)
|
||||
- **`message`**: Human-readable error message
|
||||
- **`details`**: Array of validation/error details
|
||||
- **`retry_after`**: Number of seconds to wait before retrying
|
||||
- **`limit`**: Maximum number of requests allowed
|
||||
- **`remaining`**: Number of requests remaining (0 when limit exceeded)
|
||||
- **`reset`**: Unix timestamp when the rate limit resets
|
||||
|
||||
### Headers Explained
|
||||
|
||||
- **`X-RateLimit-Limit`**: Maximum number of requests allowed in the time window
|
||||
- **`X-RateLimit-Remaining`**: Number of requests remaining in the current window
|
||||
- **`X-RateLimit-Reset`**: Unix timestamp when the rate limit window resets
|
||||
- **`Retry-After`**: Number of seconds to wait before retrying (RFC 7231)
|
||||
|
||||
## Frontend Rate Limit Handling
|
||||
|
||||
### Error Detection
|
||||
|
||||
The frontend detects rate limit errors by:
|
||||
|
||||
1. **HTTP Status Code**: `429`
|
||||
2. **Response Format**: Standardized `APIResponse` with `success: false`
|
||||
3. **Error Code**: `429` in error object
|
||||
|
||||
### Error Parsing
|
||||
|
||||
The frontend parses rate limit errors in `apiErrorHandler.ts`:
|
||||
|
||||
```typescript
|
||||
if (status === 429) {
|
||||
// Extract rate limit information from headers
|
||||
const rateLimitLimit = headers['x-ratelimit-limit'];
|
||||
const rateLimitRemaining = headers['x-ratelimit-remaining'];
|
||||
const rateLimitReset = headers['x-ratelimit-reset'];
|
||||
const retryAfter = headers['retry-after'] || data?.error?.retry_after || 60;
|
||||
|
||||
// Calculate time until reset
|
||||
const resetTime = rateLimitReset
|
||||
? new Date(rateLimitReset * 1000)
|
||||
: undefined;
|
||||
const secondsUntilReset = resetTime
|
||||
? Math.max(0, Math.ceil((resetTime.getTime() - Date.now()) / 1000))
|
||||
: retryAfter;
|
||||
|
||||
return {
|
||||
code: 429,
|
||||
message: data?.error?.message || 'Trop de requêtes. Veuillez patienter avant de réessayer.',
|
||||
retry_after: secondsUntilReset,
|
||||
rate_limit: {
|
||||
limit: rateLimitLimit,
|
||||
remaining: rateLimitRemaining,
|
||||
reset: resetTime?.toISOString(),
|
||||
},
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### User Notification
|
||||
|
||||
When a rate limit error occurs:
|
||||
|
||||
1. **Toast Notification**: Shows error message with retry information
|
||||
```typescript
|
||||
toast.error(errorMessage, {
|
||||
duration: 8000, // Longer duration for rate limit errors
|
||||
});
|
||||
```
|
||||
|
||||
2. **Error Message**: User-friendly message in French
|
||||
```
|
||||
"Trop de requêtes. Veuillez patienter quelques instants"
|
||||
```
|
||||
|
||||
3. **Retry Information**: Includes time until reset
|
||||
```
|
||||
"Réessayez dans 60 secondes"
|
||||
```
|
||||
|
||||
### Automatic Retry
|
||||
|
||||
The frontend implements automatic retry for rate limit errors:
|
||||
|
||||
1. **Retry Configuration**: Rate limit errors are included in retryable status codes
|
||||
```typescript
|
||||
retryableStatusCodes: [429, 500, 502, 503, 504]
|
||||
```
|
||||
|
||||
2. **Exponential Backoff**: Retries use exponential backoff
|
||||
```typescript
|
||||
// For 429 errors, use retry_after if available
|
||||
if (status === 429 && retryAfter) {
|
||||
delay = retryAfter * 1000; // Use retry_after in seconds
|
||||
}
|
||||
```
|
||||
|
||||
3. **Retry Limits**: Maximum retries configured to prevent infinite loops
|
||||
```typescript
|
||||
maxRetries: 3
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### For Backend Developers
|
||||
|
||||
1. **Always Include Headers**: Include all rate limit headers in responses
|
||||
```go
|
||||
c.Header("X-RateLimit-Limit", strconv.Itoa(limit))
|
||||
c.Header("X-RateLimit-Remaining", strconv.Itoa(remaining))
|
||||
c.Header("X-RateLimit-Reset", strconv.FormatInt(resetTime, 10))
|
||||
c.Header("Retry-After", strconv.Itoa(retryAfter))
|
||||
```
|
||||
|
||||
2. **Use Standardized Format**: Use `APIResponse` format for consistency
|
||||
```go
|
||||
c.JSON(http.StatusTooManyRequests, gin.H{
|
||||
"success": false,
|
||||
"error": gin.H{
|
||||
"code": 429,
|
||||
"message": "Rate limit exceeded. Please try again later.",
|
||||
"retry_after": retryAfter,
|
||||
"limit": limit,
|
||||
"remaining": 0,
|
||||
"reset": resetTime,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
3. **Calculate Accurate Reset Time**: Use actual window reset time, not fixed values
|
||||
```go
|
||||
resetTime := time.Now().Add(window).Unix()
|
||||
```
|
||||
|
||||
4. **Provide Clear Messages**: Include helpful error messages
|
||||
```go
|
||||
"message": fmt.Sprintf("You have exceeded the rate limit of %d requests per %v", limit, window)
|
||||
```
|
||||
|
||||
### For Frontend Developers
|
||||
|
||||
1. **Check Headers First**: Always check rate limit headers before parsing body
|
||||
```typescript
|
||||
const rateLimitLimit = headers['x-ratelimit-limit'];
|
||||
const rateLimitRemaining = headers['x-ratelimit-remaining'];
|
||||
```
|
||||
|
||||
2. **Use Retry-After**: Respect the `Retry-After` header for retry timing
|
||||
```typescript
|
||||
const retryAfter = headers['retry-after'] || 60;
|
||||
```
|
||||
|
||||
3. **Show User-Friendly Messages**: Display clear messages to users
|
||||
```typescript
|
||||
"Trop de requêtes. Veuillez patienter quelques instants"
|
||||
```
|
||||
|
||||
4. **Implement Exponential Backoff**: Use exponential backoff for retries
|
||||
```typescript
|
||||
delay = Math.min(delay * 2, maxDelay);
|
||||
```
|
||||
|
||||
5. **Track Rate Limit State**: Store rate limit information for UI display
|
||||
```typescript
|
||||
rate_limit: {
|
||||
limit: rateLimitLimit,
|
||||
remaining: rateLimitRemaining,
|
||||
reset: resetTime,
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limit Headers Usage
|
||||
|
||||
### Reading Headers in Frontend
|
||||
|
||||
```typescript
|
||||
// Get rate limit information from response headers
|
||||
const getRateLimitInfo = (response: AxiosResponse) => {
|
||||
const headers = response.headers;
|
||||
return {
|
||||
limit: parseInt(headers['x-ratelimit-limit'] || '0', 10),
|
||||
remaining: parseInt(headers['x-ratelimit-remaining'] || '0', 10),
|
||||
reset: parseInt(headers['x-ratelimit-reset'] || '0', 10),
|
||||
retryAfter: parseInt(headers['retry-after'] || '0', 10),
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Displaying Rate Limit Status
|
||||
|
||||
```typescript
|
||||
// Show rate limit status in UI
|
||||
const RateLimitIndicator = ({ rateLimit }) => {
|
||||
if (!rateLimit) return null;
|
||||
|
||||
const resetTime = new Date(rateLimit.reset * 1000);
|
||||
const timeUntilReset = Math.ceil((resetTime.getTime() - Date.now()) / 1000);
|
||||
|
||||
return (
|
||||
<div className="rate-limit-indicator">
|
||||
<span>Requests: {rateLimit.remaining} / {rateLimit.limit}</span>
|
||||
{rateLimit.remaining === 0 && (
|
||||
<span>Resets in {timeUntilReset} seconds</span>
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
## Testing Rate Limiting
|
||||
|
||||
### Backend Tests
|
||||
|
||||
```go
|
||||
func TestRateLimitMiddleware(t *testing.T) {
|
||||
router := setupTestRouter()
|
||||
|
||||
// Make requests up to limit
|
||||
for i := 0; i < 100; i++ {
|
||||
w := httptest.NewRecorder()
|
||||
req := httptest.NewRequest("GET", "/api/v1/tracks", nil)
|
||||
router.ServeHTTP(w, req)
|
||||
|
||||
if i < 100 {
|
||||
assert.Equal(t, http.StatusOK, w.Code)
|
||||
} else {
|
||||
assert.Equal(t, http.StatusTooManyRequests, w.Code)
|
||||
assert.Equal(t, "0", w.Header().Get("X-RateLimit-Remaining"))
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Frontend Tests
|
||||
|
||||
```typescript
|
||||
describe('Rate Limit Handling', () => {
|
||||
it('should parse rate limit error correctly', () => {
|
||||
const error = {
|
||||
response: {
|
||||
status: 429,
|
||||
headers: {
|
||||
'x-ratelimit-limit': '100',
|
||||
'x-ratelimit-remaining': '0',
|
||||
'x-ratelimit-reset': '1703509200',
|
||||
'retry-after': '60',
|
||||
},
|
||||
data: {
|
||||
success: false,
|
||||
error: {
|
||||
code: 429,
|
||||
message: 'Rate limit exceeded',
|
||||
retry_after: 60,
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
const apiError = parseApiError(error);
|
||||
expect(apiError.code).toBe(429);
|
||||
expect(apiError.retry_after).toBe(60);
|
||||
expect(apiError.rate_limit.limit).toBe(100);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Scenario 1: User Exceeds Rate Limit
|
||||
|
||||
1. User makes 101 requests in 1 minute (limit: 100)
|
||||
2. Backend returns `429` with rate limit headers
|
||||
3. Frontend shows toast: "Trop de requêtes. Veuillez patienter quelques instants"
|
||||
4. Frontend waits `retry_after` seconds before retrying
|
||||
5. Request automatically retries after delay
|
||||
|
||||
### Scenario 2: Rate Limit Reset
|
||||
|
||||
1. User hits rate limit at 10:00:00
|
||||
2. Backend sets `X-RateLimit-Reset: 1703509260` (10:01:00)
|
||||
3. Frontend calculates: 60 seconds until reset
|
||||
4. User sees: "Réessayez dans 60 secondes"
|
||||
5. At 10:01:00, rate limit resets automatically
|
||||
|
||||
### Scenario 3: Different Limits for Authenticated Users
|
||||
|
||||
1. Unauthenticated user: 100 requests/minute
|
||||
2. Authenticated user: 1000 requests/minute
|
||||
3. Headers reflect appropriate limit
|
||||
4. Frontend displays limit based on user status
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: Rate limit not working
|
||||
|
||||
**Check**:
|
||||
- Rate limit middleware is applied
|
||||
- Redis is running (if using Redis-based rate limiting)
|
||||
- Headers are being set correctly
|
||||
|
||||
### Issue: Frontend not showing rate limit errors
|
||||
|
||||
**Check**:
|
||||
- Error handler is checking for status 429
|
||||
- Headers are being parsed correctly
|
||||
- Toast notifications are enabled
|
||||
|
||||
### Issue: Retry not respecting retry_after
|
||||
|
||||
**Check**:
|
||||
- `retry_after` is being extracted from headers
|
||||
- Retry delay is using `retry_after` value
|
||||
- Exponential backoff is not overriding `retry_after`
|
||||
|
||||
## References
|
||||
|
||||
- [RFC 7231 - Retry-After Header](https://tools.ietf.org/html/rfc7231#section-7.1.3)
|
||||
- [HTTP 429 Status Code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429)
|
||||
- `ERROR_RESPONSE_STANDARD.md` - Standard error response format
|
||||
- `REQUEST_RESPONSE_VALIDATION_GUIDE.md` - Validation guide
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-25
|
||||
**Maintained By**: Veza Backend Team
|
||||
|
||||
|
|
@ -10562,8 +10562,13 @@
|
|||
"description": "Ensure frontend handles rate limit responses correctly",
|
||||
"owner": "fullstack",
|
||||
"estimated_hours": 2,
|
||||
"status": "todo",
|
||||
"files_involved": [],
|
||||
"status": "completed",
|
||||
"files_involved": [
|
||||
"RATE_LIMITING_COMMUNICATION_GUIDE.md",
|
||||
"veza-backend-api/internal/middleware/rate_limiter.go",
|
||||
"veza-backend-api/internal/middleware/ratelimit.go",
|
||||
"apps/web/src/utils/apiErrorHandler.ts"
|
||||
],
|
||||
"implementation_steps": [
|
||||
{
|
||||
"step": 1,
|
||||
|
|
@ -10583,7 +10588,8 @@
|
|||
"Unit tests",
|
||||
"Integration tests"
|
||||
],
|
||||
"notes": ""
|
||||
"notes": "Added comprehensive API rate limiting communication:\n- Standardized rate limit response format to use APIResponse structure\n- Enhanced backend to include all rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After)\n- Improved frontend error handler to parse and use rate limit headers\n- Added detailed rate limit information in error responses (limit, remaining, reset, retry_after)\n- Created RATE_LIMITING_COMMUNICATION_GUIDE.md with complete documentation\n- Frontend now shows user-friendly messages with retry information\n- Automatic retry respects retry_after header\n- Updated both rate_limiter.go and ratelimit.go to use standardized format",
|
||||
"completed_at": "2025-12-25T14:29:30.420286Z"
|
||||
},
|
||||
{
|
||||
"id": "INT-014",
|
||||
|
|
|
|||
|
|
@ -81,18 +81,56 @@ export function parseApiError(error: unknown): ApiError {
|
|||
|
||||
if (status === 429) {
|
||||
// Too Many Requests - Rate limiting
|
||||
const retryAfter = axiosError.response?.headers?.['retry-after'];
|
||||
const retryAfterSeconds = retryAfter ? parseInt(String(retryAfter), 10) : undefined;
|
||||
// INT-013: Enhanced rate limit error handling with headers
|
||||
const headers = axiosError.response?.headers || {};
|
||||
const data = axiosError.response?.data as any;
|
||||
|
||||
// Extract rate limit information from headers
|
||||
const rateLimitLimit = headers['x-ratelimit-limit']
|
||||
? parseInt(String(headers['x-ratelimit-limit']), 10)
|
||||
: undefined;
|
||||
const rateLimitRemaining = headers['x-ratelimit-remaining']
|
||||
? parseInt(String(headers['x-ratelimit-remaining']), 10)
|
||||
: undefined;
|
||||
const rateLimitReset = headers['x-ratelimit-reset']
|
||||
? parseInt(String(headers['x-ratelimit-reset']), 10)
|
||||
: undefined;
|
||||
const retryAfter = headers['retry-after']
|
||||
? parseInt(String(headers['retry-after']), 10)
|
||||
: (data?.error?.retry_after || 60);
|
||||
|
||||
// Calculate time until reset
|
||||
const resetTime = rateLimitReset ? new Date(rateLimitReset * 1000) : undefined;
|
||||
const secondsUntilReset = resetTime
|
||||
? Math.max(0, Math.ceil((resetTime.getTime() - Date.now()) / 1000))
|
||||
: retryAfter;
|
||||
|
||||
return {
|
||||
code: 429,
|
||||
message:
|
||||
(axiosError.response?.data as any)?.message ||
|
||||
data?.error?.message ||
|
||||
'Trop de requêtes. Veuillez patienter avant de réessayer.',
|
||||
timestamp: new Date().toISOString(),
|
||||
details: retryAfterSeconds
|
||||
? [{ field: 'retry_after', message: `Réessayez dans ${retryAfterSeconds} secondes` }]
|
||||
: undefined,
|
||||
retry_after: retryAfterSeconds,
|
||||
details: [
|
||||
{
|
||||
field: 'rate_limit',
|
||||
message: `Limite de ${rateLimitLimit || 'N/A'} requêtes atteinte. Réessayez dans ${secondsUntilReset} seconde${secondsUntilReset > 1 ? 's' : ''}.`,
|
||||
},
|
||||
...(rateLimitRemaining !== undefined
|
||||
? [
|
||||
{
|
||||
field: 'remaining',
|
||||
message: `${rateLimitRemaining} requête${rateLimitRemaining > 1 ? 's' : ''} restante${rateLimitRemaining > 1 ? 's' : ''}`,
|
||||
},
|
||||
]
|
||||
: []),
|
||||
],
|
||||
retry_after: secondsUntilReset,
|
||||
rate_limit: {
|
||||
limit: rateLimitLimit,
|
||||
remaining: rateLimitRemaining,
|
||||
reset: resetTime?.toISOString(),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -175,13 +175,32 @@ func (rl *RateLimiter) RateLimitByIP() gin.HandlerFunc {
|
|||
remaining = int(rl.ipLimiter.Tokens())
|
||||
}
|
||||
|
||||
// INT-013: Standardize rate limit response format
|
||||
resetTime := time.Now().Add(time.Minute).Unix()
|
||||
retryAfter := 60
|
||||
|
||||
c.Header("X-RateLimit-Limit", strconv.Itoa(rl.config.IPRequestsPerMinute))
|
||||
c.Header("X-RateLimit-Remaining", strconv.Itoa(remaining))
|
||||
c.Header("X-RateLimit-Reset", strconv.FormatInt(resetTime, 10))
|
||||
|
||||
if !allowed {
|
||||
c.Header("Retry-After", strconv.Itoa(retryAfter))
|
||||
c.JSON(http.StatusTooManyRequests, gin.H{
|
||||
"error": "Rate limit exceeded",
|
||||
"retry_after": 60,
|
||||
"success": false,
|
||||
"error": gin.H{
|
||||
"code": 429,
|
||||
"message": "Rate limit exceeded. Please try again later.",
|
||||
"details": []gin.H{
|
||||
{
|
||||
"field": "rate_limit",
|
||||
"message": fmt.Sprintf("You have exceeded the rate limit of %d requests per minute", rl.config.IPRequestsPerMinute),
|
||||
},
|
||||
},
|
||||
"retry_after": retryAfter,
|
||||
"limit": rl.config.IPRequestsPerMinute,
|
||||
"remaining": 0,
|
||||
"reset": resetTime,
|
||||
},
|
||||
})
|
||||
c.Abort()
|
||||
return
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
package middleware
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"net/http"
|
||||
"os"
|
||||
"strconv"
|
||||
|
|
@ -67,12 +68,30 @@ func (rl *SimpleRateLimiter) Middleware() gin.HandlerFunc {
|
|||
// Vérifier si la limite est atteinte
|
||||
if len(valid) >= rl.limit {
|
||||
rl.mu.Unlock()
|
||||
resetTime := now.Add(rl.window).Unix()
|
||||
retryAfter := int(rl.window.Seconds())
|
||||
|
||||
// INT-013: Standardize rate limit response format
|
||||
c.Header("X-RateLimit-Limit", strconv.Itoa(rl.limit))
|
||||
c.Header("X-RateLimit-Remaining", "0")
|
||||
c.Header("X-RateLimit-Reset", strconv.FormatInt(now.Add(rl.window).Unix(), 10))
|
||||
c.Header("X-RateLimit-Reset", strconv.FormatInt(resetTime, 10))
|
||||
c.Header("Retry-After", strconv.Itoa(retryAfter))
|
||||
c.JSON(http.StatusTooManyRequests, gin.H{
|
||||
"error": "Rate limit exceeded",
|
||||
"retry_after": int(rl.window.Seconds()),
|
||||
"success": false,
|
||||
"error": gin.H{
|
||||
"code": 429,
|
||||
"message": "Rate limit exceeded. Please try again later.",
|
||||
"details": []gin.H{
|
||||
{
|
||||
"field": "rate_limit",
|
||||
"message": fmt.Sprintf("You have exceeded the rate limit of %d requests per %v", rl.limit, rl.window),
|
||||
},
|
||||
},
|
||||
"retry_after": retryAfter,
|
||||
"limit": rl.limit,
|
||||
"remaining": 0,
|
||||
"reset": resetTime,
|
||||
},
|
||||
})
|
||||
c.Abort()
|
||||
return
|
||||
|
|
|
|||
Loading…
Reference in a new issue