Add Route Rate Limiting Support #290

Summary

Implement framework-native rate limiting via route DSL and centralized enforcement. Backend is selected globally from configuration. Per-route backend selection is not supported.

Functional Requirements

1. Add route DSL:
   • ->rateLimit(int $limit, int $interval)
2. Route stores rate-limit metadata (limit, interval).
3. Central enforcement checks metadata and applies limits.
4. On exceed, return HTTP 429 Too Many Requests.
5. Add response headers:
   • X-RateLimit-Limit
   • X-RateLimit-Remaining
   • Retry-After (blocked responses)

Adapter Contract

interface RateLimitAdapterInterface
{
    public function hit(string $key, int $limit, int $interval): bool;

    public function reset(string $key, int $count = 0): void;
}

Contract Semantics

1. hit() records one request attempt and returns:
   • true when request is allowed
   • false when limit is exceeded
2. reset($key) clears bucket state.
3. reset($key, $count) sets bucket count explicitly.

Architecture

1. RateLimit core depends only on RateLimitAdapterInterface.
2. Core must not call cache() directly.
3. Cache/Redis/File dependencies are isolated inside adapter implementations.
4. Wiring resolves adapter from rate_limit.default and injects it into service/middleware.

Backend Rules

1. No backend argument in route API.
2. Backend selection is global only via config('rate_limit.default').
3. Do not duplicate Redis connection settings in rate_limit.php.
4. Reuse existing infrastructure configuration for Redis/file connections.

Key Policy

Use one fixed internal key shape:

1. HTTP method
2. Route pattern
3. Client IP

No strategy config in this ticket.

Config

Create config/rate_limit.php:

<?php

return [
    'default' => 'file', // file|redis
];

Implementation Tasks

1. Extend src/Router/Route.php with rate-limit metadata accessors.
2. Extend src/Router/RouteBuilder.php with rateLimit($limit, $interval):
   • same chaining/error semantics as cacheable().
3. Add RateLimitAdapterInterface.
4. Add file adapter implementation.
5. Add redis adapter implementation.
6. Add centralized rate-limit enforcement (middleware or equivalent central hook).
7. Add/update tests for:
   • Route metadata behavior
   • RouteBuilder fluent behavior and error cases
   • Adapter hit/reset behavior
   • 429 enforcement flow and headers
   • global backend resolution from rate_limit.default

Out of Scope

1. Per-route backend override (for example, ->rateLimit(..., 'redis')).
2. Configurable key strategies.
3. Throttling/delay-based behavior.
4. Duplicating Redis connection config under rate_limit.php.