Server-sent events: analise o fluxo e veja o que dispara

O que são server-sent events?

Server-sent events são a metade simples do tempo real na web: o servidor mantém uma resposta aberta e vai escrevendo linhas de texto nela, o navegador transforma cada bloco de linhas num evento e o seu código escuta. Sem handshake, sem enquadramento, sem biblioteca — uma resposta com o tipo de conteúdo text/event-stream e um corpo de linhas como data: alguma coisa. É o que quase toda API de streaming usa para empurrar tokens conforme são gerados, e é um formato simples o bastante para as pessoas escreverem servidores na mão.

E escrever na mão é justamente onde o problema começa, porque o formato é mais rígido do que parece. O algoritmo de análise é especificado por inteiro, até qual buffer guarda o quê e quando cada um é esvaziado, e várias das suas regras são o oposto do que a forma da sintaxe sugere. Um fluxo pode parecer perfeitamente razoável, não conter erro nenhum e não entregar nada.

Esta página roda esse algoritmo no que você colar. Ela mostra os eventos que saem, com o último ID como o analisador o teria naquele momento, e mostra cada linha que não contribuiu com nada junto com o motivo. Essa segunda metade costuma ser a que você veio buscar.

Como usar

1. Cole o corpo do fluxo. O corpo da resposta como ele trafegou, não os cabeçalhos. As linhas podem terminar em quebra de linha, em retorno de carro ou em ambos — os três valem, e entre os exemplos há um fluxo que usa cada um.
2. Leia os eventos que dispararam. Cada um com seu tipo, seus dados e o último ID no momento do despacho. Se a tabela sair vazia, o bloco abaixo explica qual linha foi a responsável.
3. Veja as linhas que não fizeram nada. Comentários, campos desconhecidos, um nome de campo com a caixa trocada, um id com um caractere nulo, um retry que não é número, e qualquer bloco que terminou sem despachar. Cada linha diz qual desses casos era.

A regra em que todo mundo tropeça

Um evento sem dados não é despachado. A especificação é explícita: se o buffer de dados estiver vazio quando chega uma linha em branco, o analisador esvazia os buffers e retorna sem produzir nada. Então um servidor que envia um campo event e uma linha em branco — um jeito perfeitamente natural de escrever um heartbeat — não dispara ouvinte nenhum, não registra erro algum e não mostra nada no painel de rede além de um fluxo que parece estar funcionando.

A solução é um campo data, mesmo vazio, ou um comentário. Um data vazio já basta, porque o analisador acrescenta uma quebra de linha ao buffer para cada linha data, então o buffer deixa de estar vazio mesmo com o valor vazio. Uma linha de comentário são dois-pontos seguidos de qualquer coisa, e é a forma convencional de manter uma conexão viva: não reinicia o temporizador de ninguém e não produz nada.

A outra metade da mesma regra é fácil de deixar passar no sentido inverso. O buffer do tipo de evento é esvaziado a cada despacho, então um evento sem campo event é um message. O do último ID não é: a especificação diz com todas as letras que ele não é reiniciado, de modo que mantém o valor até o servidor defini-lo de novo. Dois buffers, lado a lado no mesmo algoritmo, com vidas opostas. Um evento sem id herda o anterior, e é isso que volta no cabeçalho Last-Event-ID quando a conexão cai e o navegador reconecta.

Quatro regras menores que vale conhecer

Exatamente um espaço inicial é removido do valor. Um. A linha data: oi e a linha data:oi significam a mesma coisa, mas data: oi com dois espaços guarda um deles. É um jeito comum de enfiar um espaço a mais num JSON que depois não parseia sem motivo visível.

Nomes de campo são comparados literalmente, sem dobra de maiúsculas. Data não é data. Um nome com maiúscula não é erro e não é avisado em lugar nenhum — é simplesmente um campo desconhecido, e campos desconhecidos são ignorados. O mesmo vale para qualquer erro de digitação: existem exatamente quatro nomes de campo e todo o resto é descartado em silêncio.

Um id cujo valor contenha um caractere nulo é ignorado por inteiro. Não é cortado no nulo nem esvaziado: o buffer mantém o que tinha, então o próximo evento herda o id antigo. E um retry só é aplicado se o valor for feito apenas de dígitos, o que exclui um número negativo, um decimal e qualquer coisa com uma unidade grudada.

Por fim, um fluxo que para no meio de um evento perde esse evento. A especificação diz que ao chegar ao fim qualquer dado pendente deve ser descartado, então um bloco com uma linha data mas sem linha em branco depois nunca chega. Esta ferramenta distingue isso de um fluxo que para no meio de uma linha, onde os últimos caracteres nunca viraram uma linha e nem sequer foram olhados.

O que esta ferramenta não faz

Ela não se conecta a nada. Você cola um corpo; a página lê. Para capturar um fluxo real, o painel de rede do seu navegador mostra a resposta conforme ela chega, e um cliente HTTP de linha de comando a imprime enquanto vai caindo.

Ela lê um fluxo completo e não um ao vivo, o que faz um caso se comportar diferente de um cliente real. Um fluxo terminando num retorno de carro solto aqui não tem ambiguidade, porque não há nada depois; um analisador em streaming recebendo os mesmos bytes precisa segurar esse retorno de carro caso o próximo pedaço comece com uma quebra de linha, já que os dois juntos são um único fim de linha. Os dois comportamentos estão certos para o que cada um é.

Ela também não verifica se os seus dados são JSON válido, nem nada disso. O formato carrega texto e não se interessa pelo que o texto significa — o que vale lembrar, porque um campo data espalhado por várias linhas é rejuntado com quebras de linha entre os pedaços, e essa é uma forma legal de mandar um JSON formatado que muitos servidores escritos na mão produzem sem querer.

Por que é grátis?

Ler linhas de uma string é algo que o seu navegador faz na hora. Não há servidor no meio, então não há o que cobrar nem conta a criar.

Nada é enviado. O fluxo que você cola fica nesta aba.