Torna al blog
Server-Sent Events: Streaming in Tempo Reale dal Server al Browser

Server-Sent Events: Streaming in Tempo Reale dal Server al Browser

8 min di lettura1 visualizzazioni
di Marco Salmaso
Server-Sent Events permettono al server di inviare dati al browser su una singola connessione HTTP, senza WebSocket e senza polling. Vediamo come funziona il protocollo text/event-stream, come gestire riconnessioni e id, e quando conviene davvero rispetto alle alternative.

Perché un canale unidirezionale

Quando si parla di "tempo reale" sul web la testa corre subito ai WebSocket. Eppure in moltissimi casi concreti il flusso di dati va in una sola direzione: dal server verso il browser. Notifiche, avanzamento di un job, prezzi aggiornati, log in diretta, stato di una coda. In questi scenari il browser non ha quasi nulla da dire al server: vuole solo ricevere.

Server-Sent Events (SSE) nasce esattamente per questo. È una tecnologia standard, supportata nativamente dai browser tramite l'oggetto EventSource, che tiene aperta una normale connessione HTTP e ci fa scorrere sopra un flusso di testo. Niente handshake di upgrade, niente protocollo binario separato, niente libreria lato client.

Il vantaggio pratico è grosso: se sai servire una risposta HTTP, sai già servire SSE. Il resto è disciplina nel formato del testo.

Il protocollo: text/event-stream nel dettaglio

SSE è, prima di tutto, un tipo di contenuto. Il server risponde con l'header:

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

Da quel momento la risposta non viene "chiusa": il server continua a scrivere sul socket. Ogni messaggio è composto da righe di campo, separate da una riga vuota. I campi principali sono:

  • data: il contenuto del messaggio. Se ripetuto su più righe, viene concatenato con un ritorno a capo.
  • event: il nome dell'evento, per distinguere tipi diversi di messaggio.
  • id: un identificatore del messaggio, usato per la ripresa dopo una disconnessione.
  • retry: il tempo in millisecondi che il browser deve attendere prima di riconnettersi.

Un messaggio completo ha questa forma:

id: 42
event: aggiornamento
retry: 5000
data: {"stato":"ok","avanzamento":80}

Nota la riga vuota finale: è quella che dice al client "il messaggio è finito". Dimenticarla è l'errore più comune, e il sintomo è un browser che sembra non ricevere nulla.

Le righe che iniziano con i due punti sono commenti e vengono ignorate dal client. Sono utili come heartbeat per tenere viva la connessione attraverso proxy che chiudono i socket inattivi.

Un server minimale

Vediamo un esempio in Node.js con Express. L'obiettivo è solo mostrare la meccanica: header corretti, scrittura sul socket e pulizia quando il client se ne va.

const express = require('express');
const app = express();

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

  let contatore = 0;
  const invia = (dati, id) => {
    if (id !== undefined) res.write(`id: ${id}\n`);
    res.write('event: aggiornamento\n');
    res.write(`data: ${JSON.stringify(dati)}\n\n`);
  };

  invia({ stato: 'connesso' }, contatore++);

  const timer = setInterval(() => {
    invia({ ora: new Date().toISOString() }, contatore++);
  }, 1000);

  // Fondamentale: liberare le risorse quando il client chiude
  req.on('close', () => {
    clearInterval(timer);
    res.end();
  });
});

app.listen(3000);

Il client è ancora più semplice, perché tutto è già nel browser:

const evt = new EventSource('/eventi');

evt.addEventListener('aggiornamento', (e) => {
  const dati = JSON.parse(e.data);
  console.log(dati);
});

evt.onerror = () => {
  // EventSource ritenta automaticamente, non serve fare nulla
};

La chiamata a req.on('close') non è un dettaglio estetico. In un'applicazione reale ogni client connesso consuma un descrittore di file, un buffer e, se usi timer o subscriber, anche memoria. Senza pulizia, il numero di connessioni fantasma cresce fino a far esplodere il processo.

Un equivalente in Python con Flask è altrettanto breve:

from flask import Flask, Response, stream_with_context
import json, time

app = Flask(__name__)

@app.route('/eventi')
def eventi():
    def genera():
        contatore = 0
        while True:
            payload = {'ora': time.time(), 'id': contatore}
            yield f'id: {contatore}\n'
            yield 'event: aggiornamento\n'
            yield f'data: {json.dumps(payload)}\n\n'
            contatore += 1
            time.sleep(1)
    return Response(stream_with_context(genera()),
                    mimetype='text/event-stream')

Riconnessione, id e ripresa del flusso

Questa è la parte che distingue SSE da un semplice "scrivo righe su una risposta". Il browser si riconnette da solo quando la connessione cade. Il campo retry controlla quanto aspettare, e il campo id abilita la ripresa.

Il meccanismo è semplice ma potente:

  1. Il server assegna a ogni messaggio un id crescente (o un timestamp, o un numero di sequenza).
  2. Se la connessione cade, il browser conserva l'ultimo id ricevuto.
  3. Alla riconnessione invia l'header Last-Event-ID con quel valore.
  4. Il server può ripartire da lì invece di ricominciare da capo.

Lato server la lettura è banale:

app.get('/eventi', (req, res) => {
  const ultimoId = Number(req.headers['last-event-id'] || 0);
  // riparti dall'evento successivo a ultimoId...
});

Attenzione: è il browser a chiudere e riaprire, non il server a "riprendere". Il tuo backend deve essere pronto a ricevere richieste ripetute e a ricostruire il punto giusto. Se il flusso non ha un ordine naturale (per esempio dati che arrivano da più sorgenti), spesso è più onesto non usare affatto id e ripartire dallo stato corrente.

Un'altra nota: EventSource supporta solo GET e non permette di impostare header personalizzati. Se ti serve autenticazione, o usi i cookie di sessione (che viaggiano da soli), oppure passi un token in query string, oppure rinunci a EventSource e usi fetch con uno stream, perdendo però la riconnessione automatica.

SSE, WebSocket e polling a confronto

CaratteristicaSSEWebSocketPolling
DirezioneServer → clientBidirezionaleClient → server
ProtocolloHTTPWS separatoHTTP
RiconnessioneAutomaticaManualeNon applicabile
FormatoTestoTesto o binarioQualsiasi
LatenzaBassaMolto bassaDipende dall'intervallo
Sforzo infrastrutturaleBassoMedio/altoBasso
Limite per dominio (HTTP/1.1)~6 connessioniNessunoNessuno

Il limite delle connessioni per dominio in HTTP/1.1 merita una riga in più. Con il vecchio protocollo ogni EventSource occupa uno dei sei slot disponibili, e aprirne diversi sullo stesso dominio può bloccare le altre richieste. Con HTTP/2 il problema sostanzialmente scompare, perché le stream multiple vengono multiplexate su una singola connessione TCP. Se il tuo progetto è servito in HTTP/1.1, tienilo a mente.

Casi d'uso in cui brilla

SSE è la scelta naturale quando il flusso è unidirezionale e vuoi rimanere dentro HTTP:

  • Notifiche push applicative: un nuovo ordine, un commento, un alert.
  • Avanzamento di lavori lunghi: import di un file, generazione di un report, indicizzazione.
  • Dashboard con valori che cambiano: metriche operative, stato di coda, log di un container.
  • Streaming di risposte testuali da un servizio AI, spesso già esposto in questo formato dai provider.
  • Feed di eventi dove conta la semplicità operativa più della latenza assoluta.

Dove invece conviene un WebSocket: giochi multiplayer, editor collaborativi, chat con molti utenti attivi, qualunque scenario in cui il client deve inviare dati con la stessa frequenza con cui li riceve.

Note operative per la produzione

Il codice di esempio funziona in locale e fallisce in produzione per una serie di motivi prevedibili. Vale la pena affrontarli prima di scoprirli.

Buffering dei proxy. Nginx, e diversi load balancer, tendono ad accumulare la risposta prima di inviarla. Con SSE questo significa messaggi in ritardo o mai recapitati. La contromisura tipica è disattivare il buffering sulla location interessata:

location /eventi {
    proxy_pass http://backend;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 1h;
    proxy_set_header Connection '';
    chunked_transfer_encoding on;
}

Heartbeat. Alcuni intermediari chiudono le connessioni che considerano inattive. Inviare un commento ogni 15-30 secondi (per esempio : ping\n\n) costa quasi nulla e tiene viva la linea.

Scalabilità orizzontale. Se hai più istanze del backend dietro un bilanciatore, gli eventi generati su una istanza non raggiungono automaticamente i client connessi a un'altra. Serve un pub/sub condiviso (Redis, NATS, un message broker) su cui ogni istanza pubblica e da cui ogni istanza consuma. È lo stesso problema dei WebSocket, non una peculiarità di SSE.

Timeout applicativi. Definisci un tempo massimo di vita di una connessione e forzane la chiusura in modo pulito, lasciando che il browser si riconnetta. Connessioni che vivono per giorni sono fragili e difficili da diagnosticare.

Osservabilità. Conta le connessioni attive, i messaggi inviati e le riconnessioni. Un numero di riconnessioni che sale a picchi è spesso il primo segnale che qualcosa, a monte, chiude i socket.

Conclusione

SSE è uno strumento sottovalutato perché sembra troppo semplice per essere serio. In realtà quella semplicità è esattamente il punto.

I punti chiave da portarsi via:

  • SSE è unidirezionale: server verso browser, su una normale connessione HTTP.
  • Il formato è testo puro, con campi data, event, id, retry e una riga vuota che chiude ogni messaggio.
  • La riconnessione è automatica, e il campo id permette di riprendere il flusso tramite Last-Event-ID.
  • EventSource è comodo ma limitato: solo GET e nessun header personalizzato.
  • In produzione servono proxy configurati, heartbeat, pub/sub per più istanze e una buona pulizia delle risorse lato server.
  • Se il traffico è bidirezionale ad alta frequenza, il WebSocket resta la scelta giusta; per tutto il resto, SSE spesso basta e avanza.

Foto di copertina di Emile Perron su Unsplash.