El servidor de la lección anterior tiene un defecto que da vergüenza enseñar: responde exactamente lo mismo a GET /eventos, a POST /pedidos y a DELETE /borra-todo, siempre con un 200 OK. No mira el método, no mira la ruta y no mira los parámetros. Es un servidor sordo.

En esta lección le damos oído y voz. Vamos a desmontar los dos objetos que recibe el manejador —req y res—, aprender a extraer bien la información de la petición, y construir el vocabulario con el que Escena Viva contestará durante el resto del curso: los códigos de estado, las cabeceras que importan y un módulo de ayudantes, src/servidor/respuestas.js, con la pieza que más lejos va a llegar: la tabla que traduce los error.codigo de nuestro dominio a estados HTTP. Esa tabla sobrevivirá a la llegada de Express en el Módulo 6.

1. req: anatomía de IncomingMessage
2. req.url no es una URL: parsearla con new URL
3. res: anatomía de ServerResponse
4. ERR_HTTP_HEADERS_SENT: el error más frecuente del módulo
5. Los códigos de estado que usará el curso
6. Las cabeceras que importan
7. src/servidor/respuestas.js
8. De error.codigo de dominio a estado HTTP
9. Redirecciones y el método HEAD

El primer argumento del manejador es una instancia de http.IncomingMessage. Y lo primero que hay que saber de ella es que es un stream de lectura: IncomingMessage extiende stream.Readable, con todo lo que eso implica desde la lección 03-04 (eventos data y end, for await...of, contrapresión). Node te entrega el objeto en cuanto ha terminado de leer las cabeceras; el cuerpo puede seguir viajando por la red mientras tu manejador ya se está ejecutando. Por eso el cuerpo hay que leerlo con paciencia, y por eso tiene su propia lección (04-05).

Las propiedades que se usan a diario:

Dos advertencias que valen dinero. La primera: las claves de req.headers están normalizadas a minúsculas, así que req.headers['Content-Type'] vale undefined y req.headers['content-type'] funciona. El fallo es sutil porque no da error, solo un undefined silencioso. La segunda: req.socket.remoteAddress detrás de un proxy inverso o un balanceador te devolverá la IP del proxy; la del cliente real llega en X-Forwarded-For, una cabecera que solo es fiable si controlas el proxy que la escribe. Volveremos a ello al limitar peticiones por IP en la lección 08-06.

Aquí es donde casi todo el mundo escribe su primer bug. req.url es la URL de petición del protocolo: una ruta con su cadena de consulta, sin origen. Y la tentación es tratarla como texto:

Ese código falla en cuatro escenarios reales:

1. No decodifica. Con GET /eventos?sala=Sala%20B%C3%B3veda obtienes la cadena literal Sala%20B%C3%B3veda, que no casa con 'Sala Boveda' ni con nada.
2. Se rompe con más de un parámetro. ?sala=X&orden=fecha deja sala valiendo X&orden=fecha.
3. Ignora los parámetros repetidos. ?categoria=jazz&categoria=humor es válido en HTTP y significa dos valores.
4. No contempla el fragmento ni las barras redundantes, ni normaliza nada.

La herramienta correcta es la clase URL, global desde Node 10 y estándar del navegador. Necesita una URL absoluta, así que se le pasa una base:

searchParams es un URLSearchParams: decodifica el porcentaje y el +, admite claves repetidas con getAll, y es iterable. Comprobación práctica con nuestro catálogo:

Un detalle importante sobre pathname: la clase URL no descodifica del todo el camino (por ejemplo %2F sigue siendo %2F, y con razón: una barra codificada no debe convertirse en un separador de segmentos). Si un identificador puede traer caracteres codificados, aplica decodeURIComponent a cada segmento por separado, nunca a la ruta completa. Es una precaución que retomaremos al extraer parámetros de ruta en la próxima lección.

Un patrón útil para leer parámetros numéricos con valor por defecto y validación:

El segundo argumento es un http.ServerResponse, y su naturaleza es simétrica a la de req: es un stream de escritura, ServerResponse extiende stream.Writable. Eso significa que res.write() devuelve false cuando el buffer se llena, que emite drain, y que puedes conectarle un pipeline —exactamente lo que haremos en la lección 04-04 para servir ficheros.

Una respuesta se construye en tres pasos, y el orden no es negociable:

Los métodos, con su matiz:

writeHead y setHeader se pueden combinar —writeHead gana en caso de conflicto—, pero mezclar estilos confunde. En Escena Viva usaremos setHeader para lo acumulativo y writeHead solo cuando la respuesta se cierra de inmediato.

HTTP envía las cabeceras antes del cuerpo, porque así viaja el mensaje. Y una vez que un byte ha salido por el socket, no hay forma de recuperarlo. Por eso este código explota:

En la práctica, el error casi nunca es tan obvio: aparece cuando una función responde y la ejecución continúa hasta otra que responde también.

Las tres reglas que lo evitan para siempre:

• Responder es terminar. Toda llamada a un ayudante de respuesta va precedida de return (return responderError(...)), o dentro de un if/else sin escapatoria.
• Un manejador responde exactamente una vez. Si necesitas decidir entre varias ramas, calcula primero y responde al final.
• En los catch, comprueba res.headersSent antes de intentar responder con un 500: si el fallo ocurrió a mitad de un stream, lo único que se puede hacer es res.end() o res.destroy(), porque el cliente ya recibió un 200 que no vas a poder desmentir.

El primer dígito da la familia: 2xx fue bien, 3xx mira en otro sitio, 4xx te has equivocado tú (el cliente), 5xx me he equivocado yo (el servidor). Esa frontera entre 4xx y 5xx es la más importante de todas: un 500 es un aviso para el desarrollador; un 4xx no.

Tres distinciones que se preguntan en cualquier entrevista y, más importante, que se equivocan en cualquier API mal hecha:

• 400 frente a 422. 400 es "no entiendo lo que me mandas" (JSON roto, tipo equivocado). 422 es "te entiendo perfectamente y tu petición no tiene sentido" (pides 8 entradas con un límite de 6). Muchas API usan 400 para ambos; nosotros distinguiremos, porque el mensaje de error resultante es mucho más útil.
• 401 frente a 403. 401 es "no sé quién eres" y suele acompañarse de WWW-Authenticate; 403 es "sé quién eres y no te dejo". Los nombres oficiales están cambiados respecto a lo que parecen y por eso se confunden.
• 404 frente a 409. Si la sesión no existe, 404. Si existe pero no quedan entradas, 409: el recurso está ahí, lo que falla es el estado.

Content-Type declara qué estás enviando. Para texto, con charset siempre:

Sin charset=utf-8, un navegador antiguo puede interpretar Bóveda como Bóveda. En JSON el estándar ya obliga a UTF-8, pero declararlo no cuesta nada y en text/html y text/plain es imprescindible.

Content-Length frente a Transfer-Encoding: chunked. Si conoces el tamaño exacto en bytes, decláralo: el cliente puede mostrar una barra de progreso y reutilizar mejor la conexión. Si no lo conoces —porque estás generando la respuesta sobre la marcha o enviando un stream—, Node usa chunked automáticamente, troceando el cuerpo con marcas de longitud.

Usar cuerpo.length aquí es un error clásico y muy dañino: 'Bóveda' tiene 6 caracteres y 7 bytes en UTF-8. Anunciar un byte de menos hace que el cliente corte la respuesta y falle el JSON.parse, con un mensaje incomprensible.

Cache-Control dice cuánto tiempo puede guardarse la respuesta. En una API de datos vivos, no-store; en un fichero estático, segundos o años (04-04). Location indica dónde está el recurso: obligatoria en un 201 (dónde quedó lo creado) y en un 3xx (adónde ir).

Escribir statusCode, setHeader y end en cada rama es repetitivo y, sobre todo, es donde se cuelan las incoherencias: una ruta que olvida el charset, otra que devuelve el error como texto plano. Centralicémoslo.

Tres decisiones deliberadas. Todos los errores tienen la misma forma ({ error: { codigo, mensaje, estado } }): un cliente puede programar contra codigo, que es estable, en vez de contra mensaje, que cambiará. Content-Length se calcula siempre con Buffer.byteLength, nunca con length. Y headersSent se comprueba en un único sitio, de modo que una doble respuesta ensucia el registro pero no tumba el proceso.

Llegamos a la pieza clave del módulo. Desde el Módulo 2, nuestro dominio lanza errores con un codigo propio: SESION_NO_ENCONTRADA, AFORO_INSUFICIENTE, CANTIDAD_INVALIDA. Ese vocabulario es de Escena Viva y no sabe nada de HTTP: es exactamente lo que queremos, porque GestorDeVentas debe poder usarse desde una CLI, desde una tarea programada o desde una API.

El puente entre los dos mundos es una tabla, y vive en la capa HTTP, no en el dominio:

Por qué esto es lo correcto y no un lujo de arquitecto:

• El dominio no se contamina. Evento.reservar sigue lanzando AFORO_INSUFICIENTE sin saber que existe el número 409, así que se puede seguir usando desde src/catalogo.js en la terminal.
• El fallo por defecto es 500 y es ruidoso. Un codigo desconocido significa que alguien inventó un error nuevo y olvidó registrarlo aquí: queremos enterarnos, no que se convierta en un 400 silencioso.
• Los 5xx no filtran nada. El mensaje interno va a stderr para nosotros; al cliente le llega un texto genérico. Una traza de pila en la respuesta es un regalo para quien busca tu versión de Node y tus rutas de disco.
• La tabla es una sola. Cuando lleguemos a Express en la lección 06-07, el manejador de errores cambiará de forma, pero seguirá consultando este mismo fichero.

Usarlo es una línea:

En la próxima lección ese try/catch dejará de repetirse en cada ruta: subirá una vez al despachador del enrutador.

Una redirección es un 3xx con la cabecera Location. Las cuatro que importan:

Cuidado con el 301: los navegadores lo guardan de forma agresiva y, si te equivocas de destino, los usuarios seguirán yendo al sitio malo aunque arregles el servidor, porque ni siquiera te lo van a preguntar. En la duda, 302.

El método HEAD pide una respuesta idéntica a la de GET pero sin cuerpo: sirve para consultar el tamaño o la fecha de un recurso antes de descargarlo. La buena noticia es que Node lo maneja casi solo: si el método es HEAD, descarta el cuerpo que escribas y envía solo las cabeceras. Aun así, conviene ser explícito para no generar trabajo inútil:

Nota que el Content-Length se sigue enviando aunque no haya cuerpo: es justo el dato que el cliente venía a buscar.

• Leer req.headers['Content-Type'] con mayúsculas. Devuelve undefined sin error. Las claves están siempre en minúsculas.
• Partir req.url con split('?') o split('/'). Rompe con parámetros codificados, repetidos y con más de uno. Usa new URL(req.url, base).
• Calcular Content-Length con cuerpo.length. Cuenta caracteres, no bytes; con una tilde o una ñ, la respuesta llega cortada. Usa Buffer.byteLength.
• Responder sin return. Es la causa número uno de ERR_HTTP_HEADERS_SENT.
• Enviar cuerpo en un 204 o un 304. Está prohibido por la norma y algunos proxis se atragantan.
• Devolver 200 con { "error": ... } dentro, o la traza de pila en un 500. El estado es parte de la respuesta, y la traza va al registro, nunca al cliente.
• Consejo: decide desde el principio un único formato de error para toda la API y no lo cambies. Tus clientes lo agradecerán más que cualquier funcionalidad.
• Consejo: en los catch que envuelven streams, comprueba res.headersSent; si ya salieron, lo único honesto es res.destroy().

Amplía el manejador para que GET /eventos acepte ?sala= y ?categoria= (esta última repetible) y devuelva el catálogo filtrado, con la forma { total, filtros, eventos }. Valida que sala no esté vacía y responde 400 con codigo: 'PARAMETRO_INVALIDO' si lo está. Compruébalo con curl -s 'http://localhost:3000/eventos?sala=Sala%20B%C3%B3veda'.

Añade a src/servidor/errores-http.js los códigos DATOS_CORRUPTOS (el JSON del catálogo está mal: es fallo nuestro) y FORMATO_NO_ACEPTADO (el cliente pide un formato que no servimos). Elige el estado de cada uno y justifícalo. Después escribe src/servidor/probar-errores.js, un script que recorra ESTADO_POR_CODIGO e imprima una tabla codigo | estado | familia, más el recuento por familia.

Haz que el manejador responda a HEAD /eventos con las mismas cabeceras que GET /eventos pero sin cuerpo, y comprueba con curl -I que Content-Length coincide exactamente con el número de bytes que devuelve curl -s ... | wc -c. Añade una sala con tilde al catálogo y verifica que sigue cuadrando.

Solución 1. Toda la información sale de searchParams, y la validación lanza con error.codigo para que la traduzca la tabla:

Con ?sala=Sala%20B%C3%B3veda devuelve 1 evento (evt-002, Noche de Monologos). Si hubieras usado split('='), la comparación sería contra 'Sala%20B%C3%B3veda' y el resultado, cero eventos: un filtro que "no encuentra nada" y parece un problema de datos.

Solución 2. DATOS_CORRUPTOS es un 500: el fichero del catálogo es responsabilidad nuestra y el cliente no puede hacer nada al respecto, así que además queremos que quede registrado. FORMATO_NO_ACEPTADO es un 406 Not Acceptable, el estado específico para "no puedo producir ninguno de los formatos que aceptas"; si prefieres no ampliar el vocabulario del curso, 400 es defendible, pero 406 es más preciso. El script se apoya en que la familia es el primer dígito:

Solución 3. La clave es calcular el cuerpo igual en ambos métodos y decidir solo al final si se envía:

curl -I (que envía HEAD) y curl -s ... | wc -c deben dar el mismo número. Al añadir una sala con tilde, Buffer.byteLength sube más que el número de caracteres —cada carácter acentuado ocupa dos bytes en UTF-8—, y ahí se ve por qué cuerpo.length habría mentido.

Ya sabes escuchar y contestar con propiedad. req es un IncomingMessage, que además de method, headers —siempre en minúsculas—, httpVersion y socket.remoteAddress, es un stream de lectura cuyo cuerpo todavía puede estar viajando. Su url no es una URL completa, sino ruta más consulta, y la única forma sensata de interpretarla es new URL(req.url, base) con searchParams: decodifica el porcentaje, admite claves repetidas con getAll y no se rompe con ?sala=Sala%20B%C3%B3veda.

res es un ServerResponse y un stream de escritura, con un orden inviolable: estado y cabeceras primero, cuerpo después, end() siempre. De ahí sale el error más frecuente del módulo, ERR_HTTP_HEADERS_SENT, que se cura con una regla simple: responder es terminar, y se responde una sola vez. Tienes el catálogo completo de estados que usará el curso, con las fronteras que más se equivocan —400 frente a 422, 401 frente a 403, 404 frente a 409— y las cabeceras esenciales, incluida la disciplina de calcular Content-Length con Buffer.byteLength y no con String.length.

Y Escena Viva se lleva dos módulos que la acompañarán hasta el final: src/servidor/respuestas.js, con responderJson, responderTexto, responderError, responderSinContenido y responderRedireccion, todos con un formato de error único; y src/servidor/errores-http.js, con la tabla que traduce error.codigo a estado HTTP —EVENTO_NO_ENCONTRADO a 404, AFORO_INSUFICIENTE a 409, CANTIDAD_INVALIDA a 400— y un 500 ruidoso por defecto para lo que no sepamos clasificar.

Nos falta lo evidente: decidir qué manejador atiende cada petición. En la próxima lección, Enrutamiento Manual, empezaremos con el if/else ingenuo, veremos exactamente dónde se rompe, y construiremos src/servidor/enrutador.js con una tabla de rutas, patrones tipo /eventos/:id compilados a expresiones regulares, extracción de parámetros, respuestas 405 con cabecera Allow y un try/catch central que usará la tabla que acabas de escribir.