Re: Issue 240: Migrate Upgrade details from RFC2817

OK,

I have made the following changes in 
<http://trac.tools.ietf.org/wg/httpbis/trac/changeset/1071>:

P1: rephrase definition of Upgrade header field so that it states the 
semantics for status codes != 101:

-- snip --
9.8.  Upgrade

    The "Upgrade" general-header field allows the client to specify what
    additional communication protocols it would like to use, if the
    server chooses to switch protocols.  Servers can use it to indicate
    what protocols they are willing to switch to.

      Upgrade   = "Upgrade" ":" OWS Upgrade-v
      Upgrade-v = 1#product

    For example,

      Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11

    The Upgrade header field is intended to provide a simple mechanism
    for transition from HTTP/1.1 to some other, incompatible protocol.
    It does so by allowing the client to advertise its desire to use
    another protocol, such as a later version of HTTP with a higher major
    version number, even though the current request has been made using
    HTTP/1.1.  This eases the difficult transition between incompatible
    protocols by allowing the client to initiate a request in the more
    commonly supported protocol while indicating to the server that it
    would like to use a "better" protocol if available (where "better" is
    determined by the server, possibly according to the nature of the
    method and/or resource being requested).

    The Upgrade header field only applies to switching application-layer
    protocols upon the existing transport-layer connection.  Upgrade
    cannot be used to insist on a protocol change; its acceptance and use
    by the server is optional.  The capabilities and nature of the
    application-layer communication after the protocol change is entirely
    dependent upon the new protocol chosen, although the first action
    after changing the protocol MUST be a response to the initial HTTP
    request containing the Upgrade header field.

    The Upgrade header field only applies to the immediate connection.
    Therefore, the upgrade keyword MUST be supplied within a Connection
    header field (Section 9.1) whenever Upgrade is present in an HTTP/1.1
    message.

    The Upgrade header field cannot be used to indicate a switch to a
    protocol on a different connection.  For that purpose, it is more
    appropriate to use a 3xx redirection response (Section 8.3 of
    [Part2]).

    Servers MUST include the "Upgrade" header field in 101 (Switching
    Protocols) responses to indicate which protocol(s) are being switched
    to, and MUST include it in 426 (Upgrade Required) responses to
    indicate acceptable protocols to upgrade to.  Servers MAY include it
    in any other response to indicate that they are willing to upgrade to
    one of the specified protocols.

    This specification only defines the protocol name "HTTP" for use by
    the family of Hypertext Transfer Protocols, as defined by the HTTP
    version rules of Section 2.5 and future updates to this
    specification.  Additional tokens can be registered with IANA using
    the registration procedure defined below.
-- snip --

In Part 2, add definition of status code 426:

-- snip --
8.4.19.  426 Upgrade Required

    The request can not be completed without a prior protocol upgrade.
    This response MUST include an Upgrade header field (Section 9.8 of
    [Part1]) specifying the required protocols.

    Example:

      HTTP/1.1 426 Upgrade Required
      Upgrade: HTTP/2.0
      Connection: Upgrade


    The server SHOULD include a message body in the 426 response which
    indicates in human readable form the reason for the error and
    describes any alternative courses which may be available to the user.
-- snip --

I believe we are done with ticket 240, and should treat all remaining 
issues as separate bugs...

Feedback appreciated,

Julian

Received on Saturday, 30 October 2010 17:06:22 UTC