HTTPbis Working Group                                          M. Bishop
Internet-Draft                                                 Microsoft
Expires: May 12, 2014                                  November 08, 2013

                      Extension Frames in HTTP/2.0


   This document describes a proposed modification to the HTTP/2.0
   specification to better support the creation of extensions without
   the need to version the core protocol or invoke additional protocol

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

   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 May 12, 2014.

Copyright Notice

   Copyright (c) 2013 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
   ( 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
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Bishop                    Expires May 12, 2014                  [Page 1]

Internet-Draft                 Extensions                  November 2013

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Conventions and Terminology . . . . . . . . . . . . . . .   3
   2.  Extension Functionality . . . . . . . . . . . . . . . . . . .   3
     2.1.  Extension Identification  . . . . . . . . . . . . . . . .   4
     2.2.  Extension Frames  . . . . . . . . . . . . . . . . . . . .   4
     2.3.  Extension Settings  . . . . . . . . . . . . . . . . . . .   5
     2.4.  Intermediary Behavior . . . . . . . . . . . . . . . . . .   6
     2.5.  Base Specification Behavior . . . . . . . . . . . . . . .   6
     2.6.  IANA Considerations . . . . . . . . . . . . . . . . . . .   7
   3.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   7
   Appendix A.  Example Extensions . . . . . . . . . . . . . . . . .   7
     A.1.  Server Hint . . . . . . . . . . . . . . . . . . . . . . .   8
       A.1.1.  Format  . . . . . . . . . . . . . . . . . . . . . . .   8
       A.1.2.  Behavior  . . . . . . . . . . . . . . . . . . . . . .  10
   Appendix B.  Acknowledgements . . . . . . . . . . . . . . . . . .  10

1.  Introduction

   HTTP/2.0 currently offers an inconsistent story about the use of
   extensions.  As the draft currently stands, extensions have the
   following traits:

   o  They may define SETTINGS values, provided they do not modify
      identifiers within the base HTTP/2.0 spec

   o  They may define new frame types, provided they do not:

         Conflict with the base HTTP/2.0 frame types

         Modify session state

         Require understanding in order to communicate over the base

   This poses a number of problems for such extension frames.  To begin
   with, there is no way to know whether the peer supports a given
   extension before sending extension-specific information.  This is
   addressed in the current spec by saying that implementations MUST
   ignore frame types and settings values they don't understand, but
   sending information that your peer cannot parse wastes bandwidth.
   Further, it shackles extensions since they are prohibited from
   modifying session state.

   As an additional concern, with only 256 frame types it is conceivable
   that the frame type space may be exhausted if many extensions are
   defined.  It more than conceivable that different extensions will

Bishop                    Expires May 12, 2014                  [Page 2]

Internet-Draft                 Extensions                  November 2013

   collide with each other in the choice of frame type identifiers,
   since the space is limited.  Requiring IANA to register frame type
   identifiers is onerous, since the number and types of the frames has
   changed often during HTTP/2.0 development and there is no reason to
   expect that a complex extension would do otherwise.  This should be
   balanced against the goal of defining a simple, single-frame
   extension and being able to quickly allocate this single frame type.

   Future versions of the HTTP/2.0 specification will face exactly the
   same problem as extension authors, since they currently share a frame
   type and setting value space with any extensions.  Thus, a new frame
   introduced with HTTP/2.1+ must avoid collision with HTTP/2.0
   extensions and must deal with space exhaustion.  Any means of
   resolving such adoption after the fact complicates forward-porting of
   existing extensions.

   This document proposes an alternative method of supporting extension
   frames and settings, with the following goals:

   o  Reduce the probability of collision among extensions and between
      extensions and future versions of HTTP

   o  Enable peers to completely disable all extensions

   o  Enable peers to selectively disable an extension without requiring
      knowledge of the extension they wish to disable

   o  Enable peers to quickly discover support for a particular
      extension on the far side

1.1.  Conventions and Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   document are to be interpreted as described in RFC 2119 [RFC2119].

   All numeric values are in network byte order.  Values are unsigned
   unless otherwise indicated.  Literal values are provided in decimal
   or hexadecimal as appropriate.  Hexadecimal literals are prefixed
   with "0x" to distinguish them from decimal literals.

2.  Extension Functionality

Bishop                    Expires May 12, 2014                  [Page 3]

Internet-Draft                 Extensions                  November 2013

2.1.  Extension Identification

   An extension to HTTP/2.0 is identified by an Extension ID.  An
   Extension ID is a 24-bit identifier with two parts: A sixteen-bit
   private enterprise number and an eight-bit enterprise-local extension
   identifier.  Private enterprise numbers are issued by IANA, with an
   existing registry [IANA-PEN].

   An organization is free to utilize any method to allocate and track
   the assignment of its organization-local extensions, though expert
   review of proposed extensions is strongly recommended.  If all 256
   values have been allocated, the organization may request an
   additional organizational identifier.  Extensions allocated by the
   IETF will be tracked by IANA.

   It is suggested that each organization reserve an extension ID (for
   instance, 0x00) for low-volume single-frame extensions, and allocate
   these frame types with a local registry.  This avoids consuming an
   entire extension ID for a single new frame type, at the expense of
   being unable to separately disable these single-frame extensions.
   Such extensions MUST NOT modify the state of the base protocol in any
   circumstance, since support for the specific frame cannot be
   detected.  Extensions which require several frames or the ability to
   have support separately detected should be allocated a separate ID.

   The private enterprise number 0x000000, allocated to IANA, is
   reserved in this context for IETF RFCs.  Extension ID 0x00000000 is
   reserved for values defined in base HTTP specifications and single-
   frame extensions defined by the HTTP working group.

2.2.  Extension Frames

   The EXTENSION frame (0xFF) carries content which is specific to an
   extension.  The EXTENSION frame contains a sub-header of the
   following format:

       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
       |                Extension ID (24)              | Ext. Type (8) |
       |                    Extension-specific payload               ...

                         Extension Payload Format

Bishop                    Expires May 12, 2014                  [Page 4]

Internet-Draft                 Extensions                  November 2013

   The payload of an EXTENSION frame includes the Extension ID of the
   extension which should be used to process the frame, as well as an
   extension-local frame type, permitting any extension up to 256
   distinct frame types which it has complete freedom to define.

   EXTENSION frames may be sent on any stream which is half-open in the
   sender's direction (that is, a stream on which the sender could send
   a DATA frame) or on stream zero.

   The semantics of EXTENSION frames are defined by their respective
   extensions, with the following restrictions:

   o  An extension frame on stream zero with semantics which modify the
      state of the base protocol MUST NOT be sent until the remote peer
      has indicated support for the extension.

   o  An extension frame on a non-zero stream MUST NOT modify the state
      of the base protocol.

2.3.  Extension Settings

   An implementation which does not intend to interpret or relay any
   extension frames or setting values SHOULD send the setting value
   BASE_SPECIFICATION_ONLY (0xFF) set to a non-zero value.  Upon receipt
   of this setting value, an implementation MUST NOT send any setting
   value or frame not defined in the specification of the negotiated

   In order to minimize round-trips, it is advisable to exchange any
   necessary initial state as early as possible.  This means that
   critical information should be included in the initial SETTINGS
   frame, in order to benefit from the transmission of this frame in
   advance of any other frames.  However, to avoid bloating this initial
   frame, extensions are encouraged to send only the minimum amount of
   information necessary for the extension to be useful in the initial
   SETTINGS frame.  Information which is not critical for bootstrapping
   SHOULD be sent in a subsequent SETTINGS frame, or in an extension-
   specific frame type.

   This draft updates the definition of a setting value as follows:

Bishop                    Expires May 12, 2014                  [Page 5]

Internet-Draft                 Extensions                  November 2013

       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
       |             Extension Identifier (24)         | Ext. Setting  |
       |                           Value (32)                          |

                       Modified Setting Value Format

   The Extension Setting field with a value equal to zero is reserved
   for extension identification.  An implementation which wishes to
   inform a peer that it will be employing a certain extension MAY set
   this to any non-zero value.  Interpretation of the non-zero value is
   extension-dependent, and may communicate some initial state or
   preferences.  An implementation which wishes to explicitly inform a
   peer that it does not understand, does not wish to use, or will not
   relay a certain extension MAY set this value to zero.

   The semantics of all other values of Extension Setting are defined by
   the extension.  These semantics MUST NOT modify the state the base
   protocol.  (If this is needed, define an extension-specific frame to
   carry settings.)  These setting values MUST NOT be sent for an
   extension the sender does not implement, and MUST be ignored upon
   receipt if not understood.

2.4.  Intermediary Behavior

   EXTENSION frames sent on stream zero are explicitly hop-by-hop and
   MUST be ignored by intermediaries which do not understand the
   specified Extension ID.  In order to ensure consistent state, an
   intermediary which is not terminating the HTTP request MUST provide
   one of the following behaviors to each stream other than zero:

   o  Forward all extension frames on this stream

   o  Discard all extension frames on this stream

   Because distinct streams on a given connection may be related to
   different backend servers or different clients, these behaviors MAY
   vary from stream to stream without notification to the peer on either
   side.  An intermediary which intends to discard all extension frames
   on all streams SHOULD set the BASE_SPECIFICATION_ONLY (Section 2.3,
   Paragraph 1) setting to avoid wasted effort on a peer's part.

2.5.  Base Specification Behavior

Bishop                    Expires May 12, 2014                  [Page 6]

Internet-Draft                 Extensions                  November 2013

   Since extensions now have a segregated frame and settings space, the
   receipt of any non-EXTENSION frame type not defined in the negotiated
   protocol is a session error of (new) type INVALID_FRAME_TYPE.

2.6.  IANA Considerations

   This draft employs the Private Enterprise Number registry, already
   maintained by IANA, to avoid creating a nearly duplicate registry
   specific to HTTP/2.0.  However, due to the number of bytes available,
   it restricts this registry from 32 bits to 16 bits.  This still
   allows enough space for the current number of registrations to
   double, but it does sharply increase the possibility of eventual

   One possible mitigation would be to expand the Extension ID from 24
   to 32 bits, expanding the space for the PEN to 24 bits.  This would
   require removing the extension frame sub-type and setting value space
   for extensions, constraining extensions to a single 32-bit setting
   value; extensions which require more than 32 bits for settings would
   need to define an equivalent to the SETTINGS frame.  In the same way,
   extensions which require multiple frame types would need to define a
   frame type field inside their payload.

   The proper resolution here remains an open issue, and discussion is
   one goal of this draft.

3.  References

   [HPACK]    Ruellan, H. and R. Peon, "HPACK - Header Compression for
              HTTP/2.0", draft-ietf-httpbis-header-compression-04 (work
              in progress), October 2013.

              , "Private Enterprise Numbers", .

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels ", BCP 14, RFC 2119, March 1997.

              Snell, J., "HTTP Extensions", draft-snell-httpbis-ext-
              frames-00 (work in progress), May 2013.

   [URI]      Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax ", STD 66, RFC
              3986, January 2005.

Appendix A.  Example Extensions

Bishop                    Expires May 12, 2014                  [Page 7]

Internet-Draft                 Extensions                  November 2013

   This section describes how certain extensions might leverage the
   EXTENSION frame.  It is explicitly not an attempt to define the
   specific extension at this time, though the ideas have been discussed
   and should be explored in the future.

   Other sample extensions can be found in another Internet Draft
   [SnellExtensions] submitted to this working group.

A.1.  Server Hint

   Server Push has many attractive features, because it can eliminate
   both the RTT needed to send a request and the DOM processing time to
   realize a resource will be needed.  However, it suffers from several
   drawbacks as well:

   o  The server cannot know what the client has in its cache, leading
      to wasted data transmission

   o  The server cannot push resources for other origins, specifically
      resources which may be hosted on CDNs of which the server is aware

   o  The server must fully specify the client request, which it will do

   Server Hint defines a mechanism which sacrifices the RTT savings, but
   retains the ability to initiate requests before DOM parsing (or even
   document transfer) has completed and overcomes the stated drawbacks
   of server push.  While not intended as a replacement for Server Push,
   it may be a useful complement or replacement when a PUSH_PROMISE is
   not appropriate.

A.1.1.  Format

   The format of the Server Hint frame is as follows:

       |                Target Authority (varies)                      |
       | ResCount (8+) |         Resource Records                    ...

                        Server Hint Extension Frame

   Target Authority specifies the scheme and authority components of the
   URI, which apply all resources in this frame.  (Resources which
   should be retrieved from a different authority or using a different

Bishop                    Expires May 12, 2014                  [Page 8]

Internet-Draft                 Extensions                  November 2013

   scheme MUST be sent in a separate frame.)  This URI fragment is
   formatted as a length-prefixed Huffman-encoded string, as defined in

   ResCount is an 8-bit-prefix variable-length integer, also as defined
   in HPACK [HPACK].  It defines how many Resource Records for the
   specified authority follow.

   The format of each Resource Record is as follows:

       | Length (8+)   | Attributes (8)|          Path (varies)        |
       |                    ETag (optional)                          ...
       |               Last Modified Date (optional)                 ...
       |                    Size (optional)                          ...
       |                   Reserved (optional)                       ...

                        Server Hint Extension Frame

   Length:  An 8-bit prefix integer giving the number of bytes in the
      resource record

   Attributes:  A bitmask specifying which optional pieces of
      information the server has opted to include:

      *  0x80: Set if ETag is present

      *  0x40: Set if Last-Modified Date is present

      *  0x20: Set if Size is present

      The remaining bits are reserved.

   Path:  A length-prefixed Huffman-encoded string as specified in HPACK
      [HPACK] containing the path (and optional query) component(s) of
      the resource URI [URI].

   ETag:  A length-prefixed Huffman-encoded string as specified in HPACK
      [HPACK], containing the ETag as specified in RFC 2616.

Bishop                    Expires May 12, 2014                  [Page 9]

Internet-Draft                 Extensions                  November 2013

   Last-Modified Date:  Last-Modified Date is the HTTP Date converted
      into the number of seconds since 1970-01-01 0:00 UTC formatted as
      an 8-bit prefix variable-length integer.

   Size:  The content length, formatted as an 8-bit prefix variable-
      length integer.

   Reserved:  MUST be zero-length when sent, and unknown fields in the
      Reserved space MUST be ignored.

A.1.2.  Behavior

   A server MAY send a Server Hint frame multiple times on a stream.  It
   may be sent only in a circumstance where a PUSH_PROMISE frame would
   have been permissible, except for the value of PUSH_ENABLED.  A
   single frame contains a list of resources accessible under a single
   authority, but multiple instances of the frame MAY be sent to refer
   clients to resources available from multiple authorities.

   Upon receipt of a Server Hint frame, a client MUST check its cache
   for a corresponding resource.  If the resource is not available in
   the cache, it SHOULD open connections to the specified authority and
   request the resource.

   When processing a Server Hint frame containing no resources or in
   which all resources are already available from cache, a client MAY
   prepare to make other requests in various ways, such as beginning DNS
   resolution, connection establishment, etc.

Appendix B.  Acknowledgements

   This document includes input from Martin Thompson and Gabriel

Author's Address

   Mike Bishop


Bishop                    Expires May 12, 2014                 [Page 10]