idnits 2.17.1 draft-ietf-httpbis-targeted-cache-control-04.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 (23 January 2022) is 824 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 204, but not defined == Missing Reference: 'CDN-Cache-Control' is mentioned on line 316, 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: 27 July 2022 Fastly 6 Y. Wu 7 Cloudflare 8 23 January 2022 10 Targeted HTTP Cache Control 11 draft-ietf-httpbis-targeted-cache-control-04 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 About This Document 22 This note is to be removed before publishing as an RFC. 24 Status information for this document may be found at 25 https://datatracker.ietf.org/doc/draft-ietf-httpbis-targeted-cache- 26 control/. 28 Discussion of this document takes place on the HTTP Working Group 29 mailing list (mailto:ietf-http-wg@w3.org), which is archived at 30 https://lists.w3.org/Archives/Public/ietf-http-wg/. Working Group 31 information can be found at https://httpwg.org/. 33 Source for this draft and an issue tracker can be found at 34 https://github.com/httpwg/http-extensions/labels/targeted-cc. 36 Status of This Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at https://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on 27 July 2022. 53 Copyright Notice 55 Copyright (c) 2022 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 60 license-info) in effect on the date of publication of this document. 61 Please review these documents carefully, as they describe your rights 62 and restrictions with respect to this document. Code Components 63 extracted from this document must include Revised BSD License text as 64 described in Section 4.e of the Trust Legal Provisions and are 65 provided without warranty as described in the Revised BSD License. 67 Table of Contents 69 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 70 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 71 2. Targeted Cache-Control Header Fields . . . . . . . . . . . . 3 72 2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 4 73 2.2. Cache Behavior . . . . . . . . . . . . . . . . . . . . . 5 74 2.3. Interaction with HTTP Freshness . . . . . . . . . . . . . 6 75 2.4. Defining Targeted Fields . . . . . . . . . . . . . . . . 7 76 3. The CDN-Cache-Control Targeted Field . . . . . . . . . . . . 7 77 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 7 78 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 79 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 80 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 81 6.1. Normative References . . . . . . . . . . . . . . . . . . 8 82 6.2. Informative References . . . . . . . . . . . . . . . . . 9 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 85 1. Introduction 87 Modern deployments of HTTP often use multiple layers of caching. For 88 example, a website might use a cache on the origin server itself; it 89 might deploy a caching layer in the same network as the origin 90 server, it might use one or more Content Delivery Networks (CDNs) 91 that are distributed throughout the Internet, and it might benefit 92 from browser caching as well. 94 Because it is often desirable to control these different classes of 95 caches separately, some means of targeting cache directives at them 96 is necessary. For example, if a publisher has a mechanism to 97 invalidate the contents of a cache that it has a relationship with 98 (such as a CDN cache), they might be more comfortable assigning a 99 more generous caching policy to it, while still wanting to restrict 100 the behavior of other caches. 102 The HTTP Cache-Control response header field (defined in Section 5.2 103 of [HTTP-CACHING]) is widely used to direct caching behavior. 104 However, it is relatively undifferentiated; while some cache 105 directives (e.g., s-maxage) are targeted at a specific class of 106 caches (for s-maxage, shared caches), targeting is not consistently 107 available across all existing cache directives (e.g., stale-while- 108 revalidate). This is problematic, especially as the number of 109 caching extensions grows, along with the number of potential targets. 111 Some implementations have defined ad hoc control mechanisms to 112 overcome this issue, but their interoperability is low. Section 2 113 defines a standard framework for targeted cache control using HTTP 114 response headers, and Section 3 defines one such header: the CDN- 115 Cache-Control response header field. 117 1.1. Notational Conventions 119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 121 "OPTIONAL" in this document are to be interpreted as described in BCP 122 14 [RFC2119] [RFC8174] when, and only when, they appear in all 123 capitals, as shown here. 125 2. Targeted Cache-Control Header Fields 127 A Targeted Cache-Control Header Field (hereafter, "targeted field") 128 is an HTTP response header field that has the same semantics as the 129 Cache-Control response header field ([HTTP-CACHING], Section 5.2). 130 However, it has a distinct field name that indicates the target for 131 its cache directives. 133 For example: 135 CDN-Cache-Control: max-age=60 137 is a targeted field that applies to Content Delivery Networks (CDNs), 138 as defined in Section 3. 140 2.1. Syntax 142 Targeted fields are Dictionary Structured Fields (Section 3.2 of 143 [STRUCTURED-FIELDS]). Each member of the dictionary is an HTTP cache 144 response directive (Section 5.2.2 of [HTTP-CACHING]) including 145 extension response directives (as per Section 5.2.3 of 146 [HTTP-CACHING]). Note that while targeted fields often have the same 147 syntax as Cache-Control fields, differences in error handling mean 148 that using a Cache-Control parser rather than a Structured Fields 149 parser can introduce interoperability issues. 151 Because cache directives are not defined in terms of structured data 152 types, it is necessary to map their values into the appropriate 153 types. Section 5.2 of [HTTP-CACHING] defines cache directive values 154 to be either absent, a quoted-string, or a token. 156 This means that cache directives that have no value will be mapped to 157 a Boolean (Section 3.3.6 of [STRUCTURED-FIELDS]). When the value is 158 a quoted-string, it will be mapped to a String (Section 3.3.3 of 159 [STRUCTURED-FIELDS]), and when it is a token, it will map to a Token 160 (Section 3.3.4 of [STRUCTURED-FIELDS]), an Integer (Section 3.3.1 of 161 [STRUCTURED-FIELDS]) or a Decimal (Section 3.3.2 of 162 [STRUCTURED-FIELDS]), depending on the content of the value. 164 For example, the max-age directive (Section 5.2.2.1 of 165 [HTTP-CACHING]) has an integer value; no-store (Section 5.2.2.5 of 166 [HTTP-CACHING]) always has a boolean true value, and no-cache 167 (Section 5.2.2.4 of [HTTP-CACHING]) has a value that can either be 168 boolean true or a string containing a comma-delimited list of field 169 names. 171 Implementations MUST NOT generate values that violate these inferred 172 constraints on the cache directive's value. In particular, string 173 values whose first character is not alphabetic or "*" MUST be 174 generated as structured Strings, so they are not mistaken for other 175 types. 177 Implementations SHOULD NOT consume values that violate these inferred 178 constraints. For example, a consuming implementation that coerces a 179 max-age with a decimal value into an integer would behave differently 180 than other implementations, potentially causing interoperability 181 issues. 183 Parameters received on cache directives are to be ignored, unless 184 other handling is explicitly specified. 186 If a targeted field in a given response is empty, or a parsing error 187 is encountered, that field MUST be ignored by the cache (i.e., it 188 behaves as if the field were not present, likely falling back to 189 other cache-control mechanisms present). 191 2.2. Cache Behavior 193 A cache that implements this specification maintains a _target list_ 194 - an ordered list of the targeted field names that it uses for 195 caching policy, with the order reflecting priority from most 196 applicable to least. The target list might be fixed, user- 197 configurable, or generated per request, depending upon the 198 implementation. 200 For example, a CDN cache might support both CDN-Cache-Control and a 201 header specific to that CDN, ExampleCDN-Cache-Control, with the 202 latter overriding the former. Its target list would be: 204 [ExampleCDN-Cache-Control, CDN-Cache-Control] 206 When a cache that implements this specification receives a response 207 with one or more of the header field names on its target list, the 208 cache MUST select the first (in target list order) field with a 209 valid, non-empty value and use its value to determine the caching 210 policy for the response, and MUST ignore the Cache-Control and 211 Expires header fields in that response, unless no valid, non-empty 212 value is available from the listed header fields. 214 Note that this occurs on a response-by-response basis; if no member 215 of the cache's target list is present, valid and non-empty, a cache 216 falls back to other cache control mechanisms as required by HTTP 217 [HTTP-CACHING]. 219 Targeted fields that are not on a cache's target list MUST NOT change 220 that cache's behaviour, and MUST be passed through. 222 Caches that use a targeted field MUST implement the semantics of the 223 following cache directives: 225 * max-age 227 * must-revalidate 229 * no-store 231 * no-cache 233 * private 234 Furthermore, they SHOULD implement other cache directives (including 235 extension cache directives) that they support in the Cache-Control 236 response header field. 238 The semantics and precedence of cache directives in a targeted field 239 are the same as those in Cache-Control. In particular, no-store and 240 no-cache make max-age inoperative, and unrecognised extension 241 directives are ignored. 243 2.3. Interaction with HTTP Freshness 245 HTTP caching has a single, end-to-end freshness model defined in 246 Section 4.2 of [HTTP-CACHING]. When additional freshness mechanisms 247 are only available to some caches along a request path (for example, 248 using targeted fields), their interactions need to be carefully 249 considered. In particular, a targeted cache might have longer 250 freshness lifetimes available to it than other caches, causing it to 251 serve responses that appear to be prematurely (or even immediately) 252 stale to those other caches, negatively impacting cache efficiency. 254 For example, a response stored by a CDN cache might be served with 255 the following headers: 257 Age: 1800 258 Cache-Control: max-age=600 259 CDN-Cache-Control: max-age=3600 261 From the CDN's perspective, this response is still fresh after being 262 cached for 30 minutes, while from other caches' standpoint, this 263 response is already stale. See [AGE-PENALTY] for more discussion. 265 When the targeted cache has a strong coherence mechanism (e.g., the 266 origin server has the ability to proactively invalidate cached 267 responses), it is often desirable to mitigate these effects. Some 268 techniques seen in deployments include: 270 * Removing the Age header field 272 * Updating the Date header field value to the current time 274 * Updating the Expires header field value to the current time, plus 275 any Cache-Control: max-age value 277 This specification does not place any specific requirements on 278 implementations to mitigate these effects, but definitions of 279 targeted fields can do so. 281 2.4. Defining Targeted Fields 283 A targeted field for a particular class of cache can be defined by 284 requesting registration in the Hypertext Transfer Protocol (HTTP) 285 Field Name Registry (https://www.iana.org/assignments/http-fields/). 287 Registration requests can use this document as the specification 288 document, in which case the Comments field should clearly define the 289 class of caches that the targeted field applies to. Alternatively, 290 if other documentation for the field has been created, it can be used 291 as the specification document. 293 By convention, targeted fields have the suffix "-Cache-Control": 294 e.g., "ExampleCDN-Cache-Control". However, this suffix MUST NOT be 295 used on its own to identify targeted fields; it is only a convention. 297 3. The CDN-Cache-Control Targeted Field 299 The CDN-Cache-Control response header field is a targeted field 300 (Section 2) that allows origin servers to control the behaviour of 301 CDN caches interposed between them and clients, separately from other 302 caches that might handle the response. 304 It applies to caches that are part of a distributed network that 305 operate on behalf of an origin server (commonly called a Content 306 Delivery Network or CDN). 308 CDN caches that use CDN-Cache-Control will typically forward this 309 header so that downstream CDN caches can use it as well. However, 310 they MAY remove it when this is undesirable (for example, when 311 configured to do so because it is known not to be used downstream). 313 3.1. Examples 315 For example, the following header fields would instruct a CDN cache 316 (i.e., a cache with a target list of [CDN-Cache-Control]) to consider 317 the response fresh for 600 seconds, other shared caches to consider 318 the response fresh for 120 seconds, and any remaining caches to 319 consider the response fresh for 60 seconds: 321 Cache-Control: max-age=60, s-maxage=120 322 CDN-Cache-Control: max-age=600 324 These header fields would instruct a CDN cache to consider the 325 response fresh for 600 seconds, while all other caches would be 326 prevented from storing it: 328 CDN-Cache-Control: max-age=600 329 Cache-Control: no-store 331 Because CDN-Cache-Control is not present, this header field would 332 prevent all caches from storing the response: 334 Cache-Control: no-store 336 Whereas these would prevent all caches except for CDN caches from 337 storing the response: 339 Cache-Control: no-store 340 CDN-Cache-Control: none 342 (note that 'none' is not a registered cache directive; it is here to 343 avoid sending a header field with an empty value, which would be 344 ignored) 346 4. IANA Considerations 348 Please register the following entry in the Hypertext Transfer 349 Protocol (HTTP) Field Name Registry defined by [HTTP]: 351 * Field Name: CDN-Cache-Control 353 * Status: permanent 355 * Specification Document: [this document] 357 * Comments: Cache directives targeted at Content Delivery Networks 359 5. Security Considerations 361 The security considerations of HTTP caching [HTTP-CACHING] apply. 363 The ability to carry multiple caching policies on a response can 364 result in confusion about how a response will be cached in different 365 systems, potentially resulting in unintentional reuse of responses 366 with sensitive information. For this reason, care must be exercised. 368 6. References 370 6.1. Normative References 372 [HTTP] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 373 Semantics", Work in Progress, Internet-Draft, draft-ietf- 374 httpbis-semantics-19, 12 September 2021, 375 . 378 [HTTP-CACHING] 379 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 380 Caching", Work in Progress, Internet-Draft, draft-ietf- 381 httpbis-cache-19, 12 September 2021, 382 . 385 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 386 Requirement Levels", BCP 14, RFC 2119, 387 DOI 10.17487/RFC2119, March 1997, 388 . 390 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 391 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 392 May 2017, . 394 [STRUCTURED-FIELDS] 395 Nottingham, M. and P-H. Kamp, "Structured Field Values for 396 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 397 . 399 6.2. Informative References 401 [AGE-PENALTY] 402 Cohen, E. and H. Kaplan, "The age penalty and its effect 403 on cache performance", March 2001, 404 . 406 Authors' Addresses 408 Stephen Ludin 409 Akamai 411 Email: sludin@ludin.org 413 Mark Nottingham 414 Fastly 415 Prahran 416 Australia 418 Email: mnot@mnot.net 419 URI: https://www.mnot.net/ 421 Yuchen Wu 422 Cloudflare 424 Email: me@yuchenwu.net