idnits 2.17.1 draft-ietf-httpbis-targeted-cache-control-03.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 (4 January 2022) is 835 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 199, but not defined == Missing Reference: 'CDN-Cache-Control' is mentioned on line 199, 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: 8 July 2022 Fastly 6 Y. Wu 7 Cloudflare 8 4 January 2022 10 Targeted HTTP Cache Control 11 draft-ietf-httpbis-targeted-cache-control-03 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 8 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 Web site 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 utilise 92 browser caching as well. 94 Because it is often desirable to control these different classes of 95 caches separately, some means of targeting directives at them is 96 necessary. 98 The HTTP Cache-Control response header field (defined in Section 5.2 99 of [HTTP-CACHING]) is widely used to direct caching behavior. 100 However, it is relatively undifferentiated; while some directives 101 (e.g., s-maxage) are targeted at a specific class of caches (for 102 s-maxage, shared caches), targeting is not consistently available 103 across all existing cache directives (e.g., stale-while-revalidate). 104 This is problematic, especially as the number of caching extensions 105 grows, along with the number of potential targets. 107 Some implementations have defined ad hoc control mechanisms to 108 overcome this issue, but their interoperability is low. Section 2 109 defines a standard framework for targeted cache control using HTTP 110 response headers, and Section 3 defines one such header: the CDN- 111 Cache-Control response header field. 113 1.1. Notational Conventions 115 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 116 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 117 "OPTIONAL" in this document are to be interpreted as described in BCP 118 14 [RFC2119] [RFC8174] when, and only when, they appear in all 119 capitals, as shown here. 121 2. Targeted Cache-Control Header Fields 123 A Targeted Cache-Control Header Field (hereafter, "targeted field") 124 is a HTTP response header field that has the same semantics as the 125 Cache-Control response header field ([HTTP-CACHING], Section 5.2). 126 However, it has a distinct field name that indicates the target for 127 its directives. 129 For example: 131 CDN-Cache-Control: max-age=60 133 is a targeted field that applies to Content Delivery Networks (CDNs), 134 as defined in Section 3. 136 2.1. Syntax 138 Targeted fields are Dictionary Structured Fields (Section 3.2 of 139 [STRUCTURED-FIELDS]). Each member of the dictionary is a cache 140 response directive from the Hypertext Transfer Protocol (HTTP) Cache 141 Directive Registry (https://www.iana.org/assignments/http-cache- 142 directives/). Note that while targeted fields often have the same 143 syntax as Cache-Control fields, differences in error handling mean 144 that using a Cache-Control parser rather than a Structured Fields 145 parser can introduce interoperability issues. 147 Because cache directives are not defined in terms of structured data 148 types, it is necessary to map their values into the appropriate 149 types. Section 5.2 of [HTTP-CACHING] defines cache directive values 150 to be either absent, a quoted-string, or a token. 152 This means that cache directives that have no value will be mapped to 153 a Boolean (Section 3.3.6 of [STRUCTURED-FIELDS]). When the value is 154 a quoted-string, it will be mapped to a String (Section 3.3.3 of 155 [STRUCTURED-FIELDS]), and when it is a token, it will map to a Token 156 (Section 3.3.4 of [STRUCTURED-FIELDS]), an Integer (Section 3.3.1 of 157 [STRUCTURED-FIELDS]) or a Decimal (Section 3.3.2 of 158 [STRUCTURED-FIELDS]), depending on the content of the value. 160 For example, the max-age directive (Section 5.2.2.1 of 161 [HTTP-CACHING]) has an integer value; no-store (Section 5.2.2.5 of 162 [HTTP-CACHING]) always has a boolean true value, and no-cache 163 (Section 5.2.2.4 of [HTTP-CACHING]) has a value that can either be 164 boolean true or a string containing a comma-delimited list of field 165 names. 167 Implementations MUST NOT generate values that violate these inferred 168 constraints on the directive's value. In particular, string values 169 whose first character is not alphabetic or "*" MUST be generated as 170 structured Strings, so they are not mistaken for other types. 172 Implementations SHOULD NOT consume values that violate these inferred 173 constraints. For example, a consuming implementation were to coerce 174 a max-age with a decimal value into an integer would behave 175 differently than other implementations, potentially causing 176 interoperability issues. 178 Parameters received on directives are to be ignored, unless other 179 handling is explicitly specified. 181 If a targeted field in a given response is empty, or a parsing error 182 is encountered, that field MUST be ignored by the cache (i.e., it 183 behaves as if the field were not present, likely falling back to 184 other cache control mechanisms present). 186 2.2. Cache Behavior 188 A cache that implements this specification maintains a _target list_ 189 - an ordered list of the targeted field names that it uses for 190 caching policy, with the order reflecting priority from most 191 applicable to least. The target list might be fixed, user- 192 configurable, or generated per request, depending upon the 193 implementation. 195 For example, a CDN cache might support both CDN-Cache-Control and a 196 header specific to that CDN, ExampleCDN-Cache-Control, with the 197 latter overriding the former. Its target list would be: 199 [ExampleCDN-Cache-Control, CDN-Cache-Control] 201 When a cache that implements this specification receives a response 202 with one or more of of the header field names on its target list, the 203 cache MUST select the first (in target list order) field with a 204 valid, non-empty value and use its value to determine the caching 205 policy for the response, and MUST ignore the Cache-Control and 206 Expires header fields in that response, unless no valid, non-empty 207 value is available from the listed header fields. 209 Note that this occurs on a response-by-response basis; if no member 210 of the cache's target list is present, valid and non-empty, a cache 211 falls back to other cache control mechanisms as required by HTTP 212 [HTTP-CACHING]. 214 Targeted fields that are not on a cache's target list MUST NOT change 215 that cache's behaviour, and MUST be passed through. 217 Caches that use a targeted field MUST implement the semantics of the 218 following cache directives: 220 * max-age 222 * must-revalidate 224 * no-store 226 * no-cache 228 * private 229 Furthermore, they SHOULD implement other cache directives (including 230 extension cache directives) that they support in the Cache-Control 231 response header field. 233 The semantics and precedence of cache directives in a targeted field 234 are the same as those in Cache-Control. In particular, no-store and 235 no-cache make max-age inoperative, and unrecognised extension 236 directives are ignored. 238 2.3. Interaction with HTTP Freshness 240 HTTP caching has a single, end-to-end freshness model defined in 241 Section 4.2 of [HTTP-CACHING]. When additional freshness mechanisms 242 are only available to some caches along a request path (for example, 243 using targeted fields), their interactions need to be carefully 244 considered. In particular, a targeted cache might have longer 245 freshness lifetimes available to it than other caches, causing it to 246 serve responses that appear to be prematurely (or even immediately) 247 stale to them, negatively impacting cache efficiency. 249 For example, a response stored by a CDN cache might be served with 250 the following headers: 252 Age: 1800 253 Cache-Control: max-age=600 254 CDN-Cache-Control: max-age=3600 256 From the CDN's perspective, this response is still fresh after being 257 cached for 30 minutes, while from other caches' standpoint, this 258 response is already stale. See [AGE-PENALTY] for more discussion. 260 When the targeted cache has a strong coherence mechanism (e.g., the 261 origin server has the ability to proactively invalidate cached 262 responses), it is often desirable to mitigate these effects. Some 263 techniques seen in deployments include: 265 * Removing the Age header field 267 * Updating the Date header field value to the current time 269 * Updating the Expires header field value to the current time, plus 270 any Cache-Control: max-age value 272 This specification does not place any specific requirements on 273 implementations to mitigate these effects, but definitions of 274 targeted fields can do so. 276 2.4. Defining Targeted Fields 278 A targeted field for a particular class of cache can be defined by 279 requesting registration in the Hypertext Transfer Protocol (HTTP) 280 Field Name Registry (https://www.iana.org/assignments/http-fields/). 282 Registration requests can use this document as the specification 283 document, in which case the Comments field should clearly define the 284 class of caches that the targeted field applies to. Alternatively, 285 if other documentation for the field has been created, it can be used 286 as the specification document. 288 By convention, targeted fields have the suffix "-Cache-Control": 289 e.g., "ExampleCDN-Cache-Control". However, this suffix MUST NOT be 290 used on its own to identify targeted fields; it is only a convention. 292 3. The CDN-Cache-Control Targeted Field 294 The CDN-Cache-Control response header field is a targeted field 295 (Section 2) that allows origin servers to control the behaviour of 296 CDN caches interposed between them and clients, separately from other 297 caches that might handle the response. 299 It applies to caches that are part of a distributed network that 300 operate on behalf of an origin server (commonly called a Content 301 Delivery Network or CDN). 303 CDN caches that use CDN-Cache-Control will typically forward this 304 header so that downstream CDN caches can use it as well. However, 305 they MAY remove it when this is undesirable (for example, when 306 configured to do so because it is known not to be used downstream). 308 3.1. Examples 310 For example, the following header fields would instruct a CDN cache 311 (i.e., a cache with a target list of \[CDN-Cache-Control]]) to 312 consider the response fresh for 600 seconds, other shared caches for 313 120 seconds and any remaining caches for 60 seconds: 315 Cache-Control: max-age=60, s-maxage=120 316 CDN-Cache-Control: max-age=600 318 These header fields would instruct a CDN cache to consider the 319 response fresh for 600 seconds, while all other caches would be 320 prevented from storing it: 322 CDN-Cache-Control: max-age=600 323 Cache-Control: no-store 324 Because CDN-Cache-Control is not present, this header field would 325 prevent all caches from storing the response: 327 Cache-Control: no-store 329 Whereas these would prevent all caches except for CDN caches from 330 storing the response: 332 Cache-Control: no-store 333 CDN-Cache-Control: none 335 (note that 'none' is not a registered cache directive; it is here to 336 avoid sending a header field with an empty value, which would be 337 ignored) 339 4. IANA Considerations 341 Please register the following entry in the Hypertext Transfer 342 Protocol (HTTP) Field Name Registry defined by [HTTP]: 344 * Field Name: CDN-Cache-Control 346 * Status: permanent 348 * Specification Document: [this document] 350 * Comments: Cache-Control directives targeted at Content Delivery 351 Networks 353 5. Security Considerations 355 The security considerations of HTTP caching [HTTP-CACHING] apply. 357 The ability to carry multiple caching policies on a response can 358 result in confusion about how a response will be cached in different 359 systems, if not used carefully. This might result in unintentional 360 reuse of responses with sensitive information. 362 6. References 364 6.1. Normative References 366 [HTTP] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 367 Semantics", Work in Progress, Internet-Draft, draft-ietf- 368 httpbis-semantics-19, 12 September 2021, 369 . 372 [HTTP-CACHING] 373 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 374 Caching", Work in Progress, Internet-Draft, draft-ietf- 375 httpbis-cache-19, 12 September 2021, 376 . 379 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 380 Requirement Levels", BCP 14, RFC 2119, 381 DOI 10.17487/RFC2119, March 1997, 382 . 384 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 385 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 386 May 2017, . 388 [STRUCTURED-FIELDS] 389 Nottingham, M. and P-H. Kamp, "Structured Field Values for 390 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 391 . 393 6.2. Informative References 395 [AGE-PENALTY] 396 Cohen, E. and H. Kaplan, "The age penalty and its effect 397 on cache performance", March 2001, 398 . 400 Authors' Addresses 402 Stephen Ludin 403 Akamai 405 Email: sludin@ludin.org 407 Mark Nottingham 408 Fastly 409 Prahran 410 Australia 412 Email: mnot@mnot.net 413 URI: https://www.mnot.net/ 415 Yuchen Wu 416 Cloudflare 417 Email: me@yuchenwu.net