idnits 2.17.1 draft-yoshino-wish-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 document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The abstract seems to contain references ([SSE]), 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 (March 29, 2017) is 2584 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) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) Summary: 5 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Yoshino 3 Internet-Draft W. Zhu 4 Intended status: Standards Track Google, Inc. 5 Expires: September 30, 2017 March 29, 2017 7 WiSH: A General Purpose Message Framing over Byte-Stream Oriented Wire 8 Protocols (HTTP) 9 draft-yoshino-wish-02 11 Abstract 13 This document defines a general purpose message framing named WiSH 14 which supports bi-directional message-based communication over byte- 15 stream oriented protocols such as HTTP (in its standard semantics). 16 The WiSH framing is designed to be compatible with WebSocket. You 17 may want to think about WiSH as a binary and bi-directional 18 alternative to the framing defined for the server-sent events [SSE]. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on September 30, 2017. 37 Copyright Notice 39 Copyright (c) 2017 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. Background . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3. Conformance Requirements and Terminology . . . . . . . . . . 4 57 4. WiSH Protocol . . . . . . . . . . . . . . . . . . . . . . . . 4 58 5. Framing . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 6. Using WiSH over HTTP . . . . . . . . . . . . . . . . . . . . 5 60 7. Content Negotiation and WebSocket Compatibility Consideration 5 61 7.1. Subprotocol Negotiation . . . . . . . . . . . . . . . . . 6 62 7.2. Compression Negotiation . . . . . . . . . . . . . . . . . 7 63 7.3. Valid UTF-8 Requirement . . . . . . . . . . . . . . . . . 7 64 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 65 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 9.1. Normative References . . . . . . . . . . . . . . . . . . 8 67 9.2. Non-normative References . . . . . . . . . . . . . . . . 8 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 70 1. Introduction 72 The WebSocket protocol was proposed to provide native client-server 73 bi-directional messaging for the Web. It has been implemented and 74 deployed widely, but there are still missing semantics and 75 functionalities. See [BidiwebSurvey]. 77 WiSH is a message framing format for use over the standard HTTP 78 semantics to provide bi-directional messaging semantics. WiSH stands 79 for Web in Strict HTTP. The communication protocol providing the 80 HTTP semantics can be HTTP/1.1 [RFC7231], HTTP/2 [RFC7540], HTTP/2 + 81 QUIC [QUIC], or any future protocols. Wire-protocol functionalities 82 such as compression, multiplexing, session priority, etc. are 83 provided by the underlying protocol [TransportAbstraction]. Unlike 84 HTTP/2, HTTP/1.1 doesn't specify if earlier 2xx responses are allowed 85 [RFC7540]. Therefore when HTTP/1.1 is used as the underlying 86 protocol, full-duplex communication may be broken if the client, 87 server or any proxy chooses to buffer or reject earlier 2xx 88 responses. Since proxies may buffer response bodies, communication 89 over WiSH may experience extra latency compared to WebSocket. When 90 HTTPS is used, response buffering by proxies is less likely to 91 happen. 93 Wire-protocol features of WebSocket, such as handshake or control 94 messages, are all dropped. The WiSH framing respects the semantics 95 of the underlying protocol (as opposed to turning it to a transport 96 protocol). The concept of fragmentation is retained for enabling 97 starting message transmission before determining the final length of 98 the message. 100 Application-level protocols may use WiSH as the framing protocol to 101 support bi-directional communication over HTTP and for Web and 102 Internet clients. 104 2. Background 106 There has been several attempts to improve bi-directional message- 107 based communication on the Web. 109 The server-sent events [SSE] realized message-based communication in 110 the server-to-client direction, by introducing a new Web API and a 111 special message framing format while using HTTP as the wire protocol. 112 Except for the issue of possible buffering by intermediaries, the 113 server-sent events work well with existing intermediaries and 114 frameworks that support HTTP. 116 WebSocket introduced both a new Web API and a new wire protocol to 117 realize bi-directional message-based communication. Because the wire 118 protocol is incompatible with HTTP, intermediaries and frameworks 119 have to be upgraded to understand the protocol to support WebSocket. 121 In parallel to the development of WebSocket, HTTP has been greatly 122 improved with HTTP/2. There are more improvements upcoming e.g. 123 QUIC to the HTTP. At the same time, the Web APIs for HTTP have also 124 been improved. The XMLHttpRequest is being replaced with the Fetch 125 API [Fetch] which allows for streamed uploading and downloading of 126 the body part of HTTP messages by using the Streams API [Streams]. 127 The Streams API also enables implementing data transfer and various 128 data processing (e.g. compression/decompression, message framing) in 129 the form of the transform stream. The transform stream mechanism is 130 designed to allow for optimizing transfer and processing by 131 offloading some part of them from the JavaScript world. 133 It's desirable that further evolution of bi-directional message-based 134 communication utilize HTTP/2 to reduce cost of development and 135 standardization. Bidi communication should be multiplexed with 136 normal HTTP traffic and should benefit from future transport-level 137 improvements such as QUIC. 139 The WiSH idea is based on the above analysis. Combination of the 140 Fetch API and transform streams enables efficient processing of the 141 WiSH framing. Use of the HTTP semantics as-is reduces cost and makes 142 the Web simpler. Once the WiSH idea is successfully adopted, binding 143 to the WebSocket API could be introduced as further optimization for 144 existing WebSocket users. 146 3. Conformance Requirements and Terminology 148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 150 document are to be interpreted as described in [RFC2119]. 152 Requirements phrased in the imperative as part of algorithms (such as 153 "strip any leading space characters" or "return false and abort these 154 steps") are to be interpreted with the meaning of the key word 155 ("MUST", "SHOULD", "MAY", etc.) used in introducing the algorithm. 157 Conformance requirements phrased as algorithms or specific steps can 158 be implemented in any manner, so long as the end result is 159 equivalent. In particular, the algorithms defined in this 160 specification are intended to be easy to understand and are not 161 intended to be performant. 163 4. WiSH Protocol 165 WiSH frames messages over an HTTP request or response body using the 166 framing defined in Section 5. 168 The "Content-Type" header value of the underlying HTTP request/ 169 response message MUST be "application/web-stream". 171 5. Framing 173 0 1 2 3 174 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 175 +-+-+-+-+-------+-+-------------+-------------------------------+ 176 |F|C|0|0|opcode |0|Payload |Extended payload length | 177 |I|M| | |4 bit | |length |16 bit if payload length is 126| 178 |N|P| | | | |7 bit |64 bit if payload length is 127| 179 +-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - + 180 | | 181 + - - - - - - - - - - - - - - - +-------------------------------+ 182 | |Payload Data | 183 +-------------------------------+ - - - - - - - - - - - - - - - + 184 | | 185 +---------------------------------------------------------------+ 187 WiSH framing is compatible with the framing defined in [RFC6455] for 188 the WebSocket protocol. 190 The opcode field indicates how to interpret the payload data field. 191 WiSH uses the following opcodes. 193 o %x0 denotes a continuation frame 194 o %x1 denotes a text frame 196 o %x2 denotes a binary frame 198 Any values not listed here are reserved. 200 The FIN bit together with the continuation frame opcode, payload 201 length and extended payload length work in the same way as WebSocket 202 to represent frames and messages. The fragmentation mechanism allows 203 for flushing part of a large message payload without waiting for the 204 total size of the message to be determined. 206 The CMP bit indicates whether the message is compressed. The CMP bit 207 of the first frame MUST be set to 1 when compression is enabled for 208 the message. Otherwise, it MUST be set to 0. The CMP bit of non- 209 first frames MUST be always set to 0. 211 The message type distinction by the opcode field (text and binary) is 212 kept to allow better Web support. One of the possible use cases is 213 to use the text type for exchanging metadata encoded in JSON, etc., 214 and the binary type for exchanging non-metadata messages. 216 The status code and status reason defined in the WebSocket protocol 217 are dropped. 219 The ping and pong control message of the WebSocket protocol are 220 dropped. If such a feature is needed, it should be provided by 221 underlying protocols. 223 The permessage-deflate extension [RFC7692] is defined for the 224 WebSocket protocol, to add a compression mechanism to it. No 225 extension mechanism is defined for WiSH. Compression can be 226 implemented by underlying protocols or in the application layer if 227 needed. What contents are exchanged and in what encoding they are 228 exchanged over WiSH are to be defined by the application layer. 230 6. Using WiSH over HTTP 232 Standard HTTP (REST) semantics should be followed, especially the 233 choice of the HTTP method. Some HTTP semantics may not be 234 applicable, e.g. the "Cache-Control" header, when the body is 235 streamed. However, such limitation is not specific to WiSH. 237 7. Content Negotiation and WebSocket Compatibility Consideration 239 In this section, we discuss how to bridge WiSH and WebSocket. 241 The JavaScript binding and wire protocol handshake with WebSocket 242 port is future work. Current thoughts are documented at 243 [BidiwebBinding]. 245 7.1. Subprotocol Negotiation 247 When layered over HTTP, a client and server MAY choose to negotiate a 248 subprotocol (in the WebSocket term) to use by using the standard HTTP 249 "Accept" and "Content-Type" headers. In order to be compatible with 250 RFC6455, a client MAY list offered subprotocols as follows: 252 Accept: application/web-stream; protocol=foo; q=1, 253 application/web-stream; protocol=bar; q=0.5 255 Following the "application/web-stream" media type, a parameter named 256 "protocol" is specified with the subprotocol name as its value. A 257 client offers multiple subprotocols by listing multiple "application/ 258 web-stream" media type with the "protocol" parameter with different 259 values. 261 The client MAY indicate that the media type of the request body is 262 WiSH by using the "Content-Type" header as follows: 264 Content-Type: application/web-stream 266 Where compatibility with WebSocket matters, symmetric subprotocols 267 MUST be used. When multiple subprotocols are offered, a client MUST 268 NOT specify the "protocol" parameter because it's not determined 269 which subprotocol will be chosen by the server until the negotiation 270 is done. When a single subprotocol is offered, a client MAY specify 271 the "protocol" parameter which is the same as the one specified in 272 the "Accept" header. 274 The server chooses one subprotocol from the offered ones and notifies 275 the chosen subprotocol with the "Content-Type" header as follows: 277 Content-Type: application/web-stream; protocol=foo 279 The client SHOULD NOT start streaming any data (with the request 280 body) before the client receives all the response headers from the 281 server, which concludes the negotiation process. 283 Where compatibility with WebSocket doesn't matter, the "Content-Type" 284 header value MAY differ between the HTTP request and HTTP response 285 (see Section 6). This includes a combination of WiSH and non-WiSH 286 media type. 288 7.2. Compression Negotiation 290 When layered over HTTP, a client and server MAY choose to negotiate a 291 compression to use by using the standard HTTP "Accept-Encoding" and 292 "Content-Encoding" headers. A client MAY list offered compression 293 methods as follows: 295 Accept-Encoding: 296 web-stream-deflate; 297 client_max_window_bits; server_max_window_bits=10, q=1, 298 web-stream-deflate; 299 client_max_window_bits; server_max_window_bits; q=0.5 301 Each element in the header value consists of the identifier of the 302 compression method followed by parameters configuring the method. 303 The "web-stream-deflate" compression method in the example shows how 304 the compression algorithm used for the "permessage-deflate" can be 305 configured for the example. This example includes the 306 "client_max_window_bits" for WebSocket compatibility which indicates 307 whether or not the client supports the "client_max_window_bits" 308 parameter. 310 The client MAY indicate use of the compression method for the HTTP 311 request body by using the "Content-Encoding" header as follows: 313 Content-Encoding: web-stream-deflate 315 The server chooses one compression method from the offered ones and 316 notifies the chosen compression method with the "Content-Encoding" 317 header as follows: 319 Content-Encoding: web-stream-deflate 321 The server MAY also choose not to include the "Content-Encoding" 322 header to indicate that it rejects use of any compression method. 324 The client SHOULD NOT start streaming any data (with the request 325 body) before the client receives all the response headers from the 326 server, which concludes the negotiation process. 328 7.3. Valid UTF-8 Requirement 330 In RFC6455, endpoints are required to _Fail the WebSocket Connection_ 331 when they find that the byte stream in a text message is not a valid 332 UTF-8 stream. To conform to the requirement, RFC6455 server 333 frameworks check UTF-8 validness. The contents of text messages of 334 WiSH also MUST be a valid UTF-8 stream. However, WiSH endpoints are 335 not required to check UTF-8 validness. This provides more 336 flexibility to server development. For example, a server may choose 337 to check UTF-8 validness inside a JSON parser. 339 8. Acknowledgements 341 Thank you to the following people for giving feedback to the 342 document: Ben Christensen, Costin Manolache, Kari Hurtta, Loic 343 Hoguin, Roberto Peon, Van Catha. 345 9. References 347 9.1. Normative References 349 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 350 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 351 RFC2119, March 1997, 352 . 354 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 355 6455, DOI 10.17487/RFC6455, December 2011, 356 . 358 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 359 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 360 10.17487/RFC7231, June 2014, 361 . 363 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 364 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 10 365 .17487/RFC7540, May 2015, 366 . 368 [RFC7692] Yoshino, T., "Compression Extensions for WebSocket", RFC 369 7692, DOI 10.17487/RFC7692, December 2015, 370 . 372 9.2. Non-normative References 374 [SSE] WHATWG, "HTML Living Standard", October 2016, 375 . 377 [Fetch] WHATWG, "Fetch Standard", October 2016, 378 . 380 [Streams] WHATWG, "Standard", October 2016, 381 . 383 [BidiwebSurvey] 384 Yoshino, T. and W. Zhu, "Non Request-Response 385 Communication over the Web, and What's Missing", January 386 2014, . 389 [BidiwebBinding] 390 Bidiweb, , "Issue about WiSH JavaScript binding", March 391 2017, . 393 [TransportAbstraction] 394 Zhu, W., "http-transport-abstraction", July 2016, 395 . 397 [QUIC] Hamilton, R., Iyengar, J., Swett, I., and A. Wilk, "QUIC: 398 A UDP-Based Secure and Reliable Transport for HTTP/2", 399 July 2016. 401 Authors' Addresses 403 Takeshi Yoshino 404 Google, Inc. 406 Email: tyoshino@google.com 408 Wenbo Zhu 409 Google, Inc. 411 Email: wenboz@google.com