SSE Protocol: A Complete Reference Guide

Introduction to Server-Sent Events (SSE)

Server-Sent Events (SSE) is a standard that allows a web server to push real-time updates to the client over a single, long-lived HTTP connection. Unlike WebSockets, which provide bidirectional communication, SSE is strictly unidirectional—data flows from the server to the client. This makes it an ideal choice for applications that require real-time updates but do not need the client to send continuous data back to the server over the same channel.

Why SSE Matters

Before SSE, developers relied on workarounds like long polling or forever iframes to simulate server push functionality. SSE standardizes this process, offering several distinct advantages:

Simplicity: It operates over standard HTTP, meaning you do not need special protocols, custom servers, or complex handshake mechanisms.
Built-in Reconnection: The browser's EventSource API automatically reconnects to the server if the connection drops, ensuring reliability without extra client-side logic.
Firewall Friendly: Because it uses standard HTTP ports and headers, SSE easily passes through corporate firewalls and proxies that might block WebSockets.
Lightweight Overhead: SSE has minimal protocol overhead compared to WebSockets, making it highly efficient for streaming text-based data like JSON payloads.

Understanding the SSE Protocol

At its core, the SSE protocol is incredibly simple. The client makes a standard HTTP GET request to the server. The server responds with a specific content type and keeps the connection open, sending messages as they become available.

HTTP Headers

To initiate an SSE stream, the server must respond with the following HTTP headers:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

The text/event-stream header tells the browser to treat the incoming data as an event stream rather than a standard HTTP response that should be downloaded and closed.

Message Format

Messages in SSE are plain text. Each message consists of one or more lines containing a field name, a colon, and a value. A message is terminated by a blank line (a double newline, \n\n). The protocol defines four standard fields:

data: The actual payload of the message. If the data spans multiple lines, each line must be prefixed with data:.
event: A custom event type. The client can listen for specific event types rather than generic messages.
id: An identifier for the message. If the connection drops, the browser will automatically send this ID back to the server in the Last-Event-ID header upon reconnection.
retry: The time in milliseconds the browser should wait before trying to reconnect after a connection loss.

Here is an example of a raw SSE message:

event: userUpdate
id: 12345
data: {"name": "Alice", "status": "online"}

Implementing an SSE Server

Implementing an SSE server is straightforward in almost any backend language. Below is a complete example using Node.js and its built-in http module. This server sends a timestamp to the client every second and demonstrates how to handle the Last-Event-ID header for reconnections.

const http = require('http');

const server = http.createServer((req, res) => {
  // Check if the client is requesting the SSE endpoint
  if (req.url === '/events') {
    // Set the required SSE headers
    res.writeHead(200, {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive'
    });

    // Check for Last-Event-ID to resume a dropped connection
    const lastEventId = req.headers['last-event-id'];
    let messageId = lastEventId ? parseInt(lastEventId, 10) : 0;

    // Send a heartbeat comment every 15 seconds to keep the connection alive
    const heartbeatInterval = setInterval(() => {
      res.write(': heartbeat\n\n');
    }, 15000);

    // Send a new event every 1 second
    const eventInterval = setInterval(() => {
      messageId++;
      const payload = {
        time: new Date().toISOString(),
        message: `Hello from server! Event ID: ${messageId}`
      };

      // Format the SSE message
      res.write(`id: ${messageId}\n`);
      res.write(`event: timeUpdate\n`);
      res.write(`data: ${JSON.stringify(payload)}\n\n`);
    }, 1000);

    // Clean up intervals when the client disconnects
    req.on('close', () => {
      clearInterval(heartbeatInterval);
      clearInterval(eventInterval);
      res.end();
    });

  } else {
    res.writeHead(404, { 'Content-Type': 'text/plain' });
    res.end('Not Found');
  }
});

server.listen(3000, () => {
  console.log('SSE server running on http://localhost:3000');
});

Consuming SSE on the Client

On the client side, the browser provides the EventSource API, which handles the connection, parsing, and automatic reconnection logic for you. You simply instantiate it with the URL of your SSE endpoint and attach event listeners.

JavaScript EventSource API

The following HTML and JavaScript code connects to the Node.js server defined above, listens for the custom timeUpdate event, and appends the data to the DOM.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>SSE Client Example</title>
</head>
<body>
  <h1>Server-Sent Events Demo</h1>
  <ul id="event-list"></ul>

  <script>
    const eventList = document.getElementById('event-list');

    // Connect to the SSE endpoint
    const eventSource = new EventSource('/events');

    // Listen for the custom 'timeUpdate' event
    eventSource.addEventListener('timeUpdate', (event) => {
      const data = JSON.parse(event.data);
      const listItem = document.createElement('li');
      listItem.textContent = `[${data.time}] ${data.message}`;
      eventList.appendChild(listItem);
    });

    // Handle generic errors (EventSource will auto-reconnect)
    eventSource.onerror = (error) => {
      console.error('EventSource failed:', error);
      // You can close the connection manually if desired:
      // eventSource.close();
    };

    // Optional: Listen for the default 'message' event
    eventSource.onmessage = (event) => {
      console.log('Generic message received:', event.data);
    };
  </script>
</body>
</html>

Best Practices for SSE

While SSE is simple to implement, following best practices ensures your application remains robust, scalable, and reliable in production environments.

Implement Heartbeats: Proxies and load balancers often terminate idle connections. Sending a periodic comment line (e.g., : ping\n\n) keeps the connection active without triggering client-side event listeners.
Utilize Event IDs: Always include an id field in your messages. When the browser reconnects, it sends the last received ID via the Last-Event-ID HTTP header. Your server should parse this header and replay any missed messages to ensure no data is lost during network blips.
Disable Proxy Buffering: If you are behind a reverse proxy like Nginx, ensure buffering is disabled for your SSE endpoints. Otherwise, the proxy will hold onto the data until a buffer is full, causing significant delays. In Nginx, this is done using proxy_buffering off; or by setting the X-Accel-Buffering: no header in your server response.
Manage Connection Limits: Browsers have a limit on the number of concurrent HTTP connections per domain (typically 6). If you open multiple SSE streams to the same domain, you may exhaust the connection pool. Consider using a single multiplexed SSE stream or HTTP/2, which does not have this strict limit.
Handle Client Disconnects: Always listen for the close event on the server side. If you do not clean up intervals, timeouts, and database listeners when the client disconnects, you will quickly leak memory and exhaust server resources.

Conclusion

Server-Sent Events provide a powerful, efficient, and standardized way to push real-time data from the server to the browser. By leveraging standard HTTP, SSE bypasses the complexities of WebSockets while offering built-in reconnection and a simple message format. Whether you are building a live news feed, a stock ticker, or a notification system, SSE is often the most pragmatic choice for unidirectional data streaming. By understanding the protocol details and adhering to best practices like heartbeats and event ID tracking, you can build highly responsive and resilient real-time features into your web applications.