Introduction to
Server-Sent Events

Long Polling

Server holds request open until data is available, then responds. Client immediately re-opens. Better latency, but connection churn and complex error handling.

// Long-poll loop
async function poll() {
  const res = await fetch('/api/updates?wait=30');
  const data = await res.json();
  render(data);
  poll(); // immediately re-connect
}
poll();

MIME Type & Headers

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no

The response body is an indefinite-length text stream. Each event is separated by a blank line (\n\n).

Constructor

// Basic usage
const es = new EventSource('/api/stream');

// With credentials (cookies / auth)
const es = new EventSource('/api/stream', {
  withCredentials: true
});

Server Side — Named Events

event: notification
data: {"type":"info","msg":"Deploy started"}

event: notification
data: {"type":"success","msg":"Deploy complete"}

event: heartbeat
data: ping

event: metric
data: {"cpu":23,"mem":55,"disk":71}

The event: field sets the event type. Without it, events are dispatched as "message".

How It Works

Express Implementation

import express from 'express';
const app = express();
const clients = new Set();

app.get('/events', (req, res) => {
  // 1. Set SSE headers
  res.writeHead(200, {
    'Content-Type':  'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection':    'keep-alive',
    'X-Accel-Buffering': 'no', // Nginx
  });

  // 2. Send initial retry interval
  res.write('retry: 5000\n\n');

  // 3. Register client
  clients.add(res);
  console.log(`Client connected (${clients.size})`);

  // 4. Handle disconnect
  req.on('close', () => {
    clients.delete(res);
    console.log(`Client left (${clients.size})`);
  });
});

// Broadcast helper
function broadcast(event, data, id) {
  const msg =
    (id    ? `id: ${id}\n`      : '') +
    (event ? `event: ${event}\n` : '') +
    `data: ${JSON.stringify(data)}\n\n`;

  for (const client of clients) {
    client.write(msg);
  }
}

app.listen(3000);

Fetch + ReadableStream

async function streamSSE(url, token) {
  const res = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
      'Accept': 'text/event-stream',
    },
    body: JSON.stringify({ channel: 'deploys' }),
  });

  const reader = res.body
    .pipeThrough(new TextDecoderStream())
    .getReader();

  let buffer = '';
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;

    buffer += value;
    const events = buffer.split('\n\n');
    buffer = events.pop(); // keep incomplete

    for (const raw of events) {
      const event = parseSSE(raw);
      if (event) handleEvent(event);
    }
  }
}

Server — Notification Stream

const userConnections = new Map(); // userId => Set<res>

app.get('/notifications/stream', auth, (req, res) => {
  res.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection': 'keep-alive',
  });

  const userId = req.user.id;
  if (!userConnections.has(userId))
    userConnections.set(userId, new Set());
  userConnections.get(userId).add(res);

  // Send unread count on connect
  const unread = getUnreadCount(userId);
  res.write(`event: unread-count\n`);
  res.write(`data: ${unread}\n\n`);

  req.on('close', () => {
    userConnections.get(userId)?.delete(res);
  });
});

// Called when a new notification is created
function notifyUser(userId, notification) {
  const conns = userConnections.get(userId);
  if (!conns) return;
  const payload =
    `id: ${notification.id}\n` +
    `event: notification\n` +
    `data: ${JSON.stringify(notification)}\n\n`;
  for (const res of conns) res.write(payload);
}

Server — Metric Stream

import os from 'node:os';

app.get('/metrics/stream', (req, res) => {
  res.writeHead(200, {
    'Content-Type':  'text/event-stream',
    'Cache-Control': 'no-cache',
  });

  let id = 0;
  const interval = setInterval(() => {
    const cpus = os.cpus();
    const load = os.loadavg();
    const mem  = process.memoryUsage();

    const payload = {
      ts:   Date.now(),
      cpu:  Math.round(load[0] * 100 / cpus.length),
      mem:  Math.round(mem.heapUsed / 1e6),
      rss:  Math.round(mem.rss / 1e6),
      conns: clients.size,
    };

    res.write(`id: ${++id}\n`);
    res.write(`event: metric\n`);
    res.write(`data: ${JSON.stringify(payload)}\n\n`);
  }, 1000);

  req.on('close', () => clearInterval(interval));
});

Server — Streaming LLM Proxy

app.post('/chat', async (req, res) => {
  res.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
  });

  const stream = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: req.body.messages,
    stream: true,
  });

  for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content;
    if (content) {
      res.write(`data: ${JSON.stringify({
        content
      })}\n\n`);
    }
  }

  res.write('data: [DONE]\n\n');
  res.end();
});

Workarounds for HTTP/1.1

• Use a subdomain for the SSE endpoint: stream.example.com
• Multiplex multiple event types over a single SSE connection
• Use SharedWorker to share one connection across tabs
• Upgrade to HTTP/2 (recommended)

Cookie-Based Auth (EventSource)

// Client
const es = new EventSource('/api/stream', {
  withCredentials: true  // sends cookies
});

// Server (Express + CORS)
app.use(cors({
  origin: 'https://app.example.com',
  credentials: true
}));

app.get('/api/stream', (req, res) => {
  // req.cookies available via cookie-parser
  if (!req.session.userId) {
    return res.status(401).end();
  }
  // ... stream events
});

EventSource Built-in Retry

const es = new EventSource('/stream');

es.onerror = (e) => {
  switch (es.readyState) {
    case EventSource.CONNECTING: // 0
      // Browser is auto-reconnecting
      console.log('Reconnecting...');
      break;
    case EventSource.CLOSED: // 2
      // Server sent HTTP error or closed
      console.log('Connection closed');
      break;
  }
};

The browser automatically reconnects when the connection drops. The server controls the delay via the retry: field.

Redis Pub/Sub Fan-Out

import Redis from 'ioredis';
const sub = new Redis();
const pub = new Redis();

// Each server instance subscribes
sub.subscribe('events');
sub.on('message', (channel, msg) => {
  // Broadcast to local SSE clients
  for (const client of clients) {
    client.write(`data: ${msg}\n\n`);
  }
});

// Any server can publish
function emit(event) {
  pub.publish('events', JSON.stringify(event));
}

Threat: Memory Leaks

• Forgetting to remove clients from Set on disconnect
• Growing event buffers without bounds
• Intervals/timers not cleared on close

// Always clean up
req.on('close', () => {
  clients.delete(res);
  clearInterval(timer);
  clearTimeout(timeout);
});