The MessageBroker WebSocket Subprotocol
draft-hapner-hybi-messagebroker-subprotocol-00
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Expired".
|
|
|---|---|---|---|
| Authors | Mark Hapner , Clebert Suconic | ||
| Last updated | 2011-10-01 | ||
| RFC stream | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-hapner-hybi-messagebroker-subprotocol-00
Network Working Group M. Hapner, Ed.
Internet-Draft Huawei
Intended status: Standards Track C. Suconic
Expires: April 2, 2012 redhat
September 30, 2011
The MessageBroker WebSocket Subprotocol
draft-hapner-hybi-messagebroker-subprotocol-00
Abstract
The WebSocket protocol [I-D.ietf-hybi-thewebsocketprotocol] 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.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Hapner & Suconic Expires April 2, 2012 [Page 1]
Internet-Draft MBWS and MBLWS September 2011
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 2, 2012.
Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Hapner & Suconic Expires April 2, 2012 [Page 2]
Internet-Draft MBWS and MBLWS September 2011
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. MBWS Functionality . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Connection Recovery . . . . . . . . . . . . . . . . . . . 4
2.1.1. MBWS Connections . . . . . . . . . . . . . . . . . . . 5
2.1.2. New MBWS Control Frames . . . . . . . . . . . . . . . 5
2.1.3. Connection Name and Connection Recovery . . . . . . . 6
2.1.4. Message Synchronization of a Recovered MBWS
Connection . . . . . . . . . . . . . . . . . . . . . . 6
2.1.4.1. Server-message-delivery-resync . . . . . . . . . . 7
2.1.4.2. Client-message-delivery-resync . . . . . . . . . . 7
2.1.5. Message Metadata . . . . . . . . . . . . . . . . . . . 8
2.1.5.1. Address . . . . . . . . . . . . . . . . . . . . . 8
2.1.5.1.1. Undeliverable Messages . . . . . . . . . . . . 9
2.1.5.2. Content-Type . . . . . . . . . . . . . . . . . . . 9
2.1.5.3. Property List . . . . . . . . . . . . . . . . . . 9
3. Additional Issues . . . . . . . . . . . . . . . . . . . . . . 9
3.1. Message Content and Message Fragmentation . . . . . . . . 9
3.2. REST Prior to Session Upgrade . . . . . . . . . . . . . . 10
3.3. Sec-WebSocket-Protocol Field . . . . . . . . . . . . . . . 10
3.4. Client Identity . . . . . . . . . . . . . . . . . . . . . 10
3.5. Message Security . . . . . . . . . . . . . . . . . . . . . 10
4. Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.1. MBWS Connection Recovery Scenario . . . . . . . . . . . . 10
4.2. MBLWS Session Scenario . . . . . . . . . . . . . . . . . . 11
5. Issues Outside the Scope of this Document . . . . . . . . . . 12
5.1. Messaging Scope . . . . . . . . . . . . . . . . . . . . . 12
5.2. Message Acknowledgement Interval . . . . . . . . . . . . . 12
5.3. Synchronous Messaging . . . . . . . . . . . . . . . . . . 12
5.4. End-to-End Reliability . . . . . . . . . . . . . . . . . . 12
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13
Hapner & Suconic Expires April 2, 2012 [Page 3]
Internet-Draft MBWS and MBLWS September 2011
1. Introduction
The WebSocket protocol [I-D.ietf-hybi-thewebsocketprotocol] 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.
2. MBWS Functionality
MBWS extends WebSocket with two capabilities:
o 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')
o 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.
2.1. Connection Recovery
When a WebSocket is normally closed, both client and server can
assume the messages they sent/delivered have been received by the
Hapner & Suconic Expires April 2, 2012 [Page 4]
Internet-Draft MBWS and MBLWS September 2011
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.
2.1.1. MBWS Connections
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.
2.1.2. New MBWS Control Frames
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[GPBE]
Hapner & Suconic Expires April 2, 2012 [Page 5]
Internet-Draft MBWS and MBLWS September 2011
Connection Name Extension Data
+-----------------+--------------+
| Length | Value |
+-----------------+--------------+
| base 128 varint | UTF-8 String |
+-----------------+--------------+
2.1.3. Connection Name and Connection Recovery
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.
2.1.4. Message Synchronization of a Recovered MBWS Connection
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
Hapner & Suconic Expires April 2, 2012 [Page 6]
Internet-Draft MBWS and MBLWS September 2011
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.
2.1.4.1. Server-message-delivery-resync
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.
2.1.4.2. Client-message-delivery-resync
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.
Hapner & Suconic Expires April 2, 2012 [Page 7]
Internet-Draft MBWS and MBLWS September 2011
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.
2.1.5. Message Metadata
Message Extension Data Fields
+---------------+----------------------+----------------------------+
| Field Name | Field Length in | Field Value |
| | Bytes | |
+---------------+----------------------+----------------------------+
| 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 | Attribute Value |
| | Bytes | |
+----------------+-------------------------+------------------------+
| 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.
2.1.5.1. Address
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
Hapner & Suconic Expires April 2, 2012 [Page 8]
Internet-Draft MBWS and MBLWS September 2011
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.
2.1.5.1.1. Undeliverable Messages
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.
2.1.5.2. Content-Type
Immediately following Address, a message may contain an optional
Content-Type. Its value is the MIME discrete type [RFC2045] that
describes the message's content.
2.1.5.3. Property List
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.
3. Additional Issues
3.1. Message Content and Message Fragmentation
MBWS provides the same message content and fragmentation support as
WebSocket.
Hapner & Suconic Expires April 2, 2012 [Page 9]
Internet-Draft MBWS and MBLWS September 2011
3.2. REST Prior to Session Upgrade
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.
3.3. Sec-WebSocket-Protocol Field
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.
3.4. Client Identity
WebSocket uses the HTTP origin model to identify clients. MBWS uses
the same client identity model.
3.5. Message Security
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.
4. Scenarios
4.1. MBWS Connection Recovery Scenario
1. Broker provides 'ws:' and/or 'wss:' URIs for accepting MBWS
connections.
2. Client establishes an HTTP session with Broker; identifies
itself using HTTP client origin; and, authenticates itself using
HTTP authentication.
3. If successful, Client may use session as a normal HTTP session
to invoke Broker's REST API.
Hapner & Suconic Expires April 2, 2012 [Page 10]
Internet-Draft MBWS and MBLWS September 2011
4. Client requests session upgrade to MBWS Subprotocol.
5. If upgrade successful, Client sends Connect frame with empty
connection name.
6. Broker responds with Connect frame containing a new connection
name.
7. Broker starts streaming available messages to client; and,
Client starts streaming messages to Broker.
8. Client and Broker periodically acknowledge receipt of each
other's messages using Acknowledge frames.
9. Client or Broker may initiate/respond to Ping/Pong during
session as defined by WebSocket.
10. Client or Broker may initiate session close as defined by
WebSocket.
11. If session abnormally terminates, client recovers connection by
executing (1) through (4) and then continues with (12)
12. Client sends Connect frame containing connection name it wishes
to recover
13. 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.
14. Client sends Acknowledge frame containing the sequence number of
the last message it has received.
15. 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.
16. Broker sends Acknowledge frame containing the sequence number of
the last message it has received.
17. 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)
4.2. MBLWS Session Scenario
1. Broker provides 'ws:' and/or 'wss:' URIs for accepting MBLWS
sessions.
2. Client establishes an HTTP session with Broker; identifies itself
using HTTP client origin; and, authenticates itself using HTTP
authentication.
3. If successful, Client may use session as a normal HTTP session to
invoke Broker's REST API.
4. Broker starts streaming available messages to client; and, Client
starts streaming messages to Broker.
5. Client or Broker may initiate/respond to Ping/Pong during session
as defined by WebSocket.
Hapner & Suconic Expires April 2, 2012 [Page 11]
Internet-Draft MBWS and MBLWS September 2011
6. Client or Broker may initiate session close as defined by
WebSocket.
5. Issues Outside the Scope of this Document
_This section is non-normative._
5.1. Messaging Scope
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.
5.2. Message Acknowledgement Interval
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.
5.3. Synchronous Messaging
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.
5.4. End-to-End Reliability
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.
6. References
[I-D.ietf-hybi-thewebsocketprotocol]
Fette, I. and A. Melnikov, "The WebSocket protocol",
draft-ietf-hybi-thewebsocketprotocol-16 (work in
Hapner & Suconic Expires April 2, 2012 [Page 12]
Internet-Draft MBWS and MBLWS September 2011
progress), September 2011.
[GPBE] "Google Protocol Buffers Encoding <http://code.google.com/
apis/protocolbuffers/docs/encoding.html>".
[RFC2045] Freed, N. and Borenstein, N., "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message
Bodies <http://code.google.com/apis/protocolbuffers/docs/
encoding.html>", November 1966.
Authors' Addresses
Mark Hapner (editor)
Huawei
Email: mhapner@huawei.com
Clebert Suconic
redhat
Email: csuconic@redhat.com
Hapner & Suconic Expires April 2, 2012 [Page 13]