Changeset 1831 for draft-ietf-httpbis/latest/p1-messaging.xml

Timestamp:

Aug 19, 2012, 2:46:53 AM (8 years ago)

Author:

fielding@…

Message:

clean up TE, move qvalues to p2, and make its usage consistent for accept(-*)

File:

• draft-ietf-httpbis/latest/p1-messaging.xml (modified) (10 diffs)

draft-ietf-httpbis/latest/p1-messaging.xml

@@ -46 +46 @@
   <!ENTITY methods                "<xref target='Part2' x:rel='#methods' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
   <!ENTITY OPTIONS                "<xref target='Part2' x:rel='#OPTIONS' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
+  <!ENTITY qvalue                 "<xref target='Part2' x:rel='#quality.values' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
   <!ENTITY status-codes           "<xref target='Part2' x:rel='#status.codes' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
   <!ENTITY status-100             "<xref target='Part2' x:rel='#status.100' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
@@ -1982 +1983 @@
    message.
 </t>
-<x:note><t>
-   &Note; Use of program names for the identification of encoding formats
-   is not desirable and is discouraged for future encodings. Their
-   use here is representative of historical practice, not good
-   design.
-</t></x:note>
-<x:note><t>
-   &Note; For compatibility with previous implementations of HTTP,
-   applications &SHOULD; consider "x-gzip" and "x-compress" to be
-   equivalent to "gzip" and "compress" respectively.
-</t></x:note>
 
 <section title="Compress Coding" anchor="compress.coding">
@@ -2000 +1990 @@
    The "compress" format is produced by the common UNIX file compression
    program "compress". This format is an adaptive Lempel-Ziv-Welch
-   coding (LZW).
+   coding (LZW). Recipients &SHOULD; consider "x-compress" to be
+   equivalent to "compress".
 </t>
 </section>
@@ -2027 +2018 @@
    "gzip" (GNU zip), as described in <xref target="RFC1952"/>. This format is a
    Lempel-Ziv coding (LZ77) with a 32 bit CRC.
+   Recipients &SHOULD; consider "x-gzip" to be equivalent to "gzip".
 </t>
 </section>
@@ -2037 +2029 @@
   <x:anchor-alias value="TE"/>
   <x:anchor-alias value="t-codings"/>
-  <x:anchor-alias value="te-params"/>
-  <x:anchor-alias value="te-ext"/>
-<t>
-   The "TE" header field indicates what extension transfer-codings
-   the client is willing to accept in the response, and whether or not it is
-   willing to accept trailer fields in a chunked transfer-coding.
-</t>
-<t>
-   Its value consists of the keyword "trailers" and/or a comma-separated
-   list of extension transfer-coding names with optional accept
-   parameters (as described in <xref target="transfer.codings"/>).
-</t>
-<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="TE"/><iref primary="true" item="Grammar" subitem="t-codings"/><iref primary="true" item="Grammar" subitem="te-params"/><iref primary="true" item="Grammar" subitem="te-ext"/>
+  <x:anchor-alias value="t-ranking"/>
+  <x:anchor-alias value="rank"/>
+<t>
+   The "TE" header field in a request indicates what transfer-codings,
+   besides "chunked", the client is willing to accept in response, and
+   whether or not the client is willing to accept trailer fields in a
+   chunked transfer-coding.
+</t>
+<t>
+   The TE field-value consists of a comma-separated list of transfer-coding
+   names, each allowing for optional parameters (as described in
+   <xref target="transfer.codings"/>), and/or the keyword "trailers".
+   Clients &MUST-NOT; send the chunked transfer-coding name in TE;
+   chunked is always acceptable for HTTP/1.1 recipients.
+</t>
+<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="TE"/><iref primary="true" item="Grammar" subitem="t-codings"/><iref primary="true" item="Grammar" subitem="t-ranking"/><iref primary="true" item="Grammar" subitem="rank"/>
   <x:ref>TE</x:ref>        = #<x:ref>t-codings</x:ref>
-  <x:ref>t-codings</x:ref> = "trailers" / ( <x:ref>transfer-extension</x:ref> [ <x:ref>te-params</x:ref> ] )
-  <x:ref>te-params</x:ref> = <x:ref>OWS</x:ref> ";" <x:ref>OWS</x:ref> "q=" <x:ref>qvalue</x:ref> *( <x:ref>te-ext</x:ref> )
-  <x:ref>te-ext</x:ref>    = <x:ref>OWS</x:ref> ";" <x:ref>OWS</x:ref> <x:ref>token</x:ref> [ "=" <x:ref>word</x:ref> ]
+  <x:ref>t-codings</x:ref> = "trailers" / ( <x:ref>transfer-coding</x:ref> [ <x:ref>t-ranking</x:ref> ] )
+  <x:ref>t-ranking</x:ref> = <x:ref>OWS</x:ref> ";" <x:ref>OWS</x:ref> "q=" <x:ref>rank</x:ref>
+  <x:ref>rank</x:ref>      = ( "0" [ "." 0*3<x:ref>DIGIT</x:ref> ] )
+             / ( "1" [ "." 0*3("0") ] )
 </artwork></figure>
 <t>
-   The presence of the keyword "trailers" indicates that the client is
-   willing to accept trailer fields in a chunked transfer-coding, as
-   defined in <xref target="chunked.encoding"/>. This keyword is reserved for use with
-   transfer-coding values even though it does not itself represent a
-   transfer-coding.
-</t>
-<t>
-   Examples of its use are:
+   Three examples of TE use are below.
 </t>
 <figure><artwork type="example">
@@ -2071 +2060 @@
 </artwork></figure>
 <t>
-   The TE header field only applies to the immediate connection.
-   Therefore, the keyword &MUST; be supplied within a <x:ref>Connection</x:ref>
-   header field (<xref target="header.connection"/>) whenever TE is present in
-   an HTTP/1.1 message.
-</t>
-<t>
-   A server tests whether a transfer-coding is acceptable, according to
-   a TE field, using these rules:
-  <list style="numbers">
-    <x:lt>
-      <t>The "chunked" transfer-coding is always acceptable. If the
-         keyword "trailers" is listed, the client indicates that it is
-         willing to accept trailer fields in the chunked response on
-         behalf of itself and any downstream clients. The implication is
-         that, if given, the client is stating that either all
-         downstream clients are willing to accept trailer fields in the
-         forwarded response, or that it will attempt to buffer the
-         response on behalf of downstream recipients.
-      </t><t>
-         &Note; HTTP/1.1 does not define any means to limit the size of a
-         chunked response such that a client can be assured of buffering
-         the entire response.</t>
-    </x:lt>
-    <x:lt>
-      <t>If the transfer-coding being tested is one of the transfer-codings
-         listed in the TE field, then it is acceptable unless it
-         is accompanied by a qvalue of 0. (As defined in <xref target="quality.values"/>, a
-         qvalue of 0 means "not acceptable".)</t>
-    </x:lt>
-    <x:lt>
-      <t>If multiple transfer-codings are acceptable, then the
-         acceptable transfer-coding with the highest non-zero qvalue is
-         preferred.  The "chunked" transfer-coding always has a qvalue
-         of 1.</t>
-    </x:lt>
-  </list>
+   The presence of the keyword "trailers" indicates that the client is
+   willing to accept trailer fields in a chunked transfer-coding,
+   as defined in <xref target="chunked.encoding"/>, on behalf of itself and
+   any downstream clients. For chained requests, this implies that either:
+   (a) all downstream clients are willing to accept trailer fields in the
+   forwarded response; or,
+   (b) the client will attempt to buffer the response on behalf of downstream
+   recipients.
+   Note that HTTP/1.1 does not define any means to limit the size of a
+   chunked response such that a client can be assured of buffering the
+   entire response.
+</t>
+<t>
+   When multiple transfer-codings are acceptable, the client &MAY; rank the
+   codings by preference using a "q" parameter (similar to the qvalues
+   used in content negotiation fields, &qvalue;). The rank value is a real
+   number in the range 0 through 1, where 0.001 is the least preferred and
+   1 is the most preferred; a value of 0 means "not acceptable".
 </t>
 <t>
    If the TE field-value is empty or if no TE field is present, the only
-   acceptable transfer-coding is "chunked". A message with no transfer-coding is
-   always acceptable.
-</t>
-
-<section title="Quality Values" anchor="quality.values">
-  <x:anchor-alias value="qvalue"/>
-<t>
-   Both transfer codings (<x:ref>TE</x:ref> request header field,
-   <xref target="header.te"/>) and content negotiation (&content.negotiation;)
-   use short "floating point" numbers to indicate the relative importance
-   ("weight") of various negotiable parameters.  A weight is normalized to a
-   real number in the range 0 through 1, where 0 is the minimum and 1 the
-   maximum value. If a parameter has a quality value of 0, then content with
-   this parameter is "not acceptable" for the client. HTTP/1.1
-   applications &MUST-NOT; generate more than three digits after the
-   decimal point. User configuration of these values &SHOULD; also be
-   limited in this fashion.
-</t>
-<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="qvalue"/>
-  <x:ref>qvalue</x:ref>         = ( "0" [ "." 0*3<x:ref>DIGIT</x:ref> ] )
-                 / ( "1" [ "." 0*3("0") ] )
-</artwork></figure>
-<x:note>
-  <t>
-     &Note; "Quality values" is a misnomer, since these values merely represent
-     relative degradation in desired quality.
-  </t>
-</x:note>
-</section>
+   acceptable transfer-coding is "chunked". A message with no transfer-coding
+   is always acceptable.
+</t>
+<t>
+   Since the TE header field only applies to the immediate connection,
+   a sender of TE &MUST; also send a "TE" connection option within the
+   <x:ref>Connection</x:ref> header field (<xref target="header.connection"/>)
+   in order to prevent the TE field from being forwarded by intermediaries
+   that do not support its semantics.
+</t>
 </section>
 
@@ -3585 +3537 @@
 <t>
    Names of transfer codings &MUST-NOT; overlap with names of content codings
-   (&content-codings;) unless the encoding transformation is identical, as it
+   (&content-codings;) unless the encoding transformation is identical, as
    is the case for the compression codings defined in
    <xref target="compression.codings"/>.
@@ -3593 +3545 @@
    <xref target="RFC5226" x:fmt="of" x:sec="4.1"/>), and &MUST;
    conform to the purpose of transfer coding defined in this section.
+   Use of program names for the identification of encoding formats
+   is not desirable and is discouraged for future encodings.
 </t>
 <t>
@@ -5191 +5145 @@
 <x:ref>quoted-str-nf</x:ref> = DQUOTE *( qdtext-nf / quoted-pair ) DQUOTE
 <x:ref>quoted-string</x:ref> = DQUOTE *( qdtext / quoted-pair ) DQUOTE
-<x:ref>qvalue</x:ref> = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] )
-
+
+<x:ref>rank</x:ref> = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] )
 <x:ref>reason-phrase</x:ref> = *( HTAB / SP / VCHAR / obs-text )
 <x:ref>received-by</x:ref> = ( uri-host [ ":" port ] ) / pseudonym
@@ -5207 +5161 @@
 <x:ref>status-line</x:ref> = HTTP-version SP status-code SP reason-phrase CRLF
 
-<x:ref>t-codings</x:ref> = "trailers" / ( transfer-extension [ te-params ] )
+<x:ref>t-codings</x:ref> = "trailers" / ( transfer-coding [ t-ranking ] )
+<x:ref>t-ranking</x:ref> = OWS ";" OWS "q=" rank
 <x:ref>tchar</x:ref> = "!" / "#" / "$" / "%" / "&amp;" / "'" / "*" / "+" / "-" / "." /
  "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
-<x:ref>te-ext</x:ref> = OWS ";" OWS token [ "=" word ]
-<x:ref>te-params</x:ref> = OWS ";" OWS "q=" qvalue *te-ext
 <x:ref>token</x:ref> = 1*tchar
 <x:ref>trailer-part</x:ref> = *( header-field CRLF )