Ignore:
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:
1 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p1-messaging.xml

    r1830 r1831  
    4646  <!ENTITY methods                "<xref target='Part2' x:rel='#methods' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    4747  <!ENTITY OPTIONS                "<xref target='Part2' x:rel='#OPTIONS' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
     48  <!ENTITY qvalue                 "<xref target='Part2' x:rel='#quality.values' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    4849  <!ENTITY status-codes           "<xref target='Part2' x:rel='#status.codes' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    4950  <!ENTITY status-100             "<xref target='Part2' x:rel='#status.100' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
     
    19821983   message.
    19831984</t>
    1984 <x:note><t>
    1985    &Note; Use of program names for the identification of encoding formats
    1986    is not desirable and is discouraged for future encodings. Their
    1987    use here is representative of historical practice, not good
    1988    design.
    1989 </t></x:note>
    1990 <x:note><t>
    1991    &Note; For compatibility with previous implementations of HTTP,
    1992    applications &SHOULD; consider "x-gzip" and "x-compress" to be
    1993    equivalent to "gzip" and "compress" respectively.
    1994 </t></x:note>
    19951985
    19961986<section title="Compress Coding" anchor="compress.coding">
     
    20001990   The "compress" format is produced by the common UNIX file compression
    20011991   program "compress". This format is an adaptive Lempel-Ziv-Welch
    2002    coding (LZW).
     1992   coding (LZW). Recipients &SHOULD; consider "x-compress" to be
     1993   equivalent to "compress".
    20031994</t>
    20041995</section>
     
    20272018   "gzip" (GNU zip), as described in <xref target="RFC1952"/>. This format is a
    20282019   Lempel-Ziv coding (LZ77) with a 32 bit CRC.
     2020   Recipients &SHOULD; consider "x-gzip" to be equivalent to "gzip".
    20292021</t>
    20302022</section>
     
    20372029  <x:anchor-alias value="TE"/>
    20382030  <x:anchor-alias value="t-codings"/>
    2039   <x:anchor-alias value="te-params"/>
    2040   <x:anchor-alias value="te-ext"/>
    2041 <t>
    2042    The "TE" header field indicates what extension transfer-codings
    2043    the client is willing to accept in the response, and whether or not it is
    2044    willing to accept trailer fields in a chunked transfer-coding.
    2045 </t>
    2046 <t>
    2047    Its value consists of the keyword "trailers" and/or a comma-separated
    2048    list of extension transfer-coding names with optional accept
    2049    parameters (as described in <xref target="transfer.codings"/>).
    2050 </t>
    2051 <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"/>
     2031  <x:anchor-alias value="t-ranking"/>
     2032  <x:anchor-alias value="rank"/>
     2033<t>
     2034   The "TE" header field in a request indicates what transfer-codings,
     2035   besides "chunked", the client is willing to accept in response, and
     2036   whether or not the client is willing to accept trailer fields in a
     2037   chunked transfer-coding.
     2038</t>
     2039<t>
     2040   The TE field-value consists of a comma-separated list of transfer-coding
     2041   names, each allowing for optional parameters (as described in
     2042   <xref target="transfer.codings"/>), and/or the keyword "trailers".
     2043   Clients &MUST-NOT; send the chunked transfer-coding name in TE;
     2044   chunked is always acceptable for HTTP/1.1 recipients.
     2045</t>
     2046<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"/>
    20522047  <x:ref>TE</x:ref>        = #<x:ref>t-codings</x:ref>
    2053   <x:ref>t-codings</x:ref> = "trailers" / ( <x:ref>transfer-extension</x:ref> [ <x:ref>te-params</x:ref> ] )
    2054   <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> )
    2055   <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> ]
     2048  <x:ref>t-codings</x:ref> = "trailers" / ( <x:ref>transfer-coding</x:ref> [ <x:ref>t-ranking</x:ref> ] )
     2049  <x:ref>t-ranking</x:ref> = <x:ref>OWS</x:ref> ";" <x:ref>OWS</x:ref> "q=" <x:ref>rank</x:ref>
     2050  <x:ref>rank</x:ref>      = ( "0" [ "." 0*3<x:ref>DIGIT</x:ref> ] )
     2051             / ( "1" [ "." 0*3("0") ] )
    20562052</artwork></figure>
    20572053<t>
    2058    The presence of the keyword "trailers" indicates that the client is
    2059    willing to accept trailer fields in a chunked transfer-coding, as
    2060    defined in <xref target="chunked.encoding"/>. This keyword is reserved for use with
    2061    transfer-coding values even though it does not itself represent a
    2062    transfer-coding.
    2063 </t>
    2064 <t>
    2065    Examples of its use are:
     2054   Three examples of TE use are below.
    20662055</t>
    20672056<figure><artwork type="example">
     
    20712060</artwork></figure>
    20722061<t>
    2073    The TE header field only applies to the immediate connection.
    2074    Therefore, the keyword &MUST; be supplied within a <x:ref>Connection</x:ref>
    2075    header field (<xref target="header.connection"/>) whenever TE is present in
    2076    an HTTP/1.1 message.
    2077 </t>
    2078 <t>
    2079    A server tests whether a transfer-coding is acceptable, according to
    2080    a TE field, using these rules:
    2081   <list style="numbers">
    2082     <x:lt>
    2083       <t>The "chunked" transfer-coding is always acceptable. If the
    2084          keyword "trailers" is listed, the client indicates that it is
    2085          willing to accept trailer fields in the chunked response on
    2086          behalf of itself and any downstream clients. The implication is
    2087          that, if given, the client is stating that either all
    2088          downstream clients are willing to accept trailer fields in the
    2089          forwarded response, or that it will attempt to buffer the
    2090          response on behalf of downstream recipients.
    2091       </t><t>
    2092          &Note; HTTP/1.1 does not define any means to limit the size of a
    2093          chunked response such that a client can be assured of buffering
    2094          the entire response.</t>
    2095     </x:lt>
    2096     <x:lt>
    2097       <t>If the transfer-coding being tested is one of the transfer-codings
    2098          listed in the TE field, then it is acceptable unless it
    2099          is accompanied by a qvalue of 0. (As defined in <xref target="quality.values"/>, a
    2100          qvalue of 0 means "not acceptable".)</t>
    2101     </x:lt>
    2102     <x:lt>
    2103       <t>If multiple transfer-codings are acceptable, then the
    2104          acceptable transfer-coding with the highest non-zero qvalue is
    2105          preferred.  The "chunked" transfer-coding always has a qvalue
    2106          of 1.</t>
    2107     </x:lt>
    2108   </list>
     2062   The presence of the keyword "trailers" indicates that the client is
     2063   willing to accept trailer fields in a chunked transfer-coding,
     2064   as defined in <xref target="chunked.encoding"/>, on behalf of itself and
     2065   any downstream clients. For chained requests, this implies that either:
     2066   (a) all downstream clients are willing to accept trailer fields in the
     2067   forwarded response; or,
     2068   (b) the client will attempt to buffer the response on behalf of downstream
     2069   recipients.
     2070   Note that HTTP/1.1 does not define any means to limit the size of a
     2071   chunked response such that a client can be assured of buffering the
     2072   entire response.
     2073</t>
     2074<t>
     2075   When multiple transfer-codings are acceptable, the client &MAY; rank the
     2076   codings by preference using a "q" parameter (similar to the qvalues
     2077   used in content negotiation fields, &qvalue;). The rank value is a real
     2078   number in the range 0 through 1, where 0.001 is the least preferred and
     2079   1 is the most preferred; a value of 0 means "not acceptable".
    21092080</t>
    21102081<t>
    21112082   If the TE field-value is empty or if no TE field is present, the only
    2112    acceptable transfer-coding is "chunked". A message with no transfer-coding is
    2113    always acceptable.
    2114 </t>
    2115 
    2116 <section title="Quality Values" anchor="quality.values">
    2117   <x:anchor-alias value="qvalue"/>
    2118 <t>
    2119    Both transfer codings (<x:ref>TE</x:ref> request header field,
    2120    <xref target="header.te"/>) and content negotiation (&content.negotiation;)
    2121    use short "floating point" numbers to indicate the relative importance
    2122    ("weight") of various negotiable parameters.  A weight is normalized to a
    2123    real number in the range 0 through 1, where 0 is the minimum and 1 the
    2124    maximum value. If a parameter has a quality value of 0, then content with
    2125    this parameter is "not acceptable" for the client. HTTP/1.1
    2126    applications &MUST-NOT; generate more than three digits after the
    2127    decimal point. User configuration of these values &SHOULD; also be
    2128    limited in this fashion.
    2129 </t>
    2130 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="qvalue"/>
    2131   <x:ref>qvalue</x:ref>         = ( "0" [ "." 0*3<x:ref>DIGIT</x:ref> ] )
    2132                  / ( "1" [ "." 0*3("0") ] )
    2133 </artwork></figure>
    2134 <x:note>
    2135   <t>
    2136      &Note; "Quality values" is a misnomer, since these values merely represent
    2137      relative degradation in desired quality.
    2138   </t>
    2139 </x:note>
    2140 </section>
     2083   acceptable transfer-coding is "chunked". A message with no transfer-coding
     2084   is always acceptable.
     2085</t>
     2086<t>
     2087   Since the TE header field only applies to the immediate connection,
     2088   a sender of TE &MUST; also send a "TE" connection option within the
     2089   <x:ref>Connection</x:ref> header field (<xref target="header.connection"/>)
     2090   in order to prevent the TE field from being forwarded by intermediaries
     2091   that do not support its semantics.
     2092</t>
    21412093</section>
    21422094
     
    35853537<t>
    35863538   Names of transfer codings &MUST-NOT; overlap with names of content codings
    3587    (&content-codings;) unless the encoding transformation is identical, as it
     3539   (&content-codings;) unless the encoding transformation is identical, as
    35883540   is the case for the compression codings defined in
    35893541   <xref target="compression.codings"/>.
     
    35933545   <xref target="RFC5226" x:fmt="of" x:sec="4.1"/>), and &MUST;
    35943546   conform to the purpose of transfer coding defined in this section.
     3547   Use of program names for the identification of encoding formats
     3548   is not desirable and is discouraged for future encodings.
    35953549</t>
    35963550<t>
     
    51915145<x:ref>quoted-str-nf</x:ref> = DQUOTE *( qdtext-nf / quoted-pair ) DQUOTE
    51925146<x:ref>quoted-string</x:ref> = DQUOTE *( qdtext / quoted-pair ) DQUOTE
    5193 <x:ref>qvalue</x:ref> = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] )
    5194 
     5147
     5148<x:ref>rank</x:ref> = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] )
    51955149<x:ref>reason-phrase</x:ref> = *( HTAB / SP / VCHAR / obs-text )
    51965150<x:ref>received-by</x:ref> = ( uri-host [ ":" port ] ) / pseudonym
     
    52075161<x:ref>status-line</x:ref> = HTTP-version SP status-code SP reason-phrase CRLF
    52085162
    5209 <x:ref>t-codings</x:ref> = "trailers" / ( transfer-extension [ te-params ] )
     5163<x:ref>t-codings</x:ref> = "trailers" / ( transfer-coding [ t-ranking ] )
     5164<x:ref>t-ranking</x:ref> = OWS ";" OWS "q=" rank
    52105165<x:ref>tchar</x:ref> = "!" / "#" / "$" / "%" / "&amp;" / "'" / "*" / "+" / "-" / "." /
    52115166 "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
    5212 <x:ref>te-ext</x:ref> = OWS ";" OWS token [ "=" word ]
    5213 <x:ref>te-params</x:ref> = OWS ";" OWS "q=" qvalue *te-ext
    52145167<x:ref>token</x:ref> = 1*tchar
    52155168<x:ref>trailer-part</x:ref> = *( header-field CRLF )
Note: See TracChangeset for help on using the changeset viewer.