CDNI Cache Control Metadata

Introduction In addition to the cache control parameters currently specified by Cache object in , 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.

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.
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.
Cache Bypass Control - Allows content providers to bypass CDN caching when needed (typically for testing or performance benchmarking purposes).
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.
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.

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]
- 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: 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: 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.

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 ) , 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 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'.

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

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”: Example 2: A MI.CacheBypassPolicy that applies to all requests where the host header is bypass.example.com:

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 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:

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.

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

IANA Considerations

CDNI Payload Types TBD.

Acknowledgements The authors would like to express their gratitude to the members of the Streaming Video Technology Alliance 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