Ignore:
Timestamp:
13/09/13 11:47:00 (8 years ago)
Author:
fielding@…
Message:

Reduce the burden of processing warn-date to recipients that do something with Warning fields; use warn-code section titles to demonstrate syntax examples (and differentiate from status codes); clarify tortured wording around Age; demonstrate 4am mastery of xslt; addresses #486

File:
1 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p6-cache.xml

    r2383 r2384  
    2020  <!ENTITY conformance                 "<xref target='Part1' x:rel='#conformance' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    2121  <!ENTITY notation                    "<xref target='Part1' x:rel='#notation' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    22   <!ENTITY abnf-extension             "<xref target='Part1' x:rel='#abnf.extension' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
     22  <!ENTITY abnf-extension              "<xref target='Part1' x:rel='#abnf.extension' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    2323  <!ENTITY acks                        "<xref target='Part1' x:rel='#acks' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    2424  <!ENTITY whitespace                  "<xref target='Part1' x:rel='#whitespace' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
     
    674674<t>
    675675   When a heuristic is used to calculate freshness lifetime, a cache &SHOULD;
    676    attach a <x:ref>Warning</x:ref> header field with a 113 warn-code to the
     676   generate a <x:ref>Warning</x:ref> header field with a 113 warn-code in the
    677677   response if its current_age is more than 24 hours and such a warning is not
    678678   already present.
     
    815815</t>
    816816<t>
    817    A cache &SHOULD; append a <x:ref>Warning</x:ref> header field with the 110
    818    warn-code (see <xref target="header.warning"/>) to stale responses.
    819    Likewise, a cache &SHOULD; add the 112 warn-code to stale responses if the
    820    cache is disconnected.
    821 </t>
    822 <iref item="first-hand" />
    823 <t>
    824    Note that if a cache receives a <x:dfn>first-hand</x:dfn> response (one
    825    where the freshness model is not in use; i.e., its age is 0, whether it is
    826    an entire response, or a <x:ref>304 (Not Modified)</x:ref> response) that
    827    it would normally forward to the requesting client, and the received
    828    response is no longer fresh, the cache &MAY; forward it to the requesting
    829    client without adding a new <x:ref>Warning</x:ref> (but without removing
    830    any existing Warning header fields). A cache ought not attempt to validate
    831    a response simply because that response became stale in transit.
     817   A cache &SHOULD; generate a <x:ref>Warning</x:ref> header field with the
     818   110 warn-code (see <xref target="header.warning"/>) in stale responses.
     819   Likewise, a cache &SHOULD; generate a 112 warn-code in stale responses
     820   if the cache is disconnected.
     821</t>
     822<t>
     823   A cache &SHOULD-NOT; generate a new <x:ref>Warning</x:ref> header field
     824   when forwarding a response that does not have an <x:ref>Age</x:ref> header
     825   field, even if the response is already stale.  A cache need not validate
     826   a response that merely became stale in transit.
    832827</t>
    833828</section>
     
    11641159</artwork></figure>
    11651160<t>
    1166   Age field-values are non-negative integers, representing time in seconds
    1167   (see <xref target="delta-seconds"/>).
    1168 </t>
    1169 <t>
    1170    The presence of an Age header field in a response implies that a response
    1171    is not first-hand. However, the converse is not true, since HTTP/1.0 caches
    1172    might not implement the Age header field.
     1161   The Age field-value is a non-negative integer, representing time in seconds
     1162   (see <xref target="delta-seconds"/>).
     1163</t>
     1164<t>
     1165   The presence of an Age header field implies that the response was not
     1166   generated or validated by the origin server for this request. However,
     1167   lack of an Age header field does not imply the origin was contacted, since
     1168   the response might have been received from an HTTP/1.0 cache that does not
     1169   implement Age.
    11731170</t>
    11741171</section>
     
    17361733   The "Warning" header field is used to carry additional information
    17371734   about the status or transformation of a message that might not be reflected
    1738    in the message. This information is typically used to warn about possible
     1735   in the status code. This information is typically used to warn about possible
    17391736   incorrectness introduced by caching operations or transformations applied
    17401737   to the payload of the message.
     
    17641761</artwork></figure>
    17651762<t>
    1766    Multiple warnings can be attached to a response (either by the origin
    1767    server or by a cache), including multiple warnings with the same code
    1768    number, only differing in warn-text.
    1769 </t>
    1770 <t>
    1771    When this occurs, the user agent &SHOULD; inform the user of as many of
    1772    them as possible, in the order that they appear in the response.
    1773 </t>
    1774 <t>
    1775    Systems that generate multiple Warning header fields are encouraged to
    1776    order them with this user agent behavior in mind. New Warning header fields
    1777    are added after any existing Warning header fields.
     1763   Multiple warnings can be generated in a response (either by the origin
     1764   server or by a cache), including multiple warnings with the same warn-code
     1765   number that only differ in warn-text.
     1766</t>
     1767<t>
     1768   A user agent that receives one or more Warning header fields &SHOULD;
     1769   inform the user of as many of them as possible, in the order that they
     1770   appear in the response. Senders that generate multiple Warning header
     1771   fields are encouraged to order them with this user agent behavior in mind.
     1772   A sender that generates new Warning header fields &MUST; append them after
     1773   any existing Warning header fields.
    17781774</t>
    17791775<t>
     
    17821778   validation:
    17831779   <list style="symbols">
    1784       <t>1xx Warnings describe the freshness or validation status of the
     1780      <t>1xx warn-codes describe the freshness or validation status of the
    17851781      response, and so &MUST; be deleted by a cache after validation. They can
    17861782      only be generated by a cache when validating a cached entry, and
    17871783      &MUST-NOT; be generated in any other situation.</t>
    1788       <t>2xx Warnings describe some aspect of the representation that is not
     1784      <t>2xx warn-codes describe some aspect of the representation that is not
    17891785      rectified by a validation (for example, a lossy compression of the
    17901786      representation) and &MUST-NOT; be deleted by a cache after validation,
     
    17931789</t>
    17941790<t>
    1795    If an implementation sends a message with one or more Warning header fields
    1796    to a receiver whose version is HTTP/1.0 or lower, then the sender &MUST;
    1797    include in each warning-value a warn-date that matches the
     1791   If a sender generates one or more Warning header fields in a message to be
     1792   sent to a recipient known to implement only HTTP/1.0, the sender &MUST;
     1793   include in each generated warning-value a warn-date that matches the
    17981794   <x:ref>Date</x:ref> header field in the message.
    17991795</t>
    18001796<t>
    1801    If a system receives a message with a warning-value that includes a
    1802    warn-date, and that warn-date is different from the <x:ref>Date</x:ref>
    1803    value in the response, then that warning-value &MUST; be deleted from the
    1804    message before storing, forwarding, or using it (preventing the
    1805    consequences of naive caching of Warning header fields). If all of the
    1806    warning-values are deleted for this reason, the Warning header field &MUST;
    1807    be deleted as well.
     1797   If a recipient that uses, evaluates, or displays Warning header fields
     1798   receives a warn-date that is different from the <x:ref>Date</x:ref> value
     1799   in the same message, the recipient &MUST; exclude the warning-value
     1800   containing that warn-date before storing, forwarding, or using the message.
     1801   This allows recipients to exclude warning-values that were improperly
     1802   retained after a cache validation.
     1803   If all of the warning-values are excluded, the recipient &MUST; exclude
     1804   the Warning header field as well.
    18081805</t>
    18091806<t>
    18101807   The following warn-codes are defined by this specification, each with a
    18111808   recommended warn-text in English, and a description of its meaning.
    1812 </t>
    1813 
    1814 <section title="110 Response is Stale" anchor="warn.110">
    1815   <iref primary="true" item="110 Response is Stale (warn code)" x:for-anchor=""/>
     1809   The procedure for defining additional warn codes is described in
     1810   <xref target="warn.code.registry.procedure"/>.
     1811</t>
     1812
     1813<section title='Warning: 110 means "Response is Stale"' anchor="warn.110">
     1814  <iref primary="true" item="110 (warn-code)" x:for-anchor=""/>
     1815  <iref primary="true" item="Response is Stale (warn-text)" x:for-anchor=""/>
    18161816<t>
    18171817   A cache &SHOULD; generate this whenever the sent response is stale.
     
    18191819</section>
    18201820
    1821 <section title="111 Revalidation Failed" anchor="warn.111">
    1822   <iref primary="true" item="111 Revalidation Failed (warn code)" x:for-anchor=""/>
     1821<section title='Warning: 111 means "Revalidation Failed"' anchor="warn.111">
     1822  <iref primary="true" item="111 (warn-code)" x:for-anchor=""/>
     1823  <iref primary="true" item="Revalidation Failed (warn-text)" x:for-anchor=""/>
    18231824<t>
    18241825   A cache &SHOULD; generate this when sending a stale response because an
     
    18281829</section>
    18291830
    1830 <section title="112 Disconnected Operation" anchor="warn.112">
    1831   <iref primary="true" item="112 Disconnected Operation (warn code)" x:for-anchor=""/>
     1831<section title='Warning: 112 means "Disconnected Operation"' anchor="warn.112">
     1832  <iref primary="true" item="112 (warn-code)" x:for-anchor=""/>
     1833  <iref primary="true" item="Disconnected Operation (warn-text)" x:for-anchor=""/>
    18321834<t>
    18331835   A cache &SHOULD; generate this if it is intentionally disconnected from
     
    18361838</section>
    18371839
    1838 <section title="113 Heuristic Expiration" anchor="warn.113">
    1839   <iref primary="true" item="113 Heuristic Expiration (warn code)" x:for-anchor=""/>
     1840<section title='Warning: 113 means "Heuristic Expiration"' anchor="warn.113">
     1841  <iref primary="true" item="113 (warn-code)" x:for-anchor=""/>
     1842  <iref primary="true" item="Heuristic Expiration (warn-text)" x:for-anchor=""/>
    18401843<t>
    18411844   A cache &SHOULD; generate this if it heuristically chose a freshness
     
    18451848</section>
    18461849
    1847 <section title="199 Miscellaneous Warning" anchor="warn.199">
    1848   <iref primary="true" item="199 Miscellaneous Warning (warn code)" x:for-anchor=""/>
     1850<section title='Warning: 199 means "Miscellaneous Warning"' anchor="warn.199">
     1851  <iref primary="true" item="199 (warn-code)" x:for-anchor=""/>
     1852  <iref primary="true" item="Miscellaneous Warning (warn-text)" x:for-anchor=""/>
    18491853<t>
    18501854   The warning text can include arbitrary information to be presented to
     
    18541858</section>
    18551859
    1856 <section title="214 Transformation Applied" anchor="warn.214">
    1857   <iref primary="true" item="214 Transformation Applied (warn code)" x:for-anchor=""/>
     1860<section title='Warning: 214 means "Transformation Applied"' anchor="warn.214">
     1861  <iref primary="true" item="214 (warn-code)" x:for-anchor=""/>
     1862  <iref primary="true" item="Transformation Applied (warn-text)" x:for-anchor=""/>
    18581863<t>
    18591864   &MUST; be added by a proxy if it applies any transformation to the
     
    18641869</section>
    18651870
    1866 <section title="299 Miscellaneous Persistent Warning" anchor="warn.299">
    1867   <iref primary="true" item="299 Miscellaneous Persistent Warning (warn code)" x:for-anchor=""/>
     1871<section title='Warning: 299 means "Miscellaneous Persistent Warning"' anchor="warn.299">
     1872  <iref primary="true" item="299 (warn-code)" x:for-anchor=""/>
     1873  <iref primary="true" item="Miscellaneous Persistent Warning (warn-text)" x:for-anchor=""/>
    18681874<t>
    18691875   The warning text can include arbitrary information to be presented to
    18701876   a human user, or logged. A system receiving this warning &MUST-NOT; take
    18711877   any automated action.
    1872 </t>
    1873 </section>
    1874 
    1875 <section title="Warn Code Extensions" anchor="warn.code.extensions">
    1876 <t>
    1877    Extension warn codes can be defined; see <xref target="warn.code.registry.procedure"/>
    1878    for details.
    18791878</t>
    18801879</section>
     
    26602659<x:ref>warn-date</x:ref> = DQUOTE HTTP-date DQUOTE
    26612660<x:ref>warn-text</x:ref> = quoted-string
    2662 <x:ref>warning-value</x:ref> = warn-code SP warn-agent SP warn-text SP warn-date
     2661<x:ref>warning-value</x:ref> = warn-code SP warn-agent SP warn-text [ SP warn-date ]
    26632662</artwork>
    26642663</figure>
Note: See TracChangeset for help on using the changeset viewer.