Eventos Enviados por el Servidor

Envía actualizaciones del servidor al cliente a través de una conexión HTTP persistente con Eventos Enviados por el Servidor (SSE).

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

import express from "express";
 
const app = express();
 
app.get("/events", (req, res) => {
  res.writeHead(200, {
    "Content-Type": "text/event-stream",
    "Cache-Control": "no-cache",
    Connection: "keep-alive",
  });
 
  const interval = setInterval(() => {
    res.write(`data: ${JSON.stringify({ time: Date.now() })}\n\n`);
  }, 1000);
 
  req.on("close", () => clearInterval(interval));
});

Cuándo usarlo: Feeds en vivo, notificaciones, actualizaciones de progreso y transmisión de registros donde solo el servidor envía datos.

Ejemplo de Funcionamiento

import express from "express";
 
const app = express();
const clients = new Set<import("node:http").ServerResponse>();
 
app.get("/events", (req, res) => {
  res.writeHead(200, {
    "Content-Type": "text/event-stream",
    "Cache-Control": "no-cache",
    Connection: "keep-alive",
    "X-Accel-Buffering": "no",  // deshabilitar el almacenamiento en búfer de nginx
  });
 
  res.write(": connected\n\n");  // la línea de comentario mantiene la conexión activa
  clients.add(res);
 
  req.on("close", () => {
    clients.delete(res);
  });
});
 
function broadcast(event: string, data: unknown) {
  const message = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
  for (const client of clients) {
    client.write(message);
  }
}
 
// Activar desde otra parte de la aplicación
app.post("/notify", express.json(), (req, res) => {
  broadcast("notification", req.body);
  res.json({ sent: clients.size });
});

Cliente (navegador):

const source = new EventSource("/events");
source.addEventListener("notification", (e) => {
  console.log(JSON.parse(e.data));
});
source.onerror = () => console.log("SSE reconectando...");

Lo que esto demuestra:

• Encabezados de respuesta SSE, incluyendo la deshabilitación del búfer de nginx
• Eventos con nombre con el campo event:
• Conjunto de clientes para distribución de difusión
• Limpieza al desconectarse el cliente
• EventSource del navegador con reconexión automática

Análisis Profundo

Cómo Funciona

• SSE es una respuesta HTTP de larga duración con Content-Type: text/event-stream
• Los mensajes son líneas de texto: data: ...\n\n (doble salto de línea termina el mensaje)
• Campos opcionales: event:, id:, retry:
• EventSource del navegador se reconecta automáticamente con Last-Event-ID

Formato de Mensaje SSE

event: price-update
id: 42
data: {"symbol": "AAPL", "price": 182.50}

Configuración de nginx

location /events {
    proxy_pass http://node_backend;
    proxy_buffering off;
    proxy_cache off;
    proxy_set_header Connection '';
    proxy_http_version 1.1;
    chunked_transfer_encoding off;
}

Errores comunes

• nginx almacenando en búfer SSE - los clientes ven eventos retrasados o agrupados. Solución: proxy_buffering off y X-Accel-Buffering: no.
• No limpiar al desconectarse - fuga de memoria por objetos de respuesta obsoletos. Solución: eliminar del conjunto de clientes al close.
• Escribir en una respuesta cerrada - lanza ERR_STREAM_DESTROYED. Solución: verificar res.writableEnded antes de escribir.
• No hay autenticación en el endpoint SSE - cualquiera puede suscribirse. Solución: validar la cookie/token en el GET inicial (EventSource admite cookies).
• Transmitir a todos los clientes sin límite - picos de CPU. Solución: limitar la tasa de difusión; usar salas/canales.
• Usar SSE para bidireccional - el cliente no puede enviar a través de SSE. Solución: el cliente envía a través de HTTP POST normal; el servidor envía a través de SSE.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos en Tiempo Real - SSE vs WebSocket
• Escalado en Tiempo Real - SSE multi-instancia
• Consideraciones de HTTP/2 y HTTP/3 - configuración de proxy
• Keep-Alive y Límites de Conexión - ajuste de conexión
• Mejores Prácticas en Tiempo Real - lista de verificación de la sección

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS Activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.