arckode-framework 1.3.2 → 1.4.1

package/skills/middlewares/SKILL.md

@@ -1,295 +1,45 @@
-# SKILL: Arckode Middlewares — Globales y por Ruta
+# Middlewares — HTTP Pipeline
 
-> Activar cuando: agregar CORS, rate limit, timeout, logging, compresión, body limit, auth en rutas, o crear un middleware propio.
+## Stack
 
----
+Express 4.x (request → middleware chain → controller)
 
-## 1. IMPORT
+## Orden canónico
 
 ```ts
-import {
-  cors,
-  rateLimit,
-  requestLogger,
-  bodyLimit,
-  timeout,
-  compression,
-  requireAuth,
-} from 'arckode-framework/middlewares'
+app.use(cors)             // 1. CORS
+app.use(rateLimit)        // 2. Rate limit
+app.use(authenticate)     // 3. Auth/JWT
+app.use(bodyParser)       // 4. Body parser
+app.use(validateSchema)   // 5. Validación
+app.use(cors)             // ❌ tarde — rate limit sin CORS
 ```
 
----
+## Built-in
 
-## 2. MIDDLEWARES GLOBALES (composition-root.ts)
+| Middleware | Propósito | Notas |
+|------------|-----------|-------|
+| `corsMw` | CORS headers | Configurar origins por env |
+| `rateLimitMw` | Rate limiting | Ventana por IP |
+| `authMw` | JWT verify | Setea `req.user` |
+| `validateSchemaMw` | Schema validation | POST/PUT/PATCH |
+| `errorHandlerMw` | Catch + format | Último en cadena |
+| `requestLoggerMw` | Log request | Método, path, status, ms |
 
-Los globales se aplican a TODAS las rutas. Registrar en este orden:
+## Middleware personalizado
 
 ```ts
-import { cors, rateLimit, requestLogger, bodyLimit, timeout, compression } from 'arckode-framework/middlewares'
-
-// Orden obligatorio — cada uno depende del anterior
-router.use(timeout(10_000))              // 1. Cortar requests colgados antes que todo
-router.use(cors({ origins: ['https://mi-app.com'], credentials: true }))  // 2. CORS
-router.use(bodyLimit(2 * 1024 * 1024))  // 3. Rechazar bodies > 2MB antes de parsear
-router.use(requestLogger(logger))        // 4. Loguear método, path, status, duración
-router.use(compression())               // 5. Gzip para responses > 1KB (opcional)
-// rate limit: ver sección 3 — puede ser global o por ruta
-```
-
-**El orden importa:** si `timeout` va al final, no puede cortar las fases anteriores.
-
----
-
-## 3. CORS
-
-```ts
-// Permitir cualquier origen (solo para desarrollo/APIs públicas)
-router.use(cors())
-
-// Origenes específicos (producción)
-router.use(cors({
-  origins:     ['https://mi-app.com', 'https://admin.mi-app.com'],
-  methods:     ['GET', 'POST', 'PUT', 'DELETE'],
-  headers:     ['Content-Type', 'Authorization'],
-  credentials: true,   // necesario si el frontend envía cookies o Authorization
-}))
-```
-
-**Preflight:** el middleware maneja `OPTIONS` automáticamente y retorna 204.
-
-**Múltiples orígenes:** `Access-Control-Allow-Origin` solo acepta UN valor por request
-(no una lista separada por comas — los browsers lo rechazan). El middleware compara el
-header `Origin` del request contra la lista y emite solo el origen que hizo match.
-Si el origin no está en la lista, el header se omite (el browser bloquea el request).
-
-```
-Request:  Origin: https://mi-app.com
-Response: Access-Control-Allow-Origin: https://mi-app.com   ✅
-
-Request:  Origin: https://evil.com
-Response: (sin Access-Control-Allow-Origin)                  → blocked ✅
-```
-
----
-
-## 4. RATE LIMIT
-
-```ts
-// Global: 100 requests por minuto por IP
-const limiter = rateLimit({ windowMs: 60_000, max: 100 })
-router.use(limiter)
-
-// Por ruta específica (más restrictivo para endpoints sensibles)
-const loginLimiter = rateLimit({
-  windowMs: 15 * 60_000,  // 15 minutos
-  max: 5,                  // máximo 5 intentos
-  keyBy: (req) => req.headers['x-forwarded-for'] as string ?? 'anon',
-})
-router.post('/auth/login', [loginLimiter], req => controller.login(req))
-
-// Rate limit por usuario autenticado (después de que auth middleware corra)
-const userLimiter = rateLimit({
-  windowMs: 60_000,
-  max: 200,
-  keyBy: (req) => req.user?.id ?? req.headers['x-forwarded-for'] as string ?? 'anon',
-})
-
-// Resetear límite de un usuario (ej: tras verificación de captcha)
-limiter.reset('192.168.1.1')
-```
-
-**Importante:** El rate limiter usa memoria en proceso — no persiste entre reinicios ni entre múltiples instancias. Para producción distribuida → implementar `RateLimitAdapter` con Redis.
-
----
-
-## 5. REQUEST LOGGER
-
-```ts
-// Loguea: "POST /auth/login", "POST /auth/login 200 43ms"
-router.use(requestLogger(logger))
-
-// El logger hijo del módulo también puede usarse
-router.use(requestLogger(logger.child('http')))
-```
-
-Output en logs:
-```
-[app.http] POST /auth/login { requestId: 'abc-123' }
-[app.http] POST /auth/login 200 43ms { requestId: 'abc-123', status: 200, duration: 43 }
-```
-
----
-
-## 6. BODY LIMIT
-
-```ts
-// Default: 1MB
-router.use(bodyLimit())
-
-// Custom: 10MB (para endpoints de upload)
-router.use(bodyLimit(10 * 1024 * 1024))
-
-// Por ruta (más permisivo solo en upload)
-router.post('/archivos/upload', [bodyLimit(50 * 1024 * 1024)], req => controller.upload(req))
-```
-
-Retorna **413** si el body supera el límite.
-
----
-
-## 7. TIMEOUT
-
-```ts
-// Default: 5 segundos
-router.use(timeout())
-
-// Custom por aplicación
-router.use(timeout(10_000))  // 10s
-
-// Más permisivo para endpoints lentos (reportes, exports)
-router.get('/reportes/export', [timeout(60_000)], req => controller.export(req))
-```
-
-Lanza `InternalError` si el handler no responde en tiempo.
-
----
-
-## 8. COMPRESSION (gzip)
-
-```ts
-// Comprime responses JSON > 1KB si el cliente acepta gzip
-router.use(compression())
-
-// Custom threshold
-router.use(compression({ threshold: 512 }))  // comprimir si > 512 bytes
-```
-
-**No aplica a:** SSE streams, responses `null`, responses que ya tienen `Content-Encoding`.
-
----
-
-## 9. MIDDLEWARES POR RUTA
-
-```ts
-// Un middleware
-router.get('/admin', [auth.authenticate('admin')], req => controller.dashboard(req))
-
-// Múltiples middlewares (se ejecutan en orden)
-router.post(
-  '/auth/login',
-  [loginLimiter, bodyLimit(10_000)],
-  req => controller.login(req)
-)
-
-// Auth + role específico
-router.delete(
-  '/usuarios/:id',
-  [auth.authenticate('admin', 'superadmin')],
-  req => controller.eliminar(req)
-)
-```
-
----
-
-## 10. CREAR UN MIDDLEWARE PROPIO
-
-```ts
-import type { MiddlewareHandler } from 'arckode-framework'
-
-// Middleware que verifica un API key en el header
-export function apiKeyAuth(validKeys: string[]): MiddlewareHandler {
-  return async (req, next) => {
-    const key = req.headers['x-api-key'] as string
-    if (!key || !validKeys.includes(key)) {
-      return { status: 401, body: { error: 'API key inválida' } }
-    }
-    return next()  // siempre llamar next() para continuar la cadena
-  }
-}
-
-// Middleware de auditoría
-export function auditLog(repo: RepositoryAdapter<AuditoriaDTO>): MiddlewareHandler {
-  return async (req, next) => {
-    const res = await next()
-    if (req.method !== 'GET' && res.status < 400) {
-      await repo.create({
-        userId: req.user?.id ?? 'anon',
-        action: `${req.method} ${req.path}`,
-        status: res.status,
-      } as any)
-    }
-    return res
-  }
+// src/shared/http/middlewares/audit.middleware.ts
+export function auditMiddleware(req, res, next) {
+  console.log(`[AUDIT] ${req.method} ${req.path}`)
+  next()
 }
-
-// Registrar
-router.use(apiKeyAuth(['key-secreta-1', 'key-secreta-2']))
-```
-
-**Regla:** siempre llamar `await next()` y retornar su resultado — excepto cuando querés cortar la cadena (retornar error directo, como en el ejemplo de apiKeyAuth).
-
----
-
-## 11. CADENA DE EJECUCIÓN
-
-```
-Request entrante
-  → timeout          (global)
-  → cors             (global)
-  → bodyLimit        (global)
-  → requestLogger    (global)
-  → compression      (global)
-  → loginLimiter     (por ruta, si aplica)
-  → auth.authenticate (por ruta, si aplica)
-  → handler          (controller)
-← Response saliente
 ```
 
-Los middlewares globales corren ANTES que los de ruta. El error handler del router atrapa excepciones de toda la cadena.
-
----
-
-## 12. ANTI-PATRONES
-
-```ts
-// ❌ Middleware global que modifica req.body con lógica de negocio
-router.use(async (req, next) => {
-  req.body.precio = req.body.precio * 1.21  // impuesto — NO acá, va en el service
-  return next()
-})
-
-// ❌ Olvidar llamar next() — la request queda colgada
-router.use(async (req, next) => {
-  if (req.headers['x-tenant']) {
-    // ... pero nunca llama next()
-  }
-  // cuelga para requests sin x-tenant
-})
-
-// ❌ Lógica de autenticación duplicada en cada handler
-router.get('/datos', async (req) => {
-  const token = req.headers['authorization']
-  if (!token) return { status: 401, body: { error: '...' } }  // NO
-  // usar auth.authenticate() como middleware por ruta
-})
-
-// ✅ Cortar la cadena cuando es correcto (no llamar next)
-router.use(async (req, next) => {
-  if (req.method === 'OPTIONS') {
-    return { status: 204, body: null }  // cortar la cadena intencionalmente
-  }
-  return next()
-})
-```
-
----
-
-## 13. CHECKLIST MIDDLEWARES
+## Errores silenciosos
 
-- [ ] `timeout()` es el PRIMERO en los globales
-- [ ] `cors()` tiene `origins` específicos en producción (no `'*'`)
-- [ ] `bodyLimit()` registrado antes de endpoints que reciben JSON
-- [ ] Rate limiter en endpoints de login/registro (máximo 5/15min)
-- [ ] Middlewares de ruta van en array: `[auth.authenticate('admin')]`
-- [ ] Todo middleware custom llama `await next()` (excepto cuando corta intencionalmente)
-- [ ] No hay lógica de negocio en middlewares — solo cross-cutting concerns
+| Error | Señal | Fix |
+|-------|-------|-----|
+| Body parser después de auth | Auth lee raw body | Body parser ANTES |
+| Error handler ausente | Error crashea server | `app.use(errorHandlerMw)` al final |
+| Rate limit en todas las rutas | GET /health también limitado | Skip en health endpoints |