Ignore:
Timestamp:
12/11/08 22:09:04 (12 years ago)
Author:
mnot@…
Message:

Refactor Warning as per <​http://www.w3.org/mid/908D4531-41D4-4DBE-803F-AD74281F3994@mnot.net>; tweak abstract, intro.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • draft-ietf-httpbis/latest-roy/p6-cache.xml

    r345 r347  
    193193   The Hypertext Transfer Protocol (HTTP) is an application-level
    194194   protocol for distributed, collaborative, hypermedia information
    195    systems. HTTP has been in use by the World Wide Web global information
    196    initiative since 1990. This document is Part 6 of the seven-part specification
     195   systems.
     196   This document is Part 6 of the seven-part specification
    197197   that defines the protocol referred to as "HTTP/1.1" and, taken together,
    198198   obsoletes RFC 2616.  Part 6 defines requirements on HTTP caches
    … …  
    219219<t>
    220220   HTTP is typically used for distributed information systems, where
    221    performance can be improved by the use of response caches, and includes
    222    a number of elements intended to make caching work as well as possible.
    223    Because these elements interact with each other, it is useful to describe
    224    the caching design of HTTP separately.  This document defines aspects of
    225    HTTP/1.1 related to caching and reusing response messages.
     221   performance can be improved by the use of response caches.  This document
     222   defines aspects of HTTP/1.1 related to caching and reusing response messages.
    226223</t>
    227224
    … …  
    521518   &MUST; attach a warning to that effect, using a Warning general-header.
    522519   The Warning header and the currently defined warnings are described
    523    in <xref target="header.warning"/>. The warning allows clients to take appropriate
    524    action.
    525 </t>
    526 <t>
    527    Warnings &MAY; be used for other purposes, both cache-related and
    528    otherwise. The use of a warning, rather than an error status code,
    529    distinguish these responses from true failures.
    530 </t>
    531 <t>
    532    Warnings are assigned three digit warn-codes. The first digit
    533    indicates whether the Warning &MUST; or &MUST-NOT; be deleted from a
    534    stored cache entry after a successful revalidation:
    535 </t>
    536 <t>
    537   <list style="hanging">
    538     <t hangText="1xx">Warnings that describe the freshness or revalidation status of
    539      the response, and so &MUST; be deleted after a successful
    540      revalidation. 1xx warn-codes &MAY; be generated by a cache only when
    541      validating a cached entry. It &MUST-NOT; be generated by clients.</t>
    542 
    543     <t hangText="2xx">Warnings that describe some aspect of the entity body or entity
    544      headers that is not rectified by a revalidation (for example, a
    545      lossy compression of the entity bodies) and which &MUST-NOT; be
    546      deleted after a successful revalidation.</t>
    547     </list>
    548 </t>
    549 <t>
    550    See <xref target="header.warning"/> for the definitions of the codes themselves.
    551 </t>
    552 <t>
    553    HTTP/1.0 caches will cache all Warnings in responses, without
    554    deleting the ones in the first category. Warnings in responses that
    555    are passed to HTTP/1.0 caches carry an extra warning-date field,
    556    which prevents a future HTTP/1.1 recipient from believing an
    557    erroneously cached Warning.
    558 </t>
    559 <t>
    560    Warnings also carry a warning text. The text &MAY; be in any
    561    appropriate natural language (perhaps based on the client's Accept
    562    headers), and include an &OPTIONAL; indication of what character set is
    563    used.
    564 </t>
    565 <t>
    566    Multiple warnings &MAY; be attached to a response (either by the origin
    567    server or by a cache), including multiple warnings with the same code
    568    number. For example, a server might provide the same warning with
    569    texts in both English and Basque.
    570 </t>
    571 <t>
    572    When multiple warnings are attached to a response, it might not be
    573    practical or reasonable to display all of them to the user. This
    574    version of HTTP does not specify strict priority rules for deciding
    575    which warnings to display and in what order, but does suggest some
    576    heuristics.
     520   in <xref target="header.warning"/>.
    577521</t>
    578522</section>
    … …  
    22592203</t>
    22602204<t>
    2261    Warning headers are sent with responses using:
    2262 </t>
     2205   Warnings MAY be used for other purposes, both cache-related and
     2206   otherwise.  The use of a warning, rather than an error status code,
     2207   distinguish these responses from true failures.
     2208</t>
     2209
     2210<t>
     2211   Warning headers can in general be applied to any message, however
     2212   some warn-codes are specific to caches and can only be
     2213   applied to response messages.
     2214</t>
     2215
    22632216<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Warning"/><iref primary="true" item="Grammar" subitem="warning-value"/><iref primary="true" item="Grammar" subitem="warn-code"/><iref primary="true" item="Grammar" subitem="warn-agent"/><iref primary="true" item="Grammar" subitem="warn-text"/><iref primary="true" item="Grammar" subitem="warn-date"/>
    22642217  <x:ref>Warning</x:ref>    = "Warning" ":" 1#<x:ref>warning-value</x:ref>
    … …  
    22742227  <x:ref>warn-date</x:ref>  = <x:ref>DQUOTE</x:ref> <x:ref>HTTP-date</x:ref> <x:ref>DQUOTE</x:ref>
    22752228</artwork></figure>
    2276 <t>
    2277    A response &MAY; carry more than one Warning header.
     2229
     2230<t>
     2231   Multiple warnings &MAY; be attached to a response (either by the origin
     2232   server or by a cache), including multiple warnings with the same code
     2233   number.  For example, a server might provide the same warning with
     2234   texts in both English and Basque.
     2235</t>
     2236<t>
     2237   When this occurs, the user agent ought to inform the user of as many
     2238   of them as possible, in the order that they appear in the response. 
     2239   If it is not possible to inform the user of all of the warnings,
     2240   the user agent SHOULD follow these heuristics:
     2241  <list style="symbols">
     2242    <t>Warnings that appear early in the response take priority over
     2243        those appearing later in the response.</t>
     2244
     2245    <t>Warnings in the user's preferred character set take priority
     2246        over warnings in other character sets but with identical warn-codes
     2247        and warn-agents.</t>
     2248  </list>
     2249</t>
     2250<t>
     2251   Systems that generate multiple Warning headers &SHOULD; order them with
     2252   this user agent behavior in mind. New Warning headers &SHOULD; be added
     2253  after any existing Warning headers.
     2254</t>
     2255<t>
     2256   Warnings are assigned three digit warn-codes.  The first digit
     2257   indicates whether the Warning is required to be deleted from a
     2258   stored cache entry after validation:
     2259   <list style="symbols">
     2260         <t>1xx  Warnings that describe the freshness or revalidation status of
     2261             the response, and so MUST be deleted by caches after validation.</t>
     2262         <t> 2xx  Warnings that describe some aspect of the entity body or entity
     2263             headers that is not rectified by a revalidation (for example, a
     2264             lossy compression of the entity bodies) and which MUST NOT be
     2265             deleted by caches after validation, unless a full response is
     2266             returned, in which case they MUST be.</t>
     2267   </list>
    22782268</t>
    22792269<t>
    … …  
    22902280</t>
    22912281<t>
    2292    Warning headers can in general be applied to any message, however
    2293    some specific warn-codes are specific to caches and can only be
    2294    applied to response messages. New Warning headers &SHOULD; be added
    2295    after any existing Warning headers. A cache &MUST-NOT; delete any
    2296    Warning header that it received with a message. However, if a cache
    2297    successfully validates a cache entry, it &SHOULD; remove any Warning
    2298    headers previously attached to that entry except as specified for
    2299    specific Warning codes. It &MUST; then add any Warning headers received
    2300    in the validating response. In other words, Warning headers are those
    2301    that would be attached to the most recent relevant response.
    2302 </t>
    2303 <t>
    2304    When multiple Warning headers are attached to a response, the user
    2305    agent ought to inform the user of as many of them as possible, in the
    2306    order that they appear in the response. If it is not possible to
    2307    inform the user of all of the warnings, the user agent &SHOULD; follow
    2308    these heuristics:
    2309   <list style="symbols">
    2310     <t>Warnings that appear early in the response take priority over
    2311         those appearing later in the response.</t>
    2312 
    2313     <t>Warnings in the user's preferred character set take priority
    2314         over warnings in other character sets but with identical warn-codes
    2315         and warn-agents.</t>
    2316   </list>
    2317 </t>
    2318 <t>
    2319    Systems that generate multiple Warning headers &SHOULD; order them with
    2320    this user agent behavior in mind.
    2321 </t>
    2322 <t>
    2323    Requirements for the behavior of caches with respect to Warnings are
    2324    stated in <xref target="warnings"/>.
    2325 </t>
    2326 <t>
    2327    This is a list of the currently-defined warn-codes, each with a
     2282   If an implementation sends a message with one or more Warning headers
     2283   to a receiver whose version is HTTP/1.0 or lower, then the sender &MUST;
     2284   include in each warning-value a warn-date that matches the Date header
     2285   in the message.
     2286</t>
     2287<t>
     2288   If an implementation receives a message with a warning-value that
     2289   includes a warn-date, and that warn-date is different from the Date
     2290   value in the response, then that warning-value &MUST; be deleted from
     2291   the message before storing, forwarding, or using it.  (This prevents
     2292   bad consequences of naive caching of Warning header fields.)  If all
     2293   of the warning-values are deleted for this reason, the Warning header
     2294   &MUST; be deleted as well.
     2295</t>
     2296<t>
     2297   The following warn-codes are defined by this specification, each with a
    23282298   recommended warn-text in English, and a description of its meaning.
    23292299</t>
    … …  
    23832353     take any automated action.
    23842354  </t></list>
    2385 </t>
    2386 <t>
    2387    If an implementation sends a message with one or more Warning headers
    2388    whose version is HTTP/1.0 or lower, then the sender &MUST; include in
    2389    each warning-value a warn-date that matches the date in the response.
    2390 </t>
    2391 <t>
    2392    If an implementation receives a message with a warning-value that
    2393    includes a warn-date, and that warn-date is different from the Date
    2394    value in the response, then that warning-value &MUST; be deleted from
    2395    the message before storing, forwarding, or using it. (This prevents
    2396    bad consequences of naive caching of Warning header fields.) If all
    2397    of the warning-values are deleted for this reason, the Warning header
    2398    &MUST; be deleted as well.
    23992355</t>
    24002356</section>
Note: See TracChangeset for help on using the changeset viewer.