Huawei

mhapner@huawei.com

redhat

csuconic@redhat.com

The WebSocket protocol provides a subprotocol extension facility. The MessageBroker WebSocket Subprotocol (MBWS) is a WebSocket Subprotocol used by messaging clients to send messages to, and receive messages from an internet message broker (herein called a message broker). A message broker is a messaging intermediary that queues messages sent by its clients for asynchronous delivery to its clients. Messages are addressed to message-broker-specific address names. Clients send messages to addresses and consume messages from addresses. Clients do not send messages directly to other clients. Message brokers provide a range of functionality that is outside the scope of MBWS. Typically an internet message broker provides a REST API for working with this functionality; such as configuring client credentials; setting client access controls; configuring address routing; etc. MBWS limits its scope to the definition of a WebSocket subprotocol that provides a full duplex, reliable message transport protocol between message brokers and their clients; and, between message brokers. Since reliable message transport is often independent of a broker's particular features, MBWS can be used as the message transport protocol for a wide range of message brokers. MBWS utilizes two elements of WebSocket extensibility - opcodes and extension data.

The WebSocket protocol provides a subprotocol extension facility. The MessageBroker WebSocket Subprotocol (MBWS) is a WebSocket Subprotocol used by messaging clients to send messages to, and receive messages from an internet message broker (herein called a message broker). A message broker is a messaging intermediary that queues messages sent by its clients for asynchronous delivery to its clients. Messages are addressed to message-broker-specific address names. Clients send messages to addresses and consume messages from addresses. Clients do not send messages directly to other clients. Message brokers provide a range of functionality that is outside the scope of MBWS. Typically an internet message broker provides a REST API for working with this functionality; such as configuring client credentials; setting client access controls; configuring address routing; etc. MBWS limits its scope to the definition of a WebSocket subprotocol that provides a full duplex, reliable message transport protocol between message brokers and their clients; and, between message brokers. Since reliable message transport is usually independent of a broker's particular features, MBWS can be used as the message transport protocol for a wide range of message brokers. MBWS utilizes two elements of WebSocket subprotocol extensibility - opcodes and extension data.

MBWS extends WebSocket with two capabilities: Connection Recovery - the ability to support a logical, reliable connection that spans a sequence of WebSocket sessions (herein, such a connection is called a 'connection') Message Metadata - the ability to annotate a WebSocket message with metadata to support the functionality of a message broker This document defines two subprotocols - MessageBroker WebSocket Subprotocol (MBWS) and MessageBrokerLight WebSocket Subprotocol (MBLWS). MBWS supports both Connection Recovery and Message Metadata. MBLWS supports only Message Metadata.

When a WebSocket is normally closed, both client and server can assume the messages they sent/delivered have been received by the other party. The reliability of the WebSocket's underlying TCP connection, combined with the WebSocket close protocol, insures that both parties have implicitly acknowledged the receipt of the all messages they have been sent. If a WebSocket session fails, the protocol does not define how the parties resolve what messages have been received and what messages have been lost. In many cases, this is not an issue; however, message brokers typically provide once-and-only-once QoS and WebSocket alone is not sufficient to support this. While message brokers could layer protocol over WebSocket to resolve this issue, this adds complexity and overhead. Instead, MBWS extends WebSocket with an efficient reliable messaging protocol that resolves this issue.

MBWS defines a connection that spans a sequence of one or more sessions. During the time period between the failure of one of its sessions and the creation of its next session, its parties must maintain the state required to recover the connection. Since messages may be lost when a session fails, this state must contain a window of recently sent messages. MBWS provides support for identifying connections; maintaining recently sent message windows; recovering a connection on a new session; and, resynchronizing a recovered connection's message transport.

New MBWS Control Frames Opcode Name Opcode Value Opcode Extension Data Connect %xB Optional Connection Name Acknowledge %xC base 128 varint sequence number varint is an integer encoding defined by Google Protocol Buffers Connection Name Extension Data Length Value base 128 varint UTF-8 String

When a client requests a new connection it sends a Connect frame with no extension data. The server must respond with a Connect frame containing the name of a new connection. This is the connection name that an MBWS client uses if the current session fails and the client recovers the connection via the connection recovery protocol. If a session is closed, as defined by the WebSocket close protocol, it also terminates the connection it carried. It is recommended but not required that connection name be a URN. When a client requests the recovery of a connection, it sends a Connect frame containing the name of the connection to be recovered. The message broker must then respond with a Connect frame containing a connection name. If this connection name matches the value sent by the client, the server has accepted the recovery request. If the name does not match, the server has rejected the recovery request and has created a new connection. Connection's are identified by a combination of client origin and connection name. Only the client origin that created the connection can recover the connection. A connection may be carried over a sequence of sessions during its lifetime.

MBWS requires clients and message brokers to use an implicit sequence numbering protocol for the messages transported by a connection. Each direction of transport defines a separate sequence. The first message sent by each party is sequence number 1, the next is 2, etc. Since both parties are guaranteed to see the messages in the order sent, no explicit exchange of sequence numbers is required. Both parties must acknowledge receipt of messages they receive. This is done by sending an Acknowledge frame with extension data set to the sequence number of the last message number reliably received. When a sending party receives an Acknowledge frame from its receiving party, the sending party can delete from its message recovery window all messages with sequence numbers less than or equal to the Acknowledge sequence number. A multi-fragment message is assigned one sequence number. Control frames are not assigned sequence numbers. If a session abnormally terminates and a message broker accepts a client's request to recover the connection, both client and message broker must verify that they can resume sending messages with the message sequence number required by each. This is a two phase process. First, the client provides the message broker with the information required to restart message delivery. This phase is called server-message-delivery-resync. Second, the message broker provides the client with information required to restart message delivery. This phase is called client-message-delivery-resync. If both server-message-delivery-resync and client-message-delivery-resync succeed, the connection has been recovered. If either fails, a new connection is created.

The client sends an Acknowledge frame containing the sequence number of the last message it has received. The message broker then validates it can resume sending with the next message in sequence. If so, it must reply with a Connect frame containing the connection name being recovered. If so, the client must reply with a Connect frame containing the connection name being recovered. Connection recovery then proceeds with the client-message-deliveryresync phase. If the client cannot restart with this message, it must reply with a Connect frame containing a new connection name. Message transport then begins on this new connection.

The message broker sends the client an Acknowledge frame containing the sequence number of the last message it has received. The client then validates it can resume sending with the next message in sequence. If so, the message broker must reply with a Connect frame containing the connection name being recovered. This completes a successful connection recovery and normal message transport resumes with the expected sequence numbered messages. If the message broker cannot restart with this message, it must reply with a Connect frame without a connection name. The message broker must then respond with a Connect frame containing a new connection name. Message transport then begins on this new connection.

Message Extension Data Fields Field Name Field Length in Bytes Field Value Address base 128 varint UTF-8 character string Content-Type base 128 varint UTF-8 character string Property List base 128 varint Sequence of Property Entries Property Entry Attribute Name Attribute Length in Bytes Attribute Value Name base 128 varint UTF-8 character string Value base 128 varint UTF-8 character string MBWS defines three optional message extension data Fields - Address, Content-Type and Property List - that hold per-message metadata. Message metadata should only be added to the initial frame of a message: no extension data is defined for message continuation frames. The order of message extension data must be Address, Content-Type and Property List. Each starts with a length in bytes of the value to follow. Empty fields are represented with a zero length. The extension data for a message with no metadata contains three length values set to zero.

For messages sent by a client to a broker, Address specifies the address name to which a message is addressed. Address will be used by the message broker to route the message. MBWS does not specify how this routing is to be done. For messages delivered by a message broker to a client, Address specifies a source address name. MBWS does not specify how this value is assigned. It is recommended but not required that address name be a URN. If a client sends several messages in series to the same Address, only the first message must provide an address value, subsequent messages may omit the value and the broker will assume the value is the last specified value. The previously sent address is not maintained across connection recovery. It must be reestablished with the first message sent. This same optimization can be used for messages sent by a broker to a client. The format and semantics of Address is message broker dependent and is outside the scope of MBWS. For instance, some brokers may treat Address as a strictly local name; other brokers may support a more global form of addressing.

An address name may not be known to a broker. MBWS does not define how such dead-letters are handled once they are received by a message broker. MBWS requires a message broker to acknowledge every message sent to it, whether or not it can deliver it.

Immediately following Address, a message may contain an optional Content-Type. Its value is the MIME discrete type that describes the message's content.

Immediately following Content-Type, a message may contain an optional Property List. This list contains zero or more Properties. Each property is has a Name attribute followed by a Value attribute. Property Names must not be empty. An empty Property Value is represented with a zero length.

MBWS provides the same message content and fragmentation support as WebSocket.

A client may use an HTTP session to first interact with a message broker's REST API and then upgrade the connection to MBWS or MBLWS for message transport.

Sec-WebSocket-Protocol Field Values Value MBWS.huawei.com MBLWS.huawei.com WebSocket defines the subprotocol negotiation process. This starts with a client including the Sec-WebSocket-Protocol Field with one or more subprotocol names in its WebSocket upgrade request. The table above specifies the values for the two subprotocols defined in this document.

WebSocket uses the HTTP origin model to identify clients. MBWS uses the same client identity model.

WebSocket supports TLS and MBWS recommends, but does not require, its use. In addition to providing better security the use of TLS and port 443 insures that MBWS connections avoid the overhead and latency of having to traverse web proxies.

Broker provides 'ws:' and/or 'wss:' URIs for accepting MBWS connections. Client establishes an HTTP session with Broker; identifies itself using HTTP client origin; and, authenticates itself using HTTP authentication. If successful, Client may use session as a normal HTTP session to invoke Broker's REST API. Client requests session upgrade to MBWS Subprotocol. If upgrade successful, Client sends Connect frame with empty connection name. Broker responds with Connect frame containing a new connection name. Broker starts streaming available messages to client; and, Client starts streaming messages to Broker. Client and Broker periodically acknowledge receipt of each other's messages using Acknowledge frames. Client or Broker may initiate/respond to Ping/Pong during session as defined by WebSocket. Client or Broker may initiate session close as defined by WebSocket. If session abnormally terminates, client recovers connection by executing (1) through (4) and then continues with (12) Client sends Connect frame containing connection name it wishes to recover Broker responds with Connect frame. If Connect frame contains a new connection name, broker has rejected recovery and created a new connection, processing continues with (7). If Connect frame contains recovery connection name, broker has accepted recovery. Client sends Acknowledge frame containing the sequence number of the last message it has received. Broker responds with Connect frame. If Connect frame contains a new connection name, broker has rejected recovery and created a new connection, processing continues with (7). If Connect frame contains recovery connection name, broker has accepted recovery. Broker sends Acknowledge frame containing the sequence number of the last message it has received. Client responds with Connect frame. If Connect frame contains an empty connection name, client has rejected recovery and processing continues with (6). If the connection name is the recovery connection name, processing continues at (7)

Broker provides 'ws:' and/or 'wss:' URIs for accepting MBLWS sessions. Client establishes an HTTP session with Broker; identifies itself using HTTP client origin; and, authenticates itself using HTTP authentication. If successful, Client may use session as a normal HTTP session to invoke Broker's REST API. Broker starts streaming available messages to client; and, Client starts streaming messages to Broker. Client or Broker may initiate/respond to Ping/Pong during session as defined by WebSocket. Client or Broker may initiate session close as defined by WebSocket.

_This section is non-normative._

Message brokers provide message-broker-specific functionality for routing, queueing, forwarding, filtering, transporting, etc. messages. This results in the broker delivering specific messages to specific clients. This document defines how a message broker uses the WebSocket subprotocols defined here to transport messages to/from a client. All other message broker functionality is outside the scope of this document.

The parties of an MBWS connection decide when to send Acknowledge frames. Typically these are sent after some number of messages have been received or some time interval has elapsed within which at least one message has been received. The choice of acknowledgement interval is outside the scope of this document.

Message brokers have a history of supporting synchronous messaging where clients make blocking calls to send and to receive messages. WebSocket and MBWS are natively asynchronous messaging protocols. MBWS is optimized for asynchronous, full duplex message transport. It has not been designed for synchronous messaging.

The responsibility for reliable message delivery over a MBWS connection is not the responsibility of the message broker alone - it is only achieved when both clients and brokers implement recovery of connections. The degree to which clients and message brokers are able to recover from failure is outside the scope of this document.