--- 1/draft-ietf-cdni-triggers-extensions-03.txt 2020-03-21 07:13:32.807704371 -0700 +++ 2/draft-ietf-cdni-triggers-extensions-04.txt 2020-03-21 07:13:32.903706819 -0700 @@ -1,28 +1,29 @@ Network Working Group O. Finkelman Internet-Draft Qwilt Updates: 8007 (if approved) S. Mishra Intended status: Standards Track Verizon -Expires: March 26, 2020 September 23, 2019 +Expires: September 22, 2020 March 21, 2020 CDNI Control Triggers Interface Extensions - draft-ietf-cdni-triggers-extensions-03 + draft-ietf-cdni-triggers-extensions-04 Abstract This document updates RFC 8007 to include generic extensions and more granular content matching options, required by the Open Caching architecture. 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 + commercial Content Delivery Networks (CDNs) to a caching layer at the + ISP. In that aspect, Open Caching is a specific use case of Content + Delivery Networks Interconnection (CDNI), where the commercial CDN is the upstream CDN (uCDN) and the ISP caching layer is the downstream CDN (dCDN). The extensions specified in this document to the CDNI Control Interface / Triggers are derived from requirements of Open Caching but are applicable to CDNI use cases in general. Requirements Language 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 @@ -37,25 +38,25 @@ 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 March 26, 2020. + This Internet-Draft will expire on September 22, 2020. Copyright Notice - Copyright (c) 2019 IETF Trust and the persons identified as the + Copyright (c) 2020 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 @@ -127,24 +128,24 @@ 10.2. Informative References . . . . . . . . . . . . . . . . . 41 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41 1. Introduction This document defines the objects and extensions required for granular content management operations. For that purpose it extends CDNI Control Interface / Triggers [RFC8007] by adding new content selection options to the trigger specification and specifying a generic extension mechanism that enables adding future functions for - controlling the trigger execution. This document also defines and - initial set of extension objects. This document gives examples for - the extensions specified herein, for complete examples of the trigger - interface usage see Section 6 of [RFC8007]. + controlling the trigger execution. This document also defines an + initial set of extension objects and provides examples for the + extensions. For full and complete examples of the trigger interface + usage please see Section 6 of [RFC8007]. 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]. 1.1. Terminology @@ -315,24 +316,24 @@ Section 5.1.1 of [RFC8007]. o Trigger Status Resource v2: A trigger status resource response using the payload type ci-trigger-status.v2. Version 2 MUST only use "trigger.v2" objects as defined in Section 3.3.1, instead of a "trigger" object, as well as "errors.v2" array as defined in Section 3.3.6, instead of a "errors" array. All other properties of the trigger status v2 are as defined in Section 5.1.2 of [RFC8007]. The errors array "errors.v2" is a list of all errors that occurred in any of the downstream CDNs along the execution - path. When a downstream CDN, dCDN-A, propagates a trigger to - another downstream CDN, dCDN-B, it MUST also propagated back all - errors reported by dCDN-B in the trigger status resource and add - them to its own trigger status resource. + path. When a downstream CDN,for example, dCDN-A, propagates a + trigger to another downstream CDN, say dCDN-B, it MUST also + propagate back all errors reported by dCDN-B in the trigger status + resource and add them to its own trigger status resource. o Trigger Collections: The payload type ci-trigger-collection is used with no changes and as defined in 5.1.3 of [RFC8007]. Usage example of version 2 of trigger command REQUEST: POST /triggers HTTP/1.1 User-Agent: example-user-agent/0.1 @@ -410,37 +411,38 @@ extension object. As extension objects are expected to be added to the interface as new requirements comes along, it is expected that in some cases a dCDN may receive a trigger that it cannot process or does not understand. It is essential for the trigger caller to be able to understand when such errors occur so they can take actions to fix them. This document adds a mechanism to report extension errors. o Error propagation - enable the uCDN to traceback an error to the dCDN in which it occurred. CDNI triggers may be propagated over a - chain of downstream CDNs. Let us take for example an upstream - (uCDN-A) CDN A that is delegating to a downstream CDN B (dCDN-B) - and dCDN-B is delegating to a downstream CDN C (dCDN-C). Triggers - sent from uCDN-A to dCDN-B may be redistributed from dCDN-B to - dCDN-C and errors can happen anywhere along the path. Therefore, - it is essential for uCDN-A that sets the trigger, to be able to - trace back an error to the downstream CDN where it occurred. This - document adds a mechanism to propagate the ID of the faulty dCDN - back to the uCDN by adding the CDN ID to the error description. - When a downstream dCDN-B propagates a trigger to another - downstream dCDN-C, it MUST also propagate back the errors received - in the trigger status resource from dCDN-C by adding them to the - errors array in its own status resource to be sent back to the - originating uCDN-A. This makes sure that the trigger originating - upstream CDN will receive an array of errors that occurred in all - the CDNs along the execution path, each error carrying its own CDN - identifier. + chain of downstream CDNs. For example, an upstream CDN, call it + uCDN-A, that is delegating to a downstream CDN, call it dCDN-B. + And, dCDN-B is delegating to a downstream CDN, call it, dCDN-C. + In this example, triggers sent from uCDN-A to dCDN-B may be + redistributed from dCDN-B to dCDN-C and errors can happen anywhere + along the path. Therefore, it is essential for uCDN-A that sets + the trigger, to be able to trace back an error to the downstream + CDN where it occurred. This document adds a mechanism to + propagate the ID of the faulty dCDN back to the uCDN by adding the + CDN ID to the error description. When a downstream dCDN (dCDN-B) + propagates a trigger to another downstream CDN (dCDN-C), it MUST + also propagate back the errors received in the trigger status + resource from dCDN-C by adding them to the errors array in its own + status resource to be sent back to the originating CDN, in this + example, the uCDN-A. This makes sure that the trigger originating + in an upstream CDN will receive an array of errors that occurred + in all the downstream CDNs along the execution path, each error + carrying its own CDN identifier. 3.3. Properties of CI/T Version 2 objects This section defines the values that can appear in the top-level objects described in Section 3.1, and their encodings. 3.3.1. Trigger Specification Version 2 Version 2 of the Trigger Specification adds the following properties on top of the existing properties of the trigger specification @@ -807,27 +809,27 @@ 3.3.6. Error Description Version 2 Version 2 of the Error Description adds the "content.playlists", "content.regexs", "extensions" and "cdn" properties on top of the existing properties of version 1 of the trigger Error Description as defined in Section 5.2.6 of [RFC8007]. Properties: content.regexs, content.playlists - Description: Content Regex and Playlist references copied from - the Trigger Specification. Only those regexs and playlists to - which the error applies are included in each property, but - those references MUST be exactly as they appear in the request; - the dCDN MUST NOT change or generalize the URLs or Regexs. - Note that these properties are added on top of the already - existing properties: "metadata.urls", "content.urls", + Description: Content Regex and Playlist references are copied + from the Trigger Specification. Only those regexs and + playlists to which the error applies are included in each + property, but those references MUST be exactly as they appear + in the request; the dCDN MUST NOT change or generalize the URLs + or Regexs. Note that these properties are added on top of the + already existing properties: "metadata.urls", "content.urls", "metadata.patterns" and "content.patterns". Type: A JSON array of JSON strings, where each string is copied from a "content.regexs" or "content.playlists" value in the corresponding Trigger Specification. Mandatory: At least one of "content.regexs", "content.playlists", "metadata.urls", "content.urls", "metadata.patterns" or "content.patterns" is mandatory in each Error Description object. @@ -1040,21 +1042,21 @@ } 3.4.3. Extensions with Error Propagation In the following example a CI/T "preposition" command is using two extensions to control the way the trigger is executed. In this example the receiving dCDN identified as "AS64500:0" does not support the first extension in the extensions array. dCDN "AS64500:0" further distributes this trigger to another downstream CDN that is identified as "AS64501:0", which does not support the second extension in the - extensions array. The error is propagate from "AS64501:0" to + extensions array. The error is propagated from "AS64501:0" to "AS64500:0" and the errors.v2 array reflects both errors. REQUEST: POST /triggers HTTP/1.1 User-Agent: example-user-agent/0.1 Host: triggers.dcdn.example.com Accept: */* Content-Type: application/cdni; ptype=ci-trigger-command.v2 { @@ -1243,28 +1245,27 @@ A uCDN may wish to perform content management operations on the dCDN in a specific schedule. The TimePolicy extensions allows the uCDN to instruct the dCDN to execute the trigger command in a desired time window. For example, a content provider that wishes to pre-populate a new episode at off-peak time so that it would be ready on caches at prime time when the episode is released for viewing. A scheduled operation enables the uCDN to direct the dCDN in what time frame to execute the trigger. - A uCDN may wish to to schedule a trigger such that the dCDN will - execute it in local time, as it is measured in each region. For - example, a uCDN may wish the dCDN to pull the content at off-peak - hours, between 2AM-4AM, however, as a CDN is distributed across - multiple time zones, the UTC definition of 2AM depends on the actual - location. + A uCDN may wish to schedule a trigger such that the dCDN will execute + it in local time, as it is measured in each region. For example, a + uCDN may wish the dCDN to pull the content at off-peak hours, between + 2AM-4AM, however, as a CDN is distributed across multiple time zones, + the UTC definition of 2AM depends on the actual location. - We define two alternatives for localized scheduling: + This document defines two alternatives for localized scheduling: o Regional schedule: When used in conjunction with the Location Policy defined in Section 4.1, the uCDN can trigger separate commands for different geographical regions, for each region using a different schedule. This allows the uCDN to control the execution time per region. o Local Time schedule: We introduce a "local time" version for Internet timestamps that follows the notation for local time as defined in Section 4.2.2 of [ISO8601]. When local time is used, @@ -1300,22 +1301,22 @@ trigger at the defined time frame, interpreted as the the local time per location. Type: LocalTimeWindow object as defined in Section 4.2.2. Mandatory-to-Specify: No, but exactly one of "unix-time- window", "utc-window" or "local-time-window" MUST be present. 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. + suitable to the dCDN taking under consideration other constrains and/ + or obligations. Example of a generic trigger extension object containing a time policy object that schedules the trigger execution to a window between 09:00 01/01/2000 UTC and 17:00 01/01/2000 UTC, using the "unix-time-window" property: { "generic-trigger-extension-type": "CIT.TimePolicy", "generic-trigger-extension-value": { @@ -1337,21 +1338,21 @@ Property: start Description: The start time of the window. Type: Internet date and time as defined in [RFC3339]. Mandatory-to-Specify: Yes. Property: end - Description: The end time of the window. + Description: The end-time of the window. Type: Internet date and time as defined in [RFC3339]. Mandatory-to-Specify: Yes. Example UTCWindow object that describes a time window from 02:30 01/01/2000 UTC to 04:30 01/01/2000 UTC: { "start": 2000-01-01T02:30:00.00Z, @@ -1370,21 +1371,21 @@ A LocalTimeWindow object describes a time range in local time. The reader of this object MUST interpret it as "the local time at the location of execution". For example, if the time window states 2AM to 4AM local time then a dCDN that has presence in both London (UTC) and New York (UTC-05:00) will execute the trigger at 2AM-4AM UTC in London and at 2AM-4AM UTC-05:00 in New York. Property: start - Description: The start time of the window. + Description: The start-time of the window. Type: JSON string formatted as DateLocalTime as defined in Section 4.2.3. Mandatory-to-Specify: Yes. Property: end Description: The end time of the window. @@ -1681,23 +1682,23 @@ 6.2. CDNI CI/T Trigger Error Codes types The IANA is requested to update the "CDNI CI/T Error Codes" subregistry (defined in Section 7.3 of [RFC8007] and located at ) with the following registration: +------------+-----------------------------------+------------------+ | Error Code | Description | Specification | +------------+-----------------------------------+------------------+ - | eextension | The dCDN failed to parse a | Section Section | - | | generic extension object, or does | 3.3.7 of this | - | | not support this extension. | document. | + | eextension | The dCDN failed to parse a | Section | + | | generic extension object, or does | Section 3.3.7 of | + | | not support this extension. | this document. | +------------+-----------------------------------+------------------+ 6.3. CDNI Media protocol types The IANA is requested to create a new "CDNI MediaProtocol Types" subregistry in the "Content Delivery Networks Interconnection (CDNI) Parameters" registry. The "CDNI MediaProtocol Types" namespace defines the valid MediaProtocol object values in Section Section 3.3.4, used by the Playlist object. Additions to the MediaProtocol namespace conform to the "Specification Required" @@ -1745,21 +1746,22 @@ document. 8. Acknowledgments TBD 9. Contributors The authors would like to thank all members of the "Streaming Video Alliance" (SVA) Open Caching Working Group for their contribution in - support of this document. + support of this document. Authors also thank Kevin J. Ma for his + reviews and comments. 10. References 10.1. Normative References [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, .