[Search] [txt|pdfized|bibtex] [Tracker] [Email] [Nits]
Versions: 00                                                            
Network Working Group                                          I. Svirid
Internet-Draft                                          October 18, 2016
Intended status: Informational
Expires: April 21, 2017


                         WebSocket2 over HTTP/2
                 draft-svirid-websocket2-over-http2-00

Abstract

   This document specifies a new protocol called WebSocket2 ontop of
   HTTP/2.  The WebSocket2 protocol enables two-way binary communication
   between a client running untrusted code in a controlled environment
   to a remote host that has opted-in to communications from that code.

   This protocol has little incommon with the WebSocket protocol
   [RFC6455] other than client side API compatibility.

   Please send feedback to the ietf-http-wg@w3.org mailing list.

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 April 21, 2017.

Copyright Notice

   Copyright (c) 2016 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



Svirid                   Expires April 21, 2017                 [Page 1]


Internet-Draft           WebSocket2 over HTTP/2             October 2016


   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Conventions and Terminology . . . . . . . . . . . . . . .   3
   2.  Overview  . . . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.1.  WebSocket2 Protocol . . . . . . . . . . . . . . . . . . .   3
   3.  Handshake . . . . . . . . . . . . . . . . . . . . . . . . . .   3
     3.1.  Client Handshake Request  . . . . . . . . . . . . . . . .   3
     3.2.  Server Handshake Reply  . . . . . . . . . . . . . . . . .   4
       3.2.1.  Handshake Error Reasons . . . . . . . . . . . . . . .   5
     3.3.  Post Handshake  . . . . . . . . . . . . . . . . . . . . .   5
   4.  Data Framing  . . . . . . . . . . . . . . . . . . . . . . . .   5
     4.1.  Text Frame  . . . . . . . . . . . . . . . . . . . . . . .   6
     4.2.  Binary Frame  . . . . . . . . . . . . . . . . . . . . . .   6
     4.3.  Error Frame . . . . . . . . . . . . . . . . . . . . . . .   6
       4.3.1.  Error Frame Codes . . . . . . . . . . . . . . . . . .   7
   5.  VarSize . . . . . . . . . . . . . . . . . . . . . . . . . . .   8
   6.  Compression . . . . . . . . . . . . . . . . . . . . . . . . .   8
     6.1.  LZ4 Compressed Payload  . . . . . . . . . . . . . . . . .   8
     6.2.  Deflate Compressed Payload  . . . . . . . . . . . . . . .   8
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   9
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .   9
     7.2.  Informative References  . . . . . . . . . . . . . . . . .   9
   Appendix A.  Acknowledgements . . . . . . . . . . . . . . . . . .   9
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   9

1.  Introduction

   You can read about why two way data streaming is important from the
   introduction to WebSockets in RFC6455 Section 1
   <https://tools.ietf.org/html/rfc6455#section-1>.

   WebSocket2 over HTTP/2 is a protocol ontop HTTP/2 designed for modern
   times.  Previous WebSocket client side API will be fully backward
   compatible with WebSocket2.

   In this document, we describe WebSocket2 and how to layer WebSocket2
   semantics onto HTTP/2 semantics by defining detailed mapping,
   replacement of operations and events.







Svirid                   Expires April 21, 2017                 [Page 2]


Internet-Draft           WebSocket2 over HTTP/2             October 2016


1.1.  Conventions 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 RFC 2119 [RFC2119].

2.  Overview

   WebSocket2 is functionally equivalent to binary streaming between a
   sandboxed client and inexplicit host, but layered on top of HTTP2.

   Key advantages of WebSocket2 over WebSocket:

   o No masking

   o Simpler handshake and negotiation

   o Lz4 compression method

   Key advantages of WebSocket2 over HTTP/2 include:

   o Two-way real time communication

   o Server push and delivery without client request

   o Binary transmission

2.1.  WebSocket2 Protocol

   The protocol has two main parts, the handshake and data transfer.
   Data transmitted using WebSocket2 supports compression.

3.  Handshake

   The main job of the handshake is to request authority and if granted
   by the server, to negotiate a compression medium.

3.1.  Client Handshake Request

   The client MUST use the :method GET.

   The client MUST send a sec-ws2-version header that MUST specify the
   websocket2 version being used.

   The client MAY send a sec-ws2-compression header that advertises the
   compression methods the client supports.  Valid key value pairs
   include:




Svirid                   Expires April 21, 2017                 [Page 3]


Internet-Draft           WebSocket2 over HTTP/2             October 2016


   o lz4=1-9;
       * This client supports lz4 with compression levels from 1 to 9

   o lz4=1;
       * This client supports lz4 with compression levels 1

   o deflate=8-15;
       * This client supports deflate with sliding window bits from 8-15

   Duplicate keys MUST NOT be present.

   The client MUST NOT set the END_STREAM flag when sending the headers.

   A client handshake request may look like:

                :method: GET
                :scheme: wss
                :authority: example.org
                :path: /demo
                sec-ws2-version: 1
                sec-ws2-compression: lz4=1-9; deflate=8-15;

3.2.  Server Handshake Reply

   END_STREAM on the HTTP/2 Header frame MUST only be set in the case of
   rejection.

   The server MUST send ONLY ONE of the advertised compression methods
   or exclude the sec-ws2-compression header from the response,
   signaling that no compression will be used.

   The server MUST include the sec-ws2-error header in the reply with an
   outlined error reason.

   A successful server handshake reply may look like:

                        :status: 200
                        sec-ws2-compression: lz4=1;
                        sec-ws2-error: success

   This signals that the server chose to use lz4 with a compression
   level of 1.  Now both the client and server MUST use only this
   compression method.








Svirid                   Expires April 21, 2017                 [Page 4]


Internet-Draft           WebSocket2 over HTTP/2             October 2016


3.2.1.  Handshake Error Reasons

   Valid error reasons are:

       success
           * The server accepted the client

       invalid_version
           * This version of websockets is not supported by the server

       cannot_negotiate_compression
           * This means the client did not offer any compression that
           the server requires

       rejected
           * This means the server rejected the client and does not want
           to say why. This means the server supports websockets, but
           rejected this particular client

3.3.  Post Handshake

   Following the handshake the client or server MUST NEVER set the
   END_STREAM flag on any HTTP/2 DATA frame UNLESS the stream is to be
   gracefully terminated.  Only a HTTP/2 DATA frame containing a
   WebSocket2 error frame allow the END_STREAM flag to be set.

4.  Data Framing

   Once a handshake has been successfully completed the remote endpoints
   can begin to send data to each other.  Data is sent using the HTTP/2
   transport layer fully adhering to DATA Frames, Section 6.1 [RFC7540].
   WebSocket2 has its own encapsulated framing protocol that is not to
   be confused with HTTP/2 DATA Frames.

   Three frame types are defined:

      text (represented by 0)
      binary (represented by 1)
      error (represented by 2)

   Three compression types are defined:

      none (represented by 0)
      lz4 (represented by 1)
      deflate (represented by 2)

   A WebSocket2 over HTTP/2 frame starts with the full frame length in a
   special format called VarSize.  If the first octet is less than 254,



Svirid                   Expires April 21, 2017                 [Page 5]


Internet-Draft           WebSocket2 over HTTP/2             October 2016


   this is the full frame length.  If the first octet is 254, read the
   next 16 bits as a little endian unsigned number for the frame length.
   If the first octet is 255, read the next 32 bits as a little endian
   unsigned number for the frame length.

   Next are 4 reserved bits that MUST be set to 0.

   The next 2 bits specify the compression type.

   The next 2 bits specify the frame type.

   Next is the payload which MAY be compressed if compression was
   negotiated.

   The term PAYLOAD in this section refers to data AFTER decompression
   if compression was negotiated.

                    0              1             2
             +--------------+--------------+--------------+
             | Frame Length | R  - C - F |                | ->
             |  (8,24,40)   | S  | T | T |   Payload      | ->
             |              | V  | P | P |                | ->
             |              |(4) -(2)-(2)|                | ->
             +--------------+------------+----------------+

4.1.  Text Frame

   The text frame has a Frame Type value of 0.  The payload must be
   UTF-8 encoded text.  The whole message MUST contain valid UTF-8.
   Invalid UTF-8 in the payload requires the remote end point to send an
   error frame and close their side of the stream.

4.2.  Binary Frame

   The binary frame has a Frame Type value of 1.  The payload must be
   arbitrary binary data which the application layer passes without
   comprehension.

4.3.  Error Frame

   The error frame has a Frame Type value of 2.  It MUST contain a VALID
   32 bit error code.  If the code is shorter than 32 bits, 0 bits MUST
   make up the rest to fill a total of 32 bits.  Currently there are no
   error codes less than 32 bits.

   The HTTP/2 transport layer DATA frame carrying the WebSocket2 error
   frame MUST have the END_STREAM flag set.




Svirid                   Expires April 21, 2017                 [Page 6]


Internet-Draft           WebSocket2 over HTTP/2             October 2016


   No further WebSocket2 frames may be sent from this point onward and
   the stream is half closed.

   The remote endpoint that receives the error frame MUST flush all
   pending sends followed by an error frame of its own with the CLOS
   error code.  The HTTP/2 Data frame carrying this WebSocket2 frame
   MUST have the END_STREAM flag set.

   The full WebSocket2 error frame with the length:

              0     01234567     2        3        4      5
          +--------+--------+--------+--------+--------+--------+
          |        |        |         Error Code                |
          |   5    |00000010|          (32 bits)                |
          |        |        |                                   |
          +--------+--------+--------+--------+--------+--------+

4.3.1.  Error Frame Codes

   Valid error frame codes currently are:

   CLOS

      * This should be sent when a client or server want to close the
      stream gracefully.

   UTF8

      * This should be sent when invalid UTF8 was passed in a text frame
      by a remote endpoint.

   DECO

      * This should be sent when decompression failed by a remote
      endpoint.

   FRAM

      * This should be sent when an invalid Frame Type was specified.

   LRGE

      * This should be sent when an endpoint rejects a frame due to it
      being too large.  This is up to the endpoint.







Svirid                   Expires April 21, 2017                 [Page 7]


Internet-Draft           WebSocket2 over HTTP/2             October 2016


5.  VarSize

   VarSize is a variable sized binary ranging from 1-5 octets.  It
   represents an unsigned value.  If the first octet is equal to 254,
   read the next 16 bits as little endian unsigned.  If the first octet
   is equal to 255, read the next 32 bits as little endian unsigned.
   Otherwise if the first octet is less than 254, treat this as the
   final value.

6.  Compression

   WebSocket defined one compression method which used deflate and kept
   a sliding window.  This compression is great but has limitations.
   Also keeping a sliding window is memory intensive.

   Lz4 is a compression method that is great for any kind of data while
   being very cheap.

   Currently two compression methods are defined lz4 and deflate.  The
   protocol is open to tweaking or accepting more in the future.

6.1.  LZ4 Compressed Payload

   A lz4 compressed payload is a VarSize number of the decompressed size
   followed by the actual compressed payload.  The lz4 compression level
   to use MUST be what was negotiated in the handshake.

   A lz4 compressed payload may look like:

            0         1       2        3
        +--------+--------+--------+--------+--------+--------+
        |        |   Decompressed  |     Compressed payload   | ->
        |  254   |      Size       |                          | ->
        |        |                 |                          | ->
        +--------+--------+--------+--------+--------+--------+

6.2.  Deflate Compressed Payload

   The deflate compression method implements [RFC7692] but defines more
   strict bounds.  There is no ability to reset compression context.

      * Both client and server MUST use the sliding window bits as
      determined by the server.
      * The client MUST use a memory level of 8.
      * The client MUST use a compression level of 9 (best_compression).

   Any sliding window MUST NEVER have its context reset.




Svirid                   Expires April 21, 2017                 [Page 8]


Internet-Draft           WebSocket2 over HTTP/2             October 2016


   If the deflated payload trailing 4 octets are 0x00, 0x00, 0xFF, 0xFF,
   remove them before sending the payload.

   Before inflating the payload append 0x00, 0x00, 0xFF, 0xFF to the end
   of it.

7.  References

7.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>.

   [RFC7692]  Yoshino, T., "Compression Extensions for WebSocket",
              RFC 7692, DOI 10.17487/RFC7692, December 2015,
              <http://www.rfc-editor.org/info/rfc7692>.

7.2.  Informative References

   [RFC6455]  Fette, I. and A. Melnikov, "The WebSocket Protocol",
              RFC 6455, DOI 10.17487/RFC6455, December 2011,
              <http://www.rfc-editor.org/info/rfc6455>.

   [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>.

Appendix A.  Acknowledgements

   The author wishes to thank Kari hurtta for contributing the
   handshake.

   The author wishes to thank the participants of the WebSocket
   protocol, participants of the HTTP/2 protocol and participants of the
   QUIC protocol.

Author's Address

   Ivan Svirid
   Toronto, ON
   Canada

   Email: vans_163@yahoo.com





Svirid                   Expires April 21, 2017                 [Page 9]