Internet DRAFT - draft-yoshino-wish
draft-yoshino-wish
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,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC
6455, DOI 10.17487/RFC6455, December 2011,
<http://www.rfc-editor.org/info/rfc6455>.
[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,
<http://www.rfc-editor.org/info/rfc7231>.
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 10
.17487/RFC7540, May 2015,
<http://www.rfc-editor.org/info/rfc7540>.
[RFC7692] Yoshino, T., "Compression Extensions for WebSocket", RFC
7692, DOI 10.17487/RFC7692, December 2015,
<http://www.rfc-editor.org/info/rfc7692>.
9.2. Non-normative References
[SSE] WHATWG, "HTML Living Standard - Server-sent events", May
2017, <https://html.spec.whatwg.org/multipage/comms.html
#server-sent-events>.
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, <https://github.com/bidiweb/bidiweb-semantics/blob/
master/SurveyOfProtocolGaps.md>.
[TransportAbstraction]
Zhu, W., "http-transport-abstraction", July 2016,
<https://github.com/bidiweb/http-transport-abstraction>.
[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]
