idnits 2.17.1 draft-tamplin-hybi-google-mux-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC6455]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 27, 2012) is 4466 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HyBi Working Group J. Tamplin 3 Internet-Draft T. Yoshino 4 Intended status: Standards Track Google, Inc. 5 Expires: July 30, 2012 January 27, 2012 7 A Multiplexing Extension for WebSockets 8 draft-tamplin-hybi-google-mux-02 10 Abstract 12 The WebSocket Protocol [RFC6455] requires a new transport connection 13 for every WebSocket connection. This presents a scalability problem 14 when many clients connect to the same server, and is made worse by 15 having multiple clients running in different tabs of the same user 16 agent. This extension provides a way for separate logical WebSocket 17 connections to share an underlying transport connection. 19 Please send feedback to the hybi@ietf.org mailing list. 21 Status of this Memo 23 This Internet-Draft is submitted to IETF in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on July 30, 2012. 38 Copyright Notice 40 Copyright (c) 2012 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Conformance Requirements . . . . . . . . . . . . . . . . . . . 4 57 3. Interaction with other Extensions / Framing Mechanisms . . . . 5 58 4. Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 5. Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . 7 60 6. Framing . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 61 7. Multiplex Control Frames . . . . . . . . . . . . . . . . . . . 9 62 8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 63 9. Client Behavior . . . . . . . . . . . . . . . . . . . . . . . 13 64 10. Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . 14 65 11. Fairness . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 66 12. Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 67 13. Nesting . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 68 14. Security Considerations . . . . . . . . . . . . . . . . . . . 18 69 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 70 16. Normative References . . . . . . . . . . . . . . . . . . . . . 20 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21 73 1. Overview 75 This document describes a MUX extension to the WebSocket protocol. A 76 client that supports this extension will advertise support for it in 77 the initial handshake using the "Sec-WebSocket-Extensions" header. 78 If the server supports this extension and supports parameters 79 compatible with the client's request, it accepts the use of this 80 extension in the handshake response. 82 2. Conformance Requirements 84 All diagrams, examples, and notes in this specification are non- 85 normative, as are all sections explicitly marked non-normative. 86 Everything else in this specification is normative. 88 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 89 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 90 document are to be interpreted as described in RFC2119. [RFC2119] 92 Requirements phrased in the imperative as part of algorithms (such as 93 "strip any leading space characters" or "return false and abort these 94 steps") are to be interpreted with the meaning of the key word 95 ("must", "should", "may", etc) used in introducing the algorithm. 97 Conformance requirements phrased as algorithms or specific steps MAY 98 be implemented in any manner, so long as the end result is 99 equivalent. (In particular, the algorithms defined in this 100 specification are intended to be easy to follow, and not intended to 101 be performant.) 103 3. Interaction with other Extensions / Framing Mechanisms 105 Any compression extensions negotiated apply only to the channel they 106 are negotiated on -- therefore, any compression extension in the 107 initial handshake applies only to logical channel 1. If WebSocket 108 payload data is masked by a per-frame key, such masking is applied to 109 frames for each logical channel separately. 111 If other negotiated extensions define extension data, the other 112 extension defines whether it applies to just one logical channel (it 113 is expected that most extensions will do so) or the physical channel. 114 If the other extension applies to one logical channel, it always 115 comes after the MUX extension data; otherwise the order depends on 116 the order the extensions were listed during the handshake response. 118 4. Channels 120 The MUX extension maintains separate logical channels, each of which 121 is fully the logical equivalent of an independent WebSocket 122 connection, including separate handshake headers. If the MUX 123 extension is successfully negotiated, the headers on the initial 124 handshake are automatically taken to mean channel 1, which is 125 implicitly opened by completing the handshake. New channels are 126 added by the client issuing the AddChannel command (note that only 127 the client may initiate new WebSocket connections), including any 128 request headers which do not have the same value as the initial 129 handshake. The server's AddChannel response likewise includes any 130 response headers which are different from the initial handshake (the 131 details of this are TBD, but a simple suggestion for a delta encoding 132 is given below). Channel 0 (control channel) is reserved for mux 133 control messages and does not contain payload data from any logical 134 channel. A client which attempts to add a channel to an existing 135 connection that is not accepted by the server SHOULD attempt a new 136 WebSocket connection. 138 Once the MUX extension is negotiated on a connection, all frames must 139 be prefixed with a channel number in the extension data field. 140 Control frames with a channel id 0 refer to the physical connection, 141 other control frames MUST be delivered on the logical channel in 142 order with data frames for that logical channel. Control frames 143 SHOULD be sent only on channel 0 where possible, though control 144 frames for other extensions in particular may need to apply to 145 individual logical channels. 147 A receiver MUST fail the physical connection and all open logical 148 channels if any of these rules are violated by the sender. 150 5. Flow Control 152 Each logical channel, including the implicitly created channel 1, is 153 initially given a quota of bytes that may be transmitted in each 154 direction without acknowledgement. It is illegal to send more bytes 155 than the remaining quota, and the receiver MUST fail the logical 156 channel for any sender that does so. This quota is replenished via 157 control messages as the receiver processes the data. 159 The initial quota is specified with the "quota" extension parameter, 160 and defaults to 64k (TBD) if it is not specified. The client and 161 server each may specify a "quota" parameter and these are unrelated 162 -- each specifies how many bytes the other side may send without 163 acknowledgement. The quota values in the initial handshake apply to 164 the implicitly opened channel 1. 166 6. Framing 168 If the extension is successfully negotiated during the handshake, all 169 frames have a channel id in the extension data. The channel ID is 170 encoded as a variable number of bytes, as follows: 172 0 1 2 3 4 5 6 7 173 +-+-------------+ 174 |0|channel id(7)| 175 +-+-------------+ 177 0 1 178 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 179 +-+-+---------------------------+ 180 |1|0| channel id (14) | 181 +-+-+---------------------------+ 183 0 1 2 184 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 185 +-+-+-+-----------------------------------------+ 186 |1|1|0| channel id (21) | 187 +-+-+-+-----------------------------------------+ 189 0 1 2 3 190 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 191 +-+-+-+---------------------------------------------------------+ 192 |1|1|1| channel id (29) | 193 +-+-+-+---------------------------------------------------------+ 195 The base spec requires that a sequence of frames on the wire be a 196 frame with an opcode other than 0, zero or more frames with opcode 0 197 and the FIN bit clear, and terminated by a frame with the FIN bit set 198 (which may be the initial frame in the case of an unfragmented 199 message). The MUX extension relaxes this requirement to be for just 200 frames of one logical channel, and that frames of other logical 201 channels may be interleaved arbitrarily. 203 All frames with a non-zero channel id must be delivered to the 204 specified logical channel in the order they are received, though 205 fragmentation may be changed if appropriate. Control frames with a 206 non-zero channel id may also trigger additional processing by the MUX 207 extension. 209 Control frames with a channel id of 0 refer to the physical 210 connection, and may also trigger additional processing - for example, 211 a close frame on the physical channel will close all logical channels 212 as well (details TBD). 214 7. Multiplex Control Frames 216 Data frames with a channel id of 0 are MUX control frames. Unless 217 another negotiated extension defines a meaning for them, any frames 218 on channel 0 with an opcode other than "binary" MUST trigger a 219 failure of the physical connection. Binary frames on channel 0 are 220 MUX control frames, and the payload consists of a zero or more MUX 221 control blocks, each defined as follows: 223 o a channel number encoded the same as that in the extension data 224 (designated as control channel) 226 o an opcode and data interpreted according to that opcode as 227 follows: 229 0 1 2 3 4 5 6 7 230 +-----+---------+ 231 | opc | opcdata | 232 +-----+---------+ 234 o zero or more bytes defined by the opcode 236 The opcodes defined are: 238 0 - AddChannel request (only from client) 240 Create a new logical channel as control channel, exactly as if a 241 new connection were received on a separate transport connection, 242 except for the encoding of the headers. opcdata is interpreted as 243 follows: 245 3 4 5 6 7 246 +-+---+---+ 247 |R|enc|len| 248 +---------+ 250 R is reserved for future use, len is the number of bytes used to 251 represent the length of following headers minus 1, and enc is an 252 encoding type: 254 0 - uncompressed The header bytes that follow are uncompressed, 255 and constitute the complete set of headers that would have been 256 sent on a WebSocket connection request 258 1 - delta-encoded The header bytes that follow are delta-encoded, 259 where any header that is not given is assumed to have the same 260 value as that given on the initial request of the physical 261 connection. A header with an empty value means that header is 262 not inherited from the initial connection. (TBD: this means 263 that valueless headers cannot be encoded with this scheme). 265 2-3 - reserved Reserved for future use 267 The following n bytes, where n is the value of len inside opcdata 268 plus 1, are an 8-32 bit length of the request header data that 269 follows, in network byte order. The request header data consists 270 of a series of lines, separated by a CR-LF pair and terminated by 271 an extra CR-LF pair. The first line is the full URI for the new 272 connection, and the remaining lines are the request headers, 273 encoded in UTF8 and as defined by the enc value in opcdata. 275 The initial quota for the new connection is 0, so the client may 276 not send any data for this connection until the AddChannel 277 response is received. 279 The server always responds with an AddChannel response message, 280 described below. 282 1 - AddChannel response (only from server) 284 opcdata is defined as follows: 286 3 4 5 6 7 287 +-----+---+ 288 |F|enc|len| 289 +-----+---+ 291 RSV is reserved for future use, F is true if this response 292 indicates a failure to add the requested channel, len is the of 293 bytes used to represent the length of following headers minus 1, 294 and enc is an encoding scheme defined as in the AddChannel 295 request. 297 If F is set, then the server has rejected the request to add a new 298 channel and this should be treated exactly the same as if a 299 separate connection was attempted and the handshake failed. enc is 300 ignored in this case, and the following n bytes, where n is the 301 value of len inside opcdata plus 1, are an 8-32 bit length of the 302 request header data that follows, in network byte order. The 303 request header data consists of a series of lines, separated by a 304 CR-LF pair and terminated by an extra CR-LF pair. These lines 305 should be treated as the response to an HTTP Upgrade request for 306 the WebSocket URI, For example: 308 HTTP/1.1 404 Not found 310 404 message body... 312 If F is not set, then the server has accepted the request. The 313 following n bytes, where n is the value of len inside opcdata plus 314 1, are an 8-32 bit length of the request header data that follows, 315 in network byte order. The request header data consists of a 316 series of lines, separated by a CR-LF pair and terminated by an 317 extra CR-LF pair. These are encoded according to enc as defined 318 in the AddChannel request, and the complete set of headers after 319 decoding is treated exactly as if it was received in response to a 320 handshake on a separate connection. 322 2 - FlowControl 324 opcdata is defined as follows: 326 3 4 5 6 7 327 +-----+---+ 328 | RSV |len| 329 +-----+---+ 331 RSV is reserved for future use, and len is the number of bytes in 332 the quota minus 1. 334 The following n bytes, treated as an unsigned integer in network 335 byte order, is added to the quota of the number of bytes the 336 receiver can have outstanding towards the sender of the 337 FlowControl message. (TBD: is it worth having some non-linear 338 encoding to reduce the average bits required to represent these 339 values?) 341 3-7 - reserved 343 Reserved for future use (TBD: do we need some support for 344 quiescence?) 346 8. Examples 348 _This section is non-normative._ 350 The examples below assume the handshake has already completed and the 351 x-google-mux extension was negotiated. 353 01 06 01 "Hello" 81 04 02 "bye" 80 07 01 " world" 355 This is a fragmented text message of "Hello world" on channel 1 356 interleaved with a text message of "bye" on channel 2. Note that 357 the sequence of opcodes/FIN bits cannot be understood without 358 considering the channel id of each frame. 360 9. Client Behavior 362 When a client is asked to make a new WebSocket connection, it MAY 363 choose to use an existing WebSocket connection if all of the 364 following are true: 366 o the MUX extension was successfully negotiated on that connection 368 o the scheme portions of the URIs match exactly 370 o the host portions of the URIs either match exactly or resolve to 371 the same IP address (TBD: consider DNS rebind attacks) 373 o the port portions of the URIs (either explicit or implied by the 374 scheme) match exactly 376 o the connection has an availablle logical stream id 378 If the client chooses to reuse an existing MUXd connection, it sends 379 an AddChannel message as described above. If the AddChannel is 380 successful, WebSocket frames may be sent over that channel as normal. 381 If the server rejects the AddChannel, the client SHOULD attempt to 382 open a new physical WebSocket connection (for example, in a shared 383 hosting environment a server may not be prepared to multiplex 384 connections from different customers despite having a single IP 385 address for them). 387 10. Buffering 389 There will be lots of small frames sent in this protocol 390 (particularly replenishing send quotas), so a sender SHOULD attempt 391 to aggregate MUX blocks into larger WebSocket frames. However, care 392 must be taken to avoid introducing excessive latency - the exact 393 heuristics for delaying in order to aggregate blocks is TBD. 395 11. Fairness 397 A MUX implementation MUST ensure reasonable fairness among the 398 logical channels. This is accomplished in several ways: 400 o by restricting the send quota of a logical channel, the receiver 401 can make sure that sender cannot dominate its buffer space 403 o when sending data, the sender MUST use a fair mechanism for 404 selecting which logical channel's data to send in the next 405 WebSocket frame. Simple implementations may choose a round-robin 406 scheduler, while more advanced implementations may adjust priority 407 based on the amount or frequency of data sent by each logical 408 channel. 410 o logical channel frames that are sent SHOULD be limited in size 411 (such as by refragmenting) when there is contention for the 412 physical channel to minimize head-of-line blocking 414 12. Proxies 416 Proxies which do not mux/demux are not affected by the presence of 417 this extension -- they simply process WebSocket frames as usual. 418 Proxies which filter or monitor WebSocket traffic will need to 419 understand the MUX extension in order to extract the data from 420 logical connections or to terminate individual logical connections 421 when policy is violated. Proxies which actively multiplex 422 connections or demultiplex them (for example, a mobile network might 423 have a proxy which aggregates WebSocket connections at a single cell 424 to conserve bandwidth to the main gateway) will require additional 425 configuration (perhaps including the client) that is outside the 426 scope of this document. 428 13. Nesting 430 TBD: Should we allow nesting of MUX'd channels, or should we require 431 that an intermediary MUXing channels flatten it? The advantage of 432 nesting is it is conceptually cleaner and less work for an 433 intermediary, while the disadvantage is that flow control messages 434 will get amplified by nesting and the ultimate server's job is a bit 435 more complicated to keep a tree of channel mappings. 437 14. Security Considerations 439 TBD 441 15. IANA Considerations 443 This specification is registering a value of the Sec-WebSocket- 444 Extension header field in accordance with Section 11.4 of the 445 WebSocket protocol [RFC6455] as follows: 447 Extension Identifier 449 mux 451 Extension Common Name 453 Mulplexing Extension for WebSockets 455 Extension Definition 457 This document [draft-tamplin-hybi-google-mux] defines the mux 458 extension. 460 Known Incompatible Extensions 462 None 464 16. Normative References 466 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 467 Requirement Levels", BCP 14, RFC 2119, March 1997. 469 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 470 RFC 6455, December 2011. 472 Authors' Addresses 474 John A. Tamplin 475 Google, Inc. 477 Email: jat@google.com 479 Takeshi Yoshino 480 Google, Inc. 482 Email: tyoshino@google.com