Request Routing Redirection interface for CDN Interconnection

This document defines a simple interface for the Redirection interface based on HTTP , where the attributes of a User Agent's requests are encapsulated along with any other data that can aid the dCDN in processing the requests. The RI response encapsulates the attributes of the RT(s) that the uCDN should return to the User Agent (if it decides to utilize the dCDN for delivery) along with the policy for how the response can be reused. The examples of RI requests and responses below do not contain a complete set of HTTP headers for brevity; only the pertinent HTTP headers are shown. The RI between the uCDN and dCDN uses the same HTTP interface to encapsulate the attributes of both DNS and HTTP requests received from User Agents, although the contents of the RI requests/responses contain data specific to either DNS or HTTP redirection. This approach has been chosen because it enables CDN operators to only have to deploy a single interface for the RI between their CDNs, regardless of the User Agent redirection method. In this way, from an operational point of view there is only one interface to monitor, manage, develop troubleshooting tools for, etc. In addition, having a single RI where the attributes of the User Agent's DNS or HTTP request are encapsulated along with the other data required for the dCDN to make a request routing decision, avoids having to try to encapsulate or proxy DNS/HTTP/RTMP/etc requests and find ways to somehow embed the additional CDNI Request Routing Redirection interface properties/data within those End User DNS/HTTP/RTMP/etc requests. Finally, the RI is easily extendable to support other User Agent request redirection methods (e.g., RTMP 302 redirection) by defining additional protocol specific keys for RI requests and responses along with a specification how to process them. The generic Recursive Request Redirection message flow between Request Routing systems in a pair of interconnected CDNs is as follows:

| (1) | | | | |HTTP POST to CDN B's RI | | |URI encapsulating UA | | |request attributes | | |<------------------------| (2) | | | | |HTTP Response with body | | |containing RT attributes | | |of the protocol specific | | |response to return to UA | | |------------------------>| (3) | | | | Protocol specific response (redirection)| |<--------------------------------------------------| (4) | | |]]> The User Agent sends its (DNS or HTTP) request to CDN A. The Request Routing System of CDN A processes the request and, through local policy, recognizes that the request is best served by another CDN, specifically CDN B (or that CDN B may be one of a number of candidate dCDNs it could use). The Request Routing System of CDN A sends an HTTP POST to CDN B's RI URI containing the attributes of the User Agent's request. The Request Routing System of CDN B processes the RI request and assuming the request is well formed, responds with an HTTP "200" response with a message body containing the RT(s) to return to the User Agent as well as parameters that indicate the properties of the response (cacheability and scope). The Request Routing System of CDN A sends a protocol specific response (containing the returned attributes) to the User Agent, so that the User Agent's request will be redirected to the RT(s) returned by CDN B.

The information passed in RI requests splits into two basic categories: The attributes of the User Agent's request to the uCDN. Properties/parameters that the uCDN can use to control the dCDN’s response or that can help the dCDN make its decision. Generally, dCDNs can provide better routing decisions given additional information about the content request, e.g., the URI of the requested content or the User Agent's IP address or subnet. The set of information required to base a routing decision on can be highly dependent on the type of content delivered. A uCDN SHOULD only include information that is absolutely necessary for delivering that type of content. Cookies in particular are particularly sensitive from a security/privacy point of view and in general SHOULD NOT be conveyed in the RI Requests to the dCDN. The set of information necessary to be conveyed for a particular type of request is expected to be conveyed out of band between the uCDN and dCDN. See for more detail on the privacy aspects of using RI Requests to convey information about UA requests. In order for the dCDN to determine whether it is capable of delivering any requested content, it requires CDNI metadata related to the content the User Agent is requesting. That metadata will describe the content and any policies associated with it. It is expected that the RI request contains sufficient information for the Request Router in the dCDN to be able to retrieve the required CDNI Metadata via the CDNI Metadata interface. The information passed in RI responses splits into two basic categories: The attributes of the RT to return to the User Agent in the DNS response or HTTP response. Parameters/policies that indicate the properties of the response, such as, whether it is cacheable, the scope of the response, etc. In addition to details of how to redirect the User Agent, the dCDN may wish to return additional policy information to the uCDN to it with future RI requests. For example, the dCDN may wish to return a policy that expresses “this response can be reused without requiring an RI request for 60 seconds provided the User Agent's IP address is in the range 198.51.100.0 - 198.51.100.255”. These additional policies split into two basic categories: Cacheability information signaled via the HTTP response headers of the RI response (to reduce the number of subsequent RI requests the uCDN needs to make). The scope of a cacheable response signaled in the HTTP response body of the RI response, for example, whether the response applies to a wider range of IP addresses than what was included in the RI request. The cacheability of the response is indicated using the standard HTTP Cache-Control mechanisms.

The body of RI requests and responses is a JSON object that MUST conform to containing a dictionary of key:value pairs. Senders MUST encode all (top level object and sub-object) keys specified in this document in lowercase. Receivers MUST ignore any keys that are unknown or invalid. The following top level keys are defined along with whether they are applicable to RI requests, RI responses or both: Key Request/Response Description dns Both The attributes of the UA's DNS request or the attributes of the RT(s) to return in a DNS response. http Both The attributes of the UA's HTTP request or the attributes of the RT to return in a HTTP response. scope Response The scope of the response (if it is cacheable). For example, whether the response applies to a wider range of IP addresses than what was included in the RI request. error Response Additional details if the response is an error response. cdn-path Both A List of Strings. Contains a list of the CDN Provider IDs of previous CDNs that have participated in the request routing for the associated User Agent request. On RI requests it contains the list of previous CDNs that this RI request has passed through. On RI responses it contains the list of CDNs that were involved in obtaining the final redirection included in the RI response. max-hops Request Integer specifying the maximum number of hops (CDN Provider IDs) this request is allowed to be propagated along. This allows the uCDN to coarsely constrain the latency of the request routing chain. A single request or response MUST contain only one of the dns or http keys. Requests MUST contain a cdn-path key and responses MAY contain a cdn-path key. If the max-hops key is not present then there is no limit on the number of CDN hops that the RI request can be propagated along. If the first uCDN does not wish the RI request to be propagated beyond the dCDN it is making the request to, then the uCDN MUST set max-hops to 1. The cdn-path MAY be reflected back in RI responses, although doing so could expose information to the uCDN that a dCDN may not wish to expose (for example, the existence of business relationships between a dCDN and other CDNs). If the cdn-path is reflected back in the RI response it MUST contain the value of cdn-path received in the associated RI request with the final dCDN's CDN Provider ID appended. Transit CDNs MAY remove the cdn-path from RI responses but MUST NOT modify the cdn-path in other ways. The presence of an error key within a response that also contains either a dns or http key does not automatically indicate that the RI request was unsuccessful as the error key MAY be used for communicating additional (e.g., debugging) information. When a response contains an error key as well as either a dns or http key, the error-code SHOULD be 1xx (e.g., 100). See for more details of encoding error information in RI responses. All implementations that support IPv4 addresses MUST support the encoding specified by the ’IPv4address’ rule in Section 3.2.2 of . Likewise, implementations that support IPv6 addresses MUST support all IPv6 address formats specified in . Server implementations SHOULD use IPv6 address formats specified in .

RI requests MUST use a MIME Media Type of application/cdni as specified in , with the Payload Type (ptype) parameter set to 'redirection-request'. RI responses MUST use a MIME Media Type of application/cdni as specified in , with the Payload Type (ptype) parameter set to 'redirection-response'.

The following sections provide detailed descriptions of the information that should be passed in RI requests and responses for DNS redirection.

For DNS based redirection the uCDN needs to pass the following information to the dCDN in the RI request: The IP address of the DNS resolver that made the DNS request to the uCDN. The type of DNS query made (usually either A or AAAA). The class of DNS query made (usually IN). The fully qualified domain name for which DNS redirection is being requested. The IP address or prefix of the User Agent (if known to the uCDN). The information above is encoded as a set of key:value pairs within the dns dictionary as follows: Key Value Mandatory Description resolver-ip String Yes The IP address of the UA's DNS resolver. qtype String Yes The type of DNS query made by the UA's DNS resolvers in uppercase (A, AAAA, etc.). qclass String Yes The class of DNS query made in uppercase (IN, etc.). qname String Yes The fully qualified domain name being queried. c-subnet String No The IP address (or prefix) of the UA in CIDR format. dns-only Boolean No If True then dCDN MUST only use DNS redirection and MUST include RTs to one or more surrogates in any successful RI response. CDNs MUST include the dns-only property set to True on any cascaded RI requests. Defaults to False. An RI request for DNS-based redirection MUST include a dns dictionary. This dns dictionary MUST contain the following keys: resolver-ip, qtype, qclass, qname and the value of each MUST be the value of the appropriate part of the User Agent's DNS query/request. For internationalized domain names containing non-ASCII characters, the value of the qname field MUST be the ASCII-compatible encoded (ACE) representation (A-label) of the domain name. An example RI request (uCDN->dCDN) for DNS based redirection:

For a successful DNS based redirection, the dCDN needs to return one of the following to the uCDN in the RI response: The IP address(es) of (or the CNAME of) RTs that are dCDN surrogates (if the dCDN is performing DNS based redirection directly to a surrogate); or The IP address(es) of (or the CNAME of) RTs that are Request Routers (if the dCDN will perform request redirection itself). A dCDN MUST NOT return a RT which is a Request Router if the dns-only key is set to True in the RI request. The information above is encoded as a set of key:value pairs within the dns dictionary as follows: Key Value Mandatory Description rcode Integer Yes DNS response code (see ). name String Yes The fully qualified domain name the response relates to. a List of String No Set of IPv4 Addresses of RT(s). aaaa List of String No Set of IPv6 Addresses of RT(s). cname List of String No Set of fully qualified domain names of RT(s). ttl Integer No TTL in seconds of DNS response. Default is 0. A successful RI response for DNS-based redirection MUST include a dns dictionary and MAY include an error dictionary (see ). An unsuccessful RI response for DNS-based redirection MUST include an error dictionary. If a dns dictionary is included in the RI response, it MUST include the rcode and name keys and it MUST include at least one of the following keys: a, aaaa, cname. The dns dictionary MAY include both 'a' and 'aaaa' keys. If the dns dictionary contains a cname key it MUST NOT contain either an a or aaaa key. For internationalized domain names containing non-ASCII characters, the value of the cname field MUST be the ASCII-compatible encoded (ACE) representation (A-label) of the domain name. An example of a successful RI response (dCDN->uCDN) for DNS based redirection with both a and aaaa keys is listed below :

A further example of a successful RI response (dCDN->uCDN) for DNS based redirection is listed below, in this case with a cname key containing the FQDN of the RT.

The following sections provide detailed descriptions of the information that should be passed in RI requests and responses for HTTP redirection. The dictionary keys used in HTTP Redirection requests and responses use the following conventions for their prefixes: c- is prefixed to keys for information related to the Client (User Agent). cs- is prefixed to keys for information passed by the Client (User Agent) to the Server (uCDN). sc- is prefixed to keys for information to be passed by the Server (uCDN) to the Client (User Agent).

For HTTP-based redirection the uCDN needs to pass the following information to the dCDN in the RI request: The IP address of the User Agent. The URI requested by the User Agent. The HTTP method requested by the User Agent The HTTP version number requested by the User Agent. The uCDN may also decide to pass the presence and value of particular HTTP headers included in the User Agent request to the dCDN. The information above is encoded as a set of key:value pairs within the http dictionary as follows: Key Value Mandatory Description c-ip String Yes The IP address of the UA. cs-uri String Yes The Effective Request URI requested by the UA. cs-method String Yes The method part of the request-line as defined in Section 3.1.1 of. cs-version String Yes The HTTP-version part of the request-line as defined in Section 3.1.1 of. cs-(<headername>) String No The field-value of the HTTP header field named <HeaderName> as a string, for example, cs-(cookie) would contain the value of the HTTP Cookie header from the UA request. An RI request for HTTP-based redirection MUST include an http dictionary. This http dictionary MUST contain the following keys: c-ip, cs-method, cs-version and cs-uri and the value of each MUST be the value of the appropriate part of the User Agent's HTTP request. The http dictionary of an RI request MUST contain a maximum of one cs-(<headername>) key for each unique header field-name (HTTP header field). <headername> MUST be identical to the equivalent HTTP header field-name encoded in all lowercase. In the case where the User Agent request includes multiple HTTP header fields with the same field-name, it is RECOMMENDED that the uCDN combines these different HTTP headers into a single value according to Section 3.2.2 of. However, because of the plurality of already defined HTTP header fields, and inconsistency of some of these header fields concerning the combination mechanism defined in RFC 7230, the uCDN MAY have to deviate from using the combination mechanism where appropriate. For example, it might only send the contents of the first occurrence of the HTTP Headers instead. An example RI request (uCDN->dCDN) for HTTP based redirection:

For a successful HTTP based redirection, the dCDN needs to return one of the following to the uCDN in the RI response: A URI pointing to an RT that is the selected dCDN surrogate(s) (if the dCDN is performing HTTP based redirection directly to a surrogate); or A URI pointing to an RT that is a Request Router (if the dCDN will perform request redirection itself). The information above is encoded as a set of key:value pairs within the http dictionary as follows: Key Value Mandatory Description sc-status Integer Yes The status-code part of the status-line as defined in Section 3.1.2 of to return to the UA (usually set to 302). sc-version String Yes The HTTP-version part of the status-line as defined in Section 3.1.2 of to return to the UA. sc-reason String Yes The reason-phrase part of the status-line as defined in Section 3.1.2 of to return to the UA. cs-uri String Yes The URI requested by the UA/client. sc-(location) String Yes The contents of the Location header to return to the UA (i.e., a URI pointing to the RT(s)). sc-(<headername>) String No The field-value of the HTTP header field named <HeaderName> to return to the UA. For example, sc-(expires) would contain the value of the HTTP Expires header. Note: The sc-(location) key in the table above is an example of sc-(<headername>) that has been called out separately as its presence is mandatory in RI responses. A successful RI response for HTTP-based redirection MUST include an http dictionary and MAY include an error dictionary (see ). An unsuccessful RI response for HTTP-based redirection MUST include an error dictionary. If an http dictionary is included in the RI response, it MUST include at least the following keys: sc-status, sc-version, sc-reason, cs-uri and sc-(location). The http dictionary of an RI response MUST contain a maximum of one sc-(<headername>) key for each unique header field-name (HTTP header field). <headername> MUST be identical to the equivalent HTTP header field-name encoded in all lowercase. The uCDN MAY decide to not return, override or alter any or all of the HTTP headers defined by sc-(<headername>) keys before sending the HTTP response to the UA. It should be noted that in some cases, sending the HTTP Headers indicated by the dCDN transparently on to the UA might result in, for the uCDN, undesired behaviour. As an example, the dCDN might include sc-(cache-control), sc-(last-modified) and sc-(expires) keys in the http dictionary, through which the dCDN may try to influence the cacheability of the response by the UA. If the uCDN would pass these HTTP headers on to the UA, this could mean that further requests from the uCDN would go directly to the dCDN, bypassing the uCDN and any logging it may perform on incoming requests. The uCDN is therefore recommended to carefully consider which HTTP headers to pass on, and which to either override or not pass on at all. An example of a successful RI response (dCDN->uCDN) for HTTP based redirection:

RI responses may be cacheable. As long as a cached RI response is not stale according to standard HTTP Cache-Control or other applicable mechanisms, it may be reused by the uCDN in response to User Agent requests without sending another RI request to the dCDN. An RI response MUST NOT be reused unless the request from the User Agent would generate an identical RI request to the dCDN as the one that resulted in the cached RI response (except for the c-ip field provided that the User Agent's c-ip is covered by the scope in the original RI response, as elaborated upon below). Additionally, although RI requests only encode a single User Agent request to be redirected there may be cases where a dCDN wishes to indicate to the uCDN that the RI response can be reused for other User Agent requests without the uCDN having to make another request via the RI. For example, a dCDN may know that it will always select the same Surrogates for a given set of User Agent IP addresses and in order to reduce request volume across the RI or to remove the additional latency associated with an RI request, the dCDN may wish to indicate that set of User Agent IP addresses to the uCDN in the initial RI response. This is achieved by including an optional scope dictionary in the RI response. Scope is encoded as a set of key:value pairs within the scope dictionary as follows: Key Value Mandatory Description iprange List of String No A List of IP subnets in CIDR notation that this RI response can be reused for, provided the RI response is still considered fresh. If a uCDN has multiple cached responses with overlapping scopes and a UA request comes in for which the User Agent's IP matches with the IP subnets in multiple of these cached responses, the uCDN SHOULD use the most recent cached response when determining the approriate RI response to use. The following is an example of a DNS redirection response from that is cacheable by the uCDN for 30 seconds and can be returned to any User Agent with an IPv4 address in 198.51.100.0/24.

Example of HTTP redirection response from that is cacheable by the uCDN for 60 seconds and can be returned to any User Agent with an IPv4 address in 198.51.100.0/24. Note: The response to the UA is only valid for 30 seconds, whereas the uCDN can cache the RI response for 60 seconds.

From a uCDN perspective, there are two types of errors that can be the result of the transmission of an RI request to a dCDN: An HTTP protocol error signaled via an HTTP status code, indicating a problem with the reception or parsing of the RI request or the generation of the RI response by the dCDN, and An RI-level error specified in an RI response message This section deals with the latter type. The former type is outside the scope of this document. There are numerous reasons for a dCDN to be unable to return an affirmative RI response to a uCDN. Reasons may include both dCDN internal issues such as capacity problems, as well as reasons outside the influence of the dCDN, such as a malformed RI request. To aid with diagnosing the cause of errors, RI responses SHOULD include an error dictionary to provide additional information to the uCDN as to the reason/cause of the error. The intention behind the error dictionary is to aid with either manual or automatic diagnosis of issues. The resolution of such issues is outside the scope of this document; this document does not specify any consequent actions a uCDN should take upon receiving a particular error code. Error information (if present) is encoded as a set of key:value pairs within a JSON-encoded error dictionary as follows: Key Value Mandatory Description error-code Integer Yes A three-digit numeric code defined by the server to indicate the error(s) that occurred. reason String No A string providing further information related to the error. The first digit of the error-code defines the class of error. There are 5 classes of error distinguished by the first digit of the error-code: 1xx: Informational (no error): The response should not be considered an error by the uCDN, which may proceed by redirecting the UA according to the values in the RI response. The error code and accompanying description may be used for informational purposes, e.g., for logging. 2xx: Reserved. 3xx: Reserved. 4xx: uCDN error: The dCDN can not or will not process the request due to something that is perceived to be a uCDN error, for example, the RI request could not be parsed succesfully by the dCDN. The last two-digits may be used to more specifically indicate the source of the problem. 5xx: dCDN error: Indicates that the dCDN is aware that it has erred or is incapable of satisfying the RI request for some reason, for example, the dCDN was able to parse the RI request but encountered an error for some reason. Examples include the dCDN not being able to retrieve the associated metadata or the dCDN being out of capacity. The following error codes are defined and maintained by IANA (see ): Error codes with a "Reason" of "<reason>" do not have a defined value for their 'reason'-key. Depending on the error-code semantics, the value of this field may be determined dynamically. Code Reason Description 100 <reason> (see Description) Generic informational error-code meant for carrying a human-readable string 400 <reason> (see Description) Generic error-code for uCDN errors where the dCDN can not or will not process the request due to something that is perceived to be a uCDN error. The reason field may be used to provide more details about the source of the error. 500 <reason> (see Description) Generic error-code for dCDN errors where the dCDN is aware that it has erred or is incapable of satisfying the RI request for some reason. The reason field may be used to provide more details about the source of the error. 501 Unable to retrieve metadata The dCDN is unable to retrieve the metadata associated with the content requested by the UA. This may indicate a configuration error or the content requested by the UA not existing. 502 Loop detected The dCDN detected a redirection loop (see ). 503 Maximum hops exceeded The dCDN detected the maximum number of redirection hops exceeding max-hops (see ). 504 Out of capacity The dCDN does not currently have sufficient capacity to handle the UA request. 505 Delivery protocol not supported The dCDN does not support the (set of) delivery protocols indicated in the CDNI Metadata of the content requested content by the UA. 506 Redirection protocol not supported The dCDN does not support the requested redirection protocol. This error-code is also used when the RI request has the dns-only flag set to True and the dCDN is not support or is not prepared to return a RT of a surrogate directly. The following is an example of an unsuccessful RI response (dCDN->uCDN) for a DNS based User Agent request:

The following is an example of a successful RI response (dCDN->uCDN) for a HTTP based User Agent request containing an error dictionary for informational purposes:

In order to prevent and detect RI request loops, each CDN MUST insert its CDN Provider ID into the cdn-path key of every RI request it originates or cascades. When receiving RI requests a dCDN MUST check the cdn-path and reject any RI requests which already contain the dCDN's Provider ID in the cdn-path. Transit CDNs MUST NOT propagate to any downstream CDNs if the number of CDN Provider IDs in cdn-path (before adding its own Provider ID) is equal to or greater than max-hops. The CDN Provider ID uniquely identifies each CDN provider during the course of request routing redirection. It consists of the characters AS followed by the CDN Provider's AS number, then a colon (':') and an additional qualifier that is used to guarantee uniqueness in case a particular AS has multiple independent CDNs deployed. For example, "AS64496:0". If a dCDN receives an RI request whose cdn-path already contains that dCDN's Provider ID the dCDN MUST send an RI error response which SHOULD include an error code of 502. If a dCDN receives an RI request where the number of CDN Provider IDs in cdn-path is greater than max-hops, the dCDN MUST send an RI error response which SHOULD include an error code of 503. It should be noted that the loop detection & prevention mechanisms described above only cover preventing and detecting loops within the RI itself. Besides loops within the RI itself, there is also the possibility of loops in the data plane, for example, if the IP address(es) or URI(s) returned in RI responses do not resolve directly to a surrogate in the final dCDN there is the possibility that a User Agent may be continuously redirected through a loop of CDNs. The specification of solutions to address data plane request redirection loops between CDNs is outside of the scope of this document.