idnits 2.17.1 draft-yoshino-wish-03.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 (May 10, 2017) is 2543 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: November 11, 2017 May 10, 2017 7 WiSH: A General Purpose Message Framing over Byte-Stream Oriented Wire 8 Protocols (HTTP) 9 draft-yoshino-wish-03 11 Abstract 13 This document defines a general purpose message framing named WiSH 14 which supports bi-directional (bidi) message-based communication over 15 byte-stream oriented protocols such as HTTP (in its standard 16 semantics). WiSH is designed to be compatible with WebSocket. WiSH 17 can be viewed as a binary and bidi alternative to the framing defined 18 for the server-sent events (SSE, EventSource) Web API [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 November 11, 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 . . . . . . . . . . 3 57 4. WiSH Protocol . . . . . . . . . . . . . . . . . . . . . . . . 4 58 5. Framing . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 6. Using WiSH over HTTP . . . . . . . . . . . . . . . . . . . . 5 60 7. WebSocket Compatibility Consideration . . . . . . . . . . . . 5 61 7.1. Valid UTF-8 Requirement . . . . . . . . . . . . . . . . . 5 62 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 63 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 64 9.1. Normative References . . . . . . . . . . . . . . . . . . 6 65 9.2. Non-normative References . . . . . . . . . . . . . . . . 6 66 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7 68 1. Introduction 70 The WebSocket protocol was proposed to provide native client-server 71 bidi messaging for the Web. It has been implemented and deployed 72 widely, but there are still missing semantics and features. See 73 [BidiwebSurvey]. 75 WiSH is a general purpose message framing for use over the standard 76 HTTP semantics to provide bidi messaging semantics. WiSH stands for 77 Web in Strict HTTP. 79 The communication protocol providing the standard HTTP semantics can 80 be HTTP/1.1 [RFC7231], HTTP/2 [RFC7540], HTTP/2 + QUIC [QUIC], or any 81 future protocols. Wire protocol features such as multiplexing, 82 session priority, etc. are provided by the underlying protocol 83 [TransportAbstraction]. Unlike HTTP/2, HTTP/1.1 doesn't specify if 84 earlier 2xx responses are allowed [RFC7540]. Therefore, when 85 HTTP/1.1 is used as the underlying protocol, full-duplex 86 communication may be broken if the client, server or any intermediary 87 chooses to buffer or reject earlier 2xx responses. Since 88 intermediaries may buffer response bodies, bidi communication over 89 WiSH may experience extra latency compared to WebSocket. When HTTPS 90 is used, response body buffering by intermediaries is less likely to 91 happen. 93 The wire protocol features of WebSocket, such as handshake or control 94 messages, are all dropped. WiSH respects the semantics of the 95 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 bidi communication over HTTP and for Web and Internet 102 clients. 104 2. Background 106 There has been several attempts to improve bidi message-based 107 communication on the Web. 109 The server-sent events (SSE) [SSE] realized message-based 110 communication in the server-to-client direction, by introducing a new 111 Web API and a special message framing format while using HTTP as the 112 wire protocol. Except for the issue of possible buffering by 113 intermediaries, SSE works well with existing intermediaries and 114 frameworks that support HTTP. 116 WebSocket realized bidi message-based communication by introducing 117 both a new Web API and a new wire protocol. Because the wire 118 protocol is incompatible with HTTP, intermediaries and frameworks 119 have to be upgraded to understand the wire protocol to support 120 WebSocket. 122 In parallel to the development of WebSocket, HTTP has been greatly 123 improved with HTTP/2. There are more improvements upcoming to the 124 HTTP e.g. QUIC. 126 It's desirable that normal HTTP traffic and bidi message-based 127 communication on the Web share further evolution to reduce cost of 128 development and standardization. Bidi message-based communication on 129 the Web should be multiplexed with normal HTTP traffic and should 130 benefit from future transport-level improvements such as QUIC. 132 WiSH is designed based on the above analysis. Use of the standard 133 HTTP semantics as-is reduces cost and makes the Web simpler. 135 3. Conformance Requirements and Terminology 137 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 138 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 139 document are to be interpreted as described in [RFC2119]. 141 Requirements phrased in the imperative as part of algorithms (such as 142 "strip any leading space characters" or "return false and abort these 143 steps") are to be interpreted with the meaning of the key word 144 ("MUST", "SHOULD", "MAY", etc.) used in introducing the algorithm. 146 Conformance requirements phrased as algorithms or specific steps can 147 be implemented in any manner, so long as the end result is 148 equivalent. In particular, the algorithms defined in this 149 specification are intended to be easy to understand and are not 150 intended to be performant. 152 4. WiSH Protocol 154 WiSH frames messages over an HTTP request body or response body using 155 the framing defined in Section 5. 157 The "Content-Type" header value of the underlying HTTP request or 158 response message for which WiSH is used MUST be "application/web- 159 stream". 161 5. Framing 163 0 1 2 3 164 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 165 +-+-+-+-+-------+-+-------------+-------------------------------+ 166 |F|C|0|0|opcode |0|Payload |Extended payload length | 167 |I|M| | |4 bit | |length |16 bit if payload length is 126| 168 |N|P| | | | |7 bit |64 bit if payload length is 127| 169 +-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - + 170 | | 171 + - - - - - - - - - - - - - - - +-------------------------------+ 172 | |Payload Data | 173 +-------------------------------+ - - - - - - - - - - - - - - - + 174 | | 175 +---------------------------------------------------------------+ 177 WiSH is compatible with the framing of the WebSocket protocol 178 [RFC6455]. 180 The opcode field indicates how to interpret the payload data field. 181 WiSH uses the following opcodes. 183 o %x0 denotes a continuation frame 185 o %x1 denotes the initial frame of a text message 187 o %x2 denotes the initial frame of a binary message 189 o %x3 denotes the initial frame of a text metadata message 191 o %x4 denotes the initial frame of a binary metadata message 193 Any values not listed here are reserved. 195 The FIN bit together with the continuation frame opcode, payload 196 length and extended payload length work in the same way as the 197 WebSocket protocol to represent messages. The fragmentation 198 mechanism allows for flushing part of a large message payload without 199 waiting for the total size of the message to be determined. 201 The CMP bit indicates whether the message is compressed. The CMP bit 202 of the first frame MUST be set to 1 when compression is enabled for 203 the message. Otherwise, it MUST be set to 0. The CMP bit of non- 204 first frames MUST be always set to 0. 206 The message type distinction by the opcode field (text and binary) is 207 kept to allow better Web support. 209 The two metadata opcodes can be used for exchanging metadata e.g. 210 using messages with opcode set to %x3 with metadata encoded in JSON 211 in its payload field. 213 The status code and status reason defined in the WebSocket protocol 214 are dropped. 216 The ping and pong control message of the WebSocket protocol are 217 dropped. If such a feature is needed, it should be provided by 218 underlying protocols. 220 The permessage-deflate extension [RFC7692] is defined for the 221 WebSocket protocol, to add a compression mechanism to it. The 222 permessage-deflate extension can be applied to WiSH. The details are 223 to be specified. 225 What contents are exchanged and in what encoding they are exchanged 226 over WiSH are to be defined by the application layer. 228 6. Using WiSH over HTTP 230 The standard HTTP (REST) semantics should be followed, especially the 231 choice of the HTTP method. Some HTTP semantics may not be 232 applicable, e.g. the "Cache-Control" header, when the body is 233 streamed. However, such limitation is not specific to WiSH. 235 7. WebSocket Compatibility Consideration 237 7.1. Valid UTF-8 Requirement 239 In RFC6455, endpoints are required to _Fail the WebSocket Connection_ 240 when they find that the byte stream in a text message is not a valid 241 UTF-8 stream. To conform to the requirement, RFC6455 server 242 frameworks check UTF-8 validness. The contents of text messages of 243 WiSH also MUST be a valid UTF-8 stream. However, WiSH endpoints are 244 not required to check UTF-8 validness. This provides more 245 flexibility to server development. For example, a server may choose 246 to check UTF-8 validness inside a JSON parser. 248 8. Acknowledgements 250 Thank you to the following people for giving feedback to the 251 document: Ben Christensen, Costin Manolache, Kari Hurtta, Loic 252 Hoguin, Roberto Peon, Van Catha. 254 9. References 256 9.1. Normative References 258 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 259 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 260 RFC2119, March 1997, 261 . 263 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 264 6455, DOI 10.17487/RFC6455, December 2011, 265 . 267 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 268 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 269 10.17487/RFC7231, June 2014, 270 . 272 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 273 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 10 274 .17487/RFC7540, May 2015, 275 . 277 [RFC7692] Yoshino, T., "Compression Extensions for WebSocket", RFC 278 7692, DOI 10.17487/RFC7692, December 2015, 279 . 281 9.2. Non-normative References 283 [SSE] WHATWG, "HTML Living Standard - Server-sent events", May 284 2017, . 287 [BidiwebSurvey] 288 Yoshino, T. and W. Zhu, "Non Request-Response 289 Communication over the Web, and What's Missing", January 290 2014, . 293 [TransportAbstraction] 294 Zhu, W., "http-transport-abstraction", July 2016, 295 . 297 [QUIC] Hamilton, R., Iyengar, J., Swett, I., and A. Wilk, "QUIC: 298 A UDP-Based Secure and Reliable Transport for HTTP/2", 299 July 2016. 301 Authors' Addresses 303 Takeshi Yoshino 304 Google, Inc. 306 Email: tyoshino@google.com 308 Wenbo Zhu 309 Google, Inc. 311 Email: wenboz@google.com