Network Working Group T. Yoshino Internet-Draft W. Zhu Intended status: Standards Track Google, Inc. Expires: November 11, 2017 May 10, 2017 WiSH: A General Purpose Message Framing over Byte-Stream Oriented Wire Protocols (HTTP) draft-yoshino-wish-03 Abstract This document defines a general purpose message framing named WiSH which supports bi-directional (bidi) message-based communication over byte-stream oriented protocols such as HTTP (in its standard semantics). WiSH is designed to be compatible with WebSocket. WiSH can be viewed as a binary and bidi alternative to the framing defined for the server-sent events (SSE, EventSource) Web API [SSE]. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on November 11, 2017. Copyright Notice Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of Yoshino & Zhu Expires November 11, 2017 [Page 1] Internet-DrWiSH: A General Purpose Message Framing over Byte- May 2017 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Background . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Conformance Requirements and Terminology . . . . . . . . . . 3 4. WiSH Protocol . . . . . . . . . . . . . . . . . . . . . . . . 4 5. Framing . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 6. Using WiSH over HTTP . . . . . . . . . . . . . . . . . . . . 5 7. WebSocket Compatibility Consideration . . . . . . . . . . . . 5 7.1. Valid UTF-8 Requirement . . . . . . . . . . . . . . . . . 5 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 9.1. Normative References . . . . . . . . . . . . . . . . . . 6 9.2. Non-normative References . . . . . . . . . . . . . . . . 6 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7 1. Introduction The WebSocket protocol was proposed to provide native client-server bidi messaging for the Web. It has been implemented and deployed widely, but there are still missing semantics and features. See [BidiwebSurvey]. WiSH is a general purpose message framing for use over the standard HTTP semantics to provide bidi messaging semantics. WiSH stands for Web in Strict HTTP. The communication protocol providing the standard HTTP semantics can be HTTP/1.1 [RFC7231], HTTP/2 [RFC7540], HTTP/2 + QUIC [QUIC], or any future protocols. Wire protocol features such as multiplexing, session priority, etc. are provided by the underlying protocol [TransportAbstraction]. Unlike HTTP/2, HTTP/1.1 doesn't specify if earlier 2xx responses are allowed [RFC7540]. Therefore, when HTTP/1.1 is used as the underlying protocol, full-duplex communication may be broken if the client, server or any intermediary chooses to buffer or reject earlier 2xx responses. Since intermediaries may buffer response bodies, bidi communication over WiSH may experience extra latency compared to WebSocket. When HTTPS is used, response body buffering by intermediaries is less likely to happen. The wire protocol features of WebSocket, such as handshake or control messages, are all dropped. WiSH respects the semantics of the underlying protocol (as opposed to turning it to a transport protocol). The concept of fragmentation is retained for enabling Yoshino & Zhu Expires November 11, 2017 [Page 2] Internet-DrWiSH: A General Purpose Message Framing over Byte- May 2017 starting message transmission before determining the final length of the message. Application-level protocols may use WiSH as the framing protocol to support bidi communication over HTTP and for Web and Internet clients. 2. Background There has been several attempts to improve bidi message-based communication on the Web. The server-sent events (SSE) [SSE] realized message-based communication in the server-to-client direction, by introducing a new Web API and a special message framing format while using HTTP as the wire protocol. Except for the issue of possible buffering by intermediaries, SSE works well with existing intermediaries and frameworks that support HTTP. WebSocket realized bidi message-based communication by introducing both a new Web API and a new wire protocol. Because the wire protocol is incompatible with HTTP, intermediaries and frameworks have to be upgraded to understand the wire protocol to support WebSocket. In parallel to the development of WebSocket, HTTP has been greatly improved with HTTP/2. There are more improvements upcoming to the HTTP e.g. QUIC. It's desirable that normal HTTP traffic and bidi message-based communication on the Web share further evolution to reduce cost of development and standardization. Bidi message-based communication on the Web should be multiplexed with normal HTTP traffic and should benefit from future transport-level improvements such as QUIC. WiSH is designed based on the above analysis. Use of the standard HTTP semantics as-is reduces cost and makes the Web simpler. 3. Conformance Requirements and Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("MUST", "SHOULD", "MAY", etc.) used in introducing the algorithm. Yoshino & Zhu Expires November 11, 2017 [Page 3] Internet-DrWiSH: A General Purpose Message Framing over Byte- May 2017 Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. 4. WiSH Protocol WiSH frames messages over an HTTP request body or response body using the framing defined in Section 5. The "Content-Type" header value of the underlying HTTP request or response message for which WiSH is used MUST be "application/web- stream". 5. Framing 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-------+-+-------------+-------------------------------+ |F|C|0|0|opcode |0|Payload |Extended payload length | |I|M| | |4 bit | |length |16 bit if payload length is 126| |N|P| | | | |7 bit |64 bit if payload length is 127| +-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - + | | + - - - - - - - - - - - - - - - +-------------------------------+ | |Payload Data | +-------------------------------+ - - - - - - - - - - - - - - - + | | +---------------------------------------------------------------+ WiSH is compatible with the framing of the WebSocket protocol [RFC6455]. The opcode field indicates how to interpret the payload data field. WiSH uses the following opcodes. o %x0 denotes a continuation frame o %x1 denotes the initial frame of a text message o %x2 denotes the initial frame of a binary message o %x3 denotes the initial frame of a text metadata message o %x4 denotes the initial frame of a binary metadata message Any values not listed here are reserved. Yoshino & Zhu Expires November 11, 2017 [Page 4] Internet-DrWiSH: A General Purpose Message Framing over Byte- May 2017 The FIN bit together with the continuation frame opcode, payload length and extended payload length work in the same way as the WebSocket protocol to represent messages. The fragmentation mechanism allows for flushing part of a large message payload without waiting for the total size of the message to be determined. The CMP bit indicates whether the message is compressed. The CMP bit of the first frame MUST be set to 1 when compression is enabled for the message. Otherwise, it MUST be set to 0. The CMP bit of non- first frames MUST be always set to 0. The message type distinction by the opcode field (text and binary) is kept to allow better Web support. The two metadata opcodes can be used for exchanging metadata e.g. using messages with opcode set to %x3 with metadata encoded in JSON in its payload field. The status code and status reason defined in the WebSocket protocol are dropped. The ping and pong control message of the WebSocket protocol are dropped. If such a feature is needed, it should be provided by underlying protocols. The permessage-deflate extension [RFC7692] is defined for the WebSocket protocol, to add a compression mechanism to it. The permessage-deflate extension can be applied to WiSH. The details are to be specified. What contents are exchanged and in what encoding they are exchanged over WiSH are to be defined by the application layer. 6. Using WiSH over HTTP The standard HTTP (REST) semantics should be followed, especially the choice of the HTTP method. Some HTTP semantics may not be applicable, e.g. the "Cache-Control" header, when the body is streamed. However, such limitation is not specific to WiSH. 7. WebSocket Compatibility Consideration 7.1. Valid UTF-8 Requirement In RFC6455, endpoints are required to _Fail the WebSocket Connection_ when they find that the byte stream in a text message is not a valid UTF-8 stream. To conform to the requirement, RFC6455 server frameworks check UTF-8 validness. The contents of text messages of Yoshino & Zhu Expires November 11, 2017 [Page 5] Internet-DrWiSH: A General Purpose Message Framing over Byte- May 2017 WiSH also MUST be a valid UTF-8 stream. However, WiSH endpoints are not required to check UTF-8 validness. This provides more flexibility to server development. For example, a server may choose to check UTF-8 validness inside a JSON parser. 8. Acknowledgements Thank you to the following people for giving feedback to the document: Ben Christensen, Costin Manolache, Kari Hurtta, Loic Hoguin, Roberto Peon, Van Catha. 9. References 9.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ RFC2119, March 1997, . [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 6455, DOI 10.17487/RFC6455, December 2011, . [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014, . [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 10 .17487/RFC7540, May 2015, . [RFC7692] Yoshino, T., "Compression Extensions for WebSocket", RFC 7692, DOI 10.17487/RFC7692, December 2015, . 9.2. Non-normative References [SSE] WHATWG, "HTML Living Standard - Server-sent events", May 2017, . Yoshino & Zhu Expires November 11, 2017 [Page 6] Internet-DrWiSH: A General Purpose Message Framing over Byte- May 2017 [BidiwebSurvey] Yoshino, T. and W. Zhu, "Non Request-Response Communication over the Web, and What's Missing", January 2014, . [TransportAbstraction] Zhu, W., "http-transport-abstraction", July 2016, . [QUIC] Hamilton, R., Iyengar, J., Swett, I., and A. Wilk, "QUIC: A UDP-Based Secure and Reliable Transport for HTTP/2", July 2016. Authors' Addresses Takeshi Yoshino Google, Inc. Email: tyoshino@google.com Wenbo Zhu Google, Inc. Email: wenboz@google.com Yoshino & Zhu Expires November 11, 2017 [Page 7]