Changeset 947 for draft-ietf-httpbis/10/p6-cache.xml
- Timestamp:
- 27/07/10 14:45:08 (12 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
draft-ietf-httpbis/10/p6-cache.xml
r945 r947 46 46 <?rfc-ext allow-markup-in-artwork="yes" ?> 47 47 <?rfc-ext include-references-in-index="yes" ?> 48 <rfc category="std" 49 docName="draft-ietf-httpbis-p6-cache-&ID-VERSION;" 50 ipr="pre5378Trust200902" 51 obsoletes="2616" x:maturity-level="draft" 52 xmlns:x="http://purl.org/net/xml2rfc/ext"> 48 <rfc category="std" docName="draft-ietf-httpbis-p6-cache-&ID-VERSION;" ipr="pre5378Trust200902" 49 obsoletes="2616" x:maturity-level="draft" xmlns:x="http://purl.org/net/xml2rfc/ext"> 53 50 <front> 54 51 55 <title abbrev="HTTP/1.1, Part 6">HTTP/1.1, part 6: Caching</title> 56 57 <author fullname="Roy T. Fielding" initials="R." 58 role="editor" surname="Fielding"> 59 <organization abbrev="Day Software">Day Software</organization> 60 <address> 61 <postal> 62 <street>23 Corporate Plaza DR, Suite 280</street> 63 <city>Newport Beach</city> 64 <region>CA</region> 65 <code>92660</code> 66 <country>USA</country> 67 </postal> 68 <phone>+1-949-706-5300</phone> 69 <facsimile>+1-949-706-5305</facsimile> 70 <email>fielding@gbiv.com</email> 71 <uri>http://roy.gbiv.com/</uri> 72 </address> 73 </author> 74 75 <author initials="J." surname="Gettys" fullname="Jim Gettys"> 76 <organization 77 abbrev="Alcatel-Lucent">Alcatel-Lucent Bell Labs</organization> 78 <address> 79 <postal> 80 <street>21 Oak Knoll Road</street> 81 <city>Carlisle</city> 82 <region>MA</region> 83 <code>01741</code> 84 <country>USA</country> 85 </postal> 86 <email>jg@freedesktop.org</email> 87 <uri>http://gettys.wordpress.com/</uri> 88 </address> 89 </author> 90 91 <author fullname="Jeffrey C. Mogul" initials="J." surname="Mogul"> 92 <organization abbrev="HP">Hewlett-Packard Company</organization> 93 <address> 94 <postal> 95 <street>HP Labs, Large Scale Systems Group</street> 96 <street>1501 Page Mill Road, MS 1177</street> 97 <city>Palo Alto</city> 98 <region>CA</region> 99 <code>94304</code> 100 <country>USA</country> 101 </postal> 102 <email>JeffMogul@acm.org</email> 103 </address> 104 </author> 105 106 <author fullname="Henrik Frystyk Nielsen" initials="H." surname="Frystyk"> 107 <organization abbrev="Microsoft">Microsoft Corporation</organization> 108 <address> 109 <postal> 110 <street>1 Microsoft Way</street> 111 <city>Redmond</city> 112 <region>WA</region> 113 <code>98052</code> 114 <country>USA</country> 115 </postal> 116 <email>henrikn@microsoft.com</email> 117 </address> 118 </author> 119 120 <author fullname="Larry Masinter" initials="L." surname="Masinter"> 121 <organization abbrev="Adobe Systems">Adobe Systems, Incorporated</organization> 122 <address> 123 <postal> 124 <street>345 Park Ave</street> 125 <city>San Jose</city> 126 <region>CA</region> 127 <code>95110</code> 128 <country>USA</country> 129 </postal> 130 <email>LMM@acm.org</email> 131 <uri>http://larry.masinter.net/</uri> 132 </address> 133 </author> 134 135 <author fullname="Paul J. Leach" initials="P." surname="Leach"> 136 <organization abbrev="Microsoft">Microsoft Corporation</organization> 137 <address> 138 <postal> 139 <street>1 Microsoft Way</street> 140 <city>Redmond</city> 141 <region>WA</region> 142 <code>98052</code> 143 </postal> 144 <email>paulle@microsoft.com</email> 145 </address> 146 </author> 147 148 <author fullname="Tim Berners-Lee" initials="T." surname="Berners-Lee"> 149 <organization abbrev="W3C/MIT">World Wide Web Consortium</organization> 150 <address> 151 <postal> 152 <street>MIT Computer Science and Artificial Intelligence Laboratory</street> 153 <street>The Stata Center, Building 32</street> 154 <street>32 Vassar Street</street> 155 <city>Cambridge</city> 156 <region>MA</region> 157 <code>02139</code> 158 <country>USA</country> 159 </postal> 160 <email>timbl@w3.org</email> 161 <uri>http://www.w3.org/People/Berners-Lee/</uri> 162 </address> 163 </author> 164 165 <author fullname="Yves Lafon" initials="Y." role="editor" surname="Lafon"> 166 <organization abbrev="W3C">World Wide Web Consortium</organization> 167 <address> 168 <postal> 169 <street>W3C / ERCIM</street> 170 <street>2004, rte des Lucioles</street> 171 <city>Sophia-Antipolis</city> 172 <region>AM</region> 173 <code>06902</code> 174 <country>France</country> 175 </postal> 176 <email>ylafon@w3.org</email> 177 <uri>http://www.raubacapeu.net/people/yves/</uri> 178 </address> 179 </author> 180 181 <author fullname="Mark Nottingham" initials="M." role="editor" 182 surname="Nottingham"> 183 <address> 184 <email>mnot@mnot.net</email> 185 <uri>http://www.mnot.net/</uri> 186 </address> 187 </author> 188 189 <author fullname="Julian F. Reschke" initials="J. F." role="editor" 190 surname="Reschke"> 191 <organization abbrev="greenbytes">greenbytes GmbH</organization> 192 <address> 193 <postal> 194 <street>Hafenweg 16</street> 195 <city>Muenster</city><region>NW</region><code>48155</code> 196 <country>Germany</country> 197 </postal> 198 <phone>+49 251 2807760</phone> 199 <facsimile>+49 251 2807761</facsimile> 200 <email>julian.reschke@greenbytes.de</email> 201 <uri>http://greenbytes.de/tech/webdav/</uri> 202 </address> 203 </author> 204 205 <date month="&ID-MONTH;" year="&ID-YEAR;" day="12"/> 206 <workgroup>HTTPbis Working Group</workgroup> 52 <title abbrev="HTTP/1.1, Part 6">HTTP/1.1, part 6: Caching</title> 53 54 <author fullname="Roy T. Fielding" initials="R." role="editor" surname="Fielding"> 55 <organization abbrev="Day Software">Day Software</organization> 56 <address> 57 <postal> 58 <street>23 Corporate Plaza DR, Suite 280</street> 59 <city>Newport Beach</city> 60 <region>CA</region> 61 <code>92660</code> 62 <country>USA</country> 63 </postal> 64 <phone>+1-949-706-5300</phone> 65 <facsimile>+1-949-706-5305</facsimile> 66 <email>fielding@gbiv.com</email> 67 <uri>http://roy.gbiv.com/</uri> 68 </address> 69 </author> 70 71 <author initials="J." surname="Gettys" fullname="Jim Gettys"> 72 <organization abbrev="Alcatel-Lucent">Alcatel-Lucent Bell Labs</organization> 73 <address> 74 <postal> 75 <street>21 Oak Knoll Road</street> 76 <city>Carlisle</city> 77 <region>MA</region> 78 <code>01741</code> 79 <country>USA</country> 80 </postal> 81 <email>jg@freedesktop.org</email> 82 <uri>http://gettys.wordpress.com/</uri> 83 </address> 84 </author> 85 86 <author fullname="Jeffrey C. Mogul" initials="J." surname="Mogul"> 87 <organization abbrev="HP">Hewlett-Packard Company</organization> 88 <address> 89 <postal> 90 <street>HP Labs, Large Scale Systems Group</street> 91 <street>1501 Page Mill Road, MS 1177</street> 92 <city>Palo Alto</city> 93 <region>CA</region> 94 <code>94304</code> 95 <country>USA</country> 96 </postal> 97 <email>JeffMogul@acm.org</email> 98 </address> 99 </author> 100 101 <author fullname="Henrik Frystyk Nielsen" initials="H." surname="Frystyk"> 102 <organization abbrev="Microsoft">Microsoft Corporation</organization> 103 <address> 104 <postal> 105 <street>1 Microsoft Way</street> 106 <city>Redmond</city> 107 <region>WA</region> 108 <code>98052</code> 109 <country>USA</country> 110 </postal> 111 <email>henrikn@microsoft.com</email> 112 </address> 113 </author> 114 115 <author fullname="Larry Masinter" initials="L." surname="Masinter"> 116 <organization abbrev="Adobe Systems">Adobe Systems, Incorporated</organization> 117 <address> 118 <postal> 119 <street>345 Park Ave</street> 120 <city>San Jose</city> 121 <region>CA</region> 122 <code>95110</code> 123 <country>USA</country> 124 </postal> 125 <email>LMM@acm.org</email> 126 <uri>http://larry.masinter.net/</uri> 127 </address> 128 </author> 129 130 <author fullname="Paul J. Leach" initials="P." surname="Leach"> 131 <organization abbrev="Microsoft">Microsoft Corporation</organization> 132 <address> 133 <postal> 134 <street>1 Microsoft Way</street> 135 <city>Redmond</city> 136 <region>WA</region> 137 <code>98052</code> 138 </postal> 139 <email>paulle@microsoft.com</email> 140 </address> 141 </author> 142 143 <author fullname="Tim Berners-Lee" initials="T." surname="Berners-Lee"> 144 <organization abbrev="W3C/MIT">World Wide Web Consortium</organization> 145 <address> 146 <postal> 147 <street>MIT Computer Science and Artificial Intelligence Laboratory</street> 148 <street>The Stata Center, Building 32</street> 149 <street>32 Vassar Street</street> 150 <city>Cambridge</city> 151 <region>MA</region> 152 <code>02139</code> 153 <country>USA</country> 154 </postal> 155 <email>timbl@w3.org</email> 156 <uri>http://www.w3.org/People/Berners-Lee/</uri> 157 </address> 158 </author> 159 160 <author fullname="Yves Lafon" initials="Y." role="editor" surname="Lafon"> 161 <organization abbrev="W3C">World Wide Web Consortium</organization> 162 <address> 163 <postal> 164 <street>W3C / ERCIM</street> 165 <street>2004, rte des Lucioles</street> 166 <city>Sophia-Antipolis</city> 167 <region>AM</region> 168 <code>06902</code> 169 <country>France</country> 170 </postal> 171 <email>ylafon@w3.org</email> 172 <uri>http://www.raubacapeu.net/people/yves/</uri> 173 </address> 174 </author> 175 176 <author fullname="Mark Nottingham" initials="M." role="editor" surname="Nottingham"> 177 <address> 178 <email>mnot@mnot.net</email> 179 <uri>http://www.mnot.net/</uri> 180 </address> 181 </author> 182 183 <author fullname="Julian F. Reschke" initials="J. F." role="editor" surname="Reschke"> 184 <organization abbrev="greenbytes">greenbytes GmbH</organization> 185 <address> 186 <postal> 187 <street>Hafenweg 16</street> 188 <city>Muenster</city><region>NW</region><code>48155</code> 189 <country>Germany</country> 190 </postal> 191 <phone>+49 251 2807760</phone> 192 <facsimile>+49 251 2807761</facsimile> 193 <email>julian.reschke@greenbytes.de</email> 194 <uri>http://greenbytes.de/tech/webdav/</uri> 195 </address> 196 </author> 197 198 <date month="&ID-MONTH;" year="&ID-YEAR;" day="12"/> 199 <workgroup>HTTPbis Working Group</workgroup> 207 200 208 201 <abstract> 209 202 <t> 210 The Hypertext Transfer Protocol (HTTP) is an application-level protocol for 211 distributed, collaborative, hypermedia information systems. This document 212 is Part 6 of the seven-part specification that defines the protocol 213 referred to as "HTTP/1.1" and, taken together, obsoletes RFC 2616. Part 6 214 defines requirements on HTTP caches and the associated header fields that 215 control cache behavior or indicate cacheable response messages. 203 The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, 204 collaborative, hypermedia information systems. This document is Part 6 of the seven-part 205 specification that defines the protocol referred to as "HTTP/1.1" and, taken together, 206 obsoletes RFC 2616. Part 6 defines requirements on HTTP caches and the associated header 207 fields that control cache behavior or indicate cacheable response messages. 216 208 </t> 217 209 </abstract> 218 210 219 211 <note title="Editorial Note (To be removed by RFC Editor)"> 220 <t> 221 Discussion of this draft should take place on the HTTPBIS working group 222 mailing list (ietf-http-wg@w3.org). The current issues list is at <eref 223 target="http://tools.ietf.org/wg/httpbis/trac/report/3"/> and related 224 documents (including fancy diffs) can be found at <eref 225 target="http://tools.ietf.org/wg/httpbis/"/>. 226 </t> 227 <t> 228 The changes in this draft are summarized in <xref 229 target="changes.since.09"/>. 230 </t> 212 <t> 213 Discussion of this draft should take place on the HTTPBIS working group 214 mailing list (ietf-http-wg@w3.org). The current issues list is 215 at <eref target="http://tools.ietf.org/wg/httpbis/trac/report/3"/> 216 and related documents (including fancy diffs) can be found at 217 <eref target="http://tools.ietf.org/wg/httpbis/"/>. 218 </t> 219 <t> 220 The changes in this draft are summarized in <xref target="changes.since.09"/>. 221 </t> 231 222 </note> 232 223 … … 236 227 <section anchor="caching" title="Introduction"> 237 228 <t> 238 HTTP is typically used for distributed information systems, where 239 performance can be improved by the use of response caches. This document 240 defines aspects of HTTP/1.1 related to caching and reusing response 241 messages. 229 HTTP is typically used for distributed information systems, where performance can be 230 improved by the use of response caches. This document defines aspects of HTTP/1.1 related to 231 caching and reusing response messages. 242 232 </t> 243 233 … … 245 235 <iref item="cache" /> 246 236 <t> 247 An HTTP <x:dfn>cache</x:dfn> is a local store of response messages and the 248 subsystem that controls its message storage, retrieval, and deletion. A 249 cache stores cacheable responses in order to reduce the response time and 250 network bandwidth consumption on future, equivalent requests. Any client or 251 server may include a cache, though a cache cannot be used by a server that 252 is acting as a tunnel. 253 </t> 254 <t> 255 Caching would be useless if it did not significantly improve performance. 256 The goal of caching in HTTP/1.1 is to reuse a prior response message to 257 satisfy a current request. In some cases, a stored response can be reused 258 without the need for a network request, reducing latency and network 259 round-trips; a "freshness" mechanism is used for this purpose (see <xref 260 target="expiration.model" />). Even when a new request is required, it is 261 often possible to reuse all or parts of the payload of a prior response to 262 satisfy the request, thereby reducing network bandwidth usage; a 263 "validation" mechanism is used for this purpose (see <xref 264 target="validation.model" />). 237 An HTTP <x:dfn>cache</x:dfn> is a local store of response messages and the subsystem that 238 controls its message storage, retrieval, and deletion. A cache stores cacheable responses 239 in order to reduce the response time and network bandwidth consumption on future, 240 equivalent requests. Any client or server may include a cache, though a cache cannot be 241 used by a server that is acting as a tunnel. 242 </t> 243 <t> 244 Caching would be useless if it did not significantly improve performance. The goal of 245 caching in HTTP/1.1 is to reuse a prior response message to satisfy a current request. In 246 some cases, a stored response can be reused without the need for a network request, 247 reducing latency and network round-trips; a "freshness" mechanism is used for this purpose 248 (see <xref target="expiration.model" />). Even when a new request is required, it is often 249 possible to reuse all or parts of the payload of a prior response to satisfy the request, 250 thereby reducing network bandwidth usage; a "validation" mechanism is used for this 251 purpose (see <xref target="validation.model" />). 265 252 </t> 266 253 </section> … … 268 255 <section anchor="intro.terminology" title="Terminology"> 269 256 <t> 270 This specification uses a number of terms to refer to the roles played by 271 participants in, and objects of, HTTP caching. 272 </t> 273 <t> 274 <iref item="cacheable" /> 275 <x:dfn>cacheable</x:dfn> 276 <list> 277 <t>A response is cacheable if a cache is allowed to store a copy of the 278 response message for use in answering subsequent requests. Even when a 279 response is cacheable, there may be additional constraints on whether a 280 cache can use the cached copy to satisfy a particular request.</t> 281 </list> 282 </t> 283 <t> 284 <iref item="explicit expiration time" /> 285 <x:dfn>explicit expiration time</x:dfn> 286 <list> 287 <t>The time at which the origin server intends that an entity should no 288 longer be returned by a cache without further validation.</t> 289 </list> 290 </t> 291 <t> 292 <iref item="heuristic expiration time" /> 293 <x:dfn>heuristic expiration time</x:dfn> 294 <list> 295 <t>An expiration time assigned by a cache when no explicit expiration 296 time is available.</t> 297 </list> 298 </t> 299 <t> 300 <iref item="age" /> 301 <x:dfn>age</x:dfn> 302 <list> 303 <t>The age of a response is the time since it was sent by, or 304 successfully validated with, the origin server.</t> 305 </list> 306 </t> 307 <t> 308 <iref item="first-hand" /> 309 <x:dfn>first-hand</x:dfn> 310 <list> 311 <t>A response is first-hand if the freshness model is not in use; i.e., 312 its age is 0.</t> 313 </list> 314 </t> 315 <t> 316 <iref item="freshness lifetime" /> 317 <x:dfn>freshness lifetime</x:dfn> 318 <list> 319 <t>The length of time between the generation of a response and its 320 expiration time.</t> 321 </list> 322 </t> 323 <t> 324 <iref item="fresh" /> 325 <x:dfn>fresh</x:dfn> 326 <list> 327 <t>A response is fresh if its age has not yet exceeded its freshness 328 lifetime.</t> 329 </list> 257 This specification uses a number of terms to refer to the roles played by participants 258 in, and objects of, HTTP caching. 259 </t> 260 <t> 261 <iref item="cacheable" /> 262 <x:dfn>cacheable</x:dfn> 263 <list> 264 <t>A response is cacheable if a cache is allowed to store a copy of the response message 265 for use in answering subsequent requests. Even when a response is cacheable, there may 266 be additional constraints on whether a cache can use the cached copy to satisfy a 267 particular request.</t> 268 </list> 269 </t> 270 <t> 271 <iref item="explicit expiration time" /> 272 <x:dfn>explicit expiration time</x:dfn> 273 <list> 274 <t>The time at which the origin server intends that an entity should no longer be 275 returned by a cache without further validation.</t> 276 </list> 277 </t> 278 <t> 279 <iref item="heuristic expiration time" /> 280 <x:dfn>heuristic expiration time</x:dfn> 281 <list> 282 <t>An expiration time assigned by a cache when no explicit expiration time is 283 available.</t> 284 </list> 285 </t> 286 <t> 287 <iref item="age" /> 288 <x:dfn>age</x:dfn> 289 <list> 290 <t>The age of a response is the time since it was sent by, or successfully validated 291 with, the origin server.</t> 292 </list> 293 </t> 294 <t> 295 <iref item="first-hand" /> 296 <x:dfn>first-hand</x:dfn> 297 <list> 298 <t>A response is first-hand if the freshness model is not in use; i.e., its age is 299 0.</t> 300 </list> 301 </t> 302 <t> 303 <iref item="freshness lifetime" /> 304 <x:dfn>freshness lifetime</x:dfn> 305 <list> 306 <t>The length of time between the generation of a response and its expiration time. </t> 307 </list> 308 </t> 309 <t> 310 <iref item="fresh" /> 311 <x:dfn>fresh</x:dfn> 312 <list> 313 <t>A response is fresh if its age has not yet exceeded its freshness lifetime.</t> 314 </list> 330 315 </t> 331 316 <t> … … 333 318 <x:dfn>stale</x:dfn> 334 319 <list> 335 <t>A response is stale if its age has passed its freshness lifetime 336 (either explicit or heuristic).</t> 337 </list> 338 </t> 339 <t> 340 <iref item="validator" /> 341 <x:dfn>validator</x:dfn> 342 <list> 343 <t>A protocol element (e.g., an entity tag or a Last-Modified time) that 344 is used to find out whether a stored response is an equivalent copy of 345 an entity.</t> 346 </list> 320 <t>A response is stale if its age has passed its freshness lifetime (either explicit or heuristic).</t> 321 </list> 322 </t> 323 <t> 324 <iref item="validator" /> 325 <x:dfn>validator</x:dfn> 326 <list> 327 <t>A protocol element (e.g., an entity tag or a Last-Modified time) that is used to find 328 out whether a stored response is an equivalent copy of an entity.</t> 329 </list> 347 330 </t> 348 331 <t anchor="shared.and.non-shared.caches"> 349 350 351 352 <t>A cache that is accessible to more than one user. A non-shared cache353 isdedicated to a single user.</t>354 332 <iref item="validator" /> 333 <x:dfn>shared cache</x:dfn> 334 <list> 335 <t>A cache that is accessible to more than one user. A non-shared cache is 336 dedicated to a single user.</t> 337 </list> 355 338 </t> 356 339 </section> … … 363 346 </t> 364 347 <t> 365 An implementation is not compliant if it fails to satisfy one or more of366 the "MUST" or "REQUIRED" level requirements for the protocols it348 An implementation is not compliant if it fails to satisfy one or more 349 of the "MUST" or "REQUIRED" level requirements for the protocols it 367 350 implements. An implementation that satisfies all the "MUST" or "REQUIRED" 368 level and all the "SHOULD" level requirements for its protocols is said to369 be "unconditionally compliant"; one that satisfies all the "MUST" level370 requirements but not all the "SHOULD" level requirements for its protocols371 is said to be "conditionally compliant".351 level and all the "SHOULD" level requirements for its protocols is said 352 to be "unconditionally compliant"; one that satisfies all the "MUST" 353 level requirements but not all the "SHOULD" level requirements for its 354 protocols is said to be "conditionally compliant". 372 355 </t> 373 356 </section> 374 357 375 358 <section title="Syntax Notation" anchor="notation"> 376 <x:anchor-alias value="ALPHA"/> 377 <x:anchor-alias value="CR"/> 378 <x:anchor-alias value="DIGIT"/> 379 <x:anchor-alias value="DQUOTE"/> 380 <x:anchor-alias value="LF"/> 381 <x:anchor-alias value="OCTET"/> 382 <x:anchor-alias value="SP"/> 383 <x:anchor-alias value="VCHAR"/> 384 <x:anchor-alias value="WSP"/> 385 <t> 386 This specification uses the ABNF syntax defined in ¬ation; (which 387 extends the syntax defined in <xref target="RFC5234"/> with a list rule). 388 <xref target="collected.abnf"/> shows the collected ABNF, with the list 389 rule expanded. 390 </t> 391 <t> 392 The following core rules are included by reference, as defined in <xref 393 target="RFC5234" x:fmt="," x:sec="B.1"/>: ALPHA (letters), CR (carriage 394 return), CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double 395 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 396 sequence of data), SP (space), VCHAR (any visible USASCII character), and 397 WSP (whitespace). 359 <x:anchor-alias value="ALPHA"/> 360 <x:anchor-alias value="CR"/> 361 <x:anchor-alias value="DIGIT"/> 362 <x:anchor-alias value="DQUOTE"/> 363 <x:anchor-alias value="LF"/> 364 <x:anchor-alias value="OCTET"/> 365 <x:anchor-alias value="SP"/> 366 <x:anchor-alias value="VCHAR"/> 367 <x:anchor-alias value="WSP"/> 368 <t> 369 This specification uses the ABNF syntax defined in ¬ation; (which 370 extends the syntax defined in <xref target="RFC5234"/> with a list rule). 371 <xref target="collected.abnf"/> shows the collected ABNF, with the list 372 rule expanded. 373 </t> 374 <t> 375 The following core rules are included by 376 reference, as defined in <xref target="RFC5234" x:fmt="," x:sec="B.1"/>: 377 ALPHA (letters), CR (carriage return), CRLF (CR LF), CTL (controls), 378 DIGIT (decimal 0-9), DQUOTE (double quote), 379 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), 380 OCTET (any 8-bit sequence of data), SP (space), 381 VCHAR (any visible USASCII character), 382 and WSP (whitespace). 398 383 </t> 399 384 400 385 <section title="Core Rules" anchor="core.rules"> 401 402 403 404 <t> 405 386 <x:anchor-alias value="quoted-string"/> 387 <x:anchor-alias value="token"/> 388 <x:anchor-alias value="OWS"/> 389 <t> 390 The core rules below are defined in &basic-rules;: 406 391 </t> 407 392 <figure><artwork type="abnf2616"> … … 412 397 </section> 413 398 414 <section title="ABNF Rules defined in other Parts of the Specification" 415 anchor="abnf.dependencies"> 416 <x:anchor-alias value="field-name"/> 417 <x:anchor-alias value="HTTP-date"/> 418 <x:anchor-alias value="port"/> 419 <x:anchor-alias value="pseudonym"/> 420 <x:anchor-alias value="uri-host"/> 421 <t> 422 The ABNF rules below are defined in other parts: 399 <section title="ABNF Rules defined in other Parts of the Specification" anchor="abnf.dependencies"> 400 <x:anchor-alias value="field-name"/> 401 <x:anchor-alias value="HTTP-date"/> 402 <x:anchor-alias value="port"/> 403 <x:anchor-alias value="pseudonym"/> 404 <x:anchor-alias value="uri-host"/> 405 <t> 406 The ABNF rules below are defined in other parts: 423 407 </t> 424 408 <figure><!--Part1--><artwork type="abnf2616"> … … 438 422 <section anchor="response.cacheability" title="Response Cacheability"> 439 423 <t> 440 A cache &MUST-NOT; store a response to any request, unless: 441 <list style="symbols"> 442 <t>The request method is understood by the cache and defined as being 443 cacheable, and</t> 444 <t>the response status code is understood by the cache, and</t> 445 <t>the "no-store" cache directive (see <xref 446 target="header.cache-control" />) does not appear in request or response 447 headers, and</t> 448 <t>the "private" cache response directive (see <xref 449 target="cache-response-directive" /> does not appear in the response, if 450 the cache is shared, and</t> 451 <t>the "Authorization" header (see &header-authorization;) does not 452 appear in the request, if the cache is shared, unless the response 453 explicitly allows it (see <xref target="caching.authenticated.responses" 454 />), and</t> 455 <t>the response either: 456 <list style="symbols"> 457 <t>contains an Expires header (see <xref target="header.expires" 458 />), or</t> 459 <t>contains a max-age response cache directive (see <xref 460 target="cache-response-directive" />), or</t> 461 <t>contains a s-maxage response cache directive and the cache is 462 shared, or</t> 463 <t>contains a Cache Control Extension (see <xref 464 target="cache.control.extensions" />) that allows it to be cached, 465 or</t> 466 <t>has a status code that can be served with heuristic freshness 467 (see <xref target="heuristic.freshness" />).</t> 468 </list> 469 </t> 470 </list> 471 </t> 472 <t> 473 In this context, a cache has "understood" a request method or a response 474 status code if it recognises it and implements any cache-specific 475 behaviour. In particular, 206 Partial Content responses cannot be cached by 476 an implementation that does not handle partial content (see <xref 477 target="errors.or.incomplete.response.cache.behavior" />). 478 </t> 479 <t> 480 Note that in normal operation, most caches will not store a response that 481 has neither a cache validator nor an explicit expiration time, as such 482 responses are not usually useful to store. However, caches are not 483 prohibited from storing such responses. 484 </t> 485 486 <section anchor="errors.or.incomplete.response.cache.behavior" 487 title="Storing Partial and Incomplete Responses"> 488 <t> 489 A cache that receives an incomplete response (for example, with fewer bytes 490 of data than specified in a Content-Length header) can store the response, 491 but &MUST; treat it as a partial response &partial;. Partial responses can 492 be combined as described in &combining-byte-ranges;; the result might be a 493 full response or might still be partial. A cache &MUST-NOT; return a 494 partial response to a client without explicitly marking it as such using 495 the 206 (Partial Content) status code. 496 </t> 497 <t> 498 A cache that does not support the Range and Content-Range headers 499 &MUST-NOT; store incomplete or partial responses. 500 </t> 501 </section> 502 503 </section> 504 505 506 <section anchor="constructing.responses.from.caches" 507 title="Constructing Responses from Caches"> 508 <t> 509 For a presented request, a cache &MUST-NOT; return a stored response, 510 unless: 511 <list style="symbols"> 512 <t>The presented Effective Request URI (&effective-request-uri;) and 513 that of the stored response match, and</t> 514 <t>the request method associated with the stored response allows it to 515 be used for the presented request, and</t> 516 <t>selecting request-headers nominated by the stored response (if any) 517 match those presented (see <xref target="caching.negotiated.responses" 518 />), and</t> 519 <t>the presented request and stored response are free from directives 520 that would prevent its use (see <xref target="header.cache-control" /> 521 and <xref target="header.pragma"/>), and</t> 522 <t>the stored response is either: 523 <list style="symbols"> 524 <t>fresh (see <xref target="expiration.model" />), or</t> 525 <t>allowed to be served stale (see <xref 526 target="serving.stale.responses" />), or</t> 527 <t>successfully validated (see <xref target="validation.model" 528 />).</t> 529 </list> 530 </t> 531 </list> 532 </t> 533 <t> 534 <cref anchor="TODO-method-cacheability">define method cacheability for GET, 535 HEAD and POST in p2-semantics.</cref> 536 </t> 537 <t> 538 When a stored response is used to satisfy a request, caches &MUST; include 539 a single Age header field (<xref target="header.age" />) in the response 540 with a value equal to the stored response's current_age; see <xref 541 target="age.calculations" />. 542 <cref anchor="DISCUSS-includes-validated">this currently includes 543 successfully validated responses.</cref> 544 </t> 545 <t> 546 Requests with methods that are unsafe (&safe-methods;) &MUST; be written 547 through the cache to the origin server; i.e., a cache must not reply to 548 such a request before having forwarded the request and having received a 549 corresponding response.</t> 550 <t> 551 Also, note that unsafe requests might invalidate already stored responses; 552 see <xref target="invalidation.after.updates.or.deletions" />. 553 </t> 554 <t> 555 Caches &MUST; use the most recent response (as determined by the Date 556 header) when more than one suitable response is stored. They can also 557 forward a request with "Cache-Control: max-age=0" or "Cache-Control: 558 no-cache" to disambiguate which response to use. 424 A cache &MUST-NOT; store a response to any request, unless: 425 <list style="symbols"> 426 <t>The request method is understood by the cache and defined as being cacheable, and</t> 427 <t>the response status code is understood by the cache, and</t> 428 <t>the "no-store" cache directive (see <xref target="header.cache-control" />) does not 429 appear in request or response headers, and</t> 430 <t>the "private" cache response directive (see <xref target="cache-response-directive" /> 431 does not appear in the response, if the cache is shared, and</t> 432 <t>the "Authorization" header (see &header-authorization;) does not appear in the request, if 433 the cache is shared, unless the response explicitly allows it (see <xref 434 target="caching.authenticated.responses" />), and</t> 435 <t>the response either: 436 <list style="symbols"> 437 <t>contains an Expires header (see <xref target="header.expires" />), or</t> 438 <t>contains a max-age response cache directive (see <xref target="cache-response-directive" />), or</t> 439 <t>contains a s-maxage response cache directive and the cache is shared, or</t> 440 <t>contains a Cache Control Extension (see <xref target="cache.control.extensions" />) that allows it to be cached, or</t> 441 <t>has a status code that can be served with heuristic freshness (see <xref 442 target="heuristic.freshness" />).</t> 443 </list> 444 </t> 445 </list> 446 </t> 447 <t> 448 In this context, a cache has "understood" a request method or a response status 449 code if it recognises it and implements any cache-specific behaviour. In 450 particular, 206 Partial Content responses cannot be cached by an 451 implementation that does not handle partial content 452 (see <xref target="errors.or.incomplete.response.cache.behavior" />). 453 </t> 454 <t> 455 Note that in normal operation, most caches will not store a response that has neither a 456 cache validator nor an explicit expiration time, as such responses are not usually 457 useful to store. However, caches are not prohibited from storing such responses. 458 </t> 459 460 <section anchor="errors.or.incomplete.response.cache.behavior" title="Storing Partial and Incomplete Responses"> 461 <t> 462 A cache that receives an incomplete response (for example, with fewer bytes of data 463 than specified in a Content-Length header) can store the response, but &MUST; 464 treat it as a partial response &partial;. Partial responses 465 can be combined as described in &combining-byte-ranges;; the result might be a 466 full response or might still be partial. A cache &MUST-NOT; return a partial 467 response to a client without explicitly marking it as such using the 206 (Partial 468 Content) status code. 469 </t> 470 <t> 471 A cache that does not support the Range and Content-Range headers &MUST-NOT; store 472 incomplete or partial responses. 473 </t> 474 </section> 475 476 </section> 477 478 479 <section anchor="constructing.responses.from.caches" title="Constructing Responses from Caches"> 480 <t> 481 For a presented request, a cache &MUST-NOT; return a stored response, unless: 482 <list style="symbols"> 483 <t>The presented Effective Request URI (&effective-request-uri;) and that of the stored response match, and</t> 484 <t>the request method associated with the stored response allows it to be 485 used for the presented request, and</t> 486 <t>selecting request-headers nominated by the stored response (if any) match those presented (see <xref 487 target="caching.negotiated.responses" />), and</t> 488 <t>the presented request and stored response are free from directives that would prevent 489 its use (see <xref target="header.cache-control" /> and <xref target="header.pragma"/>), 490 and</t> 491 <t>the stored response is either: 492 <list style="symbols"> 493 <t>fresh (see <xref target="expiration.model" />), or</t> 494 <t>allowed to be served stale (see <xref target="serving.stale.responses" />), or</t> 495 <t>successfully validated (see <xref target="validation.model" />).</t> 496 </list> 497 </t> 498 </list> 499 </t> 500 <t> 501 <cref anchor="TODO-method-cacheability">define method cacheability for GET, HEAD and POST in p2-semantics.</cref> 502 </t> 503 <t> 504 When a stored response is used to satisfy a request, caches &MUST; include a 505 single Age header field (<xref target="header.age" />) in the response with a value equal to the stored response's 506 current_age; see <xref target="age.calculations" />. 507 <cref anchor="DISCUSS-includes-validated">this currently includes successfully validated responses.</cref> 508 </t> 509 <t> 510 Requests with methods that are unsafe (&safe-methods;) &MUST; be written through the cache to 511 the origin server; i.e., a cache must not reply to such a request before having forwarded the request and having received a 512 corresponding response. 513 </t> 514 <t> 515 Also, note that unsafe requests might invalidate already stored responses; see 516 <xref target="invalidation.after.updates.or.deletions" />. 517 </t> 518 <t> 519 Caches &MUST; use the most recent response (as determined by the Date header) when 520 more than one suitable response is stored. They can also forward a request with 521 "Cache-Control: max-age=0" or "Cache-Control: no-cache" to disambiguate which response to 522 use. 559 523 </t> 560 524 </section> … … 562 526 <section anchor="expiration.model" title="Freshness Model"> 563 527 <t> 564 When a response is "fresh" in the cache, it can be used to satisfy 565 subsequent requests without contacting the origin server, thereby improving 566 efficiency. 567 </t> 568 <t> 569 The primary mechanism for determining freshness is for an origin server to 570 provide an explicit expiration time in the future, using either the Expires 571 header (<xref target="header.expires" />) or the max-age response cache 572 directive (<xref target="cache-response-directive" />). Generally, origin 573 servers will assign future explicit expiration times to responses in the 574 belief that the entity is not likely to change in a semantically 575 significant way before the expiration time is reached. 576 </t> 577 <t> 578 If an origin server wishes to force a cache to validate every request, it 579 can assign an explicit expiration time in the past. This means that the 580 response is always stale, so that caches should validate it before using it 581 for subsequent requests. <cref anchor="TODO-response-stale">This wording 582 may cause confusion, because the response may still be served stale.</cref> 583 </t> 584 <t> 585 Since origin servers do not always provide explicit expiration times, HTTP 586 caches may also assign heuristic expiration times when they are not 587 specified, employing algorithms that use other header values (such as the 588 Last-Modified time) to estimate a plausible expiration time. The HTTP/1.1 589 specification does not provide specific algorithms, but does impose 590 worst-case constraints on their results. 528 When a response is "fresh" in the cache, it can be used to satisfy subsequent 529 requests without contacting the origin server, thereby improving efficiency. 530 </t> 531 <t> 532 The primary mechanism for determining freshness is for an origin server to provide an 533 explicit expiration time in the future, using either the Expires header (<xref 534 target="header.expires" />) or the max-age response cache directive (<xref 535 target="cache-response-directive" />). Generally, origin servers will assign future 536 explicit expiration times to responses in the belief that the entity is not likely to 537 change in a semantically significant way before the expiration time is reached. 538 </t> 539 <t> 540 If an origin server wishes to force a cache to validate every request, it can 541 assign an explicit expiration time in the past. This means that the response is always 542 stale, so that caches should validate it before using it for subsequent requests. 543 <cref anchor="TODO-response-stale">This wording may cause confusion, because the response may still be served stale.</cref> 544 </t> 545 <t> 546 Since origin servers do not always provide explicit expiration times, HTTP caches may 547 also assign heuristic expiration times when they are not specified, employing algorithms that 548 use other header values (such as the Last-Modified time) to estimate a plausible 549 expiration time. The HTTP/1.1 specification does not provide specific algorithms, but does 550 impose worst-case constraints on their results. 591 551 </t> 592 552 <figure> … … 599 559 </figure> 600 560 <t> 601 The freshness_lifetime is defined in <xref 602 target="calculating.freshness.lifetime" />; the current_age is defined in 603 <xref target="age.calculations" />. 604 </t> 605 <t> 606 Additionally, clients may need to influence freshness calculation. They can 607 do this using several request cache directives, with the effect of either 608 increasing or loosening constraints on freshness. See <xref 609 target="cache-request-directive" />. 610 </t> 611 <t> 612 <cref anchor="ISSUE-no-req-for-directives">there are not requirements 613 directly applying to cache-request-directives and freshness.</cref> 614 </t> 615 <t> 616 Note that freshness applies only to cache operation; it cannot be used to 617 force a user agent to refresh its display or reload a resource. See <xref 618 target="history.lists" /> for an explanation of the difference between 619 caches and history mechanisms. 620 </t> 621 622 <section anchor="calculating.freshness.lifetime" 623 title="Calculating Freshness Lifetime"> 624 <t> 625 A cache can calculate the freshness lifetime (denoted as 626 freshness_lifetime) of a response by using the first match of: 627 <list style="symbols"> 628 <t>If the cache is shared and the s-maxage response cache directive 629 (<xref target="cache-response-directive" />) is present, use its value, 630 or</t> 631 <t>If the max-age response cache directive (<xref 561 The freshness_lifetime is defined in <xref target="calculating.freshness.lifetime" />; 562 the current_age is defined in <xref target="age.calculations" />. 563 </t> 564 <t> 565 Additionally, clients may need to influence freshness calculation. They can do this using 566 several request cache directives, with the effect of either increasing or loosening 567 constraints on freshness. See <xref target="cache-request-directive" />. 568 </t> 569 <t> 570 <cref anchor="ISSUE-no-req-for-directives">there are not requirements directly applying to cache-request-directives and 571 freshness.</cref> 572 </t> 573 <t> 574 Note that freshness applies only to cache operation; it cannot be used to force a user agent 575 to refresh its display or reload a resource. See <xref target="history.lists" /> for an explanation of 576 the difference between caches and history mechanisms. 577 </t> 578 579 <section anchor="calculating.freshness.lifetime" title="Calculating Freshness Lifetime"> 580 <t> 581 A cache can calculate the freshness lifetime (denoted as freshness_lifetime) of a 582 response by using the first match of: 583 <list style="symbols"> 584 <t>If the cache is shared and the s-maxage response cache directive (<xref 632 585 target="cache-response-directive" />) is present, use its value, or</t> 633 <t>If the Expires response header (<xref target="header.expires" />) is634 present, use its value minus the value of the Date response header,635 or</t>636 <t>Otherwise, no explicit expiration time is present in the response. A637 heuristic freshness lifetime might be applicable; see <xref638 target="heuristic.freshness" />.</t>639 </list> 640 </t> 641 <t> 642 Note that this calculation is not vulnerable to clock skew, since all of643 theinformation comes from the origin server.586 <t>If the max-age response cache directive (<xref target="cache-response-directive" 587 />) is present, use its value, or</t> 588 <t>If the Expires response header (<xref target="header.expires" />) is present, use 589 its value minus the value of the Date response header, or</t> 590 <t>Otherwise, no explicit expiration time is present in the response. A heuristic 591 freshness lifetime might be applicable; see <xref target="heuristic.freshness" />.</t> 592 </list> 593 </t> 594 <t> 595 Note that this calculation is not vulnerable to clock skew, since all of the 596 information comes from the origin server. 644 597 </t> 645 598 646 599 <section anchor="heuristic.freshness" title="Calculating Heuristic Freshness"> 647 600 <t> 648 If no explicit expiration time is present in a stored response that has a 649 status code of 200, 203, 206, 300, 301 or 410, a heuristic expiration time 650 can be calculated. Heuristics &MUST-NOT; be used for other response status 651 codes. 652 </t> 653 <t> 654 When a heuristic is used to calculate freshness lifetime, the cache 655 &SHOULD; attach a Warning header with a 113 warn-code to the response if 656 its current_age is more than 24 hours and such a warning is not already 657 present. 658 </t> 659 <t> 660 Also, if the response has a Last-Modified header (&header-last-modified;), 661 the heuristic expiration value &SHOULD; be no more than some fraction of 662 the interval since that time. A typical setting of this fraction might be 663 10%. 601 If no explicit expiration time is present in a stored response that has a status code 602 of 200, 203, 206, 300, 301 or 410, a heuristic expiration time can be 603 calculated. Heuristics &MUST-NOT; be used for other response status codes. 604 </t> 605 <t> 606 When a heuristic is used to calculate freshness lifetime, the cache &SHOULD; 607 attach a Warning header with a 113 warn-code to the response if its current_age is 608 more than 24 hours and such a warning is not already present. 609 </t> 610 <t> 611 Also, if the response has a Last-Modified header (&header-last-modified;), the 612 heuristic expiration value &SHOULD; be no more than some fraction of the interval 613 since that time. A typical setting of this fraction might be 10%. 664 614 </t> 665 615 <x:note> 666 667 <x:h>Note:</x:h> RFC 2616 (<xref target="RFC2616" x:fmt=","668 x:sec="13.9"/>) required that caches do not calculate heuristic669 freshness for URLs with query components (i.e., those containing '?').670 In practice, this has not been widely implemented. Therefore, servers671 are encouraged to send explicit directives (e.g., Cache-Control:672 no-cache) if they wish to precludecaching.673 616 <t> 617 <x:h>Note:</x:h> RFC 2616 (<xref target="RFC2616" x:fmt="," x:sec="13.9"/>) 618 required that caches do not calculate heuristic freshness for URLs with 619 query components (i.e., those containing '?'). In practice, this has not 620 been widely implemented. Therefore, servers are encouraged to send explicit 621 directives (e.g., Cache-Control: no-cache) if they wish to preclude 622 caching. 623 </t> 674 624 </x:note> 675 625 </section> … … 678 628 <section anchor="age.calculations" title="Calculating Age"> 679 629 <t> 680 HTTP/1.1 uses the Age response-header to convey the estimated age of the 681 response message when obtained from a cache. The Age field value is the 682 cache's estimate of the amount of time since the response was generated or 683 validated by the origin server. In essence, the Age value is the sum of the 684 time that the response has been resident in each of the caches along the 685 path from the origin server, plus the amount of time it has been in transit 686 along network paths. 687 </t> 688 <t> 689 The following data is used for the age calculation: 690 </t> 691 <t> 692 <x:dfn>age_value</x:dfn> 693 <list> 694 <t> 695 The term "age_value" denotes the value of the Age header (<xref 696 target="header.age"/>), in a form appropriate for arithmetic 697 operation; or 0, if not available. 698 </t> 699 </list> 700 </t> 701 <t> 702 <x:dfn>date_value</x:dfn> 703 <list> 704 <t> 705 HTTP/1.1 requires origin servers to send a Date header, if possible, 706 with every response, giving the time at which the response was 707 generated. The term "date_value" denotes the value of the Date 708 header, in a form appropriate for arithmetic operations. See 709 &header-date; for the definition of the Date header, and for 710 requirements regarding responses without a Date response header. 711 </t> 712 </list> 713 </t> 714 <t> 715 <x:dfn>now</x:dfn> 716 <list> 717 <t> 718 The term "now" means "the current value of the clock at the host 719 performing the calculation". Hosts that use HTTP, but especially 720 hosts running origin servers and caches, &SHOULD; use NTP (<xref 721 target="RFC1305"/>) or some similar protocol to synchronize their 722 clocks to a globally accurate time standard. 723 </t> 724 </list> 725 </t> 726 <t> 727 <x:dfn>request_time</x:dfn> 728 <list> 729 <t> 730 The current value of the clock at the host at the time the request 731 resulting in the stored response was made. 732 </t> 733 </list> 734 </t> 735 <t> 736 <x:dfn>response_time</x:dfn> 737 <list> 738 <t> 739 The current value of the clock at the host at the time the response 740 was received. 741 </t> 742 </list> 743 </t> 744 <t> 745 A response's age can be calculated in two entirely independent ways: 746 <list style="numbers"> 747 <t>the "apparent_age": response_time minus date_value, if the local 748 clock is reasonably well synchronized to the origin server's clock. If 749 the result is negative, the result is replaced by zero.</t> 750 <t>the "corrected_age_value", if all of the caches along the response 751 path implement HTTP/1.1; note this value &MUST; be interpreted relative 752 to the time the request was initiated, not the time that the response 753 was received.</t> 754 </list> 630 HTTP/1.1 uses the Age response-header to convey the estimated age of the response 631 message when obtained from a cache. The Age field value is the cache's estimate of the 632 amount of time since the response was generated or validated by the origin server. In 633 essence, the Age value is the sum of the time that the response has been resident in 634 each of the caches along the path from the origin server, plus the amount of time it has 635 been in transit along network paths. 636 </t> 637 <t> 638 The following data is used for the age calculation: 639 </t> 640 <t> 641 <x:dfn>age_value</x:dfn> 642 <list> 643 <t> 644 The term "age_value" denotes the value of the Age header (<xref target="header.age"/>), 645 in a form appropriate for arithmetic operation; or 0, if not available. 646 </t> 647 </list> 648 </t> 649 <t> 650 <x:dfn>date_value</x:dfn> 651 <list> 652 <t> 653 HTTP/1.1 requires origin servers to send a Date header, if possible, 654 with every response, giving the time at which the response was generated. 655 The term "date_value" denotes the value of the Date header, in a form 656 appropriate for arithmetic operations. See &header-date; for the definition 657 of the Date header, and for requirements regarding responses without a 658 Date response header. 659 </t> 660 </list> 661 </t> 662 <t> 663 <x:dfn>now</x:dfn> 664 <list> 665 <t> 666 The term "now" means "the current value of the clock at the host 667 performing the calculation". Hosts that use HTTP, but especially hosts 668 running origin servers and caches, &SHOULD; use NTP 669 (<xref target="RFC1305"/>) or some similar protocol to synchronize their 670 clocks to a globally accurate time standard. 671 </t> 672 </list> 673 </t> 674 <t> 675 <x:dfn>request_time</x:dfn> 676 <list> 677 <t> 678 The current value of the clock at the host at the time the request 679 resulting in the stored response was made. 680 </t> 681 </list> 682 </t> 683 <t> 684 <x:dfn>response_time</x:dfn> 685 <list> 686 <t> 687 The current value of the clock at the host at the time the response was 688 received. 689 </t> 690 </list> 691 </t> 692 <t> 693 A response's age can be calculated in two entirely independent ways: 694 <list style="numbers"> 695 <t>the "apparent_age": response_time minus date_value, if the local clock is reasonably well synchronized to the 696 origin server's clock. If the result is negative, the result is replaced by zero.</t> 697 <t>the "corrected_age_value", if all of the caches along the response path implement HTTP/1.1; 698 note this value &MUST; be interpreted relative to the time the 699 request was initiated, not the time that the response was received.</t> 700 </list> 755 701 </t> 756 702 <figure> … … 768 714 </artwork></figure> 769 715 <t> 770 The current_age of a stored response can then be calculated by adding the771 amount of time (in seconds) since the stored response was last validated by772 the origin server tothe corrected_initial_age.716 The current_age of a stored response can then be calculated by adding the amount of 717 time (in seconds) since the stored response was last validated by the origin server to 718 the corrected_initial_age. 773 719 </t> 774 720 <figure><artwork type="code"> … … 780 726 <section anchor="serving.stale.responses" title="Serving Stale Responses"> 781 727 <t> 782 A "stale" response is one that either has explicit expiry information or is 783 allowed to have heuristic expiry calculated, but is not fresh according to 784 the calculations in <xref target="expiration.model" />. 785 </t> 786 <t> 787 Caches &MUST-NOT; return a stale response if it is prohibited by an 788 explicit in-protocol directive (e.g., by a "no-store" or "no-cache" cache 789 directive, a "must-revalidate" cache-response-directive, or an applicable 790 "s-maxage" or "proxy-revalidate" cache-response-directive; see <xref 791 target="cache-response-directive"/>). 792 </t> 793 <t> 794 Caches &SHOULD-NOT; return stale responses unless they are disconnected 795 (i.e., it cannot contact the origin server or otherwise find a forward 796 path) or otherwise explicitly allowed (e.g., the max-stale request 797 directive; see <xref target="cache-request-directive" />). 798 </t> 799 <t> 800 Stale responses &SHOULD; have a Warning header with the 110 warn-code (see 801 <xref target="header.warning" />). Likewise, the 112 warn-code &SHOULD; be 802 sent on stale responses if the cache is disconnected. 803 </t> 804 <t> 805 If a cache receives a first-hand response (either an entire response, or a 806 304 (Not Modified) response) that it would normally forward to the 807 requesting client, and the received response is no longer fresh, the cache 808 &SHOULD; forward it to the requesting client without adding a new Warning 809 (but without removing any existing Warning headers). A cache &SHOULD-NOT; 810 attempt to validate a response simply because that response became stale in 811 transit. 728 A "stale" response is one that either has explicit expiry information or is allowed to 729 have heuristic expiry calculated, but is not fresh according to the calculations in 730 <xref target="expiration.model" />. 731 </t> 732 <t> 733 Caches &MUST-NOT; return a stale response if it is prohibited by an explicit 734 in-protocol directive (e.g., by a "no-store" or "no-cache" cache directive, a 735 "must-revalidate" cache-response-directive, or an applicable "s-maxage" or 736 "proxy-revalidate" cache-response-directive; see <xref target="cache-response-directive"/>). 737 </t> 738 <t> 739 Caches &SHOULD-NOT; return stale responses unless they are 740 disconnected (i.e., it cannot contact the origin server or otherwise find a forward path) 741 or otherwise explicitly allowed (e.g., the max-stale request directive; see <xref target="cache-request-directive" />). 742 </t> 743 <t> 744 Stale responses &SHOULD; have a Warning header with the 110 warn-code (see <xref 745 target="header.warning" />). Likewise, the 112 warn-code &SHOULD; be sent on stale responses if 746 the cache is disconnected. 747 </t> 748 <t> 749 If a cache receives a first-hand response (either an entire response, or a 304 (Not 750 Modified) response) that it would normally forward to the requesting client, and the 751 received response is no longer fresh, the cache &SHOULD; forward it to the 752 requesting client without adding a new Warning (but without removing any existing 753 Warning headers). A cache &SHOULD-NOT; attempt to validate a response simply because 754 that response became stale in transit. 812 755 </t> 813 756 </section> … … 816 759 <section anchor="validation.model" title="Validation Model"> 817 760 <t> 818 When a cache has one or more stored responses for a requested URI, but 819 cannot serve any of them (e.g., because they are not fresh, or one cannot 820 be selected; see <xref target="caching.negotiated.responses"/>), it can use 821 the conditional request mechanism &conditional; in the forwarded request to 822 give the origin server an opportunity to both select a valid stored 823 response to be used, and to update it. This process is known as 824 "validating" or "revalidating" the stored response. 825 </t> 826 <t> 827 When sending such a conditional request, the cache &SHOULD; add an 828 If-Modified-Since header whose value is that of the Last-Modified header 829 from the selected (see <xref target="caching.negotiated.responses"/>) 830 stored response, if available. 831 </t> 832 <t> 833 Additionally, the cache &SHOULD; add an If-None-Match header whose value is 834 that of the ETag header(s) from all responses stored for the requested URI, 835 if present. However, if any of the stored responses contains only partial 836 content, its entity-tag &SHOULD-NOT; be included in the If-None-Match 837 header field unless the request is for a range that would be fully 838 satisfied by that stored response. 839 </t> 840 <t> 841 A 304 (Not Modified) response status code indicates that the stored 842 response can be updated and reused; see <xref target="combining.headers"/>. 843 </t> 844 <t> 845 A full response (i.e., one with a response body) indicates that none of the 846 stored responses nominated in the conditional request is suitable. Instead, 847 the full response is used both to satisfy the request and replace the 848 stored response. <cref anchor="TODO-req-missing">Should there be a 849 requirement here?</cref> 850 </t> 851 <t> 852 If a cache receives a 5xx response while attempting to validate a response, 853 it &MAY; either forward this response to the requesting client, or act as 854 if the server failed to respond. In the latter case, it &MAY; return a 855 previously stored response (see <xref target="serving.stale.responses" />). 856 </t> 857 </section> 858 859 <section anchor="invalidation.after.updates.or.deletions" 860 title="Request Methods that Invalidate"> 861 <t> 862 Because unsafe methods (&safe-methods;) have the potential for changing 863 state on the origin server, intervening caches can use them to keep their 864 contents up-to-date. 865 </t> 866 <t> 867 The following HTTP methods &MUST; cause a cache to invalidate the Effective 868 Request URI (&effective-request-uri;) as well as the URI(s) in the Location 869 and Content-Location headers (if present): 870 <list style="symbols"> 871 <t>PUT</t> 872 <t>DELETE</t> 873 <t>POST</t> 874 </list> 875 </t> 876 <t> 877 An invalidation based on a URI from a Location or Content-Location header 878 &MUST-NOT; be performed if the host part of that URI differs from the host 879 part in the Effective Request URI (&effective-request-uri;). This helps 880 prevent denial of service attacks. 881 </t> 882 <t> 883 <cref anchor="TODO-def-host-part">"host part" needs to be specified 884 better.</cref> 885 </t> 886 <t> 887 A cache that passes through requests for methods it does not understand 888 &SHOULD; invalidate the Effective Request URI (&effective-request-uri;). 889 </t> 890 <t> 891 Here, "invalidate" means that the cache will either remove all stored 892 responses related to the Effective Request URI, or will mark these as 893 "invalid" and in need of a mandatory validation before they can be returned 894 in response to a subsequent request. 895 </t> 896 <t> 897 Note that this does not guarantee that all appropriate responses are 898 invalidated. For example, the request that caused the change at the origin 899 server might not have gone through the cache where a response is stored. 900 </t> 901 <t> 902 <cref anchor="TODO-spec-success-invalidate">specify that only successful 903 (2xx, 3xx?) responses invalidate.</cref> 904 </t> 905 </section> 906 907 <section anchor="caching.authenticated.responses" 908 title="Shared Caching of Authenticated Responses"> 909 910 <t> 911 Shared caches &MUST-NOT; use a cached response to a request with an 912 Authorization header (&header-authorization;) to satisfy any subsequent 913 request unless a cache directive that allows such responses to be stored is 914 present in the response. 915 </t> 916 917 <t> 918 In this specification, the following Cache-Control response directives 919 (<xref target="cache-response-directive"/>) have such an effect: 920 must-revalidate, public, s-maxage. 921 </t> 922 923 <t> 924 Note that cached responses that contain the "must-revalidate" and/or 925 "s-maxage" response directives are not allowed to be served stale (<xref 926 target="serving.stale.responses"/>) by shared caches. In particular, a 927 response with either "max-age=0, must-revalidate" or "s-maxage=0" cannot be 928 used to satisfy a subsequent request without revalidating it on the origin 929 server. 930 </t> 931 </section> 932 933 <section anchor="caching.negotiated.responses" 934 title="Caching Negotiated Responses"> 935 <t> 936 When a cache receives a request that can be satisfied by a stored response 937 that has a Vary header field (<xref target="header.vary"/>), it &MUST-NOT; 938 use that response unless all of the selecting request-headers nominated by 939 the Vary header match in both the original request (i.e., that associated 940 with the stored response), and the presented request. 941 </t> 942 <t> 943 The selecting request-headers from two requests are defined to match if and 944 only if those in the first request can be transformed to those in the 945 second request by applying any of the following: 946 <list style="symbols"> 947 <t> 761 When a cache has one or more stored responses for a requested URI, but cannot 762 serve any of them (e.g., because they are not fresh, or one cannot be selected; 763 see <xref target="caching.negotiated.responses"/>), 764 it can use the conditional request mechanism &conditional; in the forwarded 765 request to give the origin server an opportunity to both select a valid stored 766 response to be used, and to update it. This process is known as "validating" 767 or "revalidating" the stored response. 768 </t> 769 <t> 770 When sending such a conditional request, the cache &SHOULD; add an If-Modified-Since 771 header whose value is that of the Last-Modified header from the selected 772 (see <xref target="caching.negotiated.responses"/>) stored response, if available. 773 </t> 774 <t> 775 Additionally, the cache &SHOULD; add an If-None-Match header whose value 776 is that of the ETag header(s) from all responses stored for the requested URI, 777 if present. However, if any of the stored responses contains only partial 778 content, its entity-tag &SHOULD-NOT; be included in the If-None-Match header 779 field unless the request is for a range that would be fully satisfied by 780 that stored response. 781 </t> 782 <t> 783 A 304 (Not Modified) response status code indicates that the stored 784 response can be updated and reused; see <xref target="combining.headers"/>. 785 </t> 786 <t> 787 A full response (i.e., one with a response body) indicates that none 788 of the stored responses nominated in the conditional request is 789 suitable. Instead, the full response is used both to satisfy the 790 request and replace the stored response. <cref anchor="TODO-req-missing">Should there be a requirement here?</cref> 791 </t> 792 <t> 793 If a cache receives a 5xx response while attempting to validate a response, it &MAY; 794 either forward this response to the requesting client, or act as if the server failed to 795 respond. In the latter case, it &MAY; return a previously stored response (see <xref 796 target="serving.stale.responses" />). 797 </t> 798 </section> 799 800 <section anchor="invalidation.after.updates.or.deletions" title="Request Methods that Invalidate"> 801 <t> 802 Because unsafe methods (&safe-methods;) have the potential for changing state on the 803 origin server, intervening caches can use them to keep their contents 804 up-to-date. 805 </t> 806 <t> 807 The following HTTP methods &MUST; cause a cache to invalidate the Effective Request URI (&effective-request-uri;) as well 808 as the URI(s) in the Location and Content-Location headers (if present): 809 <list style="symbols"> 810 <t>PUT</t> 811 <t>DELETE</t> 812 <t>POST</t> 813 </list> 814 </t> 815 <t> 816 An invalidation based on a URI from a Location or Content-Location header &MUST-NOT; 817 be performed if the host part of that URI differs from the host part in the Effective Request URI (&effective-request-uri;). 818 This helps prevent denial of service attacks. 819 </t> 820 <t> 821 <cref anchor="TODO-def-host-part">"host part" needs to be specified better.</cref> 822 </t> 823 <t> 824 A cache that passes through requests for methods it does not understand &SHOULD; 825 invalidate the Effective Request URI (&effective-request-uri;). 826 </t> 827 <t> 828 Here, "invalidate" means that the cache will either remove all stored responses related 829 to the Effective Request URI, or will mark these as "invalid" and in need of a mandatory validation 830 before they can be returned in response to a subsequent request. 831 </t> 832 <t> 833 Note that this does not guarantee that all appropriate responses are invalidated. For 834 example, the request that caused the change at the origin server might not have gone 835 through the cache where a response is stored. 836 </t> 837 <t> 838 <cref anchor="TODO-spec-success-invalidate">specify that only successful (2xx, 3xx?) responses invalidate.</cref> 839 </t> 840 </section> 841 842 <section anchor="caching.authenticated.responses" title="Shared Caching of Authenticated Responses"> 843 844 <t>Shared caches &MUST-NOT; use a cached response to a request with an Authorization header (&header-authorization;) to satisfy any subsequent request unless a cache directive that allows such responses to be stored is present in the response.</t> 845 846 <t>In this specification, the following Cache-Control response directives (<xref target="cache-response-directive"/>) have such an effect: must-revalidate, public, s-maxage.</t> 847 848 <t>Note that cached responses that contain the "must-revalidate" and/or "s-maxage" response directives are not allowed to be served stale (<xref target="serving.stale.responses"/>) by shared caches. In particular, a response with either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to satisfy a subsequent request without revalidating it on the origin server.</t> 849 </section> 850 851 <section anchor="caching.negotiated.responses" title="Caching Negotiated Responses"> 852 <t> 853 When a cache receives a request that can be satisfied by a stored response 854 that has a Vary header field (<xref target="header.vary"/>), it &MUST-NOT; use that 855 response unless all of the selecting request-headers nominated by the Vary header match 856 in both the original request (i.e., that associated with the stored response), 857 and the presented request. 858 </t> 859 <t> 860 The selecting request-headers from two requests are defined to match 861 if and only if those in the first request can be transformed to those in the 862 second request by applying any of the following: 863 <list style="symbols"> 864 <t> 948 865 adding or removing whitespace, where allowed in the header's syntax 949 950 866 </t> 867 <t> 951 868 combining multiple message-header fields with the same field name (see 952 869 &header-fields;) 953 954 870 </t> 871 <t> 955 872 normalizing both header values in a way that is known to have identical 956 semantics, according to the header's specification (e.g., re-ordering 957 field values when order is not significant; case-normalization, where 958 values are defined to be case-insensitive) 959 </t> 960 </list> 961 </t> 962 <t> 963 If (after any normalisation that may take place) a header field is absent 964 from a request, it can only match another request if it is also absent 965 there. 966 </t> 967 <t> 968 A Vary header field-value of "*" always fails to match, and subsequent 969 requests to that resource can only be properly interpreted by the origin 970 server. 971 </t> 972 <t> 973 The stored response with matching selecting request-headers is known as the 974 selected response. 975 </t> 976 <t> 977 If no selected response is available, the cache &MAY; forward the presented 978 request to the origin server in a conditional request; see <xref 979 target="validation.model"/>. 873 semantics, according to the header's specification (e.g., re-ordering field values 874 when order is not significant; case-normalization, where values are defined to be 875 case-insensitive) 876 </t> 877 </list> 878 </t> 879 <t> 880 If (after any normalisation that may take place) a header field is absent 881 from a request, it can only match another request if it is also absent there. 882 </t> 883 <t> 884 A Vary header field-value of "*" always fails to match, and subsequent requests to that 885 resource can only be properly interpreted by the origin server. 886 </t> 887 <t> 888 The stored response with matching selecting request-headers is known as the 889 selected response. 890 </t> 891 <t> 892 If no selected response is available, the cache &MAY; forward the presented 893 request to the origin server in a conditional request; see <xref target="validation.model"/>. 980 894 </t> 981 895 </section> … … 983 897 <section anchor="combining.headers" title="Combining Responses"> 984 898 <t> 985 When a cache receives a 304 (Not Modified) response or a 206 (Partial 986 Content) response (in this section, the "new" response"), it needs to 987 created an updated response by combining the stored response with the new 988 one, so that the updated response can be used to satisfy the request. 989 </t> 990 <t> 991 If the new response contains an ETag, it identifies the stored response to 992 use. <cref anchor="TODO-mention-CL">may need language about 993 Content-Location here</cref><cref anchor="TODO-inm-mult-etags">cover case 994 where INM with multiple etags was sent</cref> 995 </t> 996 <t> 997 If the status code is 206 (partial content), both the stored and new 998 responses &MUST; have validators, and those validators &MUST; match using 999 the strong comparison function (see &weak-and-strong;). Otherwise, the 1000 responses &MUST-NOT; be combined. 1001 </t> 1002 <t> 1003 The stored response headers are used as those of the updated response, 1004 except that 1005 <list style="symbols"> 1006 <t>any stored Warning headers with warn-code 1xx (see <xref 1007 target="header.warning" />) &MUST; be deleted from the stored response 1008 and the updated response.</t> 1009 <t>any stored Warning headers with warn-code 2xx &MUST; be retained in 1010 the stored response and the updated response.</t> 1011 <t>any headers provided in the new response &MUST; replace the 1012 corresponding headers from the stored response.</t> 1013 </list> 1014 </t> 1015 <t> 1016 If a header field-name in the new response matches more than one header in 1017 the stored response, all such stored headers &MUST; be replaced. 1018 </t> 1019 <t> 1020 The updated response can <cref anchor="TODO-is-req">requirement?</cref> be 1021 used to replace the stored response in cache. In the case of a 206 1022 response, the combined entity-body &MAY; be stored. 1023 </t> 1024 <t> 1025 <cref anchor="ISSUE-how-head">discuss how to handle HEAD updates</cref> 899 When a cache receives a 304 (Not Modified) response or a 206 (Partial Content) response 900 (in this section, the "new" response"), it needs to created an updated response by combining 901 the stored response with the new one, so that the updated response can be used to satisfy the request. 902 </t> 903 <t> 904 If the new response contains an ETag, it identifies the stored 905 response to use. <cref anchor="TODO-mention-CL">may need language about Content-Location 906 here</cref><cref anchor="TODO-inm-mult-etags">cover case where INM with multiple etags was sent</cref> 907 </t> 908 <t> 909 If the status code is 206 (partial content), both the stored and new 910 responses &MUST; have validators, and those validators &MUST; match using the strong 911 comparison function (see &weak-and-strong;). Otherwise, the 912 responses &MUST-NOT; be combined. 913 </t> 914 <t> 915 The stored response headers are used as those of the updated response, except that 916 <list style="symbols"> 917 <t>any stored Warning headers with warn-code 1xx (see <xref target="header.warning" />) 918 &MUST; be deleted from the stored response and the updated response.</t> 919 <t>any stored Warning headers with warn-code 2xx &MUST; be retained in the stored 920 response and the updated response.</t> 921 <t>any headers provided in the new response &MUST; replace the corresponding 922 headers from the stored response.</t> 923 </list> 924 </t> 925 <t> 926 If a header field-name in the new response matches more than one 927 header in the stored response, all such stored headers &MUST; be replaced. 928 </t> 929 <t> 930 The updated response can <cref anchor="TODO-is-req">requirement?</cref> be used to replace the 931 stored response in cache. In the case of a 206 response, the combined 932 entity-body &MAY; be stored. 933 </t> 934 <t> 935 <cref anchor="ISSUE-how-head">discuss how to handle HEAD updates</cref> 1026 936 </t> 1027 937 </section> … … 1031 941 <section anchor="header.fields" title="Header Field Definitions"> 1032 942 <t> 1033 1034 1035 </t> 1036 <t> 1037 For entity-header fields, both sender and recipient refer to either the1038 client or theserver, depending on who sends and who receives the entity.943 This section defines the syntax and semantics of HTTP/1.1 header fields 944 related to caching. 945 </t> 946 <t> 947 For entity-header fields, both sender and recipient refer to either the client or the 948 server, depending on who sends and who receives the entity. 1039 949 </t> 1040 950 1041 951 <section anchor="header.age" title="Age"> 1042 1043 1044 1045 1046 1047 <t> 1048 1049 1050 origin server. Age values are calculated as specified in <xref1051 target="age.calculations" />.952 <iref item="Age header" primary="true" x:for-anchor="" /> 953 <iref item="Headers" primary="true" subitem="Age" x:for-anchor="" /> 954 <x:anchor-alias value="Age"/> 955 <x:anchor-alias value="Age-v"/> 956 <x:anchor-alias value="age-value"/> 957 <t> 958 The "Age" response-header field conveys the sender's estimate of the amount 959 of time since the response was generated or successfully validated at the 960 origin server. Age values are calculated as specified in 961 <xref target="age.calculations" />. 1052 962 </t> 1053 963 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Age"/><iref primary="true" item="Grammar" subitem="Age-v"/> … … 1056 966 </artwork></figure> 1057 967 <t anchor="rule.delta-seconds"> 1058 1059 968 <x:anchor-alias value="delta-seconds" /> 969 Age field-values are non-negative integers, representing time in seconds. 1060 970 </t> 1061 971 <figure><artwork type="abnf2616"><iref item="Grammar" primary="true" subitem="delta-seconds" /> … … 1063 973 </artwork></figure> 1064 974 <t> 1065 If a cache receives a value larger than the largest positive integer it can1066 represent, or if any of its age calculations overflows, it &MUST; transmit1067 an Age header with a field-value of 2147483648 (2<x:sup>31</x:sup>). Caches1068 &SHOULD; use an arithmetic typeof at least 31 bits of range.1069 </t> 1070 <t> 1071 The presence of an Age header field in a response implies that a response1072 is not first-hand. However, the converse is not true, since HTTP/1.0 caches1073 may not implement theAge header field.975 If a cache receives a value larger than the largest positive integer it can represent, or 976 if any of its age calculations overflows, it &MUST; transmit an Age header with a 977 field-value of 2147483648 (2<x:sup>31</x:sup>). Caches &SHOULD; use an arithmetic type 978 of at least 31 bits of range. 979 </t> 980 <t> 981 The presence of an Age header field in a response implies that a response is not 982 first-hand. However, the converse is not true, since HTTP/1.0 caches may not implement the 983 Age header field. 1074 984 </t> 1075 985 </section> 1076 986 1077 987 <section anchor="header.cache-control" title="Cache-Control"> 1078 <iref item="Cache-Control header" primary="true" x:for-anchor="" /> 1079 <iref item="Headers" primary="true" subitem="Cache-Control" 1080 x:for-anchor="" /> 1081 <x:anchor-alias value="Cache-Control"/> 1082 <x:anchor-alias value="Cache-Control-v"/> 1083 <x:anchor-alias value="cache-directive"/> 1084 <x:anchor-alias value="cache-extension"/> 1085 <x:anchor-alias value="cache-request-directive"/> 1086 <x:anchor-alias value="cache-response-directive"/> 1087 <t> 1088 The "Cache-Control" general-header field is used to specify directives for 1089 caches along the request/response chain. Such cache directives are 1090 unidirectional in that the presence of a directive in a request does not 1091 imply that the same directive is to be given in the response. 1092 </t> 1093 <t> 1094 HTTP/1.1 caches &MUST; obey the requirements of the Cache-Control 1095 directives defined in this section. See <xref 1096 target="cache.control.extensions"/> for information about how Cache-Control 1097 directives defined elsewhere are handled. 988 <iref item="Cache-Control header" primary="true" x:for-anchor="" /> 989 <iref item="Headers" primary="true" subitem="Cache-Control" x:for-anchor="" /> 990 <x:anchor-alias value="Cache-Control"/> 991 <x:anchor-alias value="Cache-Control-v"/> 992 <x:anchor-alias value="cache-directive"/> 993 <x:anchor-alias value="cache-extension"/> 994 <x:anchor-alias value="cache-request-directive"/> 995 <x:anchor-alias value="cache-response-directive"/> 996 <t> 997 The "Cache-Control" general-header field is used to specify directives for 998 caches along the request/response chain. Such cache directives are 999 unidirectional in that the presence of a directive in a request does not 1000 imply that the same directive is to be given in the response. 1001 </t> 1002 <t> 1003 HTTP/1.1 caches &MUST; obey the requirements of the Cache-Control directives 1004 defined in this section. See <xref target="cache.control.extensions"/> for 1005 information about how Cache-Control directives defined elsewhere are handled. 1098 1006 </t> 1099 1007 <x:note> 1100 1008 <t> 1101 1009 <x:h>Note:</x:h> HTTP/1.0 caches might not implement Cache-Control and 1102 might only implement Pragma: no-cache (see <xref target="header.pragma" 1103 />). 1010 might only implement Pragma: no-cache (see <xref target="header.pragma" />). 1104 1011 </t> 1105 1012 </x:note> 1106 1013 <t> 1107 Cache directives &MUST; be passed through by a proxy or gateway 1108 application, regardless of their significance to that application, since 1109 the directives might be applicable to all recipients along the 1110 request/response chain. It is not possible to target a directive to a 1111 specific cache. 1014 Cache directives &MUST; be passed through by a proxy or gateway application, 1015 regardless of their significance to that application, since the directives might be 1016 applicable to all recipients along the request/response chain. It is not possible to 1017 target a directive to a specific cache. 1112 1018 </t> 1113 1019 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Cache-Control"/><iref primary="true" item="Grammar" subitem="Cache-Control-v"/><iref primary="true" item="Grammar" subitem="cache-extension"/> … … 1121 1027 </artwork></figure> 1122 1028 1123 <section anchor="cache-request-directive" 1124 title="Request Cache-Control Directives"> 1029 <section anchor="cache-request-directive" title="Request Cache-Control Directives"> 1125 1030 <x:anchor-alias value="cache-request-directive" /> 1126 1031 1127 <figure><artwork type="abnf2616"><iref item="Grammar" primary="true" 1128 subitem="cache-request-directive" /> 1032 <figure><artwork type="abnf2616"><iref item="Grammar" primary="true" subitem="cache-request-directive" /> 1129 1033 <x:ref>cache-request-directive</x:ref> = 1130 1034 "no-cache" … … 1139 1043 1140 1044 <t> 1141 <x:dfn>no-cache</x:dfn> 1142 <iref item="Cache Directives" primary="true" subitem="no-cache" /> 1143 <iref item="no-cache" primary="true" subitem="Cache Directive" /> 1144 <list> 1145 <t>The no-cache request directive indicates that a stored response 1146 &MUST-NOT; be used to satisfy the request without successful validation 1147 on the origin server.</t> 1148 </list> 1149 </t> 1150 <t> 1151 <x:dfn>no-store</x:dfn> 1152 <iref item="Cache Directives" primary="true" subitem="no-store" /> 1153 <iref item="no-store" primary="true" subitem="Cache Directive" /> 1154 <list> 1155 <t>The no-store request directive indicates that a cache &MUST-NOT; 1156 store any part of either this request or any response to it. This 1157 directive applies to both non-shared and shared caches. "&MUST-NOT; 1158 store" in this context means that the cache &MUST-NOT; intentionally 1159 store the information in non-volatile storage, and &MUST; make a 1160 best-effort attempt to remove the information from volatile storage as 1161 promptly as possible after forwarding it.</t> 1162 <t>This directive is NOT a reliable or sufficient mechanism for ensuring 1163 privacy. In particular, malicious or compromised caches might not 1164 recognize or obey this directive, and communications networks may be 1165 vulnerable to eavesdropping.</t> 1166 </list> 1167 </t> 1168 <t> 1169 <x:dfn>max-age</x:dfn> 1170 <iref item="Cache Directives" primary="true" subitem="max-age" /> 1171 <iref item="max-age" primary="true" subitem="Cache Directive" /> 1172 <list> 1173 <t>The max-age request directive indicates that the client is willing to 1174 accept a response whose age is no greater than the specified time in 1175 seconds. Unless the max-stale request directive is also present, the 1176 client is not willing to accept a stale response.</t> 1177 </list> 1178 </t> 1179 <t> 1180 <x:dfn>max-stale</x:dfn> 1181 <iref item="Cache Directives" primary="true" subitem="max-stale" /> 1182 <iref item="max-stale" primary="true" subitem="Cache Directive" /> 1183 <list> 1184 <t>The max-stale request directive indicates that the client is willing 1185 to accept a response that has exceeded its expiration time. If max-stale 1186 is assigned a value, then the client is willing to accept a response 1187 that has exceeded its expiration time by no more than the specified 1188 number of seconds. If no value is assigned to max-stale, then the client 1189 is willing to accept a stale response of any age. <cref 1190 anchor="TODO-staleness" source="mnot">of any staleness?</cref></t> 1191 </list> 1192 </t> 1193 <t> 1194 <x:dfn>min-fresh</x:dfn> 1195 <iref item="Cache Directives" primary="true" subitem="min-fresh" /> 1196 <iref item="min-fresh" primary="true" subitem="Cache Directive" /> 1197 <list> 1198 <t>The min-fresh request directive indicates that the client is willing 1199 to accept a response whose freshness lifetime is no less than its 1200 current age plus the specified time in seconds. That is, the client 1201 wants a response that will still be fresh for at least the specified 1202 number of seconds.</t> 1203 </list> 1204 </t> 1205 <t> 1206 <x:dfn>no-transform</x:dfn> 1207 <iref item="Cache Directives" primary="true" subitem="no-transform" /> 1208 <iref item="no-transform" primary="true" subitem="Cache Directive" /> 1209 <list> 1210 <t>The no-transform request directive indicates that an intermediate 1211 cache or proxy &MUST-NOT; change the Content-Encoding, Content-Range or 1212 Content-Type request headers, nor the request entity-body.</t> 1213 </list> 1214 </t> 1215 <t> 1216 <x:dfn>only-if-cached</x:dfn> 1217 <iref item="Cache Directives" primary="true" subitem="only-if-cached" /> 1218 <iref item="only-if-cached" primary="true" subitem="Cache Directive" /> 1219 <list> 1220 <t>The only-if-cached request directive indicates that the client only 1221 wishes to return a stored response. If it receives this directive, a 1222 cache &SHOULD; either respond using a stored response that is consistent 1223 with the other constraints of the request, or respond with a 504 1224 (Gateway Timeout) status. If a group of caches is being operated as a 1225 unified system with good internal connectivity, such a request &MAY; be 1226 forwarded within that group of caches.</t> 1227 </list> 1228 </t> 1229 </section> 1230 1231 <section anchor="cache-response-directive" 1232 title="Response Cache-Control Directives"> 1233 <x:anchor-alias value="cache-response-directive" /> 1045 <x:dfn>no-cache</x:dfn> 1046 <iref item="Cache Directives" primary="true" subitem="no-cache" /> 1047 <iref item="no-cache" primary="true" subitem="Cache Directive" /> 1048 <list> 1049 <t>The no-cache request directive indicates that a stored response &MUST-NOT; be 1050 used to satisfy the request without successful validation on the origin server.</t> 1051 </list> 1052 </t> 1053 <t> 1054 <x:dfn>no-store</x:dfn> 1055 <iref item="Cache Directives" primary="true" subitem="no-store" /> 1056 <iref item="no-store" primary="true" subitem="Cache Directive" /> 1057 <list> 1058 <t>The no-store request directive indicates that a cache &MUST-NOT; store any part 1059 of either this request or any response to it. This directive applies to both 1060 non-shared and shared caches. "&MUST-NOT; store" in this context means that the 1061 cache &MUST-NOT; intentionally store the information in non-volatile storage, 1062 and &MUST; make a best-effort attempt to remove the information from volatile 1063 storage as promptly as possible after forwarding it.</t> 1064 <t>This directive is NOT a reliable or sufficient mechanism for ensuring privacy. In 1065 particular, malicious or compromised caches might not recognize or obey this 1066 directive, and communications networks may be vulnerable to eavesdropping.</t> 1067 </list> 1068 </t> 1069 <t> 1070 <x:dfn>max-age</x:dfn> 1071 <iref item="Cache Directives" primary="true" subitem="max-age" /> 1072 <iref item="max-age" primary="true" subitem="Cache Directive" /> 1073 <list> 1074 <t>The max-age request directive indicates that the client is willing to accept a 1075 response whose age is no greater than the specified time in seconds. Unless 1076 the max-stale request directive is also present, the client is not willing to accept a stale 1077 response.</t> 1078 </list> 1079 </t> 1080 <t> 1081 <x:dfn>max-stale</x:dfn> 1082 <iref item="Cache Directives" primary="true" subitem="max-stale" /> 1083 <iref item="max-stale" primary="true" subitem="Cache Directive" /> 1084 <list> 1085 <t>The max-stale request directive indicates that the client is willing to accept a 1086 response that has exceeded its expiration time. If max-stale is assigned a value, 1087 then the client is willing to accept a response that has exceeded its expiration 1088 time by no more than the specified number of seconds. If no value is assigned to 1089 max-stale, then the client is willing to accept a stale response of any age. <cref anchor="TODO-staleness" source="mnot">of any staleness?</cref></t> 1090 </list> 1091 </t> 1092 <t> 1093 <x:dfn>min-fresh</x:dfn> 1094 <iref item="Cache Directives" primary="true" subitem="min-fresh" /> 1095 <iref item="min-fresh" primary="true" subitem="Cache Directive" /> 1096 <list> 1097 <t>The min-fresh request directive indicates that the client is willing to accept a 1098 response whose freshness lifetime is no less than its current age plus the specified 1099 time in seconds. That is, the client wants a response that will still be fresh for 1100 at least the specified number of seconds.</t> 1101 </list> 1102 </t> 1103 <t> 1104 <x:dfn>no-transform</x:dfn> 1105 <iref item="Cache Directives" primary="true" subitem="no-transform" /> 1106 <iref item="no-transform" primary="true" subitem="Cache Directive" /> 1107 <list> 1108 <t>The no-transform request directive indicates that an intermediate cache or proxy 1109 &MUST-NOT; change the Content-Encoding, Content-Range or Content-Type request 1110 headers, nor the request entity-body.</t> 1111 </list> 1112 </t> 1113 <t> 1114 <x:dfn>only-if-cached</x:dfn> 1115 <iref item="Cache Directives" primary="true" subitem="only-if-cached" /> 1116 <iref item="only-if-cached" primary="true" subitem="Cache Directive" /> 1117 <list> 1118 <t>The only-if-cached request directive indicates that the client only wishes to 1119 return a stored response. If it receives this directive, a cache &SHOULD; either 1120 respond using a stored response that is consistent with the other constraints of the 1121 request, or respond with a 504 (Gateway Timeout) status. If a group of caches is 1122 being operated as a unified system with good internal connectivity, such a request 1123 &MAY; be forwarded within that group of caches.</t> 1124 </list> 1125 </t> 1126 </section> 1127 1128 <section anchor="cache-response-directive" title="Response Cache-Control Directives"> 1129 <x:anchor-alias value="cache-response-directive" /> 1234 1130 1235 1131 <figure><artwork type="abnf2616"><iref item="Grammar" primary="true" subitem="cache-response-directive" /> … … 1248 1144 1249 1145 <t> 1250 <x:dfn>public</x:dfn> 1251 <iref item="Cache Directives" primary="true" subitem="public" /> 1252 <iref item="public" primary="true" subitem="Cache Directive" /> 1253 <list> 1254 <t>The public response directive indicates that the response &MAY; be 1255 cached, even if it would normally be non-cacheable or cacheable only 1256 within a non-shared cache. (See also Authorization, 1257 &header-authorization;, for additional details.) </t> 1258 </list> 1259 </t> 1260 <t> 1261 <x:dfn>private</x:dfn> 1262 <iref item="Cache Directives" primary="true" subitem="private" /> 1263 <iref item="private" primary="true" subitem="Cache Directive" /> 1264 <list> 1265 <t>The private response directive indicates that the response message is 1266 intended for a single user and &MUST-NOT; be stored by a shared cache. A 1267 private (non-shared) cache &MAY; store the response.</t> 1268 <t>If the private response directive specifies one or more field-names, 1269 this requirement is limited to the field-values associated with the 1270 listed response headers. That is, the specified field-names(s) 1271 &MUST-NOT; be stored by a shared cache, whereas the remainder of the 1272 response message &MAY; be.</t> 1273 <t><x:h>Note:</x:h> This usage of the word private only controls where 1274 the response may be stored, and cannot ensure the privacy of the message 1275 content. Also, private response directives with field-names are often 1276 handled by implementations as if an unqualified private directive was 1277 received; i.e., the special handling for the qualified form is not 1278 widely implemented.</t> 1279 </list> 1280 </t> 1281 <t> 1282 <x:dfn>no-cache</x:dfn> 1283 <iref item="Cache Directives" primary="true" subitem="no-cache" /> 1284 <iref item="no-cache" primary="true" subitem="Cache Directive" /> 1285 <list> 1286 <t>The no-cache response directive indicates that the response 1287 &MUST-NOT; be used to satisfy a subsequent request without successful 1288 validation on the origin server. This allows an origin server to prevent 1289 caching even by caches that have been configured to return stale 1290 responses.</t> 1291 <t>If the no-cache response directive specifies one or more field-names, 1292 this requirement is limited to the field-values associated with the 1293 listed response headers. That is, the specified field-name(s) &MUST-NOT; 1294 be sent in the response to a subsequent request without successful 1295 validation on the origin server. This allows an origin server to prevent 1296 the re-use of certain header fields in a response, while still allowing 1297 caching of the rest of the response.</t> 1298 <t><x:h>Note:</x:h> Most HTTP/1.0 caches will not recognize or obey this 1299 directive. Also, no-cache response directives with field-names are often 1300 handled by implementations as if an unqualified no-cache directive was 1301 received; i.e., the special handling for the qualified form is not 1302 widely implemented.</t> 1303 </list> 1304 </t> 1305 <t> 1306 <x:dfn>no-store</x:dfn> 1307 <iref item="Cache Directives" primary="true" subitem="no-store" /> 1308 <iref item="no-store" primary="true" subitem="Cache Directive" /> 1309 <list> 1310 <t>The no-store response directive indicates that a cache &MUST-NOT; 1311 store any part of either the immediate request or response. This 1312 directive applies to both non-shared and shared caches. "&MUST-NOT; 1313 store" in this context means that the cache &MUST-NOT; intentionally 1314 store the information in non-volatile storage, and &MUST; make a 1315 best-effort attempt to remove the information from volatile storage as 1316 promptly as possible after forwarding it.</t> 1317 <t>This directive is NOT a reliable or sufficient mechanism for ensuring 1318 privacy. In particular, malicious or compromised caches might not 1319 recognize or obey this directive, and communications networks may be 1320 vulnerable to eavesdropping.</t> 1321 </list> 1322 </t> 1323 <t> 1324 <x:dfn>must-revalidate</x:dfn> 1325 <iref item="Cache Directives" primary="true" subitem="must-revalidate" /> 1326 <iref item="must-revalidate" primary="true" subitem="Cache Directive" /> 1327 <list> 1328 <t>The must-revalidate response directive indicates that once it has 1329 become stale, the response &MUST-NOT; be used to satisfy subsequent 1330 requests without successful validation on the origin server.</t> 1331 <t>The must-revalidate directive is necessary to support reliable 1332 operation for certain protocol features. In all circumstances an 1333 HTTP/1.1 cache &MUST; obey the must-revalidate directive; in particular, 1334 if the cache cannot reach the origin server for any reason, it &MUST; 1335 generate a 504 (Gateway Timeout) response.</t> 1336 <t>Servers &SHOULD; send the must-revalidate directive if and only if 1337 failure to validate a request on the entity could result in incorrect 1338 operation, such as a silently unexecuted financial transaction.</t> 1339 </list> 1340 </t> 1341 <t> 1342 <x:dfn>proxy-revalidate</x:dfn> 1343 <iref item="Cache Directives" primary="true" subitem="proxy-revalidate" /> 1344 <iref item="proxy-revalidate" primary="true" subitem="Cache Directive" /> 1345 <list> 1346 <t>The proxy-revalidate response directive has the same meaning as the 1347 must-revalidate response directive, except that it does not apply to 1348 non-shared caches.</t> 1349 </list> 1350 </t> 1351 <t> 1352 <x:dfn>max-age</x:dfn> 1353 <iref item="Cache Directives" primary="true" subitem="max-age" /> 1354 <iref item="max-age" primary="true" subitem="Cache Directive" /> 1355 <list> 1356 <t>The max-age response directive indicates that response is to be 1357 considered stale after its age is greater than the specified number of 1358 seconds.</t> 1359 </list> 1360 </t> 1361 <t> 1362 <x:dfn>s-maxage</x:dfn> 1363 <iref item="Cache Directives" primary="true" subitem="s-maxage" /> 1364 <iref item="s-maxage" primary="true" subitem="Cache Directive" /> 1365 <list> 1366 <t>The s-maxage response directive indicates that, in shared caches, the 1367 maximum age specified by this directive overrides the maximum age 1368 specified by either the max-age directive or the Expires header. The 1369 s-maxage directive also implies the semantics of the proxy-revalidate 1370 response directive.</t> 1371 </list> 1372 </t> 1373 <t> 1374 <x:dfn>no-transform</x:dfn> 1375 <iref item="Cache Directives" primary="true" subitem="no-transform" /> 1376 <iref item="no-transform" primary="true" subitem="Cache Directive" /> 1377 <list> 1378 <t>The no-transform response directive indicates that an intermediate 1379 cache or proxy &MUST-NOT; change the Content-Encoding, Content-Range or 1380 Content-Type response headers, nor the response entity-body.</t> 1381 </list> 1146 <x:dfn>public</x:dfn> 1147 <iref item="Cache Directives" primary="true" subitem="public" /> 1148 <iref item="public" primary="true" subitem="Cache Directive" /> 1149 <list> 1150 <t>The public response directive indicates that the response &MAY; be cached, even 1151 if it would normally be non-cacheable or cacheable only within a non-shared cache. 1152 (See also Authorization, &header-authorization;, for additional details.) </t> 1153 </list> 1154 </t> 1155 <t> 1156 <x:dfn>private</x:dfn> 1157 <iref item="Cache Directives" primary="true" subitem="private" /> 1158 <iref item="private" primary="true" subitem="Cache Directive" /> 1159 <list> 1160 <t>The private response directive indicates that the response message is intended for 1161 a single user and &MUST-NOT; be stored by a shared cache. A private (non-shared) 1162 cache &MAY; store the response.</t> 1163 <t>If the private response directive specifies one or more field-names, this 1164 requirement is limited to the field-values associated with the listed response 1165 headers. That is, the specified field-names(s) &MUST-NOT; be stored by a shared 1166 cache, whereas the remainder of the response message &MAY; be.</t> 1167 <t> 1168 <x:h>Note:</x:h> This usage of the word private only controls where the response may 1169 be stored, and cannot ensure the privacy of the message content. 1170 Also, private response directives with field-names are often handled by 1171 implementations as if an unqualified private directive was received; i.e., 1172 the special handling for the qualified form is not widely implemented.</t> 1173 </list> 1174 </t> 1175 <t> 1176 <x:dfn>no-cache</x:dfn> 1177 <iref item="Cache Directives" primary="true" subitem="no-cache" /> 1178 <iref item="no-cache" primary="true" subitem="Cache Directive" /> 1179 <list> 1180 <t>The no-cache response directive indicates that the response &MUST-NOT; be used to 1181 satisfy a subsequent request without successful validation on the origin server. 1182 This allows an origin server to prevent caching even by caches that have been 1183 configured to return stale responses.</t> 1184 <t>If the no-cache response directive specifies one or more field-names, this 1185 requirement is limited to the field-values associated with the listed response 1186 headers. That is, the specified field-name(s) &MUST-NOT; be sent in the response 1187 to a subsequent request without successful validation on the origin server. This 1188 allows an origin server to prevent the re-use of certain header fields in a 1189 response, while still allowing caching of the rest of the response.</t> 1190 <t> 1191 <x:h>Note:</x:h> Most HTTP/1.0 caches will not recognize or obey this directive. 1192 Also, no-cache response directives with field-names are often handled by 1193 implementations as if an unqualified no-cache directive was received; i.e., 1194 the special handling for the qualified form is not widely implemented. 1195 </t> 1196 </list> 1197 </t> 1198 <t> 1199 <x:dfn>no-store</x:dfn> 1200 <iref item="Cache Directives" primary="true" subitem="no-store" /> 1201 <iref item="no-store" primary="true" subitem="Cache Directive" /> 1202 <list> 1203 <t>The no-store response directive indicates that a cache &MUST-NOT; store any 1204 part of either the immediate request or response. This directive applies to both 1205 non-shared and shared caches. "&MUST-NOT; store" in this context means that the 1206 cache &MUST-NOT; intentionally store the information in non-volatile storage, 1207 and &MUST; make a best-effort attempt to remove the information from volatile 1208 storage as promptly as possible after forwarding it.</t> 1209 <t>This directive is NOT a reliable or sufficient mechanism for ensuring privacy. In 1210 particular, malicious or compromised caches might not recognize or obey this 1211 directive, and communications networks may be vulnerable to eavesdropping.</t> 1212 </list> 1213 </t> 1214 <t> 1215 <x:dfn>must-revalidate</x:dfn> 1216 <iref item="Cache Directives" primary="true" subitem="must-revalidate" /> 1217 <iref item="must-revalidate" primary="true" subitem="Cache Directive" /> 1218 <list> 1219 <t>The must-revalidate response directive indicates that once it has become stale, the response &MUST-NOT; be 1220 used to satisfy subsequent requests without successful validation on the origin server.</t> 1221 <t>The must-revalidate directive is necessary to support reliable operation for 1222 certain protocol features. In all circumstances an HTTP/1.1 cache &MUST; obey 1223 the must-revalidate directive; in particular, if the cache cannot reach the origin 1224 server for any reason, it &MUST; generate a 504 (Gateway Timeout) response.</t> 1225 <t>Servers &SHOULD; send the must-revalidate directive if and only if failure to 1226 validate a request on the entity could result in incorrect operation, such as a 1227 silently unexecuted financial transaction.</t> 1228 </list> 1229 </t> 1230 <t> 1231 <x:dfn>proxy-revalidate</x:dfn> 1232 <iref item="Cache Directives" primary="true" subitem="proxy-revalidate" /> 1233 <iref item="proxy-revalidate" primary="true" subitem="Cache Directive" /> 1234 <list> 1235 <t>The proxy-revalidate response directive has the same meaning as the must-revalidate 1236 response directive, except that it does not apply to non-shared caches.</t> 1237 </list> 1238 </t> 1239 <t> 1240 <x:dfn>max-age</x:dfn> 1241 <iref item="Cache Directives" primary="true" subitem="max-age" /> 1242 <iref item="max-age" primary="true" subitem="Cache Directive" /> 1243 <list> 1244 <t>The max-age response directive indicates that response is to be considered stale 1245 after its age is greater than the specified number of seconds.</t> 1246 </list> 1247 </t> 1248 <t> 1249 <x:dfn>s-maxage</x:dfn> 1250 <iref item="Cache Directives" primary="true" subitem="s-maxage" /> 1251 <iref item="s-maxage" primary="true" subitem="Cache Directive" /> 1252 <list> 1253 <t>The s-maxage response directive indicates that, in shared caches, the maximum age 1254 specified by this directive overrides the maximum age specified by either the 1255 max-age directive or the Expires header. The s-maxage directive also implies the 1256 semantics of the proxy-revalidate response directive.</t> 1257 </list> 1258 </t> 1259 <t> 1260 <x:dfn>no-transform</x:dfn> 1261 <iref item="Cache Directives" primary="true" subitem="no-transform" /> 1262 <iref item="no-transform" primary="true" subitem="Cache Directive" /> 1263 <list> 1264 <t>The no-transform response directive indicates that an intermediate cache or proxy 1265 &MUST-NOT; change the Content-Encoding, Content-Range or Content-Type response 1266 headers, nor the response entity-body.</t> 1267 </list> 1382 1268 </t> 1383 1269 … … 1386 1272 <section anchor="cache.control.extensions" title="Cache Control Extensions"> 1387 1273 <t> 1388 The Cache-Control header field can be extended through the use of one or 1389 more cache-extension tokens, each with an optional value. Informational 1390 extensions (those that do not require a change in cache behavior) can be 1391 added without changing the semantics of other directives. Behavioral 1392 extensions are designed to work by acting as modifiers to the existing base 1393 of cache directives. Both the new directive and the standard directive are 1394 supplied, such that applications that do not understand the new directive 1395 will default to the behavior specified by the standard directive, and those 1396 that understand the new directive will recognize it as modifying the 1397 requirements associated with the standard directive. In this way, 1398 extensions to the cache-control directives can be made without requiring 1399 changes to the base protocol. 1400 </t> 1401 <t> 1402 This extension mechanism depends on an HTTP cache obeying all of the 1403 cache-control directives defined for its native HTTP-version, obeying 1404 certain extensions, and ignoring all directives that it does not 1405 understand. 1406 </t> 1407 <t> 1408 For example, consider a hypothetical new response directive called 1409 "community" that acts as a modifier to the private directive. We define 1410 this new directive to mean that, in addition to any non-shared cache, any 1411 cache that is shared only by members of the community named within its 1412 value may cache the response. An origin server wishing to allow the UCI 1413 community to use an otherwise private response in their shared cache(s) 1414 could do so by including 1274 The Cache-Control header field can be extended through the use of one or more 1275 cache-extension tokens, each with an optional value. Informational extensions (those 1276 that do not require a change in cache behavior) can be added without changing the 1277 semantics of other directives. Behavioral extensions are designed to work by acting as 1278 modifiers to the existing base of cache directives. Both the new directive and the 1279 standard directive are supplied, such that applications that do not understand the new 1280 directive will default to the behavior specified by the standard directive, and those 1281 that understand the new directive will recognize it as modifying the requirements 1282 associated with the standard directive. In this way, extensions to the cache-control 1283 directives can be made without requiring changes to the base protocol. 1284 </t> 1285 <t> 1286 This extension mechanism depends on an HTTP cache obeying all of the cache-control 1287 directives defined for its native HTTP-version, obeying certain extensions, and ignoring 1288 all directives that it does not understand. 1289 </t> 1290 <t> 1291 For example, consider a hypothetical new response directive called "community" that 1292 acts as a modifier to the private directive. We define this new directive to mean that, 1293 in addition to any non-shared cache, any cache that is shared only by members of the 1294 community named within its value may cache the response. An origin server wishing to 1295 allow the UCI community to use an otherwise private response in their shared cache(s) 1296 could do so by including 1415 1297 </t> 1416 1298 <figure><artwork type="example"> … … 1418 1300 </artwork></figure> 1419 1301 <t> 1420 A cache seeing this header field will act correctly even if the cache does 1421 not understand the community cache-extension, since it will also see and 1422 understand the private directive and thus default to the safe behavior. 1423 </t> 1424 <t> 1425 Unrecognized cache directives &MUST; be ignored; it is assumed that any 1426 cache directive likely to be unrecognized by an HTTP/1.1 cache will be 1427 combined with standard directives (or the response's default cacheability) 1428 such that the cache behavior will remain minimally correct even if the 1429 cache does not understand the extension(s). 1430 </t> 1431 <t> 1432 The HTTP Cache Directive Registry defines the name space for the cache 1433 directives. 1434 </t> 1435 <t> 1436 Registrations &MUST; include the following fields: 1437 <list style="symbols"> 1438 <t>Cache Directive Name</t> 1439 <t>Pointer to specification text</t> 1440 </list> 1441 </t> 1442 <t> 1443 Values to be added to this name space are subject to IETF review (<xref 1444 target="RFC5226" x:fmt="," x:sec="4.1"/>). 1445 </t> 1446 <t> 1447 The registry itself is maintained at <eref 1448 target="http://www.iana.org/assignments/http-cache-directives"/>. 1302 A cache seeing this header field will act correctly even if the cache does not 1303 understand the community cache-extension, since it will also see and understand the 1304 private directive and thus default to the safe behavior. 1305 </t> 1306 <t> 1307 Unrecognized cache directives &MUST; be ignored; it is assumed that any cache 1308 directive likely to be unrecognized by an HTTP/1.1 cache will be combined with standard 1309 directives (or the response's default cacheability) such that the cache behavior will 1310 remain minimally correct even if the cache does not understand the extension(s). 1311 </t> 1312 <t> 1313 The HTTP Cache Directive Registry defines the name space for the cache 1314 directives. 1315 </t> 1316 <t> 1317 Registrations &MUST; include the following fields: 1318 <list style="symbols"> 1319 <t>Cache Directive Name</t> 1320 <t>Pointer to specification text</t> 1321 </list> 1322 </t> 1323 <t> 1324 Values to be added to this name space are subject to IETF review 1325 (<xref target="RFC5226" x:fmt="," x:sec="4.1"/>). 1326 </t> 1327 <t> 1328 The registry itself is maintained at <eref target="http://www.iana.org/assignments/http-cache-directives"/>. 1449 1329 </t> 1450 1330 </section> … … 1458 1338 <x:anchor-alias value="Expires-v"/> 1459 1339 <t> 1460 The "Expires" entity-header field gives the date/time after which the1461 response is considered stale. See <xref target="expiration.model" /> for1462 further discussion of thefreshness model.1463 </t> 1464 <t> 1465 The presence of an Expires field does not imply that the original resource1466 will change orcease to exist at, before, or after that time.1467 </t> 1468 <t> 1469 The field-value is an absolute date and time as defined by HTTP-date in1470 &full-date;;it &MUST; be sent in rfc1123-date format.1340 The "Expires" entity-header field gives the date/time after which the response is 1341 considered stale. See <xref target="expiration.model" /> for further discussion of the 1342 freshness model. 1343 </t> 1344 <t> 1345 The presence of an Expires field does not imply that the original resource will change or 1346 cease to exist at, before, or after that time. 1347 </t> 1348 <t> 1349 The field-value is an absolute date and time as defined by HTTP-date in &full-date;; 1350 it &MUST; be sent in rfc1123-date format. 1471 1351 </t> 1472 1352 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Expires"/><iref primary="true" item="Grammar" subitem="Expires-v"/> … … 1480 1360 </artwork></figure> 1481 1361 <x:note> 1482 <t> 1483 <x:h>Note:</x:h> If a response includes a Cache-Control field with the 1484 max-age directive (see <xref target="cache-response-directive" />), 1485 that directive overrides the Expires field. Likewise, the s-maxage 1486 directive overrides Expires in shared caches. 1487 </t> 1362 <t> 1363 <x:h>Note:</x:h> If a response includes a Cache-Control field with the max-age 1364 directive (see <xref target="cache-response-directive" />), that directive overrides 1365 the Expires field. Likewise, the s-maxage directive overrides Expires in shared caches. 1366 </t> 1488 1367 </x:note> 1489 1368 <t> 1490 HTTP/1.1 servers &SHOULD-NOT; send Expires dates more than one year in the 1491 future. 1492 </t> 1493 <t> 1494 HTTP/1.1 clients and caches &MUST; treat other invalid date formats, 1495 especially including the value "0", as in the past (i.e., "already 1496 expired"). 1369 HTTP/1.1 servers &SHOULD-NOT; send Expires dates more than one year in the future. 1370 </t> 1371 <t> 1372 HTTP/1.1 clients and caches &MUST; treat other invalid date formats, especially 1373 including the value "0", as in the past (i.e., "already expired"). 1497 1374 </t> 1498 1375 </section> … … 1506 1383 <x:anchor-alias value="pragma-directive"/> 1507 1384 <t> 1508 The "Pragma" general-header field is used to include 1509 implementation-specific directives that might apply to any recipient along 1510 the request/response chain. All pragma directives specify optional behavior 1511 from the viewpoint of the protocol; however, some systems &MAY; require 1512 that behavior be consistent with the directives. 1385 The "Pragma" general-header field is used to include implementation-specific directives 1386 that might apply to any recipient along the request/response chain. All pragma directives 1387 specify optional behavior from the viewpoint of the protocol; however, some systems 1388 &MAY; require that behavior be consistent with the directives. 1513 1389 </t> 1514 1390 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Pragma"/><iref primary="true" item="Grammar" subitem="Pragma-v"/><iref primary="true" item="Grammar" subitem="pragma-directive"/><iref primary="true" item="Grammar" subitem="extension-pragma"/> … … 1519 1395 </artwork></figure> 1520 1396 <t> 1521 When the no-cache directive is present in a request message, an application 1522 &SHOULD; forward the request toward the origin server even if it has a 1523 cached copy of what is being requested. This pragma directive has the same 1524 semantics as the no-cache response directive (see <xref 1525 target="cache-response-directive" />) and is defined here for backward 1526 compatibility with HTTP/1.0. Clients &SHOULD; include both header fields 1527 when a no-cache request is sent to a server not known to be HTTP/1.1 1528 compliant. HTTP/1.1 caches &SHOULD; treat "Pragma: no-cache" as if the 1529 client had sent "Cache-Control: no-cache". 1397 When the no-cache directive is present in a request message, an application &SHOULD; 1398 forward the request toward the origin server even if it has a cached copy of what is being 1399 requested. This pragma directive has the same semantics as the no-cache response directive 1400 (see <xref target="cache-response-directive" />) and is defined here for backward 1401 compatibility with HTTP/1.0. Clients &SHOULD; include both header fields when a 1402 no-cache request is sent to a server not known to be HTTP/1.1 compliant. HTTP/1.1 caches 1403 &SHOULD; treat "Pragma: no-cache" as if the client had sent "Cache-Control: no-cache". 1530 1404 </t> 1531 1405 <x:note> 1532 1533 <x:h>Note:</x:h> Because the meaning of "Pragma: no-cache" as a1534 response-header field is not actually specified, it does not provide a1535 reliable replacement for"Cache-Control: no-cache" in a response.1536 1406 <t> 1407 <x:h>Note:</x:h> Because the meaning of "Pragma: no-cache" as a response-header field 1408 is not actually specified, it does not provide a reliable replacement for 1409 "Cache-Control: no-cache" in a response. 1410 </t> 1537 1411 </x:note> 1538 1412 <t> 1539 This mechanism is deprecated; no new Pragma directives will be defined in 1540 HTTP. 1413 This mechanism is deprecated; no new Pragma directives will be defined in HTTP. 1541 1414 </t> 1542 1415 </section> … … 1548 1421 <x:anchor-alias value="Vary-v"/> 1549 1422 <t> 1550 1551 1552 </t> 1553 <t> 1554 Caches use this information, in part, to determine whether a stored1555 response can be used to satisfy a given request; see <xref1556 target="caching.negotiated.responses" />. determines, while the response is1557 fresh, whether a cache is permitted to use the response to reply to a1558 subsequent request without validation; see <xref1559 1560 </t> 1561 <t> 1562 In uncacheable or stale responses, the Vary field value advises the user1563 agent aboutthe criteria that were used to select the representation.1423 The "Vary" response-header field conveys the set of request-header fields 1424 that were used to select the representation. 1425 </t> 1426 <t> 1427 Caches use this information, in part, to determine whether a stored response 1428 can be used to satisfy a given request; see 1429 <xref target="caching.negotiated.responses" />. 1430 determines, while the response is fresh, whether a cache is permitted to use the 1431 response to reply to a subsequent request without validation; see <xref 1432 target="caching.negotiated.responses" />. 1433 </t> 1434 <t> 1435 In uncacheable or stale responses, the Vary field value advises the user agent about 1436 the criteria that were used to select the representation. 1564 1437 </t> 1565 1438 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Vary"/><iref primary="true" item="Grammar" subitem="Vary-v"/> … … 1568 1441 </artwork></figure> 1569 1442 <t> 1570 The set of header fields named by the Vary field value is known as the 1571 selecting request-headers. 1572 </t> 1573 <t> 1574 Servers &SHOULD; include a Vary header field with any cacheable response 1575 that is subject to server-driven negotiation. Doing so allows a cache to 1576 properly interpret future requests on that resource and informs the user 1577 agent about the presence of negotiation on that resource. A server &MAY; 1578 include a Vary header field with a non-cacheable response that is subject 1579 to server-driven negotiation, since this might provide the user agent with 1580 useful information about the dimensions over which the response varies at 1581 the time of the response. 1582 </t> 1583 <t> 1584 A Vary field value of "*" signals that unspecified parameters not limited 1585 to the request-headers (e.g., the network address of the client), play a 1586 role in the selection of the response representation; therefore, a cache 1587 cannot determine whether this response is appropriate. The "*" value 1588 &MUST-NOT; be generated by a proxy server; it may only be generated by an 1589 origin server. 1590 </t> 1591 <t> 1592 The field-names given are not limited to the set of standard request-header 1593 fields defined by this specification. Field names are case-insensitive. 1443 The set of header fields named by the Vary field value is known as the selecting 1444 request-headers. 1445 </t> 1446 <t> 1447 Servers &SHOULD; include a Vary header field with any cacheable response that is 1448 subject to server-driven negotiation. Doing so allows a cache to properly interpret future 1449 requests on that resource and informs the user agent about the presence of negotiation on 1450 that resource. A server &MAY; include a Vary header field with a non-cacheable 1451 response that is subject to server-driven negotiation, since this might provide the user 1452 agent with useful information about the dimensions over which the response varies at the 1453 time of the response. 1454 </t> 1455 <t> 1456 A Vary field value of "*" signals that unspecified parameters not limited to the 1457 request-headers (e.g., the network address of the client), play a role in the selection of 1458 the response representation; therefore, a cache cannot determine whether this response is 1459 appropriate. The "*" value &MUST-NOT; be generated by a proxy server; 1460 it may only be generated by an origin server. 1461 </t> 1462 <t> 1463 The field-names given are not limited to the set of standard request-header fields 1464 defined by this specification. Field names are case-insensitive. 1594 1465 </t> 1595 1466 </section> … … 1606 1477 <x:anchor-alias value="warn-text"/> 1607 1478 <t> 1608 The "Warning" general-header field is used to carry additional information 1609 about the status or transformation of a message that might not be reflected 1610 in the message. This information is typically used to warn about possible 1611 incorrectness introduced by caching operations or transformations applied 1612 to the entity body of the message. 1613 </t> 1614 <t> 1615 Warnings can be used for other purposes, both cache-related and otherwise. 1616 The use of a warning, rather than an error status code, distinguishes these 1617 responses from true failures. 1618 </t> 1619 <t> 1620 Warning headers can in general be applied to any message, however some 1621 warn-codes are specific to caches and can only be applied to response 1622 messages. 1479 The "Warning" general-header field is used to carry additional information about the status 1480 or transformation of a message that might not be reflected in the message. This 1481 information is typically used to warn about possible incorrectness introduced by caching 1482 operations or transformations applied to the entity body of the message. 1483 </t> 1484 <t> 1485 Warnings can be used for other purposes, both cache-related and otherwise. The use of a 1486 warning, rather than an error status code, distinguishes these responses from true failures. 1487 </t> 1488 <t> 1489 Warning headers can in general be applied to any message, however some warn-codes are 1490 specific to caches and can only be applied to response messages. 1623 1491 </t> 1624 1492 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Warning"/><iref primary="true" item="Grammar" subitem="Warning-v"/><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"/> … … 1637 1505 </artwork></figure> 1638 1506 <t> 1639 Multiple warnings can be attached to a response (either by the origin 1640 server or by a cache), including multiple warnings with the same code 1641 number, only differing in warn-text. 1642 </t> 1643 <t> 1644 When this occurs, the user agent &SHOULD; inform the user of as many of 1645 them as possible, in the order that they appear in the response. 1646 </t> 1647 <t> 1648 Systems that generate multiple Warning headers &SHOULD; order them with 1649 this user agent behavior in mind. New Warning headers &SHOULD; be added 1650 after any existing Warning headers. 1651 </t> 1652 <t> 1653 Warnings are assigned three digit warn-codes. The first digit indicates 1654 whether the Warning is required to be deleted from a stored response after 1655 validation: 1656 <list style="symbols"> 1657 <t>1xx Warnings describe the freshness or validation status of the 1658 response, and so &MUST; be deleted by caches after validation. They can 1659 only be generated by a cache when validating a cached entry, and 1660 &MUST-NOT; be generated in any other situation.</t> <t>2xx Warnings 1661 describe some aspect of the entity body or entity headers that is not 1662 rectified by a validation (for example, a lossy compression of the 1663 entity bodies) and &MUST-NOT; be deleted by caches after validation, 1664 unless a full response is returned, in which case they &MUST; be.</t> 1665 </list> 1666 </t> 1667 <t> 1668 If an implementation sends a message with one or more Warning headers to a 1669 receiver whose version is HTTP/1.0 or lower, then the sender &MUST; include 1670 in each warning-value a warn-date that matches the Date header in the 1671 message. 1672 </t> 1673 <t> 1674 If an implementation receives a message with a warning-value that includes 1675 a warn-date, and that warn-date is different from the Date value in the 1676 response, then that warning-value &MUST; be deleted from the message before 1677 storing, forwarding, or using it. (preventing the consequences of naive 1678 caching of Warning header fields.) If all of the warning-values are deleted 1679 for this reason, the Warning header &MUST; be deleted as well. 1680 </t> 1681 <t> 1682 The following warn-codes are defined by this specification, each with a 1683 recommended warn-text in English, and a description of its meaning. 1507 Multiple warnings can be attached to a response (either by the origin server or by 1508 a cache), including multiple warnings with the same code number, only differing 1509 in warn-text. 1510 </t> 1511 <t> 1512 When this occurs, the user agent &SHOULD; inform the user of as many of them as 1513 possible, in the order that they appear in the response. 1514 </t> 1515 <t> 1516 Systems that generate multiple Warning headers &SHOULD; order them with this user 1517 agent behavior in mind. New Warning headers &SHOULD; be added after any existing 1518 Warning headers. 1519 </t> 1520 <t> 1521 Warnings are assigned three digit warn-codes. The first digit indicates whether the 1522 Warning is required to be deleted from a stored response after validation: 1523 <list style="symbols"> 1524 <t>1xx Warnings describe the freshness or validation status of the response, and so 1525 &MUST; be deleted by caches after validation. They can only be generated by a cache 1526 when validating a cached entry, and &MUST-NOT; be generated in any other situation.</t> 1527 <t>2xx Warnings describe some aspect of the entity body or entity headers that is 1528 not rectified by a validation (for example, a lossy compression of the entity bodies) 1529 and &MUST-NOT; be deleted by caches after validation, unless a full response is 1530 returned, in which case they &MUST; be.</t> 1531 </list> 1532 </t> 1533 <t> 1534 If an implementation sends a message with one or more Warning headers to a receiver whose 1535 version is HTTP/1.0 or lower, then the sender &MUST; include in each warning-value a 1536 warn-date that matches the Date header in the message. 1537 </t> 1538 <t> 1539 If an implementation receives a message with a warning-value that includes a warn-date, 1540 and that warn-date is different from the Date value in the response, then that 1541 warning-value &MUST; be deleted from the message before storing, forwarding, or using 1542 it. (preventing the consequences of naive caching of Warning header fields.) If all of the 1543 warning-values are deleted for this reason, the Warning header &MUST; be deleted as 1544 well. 1545 </t> 1546 <t> 1547 The following warn-codes are defined by this specification, each with a recommended 1548 warn-text in English, and a description of its meaning. 1684 1549 </t> 1685 1550 <t><?rfc needLines="4"?> 1686 1687 1688 1689 1551 110 Response is stale 1552 <list> 1553 <t>&SHOULD; be included whenever the returned response is stale.</t> 1554 </list> 1690 1555 </t> 1691 1556 <t><?rfc needLines="4"?> 1692 111 Revalidation failed 1693 <list> 1694 <t>&SHOULD; be included if a cache returns a stale response because an 1695 attempt to validate the response failed, due to an inability to reach 1696 the server.</t> 1557 111 Revalidation failed 1558 <list> 1559 <t>&SHOULD; be included if a cache returns a stale response because an attempt to 1560 validate the response failed, due to an inability to reach the server.</t> 1697 1561 </list> 1698 1562 </t> 1699 1563 <t><?rfc needLines="4"?> 1700 1701 1702 <t>&SHOULD; be included if the cache is intentionally disconnected from1703 the rest of thenetwork for a period of time.</t>1704 1564 112 Disconnected operation 1565 <list> 1566 <t>&SHOULD; be included if the cache is intentionally disconnected from the rest of 1567 the network for a period of time.</t> 1568 </list> 1705 1569 </t> 1706 1570 <t><?rfc needLines="4"?> 1707 113 Heuristic expiration 1708 <list> 1709 <t>&SHOULD; be included if the cache heuristically chose a freshness 1710 lifetime greater than 24 hours and the response's age is greater than 24 1711 hours.</t> 1712 </list> 1571 113 Heuristic expiration 1572 <list> 1573 <t>&SHOULD; be included if the cache heuristically chose a freshness lifetime 1574 greater than 24 hours and the response's age is greater than 24 hours.</t> 1575 </list> 1713 1576 </t> 1714 1577 <t><?rfc needLines="4"?> 1715 1716 1717 <t>The warning text can include arbitrary information to be presented to1718 a human user, or logged. A system receiving this warning &MUST-NOT; take1719 a ny automated action, besides presenting the warning to the user.</t>1720 1578 199 Miscellaneous warning 1579 <list> 1580 <t>The warning text can include arbitrary information to be presented to a human 1581 user, or logged. A system receiving this warning &MUST-NOT; take any automated 1582 action, besides presenting the warning to the user.</t> 1583 </list> 1721 1584 </t> 1722 1585 <t><?rfc needLines="4"?> 1723 1724 1725 1726 transformation changing the content-coding (as specified in the 1727 Content-Encoding header) or media-type (as specified in the Content-Type1728 header) of the response, or the entity-body of the response, unless this1729 Warning code already appears in theresponse.</t>1730 1586 214 Transformation applied 1587 <list> 1588 <t>&MUST; be added by an intermediate cache or proxy if it applies any 1589 transformation changing the content-coding (as specified in the Content-Encoding 1590 header) or media-type (as specified in the Content-Type header) of the response, or 1591 the entity-body of the response, unless this Warning code already appears in the 1592 response.</t> 1593 </list> 1731 1594 </t> 1732 1595 <t><?rfc needLines="4"?> 1733 1734 1735 <t>The warning text can include arbitrary information to be presented1736 to a human user, or logged. A system receiving this warning &MUST-NOT;1737 take any automatedaction.</t>1738 1596 299 Miscellaneous persistent warning 1597 <list> 1598 <t>The warning text can include arbitrary information to be presented to a human 1599 user, or logged. A system receiving this warning &MUST-NOT; take any automated 1600 action.</t> 1601 </list> 1739 1602 </t> 1740 1603 </section> … … 1744 1607 <section anchor="history.lists" title="History Lists"> 1745 1608 <t> 1746 User agents often have history mechanisms, such as "Back" buttons and 1747 history lists, that can be used to redisplay an entity retrieved earlier in 1748 a session. 1749 </t> 1750 <t> 1751 The freshness model (<xref target="expiration.model"/>) does not 1752 necessarily apply to history mechanisms. I.e., a history mechanism can 1753 display a previous representation even if it has expired. 1754 </t> 1755 <t> 1756 This does not prohibit the history mechanism from telling the user that a 1757 view might be stale, or from honoring cache directives (e.g., 1758 Cache-Control: no-store). 1759 </t> 1609 User agents often have history mechanisms, such as "Back" buttons and history lists, that 1610 can be used to redisplay an entity retrieved earlier in a session. 1611 </t> 1612 <t> 1613 The freshness model (<xref target="expiration.model"/>) does not necessarily apply to history mechanisms. I.e., 1614 a history mechanism can display a previous representation even if it has expired. 1615 </t> 1616 <t> 1617 This does not prohibit the history mechanism from telling the user that a 1618 view might be stale, or from honoring cache directives (e.g., Cache-Control: no-store). 1619 </t> 1760 1620 </section> 1761 1621 … … 1763 1623 <section anchor="IANA.considerations" title="IANA Considerations"> 1764 1624 1765 <section title="Cache Directive Registry" 1766 anchor="cache.directive.registration"> 1767 <t> 1768 The registration procedure for HTTP Cache Directives is defined by <xref 1769 target="cache.control.extensions"/> of this document. 1770 </t> 1771 <t> 1772 The HTTP Cache Directive Registry should be created at <eref 1773 target="http://www.iana.org/assignments/http-cache-directives"/> and be 1774 populated with the registrations below: 1625 <section title="Cache Directive Registry" anchor="cache.directive.registration"> 1626 <t> 1627 The registration procedure for HTTP Cache Directives is defined by 1628 <xref target="cache.control.extensions"/> of this document. 1629 </t> 1630 <t> 1631 The HTTP Cache Directive Registry should be created at <eref target="http://www.iana.org/assignments/http-cache-directives"/> 1632 and be populated with the registrations below: 1775 1633 </t> 1776 1634 <?BEGININC p6-cache.cache-directives ?> … … 1896 1754 <?ENDINC p6-cache.iana-headers ?> 1897 1755 <t> 1898 The change controller is: "IETF (iesg@ietf.org) - Internet Engineering Task 1899 Force". 1756 The change controller is: "IETF (iesg@ietf.org) - Internet Engineering Task Force". 1900 1757 </t> 1901 1758 </section> … … 1905 1762 <section anchor="security.considerations" title="Security Considerations"> 1906 1763 <t> 1907 Caches expose additional potential vulnerabilities, since the contents of1908 the cache represent an attractive target for malicious exploitation.1909 Because cache contents persist after an HTTP request is complete, an attack1910 on the cache can reveal information long after a user believes that the1911 information has been removed from the network. Therefore, cache contents1912 should be protected as sensitive information.</t>1764 Caches expose additional potential vulnerabilities, since the contents of the cache 1765 represent an attractive target for malicious exploitation. Because cache contents persist 1766 after an HTTP request is complete, an attack on the cache can reveal information long after 1767 a user believes that the information has been removed from the network. Therefore, cache 1768 contents should be protected as sensitive information. 1769 </t> 1913 1770 </section> 1914 1771 1915 1772 <section anchor="ack" title="Acknowledgments"> 1916 1773 <t> 1917 Much of the content and presentation of the caching design is due to1918 suggestions and comments from individuals including: Shel Kaphan, Paul1919 Leach, Koen Holtman, David Morris,and Larry Masinter.1774 Much of the content and presentation of the caching design is due to suggestions and 1775 comments from individuals including: Shel Kaphan, Paul Leach, Koen Holtman, David Morris, 1776 and Larry Masinter. 1920 1777 </t> 1921 1778 </section>
Note: See TracChangeset
for help on using the changeset viewer.