Al final de la lección anterior quedó un cabo suelto: POST /api/pedidos lee req.body, pero req.body no existe salvo que algo lo haya creado antes. Ese "algo" es un middleware, y el middleware no es una característica más de Express: es Express. Todo lo que hace el framework —enrutar, leer cuerpos, servir estáticos, manejar errores— está construido sobre el mismo mecanismo: una lista de funciones (req, res, next) que se recorren en orden y se van pasando el testigo. En esta lección desmontamos ese mecanismo hasta el fondo, escribimos los middleware propios de Escena Viva y comparamos los integrados de Express con el cuerpo.js y el estaticos.js que programaste a mano en el módulo 4.

1. Qué es un middleware
2. El recorrido de una petición
3. next(), next(error) y no llamar a next()
4. Tipos de middleware
5. El orden de registro es el orden de ejecución
6. Middleware con ruta de montaje
7. Los middleware propios de Escena Viva
8. Middleware integrados: json, urlencoded, static
9. Middleware asíncrono
10. Factorías de middleware

Un middleware es una función con esta firma:

La clave conceptual: una ruta también es un middleware. app.get('/salud', manejador) añade a la misma pila una entrada que, además del método y el patrón, tiene una función con la misma firma; cuando Express procesa una petición recorre una única lista donde conviven middleware y rutas. Esto ya lo hiciste en el módulo 4 sin llamarlo así: encadenabas leerCuerpo antes del manejador de POST /pedidos y comprobabas el tipo de contenido, todo antes de la lógica. Express convierte ese patrón en el mecanismo central del framework.

Dos caminos, uno normal y uno de error. Un middleware puede saltar del normal al de error en cualquier punto, y nunca se vuelve atrás: una vez dentro del manejador de errores, ya no se ejecutan los middleware normales que quedaban.

Estas opciones son toda la gramática del mecanismo.

Síntomas de la versión mala: curl se queda quieto, el navegador muestra la ruedecita eternamente, no aparece ningún error en la consola del servidor y el proceso está perfectamente sano. Es desconcertante precisamente porque no hay error: simplemente nadie ha terminado la respuesta. Para diagnosticarlo:

Así, una petición colgada deja rastro en stderr con su método y su ruta, y ya solo tienes que mirar qué middleware de esa ruta tiene un if sin salida.

Regla: después de siguiente(...), escribe return salvo que sea la última línea. Llamar a siguiente() dos veces provoca el aviso Cannot set headers after they are sent to the client, otro clásico difícil de rastrear.

Todos son la misma cosa: funciones en la pila. La única que se distingue por su forma es la de error, que tiene cuatro parámetros; Express cuenta los argumentos (fn.length) para decidir si es normal o de error, y por eso olvidar el cuarto parámetro hace que tu manejador nunca se ejecute (06-07).

No hay prioridades ni resolución inteligente: Express recorre la pila de arriba abajo, en el orden exacto en que registraste cada entrada.

En la versión mala el middleware está registrado, sí, pero después de la ruta: como la ruta responde, la cadena termina antes de llegar a él.

El orden canónico de crearAplicacion(), que iremos completando y cerraremos en 06-05: ajustes (disable('x-powered-by'), set('trust proxy')), seguridad y cabeceras (helmet, cors), observabilidad (idPeticion, registroPeticiones), análisis del cuerpo (express.json), estáticos (express.static), rutas de la API, middleware 404 y, siempre el último, el manejador de errores.

aplicacion.use(fn) se ejecuta siempre; aplicacion.use('/api', fn) solo si la ruta empieza por /api. El montaje con prefijo tiene un efecto que sorprende: dentro del middleware montado, req.url pierde el prefijo.

Dentro de un middleware montado en /api, para GET /api/eventos/evt-001?x=1:

Esa reescritura es lo que permite que src/rutas/eventos.js declare router.get('/:id') sin saber que estará montado en /api/eventos. Es la misma técnica que usa express.static: montado en /descargas, busca en el disco solo la parte relativa.

Consejo de registro: en registro-peticiones.js usa siempre req.originalUrl. Con req.url dentro de un montaje, tus logs mostrarán rutas incompletas y no podrás correlacionarlas con lo que ve el cliente.

Genera un identificador único por petición: la base de la trazabilidad, que aparecerá en los registros, en las respuestas de error (06-07) y en el registro estructurado del módulo 11.

Detalle importante: se valida el identificador recibido. Aceptar a ciegas una cabecera del cliente permitiría inyectar saltos de línea en los registros o valores enormes; la regex acota longitud y caracteres.

Mide la duración real de cada petición y la escribe por stderr, según la convención del curso.

Por qué res.on('finish') y no medir tras siguiente(): porque siguiente() devuelve el control en cuanto el siguiente middleware se suspende en una operación asíncrona, no cuando la respuesta se ha enviado. El evento finish de ServerResponse —el mismo objeto stream del módulo 3— es el único punto fiable.

Que la disponibilidad de la Sala Bóveda se sirva desde una caché de treinta segundos es exactamente cómo se vende una entrada que ya no existe.

En src/app.js quedan registrados en este orden: aplicacion.use(idPeticion) primero, porque todo lo demás lo usa; aplicacion.use(crearRegistroPeticiones()) segundo, para medir desde lo antes posible; y después express.json({ limit }).

Se configura con express.json({ limit: '100kb', type: 'application/json', strict: true }): limit equivale a tu LIMITE_BYTES, type acota qué Content-Type interpreta y strict acepta solo objetos y arrays en la raíz. Comparación honesta con lo que escribiste en el módulo 4:

Es tu mismo diseño con más casos límite cubiertos. Un cuerpo que supera el límite devuelve 413 y un JSON roto devuelve 400; esos errores llegan al manejador central como cualquier otro, y en 06-07 los traduciremos a nuestro formato mirando su propiedad type. Un detalle que sorprende: si el Content-Type no es JSON, express.json() no protesta, simplemente no hace nada y req.body queda como {}. Si quieres el 415 del módulo 4, hay que exigirlo explícitamente:

Interpreta formularios HTML clásicos con aplicacion.use(express.urlencoded({ extended: true, limit: '20kb' })). Con extended: true usa la biblioteca qs y admite estructuras anidadas (filtro[sala]=Sala+Boveda); con false usa querystring del núcleo y todo queda plano. Escena Viva es una API JSON y no lo necesita, pero conviene conocerlo por si añades un formulario de contacto.

Lo que hace mejor que tu versión: rangos HTTP, dotfiles, fallthrough (que permite que un fichero inexistente siga hacia tu 404 en lugar de responder ahí mismo) y una lista de tipos MIME que nunca querrás mantener a mano. Lo que tu versión hacía y esta no: la compresión, delegada a un middleware específico. Es una separación de responsabilidades mejor que la tuya.

Un middleware puede ser async y en Express 5 esto simplemente funciona: si obtenerCatalogo rechaza (fichero ilegible, JSON corrupto) en async function cargarCatalogo(peticion, respuesta, siguiente) { peticion.catalogo = await obtenerCatalogo(); siguiente(); }, Express captura la promesa rechazada y llama a siguiente(error) por ti.

En Express 4 ese código dejaba la petición colgada si la promesa rechazaba, y había que envolver cada manejador con const asyncHandler = (fn) => (p, r, s) => Promise.resolve(fn(p, r, s)).catch(s). Si te encuentras asyncHandler, express-async-handler o wrapAsync en un proyecto, ya sabes qué son: restos de Express 4 que en Express 5 sobran. Profundizaremos en 06-07.

La excepción que sigue siendo tuya: las devoluciones de llamada dentro de un manejador. Express solo puede capturar lo que rechaza la promesa que devuelves; no ve un throw dentro de un setTimeout ni dentro de un stream.on('data').

Un middleware fijo sirve para un caso. Una factoría —una función que devuelve un middleware— sirve para todos, y es el patrón que usan express.json({ limit }), helmet({ ... }) y cors({ ... }).

Tres ventajas concretas: es configurable sin duplicar código; hace el trabajo caro una sola vez (compilar regex, leer configuración, abrir recursos), de modo que el middleware devuelto solo hace lo mínimo por petición; y es probable, porque en el módulo 9 podrás llamar a exigirCabecera('X', {...}) y probar la función devuelta con objetos falsos, sin levantar un servidor.

Es exactamente el mismo patrón de crearRegistroPeticiones(opciones) que ya has escrito en el apartado 7. Cuando dudes entre exportar un middleware o una factoría, exporta la factoría: cuesta una línea más y te ahorra una refactorización.

• No llamar a next() en algún camino. La petición se cuelga sin errores. Usa el detector de colgadas en desarrollo y escribe return después de cada siguiente(...).
• Llamar a next() y además responder. Provoca Cannot set headers after they are sent; suele venir de un return olvidado.
• Registrar express.json() después de las rutas. req.body será undefined: el error número uno de los primeros POST.
• Registrar el manejador de errores en medio. Solo captura lo registrado antes que él; va siempre el último.
• Usar req.url en los registros dentro de un montaje. Verás rutas sin el prefijo: usa req.originalUrl.
• Middleware globales que solo hacen falta en una ruta. sinCache en toda la aplicación destroza la caché de los estáticos; monta cada uno en el ámbito mínimo.
• Trabajo caro dentro del middleware en lugar de en la factoría. Compilar una regex en cada petición es desperdicio puro.
• Confiar en cabeceras del cliente sin validar. X-Id-Peticion viene de fuera: acota longitud y caracteres.
• Consejo: un middleware debe hacer una cosa. Si el tuyo autentica, registra y comprime, son tres, y tres es el número de sitios donde buscarás el fallo.

Escribe src/middleware/tiempo-servicio.js con una factoría crearTiempoServicio() que añada la cabecera X-Tiempo-Servicio con los milisegundos que ha tardado la petición. Pista: no puedes fijar cabeceras en res.on('finish') porque ya se han enviado; hay que interceptar el momento justo antes envolviendo res.end.

Crea una aplicación con tres middleware, donde el segundo tiene un camino que no llama a siguiente(). Comprueba con curl que la petición se queda colgada, añade el detector del apartado 3 y demuestra que el problema aparece en stderr con método y ruta.

Sirve publico/ con express.static configurado con maxAge: '1h' y etag: true. Con curl -si comprueba: que la primera petición devuelve 200 con ETag y Cache-Control, que repitiéndola con -H 'If-None-Match: <etag>' devuelve 304 sin cuerpo, y que pedir /publico/../.env no sale del directorio. Contrasta el resultado con lo que hacía tu estaticos.js.

Solución 1

res.on('finish') no sirve porque para entonces las cabeceras ya viajaron por la red: setHeader lanzaría o sería ignorado. res.on('close') es aún peor, porque puede dispararse con la conexión ya cerrada. Este envoltorio de end es la técnica que usa morgan internamente.

Solución 2

curl -s --max-time 5 localhost:3000/entradas se cuelga y stderr muestra [colgada] GET /entradas; añadiendo -H 'X-Sala: Sala Boveda' responde {"sala":"Sala Boveda"}.

Solución 3

El tercer caso funciona porque express.static normaliza la ruta y rechaza lo que salga del directorio base, igual que tu resolverDentroDe; la diferencia es que ahora esa protección está en un paquete que millones de despliegues ejercitan a diario, no en veinte líneas tuyas.

El middleware es el mecanismo único sobre el que está construido todo Express: una pila de funciones (req, res, next) recorrida en el orden exacto de registro, donde cada una lee, modifica, cortocircuita o pasa el testigo, y donde next(error) abre un segundo camino del que no se vuelve. Has visto el diagrama completo del recorrido, el error más frustrante del framework —no llamar a next()— y cómo diagnosticarlo, la diferencia entre req.url, req.baseUrl y req.originalUrl al montar con prefijo, y por qué el orden de registro no admite excepciones.

Escena Viva tiene ya sus middleware propios: idPeticion para la trazabilidad, crearRegistroPeticiones midiendo con res.on('finish') y escribiendo por stderr, sinCache montado solo donde el aforo cambia, y exigirCabecera como ejemplo de factoría configurable. Y has comprobado que express.json() es tu cuerpo.js con más casos límite cubiertos, y que express.static() es tu estaticos.js más tipos-mime.js con soporte de rangos y dotfiles. Todos son tuyos hasta ahora.

En la siguiente lección, Middleware de Terceros Esenciales, montamos el kit mínimo que ninguna API debería salir a producción sin él: helmet y sus cabeceras de seguridad una a una, cors para que el publico/app.js de Escena Viva pueda llamar a la API desde otro origen, morgan para el registro HTTP, compression para el ancho de banda y express-rate-limit para que un script no agote el aforo del Auditorio Ribera en diez segundos. Cada uno pasado por el filtro de auditoría que aprendiste en el módulo 5, y todos ordenados en la versión definitiva de crearAplicacion().