| Network Working Group | O. Finkelman |
| Internet-Draft | Qwilt |
| Intended status: Standards Track | S. Mishra |
| Expires: December 16, 2018 | Verizon |
| June 14, 2018 |
CDNI Triggers Interface SVA Extensions
draft-finkelman-cdni-triggers-sva-extensions-00
The Open Caching working group of the Streaming Video Alliance is focused on the delegation of video delivery request from commercial CDNs to a caching layer at the ISP. In that aspect, Open Caching 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 key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
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 December 16, 2018.
Copyright (c) 2018 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.
This document defines the objects and extensions needed for Open Caching content management operations. For that purpose it extends CDNI Control Interface/Triggers [RFC8007]. The basic operations are the ones defined in the RFC (i.e. purge, invalidate, pre-position). For consistency, this document follows the CDNI notation of uCDN (the commercial CDN) and dCDN (the ISP caching layer). When using the term CP in this document we refer to a video content provider.
The CDNI metadata interface is described in [RFC8006].
The CDNI footprint and capability interface is described in [RFC8008].
The CDNI control interface / triggers is described in [RFC8007].
This document reuses the terminology defined in [RFC6707], [RFC8006], [RFC8007], and [RFC8008].
Additionally, the following terms are used throughout this document and are defined as follows:
This document defines extensions for the CDNI Control Interface / Triggers [RFC8007] and defines FCI objects as per the CDNI Footprint and Capabilities Interface [RFC8008].
This document specifies version 2 of the CI/T objects in order to support version 2 of the Trigger Specification as required below in Section 2.1.2.
This document specifies version 2 of the Trigger Specification which is an enhancement of the Trigger Specification that includes all properties as defined in section 5.2.1 of [RFC8007] as well as the additional properties required by the use cases listed below in Section 2.1.3.
The trigger specification as defined in section 5.2.1 of [RFC8007] provides means to select content objects by matching a full content URL or patterns with wildcards. The Open Caching specifications requires two additional selection options.
The CDNI Control Interface / Triggers [RFC8007] defines a set of objects used by the trigger commands. These objects cover the basic trigger functionality. The specification of the Open Caching architecture requires additional properties to allow a more granular trigger execution operation. In this document we define a mechanism for a generic trigger extension object wrapper for managing individual CDNI trigger extensions in an opaque manner, as well as an initial set of trigger extension objects.
This document also registers CDNI Payload Types [RFC7736] under the namespace CIT for the initial set of trigger extension types:
Example use cases
Extending the trigger mechanism with optional properties requires the ability for the dCDN to advertise which optional properties it supports.
The CDNI Footprint and Capabilities Interface [RFC8008] enables the dCDN to advertise the capabilities it supports across different footprints. This document introduces FCI objects to support the advertisement of these optional properties.
Example use cases
Version 2 of the CI/T interface is an extension of the original interface as defined in section 5 of [RFC8007]. This sections defines version 2 of the CI/T objects and their properties.
Version 2 of the CI/T interface requires the support of the following objects:
Usage example of version 2 of trigger command
POST /triggers HTTP/1.1
User-Agent: example-user-agent/0.1
Host: dcdn.example.com
Accept: */*
Content-Type: application/cdni; ptype=ci-trigger-command.v2
{
"trigger.v2": { <properties of a trigger.v2 object> },
"cdn-path": [ "AS64496:1" ]
}
Version 2 of the Trigger Object Specification adds the following properties on top of the existing properties of the trigger specification defined in section 5.2.1 of [RFC8007].
Example of an invalidation trigger.v2 with a list of regex objects, a list of playlist objects, and extensions:.
{
"trigger.v2": {
"type": "invalidate",
"content.regexs": [ <list of RegexMatch objects> ],
"content.playlists": [ <list of Playlist objects> ],
"extensions": [ <list of GenericTriggerExtension objects ]
},
"cdn-path": [ "AS64496:1" ]
}
A RegexMatch consists of a regular expression string a URI is matched against, and flags describing the type of match. It is encoded as a JSON object with following properties:
Example of a case sensitive, no query parameters, regex match against:
"^(https:\/\/video\.example\.com)\/([a-z])\/movie1\/([1-7])\/*(index.m3u8|\d{3}.ts)$".
This regex matches URLs of domain video.example.com where the path structure is /(single lower case letter)/(name-of-tile]/(single digit between 1 to 7)/(index.m3u8 or a 3 digit number with ts extension). For example: https://video.example.com/d/movie1/5/index.m3u8 or https://video.example.com/k/movie1/4/013.ts.
{
"regex": "^(https:\\/\\/video\\.example\\.com)\\/([a-z])\\/movie1\
\/([1-7])\\/*(index.m3u8|\\d{3}.ts)$",
"case-sensitive": true,
"match-query-string": false
}
A Playlist consists of a full URL and an ABR protocol identifier. An implementation that supports a specific playlist ABR protocol MUST be able to parse playlist files of that protocol type and extract, possibly recursively, the URLs to all media objects and/or sub playlist files, and apply the trigger on each one of them separately.
Playlist is encoded as a JSON object with following properties:
Example of a HLS playlist:
{
"playlist": "https://www.example.com/hls/title/index.m3u8",
"abr-protocol": "hls"
}
ABR Protocol objects are used to specify registered type of ABR protocol (see Section 6.2) used for protocol related operations like pre-position according to playlist.
Type: JSON string
Example:
"dash"
A "trigger.v2" object, as defined in Section 3.2 includes an optional array of trigger extension objects. A trigger extension contain properties that are used as directives for dCDN when executing the trigger command -- for example, location policies, time policies and so on. Each such CDNI Trigger extension is a specialization of a CDNI GenericTriggerExtension object. The GenericTriggerExtension object abstracts the basic information required for trigger distribution from the specifics of any given property (i.e., property semantics, enforcement options, etc.). All trigger extensions are optional, and it is thus the responsibility of the extension specification to define a consistent default behavior for the case the extension is not present.
The trigger enforcement options concept is in accordance with the metadata enforcement options as defined in section 3.2 of [RFC8006].
The GenericTriggerExtension object defines the properties contained within it as well as whether or not the properties are "mandatory-to-enforce". If the dCDN does not understand or support a mandatory-to-enforce property, the dCDN MUST NOT execute the trigger command. If the extension is not mandatory-to-enforce, then that GenericTriggerExtension object can be safely ignored and the trigger command can be processed in accordance with the rest of the CDNI Trigger spec.
Although a CDN MUST NOT execute a trigger command if a mandatory-to-enforce extension cannot be enforced, it could still be safe to redistribute that trigger (the "safe-to-redistribute" property) to another CDN without modification. For example, in the cascaded CDN case, a transit CDN (tCDN) could convey mandatory-to-enforce trigger extension to a dCDN. For a trigger extension that does not require customization or translation (i.e., trigger extension that is safe-to-redistribute), the data representation received off the wire MAY be stored and redistributed without being understood or supported by the tCDN. However, for trigger extension that requires translation, transparent redistribution of the uCDN trigger values might not be appropriate. Certain triggers extensions can be safely, though perhaps not optimally, redistributed unmodified. For example, pre-position command might be executed in suboptimal times for some geographies if transparently redistributed, but it might still work.
Redistribution safety MUST be specified for each GenericTriggerExtension property. If a CDN does not understand or support a given GenericTriggerExtension property that is not safe-to-redistribute, the CDN MUST set the "incomprehensible" flag to true for that GenericTriggerExtension object before redistributing it. The "incomprehensible" flag signals to a dCDN that trigger metadata was not properly transformed by the tCDN. A CDN MUST NOT attempt to execute a trigger that has been marked as "incomprehensible" by a uCDN.
tCDNs MUST NOT change the value of mandatory-to-enforce or safe-to-redistribute when propagating a trigger to a dCDN. Although a tCDN can set the value of "incomprehensible" to true, a tCDN MUST NOT change the value of "incomprehensible" from true to false.
Table 1 describes the action to be taken by a tCDN for the different combinations of mandatory-to-enforce ("MtE") and safe-to-redistribute ("StR") properties when the tCDN either does or does not understand the trigger extension object in question:
| MtE | StR | Extension object understood by tCDN | Trigger action |
|---|---|---|---|
| False | True | True | Can execute and redistribute. |
| False | True | False | Can execute and redistribute. |
| False | False | False | Can execute. MUST set "incomprehensible" to true when redistributing. |
| False | False | True | Can execute. Can redistribute after transforming the trigger extension (if the CDN knows how to do so safely); otherwise, MUST set "incomprehensible" to true when redistributing. |
| True | True | True | Can execute and redistribute. |
| True | True | False | MUST NOT execute but can redistribute.. |
| True | False | True | Can execute. Can redistribute after transforming the trigger extension (if the CDN knows how to do so safely); otherwise, MUST set "incomprehensible" to true when redistributing. |
| True | False | False | MUST NOT serve. MUST set "incomprehensible" to true when redistributing. |
Table 2 describes the action to be taken by a tCDN for the different combinations of mandatory-to-enforce and "incomprehensible" ("Incomp") properties, when the dCDN either does or does not understand the trigger extension object in question:
| MtE | Incomp | Extension object understood by dCDN | Trigger action |
|---|---|---|---|
| False | False | True | Can execute. |
| False | True | True | Can execute but MUST NOT interpret/apply any trigger extension marked as "incomprehensible". |
| False | False | False | Can execute. |
| False | True | False | Can execute but MUST NOT interpret/apply any trigger extension marked as "incomprehensible". |
| True | False | True | Can execute. |
| True | True | True | MUST NOT execute. |
| True | False | False | MUST NOT execute. |
| True | True | False | MUST NOT execute. |
A GenericTriggerExtension object is a wrapper for managing individual CDNI Trigger extensions in an opaque manner.
Example of a GenericTriggerExtension containing a specific trigger extension object:
{
"generic-trigger-extension-type":
<Type of this trigger extension object>,
"generic-trigger-extension-value":
{
<properties of this trigger extension object>
},
"mandatory-to-enforce": true,
"safe-to-redistribute": true,
"incomprehensible": false
}
The objects defined below are intended to be used in the GenericTriggerExtension object's generic-trigger-extension-value field as defined in section Section 3.6.2, and their generic-trigger-extension-type property MUST be set to the appropriate CDNI Payload Type as defined in Section 6.1 .
A content operation may be relevant for a specific geographical region, or need to be excluded from a specific region. In this case, the trigger should be applied only to parts of the network that are included or not excluded by the location policy. Note that the restrictions here are on the cache location rather than client location.
The LocationPolicy object defines which CDN or cache locations the trigger command is relevant for.
Example use cases:
Object specification
If a location policy object is not listed within the trigger command, the default behavior is to execute the trigger in all available caches and locations of the dCDN.
The trigger command is allowed, or denied, for a specific cache location according to the action of the first location whose footprint matches against that cache's location. If two or more footprints overlap, the first footprint that matches against the cache's location determines the action a CDN MUST take. If the "locations" property is an empty list or if none of the listed footprints match the location of a specific cache location, then the result is equivalent to a "deny" action.
The following is an example of pre-position trigger specification with a trigger-extensions array including a location policy that allows the trigger execution in the US but blocks its execution in Canada:
{
"trigger": {
"type": "preposition",
"content.urls": [
"https://www.example.com/a/b/c/1",
"https://www.example.com/a/b/c/2"
],
"extensions": [
{
"generic-trigger-extension-type": "CIT.LocationPolicy",
"generic-trigger-extension-value":
{
"locations": [
{
"action": "allow",
"footprints": [
{
"footprint-type": "countrycode",
"footprint-value": ["us"]
}
]
},
{
"action": "deny",
"footprints": [
{
"footprint-type": "countrycode",
"footprint-value": ["ca"]
}
]
}
]
},
"mandatory-to-enforce": true,
"safe-to-redistribute": true,
"incomprehensible": false
}
]
},
"cdn-path": [ "AS64496:1" ]
}
A uCDN may wish to perform content management operation on the dCDN under a defined schedule. The TimePolicy extensions allows the uCDN to instruct the dCDN to execute the trigger command in a desired time window.
Object specification
If a time policy object is not listed within the trigger command, the default behavior is to execute the trigger in a time frame most suitable to the dCDN taking under consideration other constrains and / or obligations.
Example of trigger specification with a scheduled time window between 09:00 01/01/2000 UTC and 17:00 01/01/2000 UTC:
POST /triggers HTTP/1.1
User-Agent: example-user-agent/0.1
Host: dcdn.example.com
Accept: */*
Content-Type: application/cdni; ptype=ci-trigger-command
Content-Length: 352
{
"trigger": {
"type": "preposition",
"content.urls": [
"https://www.example.com/a/b/c/1",
"https://www.example.com/a/b/c/2"
],
"extensions": [
{
"generic-trigger-extension-type": "CIT.TimePolicy",
"generic-trigger-extension-value":
{
"windows": {
"start": 946717200,
"end": 946746000
}
}
"mandatory-to-enforce": true,
"safe-to-redistribute": true,
"incomprehensible": false
}
],
},
"cdn-path": [ "AS64496:1" ]
}
This section covers the FCI objects required for advertisement of the extensions and properties introduced in this document.
The CI/T versions capability object is used to indicate support for one or more CI/T objects versions. Note that the default version as originally defined in [RFC8007] MUST be implicitly supported regardless of the versions listed in this capability object.
The following shows an example of CI/T Versions Capability object serialization for a dCDN that supports versions 2 and 2.1 of the CI/T interface.
{
"capabilities": [
{
"capability-type": "FCI.TriggerVersion",
"capability-value": {
"versions": [ "2", "2.1" ]
},
"footprints": [
<Footprint objects>
]
}
]
}
The CI/T Playlist Protocol capability object is used to indicate support for one or more AbrProtocols listed in Section 6.2 by the playlists property of the "trigger.v2" object.
The following shows an example of CI/T Playlist Protocol Capability object serialization for a dCDN that supports "hls" and "dash".
{
"capabilities": [
{
"capability-type": "FCI.TriggerPlaylistProtocol",
"capability-value": {
"abr-protocols": ["hls", "dash"]
},
"footprints": [
<Footprint objects>
]
}
]
}
The CI/T Generic Extension capability object is used to indicate support for one or more GenericExtensionObject types.
The following shows an example of CI/T Trigger Extension Capability object serialization for a dCDN that supports the "CIT.LocationPolicy" and the "CIT.TimePolicy" objects.
{
"capabilities": [
{
"capability-type": "FCI.TriggerGenericExtension",
"capability-value": {
"trigger-extension": ["CIT.LocationPolicy", "CIT.TimePolicy"]
},
"footprints": [
<Footprint objects>
]
}
]
}
This document requests the registration of the following CDNI Payload Types under the IANA CDNI Payload Type registry defined in [RFC7736]:
| Payload Type | Specification |
|---|---|
| ci-trigger-command.v2 | RFCthis |
| ci-trigger-status.v2 | RFCthis |
| CIT.LocationPolicy | RFCthis |
| CIT.TimePolicy | RFCthis |
| FCI.TriggerVersion | RFCthis |
| FCI.TriggerPlaylistProtocol | RFCthis |
| FCI.TriggerGenericExtension | RFCthis |
[RFC Editor: Please replace RFCthis with the published RFC number for this document.]
Purpose: The purpose of this payload type is to distinguish version 2 of the CI/T command (and any associated capability advertisement)
Interface: CI/T
Encoding: see Section 4.1
Purpose: The purpose of this payload type is to distinguish version 2 of the CI/T status resource response (and any associated capability advertisement)
Interface: CI/T
Encoding: see Section 4.1
Purpose: The purpose of this Trigger Extension type is to distinguish LocationPolicy CIT Trigger Extension objects.
Interface: CI/T
Encoding: see Section 4.1
Purpose: The purpose of this Trigger Extension type is to distinguish TimePolicy CI/T Trigger Extension objects.
Interface: CI/T
Encoding: see Section 4.2
Purpose: The purpose of this payload type is to distinguish FCI advertisement objects for CI/T Triggers Versions objects
Interface: FCI
Encoding: see Section 5.1.1
Purpose: The purpose of this payload type is to distinguish FCI advertisement objects for CI/T Playlist Protocol objects
Interface: FCI
Encoding: see Section 5.2.1
Purpose: The purpose of this payload type is to distinguish FCI advertisement objects for CI/T Extension objects
Interface: FCI
Encoding: see Section 5.3.1
The IANA is requested to create a new "CDNI CI/T Trigger AbrProtocol Types" subregistry in the "Content Delivery Networks Interconnection (CDNI) Parameters" registry. The "CDNI CI/T Trigger ABR Protocol Types" namespace defines the valid ABR Protocol object values in Section Section 3.5, used by the Playlist object. Additions to the AbrProtocol namespace conform to the "Specification Required" policy as defined in section 4.6 of [RFC8126], where the specification defines the AbrProtocol Type and the protocol to which it is associated. The designated expert will verify that new protocol definitions do not duplicate existing protocol definitions and prevent gratuitous additions to the namespace.
The following table defines the initial AbrProtocol values corresponding to the HLS, MSS, and DASH protocols:
| AbrProtocol Type | Description | Type Specification | Protocol Specification |
|---|---|---|---|
| hls | HTTP Live Streaming | RFCthis | RFC 8216 |
| mss | Microsoft Smooth Streaming | RFCthis | MSS |
| dash | Dynamic Adaptive Streaming over HTTP (MPEG-DASH) | RFCthis | MPEG-DASH |
[RFC Editor: Please replace RFCthis with the published RFC number for this document.]
All security considerations listed in section 8 of [RFC8007] and section 7 of [RFC8008] apply to this document as well.
TBD
The authors would like to thank all members of the SVA's Open Caching Working Group for their contribution in support of this document.
| [MPEG-DASH] | ISO, "Information technology -- Dynamic adaptive streaming over HTTP (DASH) -- Part 1: Media presentation description and segment format", ISO/IEC 23009-1:2014, Edition 2, May 2014. |
| [MSS] | Microsoft, "[MS-SSTR]: Smooth Streaming Protocol", Protocol Revision 8.0, September 2017. |
| [PCRE841] | Hazel, P., "Perl Compatible Regular Expressions", Version 8.41, July 2017. |
| [RFC6707] | Niven-Jenkins, B., Le Faucheur, F. and N. Bitar, "Content Distribution Network Interconnection (CDNI) Problem Statement", RFC 6707, DOI 10.17487/RFC6707, September 2012. |
| [RFC7736] | Ma, K., "Content Delivery Network Interconnection (CDNI) Media Type Registration", RFC 7736, DOI 10.17487/RFC7736, December 2015. |
| [RFC8216] | Pantos, R. and W. May, "HTTP Live Streaming", RFC 8216, DOI 10.17487/RFC8216, August 2017. |