API de rate limiting escrita em PHP para fins didáticos como: mostrar como implementar autoload PSR-4, uma camada HTTP mínima, um algoritmo de rate limit e testes automatizados usando apenas a linguagem e o Composer.
Não tem interface. Somente a rota HTTP, pensada para ser chamada via curl, Postman ou similar, e rodar em Docker.
O rate limit usa o algoritmo de fixed window (janela fixa):
- Cada chave (
key) tem um contador e um horário de expiração (expires_at). - A primeira requisição de uma chave cria uma janela de
windowsegundos e conta 1. - Cada requisição seguinte, dentro da mesma janela, incrementa o contador.
- Quando o contador atinge o
limit, a requisição é bloqueada e a API devolve quanto tempo falta até a janela resetar (retry_after). - Quando o tempo da janela expira, o contador reseta e uma nova janela começa.
É o algoritmo mais simples de rate limit que existe — fácil de entender e implementar, mas tem uma limitação didática interessante: como a janela é fixa, é possível ter um pico de até 2x o limite bem na borda entre duas janelas (ex.: 5 requisições no fim de uma janela + 5 no início da próxima). Fica registrado aqui como conhecimento — não é bug, é uma característica do algoritmo (a alternativa seria sliding window, mais precisa e mais cara de calcular).
O estado (contadores) é persistido em um arquivo JSON (storage/rate-limit.json), usando flock() para evitar corrupção de dados em requisições concorrentes.
- PHP 8.3+
- Composer
composer installphp -S 127.0.0.1:8000 -t publicBody (JSON):
| Campo | Tipo | Descrição |
|---|---|---|
key |
string | Identificador único a ser limitado (ex.: IP, user ID, API key) |
limit |
int | Número máximo de requisições permitidas na janela |
window |
int | Duração da janela, em segundos |
Exemplo de requisição:
curl -X POST http://127.0.0.1:8000/api/v1/ratelimit/check \
-H "Content-Type: application/json" \
-d '{"key":"user-1","limit":5,"window":60}'Resposta (200) — permitido:
{
"allowed": true,
"limit": 5,
"remaining": 4,
"retry_after": 0
}Resposta (200) — bloqueado (limite excedido):
{
"allowed": false,
"limit": 5,
"remaining": 0,
"retry_after": 42
}Resposta (422) — parâmetros inválidos (key vazio/ausente, limit ou window ausentes ou não positivos):
{
"error": "invalid_request",
"message": "Invalid rate limit parameters."
}Resposta (400) — corpo não é um JSON válido:
{
"error": "invalid_json",
"message": "Invalid JSON body."
}Resposta (404) — rota ou método diferente do esperado:
{
"error": "not_found"
}docker compose up --buildA API fica disponível em http://localhost:8000. O diretório storage/ do host é montado dentro do container, então o estado do rate limit persiste entre reinícios.
Para rodar os testes dentro do container (sem precisar de PHP/Composer instalado localmente):
docker compose exec api vendor/bin/phpunitA imagem instala as dependências de desenvolvimento (incluindo o PHPUnit) para facilitar esse fluxo — não é uma imagem otimizada para produção.
composer testou diretamente:
vendor/bin/phpunitA suíte cobre:
JsonRateLimitStorage: liberação dentro do limite, bloqueio ao exceder, contagem independente por chave, expiração/reset de janela e persistência entre instâncias.RateLimiter: delegação correta para a camada de storage.RateLimitController: respostas de sucesso (allowed/blocked) e validação (422) para diferentes payloads inválidos.
Dockerfile Imagem PHP + Composer para rodar a API (e os testes) em container
docker-compose.yml Atalho para build/run com porta e storage montados
public/index.php Ponto de entrada HTTP (roteamento simples + tratamento de erros)
src/Http/JsonRequest.php Leitura e decodificação do corpo JSON da requisição
src/Http/Response.php Serialização da resposta HTTP em JSON
src/Controller/RateLimitController.php Validação da entrada e orquestração da chamada ao rate limiter
src/RateLimit/RateLimiter.php Delega a checagem para a camada de storage
src/RateLimit/RateLimitStorage.php Interface do contrato de storage (permite outras implementações no futuro)
src/RateLimit/JsonRateLimitStorage.php Implementação do storage em arquivo JSON (fixed window)
src/RateLimit/RateLimitResult.php DTO imutável com o resultado da checagem
storage/ Arquivo de estado do rate limit (ignorado pelo git, gerado em runtime)
tests/ Testes automatizados (PHPUnit)
- Storage em arquivo JSON não escala para múltiplos processos/containers concorrentes em alto volume — em produção, o certo seria Redis ou outro storage compartilhado de baixa latência. Como a lógica está isolada atrás de
RateLimitStorage, trocar a implementação não exige mudar oRateLimiternem oController. - Algoritmo fixed window (ver seção "Como funciona") permite picos na borda da janela.