idnits 2.17.1 draft-ietf-httpbis-targeted-cache-control-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (14 October 2021) is 919 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'ExampleCDN-Cache-Control' is mentioned on line 196, but not defined == Missing Reference: 'CDN-Cache-Control' is mentioned on line 196, but not defined -- Possible downref: Normative reference to a draft: ref. 'HTTP' -- Possible downref: Normative reference to a draft: ref. 'HTTP-CACHING' Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP S. Ludin 3 Internet-Draft Akamai 4 Intended status: Standards Track M. Nottingham 5 Expires: 17 April 2022 Fastly 6 Y. Wu 7 Cloudflare 8 14 October 2021 10 Targeted HTTP Cache Control 11 draft-ietf-httpbis-targeted-cache-control-02 13 Abstract 15 This specification defines a convention for HTTP response header 16 fields that allow cache directives to be targeted at specific caches 17 or classes of caches. It also defines one such header field, 18 targeted at Content Delivery Network (CDN) caches. 20 Note to Readers 22 _RFC EDITOR: please remove this section before publication_ 24 The issues list for this draft can be found at 25 https://github.com/httpwg/http-extensions/labels/targeted-cc 26 (https://github.com/httpwg/http-extensions/labels/targeted-cc). 28 The most recent (often, unpublished) draft is at https://httpwg.org/ 29 http-extensions/draft-ietf-httpbis-targeted-cache-control.html 30 (https://httpwg.org/http-extensions/draft-ietf-httpbis-targeted- 31 cache-control.html). 33 See also the draft's current status in the IETF datatracker, at 34 https://datatracker.ietf.org/doc/draft-ietf-httpbis-targeted-cache- 35 control/ (https://datatracker.ietf.org/doc/draft-ietf-httpbis- 36 targeted-cache-control/). 38 Status of This Memo 40 This Internet-Draft is submitted in full conformance with the 41 provisions of BCP 78 and BCP 79. 43 Internet-Drafts are working documents of the Internet Engineering 44 Task Force (IETF). Note that other groups may also distribute 45 working documents as Internet-Drafts. The list of current Internet- 46 Drafts is at https://datatracker.ietf.org/drafts/current/. 48 Internet-Drafts are draft documents valid for a maximum of six months 49 and may be updated, replaced, or obsoleted by other documents at any 50 time. It is inappropriate to use Internet-Drafts as reference 51 material or to cite them other than as "work in progress." 53 This Internet-Draft will expire on 17 April 2022. 55 Copyright Notice 57 Copyright (c) 2021 IETF Trust and the persons identified as the 58 document authors. All rights reserved. 60 This document is subject to BCP 78 and the IETF Trust's Legal 61 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 62 license-info) in effect on the date of publication of this document. 63 Please review these documents carefully, as they describe your rights 64 and restrictions with respect to this document. Code Components 65 extracted from this document must include Simplified BSD License text 66 as described in Section 4.e of the Trust Legal Provisions and are 67 provided without warranty as described in the Simplified BSD License. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 72 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 73 2. Targeted Cache-Control Header Fields . . . . . . . . . . . . 3 74 2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 3 75 2.2. Cache Behavior . . . . . . . . . . . . . . . . . . . . . 4 76 2.3. Interaction with HTTP Freshness . . . . . . . . . . . . . 6 77 2.4. Defining Targeted Fields . . . . . . . . . . . . . . . . 6 78 3. The CDN-Cache-Control Targeted Field . . . . . . . . . . . . 7 79 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 7 80 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 81 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 82 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 83 6.1. Normative References . . . . . . . . . . . . . . . . . . 8 84 6.2. Informative References . . . . . . . . . . . . . . . . . 9 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 87 1. Introduction 89 Modern deployments of HTTP often use multiple layers of caching. For 90 example, a Web site might use a cache on the origin server itself; it 91 might deploy a caching layer in the same network as the origin 92 server, it might use one or more Content Delivery Networks (CDNs) 93 that are distributed throughout the Internet, and it might utilise 94 browser caching as well. 96 Because it is often desirable to control these different classes of 97 caches separately, some means of targeting directives at them is 98 necessary. 100 The HTTP Cache-Control response header field (defined in Section 5.2 101 of [HTTP-CACHING]) is widely used to direct caching behavior. 102 However, it is relatively undifferentiated; while some directives 103 (e.g., s-maxage) are targeted at a specific class of caches (for 104 s-maxage, shared caches), targeting is not consistently available 105 across all existing cache directives (e.g., stale-while-revalidate). 106 This is problematic, especially as the number of caching extensions 107 grows, along with the number of potential targets. 109 Some implementations have defined ad hoc control mechanisms to 110 overcome this issue, but their interoperability is low. Section 2 111 defines a standard framework for targeted cache control using HTTP 112 response headers, and Section 3 defines one such header: the CDN- 113 Cache-Control response header field. 115 1.1. Notational Conventions 117 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 119 "OPTIONAL" in this document are to be interpreted as described in BCP 120 14 [RFC2119] [RFC8174] when, and only when, they appear in all 121 capitals, as shown here. 123 2. Targeted Cache-Control Header Fields 125 A Targeted Cache-Control Header Field (hereafter, "targeted field") 126 is a HTTP response header field that has the same semantics as the 127 Cache-Control response header field ([HTTP-CACHING], Section 5.2). 128 However, it has a distinct field name that indicates the target for 129 its directives. 131 For example: 133 CDN-Cache-Control: max-age=60 135 is a targeted field that applies to Content Delivery Networks (CDNs), 136 as defined in Section 3. 138 2.1. Syntax 140 Targeted fields are Dictionary Structured Fields (Section 3.2 of 141 [STRUCTURED-FIELDS]). Each member of the dictionary is a cache 142 response directive from the Hypertext Transfer Protocol (HTTP) Cache 143 Directive Registry. 145 Because cache directives are not defined in terms of structured data 146 types, it is necessary to map their values into the appropriate 147 types. Section 5.2 of [HTTP-CACHING] defines cache directive values 148 to be either absent, a quoted-string, or a token. 150 This means that cache directives that have no value will be mapped to 151 a Boolean (Section 3.3.6 of [STRUCTURED-FIELDS]). When the value is 152 a quoted-string, it will be mapped to a String (Section 3.3.3 of 153 [STRUCTURED-FIELDS]), and when it is a token, it will map to a Token 154 (Section 3.3.4 of [STRUCTURED-FIELDS]), an Integer (Section 3.3.1 of 155 [STRUCTURED-FIELDS]) or a Decimal (Section 3.3.2 of 156 [STRUCTURED-FIELDS]), depending on the content of the value. 158 For example, the max-age directive (Section 5.2.2.1 of 159 [HTTP-CACHING]) has an integer value; no-store (Section 5.2.2.5 of 160 [HTTP-CACHING]) always has a boolean true value, and no-cache 161 (Section 5.2.2.4 of [HTTP-CACHING]) has a value that can either be 162 boolean true or a string containing a comma-delimited list of field 163 names. 165 Implementations MUST NOT generate values that violate these inferred 166 constraints on the directive's value. In particular, string values 167 whose first character is not alphabetic or "*" MUST be generated as 168 structured Strings, so they are not mistaken for other types. 170 Implementations SHOULD NOT consume values that violate these inferred 171 constraints. For example, a consuming implementation were to coerce 172 a max-age with a decimal value into an integer would behave 173 differently than other implementations, potentially causing 174 interoperability issues. 176 Parameters received on directives are to be ignored, unless other 177 handling is explicitly specified. 179 If a targeted field in a given response is empty, or a parsing error 180 is encountered, that field MUST be ignored by the cache (i.e., it 181 behaves as if the field were not present, likely falling back to 182 other cache control mechanisms present). 184 2.2. Cache Behavior 186 A cache that implement this specification maintains a _target list_ - 187 an ordered list of the targeted field names that it uses for caching 188 policy, with the order reflecting priority from most applicable to 189 least. The target list might be fixed, user-configurable, or 190 generated per request, depending upon the implementation. 192 For example, a CDN cache might support both CDN-Cache-Control and a 193 header specific to that CDN, ExampleCDN-Cache-Control, with the 194 latter overriding the former. Its target list would be: 196 [ExampleCDN-Cache-Control, CDN-Cache-Control] 198 When a cache that implements this specification receives a response 199 with one or more of of the header field names on its target list, the 200 cache MUST select the first (in target list order) field with a 201 valid, non-empty value and use its value to determine the caching 202 policy for the response, and MUST ignore the Cache-Control and 203 Expires header fields in that response, unless no valid, non-empty 204 value is available from the listed header fields. 206 Note that this occurs on a response-by-response basis; if no member 207 of the cache's target list is present, valid and non-empty, a cache 208 falls back to other cache control mechanisms as required by HTTP 209 [HTTP-CACHING]. 211 Targeted fields that are not on a cache's target list MUST NOT change 212 that cache's behaviour, and MUST be passed through. 214 Caches that use a targeted field MUST implement the semantics of the 215 following cache directives: 217 * max-age 219 * must-revalidate 221 * no-store 223 * no-cache 225 * private 227 Furthermore, they SHOULD implement other cache directives (including 228 extension cache directives) that they support in the Cache-Control 229 response header field. 231 The semantics and precedence of cache directives in a targeted field 232 are the same as those in Cache-Control. In particular, no-store and 233 no-cache make max-age inoperative, and unrecognised extension 234 directives are ignored. 236 2.3. Interaction with HTTP Freshness 238 HTTP caching has a single, end-to-end freshness model defined in 239 Section 4.2 of [HTTP-CACHING]. When additional freshness mechanisms 240 are only available to some caches along a request path (for example, 241 using targeted fields), their interactions need to be carefully 242 considered. In particular, a targeted cache might have longer 243 freshness lifetimes available to it than other caches, causing it to 244 serve responses that appear to be prematurely (or even immediately) 245 stale to them, negatively impacting cache efficiency. 247 For example, a response stored by a CDN cache might be served with 248 the following headers: 250 Age: 1800 251 Cache-Control: max-age=600 252 CDN-Cache-Control: max-age=3600 254 From the CDN's perspective, this response is still fresh after being 255 cached for 30 minutes, while from other caches' standpoint, this 256 response is already stale. See [AGE-PENALTY] for more discussion. 258 When the targeted cache has a strong coherence mechanism (e.g., the 259 origin server has the ability to proactively invalidate cached 260 responses), it is often desirable to mitigate these effects. Some 261 techniques seen in deployments include: 263 * Removing the Age header field 265 * Updating the Date header field value to the current time 267 * Updating the Expires header field value to the current time, plus 268 any Cache-Control: max-age value 270 This specification does not place any specific requirements on 271 implementations to mitigate these effects, but definitions of 272 targeted fields can do so. 274 2.4. Defining Targeted Fields 276 A targeted field for a particular class of cache can be defined by 277 requesting registration in the Hypertext Transfer Protocol (HTTP) 278 Field Name Registry https://www.iana.org/assignments/http-fields/ 279 (https://www.iana.org/assignments/http-fields/), listing this 280 specification as the specification document. The Comments field of 281 the registration should clearly define the class of caches that the 282 targeted field applies to. 284 By convention, targeted fields have the suffix "-Cache-Control": 285 e.g., "ExampleCDN-Cache-Control". However, this suffix MUST NOT be 286 used on its own to identify targeted fields; it is only a convention. 288 3. The CDN-Cache-Control Targeted Field 290 The CDN-Cache-Control response header field is a targeted field 291 (Section 2) that allows origin servers to control the behaviour of 292 CDN caches interposed between them and clients, separately from other 293 caches that might handle the response. 295 It applies to caches that are part of a distributed network that 296 operate on behalf of an origin server (commonly called a Content 297 Delivery Network or CDN). 299 CDN caches that use CDN-Cache-Control will typically forward this 300 header so that downstream CDN caches can use it as well. However, 301 they MAY remove it when this is undesirable (for example, when 302 configured to do so because it is known not to be used downstream). 304 3.1. Examples 306 For example, the following header fields would instruct a CDN cache 307 to consider the response fresh for 600 seconds, other shared caches 308 for 120 seconds and any remaining caches for 60 seconds: 310 Cache-Control: max-age=60, s-maxage=120 311 CDN-Cache-Control: max-age=600 313 These header fields would instruct a CDN cache to consider the 314 response fresh for 600 seconds, while all other caches would be 315 prevented from storing it: 317 CDN-Cache-Control: max-age=600 318 Cache-Control: no-store 320 Because CDN-Cache-Control is not present, this header field would 321 prevent all caches from storing the response: 323 Cache-Control: no-store 325 Whereas these would prevent all caches except for CDN caches from 326 storing the response: 328 Cache-Control: no-store 329 CDN-Cache-Control: none 330 (note that 'none' is not a registered cache directive; it is here to 331 avoid sending a header field with an empty value, which would be 332 ignored) 334 4. IANA Considerations 336 Please register the following entry in the Hypertext Transfer 337 Protocol (HTTP) Field Name Registry defined by [HTTP]: 339 * Field Name: CDN-Cache-Control 341 * Status: permanent 343 * Specification Document: [this document] 345 * Comments: Cache-Control directives targeted at Content Delivery 346 Networks 348 5. Security Considerations 350 The security considerations of HTTP caching [HTTP-CACHING] apply. 352 The ability to carry multiple caching policies on a response can 353 result in confusion about how a response will be cached in different 354 systems, if not used carefully. This might result in unintentional 355 reuse of responses with sensitive information. 357 6. References 359 6.1. Normative References 361 [HTTP] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 362 Semantics", Work in Progress, Internet-Draft, draft-ietf- 363 httpbis-semantics-19, 12 September 2021, 364 . 367 [HTTP-CACHING] 368 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 369 Caching", Work in Progress, Internet-Draft, draft-ietf- 370 httpbis-cache-19, 12 September 2021, 371 . 374 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 375 Requirement Levels", BCP 14, RFC 2119, 376 DOI 10.17487/RFC2119, March 1997, 377 . 379 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 380 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 381 May 2017, . 383 [STRUCTURED-FIELDS] 384 Nottingham, M. and P-H. Kamp, "Structured Field Values for 385 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 386 . 388 6.2. Informative References 390 [AGE-PENALTY] 391 Cohen, E. and H. Kaplan, "The age penalty and its effect 392 on cache performance", March 2001, 393 . 395 Authors' Addresses 397 Stephen Ludin 398 Akamai 400 Email: sludin@ludin.org 402 Mark Nottingham 403 Fastly 404 Prahran 405 Australia 407 Email: mnot@mnot.net 408 URI: https://www.mnot.net/ 410 Yuchen Wu 411 Cloudflare 413 Email: me@yuchenwu.net