WebSocket Close Code 1002

Question

I've written an application that uses web sockets to communicate between the server and client. I'd like to handle the case where the client is out of date (too old), and thus would misinterpret/not appropriately handle messages. My thinking is that if the client is too old, I close the connection and send the appropriate status code. I read the spec and it seems that 1002 may be the appropriate code:

  1002 indicates that an endpoint is terminating the connection due
  to a protocol error.

However, I don't actually know what that means (if it actually refers to the web socket protocol, and thus a lower level error). Is 1002 appropriate for this, or should I be making a custom (application) close code in the 4000-4999 region as defined here: https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent

Answer 1

The error code 1002 is for low-level WebSocket protocol violations. Like, the WebSocket message was a text message, but the payload contained invalid UTF8. You should not use that for the kind of situation. Errors 1002 are usually generated by the internals of a WebSocket implementation, not an application using WebSocket.

Now, in your situation, you have two options:

1. If the client can be identified as being "too old" already during the WebSocket opening handshake, you might fail the handshake using an HTTP Bad Request 400 already.

2. You might allow the handshake to complete, do some WebSocket message exchange determining the client version, and then close the connection (doing a proper WebSocket closing handshake) with an error code from the 4000-4999 range. Yes, that range would be appropriate. https://www.rfc-editor.org/rfc/rfc6455#section-7.4.2

The latter is more flexible and gives the client better feedback. In particular, JavaScript in browser will only get access to the close code (2), not any HTTP error in (1).

Another notable aspect: a conforming WebSocket implementation will simply not allow an application to trigger a close with 1002. The only close codes allowed for application use are 1000 (which is "normal" close) and 3000 - 3999 (app use, but registered at IETF) and 4000 - 4999 (app use, private unregistered).