Consumare stream SSE in React con EventSource

new EventSource(url) crea una connessione SSE all'URL specificato. Il browser apre immediatamente una richiesta HTTP GET con l'intestazione Accept: text/event-stream. Il server mantiene aperta questa connessione e trasmette gli eventi. EventSource è un'API nativa del browser: per l'utilizzo di base non è necessaria alcuna libreria.

EventSource ha tre stati di disponibilità: 0 (CONNECTING): la connessione è in fase di stabilimento o ristabilimento; 1 (OPEN): la connessione è stabilita e gli eventi vengono trasmessi; 2 (CLOSED): la connessione è chiusa e non verrà ristabilita. Verifichi eventSource.readyState per determinare lo stato corrente.

Il gestore eventSource.onmessage viene eseguito per gli eventi del server che non hanno un tipo esplicito, ovvero quando il server invia data: ... senza un campo event:. Il gestore riceve un oggetto evento in cui event.data contiene il payload sotto forma di stringa. In genere il server applica JSON.stringify ai dati, che vengono poi elaborati con JSON.parse al momento della ricezione.

Il server può inviare eventi con nome: event: userJoined data: {"userId": "123"} . Nel browser, ascolti l'evento con eventSource.addEventListener('userJoined', handler). Questo consente di multiplexare più tipi di evento su un'unica connessione SSE: ogni tipo di evento ha il proprio gestore, rendendo il codice chiaro e organizzato.

I dati SSE arrivano sotto forma di stringhe. Per i dati strutturati, il server invia JSON.stringify(payload) e il client li analizza con const data = JSON.parse(event.data). Racchiuda sempre JSON.parse in try/catch per gestire in modo appropriato il JSON non valido inviato dal server, registrando l'errore e ignorando l'evento malformato.

Crei e chiuda EventSource all'interno di un useEffect: crei la connessione quando il componente viene montato, colleghi i gestori degli eventi e restituisca una funzione di pulizia che chiama eventSource.close(). Senza questa pulizia, la connessione rimane attiva quando il componente viene smontato, l'utente cambia pagina o l'effetto viene eseguito di nuovo con dipendenze diverse.

Nel gestore eventSource.onmessage, aggiorni lo stato React per riflettere i nuovi dati: setMessages(prev => [...prev, JSON.parse(event.data)]). Utilizzi la forma funzionale di setState per evitare problemi dovuti a una closure obsoleta: il gestore degli eventi cattura il valore iniziale dello stato, mentre l'aggiornamento funzionale garantisce di lavorare sempre sullo stato più recente.

EventSource si riconnette automaticamente quando la connessione viene persa a causa di un errore di rete o del riavvio del server. Il browser attende un breve intervallo (in genere 3 secondi, configurabile dal server tramite retry: 3000 nello stream), quindi si riconnette. Non è necessario implementare la logica di riconnessione: è integrata nell'API EventSource.

EventSource tiene traccia dell'ultimo ID evento ricevuto (impostato dal server tramite id: 123 nello stream). Durante la riconnessione, il browser invia automaticamente questo ID nell'intestazione HTTP Last-Event-ID. Un server ben progettato utilizza questo ID per riprodurre gli eventi persi, assicurando che nessun evento venga perso durante una riconnessione.

EventSource non supporta direttamente le intestazioni personalizzate. Per l'autenticazione, utilizzi i cookie (new EventSource(url, { withCredentials: true }) invia i cookie) oppure includa il token di autenticazione come parametro di query nell'URL. Se sono necessarie intestazioni Authorization, utilizzi la Fetch API con ReadableStream invece di EventSource per elaborare manualmente la risposta SSE.

Quando EventSource rileva un errore, viene attivato il gestore onerror. Il valore di readyState sarà CONNECTING (se verrà effettuato un nuovo tentativo) oppure CLOSED (in caso contrario). In onerror, controlli readyState per distinguere tra un errore di rete temporaneo (per il quale verrà effettuato automaticamente un nuovo tentativo) e un errore permanente (il server ha restituito uno stato diverso da 200). In caso di errore permanente, chiuda la connessione e informi l'utente.

Che cosa accade quando una connessione EventSource viene interrotta a causa di un errore di rete?

new EventSource(url) crea una connessione SSE con gli stati readyStates: CONNECTING, OPEN, CLOSED. onmessage gestisce gli eventi generici; addEventListener gestisce i tipi di evento con nome. JSON.parse(event.data) estrae i dati strutturati. Crei e chiuda EventSource in useEffect. La riconnessione automatica è integrata: EventSource effettua nuovi tentativi dopo gli errori di rete utilizzando Last-Event-ID per riprodurre gli eventi persi. Per l'autenticazione, utilizzi i cookie (withCredentials) o i parametri di query nell'URL.