Middlewares Disponíveis
Todos os middlewares do kernel que você pode usar nas rotas do seu módulo.
Middlewares de autenticação
| Middleware | Descrição | Uso típico |
|---|---|---|
AuthHybridMiddleware | Aceita cookie ou Bearer token. Popula $request->attribute('auth_user') | Rotas protegidas para usuários logados |
AuthCookieMiddleware | Aceita apenas cookie (não aceita Bearer token) | Rotas de página HTML que exigem login via cookie |
AuthPageMiddleware | Autentica via cookie e redireciona para login se não autenticado | Páginas HTML protegidas (ex: dashboard) |
OptionalAuthHybridMiddleware | Autentica se token presente, mas não bloqueia | Rotas públicas com comportamento diferente para logados |
AdminOnlyMiddleware | Exige nível admin_system | Rotas administrativas |
ApiTokenMiddleware | Valida token de API (X-API-KEY) | Integrações machine-to-machine |
RouteProtectionMiddleware | Valida JWT e verifica blacklist | Rotas que aceitam token de usuário ou API |
Middlewares de autorização (Scopes)
| Middleware | Parâmetros | Descrição |
|---|---|---|
ApiKeyScopeMiddleware | scopes | Verifica se API key tem os scopes necessários (write, delete, admin) |
RequireWriteScope | — | Atalho para exigir scope 'write' na API key |
RequireDeleteScope | — | Atalho para exigir scope 'delete' na API key |
Scopes de API Keys
API Keys podem ter scopes limitados (read, write, delete, admin). Use ApiKeyScopeMiddleware para garantir que a chave tem permissão para a operação.
Middlewares de proteção e performance
| Middleware | Parâmetros | Descrição |
|---|---|---|
RateLimitMiddleware | limit, window, key, user_limit | Limita requisições por janela de tempo |
CircuitBreakerMiddleware | service, threshold, cooldown | Abre o circuito após N falhas consecutivas |
ResponseCacheMiddleware | ttl, varyByQuery | Cacheia respostas GET 200 OK (reduz latência de 200ms para ~5ms) |
BotBlockerMiddleware | — | Bloqueia bots e scrapers conhecidos |
HttpsEnforcerMiddleware | — | Redireciona HTTP para HTTPS |
SecurityHeadersMiddleware | — | Adiciona headers de segurança (CSP, X-Frame-Options, etc.) |
ResponseCacheMiddleware — Performance
Use em rotas públicas GET que não mudam frequentemente. Pode melhorar throughput em 10-50x e reduzir latência de 200ms para ~5ms. Não use em rotas autenticadas (cache é compartilhado entre usuários).
Exemplos de uso nas rotas
<?php
use Src\Kernel\Middlewares\AuthHybridMiddleware;
use Src\Kernel\Middlewares\AdminOnlyMiddleware;
use Src\Kernel\Middlewares\RateLimitMiddleware;
use Src\Kernel\Middlewares\CircuitBreakerMiddleware;
use Src\Kernel\Middlewares\ResponseCacheMiddleware;
use Src\Kernel\Middlewares\ApiKeyScopeMiddleware;
use Src\Kernel\Middlewares\RequireWriteScope;
use Src\Kernel\Middlewares\RequireDeleteScope;
/** @var \Src\Kernel\Contracts\RouterInterface $router */
// Apenas autenticado
$auth = [AuthHybridMiddleware::class];
// Apenas admin
$admin = [AuthHybridMiddleware::class, AdminOnlyMiddleware::class];
// Com rate limit: 30 req/min
$rateLimit = [
AuthHybridMiddleware::class,
[RateLimitMiddleware::class, ['limit' => 30, 'window' => 60, 'key' => 'produto']]
];
// Com circuit breaker
$circuit = [
AuthHybridMiddleware::class,
[CircuitBreakerMiddleware::class, ['service' => 'database', 'threshold' => 5, 'cooldown' => 30]]
];
// Com cache de resposta (rotas públicas GET)
$cached = [
[ResponseCacheMiddleware::class, ['ttl' => 60]] // Cacheia por 60 segundos
];
// Exige scope 'write' na API key
$writeProtected = [
AuthHybridMiddleware::class,
RequireWriteScope::class
];
// Exige scope 'delete' na API key
$deleteProtected = [
AuthHybridMiddleware::class,
RequireDeleteScope::class
];
// Exige múltiplos scopes
$adminApiKey = [
AuthHybridMiddleware::class,
[ApiKeyScopeMiddleware::class, ['scopes' => ['admin', 'write']]]
];
// Rota pública com cache
$router->get('/api/status', [StatusController::class, 'index'], $cached);
// Rota protegida com rate limit
$router->post('/api/produto', [ProdutoController::class, 'criar'], $rateLimit);
// Rota que exige scope 'write'
$router->put('/api/produto/{id}', [ProdutoController::class, 'atualizar'], $writeProtected);
// Rota que exige scope 'delete'
$router->delete('/api/produto/{id}', [ProdutoController::class, 'deletar'], $deleteProtected);
// Combinando múltiplos middlewares
$router->post('/api/produto', [ProdutoController::class, 'criar'], [
AuthHybridMiddleware::class,
RequireWriteScope::class,
[RateLimitMiddleware::class, ['limit' => 10, 'window' => 60, 'key' => 'produto.criar']],
[CircuitBreakerMiddleware::class, ['service' => 'database', 'threshold' => 3, 'cooldown' => 20]],
]);Acessando o usuário autenticado no controller
public function criar(Request $request): Response
{
// Obtém o usuário logado (injetado pelo AuthHybridMiddleware)
$user = $request->attribute('auth_user');
$userId = $user->getUuid()->toString();
$username = $user->getUsername();
$nivel = $user->getNivelAcesso(); // 'admin_system' | 'usuario'
// Usa o userId para associar o recurso ao usuário
$item = $this->service->criar($request->body, $userId);
return Response::json(['produto' => $item], 201);
}Middleware próprio do módulo
Você pode criar middlewares específicos para o seu módulo implementando MiddlewareInterface:
use Src\Kernel\Contracts\MiddlewareInterface;
use Src\Kernel\Http\Request\Request;
use Src\Kernel\Http\Response\Response;
final class ApiKeyMiddleware implements MiddlewareInterface
{
public function handle(Request $request, callable $next): Response
{
$key = $request->header('X-Api-Key');
if ($key !== 'minha-chave-secreta') {
return Response::json(['error' => 'API Key inválida.'], 401);
}
return $next($request);
}
}Resumo de Middlewares por Categoria
| Categoria | Middlewares | Total |
|---|---|---|
| Autenticação | AuthHybridMiddleware, AuthCookieMiddleware, AuthPageMiddleware, OptionalAuthHybridMiddleware, AdminOnlyMiddleware, ApiTokenMiddleware, RouteProtectionMiddleware | 7 |
| Autorização (Scopes) | ApiKeyScopeMiddleware, RequireWriteScope, RequireDeleteScope | 3 |
| Proteção e Performance | RateLimitMiddleware, CircuitBreakerMiddleware, ResponseCacheMiddleware, BotBlockerMiddleware, HttpsEnforcerMiddleware, SecurityHeadersMiddleware | 6 |
Total: 16 middlewares disponíveis
Todos os middlewares estão no namespace Src\Kernel\Middlewares e podem ser usados em qualquer módulo.