Skip to main content

Targeted HTTP Cache Control
draft-ietf-httpbis-targeted-cache-control-04

The information below is for an old version of the document that is already published as an RFC.
Document Type
This is an older version of an Internet-Draft that was ultimately published as RFC 9213.
Authors Stephen Ludin , Mark Nottingham , Yuchen Wu
Last updated 2022-06-08 (Latest revision 2022-01-23)
Replaces draft-cdn-control-header
RFC stream Internet Engineering Task Force (IETF)
Intended RFC status Proposed Standard
Formats
Reviews
Additional resources Mailing list discussion
Stream WG state Submitted to IESG for Publication
Document shepherd Tommy Pauly
Shepherd write-up Show Last changed 2021-11-16
IESG IESG state Became RFC 9213 (Proposed Standard)
Action Holders
(None)
Consensus boilerplate Yes
Telechat date (None)
Responsible AD Francesca Palombini
Send notices to tpauly@apple.com
IANA IANA review state IANA OK - Actions Needed
IANA action state RFC-Ed-Ack
IANA expert review state Expert Reviews OK
draft-ietf-httpbis-targeted-cache-control-04
HTTP                                                            S. Ludin
Internet-Draft                                                    Akamai
Intended status: Standards Track                           M. Nottingham
Expires: 27 July 2022                                             Fastly
                                                                   Y. Wu
                                                              Cloudflare
                                                         23 January 2022

                      Targeted HTTP Cache Control
              draft-ietf-httpbis-targeted-cache-control-04

Abstract

   This specification defines a convention for HTTP response header
   fields that allow cache directives to be targeted at specific caches
   or classes of caches.  It also defines one such header field,
   targeted at Content Delivery Network (CDN) caches.

About This Document

   This note is to be removed before publishing as an RFC.

   Status information for this document may be found at
   https://datatracker.ietf.org/doc/draft-ietf-httpbis-targeted-cache-
   control/.

   Discussion of this document takes place on the HTTP Working Group
   mailing list (mailto:ietf-http-wg@w3.org), which is archived at
   https://lists.w3.org/Archives/Public/ietf-http-wg/.  Working Group
   information can be found at https://httpwg.org/.

   Source for this draft and an issue tracker can be found at
   https://github.com/httpwg/http-extensions/labels/targeted-cc.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

Ludin, et al.             Expires 27 July 2022                  [Page 1]
Internet-Draft         Targeted HTTP Cache Control          January 2022

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 27 July 2022.

Copyright Notice

   Copyright (c) 2022 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Notational Conventions  . . . . . . . . . . . . . . . . .   3
   2.  Targeted Cache-Control Header Fields  . . . . . . . . . . . .   3
     2.1.  Syntax  . . . . . . . . . . . . . . . . . . . . . . . . .   4
     2.2.  Cache Behavior  . . . . . . . . . . . . . . . . . . . . .   5
     2.3.  Interaction with HTTP Freshness . . . . . . . . . . . . .   6
     2.4.  Defining Targeted Fields  . . . . . . . . . . . . . . . .   7
   3.  The CDN-Cache-Control Targeted Field  . . . . . . . . . . . .   7
     3.1.  Examples  . . . . . . . . . . . . . . . . . . . . . . . .   7
   4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   8
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .   8
   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   8
     6.1.  Normative References  . . . . . . . . . . . . . . . . . .   8
     6.2.  Informative References  . . . . . . . . . . . . . . . . .   9
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   9

1.  Introduction

   Modern deployments of HTTP often use multiple layers of caching.  For
   example, a website might use a cache on the origin server itself; it
   might deploy a caching layer in the same network as the origin
   server, it might use one or more Content Delivery Networks (CDNs)
   that are distributed throughout the Internet, and it might benefit
   from browser caching as well.

Ludin, et al.             Expires 27 July 2022                  [Page 2]
Internet-Draft         Targeted HTTP Cache Control          January 2022

   Because it is often desirable to control these different classes of
   caches separately, some means of targeting cache directives at them
   is necessary.  For example, if a publisher has a mechanism to
   invalidate the contents of a cache that it has a relationship with
   (such as a CDN cache), they might be more comfortable assigning a
   more generous caching policy to it, while still wanting to restrict
   the behavior of other caches.

   The HTTP Cache-Control response header field (defined in Section 5.2
   of [HTTP-CACHING]) is widely used to direct caching behavior.
   However, it is relatively undifferentiated; while some cache
   directives (e.g., s-maxage) are targeted at a specific class of
   caches (for s-maxage, shared caches), targeting is not consistently
   available across all existing cache directives (e.g., stale-while-
   revalidate).  This is problematic, especially as the number of
   caching extensions grows, along with the number of potential targets.

   Some implementations have defined ad hoc control mechanisms to
   overcome this issue, but their interoperability is low.  Section 2
   defines a standard framework for targeted cache control using HTTP
   response headers, and Section 3 defines one such header: the CDN-
   Cache-Control response header field.

1.1.  Notational Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

2.  Targeted Cache-Control Header Fields

   A Targeted Cache-Control Header Field (hereafter, "targeted field")
   is an HTTP response header field that has the same semantics as the
   Cache-Control response header field ([HTTP-CACHING], Section 5.2).
   However, it has a distinct field name that indicates the target for
   its cache directives.

   For example:

   CDN-Cache-Control: max-age=60

   is a targeted field that applies to Content Delivery Networks (CDNs),
   as defined in Section 3.

Ludin, et al.             Expires 27 July 2022                  [Page 3]
Internet-Draft         Targeted HTTP Cache Control          January 2022

2.1.  Syntax

   Targeted fields are Dictionary Structured Fields (Section 3.2 of
   [STRUCTURED-FIELDS]).  Each member of the dictionary is an HTTP cache
   response directive (Section 5.2.2 of [HTTP-CACHING]) including
   extension response directives (as per Section 5.2.3 of
   [HTTP-CACHING]).  Note that while targeted fields often have the same
   syntax as Cache-Control fields, differences in error handling mean
   that using a Cache-Control parser rather than a Structured Fields
   parser can introduce interoperability issues.

   Because cache directives are not defined in terms of structured data
   types, it is necessary to map their values into the appropriate
   types.  Section 5.2 of [HTTP-CACHING] defines cache directive values
   to be either absent, a quoted-string, or a token.

   This means that cache directives that have no value will be mapped to
   a Boolean (Section 3.3.6 of [STRUCTURED-FIELDS]).  When the value is
   a quoted-string, it will be mapped to a String (Section 3.3.3 of
   [STRUCTURED-FIELDS]), and when it is a token, it will map to a Token
   (Section 3.3.4 of [STRUCTURED-FIELDS]), an Integer (Section 3.3.1 of
   [STRUCTURED-FIELDS]) or a Decimal (Section 3.3.2 of
   [STRUCTURED-FIELDS]), depending on the content of the value.

   For example, the max-age directive (Section 5.2.2.1 of
   [HTTP-CACHING]) has an integer value; no-store (Section 5.2.2.5 of
   [HTTP-CACHING]) always has a boolean true value, and no-cache
   (Section 5.2.2.4 of [HTTP-CACHING]) has a value that can either be
   boolean true or a string containing a comma-delimited list of field
   names.

   Implementations MUST NOT generate values that violate these inferred
   constraints on the cache directive's value.  In particular, string
   values whose first character is not alphabetic or "*" MUST be
   generated as structured Strings, so they are not mistaken for other
   types.

   Implementations SHOULD NOT consume values that violate these inferred
   constraints.  For example, a consuming implementation that coerces a
   max-age with a decimal value into an integer would behave differently
   than other implementations, potentially causing interoperability
   issues.

   Parameters received on cache directives are to be ignored, unless
   other handling is explicitly specified.

Ludin, et al.             Expires 27 July 2022                  [Page 4]
Internet-Draft         Targeted HTTP Cache Control          January 2022

   If a targeted field in a given response is empty, or a parsing error
   is encountered, that field MUST be ignored by the cache (i.e., it
   behaves as if the field were not present, likely falling back to
   other cache-control mechanisms present).

2.2.  Cache Behavior

   A cache that implements this specification maintains a _target list_
   - an ordered list of the targeted field names that it uses for
   caching policy, with the order reflecting priority from most
   applicable to least.  The target list might be fixed, user-
   configurable, or generated per request, depending upon the
   implementation.

   For example, a CDN cache might support both CDN-Cache-Control and a
   header specific to that CDN, ExampleCDN-Cache-Control, with the
   latter overriding the former.  Its target list would be:

     [ExampleCDN-Cache-Control, CDN-Cache-Control]

   When a cache that implements this specification receives a response
   with one or more of the header field names on its target list, the
   cache MUST select the first (in target list order) field with a
   valid, non-empty value and use its value to determine the caching
   policy for the response, and MUST ignore the Cache-Control and
   Expires header fields in that response, unless no valid, non-empty
   value is available from the listed header fields.

   Note that this occurs on a response-by-response basis; if no member
   of the cache's target list is present, valid and non-empty, a cache
   falls back to other cache control mechanisms as required by HTTP
   [HTTP-CACHING].

   Targeted fields that are not on a cache's target list MUST NOT change
   that cache's behaviour, and MUST be passed through.

   Caches that use a targeted field MUST implement the semantics of the
   following cache directives:

   *  max-age

   *  must-revalidate

   *  no-store

   *  no-cache

   *  private

Ludin, et al.             Expires 27 July 2022                  [Page 5]
Internet-Draft         Targeted HTTP Cache Control          January 2022

   Furthermore, they SHOULD implement other cache directives (including
   extension cache directives) that they support in the Cache-Control
   response header field.

   The semantics and precedence of cache directives in a targeted field
   are the same as those in Cache-Control.  In particular, no-store and
   no-cache make max-age inoperative, and unrecognised extension
   directives are ignored.

2.3.  Interaction with HTTP Freshness

   HTTP caching has a single, end-to-end freshness model defined in
   Section 4.2 of [HTTP-CACHING].  When additional freshness mechanisms
   are only available to some caches along a request path (for example,
   using targeted fields), their interactions need to be carefully
   considered.  In particular, a targeted cache might have longer
   freshness lifetimes available to it than other caches, causing it to
   serve responses that appear to be prematurely (or even immediately)
   stale to those other caches, negatively impacting cache efficiency.

   For example, a response stored by a CDN cache might be served with
   the following headers:

   Age: 1800
   Cache-Control: max-age=600
   CDN-Cache-Control: max-age=3600

   From the CDN's perspective, this response is still fresh after being
   cached for 30 minutes, while from other caches' standpoint, this
   response is already stale.  See [AGE-PENALTY] for more discussion.

   When the targeted cache has a strong coherence mechanism (e.g., the
   origin server has the ability to proactively invalidate cached
   responses), it is often desirable to mitigate these effects.  Some
   techniques seen in deployments include:

   *  Removing the Age header field

   *  Updating the Date header field value to the current time

   *  Updating the Expires header field value to the current time, plus
      any Cache-Control: max-age value

   This specification does not place any specific requirements on
   implementations to mitigate these effects, but definitions of
   targeted fields can do so.

Ludin, et al.             Expires 27 July 2022                  [Page 6]
Internet-Draft         Targeted HTTP Cache Control          January 2022

2.4.  Defining Targeted Fields

   A targeted field for a particular class of cache can be defined by
   requesting registration in the Hypertext Transfer Protocol (HTTP)
   Field Name Registry (https://www.iana.org/assignments/http-fields/).

   Registration requests can use this document as the specification
   document, in which case the Comments field should clearly define the
   class of caches that the targeted field applies to.  Alternatively,
   if other documentation for the field has been created, it can be used
   as the specification document.

   By convention, targeted fields have the suffix "-Cache-Control":
   e.g., "ExampleCDN-Cache-Control".  However, this suffix MUST NOT be
   used on its own to identify targeted fields; it is only a convention.

3.  The CDN-Cache-Control Targeted Field

   The CDN-Cache-Control response header field is a targeted field
   (Section 2) that allows origin servers to control the behaviour of
   CDN caches interposed between them and clients, separately from other
   caches that might handle the response.

   It applies to caches that are part of a distributed network that
   operate on behalf of an origin server (commonly called a Content
   Delivery Network or CDN).

   CDN caches that use CDN-Cache-Control will typically forward this
   header so that downstream CDN caches can use it as well.  However,
   they MAY remove it when this is undesirable (for example, when
   configured to do so because it is known not to be used downstream).

3.1.  Examples

   For example, the following header fields would instruct a CDN cache
   (i.e., a cache with a target list of [CDN-Cache-Control]) to consider
   the response fresh for 600 seconds, other shared caches to consider
   the response fresh for 120 seconds, and any remaining caches to
   consider the response fresh for 60 seconds:

   Cache-Control: max-age=60, s-maxage=120
   CDN-Cache-Control: max-age=600

   These header fields would instruct a CDN cache to consider the
   response fresh for 600 seconds, while all other caches would be
   prevented from storing it:

Ludin, et al.             Expires 27 July 2022                  [Page 7]
Internet-Draft         Targeted HTTP Cache Control          January 2022

   CDN-Cache-Control: max-age=600
   Cache-Control: no-store

   Because CDN-Cache-Control is not present, this header field would
   prevent all caches from storing the response:

   Cache-Control: no-store

   Whereas these would prevent all caches except for CDN caches from
   storing the response:

   Cache-Control: no-store
   CDN-Cache-Control: none

   (note that 'none' is not a registered cache directive; it is here to
   avoid sending a header field with an empty value, which would be
   ignored)

4.  IANA Considerations

   Please register the following entry in the Hypertext Transfer
   Protocol (HTTP) Field Name Registry defined by [HTTP]:

   *  Field Name: CDN-Cache-Control

   *  Status: permanent

   *  Specification Document: [this document]

   *  Comments: Cache directives targeted at Content Delivery Networks

5.  Security Considerations

   The security considerations of HTTP caching [HTTP-CACHING] apply.

   The ability to carry multiple caching policies on a response can
   result in confusion about how a response will be cached in different
   systems, potentially resulting in unintentional reuse of responses
   with sensitive information.  For this reason, care must be exercised.

6.  References

6.1.  Normative References

Ludin, et al.             Expires 27 July 2022                  [Page 8]
Internet-Draft         Targeted HTTP Cache Control          January 2022

   [HTTP]     Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP
              Semantics", Work in Progress, Internet-Draft, draft-ietf-
              httpbis-semantics-19, 12 September 2021,
              <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-
              semantics-19>.

   [HTTP-CACHING]
              Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP
              Caching", Work in Progress, Internet-Draft, draft-ietf-
              httpbis-cache-19, 12 September 2021,
              <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-
              cache-19>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

   [STRUCTURED-FIELDS]
              Nottingham, M. and P-H. Kamp, "Structured Field Values for
              HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021,
              <https://www.rfc-editor.org/rfc/rfc8941>.

6.2.  Informative References

   [AGE-PENALTY]
              Cohen, E. and H. Kaplan, "The age penalty and its effect
              on cache performance", March 2001,
              <https://dl.acm.org/doi/10.5555/1251440.1251447>.

Authors' Addresses

   Stephen Ludin
   Akamai

   Email: sludin@ludin.org

   Mark Nottingham
   Fastly
   Prahran
   Australia

   Email: mnot@mnot.net

Ludin, et al.             Expires 27 July 2022                  [Page 9]
Internet-Draft         Targeted HTTP Cache Control          January 2022

   URI:   https://www.mnot.net/

   Yuchen Wu
   Cloudflare

   Email: me@yuchenwu.net

Ludin, et al.             Expires 27 July 2022                 [Page 10]