goplt/docs/content/adr/0027-rate-limiting-strategy.md

ADR-0027: Rate Limiting Strategy

Status

Accepted

Context

The platform needs rate limiting to:

• Prevent abuse and DoS attacks
• Protect against brute-force attacks
• Ensure fair resource usage
• Comply with API usage policies

Rate limiting strategies:

1. Per-user rate limiting - Based on authenticated user
2. Per-IP rate limiting - Based on client IP
3. Fixed rate limiting - Global limits
4. Distributed rate limiting - Shared state across instances

Decision

Implement multi-level rate limiting:

1. Per-user rate limiting: For authenticated requests (e.g., 100 req/min)
2. Per-IP rate limiting: For all requests (e.g., 1000 req/min)
3. Storage: Redis for distributed rate limiting
4. Algorithm: Token bucket or sliding window

Rationale:

• Multi-level provides defense in depth
• Per-user prevents abuse by authenticated users
• Per-IP protects against unauthenticated abuse
• Redis enables distributed rate limiting (multi-instance)
• Token bucket provides smooth rate limiting

Consequences

Positive

• Multi-layer protection
• Works with multiple instances
• Configurable per endpoint
• Standard approach

Negative

• Requires Redis (or shared state)
• Additional latency (minimal)
• Need to handle Redis failures gracefully

Implementation Notes

• Use github.com/ulule/limiter/v3 library
• Configure limits in config file
• Store rate limit state in Redis
• Return X-RateLimit-* headers
• Handle Redis failures gracefully (fail open or closed based on config)
• Configure different limits for different endpoints