Consumindo fluxos SSE no React com EventSource

new EventSource(url) cria uma conexão SSE para a URL especificada. O navegador abre imediatamente uma solicitação HTTP GET com o cabeçalho Accept: text/event-stream. O servidor mantém essa conexão aberta e transmite eventos. EventSource é uma API nativa do navegador — nenhuma biblioteca é necessária para o uso básico.

EventSource tem três estados de prontidão: 0 (CONNECTING) — a conexão está sendo estabelecida ou restabelecida; 1 (OPEN) — a conexão foi estabelecida e os eventos estão fluindo; 2 (CLOSED) — a conexão está fechada e não será restabelecida. Verifique eventSource.readyState para determinar o estado atual.

O manipulador eventSource.onmessage é acionado para eventos do servidor que não têm um tipo de evento explícito (o servidor envia data: ... sem um campo event:). O manipulador recebe um objeto de evento no qual event.data é o conteúdo na forma de uma cadeia de caracteres. Normalmente, o servidor serializa os dados com JSON.stringify, para que você possa analisá-los com JSON.parse ao recebê-los.

O servidor pode enviar eventos nomeados: event: userJoined data: {"userId": "123"} . No navegador, escute-os com eventSource.addEventListener('userJoined', handler). Isso permite multiplexar vários tipos de evento em uma única conexão SSE — cada tipo de evento tem seu próprio manipulador, mantendo o código limpo e organizado.

Os dados do SSE chegam como cadeias de caracteres. Para dados estruturados, o servidor envia JSON.stringify(payload) e o cliente os analisa: const data = JSON.parse(event.data). Sempre envolva JSON.parse em try/catch para lidar adequadamente com JSON malformado enviado pelo servidor, registrando o erro e ignorando o evento malformado.

Crie e feche o EventSource dentro de um useEffect: crie a conexão quando o componente for montado, associe os manipuladores de eventos e retorne uma função de limpeza que chame eventSource.close(). Sem essa limpeza, a conexão vazará quando o componente for desmontado, quando o usuário navegar para outra página ou quando o efeito for executado novamente com dependências diferentes.

Dentro do manipulador eventSource.onmessage, atualize o estado do React para refletir os novos dados: setMessages(prev => [...prev, JSON.parse(event.data)]). Use a forma funcional de setState para evitar problemas de fechamento obsoleto — o manipulador de eventos captura o valor inicial do estado, enquanto a atualização funcional garante que você sempre adicione os dados ao estado mais recente.

EventSource reconecta automaticamente quando a conexão é perdida devido a um erro de rede ou à reinicialização do servidor. O navegador aguarda um breve intervalo (normalmente 3 segundos, configurável pelo servidor por meio de retry: 3000 no fluxo) e então se reconecta. Você não precisa implementar a lógica de reconexão — ela já faz parte da API EventSource.

EventSource acompanha o ID do último evento recebido (definido pelo servidor usando id: 123 no fluxo). Ao se reconectar, o navegador envia automaticamente esse ID no cabeçalho HTTP Last-Event-ID. Um servidor bem projetado usa isso para reenviar eventos perdidos, garantindo que nenhum evento seja perdido durante uma reconexão.

EventSource não oferece suporte direto a cabeçalhos personalizados. Para autenticação, use cookies (new EventSource(url, { withCredentials: true }) envia cookies) ou inclua o token de autenticação como parâmetro de consulta da URL. Se precisar de cabeçalhos de autorização, use a API Fetch com ReadableStream em vez de EventSource para processar manualmente a resposta SSE.

Quando EventSource encontra um erro, o manipulador de erros é acionado. O readyState será CONNECTING (se uma nova tentativa for feita) ou CLOSED (caso contrário). No tratamento de erros, verifique readyState para distinguir entre um erro temporário de rede (que será corrigido automaticamente por uma nova tentativa) e uma falha permanente (o servidor retornou um status diferente de 200). Para erros permanentes, feche a conexão e notifique o usuário.

O que acontece quando uma conexão EventSource é interrompida devido a um erro de rede?

A criação de uma conexão com EventSource estabelece uma conexão SSE com os estados de prontidão: CONNECTING, OPEN, CLOSED. O manipulador de mensagens trata eventos genéricos; o método addEventListener trata tipos de eventos nomeados. JSON.parse(event.data) extrai dados estruturados. Crie e faça a limpeza de EventSource em useEffect. A reconexão automática já está integrada — EventSource tenta novamente após erros de rede usando o ID do último evento para reenviar eventos perdidos. Autentique-se por meio de cookies (withCredentials) ou parâmetros de consulta da URL.