idnits 2.17.1 draft-ietf-hybi-websocket-multiplexing-01.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 (April 20, 2012) is 4389 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: October 22, 2012 April 20, 2012 7 A Multiplexing Extension for WebSockets 8 draft-ietf-hybi-websocket-multiplexing-01 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 October 22, 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 1.1. Physical Connection and Logical Channels . . . . . . . . . 3 57 2. Conformance Requirements . . . . . . . . . . . . . . . . . . . 4 58 3. Interaction with other Extensions / Framing Mechanisms . . . . 5 59 3.1. Choosing the point to apply an extension . . . . . . . . . 5 60 4. Multiplexed Connections . . . . . . . . . . . . . . . . . . . 7 61 5. Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . 9 62 6. Framing . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 63 7. Multiplex Control Blocks . . . . . . . . . . . . . . . . . . . 12 64 7.1. AddChannelRequest . . . . . . . . . . . . . . . . . . . . 13 65 7.2. AddChannelResponse . . . . . . . . . . . . . . . . . . . . 15 66 7.3. FlowControl . . . . . . . . . . . . . . . . . . . . . . . 16 67 7.4. DropChannel . . . . . . . . . . . . . . . . . . . . . . . 17 68 7.5. EncapsulatedControlFrame . . . . . . . . . . . . . . . . . 18 69 8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 70 9. Client Behavior . . . . . . . . . . . . . . . . . . . . . . . 20 71 10. Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . 21 72 11. Fairness . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 73 12. Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 74 13. Nesting . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 75 14. Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 76 15. Close the Logical Channel . . . . . . . . . . . . . . . . . . 26 77 16. Fail the Logical Channel . . . . . . . . . . . . . . . . . . . 27 78 17. Fail the Physical Connection . . . . . . . . . . . . . . . . . 28 79 18. Operations and Events on Multiplexed Connection . . . . . . . 29 80 19. Security Considerations . . . . . . . . . . . . . . . . . . . 30 81 20. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 82 21. Normative References . . . . . . . . . . . . . . . . . . . . . 32 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 33 85 1. Overview 87 This document describes a multiplexing extension for the WebSocket 88 Protocol. With this extension, one TCP connection can provide 89 multiple virtual WebSocket connections by tagging frames using 90 "Extension data". A client that supports this extension will 91 advertise support for it in the client's opening handshake using the 92 "Sec-WebSocket-Extensions" header. If the server supports this 93 extension and supports parameters compatible with the client's 94 request, it accepts the use of this extension by the 95 "Sec-WebSocket-Extensions" header in the server's opening handshake. 97 1.1. Physical Connection and Logical Channels 99 Under use of this extension, one transport connection is shared by 100 multiple application-level instances. The WebSocket connection which 101 lies directly on the TCP connection and negotiated this multiplexing 102 extension is called "physical connection". Data channels virtually 103 established by ID tagging are called "logical channels". Control 104 information and data for each WebSocket appplication instances are 105 sent over corresponding logical channels. 107 Data for different logical channels are distinguished by the channel 108 ID allocated in the "Extension data" portion of each frame. 110 The opcode field in the base protocol's framing is used as-is to 111 indicate the type of a frame in transferring data frames of 112 multiplexed connections. Not to confuse intermediaries that don't 113 understand multiplexing extension, multiplex control blocks are used 114 to transfer control frames of multiplexed connections. For example, 115 it's possible that such intermediaries disconnect underlying 116 transport when they see a frame with opcode of close. 118 2. Conformance Requirements 120 All diagrams, examples, and notes in this specification are non- 121 normative, as are all sections explicitly marked non-normative. 122 Everything else in this specification is normative. 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 126 document are to be interpreted as described in RFC2119 [RFC2119]. 128 Requirements phrased in the imperative as part of algorithms (such as 129 "strip any leading space characters" or "return false and abort these 130 steps") are to be interpreted with the meaning of the key word 131 ("must", "should", "may", etc) used in introducing the algorithm. 133 Conformance requirements phrased as algorithms or specific steps MAY 134 be implemented in any manner, so long as the end result is 135 equivalent. (In particular, the algorithms defined in this 136 specification are intended to be easy to follow, and not intended to 137 be performant.) 139 3. Interaction with other Extensions / Framing Mechanisms 141 If any extension (e.g. compression) is placed before this extension 142 in the "Sec-WebSocket-Extensions" header of the physical connection, 143 that extension is applied to multiplexed connections unless otherwise 144 noted in the extension's spec. 146 If such an extension define fields in the "Extension data", they come 147 after this multiplexing extension's field. 149 If any extension is placed after this extension in the 150 "Sec-WebSocket-Extensions" header of the physical connection, that 151 extension is applied to frames after multiplexing on the sender side, 152 and before demultiplexing on the receiver side unless otherwise noted 153 in the extension's spec. 155 If such an extension define fields in the "Extension data", they come 156 before this multiplexing extension's field. 158 A client MAY request such an extension for both the physical 159 connection and the multiplexed connections by placing extension 160 entries before and after this multiplexing extension. In this case, 161 the server SHOULD reject at least either of them if it's useless to 162 apply the same extension twice. 164 For example, if we have a compression extension called foo-compress, 165 the client sends 167 Sec-WebSocket-Extensions: foo-compress, mux, foo-compress 169 in the client's opening handshake of the physical connection to 170 request use of the compression for both physical and multiplexed 171 connections. Then, the server would send back 173 Sec-WebSocket-Extensions: mux, foo-compress 175 to apply compression after multiplexing, or 177 Sec-WebSocket-Extensions: foo-compress, mux 179 to apply compression to multiplexed connections. 181 3.1. Choosing the point to apply an extension 183 Where to apply a compression extension makes difference to resource 184 consumption and flexibility. Compression algorithms often use some 185 memory to keep its context. Some of compression extensions may keep 186 using the same context for all the frames on the same connection. 188 If such an extension is applied to the physical connection, 189 intermediaries that want to demultiplex or multiplex the connection 190 need to decompress (before demultiplexing) and recompress (before 191 multiplexing again) all the frames. 193 If such an extension is applied to each multiplexed connection, we 194 can control to which channel we apply the compression, so we can 195 avoid applying compression to channels transferring incompressible 196 data. Intermediaries that want to demultiplex can forward 197 Application data field leaving it untouched. However, compressing 198 each multiplexed connection is expensive in terms of memory 199 consumption. 201 4. Multiplexed Connections 203 The multiplexing extension maintains separate logical channels, each 204 of which provides fully the logical equivalent of an independent 205 WebSocket connection, including separate handshake headers. If the 206 multiplexing extension is successfully negotiated, one multiplexed 207 connection is automatically established, and the headers on the 208 opening handshake of the physical connection are automatically taken 209 to mean ones for the multiplexed connection. It's called "Implicitly 210 Opened Connection". It's served by the logical channel with channel 211 ID of 1 which is also implicitly opened on completion of the opening 212 handshake. New channels are added by the client issuing the 213 AddChannelRequest multiplex control block (note that only the client 214 may initiate new WebSocket connections), including any handshake 215 headers which do not have the same value as the client's opening 216 handshake of the physical connection. The server's 217 AddChannelResponse likewise includes any handshake headers which are 218 different from the server's opening handshake of the physical 219 connection (the details of this are TBD, but a simple suggestion for 220 a delta encoding is given below). Channel 0 (control channel) is 221 reserved for multiplex control blocks and does not contain payload 222 data from any multiplexed connection. In interpreting 223 "Sec-WebSocket-Extensions" header for a multiplexed connection, the 224 entry for this multiplexing extension is ignored but is used to 225 adjust parameters for the multiplexed connection. A client which 226 attempts to add a channel to an existing connection that is not 227 accepted by the server SHOULD attempt to open a new underlying 228 connection and open a new WebSocket connection on it. 230 If any inconsistency is found between the "Sec-WebSocket-Extensions" 231 header for the physical connection and one for a multiplexed 232 connection (after decoding header compression), a server MUST reject 233 the AddChannelRequest, and a client MUST _Fail the Physical 234 Connection_. 236 Once the multiplexing extension is negotiated on a connection, all 237 frames must be prefixed with a channel ID number in the "Extension 238 data". Channel ID is assigned by client on issuing 239 AddChannelRequest. Control frames with a channel ID 0 refer to the 240 physical connection. Control frames of multiplexed connection MUST 241 be delivered by EncapsulatedControlFrame multiplex control block. 242 Control frames with non-zero channel ID MUST NOT be sent. Control 243 frames SHOULD be sent only on channel 0 where 245 A receiver MAY process frames for different non-control logical 246 channels in parallel. A receiver MUST process frames for the control 247 channel exclusively. 249 A receiver MUST _Fail the Physical Connection_ if any of these rules 250 are violated by the sender. 252 5. Flow Control 254 Each logical channel with non-zero ID, including one created for 255 "Implicitly Opened Connection" is given a value called send quota. 256 The send quota limits the number of bytes in "Payload data" that the 257 endpoint may transmit. As the endpoint transmits frames, the 258 corresponding send quota is consumed by the number of bytes in 259 "Payload data" portion of the frames. It is illegal to send a frame 260 with "Payload data" larger than the remaining send quota. The 261 receiver MUST _Fail the Logical Channel_ for any sender that does so. 262 The send quota is replenished by FlowControl multiplex control blocks 263 sent by the receiver as it processes received data. 265 "quota" extension parameter sent by the other peer specifies the 266 initial send quota. It defaults to 64KiB if the parameter is not 267 specified. The client and server each MAY specify the "quota" 268 parameter and these are unrelated -- each specifies the initial send 269 quota of the other peer for the logical channel. The "quota" value 270 in the opening handshakes of the physical connection applies to the 271 logical channel for "Implicitly Opened Connection". The "quota" 272 value in the handshake attached to AddChannelRequest and 273 AddChannelResponse multiplex control block apply to the logical 274 channel opened by them. 276 Until a client receives an AddChannelResponse in reply to the sent 277 AddChannelRequest, the send quota of the logical channel is 0. When 278 it receives the AddChannelResponse, the send quota is initialized to 279 the initial send quota. When a server receives an AddChannelRequest 280 and decides to accept it, the send quota of the logical channel is 281 initialized to the initial send quota. 283 On client side, the send quota of the logical channel for "Implicitly 284 Opened Connection" is 0 until the client receives the server's 285 opening handshake of the physical connection. It's initialized to 286 the initial send quota when the client receives the handshake. On 287 server side, the send quota of the logical channel for "Implicitly 288 Opened Connection" is initialized to the initial send quota when the 289 server receives the client's opening handshake of the physical 290 connection and decides to accept it. 292 6. Framing 294 If the extension is successfully negotiated during the opening 295 handshake, all frames have a channel ID in the "Extension data". The 296 channel ID is encoded as a variable number of bytes, as follows: 298 0 1 2 3 4 5 6 7 299 +-+-------------+ 300 |0|Channel ID(7)| 301 +-+-------------+ 303 0 1 304 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 305 +-+-+---------------------------+ 306 |1|0| Channel ID (14) | 307 +-+-+---------------------------+ 309 0 1 2 310 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 311 +-+-+-+-----------------------------------------+ 312 |1|1|0| Channel ID (21) | 313 +-+-+-+-----------------------------------------+ 315 0 1 2 3 316 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 317 +-+-+-+---------------------------------------------------------+ 318 |1|1|1| Channel ID (29) | 319 +-+-+-+---------------------------------------------------------+ 321 The base spec requires that a sequence of frames on the wire be a 322 sequence of valid fragments (or one of valid unfragmented frames). 323 The multiplexing extension relaxes this requirement to be for just 324 frames of one logical channel, and that frames of other logical 325 channels may be interleaved arbitrarily. 327 All frames with a non-zero channel ID MUST be delivered to the 328 corresponding multiplexed connection in the order they are received, 329 though fragmentation may be changed if appropriate. Control frames 330 with a non-zero channel ID may also trigger additional processing by 331 the multiplexing extension. 333 Intermediaries MAY fragment or defragment frames with the same 334 channel ID as far as they maintain resulting frames prefixed with one 335 valid channel ID. When multiple frames are defragmented into one 336 frame, channel ID field for second and later frames MUST be removed. 337 Frames MUST NOT be defragmented if there's any frame with channel ID 338 of 0 between them. When a frames is fragmented into multiple frames, 339 all the resulting fragments MUST prefixed with the channel ID. 341 Control frames with a channel ID of 0 refer to the physical 342 connection, and may also trigger additional processing - for example, 343 a close frame on the physical connection will close all logical 344 channels as well (details TBD). 346 If a frame doesn't contain valid channel ID, _Fail the Physical 347 Connection_. The cases where it's considered that the channel ID is 348 invalid are: 350 o The "Payload data" portion doesn't contain a complete channel ID. 352 o No channel has been opened for the channel ID. 354 o The channel has been closed and not reopened. 356 7. Multiplex Control Blocks 358 Binary frames with a channel ID of 0 contain zero or more multiplex 359 control blocks in "Payload data". If possible, putting multiple 360 control blocks into one WebSocket message saves framing overhead. 361 Unless another negotiated extension defines a meaning for them, 362 endpoints MUST NOT send any data frame with an opcode other than 363 "binary frame" on the control channel. If an endpoint received such 364 frame, it MUST _Fail the Physical Connection_. 366 Multiplex control blocks are sent in data frames, so they can be 367 fragmented and interleaved with other logical channels. Processing 368 of multiplex control blocks MUST be done when the entire message 369 containing them is received (and the original data become available 370 after decoding if any encoding is applied to the "Payload data" 371 portion). 373 Control blocks has fields as follows: 375 0 1 2 3 4 5 6 7 376 +---------------+ 377 | Objective | 378 : channel ID : 379 | (8-32 bit) | 380 +-----+---------+ 381 | Opc | | 382 +-----+ : 383 | Opc specific : 384 : data : 385 | | 386 +---------------+ 388 Objective channel ID 390 The channel ID of the logical channel objective to this operation. 391 Encoding is the same as one used in the extension data (designated 392 as control channel). 394 Opc 396 A multiplex control opcode as defined in the following 397 subsections. Opc of 5-7 are Reserved for future use (TBD: do we 398 need some support for quiescence?). 400 Opc specific data 402 Data interpreted according to that opcode. 404 Each of the following subsections describes one multiplex control 405 opcode and how to interpret opc specific data for that opcode. 407 If any incomplete multiplex control block is found, the endpoint MUST 408 _Fail the Physical Connection_. 410 7.1. AddChannelRequest 412 AddChannelRequest is used to create the objective channel, as if a 413 new connection were received on a separate transport connection, 414 except for the encoding of the headers. Multiplex control opcode of 415 AddChannelRequest is 0. AddChannelRequest is sent only from clients. 416 AddChannelRequest has fields as follows: 418 0 1 2 3 4 5 6 7 419 +-+-+-+-+---+---+ 420 |0|0|0|R|Enc|Len| 421 +-+-+-+-+---+---+ 422 |Size of encoded| 423 :handshake : 424 |(8-32 bit) | 425 +---------------+ 426 |Encoded | 427 :handshake : 428 | | 429 +---------------+ 431 R 433 Reserved for future use. 435 Len 437 The size of the size of encoded handshake field in bytes minus 1. 439 Enc 441 Encoding scheme type: 443 0 - identity 445 The handshake data that follow are sent as-is without any 446 special encoding or compression applied, and constitute the 447 complete set of a Request-Line and headers that would have been 448 sent on a WebSocket opening handshake. 450 1 - delta-encoded 452 The handshake data that follow are delta-encoded, where any 453 header that is not given is assumed to have the same value as 454 that given on the current delta base handshake data. The delta 455 base is initially the client's opening handshake of the 456 physical connection. Every time, an AddChannelRequest with its 457 Enc equals to identity is received, the delta base is updated 458 to the handshake in the AddChannelRequest. The only exceptions 459 are the Request-Line and the "Sec-WebSocket-Extensions" header. 460 The Request-Line MUST be sent even if it's the same as one in 461 the delta base. If the "Sec-WebSocket-Extensions" header is 462 not given, its value is assumed to be the extension entry for 463 this multiplexing extension and ones follow it in in the delta 464 base. A header with an empty value means that header is not 465 inherited from the delta base. When to send valueless headers, 466 identity encoding MUST be used. 468 2-3 - reserved 470 Reserved for future use. 472 Size of encoded handshake 474 The size of the following encoded handshake field in bytes in 475 network byte order. 477 Encoded handshake 479 The client's opening handshake as defined in Section 4 of RFC 6455 480 [RFC6455] for the new multiplexed connection. This field is 481 encoded as defined in the description for the Enc field. The 482 complete set of a Request-Line and headers after decoding is 483 treated exactly as if it was sent on a separate connection. 485 If there's already a logical channel with the same channel ID as one 486 specified in this AddChannelRequest, it MUST _Fail the Physical 487 Connection_. Once the server receives an AddChannelRequest, it MUST 488 decide whether to accept or reject the request. To accept the 489 request, it MUST create a new logical channel with the channel ID set 490 to the objective channel ID field of the AddChannelRequest. 492 Channel ID assignment is done by the client. Client MAY use any 493 algorithm to choose channel IDs for new channels. Note that channel 494 ID assignment might be changed by intermediaries, so it's not 495 guaranteed that the value of channel ID is the same on the other 496 peer. 498 The server MUST respond to the request with an AddChannelResponse, 499 described below. 501 The same limit on simultaneous opening handshake as specified in 502 Section 4.1 of [RFC6455] is applied to AddChannelRequests for 503 multiplexed channels. 505 Different from non-multiplexed WebSocket connection, a client MAY 506 send frames of multiplexed connections except for "Implicitly Opened 507 Connection" before receiving AddChannelResponse as far as there's 508 sufficient send quota. In case the AddChannelRequest fails, those 509 frames are ignored by the other peer. This doesn't mean that users 510 of this protocol such as the WebSocket API are required to allow 511 their users to send frames before receiving the server's opening 512 handshake. 514 7.2. AddChannelResponse 516 AddChannelResponse is sent in response to the AddChannelRequest. 517 Multiplex control opcode of the AddChannelResponse is 1. 518 AddChannelResponse is sent only from servers. AddChannelResponse has 519 fields as follows: 521 0 1 2 3 4 5 6 7 522 +-+-+-+-+---+---+ 523 |0|0|1|F|Enc|Len| 524 +-+-+-+-+---+---+ 525 |Size of encoded| 526 :handshake : 527 |(8-32 bit) | 528 +---------------+ 529 |Encoded | 530 :handshake : 531 | | 532 +---------------+ 534 F 536 If F is set, then the server has rejected the AddChannelRequest 537 and this SHOULD be treated exactly the same as if a separate 538 connection was attempted and the opening handshake failed. Enc 539 MUST be set to identity in this case, and encoded handshake field 540 MUST contain the response to an HTTP Upgrade request for the 541 request made by the AddChannelRequest, For example: 543 HTTP/1.1 404 Not found 545 404 message body... 547 If F is not set, then the server has accepted the 548 AddChannelRequest. 550 Len 552 The size of the size of encoded handshake field in bytes minus 1. 554 Enc 556 Encoding scheme type the same as defined for the AddChannelRequest 557 opcode (but replacing "AddChannelRequest" with 558 "AddChannelResponse", and "Request-Line" with "Response-Line"). 560 Size of encoded handshake 562 The size of the following encoded handshake field in bytes in 563 network byte order. 565 Encoded handshake 567 The server's opening handshake as defined in Section 4 of RFC 6455 568 [RFC6455] for this multiplexed connection. This field is encoded 569 according to Enc. The complete set of a Response-Line and headers 570 after decoding is treated exactly as if it was received in 571 response to a client's opening handshake on a separate connection. 573 If the server's opening handshake is validated, the client MUST take 574 this as _The WebSocket Connection is Established_. 576 7.3. FlowControl 578 FlowControl is used to replenish the other peer's send quota for each 579 logical channel. Multiplex control opcode of FlowControl is 2. 580 FlowControl has fields as follows. 582 0 1 2 3 4 5 6 7 583 +-+-+-+-----+---+ 584 |0|1|0| RSV |Len| 585 +-+-+-+-----+---+ 586 |Replenished | 587 :quota : 588 |(8-32 bit) | 589 +---------------+ 591 RSV 593 Reserved for future use. 595 Len 597 The size of replenished quota field in bytes minus 1. 599 Replenished quota 601 An unsigned integer in network byte order added to the quota of 602 the number of bytes the receiver can have outstanding towards the 603 sender of the FlowControl message. (TBD: is it worth having some 604 non-linear encoding to reduce the average bits required to 605 represent these values?) 607 7.4. DropChannel 609 DropChannel is used to close a logical channel. Multiplex control 610 opcode of DropChannel is 3. DropChannel has fields as follows: 612 0 1 2 3 4 5 6 7 613 +-+-+-+-+---+---+ 614 |0|1|1|F|RSV|Len| 615 +-+-+-+-+---+---+ 616 |Size of reason | 617 :(8-32 bit) : 618 | | 619 +---------------+ 620 |Reason | 621 : : 622 | | 623 +---------------+ 625 F 627 F is set when this DropChannel is due to multiplexing level error. 628 F is unset when this DropChannel is sent because the multiplexed 629 connection is asked to _Close the WebSocket Connection_, and the 630 reason field MUST be empty for this case. 632 RSV 634 Reserved for future use. 636 Len 638 The size of the size of reason field in bytes minus 1. 640 Size of reason 642 The size of the reason field in bytes in network byte order. 644 Reason 646 The reason of closure. 648 When an endpoint received DropChannel, the endpoint MUST remove the 649 logical channel and the application instance that used the logical 650 channel MUST treat this as closure of underlying transport. Once a 651 logical channel is removed by the DropChannel request, the channel ID 652 of the logical channel becomes available again for AddChannelRequest. 654 7.5. EncapsulatedControlFrame 656 EncapsulatedControlFrame is used to transfer control frames of 657 multiplexed connections. Multiplex control opcode of 658 EncapsulatedControlFrame is 4. 660 0 1 2 3 4 5 6 7 661 +-+-+-+---------+ 662 |1|0|0| RSV | 663 +-+-+-+---------+ 664 |Encapsulated | 665 :frame : 666 | | 667 +---------------+ 669 RSV 671 Reserved for future use. 673 Encapsulated frame 675 One encapsulated control frame including the original WebSocket 676 header. MASK bit in the encapsulated control frame MUST be unset 677 and the "Payload data" in it MUST be unmasked. 679 When an endpoint received EncapsulatedControlFrame, the endpoint MUST 680 treat the control frame encapsulated in it as one received for the 681 corresponding multiplexed channel. 683 8. Examples 685 _This section is non-normative._ 687 The examples below assume the handshake has already completed and the 688 mux extension was negotiated. 690 01 06 01 "Hello" 81 04 02 "bye" 80 07 01 " world" 692 This is a fragmented text message of "Hello world" on channel 1 693 interleaved with a text message of "bye" on channel 2. Note that 694 the sequence of opcodes/FIN bits cannot be understood without 695 considering the channel ID of each frame. 697 9. Client Behavior 699 When a client is asked to _Establish a WebSocket Connection_ by some 700 WebSocket application instance, it MAY choose to reuse an existing 701 WebSocket connection if all of the following are true: 703 o the multiplexing extension was successfully negotiated on that 704 connection 706 o the scheme portions of the URIs match exactly 708 o the host portions of the URIs either match exactly or resolve to 709 the same IP address (TBD: consider DNS rebind attacks) 711 o the port portions of the URIs (either explicit or implied by the 712 scheme) match exactly 714 o the connection has an availablle logical channel ID 716 If the client chooses to reuse an existing multiplexed connection, it 717 sends an AddChannelRequest as described above. If the 718 AddChannelRequest is accepted, WebSocket frames may be sent over that 719 channel as normal. If the server rejects the AddChannel, the client 720 SHOULD attempt to open a new physical WebSocket connection (for 721 example, in a shared hosting environment a server may not be prepared 722 to multiplex connections from different customers despite having a 723 single IP address for them). 725 10. Buffering 727 There will be lots of small frames sent in this protocol 728 (particularly replenishing send quotas), so a sender SHOULD attempt 729 to aggregate multiplex control blocks into larger WebSocket frames. 730 For data frames, a sender also SHOULD attempt to aggregate fragments 731 into one packet of the underlying transport. However, care must be 732 taken to avoid introducing excessive latency - the exact heuristics 733 for delaying in order to aggregate blocks is TBD. 735 11. Fairness 737 A multiplexing implementation MUST ensure reasonable fairness among 738 the logical channels. This is accomplished in several ways: 740 Receiver side 742 o The receiver MAY limit the send quota of a logical channel by not 743 replenishing it to make sure that any logical channel doesn't 744 dominate the connection. 746 o Send quota for one logical channel SHOULD be determined 747 considering the processing capacity (buffer size, processing 748 power, throughput, etc.) of that logical channel. For example, 749 when a logical channel with excess load cannot drain data from the 750 connection smoothly, the other logical channels get stuck even 751 when they have room of processing capacity. Unless there's 752 special need to give such a big quota for the channel, such 753 condition just makes overall performance low. 755 Sender side 757 o The sender MUST use a fair mechanism for selecting which logical 758 channel's data to send in the next WebSocket frame. Simple 759 implementations may choose a round-robin scheduler, while more 760 advanced implementations may adjust priority based on the amount 761 or frequency of data sent by each logical channel. 763 o The sender MUST fragment a large message into smaller frames to 764 prevent a large message in a logical channel occupying the 765 physical connection and thus delaying messages in other logical 766 channels. 768 12. Proxies 770 Proxies which do not multiplex/demultiplex are not affected by the 771 presence of this extension -- they simply process WebSocket frames as 772 usual. Proxies which filter or monitor WebSocket traffic will need 773 to understand the multiplexing extension in order to extract the data 774 from logical connections or to terminate individual logical 775 connections when policy is violated. Proxies which actively 776 multiplex connections or demultiplex them (for example, a mobile 777 network might have a proxy which aggregates WebSocket connections at 778 a single cell to conserve bandwidth to the main gateway) will require 779 additional configuration (perhaps including the client) that is 780 outside the scope of this document. 782 13. Nesting 784 TBD: Should we allow nesting of multiplexed channels, or should we 785 require that an intermediary multiplexing channels flatten it? The 786 advantage of nesting is it is conceptually cleaner and less work for 787 an intermediary, while the disadvantage is that flow control messages 788 will get amplified by nesting and the ultimate server's job is a bit 789 more complicated to keep a tree of channel mappings. 791 14. Timeout 793 When all the logical channels are closed, each endpoint MAY _Start 794 the WebSocket Closing Handshake_ on the physical connection. Such 795 _Start the WebSocket Closing Handshake_ operation SHOULD be delayed 796 assuming the physical connection may be reused after some idle 797 period. 799 15. Close the Logical Channel 801 To _Close the Logical Channel_, an endpoint MUST send a DropChannel 802 multiplex control block with F bit unset. The endpoint MAY provide 803 the reason of failure in the DropChannel block. 805 16. Fail the Logical Channel 807 To _Fail the Logical Channel_, an endpoint MUST send a DropChannel 808 multiplex control block with F bit set. The endpoint MAY provide the 809 reason of failure in the DropChannel block. 811 17. Fail the Physical Connection 813 To _Fail the Physical Connection_, an endpoint MUST send a 814 DropChannel multiplex control block with objective channel ID of 0 815 and F bit set, and then _Fail the WebSocket Connection_ on the 816 physical connection with status code of 1002 (TBD). 818 18. Operations and Events on Multiplexed Connection 820 When an endpoint is asked to perform any operation defined in the 821 WebSocket Protocol except for _Close the WebSocket Connection_ by 822 some application instance, the endpoint MUST perform the operation on 823 the corresponding logical channel. If the operation involves control 824 frames, they MUST be encapsulated in EncapsulatedControlFrame 825 multiplex control blocks. 827 Any event on a logical channel except for _The WebSocket Connection 828 is Closed_, MUST be taken as one for the corresponding application 829 instance. 831 When an endpoint is asked to do _Close the WebSocket Connection_ by 832 some application instance, it MUST perform _Close the Logical 833 Channel_ on the corresponding logical channel. 835 When a DropChannel is received, or the physical connection is closed, 836 it MUST be taken as _The WebSocket Connection is Closed_ event for 837 the corresponding application instance(s). 839 What to set to _Extension In Use_ for each multiplexed connection is 840 TBD. 842 19. Security Considerations 844 To protect a server from denial-of-service attack, implementation 845 SHOULD have a way to limit the number of concurrent logical channels. 847 TBD 849 20. IANA Considerations 851 This specification is registering a value of the Sec-WebSocket- 852 Extension header field in accordance with Section 11.4 of the 853 WebSocket protocol [RFC6455] as follows: 855 Extension Identifier 857 mux 859 Extension Common Name 861 Multiplexing Extension for WebSockets 863 Extension Definition 865 This document 867 Known Incompatible Extensions 869 None 871 21. Normative References 873 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 874 Requirement Levels", BCP 14, RFC 2119, March 1997. 876 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 877 RFC 6455, December 2011. 879 Authors' Addresses 881 John A. Tamplin 882 Google, Inc. 884 Email: jat@google.com 886 Takeshi Yoshino 887 Google, Inc. 889 Email: tyoshino@google.com