Rate Limiter Laravel Package

Technical Evaluation

Architecture Fit

• Calendar-Aligned Fixed Window Mode: Introduces a new rate-limiting algorithm (calendar-aligned fixed window) alongside the existing token bucket. This mode aligns with time-based windows (e.g., "100 requests per hour, starting at the top of the hour"), improving predictability for scheduled workloads (e.g., cron jobs, batch processing). The fix in v8.1.0-BETA3 (#64294) hardens this mode, addressing edge cases where window boundaries could cause inconsistent counting across distributed systems.
• Laravel Integration: Remains seamless with Laravel’s service container and caching backends. The new mode can coexist with the token bucket, allowing mixed policy strategies (e.g., token bucket for APIs + fixed window for batch jobs).
• Distributed Systems: Redis/Memcached support is unchanged, but the fixed window mode now handles time-zone-aware window alignment more robustly, reducing race conditions in multi-AZ deployments.
• Compound Policies: CompoundRateLimiterFactory now supports mixing token bucket and fixed window policies, enabling complex scenarios (e.g., "100 requests/hour for batch jobs AND 10 requests/second for APIs").
• HTTP Compliance: Retry-After headers remain RFC 6585-compliant; no regressions.

Integration Feasibility

• Low Friction for Existing Code: No breaking changes to existing token bucket implementations. The fixed window mode is opt-in and requires explicit configuration.
• Laravel Middleware: No impact on RateLimiterMiddleware; existing token bucket policies continue to work unchanged.
• Queue Workers: Queue-based rate limiting (e.g., Job::handle()) can now use fixed window mode for scheduled jobs, improving alignment with cron-like workflows.
• CLI Commands: Artisan commands can leverage calendar-aligned windows for batch operations (e.g., php artisan schedule:run).
• Event-Driven: Event logging (e.g., Telescope) remains unaffected; new mode adds window-boundary events for observability.

Technical Risk

• Storage Backend: No changes; Redis/Memcached still required for distributed setups (~5ms latency). Fixed window mode may increase storage usage due to per-window tracking.
• PHP Version: Still requires PHP 8.1+ (Symfony 8+). Legacy apps face upgrade risk.
• Fixed Window Nuances:
  • v8.1.0-BETA3 hardens window alignment, but time-zone handling must be explicitly configured (default: UTC).
  • Testing required: Validate mixed-mode policies (e.g., token bucket + fixed window) and window boundary edge cases (e.g., requests crossing hour boundaries).
• Cold Starts: Serverless environments (Lambda) may experience initial latency if Redis isn’t pre-warmed, especially for fixed window mode.
• Compound Limits: Increased complexity; teams must understand logical policies (e.g., RateLimiter::createCompound([$tokenBucketPolicy, $fixedWindowPolicy])).

Key Questions

1. Storage Strategy:
   • Updated: Fixed window mode may increase Redis memory usage due to per-window tracking. Monitor eviction rates.
   • Confirm fallback behavior for Redis failures in fixed window mode.
2. Policy Design:
   • New: Evaluate use cases for calendar-aligned fixed window (e.g., batch jobs, scheduled tasks).
   • How will we test mixed-mode policies (token bucket + fixed window)?
   • What time zone should window alignment use (e.g., UTC vs. user-local)?
3. Observability:
   • Updated: Log window-boundary events to Telescope/Datadog. Monitor for window alignment issues.
   • Set alerts for window overflows (e.g., requests exceeding limits at boundary crossings).
4. Performance:
   • Updated: Fixed window mode may add ~1-2ms overhead per request (vs. token bucket). Benchmark in production-like conditions.
   • Will we cache limiter instances (e.g., app()->singleton) to reduce overhead?
5. Fallbacks:
   • Updated: Define behavior if rate limiter fails (e.g., Redis down). Test fixed window fallback (e.g., allow requests if Redis fails).
6. Testing:
   • Updated: Add tests for:
     • Fixed window boundary scenarios (e.g., requests at :59:59 vs. :00:00).
     • Mixed-mode policies (token bucket + fixed window).
     • Time-zone alignment (e.g., UTC vs. user-local).
   • Simulate traffic spikes with Artillery/k6, focusing on window transitions.

Integration Approach

Stack Fit

• Laravel Core: Unchanged for token bucket; new fixed window mode requires explicit configuration.
• Caching Layer: Uses Laravel’s cache drivers (Redis, database, file) for storage. Fixed window mode recommends Redis for distributed consistency.
• Queue System: Applies rate limiting to Laravel Queues (Job::handle()) with new fixed window support for scheduled jobs.
• HTTP Layer: Injects Retry-After headers; no regressions.
• Event System: Logs rate-limiting events (now including window-boundary events) via Laravel’s events/Monolog.
• Service Container: Register RateLimiterFactory as a singleton/contextual binding; fixed window mode is opt-in.

Migration Path

1. Assessment Phase:
   • Audit existing rate-limiting logic. Identify scheduled/batch workloads (e.g., cron jobs, batch imports) as candidates for fixed window mode.
   • Prioritize high-risk endpoints (e.g., /api/webhooks, /api/batch) for pilot testing.
2. Pilot Phase:
   • Replace one batch endpoint (e.g., /api/import) with fixed window mode.
   • Test with load tools (Artillery/k6) to validate:
     • Window boundary behavior (e.g., requests at :59:59 vs. :00:00).
     • Mixed-mode policies (token bucket + fixed window).
   • Compare performance vs. token bucket (e.g., latency, memory usage).
3. Rollout Phase:
   • Middleware: Keep RateLimiterMiddleware for token bucket; add fixed window policies for batch endpoints.
   • Queues: Apply fixed window to Job::handle() for scheduled jobs; verify window alignment.
   • CLI: Protect Artisan commands (e.g., php artisan schedule:run) with fixed window mode.
   • Dynamic Adjustments: Implement runtime policy updates (e.g., via Horizon).
4. Observability Phase:
   • Log window-boundary events to Telescope/Datadog.
   • Monitor for window alignment issues (e.g., misaligned clocks in distributed setups).
   • Set alerts for policy violations (e.g., Slack/PagerDuty).

Compatibility

• Laravel 10+: Native integration with Symfony v8.1.0-BETA3.
• Laravel 9: Manual dependency injection required (composer require symfony/rate-limiter:^8.1).
• Legacy PHP (<8.1): Not supported; upgrade required.
• Non-Laravel Symfony: Works natively in Symfony apps.
• Third-Party Packages: No conflicts; v8.1.0-BETA3 is backward-compatible for token bucket mode.

Sequencing

1. Storage Backend: Configure Redis/Memcached first (critical for fixed window mode).
2. Core Policies:
   • Define global token bucket policies in config/rate_limits.php.
   • Add fixed window policies for batch/scheduled workloads.
3. Middleware: Replace throttle with RateLimiterMiddleware (token bucket only).
4. Queues/CLI:
   • Apply token bucket to high-concurrency endpoints.
   • Apply fixed window to batch/scheduled jobs.
5. Observability: Set up logging/alerts; validate event accuracy for both modes.
6. Dynamic Adjustments: Implement runtime policy updates (e.g., via Horizon).

Operational Impact

Maintenance

• Moderate Effort: Fixed window mode introduces new configuration and testing requirements.
• Dependency Updates: Monitor Symfony for breaking changes (e.g., PHP 8.4+ in v9.0).
• Policy Updates:
  • Adjust limits via config/rate_limits.php or env vars.
  • New: Define time zones and window boundaries for fixed window mode.
• Storage Maintenance: Redis/Memcached requires monitoring (memory, evictions); fixed window mode may increase usage.

Support

• Debugging:
  • Use RateLimiter::getTokensLeft() (token bucket) or RateLimiter::getRemainingRequests() (fixed window)