Server-Sent Events: Streaming in Tempo Reale dal Server al Browser
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:
- Il server assegna a ogni messaggio un
idcrescente (o un timestamp, o un numero di sequenza). - Se la connessione cade, il browser conserva l'ultimo
idricevuto. - Alla riconnessione invia l'header
Last-Event-IDcon quel valore. - 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
| Caratteristica | SSE | WebSocket | Polling |
|---|---|---|---|
| Direzione | Server → client | Bidirezionale | Client → server |
| Protocollo | HTTP | WS separato | HTTP |
| Riconnessione | Automatica | Manuale | Non applicabile |
| Formato | Testo | Testo o binario | Qualsiasi |
| Latenza | Bassa | Molto bassa | Dipende dall'intervallo |
| Sforzo infrastrutturale | Basso | Medio/alto | Basso |
| Limite per dominio (HTTP/1.1) | ~6 connessioni | Nessuno | Nessuno |
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,retrye una riga vuota che chiude ogni messaggio. - La riconnessione è automatica, e il campo
idpermette di riprendere il flusso tramiteLast-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.