idnits 2.17.1 draft-cdn-control-header-00.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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (23 November 2020) is 1249 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-cache-12 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). 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: Informational M. Nottingham 5 Expires: 27 May 2021 Fastly 6 Y. Wu 7 Cloudflare 8 23 November 2020 10 The CDN-Cache-Control HTTP Response Header Field 11 draft-cdn-control-header-00 13 Abstract 15 This specification defines an HTTP header field that conveys HTTP 16 cache directives to CDN caches. 18 Note to Readers 20 _RFC EDITOR: please remove this section before publication_ 22 The issues list for this draft can be found at https://github.com/ 23 cdn-specs/control-header/issues (https://github.com/cdn-specs/ 24 control-header/issues). 26 The most recent (often, unpublished) draft is at https://cdn- 27 specs.github.io/control-header/ (https://cdn-specs.github.io/control- 28 header/). 30 Recent changes are listed at https://github.com/cdn-specs/control- 31 header/commits/main (https://github.com/cdn-specs/control- 32 header/commits/main). 34 See also the draft's current status in the IETF datatracker, at 35 https://datatracker.ietf.org/doc/draft-cdn-control-header/ 36 (https://datatracker.ietf.org/doc/draft-cdn-control-header/). 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 27 May 2021. 55 Copyright Notice 57 Copyright (c) 2020 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. The CDN-Cache-Control Response Header Field . . . . . . . . . 3 74 2.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 4 75 2.2. Parsing . . . . . . . . . . . . . . . . . . . . . . . . . 5 76 3. Security Considerations . . . . . . . . . . . . . . . . . . . 5 77 4. Normative References . . . . . . . . . . . . . . . . . . . . 5 78 Appendix A. Frequently Asked Questions . . . . . . . . . . . . . 6 79 A.1. Why not Surrogate-Control? . . . . . . . . . . . . . . . 6 80 A.2. Why not mix with Cache-Control? . . . . . . . . . . . . . 6 81 A.3. Is this just for CDNs? . . . . . . . . . . . . . . . . . 7 82 A.4. What if I use more than one CDN? . . . . . . . . . . . . 7 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7 85 1. Introduction 87 Many HTTP origin servers use Content Delivery Networks (i.e., 88 distributed HTTP gateways, usually implementing caches) to speed up 89 distributing their content. 91 While HTTP defines Cache-Control as a means of controlling cache 92 behaviour for both private caches and shared caches, it is often 93 desirable to give CDN caches separate instructions. To meet this 94 need, this specification defines a separate header field that conveys 95 HTTP cache directives to CDN caches only. 97 1.1. Notational Conventions 99 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 100 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 101 "OPTIONAL" in this document are to be interpreted as described in BCP 102 14 [RFC2119] [RFC8174] when, and only when, they appear in all 103 capitals, as shown here. 105 2. The CDN-Cache-Control Response Header Field 107 The CDN-Cache-Control response header field allows origin servers to 108 control the behaviour of CDN caches interposed between them and 109 clients, separately from other caches that might handle the response. 111 It is a Dictionary Structured Header 112 [I-D.ietf-httpbis-header-structure], whose members can be any 113 directive registered in the HTTP Cache Directive Registry 114 https://www.iana.org/assignments/http-cache-directives/http-cache- 115 directives.xhtml (https://www.iana.org/assignments/http-cache- 116 directives/http-cache-directives.xhtml). 118 When a valid CDN-Cache-Control header field is present in a response, 119 CDN caches MUST ignore the Cache-Control and Expires response headers 120 in that response. As such, CDN-Cache-Control is a wholly separate 121 way to control the CDN cache. Note that this is on a response-by- 122 response basis; if CDN-Cache-Control is not present, CDN caches MAY 123 fall back to other control mechanisms as required by HTTP 124 [I-D.ietf-httpbis-cache]. 126 The semantics and precedence of cache directives in CDN-Cache-Control 127 are the same as those in Cache-Control. In particular, no-store and 128 no-cache make max-age inoperative. 130 Caches that use CDN-Cache-Control MUST implement the semantics of the 131 following directives: 133 * max-age 135 * must-revalidate 137 * no-store 139 * no-cache 141 * private 142 CDN caches that use CDN-Cache-Control MAY forward this header so that 143 downstream CDN caches can use it as well. However, doing so exposes 144 its value to all downstream clients, which might be undesirable. As 145 a result, CDN caches that process this header field MAY remove it 146 (for example, when configured to do so because it is known not to be 147 used downstream). 149 A CDN cache that does not use CDN-Cache-Control MUST pass the CDN- 150 Cache-Control header through. 152 Private caches SHOULD ignore the CDN-Cache-Control header field. 154 2.1. Examples 156 For example, the following header fields would instruct a CDN cache 157 to consider the response fresh for 600 seconds, other shared caches 158 for 120 seconds and any remaining caches for 60 seconds: 160 Cache-Control: max-age=60, s-maxage=120 161 CDN-Cache-Control: max-age=600 163 These header fields would instruct a CDN cache to consider the 164 response fresh for 600 seconds, while all other caches would be 165 prevented from storing it: 167 Cache-Control: no-store 168 CDN-Cache-Control: max-age=600 170 Because CDN-Cache-Control is not present, this header field would 171 prevent all caches from storing the response: 173 Cache-Control: no-store 175 Whereas these would prevent all caches except for CDN caches from 176 storing the response: 178 Cache-Control: no-store 179 CDN-Cache-Control: none 181 (note that 'none' is not a registered cache directive; it is here to 182 avoid sending a header field with an empty value, because such a 183 header might not be preserved in all cases) 185 2.2. Parsing 187 CDN-Cache-Control is specified as a Structured Field 188 [I-D.ietf-httpbis-header-structure], and implementations are 189 encouraged to use a parser for that format in the interests of 190 robustness, interoperability and security. 192 When an implementation parses CDN-Cache-Control as a Structured 193 Field, each directive will be assigned a value. For example, max-age 194 has an integer value; no-store's value is boolean true, and no- 195 cache's value can either be boolean true or a list of field names. 196 Implementations SHOULD NOT accept other values (e.g. coerce a max-age 197 with a decimal value into an integer). Likewise, implementations 198 SHOULD ignore parameters on directives, unless otherwise specified. 200 However, implementers MAY initially reuse a Cache-Control parser for 201 simplicity. If they do so, they SHOULD observe the following points, 202 to aid in a smooth transition to a full Structured Field parser and 203 prevent interoperability issues: 205 * If a directive is repeated in the field value (e.g., "max-age=30, 206 max-age=60"), the last value 'wins' (60, in this case) 208 * Members of the directives can have parameters (e.g., "max- 209 age=30;a=b;c=d"), which should be ignored unless specified. 211 3. Security Considerations 213 The security considerations of HTTP caching [I-D.ietf-httpbis-cache] 214 apply. 216 4. Normative References 218 [I-D.ietf-httpbis-cache] 219 Fielding, R., Nottingham, M., and J. Reschke, "HTTP 220 Caching", Work in Progress, Internet-Draft, draft-ietf- 221 httpbis-cache-12, 2 October 2020, . 224 [I-D.ietf-httpbis-header-structure] 225 Nottingham, M. and P. Kamp, "Structured Field Values for 226 HTTP", Work in Progress, Internet-Draft, draft-ietf- 227 httpbis-header-structure-19, 3 June 2020, 228 . 231 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 232 Requirement Levels", BCP 14, RFC 2119, 233 DOI 10.17487/RFC2119, March 1997, 234 . 236 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 237 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 238 May 2017, . 240 Appendix A. Frequently Asked Questions 242 A.1. Why not Surrogate-Control? 244 The Surrogate-Control header field is used by a variety of cache 245 implementations, but their interpretation of it is not consistent; 246 some only support 'no-store', others support a few directives, and 247 still more support a larger variety of implementation-specific 248 directives. These implementations also differ in how they relate 249 Surrogate-Control to Cache-Control and other mechanisms. 251 Rather than attempting to align all of these different but well 252 established behaviours (which would likely fail, because many 253 existing deployments depend upon them) or defining a very small 254 subset, a new header field seems more likely to provide clear 255 interoperability without compromising functionality. 257 A.2. Why not mix with Cache-Control? 259 An alternative design would be to have CDN caches combine the 260 directives found in Cache-Control and CDN-Cache-Control, considering 261 their union as the directives that must be followed. 263 While this would be slightly less verbose in some cases, it would 264 make interoperability considerably more complex to achieve. Consider 265 the case when there are syntax errors in the argument of a directive; 266 e.g., 'max-age=n60'. Should that directive be ignored, or does it 267 invalidate the entire header field value? If the directive is 268 ignored in CDN-Cache-Control, should the cache fall back to a value 269 in Cache-Control? And so on. 271 Also, this approach would make it difficult to direct the CDN cache 272 to store something while directing other caches to avoid storing it 273 (because no-store overrides max-age). 275 A.3. Is this just for CDNs? 277 By default, yes. There is often a need to differentiate between CDNs 278 and gateway caches deployed local to the origin server; CDN-Cache- 279 Control allows that. 281 In some cases, a site might create a CDN by deploying gateway caches 282 and routing traffic to them; this is, after all, how a CDN works at a 283 high level. To support this scenario, gateway caches MAY be 284 configured to process the CDN-Cache-Control header field, but they 285 MUST NOT default to supporting it. 287 A.4. What if I use more than one CDN? 289 Individual CDNs can choose to define their own control mechanisms 290 that take precedence over this header field. It is RECOMMENDED that 291 they use a header whose value has the same syntax and semantics, and 292 use a field name in the pattern "CDN_NAME-CDN-Cache-Control"; for 293 example, the Foo CDN might register "Foo-CDN-Cache-Control". When 294 present on a response received by Foo CDN, that header field would 295 override both CDN-Cache-Control and Cache-Control. As with CDN- 296 Cache-Control, Foo CDN could decide whether or not to strip that 297 header from responses before sending them. 299 Authors' Addresses 301 Stephen Ludin 302 Akamai 304 Email: sludin@ludin.org 306 Mark Nottingham 307 Fastly 308 made in 309 Prahran VIC 310 Australia 312 Email: mnot@mnot.net 313 URI: https://www.mnot.net/ 315 Yuchen Wu 316 Cloudflare 318 Email: me@yuchenwu.net