Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Rate Limit API

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.

Como funciona

O rate limit usa o algoritmo de fixed window (janela fixa):

  1. Cada chave (key) tem um contador e um horário de expiração (expires_at).
  2. A primeira requisição de uma chave cria uma janela de window segundos e conta 1.
  3. Cada requisição seguinte, dentro da mesma janela, incrementa o contador.
  4. Quando o contador atinge o limit, a requisição é bloqueada e a API devolve quanto tempo falta até a janela resetar (retry_after).
  5. 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.

Requisitos

  • PHP 8.3+
  • Composer

Instalação

composer install

Rodando a API

php -S 127.0.0.1:8000 -t public

Endpoint

POST /api/v1/ratelimit/check

Body (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"
}

Rodando com Docker

docker compose up --build

A 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/phpunit

A imagem instala as dependências de desenvolvimento (incluindo o PHPUnit) para facilitar esse fluxo — não é uma imagem otimizada para produção.

Rodando os testes

composer test

ou diretamente:

vendor/bin/phpunit

A 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.

Estrutura do projeto

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)

Limitações conhecidas (propositais, para fins didáticos)

  • 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 o RateLimiter nem o Controller.
  • Algoritmo fixed window (ver seção "Como funciona") permite picos na borda da janela.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages