Korzystanie ze strumieni SSE w React z EventSource

new EventSource(url) tworzy połączenie SSE ze wskazanym adresem URL. Przeglądarka natychmiast otwiera żądanie HTTP GET z nagłówkiem Accept: text/event-stream. Serwer utrzymuje to połączenie otwarte i przesyła strumieniowo zdarzenia. EventSource to natywne API przeglądarki — do podstawowego użycia nie jest wymagana żadna biblioteka.

EventSource ma trzy stany gotowości: 0 (CONNECTING) — połączenie jest ustanawiane lub ponownie ustanawiane, 1 (OPEN) — połączenie zostało ustanowione i zdarzenia są przesyłane, 2 (CLOSED) — połączenie jest zamknięte i nie zostanie ponownie nawiązane. Bieżący stan można sprawdzić za pomocą eventSource.readyState.

Procedura obsługi eventSource.onmessage jest wywoływana dla zdarzeń serwera, które nie mają jawnie określonego typu zdarzenia (serwer wysyła data: ... bez pola event:). Procedura obsługi otrzymuje obiekt zdarzenia, w którym event.data zawiera dane jako ciąg znaków. Serwer zazwyczaj serializuje dane za pomocą JSON.stringify, aby po stronie klienta można było użyć JSON.parse po ich odebraniu.

Serwer może wysyłać nazwane zdarzenia: event: userJoined\ndata: {"userId": "123"}\n\n. W przeglądarce należy nasłuchiwać ich za pomocą eventSource.addEventListener('userJoined', handler). Umożliwia to multipleksowanie wielu typów zdarzeń przez jedno połączenie SSE — każdy typ zdarzenia ma własną procedurę obsługi, dzięki czemu kod jest przejrzysty i uporządkowany.

Dane SSE docierają jako ciągi znaków. W przypadku danych o strukturze serwer wysyła JSON.stringify(payload), a klient je analizuje: const data = JSON.parse(event.data). Zawsze należy umieszczać JSON.parse w bloku try/catch, aby poprawnie obsłużyć nieprawidłowy JSON z serwera, rejestrując błąd i pomijając nieprawidłowe zdarzenie.

EventSource należy tworzyć i zamykać wewnątrz useEffect: utworzyć połączenie podczas montowania komponentu, podłączyć procedury obsługi zdarzeń i zwrócić funkcję czyszczącą, która wywołuje eventSource.close(). Bez czyszczenia połączenie wycieka, gdy komponent jest odmontowywany, użytkownik przechodzi na inną stronę lub efekt jest ponownie uruchamiany z innymi zależnościami.

Wewnątrz procedury obsługi eventSource.onmessage należy aktualizować stan React, aby odzwierciedlał nowe dane: setMessages(prev => [...prev, JSON.parse(event.data)]). Należy używać funkcyjnej postaci setState, aby uniknąć problemów z nieaktualnym domknięciem — procedura obsługi przechwytuje początkową wartość stanu, a aktualizacja funkcyjna gwarantuje pracę zawsze na najnowszym stanie.

EventSource automatycznie ponownie nawiązuje połączenie, gdy zostanie ono utracone z powodu błędu sieci lub ponownego uruchomienia serwera. Przeglądarka czeka krótki czas (zwykle 3 sekundy, konfigurowalny przez serwer za pomocą retry: 3000 w strumieniu), a następnie ponownie się łączy. Nie trzeba implementować logiki ponownego łączenia — jest ona wbudowana w API EventSource.

EventSource śledzi ostatni odebrany identyfikator zdarzenia (ustawiany przez serwer za pomocą id: 123 w strumieniu). Podczas ponownego łączenia przeglądarka automatycznie wysyła ten identyfikator w nagłówku HTTP Last-Event-ID. Dobrze zaprojektowany serwer używa go do odtworzenia pominiętych zdarzeń, dzięki czemu podczas ponownego łączenia żadne zdarzenia nie zostaną utracone.

EventSource nie obsługuje bezpośrednio niestandardowych nagłówków. Do uwierzytelniania należy użyć plików cookie (new EventSource(url, { withCredentials: true }) wysyła pliki cookie) albo dołączyć token uwierzytelniający jako parametr zapytania URL. Jeśli potrzebne są nagłówki Authorization, należy użyć Fetch API wraz z ReadableStream zamiast EventSource i ręcznie przetwarzać odpowiedź SSE.

Gdy EventSource napotka błąd, wywoływany jest handler onerror. Właściwość readyState będzie mieć wartość CONNECTING (jeśli połączenie zostanie ponowione) albo CLOSED (jeśli nie). W funkcji onerror należy sprawdzić readyState, aby odróżnić tymczasowy błąd sieci (połączenie zostanie automatycznie ponowione) od trwałej awarii (serwer zwrócił status inny niż 200). W przypadku trwałych błędów należy zamknąć połączenie i powiadomić użytkownika.

Co się dzieje, gdy połączenie EventSource zostanie przerwane z powodu błędu sieci?

new EventSource(url) tworzy połączenie SSE ze stanami readyStates: CONNECTING, OPEN, CLOSED. onmessage obsługuje zdarzenia ogólne, a addEventListener — nazwane typy zdarzeń. JSON.parse(event.data) wyodrębnia uporządkowane dane. EventSource należy tworzyć i sprzątać w useEffect. Automatyczne ponowne łączenie jest wbudowane — EventSource ponawia próbę po błędach sieci, używając Last-Event-ID do odtworzenia pominiętych zdarzeń. Uwierzytelnianie odbywa się za pomocą plików cookie (withCredentials) lub parametrów zapytania URL.