Ignore:
Timestamp:
24/09/13 01:14:46 (9 years ago)
Author:
fielding@…
Message:

add example Warning and recommend - be used as pseudonym when name is unknown; addresses #496

File:
1 edited

Legend:

Unmodified
Added
Removed

  • draft-ietf-httpbis/latest/p6-cache.html

    r2408 r2409  
    638638               <li><a href="#rfc.section.5.4">5.4</a>&nbsp;&nbsp;&nbsp;<a href="#header.pragma">Pragma</a></li>
    639639               <li><a href="#rfc.section.5.5">5.5</a>&nbsp;&nbsp;&nbsp;<a href="#header.warning">Warning</a><ul>
    640                      <li><a href="#rfc.section.5.5.1">5.5.1</a>&nbsp;&nbsp;&nbsp;<a href="#warn.110">Warning: 110 means "Response is Stale"</a></li>
    641                      <li><a href="#rfc.section.5.5.2">5.5.2</a>&nbsp;&nbsp;&nbsp;<a href="#warn.111">Warning: 111 means "Revalidation Failed"</a></li>
    642                      <li><a href="#rfc.section.5.5.3">5.5.3</a>&nbsp;&nbsp;&nbsp;<a href="#warn.112">Warning: 112 means "Disconnected Operation"</a></li>
    643                      <li><a href="#rfc.section.5.5.4">5.5.4</a>&nbsp;&nbsp;&nbsp;<a href="#warn.113">Warning: 113 means "Heuristic Expiration"</a></li>
    644                      <li><a href="#rfc.section.5.5.5">5.5.5</a>&nbsp;&nbsp;&nbsp;<a href="#warn.199">Warning: 199 means "Miscellaneous Warning"</a></li>
    645                      <li><a href="#rfc.section.5.5.6">5.5.6</a>&nbsp;&nbsp;&nbsp;<a href="#warn.214">Warning: 214 means "Transformation Applied"</a></li>
    646                      <li><a href="#rfc.section.5.5.7">5.5.7</a>&nbsp;&nbsp;&nbsp;<a href="#warn.299">Warning: 299 means "Miscellaneous Persistent Warning"</a></li>
     640                     <li><a href="#rfc.section.5.5.1">5.5.1</a>&nbsp;&nbsp;&nbsp;<a href="#warn.110">Warning: 110 - "Response is Stale"</a></li>
     641                     <li><a href="#rfc.section.5.5.2">5.5.2</a>&nbsp;&nbsp;&nbsp;<a href="#warn.111">Warning: 111 - "Revalidation Failed"</a></li>
     642                     <li><a href="#rfc.section.5.5.3">5.5.3</a>&nbsp;&nbsp;&nbsp;<a href="#warn.112">Warning: 112 - "Disconnected Operation"</a></li>
     643                     <li><a href="#rfc.section.5.5.4">5.5.4</a>&nbsp;&nbsp;&nbsp;<a href="#warn.113">Warning: 113 - "Heuristic Expiration"</a></li>
     644                     <li><a href="#rfc.section.5.5.5">5.5.5</a>&nbsp;&nbsp;&nbsp;<a href="#warn.199">Warning: 199 - "Miscellaneous Warning"</a></li>
     645                     <li><a href="#rfc.section.5.5.6">5.5.6</a>&nbsp;&nbsp;&nbsp;<a href="#warn.214">Warning: 214 - "Transformation Applied"</a></li>
     646                     <li><a href="#rfc.section.5.5.7">5.5.7</a>&nbsp;&nbsp;&nbsp;<a href="#warn.299">Warning: 299 - "Miscellaneous Persistent Warning"</a></li>
    647647                  </ul>
    648648               </li>
    … …  
    953953         time. A typical setting of this fraction might be 10%.
    954954      </p>
    955       <p id="rfc.section.4.2.2.p.4">When a heuristic is used to calculate freshness lifetime, a cache <em class="bcp14">SHOULD</em> generate a <a href="#header.warning" class="smpl">Warning</a> header field with a 113 warn-code (see <a href="#warn.113" id="rfc.xref.warn.113.1" title="Warning: 113 means &#34;Heuristic Expiration&#34;">Section&nbsp;5.5.4</a>) in the response if its current_age is more than 24 hours and such a warning is not already present.
     955      <p id="rfc.section.4.2.2.p.4">When a heuristic is used to calculate freshness lifetime, a cache <em class="bcp14">SHOULD</em> generate a <a href="#header.warning" class="smpl">Warning</a> header field with a 113 warn-code (see <a href="#warn.113" id="rfc.xref.warn.113.1" title="Warning: 113 - &#34;Heuristic Expiration&#34;">Section&nbsp;5.5.4</a>) in the response if its current_age is more than 24 hours and such a warning is not already present.
    956956      </p>
    957957      <div class="note" id="rfc.section.4.2.2.p.5">
    … …  
    10281028         or doing so is explicitly allowed (e.g., by the max-stale request directive; see <a href="#cache-request-directive" title="Request Cache-Control Directives">Section&nbsp;5.2.1</a>).
    10291029      </p>
    1030       <p id="rfc.section.4.2.4.p.4">A cache <em class="bcp14">SHOULD</em> generate a <a href="#header.warning" class="smpl">Warning</a> header field with the 110 warn-code (see <a href="#warn.110" id="rfc.xref.warn.110.1" title="Warning: 110 means &#34;Response is Stale&#34;">Section&nbsp;5.5.1</a>) in stale responses. Likewise, a cache <em class="bcp14">SHOULD</em> generate a 112 warn-code (see <a href="#warn.112" id="rfc.xref.warn.112.1" title="Warning: 112 means &#34;Disconnected Operation&#34;">Section&nbsp;5.5.3</a>) in stale responses if the cache is disconnected.
     1030      <p id="rfc.section.4.2.4.p.4">A cache <em class="bcp14">SHOULD</em> generate a <a href="#header.warning" class="smpl">Warning</a> header field with the 110 warn-code (see <a href="#warn.110" id="rfc.xref.warn.110.1" title="Warning: 110 - &#34;Response is Stale&#34;">Section&nbsp;5.5.1</a>) in stale responses. Likewise, a cache <em class="bcp14">SHOULD</em> generate a 112 warn-code (see <a href="#warn.112" id="rfc.xref.warn.112.1" title="Warning: 112 - &#34;Disconnected Operation&#34;">Section&nbsp;5.5.3</a>) in stale responses if the cache is disconnected.
    10311031      </p>
    10321032      <p id="rfc.section.4.2.4.p.5">A cache <em class="bcp14">SHOULD NOT</em> generate a new <a href="#header.warning" class="smpl">Warning</a> header field when forwarding a response that does not have an <a href="#header.age" class="smpl">Age</a> header field, even if the response is already stale. A cache need not validate a response that merely became stale in transit.
    … …  
    14601460                  ; the name or pseudonym of the server adding
    14611461                  ; the Warning header field, for use in debugging
     1462                  ; a single "-" is recommended when agent unknown
    14621463  <a href="#header.warning" class="smpl">warn-text</a>  = <a href="#imported.abnf" class="smpl">quoted-string</a>
    14631464  <a href="#header.warning" class="smpl">warn-date</a>  = <a href="#imported.abnf" class="smpl">DQUOTE</a> <a href="#imported.abnf" class="smpl">HTTP-date</a> <a href="#imported.abnf" class="smpl">DQUOTE</a>
    … …  
    14791480         </li>
    14801481      </ul>
    1481       <p id="rfc.section.5.5.p.8">If a sender generates one or more Warning header fields in a message to be sent to a recipient known to implement only HTTP/1.0,
    1482          the sender <em class="bcp14">MUST</em> include in each generated warning-value a warn-date that matches the <a href="p2-semantics.html#header.date" class="smpl">Date</a> header field in the message.
    1483       </p>
    1484       <p id="rfc.section.5.5.p.9">If a recipient that uses, evaluates, or displays Warning header fields receives a warn-date that is different from the <a href="p2-semantics.html#header.date" class="smpl">Date</a> value in the same message, the recipient <em class="bcp14">MUST</em> exclude the warning-value containing that warn-date before storing, forwarding, or using the message. This allows recipients
     1482      <p id="rfc.section.5.5.p.8">If a sender generates one or more 1xx warn-codes in a message to be sent to a recipient known to implement only HTTP/1.0,
     1483         the sender <em class="bcp14">MUST</em> include in each corresponding warning-value a warn-date that matches the <a href="p2-semantics.html#header.date" class="smpl">Date</a> header field in the message. For example:
     1484      </p>
     1485      <div id="rfc.figure.u.14"></div><pre class="text">HTTP/1.1 200 OK
     1486Date: Sat, 25 Aug 2012 23:34:45 GMT
     1487Warning: 112 - "network down" "Sat, 25 Aug 2012 23:34:45 GMT"
     1488
     1489</pre><p id="rfc.section.5.5.p.10">If a recipient that uses, evaluates, or displays Warning header fields receives a warn-date that is different from the <a href="p2-semantics.html#header.date" class="smpl">Date</a> value in the same message, the recipient <em class="bcp14">MUST</em> exclude the warning-value containing that warn-date before storing, forwarding, or using the message. This allows recipients
    14851490         to exclude warning-values that were improperly retained after a cache validation. If all of the warning-values are excluded,
    14861491         the recipient <em class="bcp14">MUST</em> exclude the Warning header field as well.
    14871492      </p>
    1488       <p id="rfc.section.5.5.p.10">The following warn-codes are defined by this specification, each with a recommended warn-text in English, and a description
     1493      <p id="rfc.section.5.5.p.11">The following warn-codes are defined by this specification, each with a recommended warn-text in English, and a description
    14891494         of its meaning. The procedure for defining additional warn codes is described in <a href="#warn.code.registry.procedure" title="Procedure">Section&nbsp;7.2.1</a>.
    14901495      </p>
    14911496      <div id="rfc.iref.49"></div>
    14921497      <div id="rfc.iref.r.1"></div>
    1493       <h3 id="rfc.section.5.5.1"><a href="#rfc.section.5.5.1">5.5.1</a>&nbsp;<a id="warn.110" href="#warn.110">Warning: 110 means "Response is Stale"</a></h3>
     1498      <h3 id="rfc.section.5.5.1"><a href="#rfc.section.5.5.1">5.5.1</a>&nbsp;<a id="warn.110" href="#warn.110">Warning: 110 - "Response is Stale"</a></h3>
    14941499      <p id="rfc.section.5.5.1.p.1">A cache <em class="bcp14">SHOULD</em> generate this whenever the sent response is stale.
    14951500      </p>
    14961501      <div id="rfc.iref.50"></div>
    14971502      <div id="rfc.iref.r.2"></div>
    1498       <h3 id="rfc.section.5.5.2"><a href="#rfc.section.5.5.2">5.5.2</a>&nbsp;<a id="warn.111" href="#warn.111">Warning: 111 means "Revalidation Failed"</a></h3>
     1503      <h3 id="rfc.section.5.5.2"><a href="#rfc.section.5.5.2">5.5.2</a>&nbsp;<a id="warn.111" href="#warn.111">Warning: 111 - "Revalidation Failed"</a></h3>
    14991504      <p id="rfc.section.5.5.2.p.1">A cache <em class="bcp14">SHOULD</em> generate this when sending a stale response because an attempt to validate the response failed, due to an inability to reach
    15001505         the server.
    … …  
    15021507      <div id="rfc.iref.51"></div>
    15031508      <div id="rfc.iref.d.1"></div>
    1504       <h3 id="rfc.section.5.5.3"><a href="#rfc.section.5.5.3">5.5.3</a>&nbsp;<a id="warn.112" href="#warn.112">Warning: 112 means "Disconnected Operation"</a></h3>
     1509      <h3 id="rfc.section.5.5.3"><a href="#rfc.section.5.5.3">5.5.3</a>&nbsp;<a id="warn.112" href="#warn.112">Warning: 112 - "Disconnected Operation"</a></h3>
    15051510      <p id="rfc.section.5.5.3.p.1">A cache <em class="bcp14">SHOULD</em> generate this if it is intentionally disconnected from the rest of the network for a period of time.
    15061511      </p>
    15071512      <div id="rfc.iref.52"></div>
    15081513      <div id="rfc.iref.h.2"></div>
    1509       <h3 id="rfc.section.5.5.4"><a href="#rfc.section.5.5.4">5.5.4</a>&nbsp;<a id="warn.113" href="#warn.113">Warning: 113 means "Heuristic Expiration"</a></h3>
     1514      <h3 id="rfc.section.5.5.4"><a href="#rfc.section.5.5.4">5.5.4</a>&nbsp;<a id="warn.113" href="#warn.113">Warning: 113 - "Heuristic Expiration"</a></h3>
    15101515      <p id="rfc.section.5.5.4.p.1">A cache <em class="bcp14">SHOULD</em> generate this if it heuristically chose a freshness lifetime greater than 24 hours and the response's age is greater than
    15111516         24 hours.
    … …  
    15131518      <div id="rfc.iref.53"></div>
    15141519      <div id="rfc.iref.m.6"></div>
    1515       <h3 id="rfc.section.5.5.5"><a href="#rfc.section.5.5.5">5.5.5</a>&nbsp;<a id="warn.199" href="#warn.199">Warning: 199 means "Miscellaneous Warning"</a></h3>
     1520      <h3 id="rfc.section.5.5.5"><a href="#rfc.section.5.5.5">5.5.5</a>&nbsp;<a id="warn.199" href="#warn.199">Warning: 199 - "Miscellaneous Warning"</a></h3>
    15161521      <p id="rfc.section.5.5.5.p.1">The warning text can include arbitrary information to be presented to a human user, or logged. A system receiving this warning <em class="bcp14">MUST NOT</em> take any automated action, besides presenting the warning to the user.
    15171522      </p>
    15181523      <div id="rfc.iref.54"></div>
    15191524      <div id="rfc.iref.t.1"></div>
    1520       <h3 id="rfc.section.5.5.6"><a href="#rfc.section.5.5.6">5.5.6</a>&nbsp;<a id="warn.214" href="#warn.214">Warning: 214 means "Transformation Applied"</a></h3>
     1525      <h3 id="rfc.section.5.5.6"><a href="#rfc.section.5.5.6">5.5.6</a>&nbsp;<a id="warn.214" href="#warn.214">Warning: 214 - "Transformation Applied"</a></h3>
    15211526      <p id="rfc.section.5.5.6.p.1"><em class="bcp14">MUST</em> be added by a proxy if it applies any transformation to the representation, such as changing the content-coding, media-type,
    15221527         or modifying the representation data, unless this Warning code already appears in the response.
    … …  
    15241529      <div id="rfc.iref.55"></div>
    15251530      <div id="rfc.iref.m.7"></div>
    1526       <h3 id="rfc.section.5.5.7"><a href="#rfc.section.5.5.7">5.5.7</a>&nbsp;<a id="warn.299" href="#warn.299">Warning: 299 means "Miscellaneous Persistent Warning"</a></h3>
     1531      <h3 id="rfc.section.5.5.7"><a href="#rfc.section.5.5.7">5.5.7</a>&nbsp;<a id="warn.299" href="#warn.299">Warning: 299 - "Miscellaneous Persistent Warning"</a></h3>
    15271532      <p id="rfc.section.5.5.7.p.1">The warning text can include arbitrary information to be presented to a human user, or logged. A system receiving this warning <em class="bcp14">MUST NOT</em> take any automated action.
    15281533      </p>
    … …  
    16751680                  <td class="left">110</td>
    16761681                  <td class="left">Response is Stale</td>
    1677                   <td class="left"><a href="#warn.110" id="rfc.xref.warn.110.2" title="Warning: 110 means &#34;Response is Stale&#34;">Section&nbsp;5.5.1</a>
     1682                  <td class="left"><a href="#warn.110" id="rfc.xref.warn.110.2" title="Warning: 110 - &#34;Response is Stale&#34;">Section&nbsp;5.5.1</a>
    16781683                  </td>
    16791684               </tr>
    … …  
    16811686                  <td class="left">111</td>
    16821687                  <td class="left">Revalidation Failed</td>
    1683                   <td class="left"><a href="#warn.111" id="rfc.xref.warn.111.1" title="Warning: 111 means &#34;Revalidation Failed&#34;">Section&nbsp;5.5.2</a>
     1688                  <td class="left"><a href="#warn.111" id="rfc.xref.warn.111.1" title="Warning: 111 - &#34;Revalidation Failed&#34;">Section&nbsp;5.5.2</a>
    16841689                  </td>
    16851690               </tr>
    … …  
    16871692                  <td class="left">112</td>
    16881693                  <td class="left">Disconnected Operation</td>
    1689                   <td class="left"><a href="#warn.112" id="rfc.xref.warn.112.2" title="Warning: 112 means &#34;Disconnected Operation&#34;">Section&nbsp;5.5.3</a>
     1694                  <td class="left"><a href="#warn.112" id="rfc.xref.warn.112.2" title="Warning: 112 - &#34;Disconnected Operation&#34;">Section&nbsp;5.5.3</a>
    16901695                  </td>
    16911696               </tr>
    … …  
    16931698                  <td class="left">113</td>
    16941699                  <td class="left">Heuristic Expiration</td>
    1695                   <td class="left"><a href="#warn.113" id="rfc.xref.warn.113.2" title="Warning: 113 means &#34;Heuristic Expiration&#34;">Section&nbsp;5.5.4</a>
     1700                  <td class="left"><a href="#warn.113" id="rfc.xref.warn.113.2" title="Warning: 113 - &#34;Heuristic Expiration&#34;">Section&nbsp;5.5.4</a>
    16961701                  </td>
    16971702               </tr>
    … …  
    16991704                  <td class="left">199</td>
    17001705                  <td class="left">Miscellaneous Warning</td>
    1701                   <td class="left"><a href="#warn.199" id="rfc.xref.warn.199.1" title="Warning: 199 means &#34;Miscellaneous Warning&#34;">Section&nbsp;5.5.5</a>
     1706                  <td class="left"><a href="#warn.199" id="rfc.xref.warn.199.1" title="Warning: 199 - &#34;Miscellaneous Warning&#34;">Section&nbsp;5.5.5</a>
    17021707                  </td>
    17031708               </tr>
    … …  
    17051710                  <td class="left">214</td>
    17061711                  <td class="left">Transformation Applied</td>
    1707                   <td class="left"><a href="#warn.214" id="rfc.xref.warn.214.1" title="Warning: 214 means &#34;Transformation Applied&#34;">Section&nbsp;5.5.6</a>
     1712                  <td class="left"><a href="#warn.214" id="rfc.xref.warn.214.1" title="Warning: 214 - &#34;Transformation Applied&#34;">Section&nbsp;5.5.6</a>
    17081713                  </td>
    17091714               </tr>
    … …  
    17111716                  <td class="left">299</td>
    17121717                  <td class="left">Miscellaneous Persistent Warning</td>
    1713                   <td class="left"><a href="#warn.299" id="rfc.xref.warn.299.1" title="Warning: 299 means &#34;Miscellaneous Persistent Warning&#34;">Section&nbsp;5.5.7</a>
     1718                  <td class="left"><a href="#warn.299" id="rfc.xref.warn.299.1" title="Warning: 299 - &#34;Miscellaneous Persistent Warning&#34;">Section&nbsp;5.5.7</a>
    17141719                  </td>
    17151720               </tr>
    … …  
    19341939      <p id="rfc.section.B.p.2">The rules below are defined in <a href="#Part1" id="rfc.xref.Part1.13"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>:
    19351940      </p>
    1936       <div id="rfc.figure.u.14"></div><pre class="inline">  <a href="#imported.abnf" class="smpl">OWS</a>           = &lt;OWS, defined in <a href="#Part1" id="rfc.xref.Part1.14"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>, <a href="p1-messaging.html#whitespace" title="Whitespace">Section 3.2.3</a>&gt;
     1941      <div id="rfc.figure.u.15"></div><pre class="inline">  <a href="#imported.abnf" class="smpl">OWS</a>           = &lt;OWS, defined in <a href="#Part1" id="rfc.xref.Part1.14"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>, <a href="p1-messaging.html#whitespace" title="Whitespace">Section 3.2.3</a>&gt;
    19371942  <a href="#imported.abnf" class="smpl">field-name</a>    = &lt;field-name, defined in <a href="#Part1" id="rfc.xref.Part1.15"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>, <a href="p1-messaging.html#header.fields" title="Header Fields">Section 3.2</a>&gt;
    19381943  <a href="#imported.abnf" class="smpl">quoted-string</a> = &lt;quoted-string, defined in <a href="#Part1" id="rfc.xref.Part1.16"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>, <a href="p1-messaging.html#field.components" title="Field value components">Section 3.2.6</a>&gt;
    … …  
    19431948  <a href="#imported.abnf" class="smpl">uri-host</a>      = &lt;uri-host, defined in <a href="#Part1" id="rfc.xref.Part1.20"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>, <a href="p1-messaging.html#uri" title="Uniform Resource Identifiers">Section 2.7</a>&gt;
    19441949</pre><p id="rfc.section.B.p.4">The rules below are defined in other parts:</p>
    1945       <div id="rfc.figure.u.15"></div><pre class="inline">  <a href="#imported.abnf" class="smpl">HTTP-date</a>     = &lt;HTTP-date, defined in <a href="#Part2" id="rfc.xref.Part2.9"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>, <a href="p2-semantics.html#http.date" title="Date/Time Formats">Section 7.1.1.1</a>&gt;
     1950      <div id="rfc.figure.u.16"></div><pre class="inline">  <a href="#imported.abnf" class="smpl">HTTP-date</a>     = &lt;HTTP-date, defined in <a href="#Part2" id="rfc.xref.Part2.9"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>, <a href="p2-semantics.html#http.date" title="Date/Time Formats">Section 7.1.1.1</a>&gt;
    19461951</pre><h1 id="rfc.section.C"><a href="#rfc.section.C">C.</a>&nbsp;<a id="collected.abnf" href="#collected.abnf">Collected ABNF</a></h1>
    19471952      <p id="rfc.section.C.p.1">In the collected ABNF below, list rules are expanded as per <a href="p1-messaging.html#notation" title="Syntax Notation">Section 1.2</a> of <a href="#Part1" id="rfc.xref.Part1.21"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>.
    19481953      </p>
    1949       <div id="rfc.figure.u.16"></div><pre class="inline"><a href="#header.age" class="smpl">Age</a> = delta-seconds
     1954      <div id="rfc.figure.u.17"></div><pre class="inline"><a href="#header.age" class="smpl">Age</a> = delta-seconds
    19501955
    19511956<a href="#header.cache-control" class="smpl">Cache-Control</a> = *( "," OWS ) cache-directive *( OWS "," [ OWS
Note: See TracChangeset for help on using the changeset viewer.