CDNI Cache Control Metadata
draft-power-cdni-cache-control-metadata-00

Network Working Group                                           W. Power
Internet-Draft                                              G. Goldstein
Updates: 8006 (if approved)                           Lumen Technologies
Intended status: Standards Track                           13 March 2023
Expires: 14 September 2023

                      CDNI Cache Control Metadata
               draft-power-cdni-cache-control-metadata-00

Abstract

   This specification adds to the basic Cache Control metadata defined
   in RFC8006, providing Content Providers and uCDNs more fine-grained
   control over dCDN caching.  Use cases include overriding or adjusting
   cache-control headers from the origin, bypassing caching altogether,
   or altering cache keys with dynamically generated values.

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/.

   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 14 September 2023.

Copyright Notice

   Copyright (c) 2023 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.

Power & Goldstein       Expires 14 September 2023               [Page 1]
Internet-Draft         CDNI Cache Control Metadata            March 2023

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  MI.CachePolicy  . . . . . . . . . . . . . . . . . . . . . . .   3
   3.  MI.NegativeCachePolicy  . . . . . . . . . . . . . . . . . . .   6
   4.  MI.StaleContentCachePolicy  . . . . . . . . . . . . . . . . .   7
   5.  MI.CacheBypassPolicy  . . . . . . . . . . . . . . . . . . . .   9
   6.  MI.ComputedCacheKey . . . . . . . . . . . . . . . . . . . . .  11
   7.  Conclusion  . . . . . . . . . . . . . . . . . . . . . . . . .  11
   8.  Security Considerations . . . . . . . . . . . . . . . . . . .  12
   9.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  12
     9.1.  CDNI Payload Types  . . . . . . . . . . . . . . . . . . .  12
   10. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  12
   11. References  . . . . . . . . . . . . . . . . . . . . . . . . .  12
     11.1.  Normative References . . . . . . . . . . . . . . . . . .  12
     11.2.  Informative References . . . . . . . . . . . . . . . . .  13
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  13

1.  Introduction

   In addition to the cache control parameters currently specified by
   Cache object in [RFC8006], Content Providers and uCDNs often need
   more fine-grained control over dCDN caching, including scenarios
   where it is desirable to override or adjust cache-control headers
   from the origin.

   These capabilities are required for commercial CDN and open caching
   use cases:

   Positive Cache Control - Allows the uCDN to specify internal caching
   policies for the dCDN and external caching policies advertised to
   clients of the dCDN, overriding any cache control policy set in the
   response from the uCDN.

   1.  Positive Cache Control - Allows the uCDN to specify internal
       caching policies for the dCDN and external caching policies
       advertised to clients of the dCDN, overriding any cache control
       policy set in the response from the uCDN.

   2.  Negative Cache Control - Allows the specification of caching
       policies based on error response codes received from the origin,
       allowing for fine-grained control of the downstream caching of
       error responses.  For example, it may be desirable to cache error
       responses at the dCDN for a short period of time to prevent an
       overwhelmed origin service or uCDN from being flooded with
       requests.

Power & Goldstein       Expires 14 September 2023               [Page 2]
Internet-Draft         CDNI Cache Control Metadata            March 2023

   3.  Cache Bypass Control - Allows content providers to bypass CDN
       caching when needed (typically for testing or performance
       benchmarking purposes).

   4.  Stale Content Policies - Allows control over how the dCDN should
       process requests for stale content.  For example, this policy
       allows the content provider to specify that stale content be
       served from cache for a specified time period while refreshes
       from the origin occur asynchronously.

   5.  Dynamically Constructed Cache Keys - It is typical in advanced
       CDN configurations to generate cache keys that are dynamically
       constructed via lightweight processing of various properties of
       the HTTP request and/or response.  As an example, an origin may
       specify a cache key as a value returned in a specific HTTP
       response header.  The Metadata Expression Language is used to
       allow for such advanced cache key construction.

2.  MI.CachePolicy

   CachePolicy is a new GenericMetadata object that allows for the uCDN
   to specify internal caching policies for the dCDN, as well as
   external caching policies advertised to clients of the dCDN
   (overriding any cache control policy set in the response from the
   uCDN).

      Property: internal

      -  Description: Specifies the internal cache control policy to be
         used by the dCDN.

      -  Type: Number in seconds encoded as string (e.g. 5 is a five
         second cache ) and/or a list of Enumeration [as-is|no-cache|no-
         store]

      -  Mandatory-to-Specify: No.  The default is to use the cache
         control policy specified in the response from the uCDN.

      Property: external

      -  Description: Specifies the external cache control policy to be
         used by clients of the dCDN.

      -  Type: Number in seconds encoded as string (e.g. 5 is a five
         second cache ) and/or a list of Enumeration [as-is|no-cache|no-
         store]

Power & Goldstein       Expires 14 September 2023               [Page 3]
Internet-Draft         CDNI Cache Control Metadata            March 2023

      -  Mandatory-to-Specify: No.  The default is to use the cache
         control policy specified in the response from the uCDN.

      Property: force-internal

      -  Description: If set to True, the metadata interface cache
         policy defined in the MI.CachePolicy internal property value
         will override any cache control policy set in the response from
         the uCDN.  If set to False, the MI.CachePolicy internal
         property value is only used if there is no cache control policy
         provided in the response from the uCDN.

      -  Type: Boolean

      -  Mandatory-to-Specify: No.  The default is "False", which will
         apply the MI.CachePolicy internal property value only if no
         policy is provided in the response from the uCDN.

      Property: force-external

      -  Description: If set to True, the metadata interface cache
         policy defined in the MI.CachePolicy external property value
         will override any cache control policy set in the response from
         the uCDN.  If set to False, the MI.CachePolicy external
         property value is only used if there is no cache control policy
         provided in the response from the uCDN.

      -  Type: Boolean

      -  Mandatory-to-Specify: No.  The default is "False", which will
         apply the MI.CachePolicy external property value only if no
         policy is provided in the response from the uCDN.

   Example 1: An MI.CachePolicy that sets the internal cache control
   policy to five seconds.  The external cache policy is set to 'no-
   cache', and both policies are forced:

   {
     "generic-metadata-type": "MI.CachePolicy",
     "generic-metadata-value": {
       "internal": "5",
       "external": "no-cache",
       "force-internal": "true",
       "force-external": "true"
     }
   }

Power & Goldstein       Expires 14 September 2023               [Page 4]
Internet-Draft         CDNI Cache Control Metadata            March 2023

   Example 2: An MI.CachePolicy that sets the internal cache control
   policy to "as-is" (keep the policy set in the response from the
   uCDN).  The external cache policy is set to 'no-cache' and forced:

   {
     "generic-metadata-type": "MI.CachePolicy",
     "generic-metadata-value": {
       "internal": "as-is",
       "external": "no-cache",
       "force-external": "true"
     }
   }

   Example 3: An MI.CachePolicy in the context of the processing stages
   model that sets a caching policy only if the HTTP status code
   received from the origin is a 200.  In this example, the internal
   cache control policy is set to five seconds.  The external cache
   policy is set to 'no-cache'.  Internal and external force flags are
   both set to ‘False’, indicating that the MI.CachePolicy only applies
   if there is no cache policy in the response from the uCDN.

   {
     "generic-metadata-type": "MI.ProcessingStages",
     "generic-metadata-value": {
       "origin-response": [
         {
           "match": {
             "expression": "resp.status == 200"
         },
         "stage-metadata": {
             "generic-metadata": [
               {
                 "generic-metadata-type": "MI.CachePolicy",
                 "generic-metadata-value": {
                   "internal": "5",
                   "external": "no-cache",
                   "force-internal": "false",
                   "force-external": "false"
                 }
               }
             ]
           }
         }
       ]
     }
   }

Power & Goldstein       Expires 14 September 2023               [Page 5]
Internet-Draft         CDNI Cache Control Metadata            March 2023

3.  MI.NegativeCachePolicy

   NegativeCachePolicy is a new GenericMetadata object that allows for
   the specification of caching policies based on response codes
   received from the origin.

      Property: error-codes

      -  Description: Array of HTTP response status codes (See Sections
         15.5 and 15.6 of [RFC9110]) , that if returned from the uCDN,
         will be cached using the cache policy defined by the cache-
         policy property.

      -  Type: Array of HTTP response status codes

      -  Values: Any HTTP status code from 100 to 599, or one of the
         special values "4xx" or "5xx", where "xx" implies everything
         from 00 to 99.  Note that use of 4xx would specify that 416
         responses are cached.

      -  Mandatory-to-Specify: No.  The default is to revert to
         [RFC8006] behavior.  An empty or unspecified list may function
         as a means to revoke a list inherited from an upper level
         configuration

      Property: cache-policy

      -  Description: MI.CachePolicy to apply to the HTTP response
         status codes returned by the uCDN.

      -  Mandatory-to-Specify: Yes

   Example: A MI.NegativeCachePolicy that applies to HTTP error codes:
   "404", "503", "504" and sets the internal cache control policy to
   five seconds and external to 'no-cache'.

   {
     "generic-metadata-type": "MI.NegativeCachePolicy",
     "generic-metadata-value": {
       "error-codes": [ "404", "503", "504" ],
       "cache-policy": {
         "internal": "5",
         "external": "no-cache",
         "force-internal": "true",
         "force-external": "true"
       }
     }
   }

Power & Goldstein       Expires 14 September 2023               [Page 6]
Internet-Draft         CDNI Cache Control Metadata            March 2023

4.  MI.StaleContentCachePolicy

   MI.StaleContentCachePolicy is a new GenericMetadata object that
   allows the uCDN to specify the policy to use by a dCDN when
   responding with stale content.  For example, this policy allows the
   content provider to specify that stale content be served from cache
   for a specified time period while refreshes from the origin occur
   asynchronously.

      Property: stale-while-revalidating

      -  Description: Instructs the dCDN to serve a stale version of a
         resource while refreshing the resource with the uCDN.  When set
         to "True", the dCDN will return a previously cached version of
         a resource while the resource is refreshed with the uCDN in the
         background.

      -  Type: Boolean

      -  Mandatory-to-Specify: No.  The default is False, which waits
         for the uCDN to refresh a resource before responding to the
         client.

      Property: stale-if-error

      -  Description: Instructs the dCDN to serve a stale version of a
         resource if any one of a specified set of HTTP status codes was
         received when trying to refresh the resource with the uCDN.  In
         this case, the dCDN will return a previously cached version of
         a resource instead of caching the error response.  While this
         capability is typically used for well-understood HTTP error
         status codes, a list of any HTTP codes can be provided for
         maximum flexibility.

      -  Type: Array of HTTP response status codes

      -  Values: Any HTTP status code from 100 to 599, or one of the
         special values "4xx" or "5xx", where "xx" implies everything
         from 00 to 99.

      -  Mandatory-to-Specify: No.  The default is to not serve stale
         content.  An empty or unspecified list may function as a mean
         to revoke a list inherited from an upper level configuration

      Property: failed-refresh-ttl

Power & Goldstein       Expires 14 September 2023               [Page 7]
Internet-Draft         CDNI Cache Control Metadata            March 2023

      -  Description: Instructs the dCDN to serve a stale version of a
         resource for the number of seconds specified in failed-refresh-
         ttl before trying to revalidate the resource with the uCDN.
         Use of failed-refresh-ttl allows the load to be reduced on the
         uCDN during times of system stress.

      -  Type: Integer

      -  Mandatory-to-Specify: No

   Example 1: A MI.StaleContentCachePolicy where stale-while-
   revalidating is true, instructing the dCDN to respond with a stale
   cached version of the resource while it refreshes the resource with
   the uCDN in the background:

   {
     "generic-metadata-type": "MI.StaleContentCachePolicy",
     "generic-metadata-value": {
       "stale-while-revalidating": true
     }
   }

   Example 2: A MI.StaleContentCachePolicy where stale-if-error
   instructs the dCDN to use the stale cached resource if it receives an
   error of type 503 or 504 when trying to refresh the resource with the
   uCDN.

   failed-refresh-ttl instructs the dCDN to use a five second cache TTL
   on the resource that receives an error when refreshing from the uCDN.
   That is, after five seconds, the dCDN will attempt to refresh the
   resource with the uCDN.

   {
     "generic-metadata-type": "MI.StaleContentCachePolicy",
     "generic-metadata-value": {
       "stale-if-error": [ "503", "504" ],
       "failed-refresh-ttl": "5"
     }
   }

   Example 3: A MI.StaleContentCachePolicy where stale-while-
   revalidating is true, instructing the dCDN to respond with a stale
   cached version of the resource while it refreshes the resource with
   the uCDN in the background.

   stale-if-error instructs the dCDN to use the stale cached resource if
   it receives an error of type 404 or any 5xx status when trying to
   refresh the resource with the uCDN.

Power & Goldstein       Expires 14 September 2023               [Page 8]
Internet-Draft         CDNI Cache Control Metadata            March 2023

   failed-refresh-ttl instructs the dCDN to use a five second cache TTL
   on the resource that receives an error when refreshing from the uCDN.
   That is, after five seconds, the dCDN will attempt to refresh the
   resource with the uCDN.

   {
     "generic-metadata-type": "MI.StaleContentCachePolicy",
     "generic-metadata-value": {
       "stale-while-revalidating": "true",
         "stale-if-error": [ "404", "5xx" ],
         "failed-refresh-ttl": "5"
     }
   }

5.  MI.CacheBypassPolicy

   CacheBypassPolicy is a new GenericMetadata object that allows a
   client request to be set as non-cacheable.  It is expected that this
   feature will be used to allow clients to bypass cache when testing
   the uCDN fill path.  Note: CacheBypassPolicy is typically used in
   conjunction with a path match or match expression on a header value
   or query parameter.  Any content previously cached (by client
   requests that do not set CacheBypassPolicy) is not evicted.

      Property: bypass-cache

      -  Description: A Boolean value that can activate the feature for
         a given client request.  It is expected that this feature will
         be used within ProcessingStages to allow a client request to be
         marked to bypass cache.

      -  Type: Boolean

      -  Mandatory-to-Specify: No.  The default is False.

   Example 1: A MI.CacheBypassPolicy with the client HTTP header of:
   CDN-BYPASS: “True”:

Power & Goldstein       Expires 14 September 2023               [Page 9]
Internet-Draft         CDNI Cache Control Metadata            March 2023

   {
     "generic-metadata-type": "MI.ProcessingStages",
     "generic-metadata-value": {
       "client-request": [
         {
           "match": {
             "expression": "req.h.cdn-bypass == 'true'"
           },
           "stage-metadata": {
             "generic-metadata": [
               {
                 "generic-metadata-type": "MI.CacheBypassPolicy",
                 "generic-metadata-value": {
                   "bypass-cache": "true"
                 }
               }
             ]
           }
         }
       ]
     }
   }

   Example 2: A MI.CacheBypassPolicy that applies to all requests where
   the host header is bypass.example.com:

   {
     "generic-metadata-type": "MI.ProcessingStages",
     "generic-metadata-value": {
       "client-request": [
         {
           "match": {
             "expression": "req.h.host == 'bypass.example.com'"
         },
         "stage-metadata": {
             "generic-metadata": [
               {
                 "generic-metadata-type": "MI.CacheBypassPolicy",
                 "generic-metadata-value": {
                   "bypass-cache": "true"
                 }
               }
             ]
           }
         }
       ]
     }
   }

Power & Goldstein       Expires 14 September 2023              [Page 10]
Internet-Draft         CDNI Cache Control Metadata            March 2023

6.  MI.ComputedCacheKey

   It is typical in advanced CDN configurations to generate cache keys
   that are dynamically constructed via lightweight processing of
   various properties of the HTTP request and/or response.  As an
   example, an origin may specify a cache key as a value returned in a
   specific HTTP response header.

   ComputedCacheKey is a new GenericMetadata object that allows for the
   specification of a cache key using the metadata expression language.
   Typical use cases would involve the construction of a cache key from
   one or more elements of the HTTP request.  In cases where both the
   ComputedCacheKey and the Cache object are applied, the
   ComputedCacheKey will take precedence.

      Property: expression

      -  Description: The expression that specifies how the cache key
         shall be constructed.

      -  Type: String.  An expression using [CDNI-MEL] to dynamically
         construct the cache key from elements of the HTTP request and/
         or response.

      -  Mandatory-to-Specify: Yes

   Example, using a custom request header as the cache key instead of
   the URI path:

   {
     "generic-metadata-type": "MI.ComputedCacheKey",
     "generic-metadata-value": {
       "expression": "req.h.X-Cache-Key"
     }
   }

7.  Conclusion

   This specification has defined a new set of Cache Control Metadata
   objects that meet the needs of Content Providers, CDNs, and Open
   Caching Systems.  As the standard matures and gains wider adoption,
   it is expected that additions to this set of cache control policies
   will be required.

Power & Goldstein       Expires 14 September 2023              [Page 11]
Internet-Draft         CDNI Cache Control Metadata            March 2023

8.  Security Considerations

   The FCI and MI objects defined in the present document are
   transferred via the interfaces defined in CDNI [RFC8006].  [RFC8006]
   describes how to secure these interfaces, protecting the integrity,
   confidentiality and ensuring the authenticity of the dCDN and uCDN.
   The security provide by [RFC8006] should therefore address the above
   security concerns.

9.  IANA Considerations

9.1.  CDNI Payload Types

   TBD.

10.  Acknowledgements

   The authors would like to express their gratitude to the members of
   the Streaming Video Technology Alliance [SVTA] Open Caching Working
   Group for their guidance / contribution / reviews ...)

   Particulary the following people contribute in one or other way to
   the content of this draft:

      Guillaume Bichot - Broadpeak

      Pankaj Chaudhari - Disney Streaming Services

      Yoav Gressel - Qwilt

      Alfonso Siloniz - Telefonica

      Ben Rosenblum - Vecima

11.  References

11.1.  Normative References

   [RFC9110]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP Semantics", STD 97, RFC 9110,
              DOI 10.17487/RFC9110, June 2022,
              <https://www.rfc-editor.org/info/rfc9110>.

   [RFC8006]  Niven-Jenkins, B., Murray, R., Caulfield, M., and K. Ma,
              "Content Delivery Network Interconnection (CDNI)
              Metadata", RFC 8006, DOI 10.17487/RFC8006, December 2016,
              <https://www.rfc-editor.org/info/rfc8006>.

Power & Goldstein       Expires 14 September 2023              [Page 12]
Internet-Draft         CDNI Cache Control Metadata            March 2023

11.2.  Informative References

   [SVTA]     "Streaming Video Technology Alliance Home Page",
              <https://www.svta.org>.

   [CDNI-MEL] Goldstein, G., Ed., Chaudhari, P., Power, W., Gressel, Y.,
              and A. Warshavsky, "SVTA Open Caching - Configuration
              Interface Part 2a - Metadata Expression Language",
              Version 2.0, 2 July 2021.

Authors' Addresses

   Will Power
   Lumen Technologies
   United States of America
   Email: wrpower@gmail.com

   Glenn Goldstein
   Lumen Technologies
   United States of America
   Email: glenng1215@gmail.com

Power & Goldstein       Expires 14 September 2023              [Page 13]