idnits 2.17.1 draft-ietf-httpbis-targeted-cache-control-01.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 (20 September 2021) is 948 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 149, but not defined == Missing Reference: 'CDN-Cache-Control' is mentioned on line 149, but not defined -- Possible downref: Normative reference to a draft: ref. 'HTTP' -- Possible downref: Normative reference to a draft: ref. 'HTTP-CACHING' -- Duplicate reference: draft-ietf-httpbis-cache, mentioned in 'I-D.ietf-httpbis-cache', was also mentioned in 'HTTP-CACHING'. -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-httpbis-cache' Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 5 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: 24 March 2022 Fastly 6 Y. Wu 7 Cloudflare 8 20 September 2021 10 Targeted HTTP Cache Control 11 draft-ietf-httpbis-targeted-cache-control-01 13 Abstract 15 This specification defines a convention for HTTP response header 16 fields that allow directives controlling caching to be targeted at 17 specific caches or classes of caches. It also defines one such 18 header field, 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 24 March 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. Cache Behavior . . . . . . . . . . . . . . . . . . . . . 3 75 2.2. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 5 76 2.3. Interaction with HTTP Freshness . . . . . . . . . . . . . 6 77 2.4. Defining Targeted Fields . . . . . . . . . . . . . . . . 7 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 with 90 varying properties. For example, a Web site might use a cache on the 91 origin server itself; it might deploy a caching layer in the same 92 network as the origin server, it might use one or more Content 93 Delivery Networks (CDNs) that are distributed throughout the 94 Internet, and it might utilise 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 is widely used to direct 101 caching behavior. However, it is relatively undifferentiated; while 102 some directives (e.g., s-maxage) are targeted at a specific class of 103 caches (for s-maxage, shared caches), targeting is not consistently 104 available across all existing cache directives (e.g., stale-while- 105 revalidate). This is problematic, especially as the number of 106 caching extensions grows, along with the number of potential targets. 108 Some implementations have defined ad hoc control mechanisms to 109 overcome this issue, but their interoperability is low. Section 2 110 defines a standard framework for targeted cache control using HTTP 111 response headers, and Section 3 defines one such header: the CDN- 112 Cache-Control response header field. 114 1.1. Notational Conventions 116 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 117 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 118 "OPTIONAL" in this document are to be interpreted as described in BCP 119 14 [RFC2119] [RFC8174] when, and only when, they appear in all 120 capitals, as shown here. 122 2. Targeted Cache-Control Header Fields 124 A Targeted Cache-Control Header Field (hereafter, "targeted field") 125 is a HTTP response header field that has the same semantics as the 126 Cache-Control response header field ([HTTP-CACHING], Section 5.2). 127 However, it has a distinct field name that indicates the target for 128 its directives. 130 For example: 132 CDN-Cache-Control: max-age=60 134 is a targeted field that applies to Content Delivery Networks (CDNs), 135 as defined in Section 3. 137 2.1. Cache Behavior 139 A cache that implement this specification maintains a _target list_ - 140 an ordered list of the targeted field names that it uses for caching 141 policy, with the order reflecting priority from most applicable to 142 least. The target list might be fixed, user-configurable, or 143 generated per request, depending upon the implementation. 145 For example, a CDN cache might support both CDN-Cache-Control and a 146 header specific to that CDN, ExampleCDN-Cache-Control, with the 147 latter overriding the former. Its target list would be: 149 [ExampleCDN-Cache-Control, CDN-Cache-Control] 151 When a cache that implements this specification receives a response 152 with one or more of of the header field names on its target list, the 153 cache MUST select the first (in target list order) field with a 154 valid, non-empty value and use its value to determine the caching 155 policy for the response, and MUST ignore the Cache-Control and 156 Expires header fields in that response, unless no valid, non-empty 157 value is available from the listed header fields. 159 Note that this occurs on a response-by-response basis; if no member 160 of the cache's target list is present, valid and non-empty, a cache 161 falls back to other cache control mechanisms as required by HTTP 162 [HTTP-CACHING]. 164 Targeted fields that are not on a cache's target list MUST NOT change 165 that cache's behaviour, and MUST be passed through. 167 Caches that use a targeted field MUST implement the semantics of the 168 following cache directives: 170 * max-age 172 * must-revalidate 174 * no-store 176 * no-cache 178 * private 180 Furthermore, they SHOULD implement other cache directives (including 181 extension cache directives) that they support in the Cache-Control 182 response header field. 184 The semantics and precedence of cache directives in a targeted field 185 are the same as those in Cache-Control. In particular, no-store and 186 no-cache make max-age inoperative, and unrecognised extension 187 directives are ignored. 189 2.2. Syntax 191 Targeted fields are defined as Dictionary Structured Fields 192 (Section 3.2 of [STRUCTURED-FIELDS]). Each member of the dictionary 193 is a cache directive from the Hypertext Transfer Protocol (HTTP) 194 Cache Directive Registry. 196 Because cache directives are not defined in terms of structured data 197 types, it is necessary to map their values into the appropriate 198 types. Typically, they are mapped into a Boolean (Section 3.3.6 of 199 [STRUCTURED-FIELDS]) when the member has no separate value, a Token 200 (Section 3.3.4 of [STRUCTURED-FIELDS]) for alphanumeric values, a 201 String (Section 3.3.3 of [STRUCTURED-FIELDS]) for quote-delimited 202 values, or an Integer (Section 3.3.1 of [STRUCTURED-FIELDS]) for 203 purely numeric values. 205 For example, the max-age directive (Section 5.2.2.1 of 206 [HTTP-CACHING]) has an integer value; no-store (Section 5.2.2.5 of 207 [HTTP-CACHING]) always has a boolean true value, and no-cache 208 (Section 5.2.2.4 of [HTTP-CACHING]) has a value that can either be 209 boolean true or a string containing a comma-delimited list of field 210 names. 212 Implementations MUST NOT generate and SHOULD NOT consume values that 213 violate these inferred constraints on the directive's value (e.g. 214 coerce a max-age with a decimal value into an integer). Parameters 215 received on directives are to be ignored, unless other handling is 216 explicitly specified. 218 Sending implementations MUST generate valid Structured Fields. 219 Receiving implementations SHOULD use a Structured Fields parser, but 220 MAY reuse an existing parser for the Cache-Control field value 221 (Section 5.2 of [HTTP-CACHING]). Those that do SHOULD implement the 222 following constraints, to aid in a smooth transition to a full 223 Structured Field parser and prevent interoperability issues: 225 * Directive names are all lowercase (e.g., "MAX-AGE=60" is 226 considered an error). 228 * If a directive is repeated in the field value (e.g., "max-age=30, 229 max-age=60"), the last value 'wins' (60, in this case). 231 * Members of the directives can have parameters (e.g., "max- 232 age=30;a=b;c=d"), which are ignored unless specified. 234 If a targeted field in a given response is empty, or a parsing error 235 is encountered, that field MUST be ignored by the cache (i.e., it 236 behaves as if the field were not present, likely falling back to 237 other cache control mechanisms present). 239 2.3. Interaction with HTTP Freshness 241 HTTP caching has a single, end-to-end freshness model defined in 242 Section 4.2 of [I-D.ietf-httpbis-cache]. When additional freshness 243 mechanisms are only available to some caches along a request path 244 (for example, using targeted fields), their interactions need to be 245 carefully considered. In particular, a targeted cache might have 246 longer freshness lifetimes available to it than other caches, causing 247 it to serve responses that appear to be prematurely (or even 248 immediately) stale to them, negatively impacting cache efficiency. 250 For example, a response stored by a CDN cache might be served with 251 the following headers: 253 Age: 1800 254 Cache-Control: max-age=600 255 CDN-Cache-Control: max-age=3600 257 From the CDN's perspective, this response is still fresh after being 258 cached for 30 minutes, while from other caches' standpoint, this 259 response is already stale. See [AGE-PENALTY] for more discussion. 261 When the targeted cache has a strong coherence mechanism (e.g., the 262 origin server has the ability to proactively invalidate cached 263 responses), it is often desirable to mitigate these effects. Some 264 techniques seen in deployments include: 266 * Removing the Age header field 268 * Updating the Date header field value to the current time 270 * Updating the Expires header field value to the current time, plus 271 any Cache-Control: max-age value 273 This specification does not place any specific requirements on 274 implementations to mitigate these effects, but definitions of 275 targeted fields can do so. 277 2.4. Defining Targeted Fields 279 A targeted field for a particular class of cache can be defined by 280 requesting registration in the Hypertext Transfer Protocol (HTTP) 281 Field Name Registry https://www.iana.org/assignments/http-fields/ 282 (https://www.iana.org/assignments/http-fields/), listing this 283 specification as the specification document. The Comments field of 284 the registration should clearly define the class of caches that the 285 targeted field applies to. 287 By convention, targeted fields have the suffix "-Cache-Control": 288 e.g., "ExampleCDN-Cache-Control". However, this suffix MUST NOT be 289 used on its own to identify targeted fields; it is only a convention. 291 3. The CDN-Cache-Control Targeted Field 293 The CDN-Cache-Control response header field is a targeted field 294 (Section 2) that allows origin servers to control the behaviour of 295 CDN caches interposed between them and clients, separately from other 296 caches that might handle the response. 298 It applies to caches that are part of a distributed network that 299 operate on behalf of an origin server (commonly called a Content 300 Delivery Network or CDN). 302 CDN caches that use CDN-Cache-Control will typically forward this 303 header so that downstream CDN caches can use it as well. However, 304 they MAY remove it when this is undesirable (for example, when 305 configured to do so because it is known not to be used downstream). 307 3.1. Examples 309 For example, the following header fields would instruct a CDN cache 310 to consider the response fresh for 600 seconds, other shared caches 311 for 120 seconds and any remaining caches for 60 seconds: 313 Cache-Control: max-age=60, s-maxage=120 314 CDN-Cache-Control: max-age=600 316 These header fields would instruct a CDN cache to consider the 317 response fresh for 600 seconds, while all other caches would be 318 prevented from storing it: 320 CDN-Cache-Control: max-age=600 321 Cache-Control: no-store 323 Because CDN-Cache-Control is not present, this header field would 324 prevent all caches from storing the response: 326 Cache-Control: no-store 328 Whereas these would prevent all caches except for CDN caches from 329 storing the response: 331 Cache-Control: no-store 332 CDN-Cache-Control: none 334 (note that 'none' is not a registered cache directive; it is here to 335 avoid sending a header field with an empty value, which would be 336 ignored) 338 4. IANA Considerations 340 Please register the following entry in the Hypertext Transfer 341 Protocol (HTTP) Field Name Registry defined by [HTTP]: 343 * Field Name: CDN-Cache-Control 345 * Status: permanent 347 * Specification Document: [this document] 349 * Comments: Cache-Control directives targeted at Content Delivery 350 Networks 352 5. Security Considerations 354 The security considerations of HTTP caching [HTTP-CACHING] apply. 356 The ability to carry multiple caching policies on a response can 357 result in confusion about how a response will be cached in different 358 systems, if not used carefully. This might result in unintentional 359 reuse of responses with sensitive information. 361 6. References 363 6.1. Normative References 365 [HTTP] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 366 Semantics", Work in Progress, Internet-Draft, draft-ietf- 367 httpbis-semantics-19, 12 September 2021, 368 . 371 [HTTP-CACHING] 372 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 373 Caching", Work in Progress, Internet-Draft, draft-ietf- 374 httpbis-cache-19, 12 September 2021, 375 . 378 [I-D.ietf-httpbis-cache] 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/ 420 Yuchen Wu 421 Cloudflare 423 Email: me@yuchenwu.net