Cerrábamos el Módulo 3 con una frase: el proyecto sabe leer y escribir, pero no sabe hablar con nadie. Escena Viva tiene un catálogo en disco, informes por mes, rutas blindadas y tuberías que procesan ventas con memoria constante. Todo eso lo consume una única persona: quien ejecuta el comando en su terminal.

Hoy eso cambia. Al terminar esta lección, cualquier navegador de tu red podrá pedirle datos a Escena Viva.

Y verás enseguida que no estamos en territorio desconocido. Un servidor HTTP de Node es un EventEmitter que emite request —los mismos on y emit de la lección 02-05—, arrancarlo es una operación asíncrona que se confirma con un evento, y mantener el proceso vivo es exactamente el mecanismo de cuenta de referencias del bucle de eventos que estudiamos en 02-01. El módulo node:http no añade conceptos nuevos: conecta a la red los que ya tienes.

1. HTTP en cinco minutos: petición, respuesta y un intercambio real
2. http.createServer: el servidor es un EventEmitter
3. server.listen, el evento listening y el puerto
4. El primer servidor de Escena Viva
5. Tres formas de probarlo: navegador, curl y node -e
6. Por qué el proceso ya no termina solo
7. Errores de arranque: EADDRINUSE y EACCES
8. Apagado ordenado: server.close() y SIGINT

HTTP es un protocolo de petición y respuesta sobre texto. El cliente abre una conexión TCP, envía un bloque de texto con un formato muy concreto, y el servidor contesta con otro bloque. Nada más. Ni el cliente ni el servidor mantienen memoria de lo ocurrido entre una petición y otra: HTTP es sin estado, y todo lo que parece estado (sesiones, carritos, usuarios conectados) se construye encima, como veremos en el Módulo 8.

Una petición tiene cuatro partes y una respuesta tres:

Así se ve un intercambio completo, tal cual viaja por el cable. La línea en blanco es lo que separa las cabeceras del cuerpo, y es obligatoria:

Fíjate en dos detalles que te van a ahorrar horas de depuración más adelante:

• La ruta que llega al servidor no incluye el dominio. Host: localhost:3000 viaja en una cabecera aparte. Por eso, como veremos en la próxima lección, req.url vale /eventos y nunca http://localhost:3000/eventos.
• Las cabeceras son texto plano Nombre: valor, insensibles a mayúsculas, y pueden repetirse. Node te las entregará siempre normalizadas a minúsculas.

La buena noticia es que no vas a escribir ese texto a mano: el módulo node:http lo analiza al recibirlo y lo genera al responder. Tú trabajas con dos objetos, req y res.

El servidor mínimo cabe en cuatro líneas:

Guárdalo como hola.js, ejecútalo con node hola.js y abre http://localhost:3000. Ya tienes un servidor web.

Ahora lo importante: esa función que le pasas a createServer no es nada especial. http.Server hereda de net.Server, que hereda de EventEmitter. Pasar el manejador al constructor es puro azúcar sintáctico: Node hace un servidor.on('request', manejador) por ti. Estas dos versiones son exactamente equivalentes:

Saber esto no es trivia: significa que puedes registrar varios oyentes de request, y que todo lo que aprendiste sobre EventEmitter aplica aquí. Un caso real es separar el registro de peticiones de la lógica:

El diagnóstico va a stderr y los datos a stdout, como venimos haciendo desde el Módulo 1.

Estos son los eventos del servidor que importan en este módulo:

La diferencia entre connection y request merece un momento. No son lo uno por lo otro: HTTP/1.1 mantiene la conexión abierta por defecto (Connection: keep-alive), de modo que un navegador que carga una página con tres imágenes puede abrir una conexión y enviar cuatro peticiones por ella. Verlo en directo aclara el concepto:

Recarga la página un par de veces y verás cómo el contador de peticiones sube mucho más deprisa que el de conexiones. Ese detalle vuelve en el apartado 8, cuando intentemos apagar el servidor.

listen es lo que pone al servidor a escuchar. Su firma habitual es listen(puerto, host, callback), y es asíncrona: cuando la llamada retorna, el socket todavía no está listo.

Ese callback no es error-first: es simplemente un oyente de listening registrado con once. Por eso esta versión hace lo mismo:

servidor.address() devuelve { address, family, port } y solo tiene valor después de listening; antes devuelve null. Es la forma correcta de averiguar el puerto real cuando pides el puerto 0, que significa "el sistema operativo elige uno libre" —un truco imprescindible en las pruebas automáticas del Módulo 9, donde no puedes fijar un puerto sin arriesgarte a colisiones.

El segundo argumento, el host, decide quién puede conectarse: '127.0.0.1' acepta solo conexiones desde esta misma máquina, y '0.0.0.0' (el valor por defecto) las acepta por todas las interfaces de red, que es lo que hace falta en contenedores o para probar desde el móvil.

En desarrollo, 127.0.0.1 es la opción prudente: evita que tu servidor a medio hacer quede expuesto a la red de la cafetería. En Docker, en cambio, es un error clásico, porque el contenedor no recibiría el tráfico redirigido desde fuera (lo veremos en el Módulo 11).

Vamos con el código real. Crea src/servidor/servidor.js. La regla que nos autoimponemos desde el minuto uno es la que llevamos defendiendo todo el curso: nada de E/S síncrona dentro del manejador. El catálogo se lee con obtenerCatalogo(), que es asíncrono desde la lección 03-01.

Cuatro decisiones que se arrastran durante todo el módulo:

• crearServidor() se exporta sin arrancarlo. Separar la construcción del arranque es lo que permitirá levantar el servidor en un puerto aleatorio dentro de una prueba (Módulo 9) sin que el fichero abra un puerto por el mero hecho de ser importado. El require.main === module es lo que hace que siga siendo ejecutable con node src/servidor/servidor.js.
• El .catch no es opcional. http.createServer ignora por completo el valor que devuelva el manejador. Si el manejador es async y lanza, la promesa queda rechazada sin dueño: el cliente se queda colgado hasta que expire su tiempo límite y, desde Node 15, el proceso se cae por unhandledRejection. Un solo evento corrupto en el JSON tumbaría el servidor entero.
• res.headersSent evita el error ERR_HTTP_HEADERS_SENT: si el fallo ocurrió después de empezar a escribir la respuesta, ya no se pueden cambiar las cabeceras. Es el error más común del módulo y lo desmenuzamos en 04-02.
• El puerto sale del entorno. process.env.PUERTO permite cambiarlo sin tocar el código; en producción lo impone la plataforma. La configuración por entorno es el tema de la lección 11-01.

Arranca el servidor:

El navegador es la prueba más rápida (http://localhost:3000), pero también la que menos te enseña: no ves cabeceras ni código de estado, y añade peticiones fantasma como /favicon.ico que ensucian tus registros. Es útil, pero no basta.

curl -i http://localhost:3000/ muestra la respuesta completa, cabeceras incluidas. Es la herramienta que usaremos en todo el módulo:

Ahí están los números de la semilla: 3 eventos, 7 sesiones, aforo 3000, 1811 vendidas y 1189 libres. Nota que no hay Content-Length sino Transfer-Encoding: chunked; en 04-02 explicaremos exactamente por qué y cuándo conviene cada uno.

Banderas de curl que usaremos: -i incluye las cabeceras, -s silencia la barra de progreso, -X fuerza el método, -H añade una cabecera y -d envía un cuerpo.

Y node -e, para probar desde el propio Node con fetch (la API cliente que estudiaremos a fondo en 04-06):

Ejecuta el servidor y fíjate en algo que no había pasado nunca en este curso: el proceso no termina. Todos los scripts anteriores hacían su trabajo y devolvían el control a la terminal. Este se queda ahí, aparentemente sin hacer nada.

No es magia, es la cuenta de referencias del bucle de eventos de la lección 02-01. Node sale cuando no quedan operaciones pendientes que puedan producir trabajo futuro. Un socket a la escucha es exactamente eso: un manejador activo que puede despertar el bucle en cualquier momento. Mientras exista, la cuenta no llega a cero y el proceso sigue vivo.

Puedes comprobarlo desactivando esa referencia:

Ese programa imprime escuchando y termina inmediatamente, sin haber servido nada. El servidor estaba correctamente arrancado; simplemente había dejado de contar. unref() tiene usos legítimos (un servidor de métricas secundario que no debe impedir el cierre), pero para el servidor principal es un fallo garantizado. ref() deshace el efecto.

La consecuencia práctica es que, a partir de ahora, tu proceso tiene ciclo de vida: arranca, sirve durante días y tiene que poder apagarse bien. De eso trata el apartado 8.

Arranca el servidor en una terminal y, sin pararlo, arráncalo en otra:

Reconoce ese mensaje: Unhandled 'error' event es lo de la lección 02-05. Un EventEmitter que emite error sin oyentes lanza la excepción y tumba el proceso. http.Server no es una excepción a la regla.

Los dos fallos de arranque que verás en la práctica:

EACCES sorprende a quien intenta escuchar en el puerto 80 "porque es el de HTTP". En sistemas tipo Unix, los puertos menores de 1024 son privilegios reservados: solo root puede abrirlos. La respuesta correcta nunca es ejecutar Node como root, sino escuchar en un puerto alto y dejar que Nginx o el balanceador de la plataforma escuchen en el 80/443 (Módulo 11).

El arreglo es registrar un oyente de error antes de llamar a listen, y dar un mensaje que se entienda:

error.code (en inglés, propiedad del sistema) es lo que llega de libuv; no lo confundas con nuestro error.codigo de dominio, que traduciremos a estados HTTP en la próxima lección. Y process.exitCode = 1 en vez de process.exit(1): deja que el proceso termine de forma natural vaciando sus buffers de salida, como ya vimos en el Módulo 1.

Para localizar al culpable de un EADDRINUSE en Linux o macOS: lsof -i :3000 te dice qué proceso tiene el puerto, y kill <PID> lo libera.

Cuando pulsas Ctrl+C, tu terminal envía la señal SIGINT al proceso, y el comportamiento por defecto de Node es morir en el acto. Eso es aceptable en un script; en un servidor, significa cortar a media frase las peticiones en curso: un cliente se queda sin su respuesta, y una escritura de fichero puede quedar a medias.

El apagado ordenado consiste en dejar de aceptar conexiones nuevas y esperar a que terminen las vivas:

El punto delicado es el 2, y viene de lo que vimos en el apartado 2: close() no cierra las conexiones existentes, solo el socket a la escucha. Con keep-alive, un navegador que te ha pedido una página deja su conexión TCP abierta unos segundos por si pide algo más. Esas conexiones ociosas no están sirviendo nada, pero cuentan como vivas, así que close() se queda esperando y parece que tu servidor "no cierra". closeIdleConnections() (Node 18.2+) despacha exactamente ese caso: cierra las que no tienen una petición en curso y respeta las que sí.

Sobre las señales: SIGINT es tu Ctrl+C; SIGTERM es la que envían Docker, systemd y las plataformas de despliegue para pedir un cierre ordenado, con un plazo tras el cual mandan SIGKILL, que no se puede capturar. Por eso el temporizador de seguridad: más vale cerrar tú en 10 segundos que dejar que te maten a los 30 dejando ficheros a medias. En el Módulo 11 volveremos sobre esto con PM2 y Docker.

• Olvidar res.end(). El cliente se queda esperando indefinidamente. En el navegador se ve como una pestaña que gira sin fin, y en curl como una respuesta que nunca llega. Toda ruta de ejecución del manejador debe terminar en un end().
• Hacer E/S síncrona en el manejador. Un readFileSync en una ruta bloquea el bucle de eventos y, por tanto, a todos los clientes a la vez, no solo al que la pidió. Es aceptable en el arranque; jamás dentro de request.
• Manejador async sin .catch. Promesa rechazada sin dueño, cliente colgado y proceso caído. Envuelve siempre, como hace crearServidor().
• No escuchar el evento error del servidor. Un EADDRINUSE te tumba el proceso con una traza incomprensible en vez de un mensaje útil.
• Confundir connection con request. Con keep-alive, una conexión sirve muchas peticiones. Contar conexiones no es contar visitas.
• Consejo: exporta crearServidor() sin arrancarlo y arranca solo bajo require.main === module. Tu yo del Módulo 9, escribiendo pruebas de integración, te lo agradecerá.
• Consejo: durante el desarrollo, node --watch src/servidor/servidor.js reinicia el proceso al guardar. Sin dependencias y sin nodemon.

Amplía src/servidor/servidor.js para que lleve la cuenta de conexiones TCP y de peticiones HTTP servidas, y las exponga en el resumen JSON bajo las claves conexiones y peticiones. Después, con el servidor arrancado, ejecuta curl tres veces seguidas y luego recarga la página del navegador tres veces. Explica por qué los dos números no crecen igual.

Escribe src/servidor/arrancar.js que reciba el puerto por process.argv (con process.env.PUERTO como segunda opción y 3000 como tercera), arranque el servidor y trate los tres casos: arranque correcto (imprime la URL real obtenida de servidor.address()), EADDRINUSE (mensaje claro y exitCode 1) y EACCES. Pruébalo con los puertos 3000, 80 y con dos instancias a la vez.

Añade una ruta lenta al manejador: si req.url es /lento, espera 5 segundos con dormir (de src/utiles/dormir.js) antes de responder. Lanza curl http://localhost:3000/lento y, mientras espera, pulsa Ctrl+C en el servidor. Comprueba que la petición se completa y que solo después aparece cerrado limpiamente. Repite quitando closeIdleConnections() y explica qué cambia.

Solución 1. Los contadores son estado del servidor, así que viven en crearServidor:

Tres curl producen 3 conexiones y 3 peticiones: curl cierra su conexión al terminar cada invocación. Tres recargas del navegador producen normalmente 1 conexión y 6 peticiones o más: el navegador reutiliza la conexión gracias a keep-alive y, además, pide /favicon.ico por su cuenta. Esa asimetría es justo la razón de existir de closeIdleConnections().

Solución 2. La clave es que el oyente de error se registre antes de listen, porque el fallo se emite de forma asíncrona pero inmediata:

Con el puerto 80 sin privilegios obtienes EACCES; con dos instancias en el 3000, la segunda da EADDRINUSE. Sin el oyente, ambos casos serían un volcado de pila con Unhandled 'error' event.

Solución 3. Con closeIdleConnections() verás que la petición lenta se completa y que el proceso termina un instante después. Sin ella, si antes has usado el navegador, el proceso se queda colgado hasta que expira el keep-alive (5 segundos por defecto, server.keepAliveTimeout), o incluso hasta el plazo forzado de 10 segundos si el navegador renueva la conexión. Es el síntoma exacto de "mi servidor no cierra con Ctrl+C", y ahora sabes que la culpa no es de tu código, sino de una conexión ociosa que sigue contando.

Escena Viva ya está en la red. Y lo ha conseguido sin conceptos nuevos: http.createServer devuelve un EventEmitter que emite request —da igual si pasas el manejador al constructor o lo registras con on—, además de connection, listening, close y ese error que, si no escuchas, te tumba el proceso igual que en la lección 02-05. listen(puerto, host, callback) es asíncrono y su callback no es más que un once('listening'); server.address() te da el puerto real, imprescindible cuando pides el puerto 0.

Tienes el primer servidor real en src/servidor/servidor.js, con la disciplina que mantendremos todo el módulo: manejador asíncrono desde el minuto uno, .catch obligatorio para que una promesa rechazada no te cueste el proceso, puerto configurable con process.env.PUERTO y crearServidor() exportado sin arrancar. Sabes probarlo con el navegador, con curl -i —que enseña las cabeceras— y con node -e. Entiendes por qué el proceso ya no termina solo: el socket a la escucha mantiene la cuenta de referencias del bucle de eventos, y unref() lo demuestra apagándolo. Y sabes arrancarlo y apagarlo bien: EADDRINUSE y EACCES capturados con mensajes útiles, y un cierre ordenado con SIGINT/SIGTERM, server.close() y closeIdleConnections(), porque las conexiones persistentes no se cierran solas.

Lo que hace nuestro servidor, sin embargo, es bochornoso: responde lo mismo a /, a /eventos y a /cualquier-cosa, siempre con un 200, sin mirar el método ni los parámetros. Es hora de leer de verdad lo que nos llega y de construir con cuidado lo que devolvemos. En la próxima lección, Manejo de Solicitudes y Respuestas, desmontamos req —que es un stream de lectura— y res —que es un stream de escritura—, aprendemos a parsear la URL sin cortar cadenas a mano, repasamos los códigos de estado que usará el curso entero y construimos src/servidor/respuestas.js con la tabla que traduce nuestros error.codigo de dominio a estados HTTP.