Enhance rate limiting with user-based limits and proxy handling

[ErnieAtLYD]

Problem

Current rate limiting relies solely on IP addresses, which can be unreliable behind proxies/CDNs and doesn't account for authenticated users who should have different limits.

Solution

Implement enhanced rate limiting with user-based limits, better proxy handling, and configurable limit tiers.

Tasks

• Improve IP detection for proxy/CDN scenarios
• Add user-based rate limiting (when authentication is added)
• Implement tiered rate limiting (anonymous, authenticated, premium)
• Add distributed rate limiting for multi-instance deployments
• Add rate limiting bypass for admin users
• Implement sliding window rate limiting
• Add rate limiting headers in API responses

Rate Limiting Tiers

• Anonymous: 5 requests/hour
• Authenticated: 50 requests/hour
• Premium: 200 requests/hour
• Admin: Unlimited

Proxy Handling Improvements

• Better X-Forwarded-For parsing
• Support for X-Real-IP headers
• Cloudflare CF-Connecting-IP support
• Rate limiting by user session when IP is unreliable

Acceptance Criteria

• Rate limits work correctly behind proxies/CDNs
• Different user tiers have appropriate limits
• Rate limiting state is shared across server instances
• Users receive clear rate limit information in responses
• Rate limiting doesn't break legitimate usage patterns

Priority

Medium - Important for fair usage but current implementation works

Related

Rate limiting concerns from PR #12 code review

[ErnieAtLYD]

@claude what would you implementation plan?

[claude]

Claude finished @ErnieAtLYD's task —— View job

---

Implementation Plan for Enhanced Rate Limiting

Todo List

• Analyze current rate limiting implementation
• Review tech stack and available infrastructure
• Design enhanced rate limiting architecture
• Create detailed implementation plan with phases
• Address proxy handling requirements
• Plan user tier system integration
• Design distributed rate limiting approach
• Plan sliding window implementation
• Design API response headers strategy

Current State Analysis

No existing rate limiting - Fresh implementation needed for Next.js 15 app currently deployed on Vercel with no backend APIs.

Implementation Plan - Phased Approach

Phase 1: Foundation (Week 1-2)

• Basic middleware with IP-based rate limiting
• Proxy header detection utility
• In-memory store for development
• Core rate limiter service

Phase 2: User Tiers (Week 3)

• Anonymous: 5/hour, Authenticated: 50/hour, Premium: 200/hour, Admin: unlimited
• Session-based fallback when IP unreliable
• Enhanced proxy detection (CF-Connecting-IP, X-Real-IP, X-Forwarded-For)

Phase 3: Production Storage (Week 4)

• Vercel KV integration for distributed deployments
• Redis adapter alternative
• Shared rate limit state across instances

Phase 4: Advanced Features (Week 5-6)

• Sliding window algorithm
• Comprehensive API headers
• Admin bypass functionality

Technical Implementation Details

Sliding Window Algorithm

Uses timestamp array with efficient cleanup via binary search. Tracks requests within rolling time window for accurate rate limiting without burst allowance issues.

API Response Headers Strategy

// Standard rate limiting headers (RFC 6585 + draft standards)
'X-RateLimit-Limit': '50'                    // Requests allowed per window
'X-RateLimit-Remaining': '42'                // Requests left in current window  
'X-RateLimit-Reset': '1640995200'            // Unix timestamp when window resets
'X-RateLimit-Policy': '50;w=3600'            // Policy: limit;window=3600s
'Retry-After': '300'                         // Seconds to wait (when rate limited)

// Custom headers for enhanced debugging
'X-RateLimit-Key': 'ip:192.168.1.1'         // Identifier used for rate limiting
'X-RateLimit-Tier': 'authenticated'         // User tier applied

Proxy Handling Priority

1. CF-Connecting-IP (Cloudflare)
2. X-Real-IP (nginx/reverse proxies)
3. X-Forwarded-For (load balancers) - first valid public IP
4. request.ip (direct connection fallback)

Key Features

• Multi-tier rate limiting with user-based overrides
• Distributed state via Vercel KV or Redis
• Sliding window prevents burst circumvention
• Proxy-aware IP detection with fallbacks
• Standard HTTP headers for client integration
• Admin bypass for operational access
• Session fallback when IP detection unreliable

Dependencies Required

{
  "@vercel/kv": "^1.0.0",        // Vercel KV store
  "ioredis": "^5.3.0",          // Redis client (alternative)
  "ip-range-check": "^0.2.0"    // Private IP validation
}

This plan provides a comprehensive, production-ready rate limiting system that scales with your application's growth from client-side app to full-stack platform.

---