| Internet-Draft | CDNI Metadata Model Extensions | October 2021 |
| Goldstein, et al. | Expires 28 April 2022 | [Page] |
Open Caching architecture is a use case of Content Delivery Networks Interconnection (CDNI) in which the commercial Content Delivery Network (CDN) is the upstream CDN (uCDN) and the ISP caching layer serves as the downstream CDN (dCDN). This document proposed extensions to the RFC8006 Metadata Model by way of a set of GenericMetadata objects that address extend the original CDNI capabilities to meet the more general needs of the CDN and Open Caching industry. Extensions to RFC8008 are also introduced to allow a dCDN to advertise support for these extended metadata capabilities.¶
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 28 April 2022.¶
Copyright (c) 2021 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 Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶
The Streaming Video Alliance [SVA] is a global association that works to solve streaming video challenges in an effort to improve end-user experience and adoption. The Open Caching Working Group [OCWG] of the Streaming Video Alliance [SVA] is focused on the delegation of video delivery requests from commerical CDNs to a caching layer at the ISP's network. Open Caching architecture is a specific use case of CDNI where the commercial CDN is the upstream CDN (uCDN) and the ISP caching layer is the downstream CDN (dCDN). The interchange of content delivery configuration metadata between the various entities in the delivery ecosystem is essential for efficient interoperability. The need for an industry-standard API and metadata model becomes increasingly important as content and service providers automate more of their operations, and as technologies, such as open caching, require coordination of content delivery configurations. In order to achieve this, the Open Caching Configuration Interface Specification [OC-CI] defines an interface contemplating a set of use cases.¶
The following capabilities extend the [RFC8006] Metadata Model:¶
For consistency with other CDNI documents this document follows the CDNI convention of uCDN (upstream CDN) and dCDN (downstream CDN) to represent the commercial CDN and ISP caching layer respectively.¶
This document defines and registers CDNI GenericMetadata objects (as defined in section 4 of [RFC8006]), registers additional CDNI Payload Types (section 7.1 of [RFC8006]), and adds capability objects (extending section 5 in [RFC8008])¶
The following terms are used throughout this document:¶
Additionally, this document reuses the terminology defined in [RFC6707], [RFC7336], [RFC8006], [RFC8007], [RFC8008], and [RFC8804]. Specifically, we use the following CDNI acronyms:¶
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.¶
Section 4 of [RFC8006] defines a set of GenericMetadata Object Types. Below additional GenericMetadata Objects are defined to meet the more general needs of the CDNs and Open Caching industry.¶
Note: In the following sections, the term "mandatory-to-specify" is used to convey which properties MUST be included when serializing a given capability object. When mandatory-to-specify is defined as "Yes" for an individual property, it means that if the object containing that property is included in a message, then the mandatory-to-specify property MUST also be included.¶
To meet the CDN industry requirements for origin authentication, two new authentication types are proposed to be registered via the CDNi Media Type Registration process, as described in [RFC7736].¶
auth-type: headerauth¶
auth-type: awsv4auth¶
The HeaderAuth metadata object is used in the auth-value property of the Auth object, as defined in section 4.2.7 of [RFC8006], and may be applied to any source by including or referencing it under its authentication property. This method of authentication provides a simple capability for a mutually agreed upon header to be added by the CDN to all requests sent to a specific origin. Note that if a dynamically generated header value is required, the RequestTransform capabilities within StageProcessing (See Section 2.10) can be used.¶
The AWSv4Auth metadata object is used in the auth-value property of the Auth object as defined in RFC-8006 section 4.2.7, and may be applied to any source by including or referencing it under its authentication property.¶
AWSv4 authentication causes upstream requests to have a signature applied, following the method described in [AWSv4Method]. A hash-based signature is calculated over the request URI and specified headers, and provided in an Authorization: header on the upstream request. The signature is tied to a pre-shared secret key specific to an AWS service, region, and key ID.¶
Property: access-key-id¶
Property: secret-access-key¶
Property: aws-region¶
Property: aws-service¶
Property: host-name¶
Downstream CDNs often have the ability to compress HTTP response bodies in cases where the client has declared that it can accept compressed responses (via an Accept-Encoding header), but the source/origin has returned an uncompressed response¶
The specific compression algorithm used by the dCDN is negotiated by the client's Accept-Encoding header according to [RFC7694] (including q= preferences) and the compression capabilities available on the dCDN.¶
MI.AllowCompress is a new GenericMetadata object that allows the uCDN to control the activation of response compression in the dCDN directly, and allows content providers to disable compression in cases where compressed responses are not handled properly by certain streaming devices. This can be achieved using a match expression on the user agent.¶
In addition, HeaderTransform allows the uCDN to normalize, or modify, the Accept-Encoding header to allow for fine-grain control over the selection of the compression algorithm (e.g., gzip, compress, deflate, br, etc.).¶
Properties of AllowCompress object are:¶
MI.CachePolicy is a new GenericMetadata object that allows for 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¶
Property: internal¶
Property: external¶
Property: force¶
While the properties provided by the standard CDNi metadata Cache object (See Section 4.2.6 [RFC8006]) provide some simple control over the construction of the cache key, 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.¶
MI.ComputedCacheKey is a new GenericMetadata object that allows for the specification of a cache key using the metadata expression language. See Section 4. 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.¶
Delegation of traffic between an uCDN over a dCDN based on HTTP redirection does change the domain name in the client requests. This represents a cross-origin request that must be managed appropriately using Cross-Origin Resource Sharing (CORS) headers in the responses in the dCDN.¶
The dynamic generation of CORS headers is typical in modern HTTP request processing and avoids CORS validation forwarded to the uCDN origin servers, particularly with the preflight OPTIONS requests. The CDNI metadata model requires extensions to specify how a dCDN should generate and evaluate these headers.¶
Simple CORS requests are those where both HTTP method and headers in the request are included in the safe list defined by the World Wide Web Consortium [W3C]. The user agent request can include an origin header set to the URL domain of the webpage where a player runs. Depending on the metadata configuration, the logic to apply by the dCDN is:¶
When a UA makes a request that includes a method or headers that are not included in the safe-list, the client will make a CORS preflight request using the OPTIONS method to the resource including the origin header. If CORS is enabled and the requests passes the origin validation, the OCN should respond with the set of headers that indicate what is permitted for that resource, including one or more of the following:¶
CrossoriginPolicy allows for the specification of dynamically generated CORS headers.¶
Property: allow-origin¶
MI.NegativeCachePolicy is a new GenericMetadata object that allows for 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 uCDN for a short period of time to prevent an overwhelmed origin service from being flooded with requests¶
Property: error-codes¶
Property: cache-policy¶
MI.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 only applies to the current request. In addition, any content previously cached (by client requests that do not set CacheBypassPolicy) is not evicted.¶
Property: error-codes¶
MI.OcnSelection is a new GenericMetadata object that allows the uCDN to indicate to the dCDN a preference in terms of OCN selection.¶
Property: ocn-delivery¶
An OcnDelivery object contains the following properties:¶
Property: ocn-medium¶
Property: ocn-transport¶
Property: ocn-type¶
Property: ocn-selection¶
MI.PrivateFeatureList is a new GenericMetadata configuration object as a base generic object that permits the control of private features. Note that the private features exposed by the dCDN can be advertised through a dedicated FCI object.¶
Property: features¶
A ProcessingStages object is a type of GenericMetadata that describes the matching rules, metadata, and transformations to be applied at specific stages in the request processing pipeline.¶
It is typical in CDN configurations to define matching rules and metadata that are to be applied at specific stages in the request processing pipeline. For example, it may be required to append a host header prior to forwarding a request to an origin, or modify the response returned from an origin prior to storing in the cache. The following four processing stages are defined:¶
+-------+ +---------------+ +--------+
| +--->|A B+--->| |
| | | | | uCDN |
| UA | | dCDN | | |
| | | | | Source |
| |<---+D C|<---+ |
+-------+ +---------------+ +--------+
Each of the four processing stages is represented by an array of StageRules objects, with each StageRules object defining match criteria along with metadata that should be applied if the match applies to true. It should be noted that all of the StageRules objects in the array are evaluated and processed in order. A possible future extension to this processing model could allow for an if-else structure, where processing for a stage is halted upon matching of a StageRule match expression.¶
+----------------+
|ProcessingStages|
+----------------+
(*)
|
+----------------+-------+---------+----------------+
| | | |
v v v v
+-------------+ +-------------+ +--------------+ +--------------+
|ClientRequest| |OriginRequest| |OriginResponse| |ClientResponse|
+-------------+ +-------------+ +--------------+ +--------------+
(*) (*) (*) (*)
| | | |
+---------------+----------------+----------------+
|
| +---------------+
| +-------->|ExpressionMatch|
| | +---------------+
| |
| | *****************
| (*) +--->*GenericMetadata*
| +----------+ +-------------+ | * Objects *
+--->+StageRules+--->|StageMetadata+(*)-+ *****************
+----------+ +-------------+
(*) (*)
| |
+-------+ +-----------+
| |
v v
+----------------+ +-----------------+
|RequestTransform|(*)-+ +-(*)|ResponseTransform|
+----------------+ | | +-----------------+
(*) | |
| | |
| v v
| +---------------+
| |HeaderTransform|(*)-+
| +---------------+ |
| |
v |
+-----------------+ |
|SyntheticResponse|(*)--+ v
+-----------------+ | +----------+
+----->|HTTPHeader|
+----------+
Each of the four processing stages is represented by an array of StageRules objects, with each StageRules object defining criteria along with metadata that should be applied if the match applies to True. It should be noted that the StageRules objects in the array are evaluated and processed in order. A possible future extension to this processing model could allow for an if-else structure, where processing for a stage is halted upon the first match of a StageRules expression.¶
Property: client-request¶
Property: origin-request¶
Property: origin-response¶
Property: client-response¶
A StageRules object is used within the context of ProcessingStages to define elements in a list of match rules and stage-specific metadata and transformations that should be applied conditionally on a rich expression match.¶
Property: match¶
Property: stage-metadata¶
CDN and open caching systems often require a rich set of matching rules, with full regular expressions and Boolean combinations of matching parameters for host, path, and header elements of a request. In typical CDN implementations, this capability is provided by a rich expression language that can be embedded in the metadata configurations¶
The ExpressionMatch object contains the rich expression that must evaluate to True for the StageMetadata to be applied for the specific StageRules. Defining expressions as stand-alone objects allows for sets of reusable match expressions to be reused via metadata reference linking.¶
Property: expression¶
The StageMetadata object contains GenericMetadata and HTTP request/response transformations that should be applied for a StageRules match. The following table defines the processing stages where request and response transformations are possible:¶
| Stage | request-transform | response-transform |
|---|---|---|
| clientRequest | Yes | Yes |
| originRequest | Yes | Yes |
| originResponse | Yes | No |
| clientResponse | Yes | No |
Note that for the stages where both request and response transformations are allowed, it is possible to specify both. This may be the case if, for example, the request URI needs alteration for cache-key generation and the response headers need to be manipulated.¶
Property: generic-metadata¶
Property: request-transform¶
Property: response-transform¶
The RequestTransform object contains metadata for transforming the HTTP request for a specific StageRules object. The transformation can be the modification of any request header and/or the modification of the URI. Modifications are applied such that downstream processing stages receive the modified HTTP request as their input.¶
The ResponseTransform object contains metadata for transforming the HTTP response for a StageRules match. The transformation can be the modification of any response header, HTTP response status code, or the generation of a synthetic response. Modifications are applied such that downstream processing stages receive the modified HTTP response as their input.¶
Property: headers¶
Property: response-status¶
Property: status-is-expression¶
Property: synthetic¶
It is quite common in CDN configurations to specify a synthetic response be generated based on inspection of aspects of the original request or the origin response.¶
The SyntheticResponse object allows for the specification of a synthetic response to be generated in response to the HTTP request being processed. The synthetic response can contain a set of response headers, a status code, and a response body, and is a complete replacement for any HTTP response elements generated in an earlier processing stage.¶
A dynamically generated Content-Length HTTP response header is generated based on the length of the generated response body.¶
Property: headers¶
Property: response-status¶
Property: status-is-expression¶
Property: body¶
Property: body-is-expression¶
In processing HTTP requests, it is often required to modify HTTP request or response headers at one of the processing stages, requiring CDNi metadata to have the capability to update any field in an HTTP request or response header. It should be noted that certain HTTP headers (such as Set-Cookie) have multiple occurrences in a request or response, thereby requiring that we allow for add and replace designations for header modification.¶
The HeaderTransform object specifies how HTTP headers should be added, replaced, or deleted from HTTP requests and responses.¶
Property: add¶
Property: replace¶
Property: delete¶
MI.RequestedCapacityLimits is a new GenericMetadata object that allows the uCDN to communicate to the dCDN a desired change in the advertised traffic delegation limits for a given host and footprint.¶
Property: requested-limits¶
RequestedCapacityLimit objects contain the following properties:¶
Property: limit-type¶
Property: limit-value¶
Property: footprints¶
MI.RequestRouting is a new GenericMetadata object that allows the uCDN to force the dCDN request routing mode(s) to be applied when working in iterative redirection mode. The list of redirection modes supported by the dCDN is advertised through the FCI.RedirectionMode object. See Section 5.5 of [RFC8006]. The list of request routing modes supported by the dCDN is advertised through the FCI.RequestRouting object (Section 2.12)¶
Property: request-routing-modes¶
CDN configurations typically have multiple layers of identifiers that group configurations by customer account to facilitate logging, billing, and support operations. The metadata model sis extended to allow for the association service identifier metadata to a host or path match and to allow for these IDs to be dynamically generated via an expression language. For example, it may be necessary to extract a portion of the Request URI path to derive a service identifier (e.g.: /news/* maps to one serviceID and /movies/* maps to a different serviceID)¶
A MI.ServiceIDs is a new GenericMetadata object that allows for the specification of two tiers of CDN-specific identifiers and names. The interpretation of these identifiers is implementation specific.¶
Property: service-id¶
Property: service-id-is-expression¶
Property: service-name¶
Property: property-id¶
Property: property-id-is-expression¶
Property: property-name¶
MI.SourceMetadataExtended is an alternative to the CDNi standard MI.SourceMetadata object (See Section 4.2.1 of [RFC8006]), which adds a property to specify load balancing across multiple sources, as well as a SourceExtended sub-object with additional attributes to the CDNi standard Source object (See Section 4.2.1.1 of [RFC8006]). While both SourceMetadataExtended and SourceMetadata can be provided for backward compatibility, a dCDN that advertises capability for SourceMetadataExtended will ignore SourceMetadata if both are provided for a given host or path match.¶
SourceExtended is an alternative to the CDNi standard Source (Section 4.2.1.1 of [RFC8006]) object with additional metadata. Open Caching use cases requires additional capabilities not covered in [RFC8006] as:¶
It inherits all the attributes of the Source object (acquistion-auth, endpoints, and protocol), with the following additions:¶
Property: origin-host¶
Property: webroot¶
Property: follow-redirects¶
Property: timeout-ms¶
Property: failover-errors¶
The LoadBalanceMetadata object defines how content acquisition requests are distributed over the SourceExtended objects listed in the SourceMetadataExtended object.¶
It permits the following capabilities:¶
Parameters for LoadBalanceMetadata are:¶
Property: balance-algorithm¶
Description: Specifies the algorithm to be used when distributing content acquisition requests over the sources in a SourceMetadataExtended object. The available algorithms are random content-hash and ip-hash¶
Property: balance-weights¶
Property: balance-path-pattern¶
MI.StaleContentCachePolicy is a new GenericMetadata object that allows the uCDN to specify the policy 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.¶
Property: stale-while-revalidating¶
Property: stale-if-error¶
Property: failed-refresh-ttl¶
Content delivery networks often apply different infrastructure, network routes, and internal metadata for different types of traffic. Knowing those differences, a dCDN provider can implement specific strategies that will maximize performance and thereby provide more available capacity to the upstream provider. it should be noted that the dCDNs handling of the traffic types is implementation-specific and not prescribed here.¶
TrafficType metadata defines a set of descriptors that characterize either the type or usage of the traffic, enabling dCDNs to apply any internal configuration rules without exposing an unnecessary amount of internal details.¶
Section 5 of [RFC8008] describes the FCI Capability Advertisement Object, which includes a CDNI Capability Object as well as the capability object type (a CDNI Payload Type). The section also defines the Capability Objects per such type. Below we define additional Capability Objects.¶
In most cases, the presence or absence of a GenericMetadata object name in FCI.Metadata (as described above), is sufficient to convey support for a capability. There are cases, however, where more fine-grained capabilities declarations are required. Specifically, a dCDN may support some, but not all, of the capabilities specified by one of the new GenericMetadata objects. In these cases, new FCI objects are created to allow a dCDN to express these fine-grained capabilities.¶
Note: In the following sections, the term "mandatory-to-specify" is used to convey which properties MUST be included when serializing a given capability object. When mandatory-to-specify is defined as "Yes" for an individual property, it means that if the object containing that property is included in an FCI message, then the mandatory-to-specify property MUST also be included.¶
This object is used to to indicate the support of authentication methods to be used for content acquisition (while interacting with an origin server) and authorization methods to be used for content delivery.¶
This documents defines two new authentication methods (See Section 2.1), while there is one other authorization method under specification in CDNI called URI signing [URI.signing]¶
Property: authe-types¶
Property: autho-types¶
This object is used to signal the set of features that are supported in relation with the ProcessingStages (Section 2.10) configuration object. Those optional features depend on the CDNI-MEL language (Section 4) support.¶
Property: features¶
This object is used to signal the supported features related to the SourceMetadataExtended configuration object.¶
Property: load-balance¶
This object is used by the dCDN to signal/announce the supported request routing modes. This can be optionally used by the uCDN to further select a subset of those modes when operating one of the iterative delegation modes. See Section 2.12¶
Property: request-routing-modes¶
This object is used by the dCDN to signal/announce the list of supported private features. See Section 2.9¶
This object is used by the dCDN to signal/announce the supported OCN types and/or their transport arrangement and/or medium supported by OCNs.¶
Property: ocn-delivery-list¶
Property: ocn-type-list¶
The CDNI Metadata Expression Language provides a syntax with a rich set of variables, operators, and built-in functions to facilitate use cases within the extended CDNi metadata model.¶
Expressions can evaluate to a Boolean, string, or integer, depending on the use case:¶
| Usage | Description | Evaluation Results |
|---|---|---|
| ExpressionMatch.expression | Dynamically determines if StageMetadata should be applied at a specific StageRules. | Boolean. Expressions that do not evaluate to True or False shall be considered as False. |
| RequestTransform.uri | Rewrites request URI that will be presented to all downstream stages. | String |
| ResponseTransform.response-status | Dynamically sets a response status code to replace the status-code returned by the origin. | Integer (HTTP status code) |
| SyntheticResponse.response-status | Dynamically sets a response status code for a synthetically constructed response. | Integer (HTTP status code) |
| SyntheticResponse.body | Dynamically constructs a response body. | String |
| HTTPHeader.value | Dynamically constructs a header value. | String |
| ComputedCacheKey.expression | Dynamically constructs a cache key. | String |
| ServiceIDs.properry-id,ServiceIDs.service-id | Dynamically constructs service and property identifiers. | String |
| Variable | Meaning |
|---|---|
| req.h.<name> | Request header <name> |
| req.uri | Request URI (includes query string and fragment identifier, if any) |
| req.uri.path | Request URI path |
| req.uri.pathquery | Request path and query string |
| req.uri.query | Request query string |
| req.uri.query.<key> | Request query string value associated with <key> |
| req.method | Request HTTP method (GET, POST, others) |
| resp.h.<name> | Response header <name> |
| resp.status | Response status code |
| Operator | Type | Result Type | Meaning |
|---|---|---|---|
| == | infix | Boolean | Equality test |
| != | infix | Boolean | Inequality test |
| ! | infix | Boolean | Logical NOT operator |
| > | infix | Boolean | Greater than test |
| < | infix | Boolean | Less than test |
| >= | infix | Boolean | Greater than or equal test |
| <= | infix | Boolean | Less than or equal |
| *= | infix | Boolean | Glob style match |
| ~= | infix | Boolean | Regular expression match (see https://www.pcre.org/ for details on PCRE RegEx matching) |
| ipmatch | infix | Boolean | Match against IP address or CIDR (IPv4 and IPv6) |
| + | infix | Numeric | Addition |
| - | infix | Numeric | Subtraction |
| * | infix | Numeric | Multiplication |
| / | infix | Numeric | Division |
| % | infix | Unsigned or Integer | Modulus |
| . | infix | String | Concatenation |
| ? : | ternary | * | Conditional operator: <e> ? <v1> : <v2> Evaluates <v1> if <e> is true, <v2> otherwise. |
| ( ) | grouping | Used to override precedence and for function calls. |
| Keyword | Meaning |
|---|---|
| and | Logical AND |
| or | Logical OR |
| not | Logical NOT (see also the ! operator) |
| nil | No value (distinct from empty value) |
| true | Boolean constant: true |
| false | Boolean constant: false |
| Function | Action | Argument(s) | Returns |
|---|---|---|---|
| integer(e) | Converts expression to integer. | 1 | integer |
| real(e) | Converts expression to real. | 1 | real |
| string(e) | Converts expression to string. | 1 | string |
| boolean(e) | Converts expression to Boolean. | 1 | Boolean |
| Function | Action | Argument(s) | Returns |
|---|---|---|---|
| upper(e) | Converts a string to uppercase. Useful for case-insensitive comparisons. | 1 | string |
| lower(e) | Converts a string to lowercase. Useful for case-insensitive comparisons. | 1 | string |
| Function | Action | Argument(s) | Returns |
|---|---|---|---|
| match(string Input, string Match) | Regular expression Match is applied to Input and the matching element (if any) is returned. Empty string is returned if there is no match. See https://www.pcre.org/ for details on PCRE RegEx matching. | 2 | string |
| match_replace(string Input, string Match, string Replace) | Regular expression Match is applied to Input arg and replaced with the Replace arg upon successful match. Returns updated (replaced) version of Input. | 3 | string |
| add_query(string Input, string q, string v) | Add query string element q with value v to the Input string. If v is nil, then just add the query string element q. The query element q and value v must conform to the format defined in: https://datatracker.ietf.org/doc/html/rfc3986 | 2 | string |
| remove_query(string Input, string q) | Remove (all occurrences of) query string element q from the Input string. | 2 | string |
| path_element(string Input, integer n) | Return the path element n from Input. -1 returns the last element. | 2 | string |
| path_element(string Input, integer n, integer m) | Return the path elements from position n to m. | 3 | string |
To ensure reliable service, all CDNI Metadata configurations MUST be validated for syntax errors before they are ingested into a dCDN. That is, existing configurations should be kept as the live running configuration until the new configuration has passed validation. If errors are detected in a new configuration, the configuration MUST be rejected. A HTTP 500 Internal Server Error should be returned with a message that indicates the source of the error (line number, and configuration element that caused the error).¶
Examples of compile-time errors:¶
If a runtime error is detected when processing a request, the request should be terminated, and a HTTP 500 'Internal Server Error' returned to the caller. To avoid security leaks, sensitive information MUST be removed from the error message before it is returned to an external client. In addition to returning the HTTP 500 error, the dCDN SHOULD log additional diagnostics information to assist in troubleshooting.¶
Examples of runtime errors:¶
Sets the MI.ComputedCacheKey to the value of the X-Cache-Key header from the client request.¶
{
"generic-metadata-type": "MI.ComputedCacheKey",
"generic-metadata-value": {
"expression": "$req.h.x-cache-key"
}
}
¶
Sets the MI.ComputedCacheKey to the lowercase version of the URI.¶
{
"generic-metadata-type": "MI.ComputedCacheKey",
"generic-metadata-value": {
"expression": "$lower(req.uri)"
}
}
¶
ExpressionMatch where the expression is true if the user-agent (glob) matches *Safari* and the referrer equals www.example.com.¶
{
"expression": "req.h.user-agent *= '*Safari*'
and req.h.referrer == 'www.example.com'"
}
¶
Adds X-custom-response-header with a value equal to the value of user-agent - host header.¶
{
"response-transform": {
"headers": {
"add": [
{
"name": "X-custom-response-header",
"value": "$req.h.user-agent - $req.h.host",
"value-is-expression": true
}
],
"response-status": "403"
}
}
}
¶
Adds a Set-Cookie header with a dynamically computed cookie value (concatenating user agent and host name) and forces a 403 response.¶
{
"response-transform":{
"headers":{
"add":[
{
"name":"Set-Cookie",
"value":"$req.h.user-agent - $req.h.host",
"value-is-expression":true
}
]
}
}
}
¶
Extracts the first path element from the URI. For example, if the URI = /789/second/third/test.txt, property-id is set to the first-path (789).¶
{
"generic-metadata-type":"MI.ServiceIDs",
"generic-metadata-value":{
"service-id":"12345",
"service-name":"My Streaming Service",
"property-id":"$path_element(req.uri, 1)",
"property-id-is-expression":true
}
}
¶
TBD. Two new auth-types will be introduced for use with SourceMetadataExtended: AWSv4Auth and HeaderAuth¶
This specification is in accordance with the CDNI Request Routing: Footprint and Capabilities Semantics. As such, it is subject to the security and privacy considerations as defined in Section 8 of [RFC8006] and in Section 7 of [RFC8008] respectively.¶
MORE - TBD¶
The authors would like to express their gratitude to the members of the Streaming Video Alliance Open Caching Working Group for their guidance / contribution / reviews ...)¶