CDNI Metadata Expression Language

7.1. Type Conversions

The following table summarizes the return values of type conversion functions when presented with edge-case input values:¶

7.2. String Conversions

7.3. Convenience Functions

8.1. MI.SetVariable

MI.SetVariable is a GenericMetadata object that allows one to set user-defined variables that can be accessed from MEL. Variables set via this mechanism can be accessed in matching and value construction expressions using a var. prefix before the variable name. Note: Variable names MUST be string literals.¶

Property: variable-name¶

• Description: The name of the variable.¶

• Type: String. Alphanumeric with both uppercase and lowercase characters; the property MUST start with a letter.¶

• Mandatory-to-Specify: Yes¶

Property: variable-value¶

• Description: The string representation of the value to set for the user-defined variable.¶

• Type: String, either the static value or a MEL expression, determined by the value-is-expression property.¶

• Mandatory-to-Specify: Yes¶

Property: value-is-expression¶

• Description: A flag to signal whether the value is a static string literal or a MEL expression that needs to be dynamically evaluated.¶

• Type: Boolean¶

• Mandatory-to-Specify: No. The default is "False", indicating that the value is a string literal and does not need to be evaluated.¶

The following example illustrates the setting of a user-defined variable whose value is a MEL expression suffixed by a static literal string:¶

{
  "generic-metadata-type": "MI.SetVariable",
  "generic-metadata-value": {
    "variable-name": "myvar",
    "variable-value": "req.h.host . 'is my host from player'"
    "value-is-expression": true
  }
}

The following example illustrates the setting of a user-defined variable whose value is another user-defined variable suffixed by a static literal string:¶

{
  "generic-metadata-type": "MI.SetVariable",
  "generic-metadata-value": {
    "variable-name": "myvar1",
    "variable-value": "req.host . 'is my host from player'"
    "value-is-expression": true
  }
}
{
  "generic-metadata-type": "MI.SetVariable",
  "generic-metadata-value": {
    "variable-name": "myvar2",
    "variable-value": "var.myvar1 . 'and forwarded to Origin'"
    "value-is-expression": true
  }
}

9.1. Compile-Time Errors

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. An 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 MEL compile-time errors:¶

• Unknown MEL variable name referenced in an expression¶

• Unknown MEL operator, keyword, or functions referenced in an expression¶

• Incorrect number of arguments used in a MEL expression operator or function¶

• Incorrect type of argument used in a MEL expression operator or function¶

9.2. Runtime Errors

If a runtime error is detected when processing a request, the request SHOULD be terminated, and an 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 diagnostic information to assist in troubleshooting.¶

Examples of runtime errors:¶

• Failure to allocate memory (or other server resources) when evaluating a MEL expression¶

• Incorrect runtime argument type in a MEL expression, such as, trying to convert a non-numeric string to a number¶

10.1. FCI.SupportedMELFeatures

The FCI.SupportedMELFeatures object is contained in FCI Capabilities advertisements and allows a dCDN to advertise the portions of the MEL specification that it supports. If a capabilities advertisement does not contain a FCI.SupportedMELFeatures or a FCI.MetadataExtended object with an embedded FCI.SupportedMELFeatures object, the upstream content delivery network (uCDN) MUST assume that the dCDN has support for the full MEL specification.¶

Property: keywords¶

• Description: A list of supported keywords.¶

• Type: Array¶

• Mandatory-to-Specify: No. If not specified, it is assumed to be empty.¶

• Values: ["and", "or", "not", "nil", "true", "false"]¶

Property: operators¶

• Description: A list of supported operators.¶

• Type: Array¶

• Mandatory-to-Specify: No. If not specified, it is assumed to be empty.¶

• Values: ["==", "!=", "!", ">", "<", ">=", "<=", "*=", "~=", "+", "-", "*", "/", "%", " . ", "()", "?:", "ipmatch"]¶

Property: variables¶

• Description: A list of supported variables.¶

• Type: Array¶

• Mandatory-to-Specify: No. If not specified, it is assumed to be empty.¶

• Values: ["req.h.<name>", "req.uri", "req.uri.path", "req.uri.pathquery", "req.uri.query", "req.uri.query.<key>", "req.uri.querykv.<key>", "req.method", "req.scheme", "resp.h.<name>", "resp.status", "req.clientip", "req.clientport", "var.<user-variable>" ]¶

Property: built-in-functions¶

• Description: A list of supported built-in function names.¶

• Type: Array¶

• Mandatory-to-Specify: No. If not specified, it is assumed to be empty¶

• Values: ["integer", real", "string", "boolean", upper", "lower", "match", "match_replace", "add_query", "remove_query", "path_element", "path_elements", "add_query_multi", "remove_query_multi", "keep_query_multi"]¶

The following example advertises a subset of MEL support:¶

{
"capabilities": [
    {
      "capability-type": "FCI.SupportedMELFeatures",
      "capability-value": {
        "keywords": ["and", "or", "not", "nil", "true", "false"],
        "operators" : ["==", "!=", "!", ">", "<", ">=",
           "<=", "~=", " . ", "()" ],
        "variables": ["req.h.<name>", "req.uri", "req.uri.path" ],
        "built-in-functions": [ "string", "boolean", "upper",
           "lower", "match", "match_replace", "path_element"]
      }
    }
  ]
}

11.1. MI.ComputedCacheKey

The following examples illustrate usage of the Metadata Expression Language to dynamically generate cache keys, as specified by the MI.ComputedCacheKey object in the Cache Control Metadata Specification [SVTA2033]¶

Example setting the cache key to the value of the X-Cache-Key header from the client HTTP request:¶

{
  "generic-metadata-type": "MI.ComputedCacheKey",
  "generic-metadata-value": {
    "expression": "req.h.x-cache-key"
  }
}

Example setting the cache key to the request URI, forced to lower-case:¶

{
  "generic-metadata-type": "MI.ComputedCacheKey",
  "generic-metadata-value": {
    "expression": "lower(req.uri)"
  }
}

11.2. MI.ExpressionMatch

The following example illustrates usage of the Metadata Expression Language to create a match expression, as specified by the Processing Stages Metadata Specification [SVTA2032]¶

In this example, the expression is true if the user-agent (glob) matches '*Safari*' and the referrer equals 'www.x.com'.¶

{
  "generic-metadata-type": "MI.MatchExpression",
  "generic-metadata-value": {
    "expression": "req.h.user-agent *= '*Safari*' and
                   req.h.referer == 'www.x.com'"
  }
}

11.3. MI.ResponseTransform

The following example illustrates usage of the Metadata Expression Language to alter the headers of an HTTP response, as specified by the Processing Stages Metadata Specification [SVTA2032]¶

An HTTP response is transformed by adding a dynamically constructed header with a value that uses the expression language to concatenate the values of the user-agent and host header.¶

{
  "generic-metadata-type": "MI.ResponseTransform",
  "generic-metadata-value": {
    "header-transform": {
      "add": [
        {
          "name": "X-custom-response-header",
          "value": "req.h.user-agent . '-' . req.h.host",
          "value-is-expressions": true
        }
      ]
    }
  }
}

13.1. CDNI Payload Types

This document requests the registration of the following entries under the "CDNI Payload Types" registry hosted by IANA:¶