Codes de fermeture WebSocket

Qu'est-ce qu'un code de fermeture WebSocket ?

Lorsqu'une connexion WebSocket se termine proprement, la partie qui la ferme envoie une trame Close portant un nombre à quatre chiffres qui en donne la raison. 1000 signifie que la connexion s'est achevée normalement, 1001 que l'extrémité s'en va, 1011 que le serveur a rencontré une condition imprévue. Votre bibliothèque cliente vous montre ce nombre, et c'est généralement le seul indice dont vous disposez.

Ces nombres sont gérés par l'IANA dans un registre de vingt-quatre lignes : seize codes individuels dans les 1000, quelques attributions dans les 3000, et plusieurs plages non attribuées ou réservées à vos propres définitions. Cette page les liste tous, avec une recherche, et un nombre sans ligne propre renvoie à la plage qui le contient.

Elle signale aussi une chose que le registre ne peut pas signaler. Trois de ces codes ne sont pas du tout des messages, et l'un d'eux est très probablement la raison pour laquelle vous lisez ceci.

Comment l'utiliser

1. Saisissez le nombre rapporté par votre client. La ligne correspondante apparaît en premier. Si le nombre n'a pas de ligne propre — n'importe lequel dans les 2000, ou un code d'usage privé dans les 4000 — vous obtenez la plage qui le couvre plutôt que rien du tout.
2. Lisez l'état, pas seulement la signification. Chaque ligne indique si le code peut réellement être envoyé. C'est cette colonne qui vous dit si l'autre partie l'a choisi ou si votre propre bibliothèque l'a inventé.
3. Cherchez aussi par mots. Taper une partie d'une signification fonctionne — abnormal, policy, restart — ce qui va plus vite quand on se souvient à moitié de la formule mais pas du nombre.

1006 n'est pas un message du serveur

Voilà ce qu'il faut retenir. Trois codes — 1005, 1006 et 1015 — portent chacun dans la RFC 6455 une phrase indiquant qu'il s'agit de valeurs réservées qui ne doivent pas être placées comme code d'état dans une trame de contrôle Close. Ce ne sont pas des choses qu'une extrémité peut envoyer. Ils existent pour qu'une bibliothèque ait quelque chose à signaler quand il n'y a rien à signaler.

1006 signifie que votre client n'a jamais reçu la moindre trame Close. Personne ne l'a choisi et personne ne l'a envoyé ; la bibliothèque l'a inscrit pour décrire une connexion qui s'est simplement arrêtée. La cause se situe donc sous le protocole : une connexion TCP coupée, un proxy ou un répartiteur de charge qui a expiré la socket, un réseau disparu, ou une poignée de main jamais achevée. Fouiller les journaux du serveur à la recherche de qui a envoyé 1006, c'est chercher quelqu'un qui n'existe pas.

1005 est la même idée d'un cran : une trame Close est bien arrivée, mais elle ne portait aucun code d'état, ce qui est licite. Et 1015 rapporte que TLS a échoué avant qu'il n'y ait de WebSocket dont parler. Tous trois sont votre propre côté décrivant sa situation, dans le vocabulaire que la spécification a réservé exactement à cela.

Il existe un quatrième état qu'on met facilement dans le même sac, à tort. 1004 est réservé avec sa signification indéfinie, et ne porte aucune clause en interdisant l'envoi : c'est simplement un nombre auquel personne n'a donné de rôle. Quatre états, donc, là où une table recopiée du registre en montre deux.

Ce que le registre dit, et ce qu'il tait

L'IANA publie cinq colonnes par ligne : le code d'état, sa signification, un contact, une référence et un responsable des modifications. Aucune colonne n'indique si un code peut être envoyé, et il n'y a pas moyen d'en ajouter une sans modifier le schéma du registre. La distinction ne vit que dans la prose de la section 7.4.1 de la RFC 6455.

C'est pourquoi tant de tables publiées la perdent. 1000 et 1006 sont des lignes de même forme, avec le même type de signification et la même référence à la même RFC : une table engendrée depuis le registre les dessine à l'identique. Rien dans les données ne dit que l'un est un message et l'autre une fiction locale.

Trois codes ont une provenance qu'il vaut mieux montrer que masquer. 1012, 1013 et 1014 — redémarrage du service, réessayez plus tard, et une erreur de passerelle calquée à dessein sur le 502 de HTTP — n'ont été définis par aucun document normatif. Ils ont été enregistrés par un message adressé à une liste de diffusion, et la colonne référence du registre pointe vers ce message plutôt que vers une RFC. Ils fonctionnent, ils sont largement implémentés, et ils sont arrivés là par un chemin différent de tout ce qui les entoure.

La limite assumée d'une page comme celle-ci est qu'elle est un instantané d'un registre qui peut gagner des lignes. Ce qui l'empêche de vieillir en silence, c'est que le générateur refuse de construire si la RFC 6455 ne contient plus la phrase exacte qu'il attribue à chacun des trois codes jamais envoyés : la classification ne peut donc pas s'éloigner de sa source sans faire échouer la compilation.

Pourquoi est-ce gratuit ?

La liste entière est dans la page, et la recherche s'exécute dans votre navigateur. Il n'y a rien à faire tourner sur un serveur, ni aucune raison de vous demander un compte.

Rien de ce que vous saisissez n'est envoyé, conservé ni journalisé. Vous arrivez généralement ici avec un code tiré d'un journal de production, et la façon fiable de garder cela privé est de ne jamais le recevoir.