Add websocket subprotocol negotiation for STOMP

[joffrey-bion]

Problem / use case

The web socket protocol defines a way to negotiate subprotocols via the Sec-WebSocket-Protocol header. STOMP is one such subprotocol, and has several values registered in IANA's WebSocket Subprotocol Name Registry: v10.stomp, v11.stomp, v12.stomp.

While sending this header is technically not mandated by the STOMP spec, some servers might decide that they require the header in order to speak the STOMP protocol (which is a valid requirement to set), in which case Krossbow simply cannot communicate with them.

Also, some servers such as ActiveMQ don't actually respect the web socket spec entirely, and may return a protocol in Sec-WebSocket-Protocol even though none was sent by the client. This breaks some strict client implementations (such as Darwin's NSURLSessionWebSocketTask), which actively check that the negotiated protocol was sent by the client (see https://github.com/joffrey-bion/krossbow/issues/492).

Feature (solution)

It would be more correct for the Krossbow client to specify that it wants to speak STOMP v1.2 by sending the Sec-WebSocket-Protocol=v12.stomp header.

Going further, we could consider sending all 3 header values, and making sure we adjust Krossbow's behaviour based on the version selected by the server. Essentially, we could support older versions of STOMP through this negotiation.

Current alternatives

It is not always possible. In some client implementations like Ktor, we can define a default request with the header, but that's quite a hack. In most other client implementations, we simply can't do anything to make Krossbow send that header.

[joffrey-bion]

Summary of changes between protocol versions

Changes from 1.0 to 1.1

STOMP 1.1 is designed to be backwards compatible with STOMP 1.0 while introducing several new features not present in STOMP 1.0:

• protocol negotiation to allow for interoperability between clients and servers supporting successive versions of STOMP
• heartbeats to allow for reliable detection of disconnecting clients and servers
• NACK frames for negative acknowledgment of message receipt
• Support for virtual hosting (host header in CONNECT/STOMP frame)

Changes from 1.1 to 1.2

STOMP 1.2 is mostly backwards compatible with STOMP 1.1. There are only two incompatible changes:

• it is now possible to end frame lines with carriage return plus line feed instead of only line feed
• message acknowledgment has been simplified and now uses a dedicated header

Apart from these, STOMP 1.2 introduces no new features but focuses on clarifying some areas of the specification such as:

• repeated frame header entries
• use of the content-length and content-type headers
• required support of the STOMP frame by servers (used to be "servers SHOULD support")
• connection lingering
• scope and uniqueness of subscription and transaction identifiers
• meaning of the RECEIPT frame with regard to previous frames

What Krossbow should do with negotiated version

Things that don't need to change

• heartbeats are not supported in 1.0, but there is no harm in trying (maybe some servers support them anyway despite negotiating 1.0?). Also, heartbeats have their own negotation system, so the user already knows the specified values might not be the values that will actually be selected, and will depend on what the server supports.
• NACK frames are not supported in 1.0, but there is no harm in trying (maybe some servers support them anyway despite negotiating 1.0?)
• the STOMP frame is not mentioned in 1.0, but also not mentioned as an addition in 1.1. Also, the lack of CONNECT in the EBNF grammar of 1.0 doesn't rule out the possibility that STOMP frames could be supported by some 1.0 servers. Therefore, we shouldn't fail early if the user set connectWithStompCommand=true (the default is still false, which is the most compatible option).
• we will keep sending frames using \n as line ending as it's compatible with all versions, no need to use \r\n ourselves, no matter the platform. We also already accept \r\n in received frames (via readLineStrict()), and there is no need to eagerly fail on \r\n if the negotiated version is <= 1.1.

Things to change

• negotiation at STOMP level is a concept introduced after 1.0, so we should consider "1.0" the default value if no version header is present in the CONNECTED frame
• the host header of the CONNECT frame is not supported in 1.0, we should avoid sending it in this case
• we need to deal with the change of header format in ACK/NACK frames somehow