HyBi Working Group J. Tamplin
Internet-Draft T. Yoshino
Intended status: Standards Track Google, Inc.
Expires: March 9, 2013 September 5, 2012
A Multiplexing Extension for WebSockets
draft-ietf-hybi-websocket-multiplexing-05
Abstract
The WebSocket Protocol [RFC6455] requires a new transport connection
for every WebSocket connection. This presents a scalability problem
when many clients connect to the same server, and is made worse by
having multiple clients running in different tabs of the same user
agent. This extension provides a way for separate logical WebSocket
connections to share an underlying transport connection.
Please send feedback to the hybi@ietf.org mailing list.
Status of this Memo
This Internet-Draft is submitted to IETF 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-
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 March 9, 2013.
Copyright Notice
Copyright (c) 2012 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
Tamplin & Yoshino Expires March 9, 2013 [Page 1]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
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.
Table of Contents
1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Physical Connection and Logical Channels . . . . . . . . . 3
2. Conformance Requirements . . . . . . . . . . . . . . . . . . . 4
3. Extension Negotiation . . . . . . . . . . . . . . . . . . . . 5
4. Interaction with other Extensions / Framing Mechanisms . . . . 6
4.1. Choosing the point to apply an extension . . . . . . . . . 6
5. Multiplexed Connections . . . . . . . . . . . . . . . . . . . 8
6. Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . 9
6.1. New Channel Slot . . . . . . . . . . . . . . . . . . . . . 9
6.2. Send Quota . . . . . . . . . . . . . . . . . . . . . . . . 9
7. Framing . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
8. Encapsulation . . . . . . . . . . . . . . . . . . . . . . . . 12
9. Multiplex Control Blocks . . . . . . . . . . . . . . . . . . . 14
9.1. AddChannelRequest . . . . . . . . . . . . . . . . . . . . 15
9.2. AddChannelResponse . . . . . . . . . . . . . . . . . . . . 17
9.3. FlowControl . . . . . . . . . . . . . . . . . . . . . . . 19
9.4. DropChannel . . . . . . . . . . . . . . . . . . . . . . . 20
9.4.1. Drop Reason Codes . . . . . . . . . . . . . . . . . . 21
9.5. NewChannelSlot . . . . . . . . . . . . . . . . . . . . . . 23
10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
11. Client Behavior . . . . . . . . . . . . . . . . . . . . . . . 26
12. Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . 27
13. Fairness . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
14. Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
15. Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
16. Close the Logical Channel . . . . . . . . . . . . . . . . . . 31
17. Fail the Logical Channel . . . . . . . . . . . . . . . . . . . 32
18. Fail the Physical Connection . . . . . . . . . . . . . . . . . 33
19. Operations and Events on Multiplexed Connection . . . . . . . 34
20. Security Considerations . . . . . . . . . . . . . . . . . . . 35
21. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36
22. Normative References . . . . . . . . . . . . . . . . . . . . . 37
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 38
Tamplin & Yoshino Expires March 9, 2013 [Page 2]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
1. Overview
This document describes a multiplexing extension for the WebSocket
Protocol. With this extension, one TCP connection can provide
multiple virtual WebSocket connections by encapsulating frames taged
with a channel ID. A client that supports this extension will
advertise support for it in the client's opening handshake using the
"Sec-WebSocket-Extensions" header. If the server supports this
extension and supports parameters compatible with the client's
request, it accepts the use of this extension by the
"Sec-WebSocket-Extensions" header in the server's opening handshake.
1.1. Physical Connection and Logical Channels
Under use of this extension, one transport connection is shared by
multiple application-level instances. The WebSocket connection which
lies directly on the TCP connection and negotiated this multiplexing
extension is called "physical connection". Virtual WebSocket
connections established for each application-level instance are
called "mutiplexed connections". Data channels virtually established
by ID tagging are called "logical channels". Logical channels with
non-zero ID exchange data for multiplexed connections. The logical
channel with ID of 0 exchanges multiplex control information.
Data for different logical channels are distinguished by the channel
ID placed at the head of the message that encapsulates the original
frame of a multiplex connection.
Tamplin & Yoshino Expires March 9, 2013 [Page 3]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
2. Conformance Requirements
All diagrams, examples, and notes in this specification are non-
normative, as are all sections explicitly marked non-normative.
Everything else in this specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC2119 [RFC2119].
Requirements phrased in the imperative as part of algorithms (such as
"strip any leading space characters" or "return false and abort these
steps") are to be interpreted with the meaning of the key word
("must", "should", "may", etc) used in introducing the algorithm.
Conformance requirements phrased as algorithms or specific steps MAY
be implemented in any manner, so long as the end result is
equivalent. (In particular, the algorithms defined in this
specification are intended to be easy to follow, and not intended to
be performant.)
Tamplin & Yoshino Expires March 9, 2013 [Page 4]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
3. Extension Negotiation
The registered extension token for this extension is "mux".
To request use of the WebSocket Multiplexing Extension, a client MUST
include an element with the "mux" extension token as its extension
identifier in the "Sec-WebSocket-Extensions" header in its opening
handshake. The element MAY contain an extension parameter named
"quota". The value of the "quota" extension parameter specifies the
server's send quota for the "Implicitly Opened Connection".
To accept use of the WebSocket Multiplexing Extension, a server MUST
include an element with the "mux" extension token in the
"Sec-WebSocket-Extensions" header in its opening handshake. The
element MUST NOT contain any extension parameter.
A server MAY choose to reject use of the WebSocket Multiplexing
Extension by not including the element for the extension in the
"Sec-WebSocket-Extensions" header in its opening handshake. If any
elements were listed after the element for the WebSocket Multiplexing
Extension in the "Sec-WebSocket-Extensions" from the client, they
MUST also be rejected.
Tamplin & Yoshino Expires March 9, 2013 [Page 5]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
4. Interaction with other Extensions / Framing Mechanisms
If any extension (e.g. compression) is placed before this extension
in the "Sec-WebSocket-Extensions" header of the physical connection,
that extension is applied to multiplexed connections unless otherwise
noted in the extension's spec.
If any extension is placed after this extension in the
"Sec-WebSocket-Extensions" header of the physical connection, that
extension is applied to frames after multiplexing on the sender side,
and before demultiplexing on the receiver side unless otherwise noted
in the extension's spec.
A client MAY request such an extension for both the physical
connection and multiplexed connections by placing extension entries
before and after this multiplexing extension. In this case, the
server SHOULD reject at least either of them if it's useless to apply
the same extension twice.
For example, if we have a compression extension called foo-compress,
the client sends
Sec-WebSocket-Extensions: foo-compress, mux, foo-compress
in the client's opening handshake of the physical connection to
request use of the compression for both physical and multiplexed
connections. Then, the server would send back
Sec-WebSocket-Extensions: mux, foo-compress
to apply compression after multiplexing, or
Sec-WebSocket-Extensions: foo-compress, mux
to apply compression to multiplexed connections.
4.1. Choosing the point to apply an extension
Where to apply a compression extension makes difference to resource
consumption and flexibility. Compression algorithms often use some
memory to keep its context. Some of compression extensions may keep
using the same context for all the messages on the same connection.
If such an extension is applied to the physical connection,
intermediaries that want to demultiplex or multiplex the connection
need to decompress (before demultiplexing) and recompress (before
multiplexing again) all the frames.
Tamplin & Yoshino Expires March 9, 2013 [Page 6]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
If such an extension is applied to each multiplexed connection, we
can control to which channel we apply the compression, so we can
avoid applying compression to channels transferring incompressible
data. Intermediaries that want to demultiplex can forward payload
leaving it untouched. However, compressing each multiplexed
connection is expensive in terms of memory consumption.
Tamplin & Yoshino Expires March 9, 2013 [Page 7]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
5. Multiplexed Connections
The multiplexing extension maintains separate logical channels, each
of which provides fully the logical equivalent of an independent
WebSocket connection, including separate handshake headers. If the
multiplexing extension is successfully negotiated, one multiplexed
connection is automatically established, and the headers on the
opening handshake of the physical connection are automatically taken
to mean ones for the multiplexed connection. It's called "Implicitly
Opened Connection". It's served by the logical channel with channel
ID of 1 which is also implicitly opened on completion of the opening
handshake. New channels are added by the client issuing the
AddChannelRequest multiplex control block (note that only the client
may initiate new WebSocket connections), including any handshake
headers which do not have the same value as the client's opening
handshake of the physical connection. The server's
AddChannelResponse likewise includes any handshake headers which are
different from the server's opening handshake of the physical
connection Channel 0 (control channel) is reserved for multiplex
control blocks and does not contain Payload Data from any multiplexed
connection. A client which attempts to add a channel to an existing
connection that is not accepted by the server SHOULD attempt to open
a new underlying connection and open a new WebSocket connection on
it.
Once the multiplexing extension is negotiated on a connection, all
frames of multiplexed connection MUST be prefixed with a channel ID
number and encapsulated into binary messages. The channel ID is
assigned by the client on issuing an AddChannelRequest.
A receiver MAY process frames for different non-control logical
channels in parallel. A receiver MUST process frames for the control
channel exclusively.
A receiver MUST _Fail the Physical Connection_ if any of these rules
are violated by the sender.
Tamplin & Yoshino Expires March 9, 2013 [Page 8]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
6. Flow Control
6.1. New Channel Slot
A client has a pool of slots called "new channel slots". It's
initialized to be empty on establishment of the physical connection.
A NewChannelSlot multiplex control block sent by the server adds
slots to the pool.
Each slot has a non-negative integer value called "initial send
quota". Its function is explained in the later subsection.
When sending an AddChannelRequest, the client MUST pick the oldest
new channel slot from the pool and remove it from the pool. If there
are no slots in the pool, the client MUST NOT issue an
AddChannelRequest. An endpoint MUST _Fail the Logical Channel_ with
drop reason code of 2007 when it's clear that the other peer violates
this.
A server can regulate the rate of AddChannelRequests by not
replenishing the pool.
6.2. Send Quota
For each logical channel with non-zero ID, server and client are
respectively given a non-negative integer value called "send quota".
For the logical channel created for the "Implicitly Opened
Connection", the client's "send quota" is initialized to 0 on
establishment of the physical connection. The server's "send quota"
for the channel is initialized on sending its opening handshake for
the physical connection. The "quota" extension parameter attached to
the extension token for this multiplexing extension in the client's
opening handshake for the physical connection specifies the initial
value. If the "quota" extension parameter is not specified, the
initial value is set to 0. The extension parameter has the initial
value on its parameter value side as a non-negative integer in
decimal.
For a logical channel added by issuing an AddChannelRequest, a client
gets "send quota" equal to the "initial send quota" value on the "new
channel slot" picked for the AddChannelRequest on sending it.
For a logical channel added by accepting an AddChannelRequest, a
server gets "send quota" of 0 on sending the corresponding
AddChannelResponse.
Tamplin & Yoshino Expires March 9, 2013 [Page 9]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
When an endpoint receives a FlowControl for a logical channel, its
"send quota" for the channel gets replenished.
When sending a frame on a logical channel with non-zero ID, the
length of the "Payload data" of the frame MUST NOT be greater than
the "send quota" of the endpoint for the channel. An endpoint MUST
_Fail the Logical Channel_ with drop reason code of 3005 when it's
clear that the other peer violates this.
When a frame is sent on a logical channel with non-zero ID, the
length of the "Payload data" of the frame is subtracted from the
"send quota" of the endpoint for the channel.
An endpoint SHOULD NOT delay replenishment of the other peer's "send
quota" for a logical channel when it has more room for accepting new
data for the channel.
Tamplin & Yoshino Expires March 9, 2013 [Page 10]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
7. Framing
The multiplexing extension uses binary messages to transfer both data
for controlling multiplexing and data of multiplexed connections.
Binary messages have the logical channel ID field at the head of
them. Logical channel ID of 0 is designated for control channel
where multiplex control blocks are exchanged. Non-zero logical
channel IDs are used for transferring data for multiplexed
connections.
The logical channel ID is encoded as variable number of bytes (1, 2,
3 or 4 octets), as follows:
0 1 2 3 4 5 6 7
+-+-------------+
|0|Channel ID(7)|
+-+-------------+
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+---------------------------+
|1|0| Channel ID (14) |
+-+-+---------------------------+
0 1 2
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
+-+-+-+-----------------------------------------+
|1|1|0| Channel ID (21) |
+-+-+-+-----------------------------------------+
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+---------------------------------------------------------+
|1|1|1| Channel ID (29) |
+-+-+-+---------------------------------------------------------+
This encoding is also used by multiplex control blocks where they
need to specify the ID of the objective channel.
See Section 8 (non-control channel) and Section 9 (control channel)
for more details on data that follow the logical channel ID field.
Tamplin & Yoshino Expires March 9, 2013 [Page 11]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
8. Encapsulation
This extension encapsulates each frame of a multiplexed connection
into a binary message with Payload Data obtained by concatenating the
following data in the order they are listed:
1. The logical channel ID for the multiplexed connection.
2. FIN, RSV1, RSV2, RSV3 and opcode of the original frame.
3. Unmasked "Payload Data" of the original frame.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+---------------------------------------------------------------+
| Logical channel ID |
| (8/16/24/32) |
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
| Logical channel ID continued |
+-+-+-+-+-------+-----------------------------------------------+
|F|R|R|R| opcode| Payload Data of original frame |
|I|S|S|S| (4) | |
|N|V|V|V| | |
| |1|2|3| | |
+-+-+-+-+-------+ - - - - - - - - - - - - - - - - - - - - - - - +
: Payload Data of original frame continued ... :
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
: Payload Data of original frame continued ... :
+---------------------------------------------------------------+
All encapsulated frames with a non-zero channel ID MUST be delivered
to the corresponding multiplexed connection in the order they are
received.
This extension MAY change the fragmentation of the original message
before encapsulation in order to insert multiplex control blocks or
adjust the amount of data to flush along with flow control. In doing
this, control messages MAY also be fragmented. Control messages
multiplexed with fragmentation MUST be delivered to the corresponding
multiplexed connection after receiving all fragments and
defragmenting them.
To allow for adjustment of fragmentation, this multiplexing extension
MUST NOT be used after any extension that does any of the followings:
o Require frame boundary on its output to be preserved.
Tamplin & Yoshino Expires March 9, 2013 [Page 12]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
o Use the "Extension data" field or any of the reserved bits on the
WebSocket header as per-frame attribute.
Intermediaries that doesn't understand the WebSocket Multiplexing
Extension MAY fragment the encapsulating messages.
If an encapsulating message doesn't contain a complete channel ID,
_Fail the Physical Connection_ with drop reason code of 2002.
If an encapsulating message contains a logical channel ID of an
inactive channel (e.g. no channel has been opened for the channel ID,
or the channel has been closed by DropChannel or AddChannelResponse
with F bit on and not reopened), the endpoint MUST ignore the
message.
If a binary message with a non-zero channel ID doesn't contain at
least one octet after the channel ID, _Fail the Physical Connection_
with drop reason code of 2003.
Tamplin & Yoshino Expires March 9, 2013 [Page 13]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
9. Multiplex Control Blocks
A binary message with the channel ID of 0 contains zero or more
multiplex control blocks in "Payload data".
0 1 2 3 4 5 6 7
+---------------+
|Channel ID of 0|
+---------------+
|1st multiplex |
:control block :
| |
+---------------+
|2nd multiplex |
:control block :
| |
+---------------+
|... |
: :
| |
+---------------+
Putting multiple control blocks into one WebSocket message saves
framing overhead.
Unless any other negotiated extension defines a meaning for them,
endpoints MUST NOT send any data frame with an opcode other than
"binary frame". When an endpoint received such a frame, it MUST
_Fail the Physical Connection_ with drop reason code of 2001.
Each multiplex control block has fields as follows:
0 1 2 3 4 5 6 7
+-----+---------+
| Opc | |
+-----+ :
| Opc specific :
: data :
| |
+---------------+
Opc
A multiplex control opcode as defined in the following
subsections. Opc of 5-7 are reserved for future use.
Tamplin & Yoshino Expires March 9, 2013 [Page 14]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
Opc specific data
Data interpreted according to that opcode.
Each of the following subsections describes one multiplex control
opcode and how to interpret opc specific data for that opcode.
If any reserved opcode is set to opc, the endpoint MUST _Fail the
Physical Connection_ with drop reason code of 2004.
If any incomplete multiplex control block is found, the endpoint MUST
_Fail the Physical Connection_ with drop reason code of 2005.
9.1. AddChannelRequest
AddChannelRequest is sent only by clients to create a new logical
channel, as if a new WebSocket connection were received on a separate
transport connection.
Multiplex control opcode of AddChannelRequest is 0.
AddChannelRequest has fields as follows:
0 1 2 3 4 5 6 7
+-+-+-+-----+---+
|0|0|0| RSV |Enc|
+-+-+-+-----+---+
|Objective |
:channel ID :
|(1-4 octet) |
+---------------+
|Handshake size |
:(1-9 octet) :
| |
+---------------+
|Handshake |
: :
| |
+---------------+
Enc
Handshake encoding type:
0 - identity
The client's handshake data in the handshake field are sent
as-is without any special encoding or compression applied, and
Tamplin & Yoshino Expires March 9, 2013 [Page 15]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
constitute the complete set of a Request-Line, headers and the
CRLF after the last header that would have been sent on opening
handshake.
1 - delta-encoded
The client's handshake data in the handshake field are delta-
encoded, where any header that is not given is assumed to have
the same value as that given on the current delta base. The
delta base is initialized to the client's opening handshake of
the physical connection but after modifying the
"Sec-WebSocket-Extensions" by removing the element for this
extension and following ones. Every time, an AddChannelRequest
where Enc field is identity is received, the delta base is
updated to its handshake. The Request-Line MUST be sent
regardless if it's the same as one in the delta base or not. A
header with an empty value means that the header is not
inherited from the delta base. When to send valueless headers,
identity encoding MUST be used.
2-3 - reserved
Reserved for future use. An endpoint MUST _Fail the Logical
Channel_ with drop reason code of 3002 if any of reserved type
is specified.
Objective channel ID
The channel ID of the logical channel objective to this operation.
Encoding is the same as one used for encapsulation.
Handshake size
The size of the handshake field encoded the same way as payload
length of the WebSocket Protocol [RFC6455] with 1 bit padding at
the head.
Handshake
The client's opening handshake as defined in Section 4 of RFC 6455
[RFC6455] for the new multiplexed connection. Upgrade,
Connection, Sec-WebSocket-Key and Sec-WebSocket-Version header are
excluded because they are not meaningful under multiplexing. This
field is encoded using the encoding specified by the Enc field.
An endpoint MUST _Fail the Logical Channel_ with drop reason code
of 3001 if any problem is found in parsing this field.
If the channel ID specified by an AddChannelRequest is in use, it
Tamplin & Yoshino Expires March 9, 2013 [Page 16]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
MUST _Fail the Physical Connection_ with drop reason code of 2006.
To accept an AddChannelRequest, the endpoint MUST send an
AddChannelResponse with F bit unset and the objective channel ID
field set to the channel ID specified in the AddChannelRequest. In
this case, the channel becomes active.
To respond to an AddChannelRequest with status meaning handshake
failure, the endpoint MUST send an AddChannelResponse with F bit set
and its objective channel ID field set to the channel ID specified in
the AddChannelRequest. In this case, the channel stays inactive.
To reject an AddChannelRequest due to multiplexing level error, the
endpoint MUST send a DropChannel with its objective channel ID field
set to the channel ID specified in the AddChannelRequest. In this
case, the channel stays inactive.
Channel ID assignment is done by client side. A client MAY use any
algorithm to choose channel IDs for new channels. Note that channel
ID assignment might be changed by intermediaries, so it's not
guaranteed that the value of channel ID is the same on the other
peer.
Different from non-multiplexed WebSocket connection, a client MAY
send frames of multiplexed connections except for "Implicitly Opened
Connection" before receiving AddChannelResponse as far as there's
sufficient send quota. In case the AddChannelRequest fails, those
frames are discarded by the other peer. This doesn't mean that users
of this protocol such as the WebSocket API are required to allow
their users to send frames before receiving the server's opening
handshake.
9.2. AddChannelResponse
AddChannelResponse is sent only by servers in response to the
AddChannelRequest.
Multiplex control opcode of the AddChannelResponse is 1.
AddChannelResponse has fields as follows:
Tamplin & Yoshino Expires March 9, 2013 [Page 17]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
0 1 2 3 4 5 6 7
+-+-+-+-+---+---+
|0|0|1|F|RSV|Enc|
+-+-+-+-+---+---+
|Objective |
:channel ID :
|(1-4 octet) |
+---------------+
|Handshake size |
:(1-9 octet) :
| |
+---------------+
|Handshake |
: :
| |
+---------------+
F
If F is not set, then the server has accepted the
AddChannelRequest. The handshake field MUST contain the response
to an HTTP Upgrade request for the request made by the
AddChannelRequest, If F is set, then the server has rejected the
AddChannelRequest and this SHOULD be treated exactly the same as
if a separate connection was attempted and the connection was
closed after receiving the server's handshake. Enc MUST be set to
identity in this case. The handshake field MUST contain the
response to an HTTP Upgrade request for the request made by the
AddChannelRequest,
Enc
Encoding type the same as defined for the AddChannelRequest opcode
(but replacing "AddChannelRequest" with "AddChannelResponse", and
"Request-Line" with "Response-Line"). An endpoint MUST _Fail the
Logical Channel_ with drop reason code of 3004 if any of reserved
type is specified.
Objective channel ID
Same as one in the AddChannelRequest. If an inactive channel is
specified, the endpoint MUST ignore this AddChannelResponse.
Handshake size
The size of the handshake field encoded the same way as payload
length of the WebSocket Protocol with 1 bit padding at the head.
Tamplin & Yoshino Expires March 9, 2013 [Page 18]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
Handshake
The server's opening handshake as defined in Section 4 of RFC 6455
[RFC6455] for this multiplexed connection. Upgrade, Connection
and Sec-WebSocket-Accept header are excluded because they are not
meaningful under multiplexing. This field is encoded using the
encoding specified by the Enc field. An endpoint MUST _Fail the
Logical Channel_ with drop reason code of 3003 if any problem is
found in parsing this field.
If the server's opening handshake is validated, the client MUST take
this as _The WebSocket Connection is Established_.
9.3. FlowControl
FlowControl is used to replenish the other peer's send quota for the
specified logical channel.
Multiplex control opcode of FlowControl is 2.
FlowControl has fields as follows.
0 1 2 3 4 5 6 7
+-+-+-+---------+
|0|1|0| RSV |
+-+-+-+---------+
|Objective |
:channel ID :
|(8-32 bit) |
+---------------+
|Replenished |
:send quota :
|(1-9 octet) |
+---------------+
Objective channel ID
Same as one in the AddChannelRequest. If an inactive channel is
specified, the endpoint MUST ignore this FlowControl.
Replenished quota
The number of bytes the receiver can have outstanding towards the
sender of the FlowControl message. It's encoded the same way as
payload length of the WebSocket Protocol with 1 bit padding at the
head.
Tamplin & Yoshino Expires March 9, 2013 [Page 19]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
9.4. DropChannel
DropChannel is used to close a logical channel.
Multiplex control opcode of DropChannel is 3.
DropChannel has fields as follows:
0 1 2 3 4 5 6 7
+-+-+-+---------+
|0|1|1| RSV |
+-+-+-+---------+
|Objective |
:channel ID :
|(1-4 octet) |
+---------------+
|Reason size |
:(1-9 octet) :
| |
+---------------+
|Reason |
: :
| |
+---------------+
Objective channel ID
Same as one in the AddChannelRequest.
Reason size
The size of the reason field encoded the same way as payload
length of the WebSocket Protocol with 1 bit padding at the head.
Reason
The reason of closure. Reason MAY be empty. If reason is not
empty, the first two bytes MUST be a 2-byte unsigned integer (in
network byte order) representing a drop reason code. Following
the 2-byte integer, reason MAY contain UTF-8-encoded human
readable drop reason phrase.
When an endpoint received a DropChannel for an active non-control
channel, the endpoint MUST tear down the logical channel, and the
application instance that used the logical channel MUST treat this as
closure of underlying transport.
When an endpoint received a DropChannel in response to an
Tamplin & Yoshino Expires March 9, 2013 [Page 20]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
AddChannelRequest, the endpoint MUST abort creation of the logical
channel, and the application instance that requested creation of the
logical channel MUST treat this as closure of underlying transport
without receiving reply for the creation request.
When an endpoint sent or received a DropChannel for an active non-
control channel, the endpoint MUST mark the channel as inactive. If
the endpoint is server and it has not already sent a DropChannel for
the channel, it MUST send a DropChannel with drop reason code of
3008.
Once received a DropChannel for a logical channel, the channel ID of
the logical channel becomes available again for a new
AddChannelRequest.
9.4.1. Drop Reason Codes
Drop reason codes are 4 digit unsigned integers.
1000-1999 are for normal closure on logical channel without any
multiplexing level error. These codes are used for dropping non-
control channels.
1000 Normal closure
DropChannel with this drop reason code is commonly sent when
_Close the WebSocket Connection_ is made on the multiplexed
connection.
2000-2999 are for errors that _Fail the Physical Connection_. These
codes are used for dropping the control channel.
2000 Physical connection failed
Used if a more specific error is not available.
2001 Invalid encapsulating message
Received a data message with non binary opcode.
2002 Channel ID is truncated
When received an encapsulating message with a logical channel ID
which is truncated.
Tamplin & Yoshino Expires March 9, 2013 [Page 21]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
2003 Encapsulated frame is truncated
Channel is non-control. The header field of encapsulated frame is
missing.
2004 Unknown multiplex control opcode
Channel is control. Opcode of multiplex control block is unknown.
2005 Invalid multiplex control block
Channel is control. Encountered an invalid multiplex control
block. E.g. objective channel ID is truncated, reserved bit is
raised.
2006 Channel already exists
Received an AddChannelRequest for an active channel.
2007 New channel slot violation
Received an AddChannelRequest despite the other peer has no new
channel slot.
2008 New channel slot overflow
Received a NewChannelSlot that overflows the number of new channel
slots.
3000-3999 are for errors that _Fail the Logical channel_. These
codes are used for dropping non-control channels.
3000 Logical channel failed
Used if a more specific error is not available.
3001 Bad request
Received an AddChannelRequest with a malformed handshake.
3002 Unknown request encoding
Received an AddChannelRequest with an unknown encoding type.
3003 Bad response
Received an AddChannelResponse with a malformed handshake.
Tamplin & Yoshino Expires March 9, 2013 [Page 22]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
3004 Unknown response encoding
Received an AddChannelResponse with an unknown encoding type.
3005 Send quota violation
Received an encapsulating message exceeding send quota.
3006 Send quota overflow
Received a FlowControl that overflows send quota.
3007 Idle timeout
Terminating an idle channel.
3008 DropChannel acknowledged
Used for a DropChannel sent in response to received DropChannel.
When a server received a DropChannel and it hasn't sent any
DropChannel for that logical channel, the server MUST send a
DropChannel with this reason code so that the client can release
the channel ID and reuse it for a new AddChannelRequest safely.
4000-4999 are for requesting the other peer to take some actions.
These codes are used for dropping non-control channels.
4001 Use another physical connection
The server is requesting the client to open a new physical
connection and use it than adding any more logical channel until
receiving a NewChannelSlot. A client received this reason code
SHOULD NOT issue an AddChannelRequest on this physical connection
until receiving a NewChannelSlot.
4002 Busy
The server is requesting the client to stop issuing an
AddChannelRequest until receiving a NewChannelSlot. A client
received this reason code SHOULD NOT issue an AddChannelRequest on
this physical connection until receiving a NewChannelSlot.
9.5. NewChannelSlot
NewChannelSlot is sent only by servers to adds new slots to the
client's new channel pool.
Multiplex control opcode of NewChannelSlot is 4.
Tamplin & Yoshino Expires March 9, 2013 [Page 23]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
NewChannelSlot has fields as follows:
0 1 2 3 4 5 6 7
+-+-+-+-------+-+
|1|0|0| RSV |F|
+-+-+-+-------+-+
|Number of slots|
:(1-9 octet) :
| |
+---------------+
|Initial send |
:quota :
|(1-9 octet) |
+---------------+
F
If F bit is false, normal slot is added. If F bit is true,
fallback suggestion slot is added. Number of slots field and
initial quota field MUST be 0 for fallback suggestion slot. When
a client encounters a fallback suggestion slot, it MUST open a new
physical connection and use it than adding any more logical
channel on this physical connection until any normal slot is
available.
Number of slots
The number of slots to add. It's encoded the same way as payload
length of the WebSocket Protocol with 1 bit padding at the head.
This value MAY be 0 when it makes sense.
Initial quota
The initial quota each of slots added by this NewChannelSlot gets.
It's encoded the same way as payload length of the WebSocket
Protocol with 1 bit padding at the head.
When a client received a NewChannelSlot, the client MUST add new
slots of the specified number. Each of new slots gets the specified
initial send quota.
Tamplin & Yoshino Expires March 9, 2013 [Page 24]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
10. Examples
_This section is non-normative._
The examples below assume the handshake has already completed and the
multiplexing extension was negotiated.
Frames of encapsulating messages from client to server MUST be
masked. To simplify, the examples below are not masked.
0x82 0x0d 0x01 0x81 "Hello world"
This is a non-fragmented text message of "Hello world" on channel
1 encapsulated into a non-fragmented message.
0x02 0x07 0x01 0x81 "Hello" 0x80 0x06 " world"
This is a fragmented encapsulating message converying a non-
fragmented text frame "Hello world" on channel 1.
0x82 0x07 0x01 0x01 "Hello" 0x82 0x05 0x02 0x81 "bye" 0x82 0x08 0x01
0x80 " world"
This example shows how data for two channels are interleaved.
There're three non-fragmented encapsulating messages. The first
and third one convey each of two frames of a fragmented text
message of "Hello world" on channel 1. The second one conveys a
non-fragmented text message of "bye" on channel 2.
Tamplin & Yoshino Expires March 9, 2013 [Page 25]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
11. Client Behavior
When a client is asked to _Establish a WebSocket Connection_ by some
WebSocket application instance, it MAY choose to reuse an existing
WebSocket connection if all of the following are true:
o the multiplexing extension was successfully negotiated on that
connection
o the scheme portions of the URIs match exactly
o the host portions of the URIs either match exactly or resolve to
the same IP address (TBD: consider DNS rebind attacks)
o the port portions of the URIs (either explicit or implied by the
scheme) match exactly
o the connection has an availablle logical channel ID
If the client chooses to reuse an existing multiplexed connection, it
sends an AddChannelRequest as described above. If the
AddChannelRequest is accepted, WebSocket frames may be sent over that
channel as normal. If the server rejects the AddChannel, the client
SHOULD attempt to open a new physical WebSocket connection (for
example, in a shared hosting environment a server may not be prepared
to multiplex connections from different customers despite having a
single IP address for them).
Tamplin & Yoshino Expires March 9, 2013 [Page 26]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
12. Buffering
There will be lots of small frames sent in this protocol
(particularly replenishing send quotas), so a sender SHOULD attempt
to aggregate multiplex control blocks into larger WebSocket frames.
For data frames, a sender also SHOULD attempt to aggregate fragments
into one packet of the underlying transport. However, care must be
taken to avoid introducing excessive latency - the exact heuristics
for delaying in order to aggregate blocks is TBD.
Tamplin & Yoshino Expires March 9, 2013 [Page 27]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
13. Fairness
A multiplexing implementation MUST ensure reasonable fairness among
the logical channels. This is accomplished in several ways:
Receiver side
o The receiver MAY limit the send quota of a logical channel by not
replenishing it to make sure that any logical channel doesn't
dominate the connection.
o Send quota for one logical channel SHOULD be determined
considering the processing capacity (buffer size, processing
power, throughput, etc.) of that logical channel. For example,
when a logical channel with excess load cannot drain data from the
connection smoothly, the other logical channels get stuck even
when they have room of processing capacity. Unless there's
special need to give such a big quota for the channel, such
condition just makes overall performance low.
Sender side
o The sender MUST use a fair mechanism for selecting which logical
channel's data to send in the next WebSocket frame. Simple
implementations may choose a round-robin scheduler, while more
advanced implementations may adjust priority based on the amount
or frequency of data sent by each logical channel.
o The sender MUST fragment a large message into smaller frames to
prevent a large message in a logical channel occupying the
physical connection and thus delaying messages in other logical
channels.
Tamplin & Yoshino Expires March 9, 2013 [Page 28]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
14. Proxies
Proxies which do not multiplex/demultiplex are not affected by the
presence of this extension -- they simply process WebSocket frames as
usual. Proxies which filter or monitor WebSocket traffic will need
to understand the multiplexing extension in order to extract the data
from logical connections or to terminate individual logical
connections when policy is violated. Proxies which actively
multiplex connections or demultiplex them (for example, a mobile
network might have a proxy which aggregates WebSocket connections at
a single cell to conserve bandwidth to the main gateway) will require
additional configuration (perhaps including the client) that is
outside the scope of this document.
Tamplin & Yoshino Expires March 9, 2013 [Page 29]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
15. Timeout
When all the logical channels are closed, each endpoint MAY _Start
the WebSocket Closing Handshake_ on the physical connection. Such
_Start the WebSocket Closing Handshake_ operation SHOULD be delayed
assuming the physical connection may be reused after some idle
period.
Tamplin & Yoshino Expires March 9, 2013 [Page 30]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
16. Close the Logical Channel
To _Close the Logical Channel_, an endpoint MUST send a DropChannel
multiplex control block with drop reason code of 1000.
Tamplin & Yoshino Expires March 9, 2013 [Page 31]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
17. Fail the Logical Channel
To _Fail the Logical Channel_, an endpoint MUST send a DropChannel
multiplex control block with drop reason code in the range of 3000-
3999.
Tamplin & Yoshino Expires March 9, 2013 [Page 32]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
18. Fail the Physical Connection
To _Fail the Physical Connection_, an endpoint MUST send a
DropChannel multiplex control block with objective channel ID of 0
and drop reason code in the range of 2000-2999, and then _Fail the
WebSocket Connection_ on the physical connection with status code of
1011.
Tamplin & Yoshino Expires March 9, 2013 [Page 33]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
19. Operations and Events on Multiplexed Connection
When an endpoint is asked to perform any operation defined in the
WebSocket Protocol except for _Close the WebSocket Connection_ by
some application instance, the endpoint MUST perform the operation on
the corresponding logical channel.
Any event on a logical channel except for _The WebSocket Connection
is Closed_, MUST be taken as one for the corresponding application
instance.
When an endpoint is asked to do _Close the WebSocket Connection_ by
some application instance, it MUST perform _Close the Logical
Channel_ on the corresponding logical channel.
When a DropChannel is received, or the physical connection is closed,
it MUST be taken as _The WebSocket Connection is Closed_ event for
the corresponding application instance(s).
What to set to _Extension In Use_ for each multiplexed connection is
TBD.
Tamplin & Yoshino Expires March 9, 2013 [Page 34]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
20. Security Considerations
A client MUST be prepared to receive a NewChannelSlot with huge value
on the number of slots field.
Each message should consume quota for some fixed value to prohibit a
channel sending lots of zero sized message to occupy the physical
connection (TBD).
Have upper bound for send quota.
Tamplin & Yoshino Expires March 9, 2013 [Page 35]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
21. IANA Considerations
This specification is registering a value of the Sec-WebSocket-
Extension header field in accordance with Section 11.4 of the
WebSocket protocol [RFC6455] as follows:
Extension Identifier
mux
Extension Common Name
Multiplexing Extension for WebSockets
Extension Definition
This document
Known Incompatible Extensions
None
Tamplin & Yoshino Expires March 9, 2013 [Page 36]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
22. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol",
RFC 6455, December 2011.
Tamplin & Yoshino Expires March 9, 2013 [Page 37]
Internet-Draft A Multiplexing Extension for WebSockets September 2012
Authors' Addresses
John A. Tamplin
Google, Inc.
Email: jat@jaet.org
Takeshi Yoshino
Google, Inc.
Email: tyoshino@google.com
Tamplin & Yoshino Expires March 9, 2013 [Page 38]
