HyBi Working Group J.A. Tamplin
Internet-Draft T. Yoshino
Intended status: Standards Track Google, Inc.
Expires: April 29, 2012 October 27, 2011

A Mulplexing Extension for WebSockets


The WebSocket Protocol [WS] 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 April 29, 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.

Table of Contents

1. Overview

This document describes a MUX extension to the WebSocket protocol. A client that supports this extension will advertise support for it in the initial 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 in the handshake response.

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.)

3. Interaction with other Extensions / Framing Mechanisms

Any compression extensions negotiated apply only to the channel they are negotiated on -- therefore, any compression extension in the initial handshake applies only to logical channel 1. If WebSocket payload data is masked by a per-frame key, such masking is applied to frames for each logical channel separately.

If other negotiated extensions define extension data, the other extension defines whether it applies to just one logical channel (it is expected that most extensions will do so) or the physical channel. If the other extension applies to one logical channel, it always comes after the MUX extension data; otherwise the order depends on the order the extensions were listed during the handshake response.

4. Channels

The MUX extension maintains separate logical channels, each of which is fully the logical equivalent of an independent WebSocket connection, including separate handshake headers. If the MUX extension is successfully negotiated, the headers on the initial handshake are automatically taken to mean channel 1, which is implicitly opened by completing the handshake. New channels are added by the client issuing the AddChannel command (note that only the client may initiate new WebSocket connections), including any request headers which do not have the same value as the initial handshake. The server's AddChannel response likewise includes any response headers which are different from the initial handshake (the details of this are TBD, but a simple suggestion for a delta encoding is given below). Channel 0 is reserved for mux control messages and does not contain payload data from any logical channel. A client which attempts to add a channel to an existing connection that is not accepted by the server SHOULD attempt a new WebSocket connection.

Once the MUX extension is negotiated on a connection, all frames must be prefixed with a channel number in the extension data field. Control frames with a channel id 0 refer to the physical connection, other control frames MUST be delivered on the logical channel in order with data frames for that logical channel. Control frames SHOULD be sent only on channel 0 where possible, though control frames for other extensions in particular may need to apply to individual logical channels.

A receiver MUST fail the physical connection and all open logical channels if any of these rules are violated by the sender.

5. Flow Control

Each logical channel, including the implicitly created channel 1, is initially given a quota of bytes that may be transmitted in each direction without acknowledgement. It is illegal to send more bytes than the remaining quota, and the receiver MUST fail the logical channel for any sender that does so. This quota is replenished via control messages as the receiver processes the data.

The initial quota is specified with the "quota" extension parameter, and defaults to 64k (TBD) if it is not specified. The client and server each may specify a "quota" parameter and these are unrelated -- each specifies how many bytes the other side may send without acknowledgement. The quota values in the initial handshake apply to the implicitly opened channel 1.

6. Framing

If the extension is successfully negotiated during the handshake, all frames have a channel id in the extension data. The channel ID is encoded as a variable number of bytes, 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)                     | 

The base spec requires that a sequence of frames on the wire be a frame with an opcode other than 0, zero or more frames with opcode 0 and the FIN bit clear, and terminated by a frame with the FIN bit set (which may be the initial frame in the case of an unfragmented message). The MUX extension relaxes this requirement to be for just frames of one logical channel, and that frames of other logical channels may be interleaved arbitrarily.

All frames with a non-zero channel id must be delivered to the specified logical channel in the order they are received, though fragmentation may be changed if appropriate. Control frames with a non-zero channel id may also trigger additional processing by the MUX extension.

Control frames with a channel id of 0 refer to the physical connection, and may also trigger additional processing - for example, a close frame on the physical channel will close all logical channels as well (details TBD).

7. Multiplex Control Frames

Data frames with a channel id of 0 are MUX control frames. Unless another negotiated extension defines a meaning for them, any frames on channel 0 with an opcode other than "binary" MUST trigger a failure of the physical connection. Binary frames on channel 0 are MUX control frames, and the payload consists of a zero or more MUX control blocks, each defined as follows:

The opcodes defined are:

8. Examples

This section is non-normative.

The examples below assume the handshake has already completed and the x-google-mux extension was negotiated.

9. Client Behavior

When a client is asked to make a new WebSocket connection, it MAY choose to use an existing WebSocket connection if all of the following are true:

If the client chooses to reuse an existing MUXd connection, it sends an AddChannel message as described above. If the AddChannel is successful, 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).

10. Buffering

There will be lots of small frames sent in this protocol (particularly replenishing send quotas), so a sender SHOULD attempt to aggregate MUX blocks into larger WebSocket frames. However, care must be taken to avoid introducing excessive latency - the exact heuristics for delaying in order to aggregate blocks is TBD.

11. Fairness

A MUX implementation MUST ensure reasonable fairness among the logical channels. This is accomplished in several ways:

12. Proxies

Proxies which do not mux/demux 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 MUX 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.

13. Nesting

TBD: Should we allow nesting of MUX'd channels, or should we require that an intermediary MUXing channels flatten it? The advantage of nesting is it is conceptually cleaner and less work for an intermediary, while the disadvantage is that flow control messages will get amplified by nesting and the ultimate server's job is a bit more complicated to keep a tree of channel mappings.

14. Security Considerations


15. 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 [WS] as follows:

16. References

[WS] Fette, I. and A. Melnikov, "The WebSocket Protocol", Internet-Draft draft-ietf-hybi-thewebsocketprotocol-17, September 2011.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.

Authors' Addresses

John A. Tamplin Google, Inc. EMail: jat@google.com
Takeshi Yoshino Google, Inc. EMail: tyoshino@google.com