Códigos de fechamento do WebSocket

O que é um código de fechamento de WebSocket

Quando uma conexão WebSocket termina de forma limpa, o lado que a fecha envia um quadro Close com um número de quatro dígitos dizendo por quê. 1000 significa que a conexão terminou normalmente, 1001 que a ponta está indo embora, 1011 que o servidor topou com uma condição inesperada. Sua biblioteca cliente mostra esse número, e ele costuma ser a única pista que você tem sobre o que deu errado.

Os números são geridos pela IANA num registro de vinte e quatro linhas: dezesseis códigos individuais nos 1000, algumas atribuições nos 3000 e vários trechos não atribuídos ou reservados para você mesmo definir. Esta página lista todos, com busca, e um número sem linha própria resolve para o trecho em que cai.

Ela também marca algo que o registro não consegue marcar. Três desses códigos não são mensagens de jeito nenhum, e um deles é quase certamente o motivo de você estar lendo isto.

Como usar

1. Digite o número que o cliente informou. A linha correspondente vem primeiro. Se o número não tiver linha própria — qualquer um nos 2000, ou um de uso privado nos 4000 — você recebe a faixa que o cobre, em vez de nada.
2. Leia o estado, não só o significado. Cada linha diz se o código pode mesmo ser enviado. É essa coluna que revela se o outro lado o escolheu ou se a sua própria biblioteca o inventou.
3. Busque por palavras também. Digitar parte de um significado funciona — abnormal, policy, restart — o que é mais rápido quando você lembra mais ou menos a frase mas não o número.

1006 não é uma mensagem do servidor

Esta é a parte que vale levar. Três códigos — 1005, 1006 e 1015 — carregam cada um na RFC 6455 uma frase dizendo que são valores reservados que não devem ser definidos como código de status num quadro de controle Close. Não são coisas que uma ponta possa enviar. Existem para que uma biblioteca tenha o que informar quando não há o que informar.

1006 significa que o seu cliente nunca recebeu quadro Close nenhum. Ninguém o escolheu e ninguém o enviou; a biblioteca preencheu isso para descrever uma conexão que simplesmente parou. Então a causa está abaixo do protocolo: uma conexão TCP derrubada, um proxy ou balanceador que estourou o tempo do socket, uma rede que sumiu, ou um handshake que nunca completou. Vasculhar os logs do servidor atrás de quem enviou 1006 é procurar alguém que não existe.

1005 é a mesma ideia um passo adiante: um quadro Close até chegou, mas não trazia código de status algum, o que é permitido. E 1015 informa que o TLS falhou antes de existir um WebSocket para falar. Os três são o seu próprio lado descrevendo a situação dele, no vocabulário que a especificação separou exatamente para isso.

Há um quarto estado fácil de jogar no mesmo balde, e não deveria. 1004 está reservado com significado indefinido, e não carrega nenhuma cláusula proibindo enviá-lo: é apenas um número a que ninguém deu função. Quatro estados, portanto, onde uma tabela copiada do registro mostra dois.

O que o registro diz e o que não diz

A IANA publica cinco colunas por linha: o código de status, seu significado, um contato, uma referência e um controlador de mudanças. Não há coluna alguma sobre se um código pode ser enviado, e não há como acrescentá-la sem mudar o esquema do registro. A distinção vive só na prosa da seção 7.4.1 da RFC 6455.

É por isso que tantas tabelas publicadas a perdem. 1000 e 1006 são linhas do mesmo formato, com o mesmo tipo de significado e a mesma referência à mesma RFC, então uma tabela gerada a partir do registro desenha as duas idênticas. Nada nos dados diz que um é uma mensagem e o outro uma ficção local.

Três códigos têm uma procedência que vale mostrar em vez de disfarçar. 1012, 1013 e 1014 — reinício de serviço, tente mais tarde, e um erro de gateway espelhando de propósito o 502 do HTTP — não foram definidos por documento normativo nenhum. Foram registrados por uma mensagem numa lista de e-mails, e a coluna de referência do registro aponta para essa mensagem em vez de para uma RFC. Funcionam, são amplamente implementados, e chegaram lá por um caminho diferente de tudo à volta.

A limitação honesta de uma página assim é que ela é um retrato de um registro que pode ganhar linhas. O que impede que envelheça em silêncio é que o gerador se recusa a construir se a RFC 6455 não contiver mais a frase exata que atribui a cada um dos três códigos que nunca são enviados — a classificação não pode se afastar da fonte sem quebrar a compilação.

Por que é grátis?

A lista inteira está na página, e a busca acontece no seu navegador. Não há nada para rodar num servidor nem motivo para pedir uma conta.

Nada do que você digita é enviado, guardado ou registrado. Você costuma chegar aqui com um código tirado de um log de produção, e o jeito confiável de manter isso privado é nunca recebê-lo.