--- 1/draft-ietf-cdni-triggers-extensions-06.txt 2020-12-23 14:13:10.977931461 -0800 +++ 2/draft-ietf-cdni-triggers-extensions-07.txt 2020-12-23 14:13:11.029932154 -0800 @@ -1,34 +1,32 @@ Network Working Group O. Finkelman Internet-Draft Qwilt Updates: 8007 (if approved) S. Mishra Intended status: Standards Track Verizon -Expires: March 28, 2021 N. Sopher +Expires: June 26, 2021 N. Sopher Qwilt - September 24, 2020 + December 23, 2020 CDNI Control Triggers Interface Extensions - draft-ietf-cdni-triggers-extensions-06 + draft-ietf-cdni-triggers-extensions-07 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 architeccture is a use case of - Content Delivery Network 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 defines extensions to the Content Delivery Network - Interconnection (CDNI) Control Interface/Triggers. These extensions - are derived from requirements raised by Open Caching architecture but - are also applicable to CDNI use cases in general. + Open Caching architecture is a use case of Content Delivery Network + 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 defines + extensions to the Content Delivery Network Interconnection (CDNI) + Control Interface/Triggers defined in RFC 8007. These extensions are + derived from requirements raised by Open Caching architecture but are + also applicable to CDNI use cases in general. Requirements Language 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 [RFC2119]. Status of This Memo This Internet-Draft is submitted in full conformance with the @@ -37,21 +35,21 @@ 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 28, 2021. + This Internet-Draft will expire on June 26, 2021. Copyright Notice 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 @@ -70,108 +68,106 @@ 2.1. CDNI Control Interface / Triggers Extensions . . . . . . 5 2.1.1. CI/T Objects . . . . . . . . . . . . . . . . . . . . 5 2.1.2. Trigger Specification . . . . . . . . . . . . . . . . 5 2.1.3. Content Selection . . . . . . . . . . . . . . . . . . 5 2.1.4. Trigger Extensibility . . . . . . . . . . . . . . . . 6 2.1.5. Error Handling . . . . . . . . . . . . . . . . . . . 6 2.2. CDNI Footprint and Capabilities Interface Extensions . . 7 3. CI/T Version 2 . . . . . . . . . . . . . . . . . . . . . . . 7 3.1. CI/T Objects V2 . . . . . . . . . . . . . . . . . . . . . 7 3.2. Error Handling V2 . . . . . . . . . . . . . . . . . . . . 10 - 3.3. Properties of CI/T Version 2 objects . . . . . . . . . . 11 - 3.3.1. Trigger Specification Version 2 . . . . . . . . . . . 11 - 3.3.2. RegexMatch . . . . . . . . . . . . . . . . . . . . . 12 - 3.3.3. Playlist . . . . . . . . . . . . . . . . . . . . . . 14 - 3.3.4. MediaProtocol . . . . . . . . . . . . . . . . . . . . 14 - 3.3.5. CI/T Trigger Extensions . . . . . . . . . . . . . . . 15 - 3.3.5.1. Enforcement Options . . . . . . . . . . . . . . . 15 - 3.3.5.2. GenericExtensionObject . . . . . . . . . . . . . 18 - 3.3.6. Error Description Version 2 . . . . . . . . . . . . . 20 - 3.3.7. Error codes . . . . . . . . . . . . . . . . . . . . . 22 - 3.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . 22 - 3.4.1. Invalidation with Regex . . . . . . . . . . . . . . . 22 - 3.4.2. Preposition with Playlists . . . . . . . . . . . . . 24 - 3.4.3. Extensions with Error Propagation . . . . . . . . . . 25 - 4. Trigger Extension Objects . . . . . . . . . . . . . . . . . . 27 - 4.1. LocationPolicy extension . . . . . . . . . . . . . . . . 27 - 4.2. TimePolicy Extension . . . . . . . . . . . . . . . . . . 29 - 4.2.1. UTCWindow . . . . . . . . . . . . . . . . . . . . . . 31 - 4.2.2. LocalTimeWindow . . . . . . . . . . . . . . . . . . . 32 - 4.2.3. DateLocalTime . . . . . . . . . . . . . . . . . . . . 33 - 4.2.3.1. Date and Local Time Format . . . . . . . . . . . 33 - 4.2.3.2. Restrictions . . . . . . . . . . . . . . . . . . 34 - 5. Footprint and Capabilities . . . . . . . . . . . . . . . . . 34 - 5.1. CI/T Versions Capability Object . . . . . . . . . . . . . 34 - 5.1.1. CI/T Versions Capability Object Serialization . . . . 35 - 5.2. CI/T Playlist Protocol Capability Object . . . . . . . . 35 + 3.2.1. Extension Errors . . . . . . . . . . . . . . . . . . 10 + 3.2.2. Error propagation . . . . . . . . . . . . . . . . . . 11 + 3.3. Properties of CI/T Version 2 objects . . . . . . . . . . 13 + 3.3.1. Trigger Specification Version 2 . . . . . . . . . . . 14 + 3.3.2. RegexMatch . . . . . . . . . . . . . . . . . . . . . 15 + 3.3.3. Playlist . . . . . . . . . . . . . . . . . . . . . . 16 + 3.3.4. MediaProtocol . . . . . . . . . . . . . . . . . . . . 17 + 3.3.5. CI/T Trigger Extensions . . . . . . . . . . . . . . . 17 + 3.3.5.1. Enforcement Options . . . . . . . . . . . . . . . 17 + 3.3.5.2. GenericExtensionObject . . . . . . . . . . . . . 20 + 3.3.6. Error Description Version 2 . . . . . . . . . . . . . 22 + 3.3.7. Error codes . . . . . . . . . . . . . . . . . . . . . 24 + 3.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . 24 + 3.4.1. Invalidation with Regex . . . . . . . . . . . . . . . 24 + 3.4.2. Preposition with Playlists . . . . . . . . . . . . . 26 + 3.4.3. Extensions with Error Propagation . . . . . . . . . . 27 + 4. Trigger Extension Objects . . . . . . . . . . . . . . . . . . 29 + 4.1. LocationPolicy extension . . . . . . . . . . . . . . . . 29 + 4.2. TimePolicy Extension . . . . . . . . . . . . . . . . . . 31 + 4.2.1. UTCWindow . . . . . . . . . . . . . . . . . . . . . . 33 + 4.2.2. LocalTimeWindow . . . . . . . . . . . . . . . . . . . 34 + 4.2.3. DateLocalTime . . . . . . . . . . . . . . . . . . . . 35 + 4.2.3.1. Date and Local Time Format . . . . . . . . . . . 35 + 4.2.3.2. Restrictions . . . . . . . . . . . . . . . . . . 36 + 5. Footprint and Capabilities . . . . . . . . . . . . . . . . . 36 + 5.1. CI/T Versions Capability Object . . . . . . . . . . . . . 36 + 5.1.1. CI/T Versions Capability Object Serialization . . . . 37 + 5.2. CI/T Playlist Protocol Capability Object . . . . . . . . 37 5.2.1. CI/T Playlist Protocol Capability Object - Serialization . . . . . . . . . . . . . . . . . . . . 35 - 5.3. CI/T Trigger Extension Capability Object . . . . . . . . 36 + Serialization . . . . . . . . . . . . . . . . . . . . 37 + 5.3. CI/T Trigger Extension Capability Object . . . . . . . . 38 5.3.1. CI/T Trigger Extension Capability Object - Serialization . . . . . . . . . . . . . . . . . . . . 36 - 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 - 6.1. CDNI Payload Types . . . . . . . . . . . . . . . . . . . 37 - 6.1.1. CDNI ci-trigger-command.v2 Payload Type . . . . . . . 37 - 6.1.2. CDNI ci-trigger-status.v2 Payload Type . . . . . . . 38 - 6.1.3. CDNI CI/T LocationPolicy Trigger Extension Type . . . 38 - 6.1.4. CDNI CI/T TimePolicy Trigger Extension Type . . . . . 38 - 6.1.5. CDNI FCI CI/T Versions Payload Type . . . . . . . . . 38 - 6.1.6. CDNI FCI CI/T Playlist Protocol Payload Type . . . . 38 - 6.1.7. CDNI FCI CI/T Extension Objects Payload Type . . . . 39 - 6.2. CDNI CI/T Trigger Error Codes types . . . . . . . . . . . 39 - 6.3. CDNI Media protocol types . . . . . . . . . . . . . . . . 39 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 40 - 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 40 - 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 40 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 41 - 10.1. Normative References . . . . . . . . . . . . . . . . . . 41 - 10.2. Informative References . . . . . . . . . . . . . . . . . 42 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 43 + Serialization . . . . . . . . . . . . . . . . . . . . 38 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 + 6.1. CDNI Payload Types . . . . . . . . . . . . . . . . . . . 39 + 6.1.1. CDNI ci-trigger-command.v2 Payload Type . . . . . . . 39 + 6.1.2. CDNI ci-trigger-status.v2 Payload Type . . . . . . . 40 + 6.1.3. CDNI CI/T LocationPolicy Trigger Extension Type . . . 40 + 6.1.4. CDNI CI/T TimePolicy Trigger Extension Type . . . . . 40 + 6.1.5. CDNI FCI CI/T Versions Payload Type . . . . . . . . . 40 + 6.1.6. CDNI FCI CI/T Playlist Protocol Payload Type . . . . 40 + 6.1.7. CDNI FCI CI/T Extension Objects Payload Type . . . . 41 + 6.2. CDNI CI/T Trigger Error Codes types . . . . . . . . . . . 41 + 6.3. CDNI Media protocol types . . . . . . . . . . . . . . . . 41 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 42 + 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 42 + 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 42 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 + 10.1. Normative References . . . . . . . . . . . . . . . . . . 43 + 10.2. Informative References . . . . . . . . . . . . . . . . . 44 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 45 1. Introduction 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 Open Caching Content Management Operations Specification [OC-CM] defines objects and extensions required by Open Caching architecture for granular - content management operations such as new content selection options. - 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]. + content management operations. This document adds those extensions + to the CDNI Control Interface / Triggers [RFC8007] as required for + Open Caching content management options. This document also + specifies a generic extension mechanism to enable adding future + functions for controlling the trigger execution>. 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]. 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. + CDNI convention of uCDN (upstream CDN) and dCDN (downstream CDN) as + described in [RFC6707] to represent the commercial CDN and ISP + caching layer, respectively. 1.1. Terminology - This document reuses the terminology defined in [RFC6707], [RFC8006], - [RFC8007], and [RFC8008]. + This document reuses the terminology defined in [RFC6707], [RFC7736] + [RFC8006], [RFC8007], and [RFC8008]. Additionally, the following terms are used throughout this document and are defined as follows: o HLS - HTTP Live Streaming o DASH - Dynamic Adaptive Streaming Over HTTP o MSS - Microsoft Smooth Streaming @@ -217,21 +213,21 @@ additional properties required by the use cases listed below in Section 2.1.3 and Section 2.1.4. 2.1.3. Content Selection 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. This document specifies two additional selection options: - o Regular Expression - Using regex a uCDN can create more complex + o Regular Expression - Using regex, a uCDN can create more complex rules to select the content objects for the cases of "invalidation" and "purge". For example, purging specific content within a specific directory path. o Content Playlist - Using video playlist files, a uCDN can trigger an operation that will be applied to a collection of distinct media files in a format that is natural for a streaming video content provider. A playlist may have several formats, specifically HTTP Live Streaming (HLS) *.m3u8 manifest [RFC8216], Microsoft Smooth Streaming (MSS) *.ismc client manifest [MSS], and @@ -332,21 +328,21 @@ 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 + another downstream CDN, 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 @@ -414,51 +410,163 @@ } 3.2. Error Handling V2 The CDNI CI/T interface defines a mechanism for error reporting (see Section 4.7 of [RFC8007]) and an Error Description object for reporting errors (see Section 5.2.6 of [RFC8007]). This document specifies version 2 of CI/T error handling in order to support the following: - o Extension errors - report an error that happened due to an - 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. +3.2.1. 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 might be 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. While propagating back the errors, and - depending on the implementation, downstream dCDN-B MAY also - specify the dCDN-C CDN identifier, indicating that the error - relates spefically to this CDN. The trigger originating upstream - CDN will receive an array of errors that occurred in all the CDNs - along the execution path, where each error MAY carrying its own - CDN identifier. + Report an error that occures due to an extension object. As + extension objects are expected to be added to the interface whenever + new requirement comes along, it is expected that in some cases a dCDN + may receive a trigger that it cannot process or it does not + understand. It is therefore essential for the trigger caller to be + able to know when such errors occur so they can take actions to fix + them. This document adds a mechanism to report extension errors. + +3.2.2. Error propagation + + This subsection explains the mechanism for enabling the uCDN to + traceback an error to the dCDN in which it occurred. CDNI triggers + may be propagated over a chain of downstream CDNs. For example, an + upstream CDN A (uCDN-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 occur anywhere along the path. Therefore, + it might be 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 CDN Provider ID (PID) of + the dCDN where the fault occured, back to the uCDN by adding the PID + to the error description. When dCDN-B propagates a trigger to the + further 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. While propagating back the errors, and depending + on the implementation, dCDN-B MAY also specify the dCDN-C PID, + indicating to which CDN the error relates spefically. The trigger + originating upstream CDN will receive an array of errors that + occurred in all the CDNs along the execution path, where each error + MAY be carrying its own CDN identifier. + + Figure 1 below is an example showing the message flow used by uCDN-A + to trigger activity in the dCDN-B, followed by dCDN-C, as well as the + discovery of the status of that activity, including the Error + Propagation. + + uCDN-A dCDN-B dCDN-C + | | | + | (1) POST | | + | https://dcdn-b.example.com | | + | /triggers/uCDN-A | | + [ ]--------------------------->[ ]--+ | + | [ ] | (2) | + | [ ]<-+ | + | (3) HTTP 201 Response. [ ] | + |<----------------------------[ ] | + | Loc: [ ] | + | https://dcdn-b.example.com [ ] (4) POST | + | /triggers/uCDN-A/123 [ ] https://dcdn-c.example.com | + | [ ] /triggers/uCDN-A | (5) + | [ ]--------------------------->[ ]--+ + | | [ ] | + | | [ ]<-+ + | | (6) HTTP 201 Response. [ ] + | [ ]<---------------------------[ ] + | | Loc: | + | | https://dcdn-c.example.com | + | | /triggers/dCDN-B/456 | + | | | + | [ ]--+ | + | [ ] | (7.1) | + | [ ]<-+ [ ]--+ + | | (7.2) [ ] | + | | [ ]<-+ + | | | + . . . + . . . + . . . + | | (8) GET | + | | https://dcdn-c.example.com | + | | /triggers/dCDN-B/456 | + | [ ]--------------------------->[ ] + | | [ ] + | | (9) HTTP 200 [ ] + | | Trigger Status Resource [ ] + | [ ]<---------------------------[ ] + | | | + . . . + . . . + . . . + | (10) GET | | + | https://dcdn-b.example.com | | + | /triggers/uCDN-A/123 | | + [ ]--------------------------->[ ] | + | [ ] | + | (11) HTTP 200 [ ] | + | Trigger Status Resource [ ] | + [ ]<---------------------------[ ] | + + Figure 1: CDNI Message Flow for Triggers, Including Error Propagation + + The steps in Figure 1 are as follows: + + 1. The uCDN-A triggers action in the dCDN-B by POSTing a CI/T + Command to a collection of Trigger Status Resources + "https://dcdn-b.example.com/triggers/uCDN-A". This URL was + given to the uCDN-A when the CI/T interface was established. + + 2. The dCDN-B authenticates the request, validates the CI/T + Command, and, if it accepts the request, creates a new Trigger + Status Resource. + + 3. The dCDN-B responds to the uCDN-A with an HTTP 201 response + status and the location of the Trigger Status Resource. + + 4. The dCDN-B triggers the action in the dCDN-C by POSTing a CI/T + Command to a collection of Trigger Status Resources + "https://dcdn-c.example.com/triggers/dCDN-B". This URL was + given to the uCDN-A when the CI/T interface was established. + + 5. The dCDN-C authenticates the request, validates the CI/T + Command, and, if it accepts the request, creates a new Trigger + Status Resource. + + 6. The dCDN-C responds to the dCDN-B with an HTTP 201 response + status and the location of the Trigger Status Resource. + + 7. The dCDN-C acts upon the CI/T Command. However, the command + fails at dCDN-C as, for example, the Tigger Specification + contains a "type" that is not supported by dCDN-C. + + 8. The dCDN-B can poll, possibly repeatedly, the Trigger Status + Resource in dCDN-C. + + 9. The dCDN-C responds with the Trigger Status Resource, describing + the progress or results of the CI/T Trigger Command. In the + described flow, the returned Status is "failed", with an Error + Description Object holding an "eunsupported" Error Code + reflecting the status response. + + 10. The uCDN-A can poll, possibly repeatedly, the Trigger Status + Resource in dCDN-B. + + 11. The dCDN-B responds with the Trigger Status Resource, describing + the progress or results of the CI/T Trigger Command. In the + flow described above, the returned Status is "failed", and the + "eunsupported" error received in the trigger status resource + from dCDN-C is propagated along with dCDN-C PID by adding it to + the errors array in dCDN-B's own status resource to be sent back + to the originating uCDN-A. 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 @@ -486,22 +594,22 @@ Property: extensions Description: Array of trigger extension data. Type: Array of GenericTriggerExtension objects (see Section 3.3.5.2). Mandatory: No. The default is no extensions. - Example of an invalidation trigger.v2 with a list of regex objects, a - list of playlist objects, and extensions: + Example of a JSON serialized invalidation trigger.v2 object with a + list of regex objects, a list of playlist objects, and extensions: { "trigger.v2": { "type": "invalidate", "content.regexs": [ ], "content.playlists": [ ], "extensions": [ , "generic-trigger-extension-value": { }, "mandatory-to-enforce": true, "safe-to-redistribute": true, @@ -873,37 +981,37 @@ The "cdn" property is used by the originating uCDN or by propagating dCDN in order to distinguish in which CDN the error occured. Type: A non-empty JSON string, where the string is a CDN PID as defined in Section 4.6 of [RFC8007]. Mandatory: Yes. In the case the dCDN does not like to expose this information, it should provide its own CDN PID. - Example of an Error Description object reporting a malformed - Playlist: + Example of a JSON serialized Error Description object reporting a + malformed Playlist: { "content.playlists": [ { "playlist": "https://www.example.com/hls/title/index.m3u8", "media-protocol": "hls" } ], "description": "Failed to parse HLS playlist", "error": "econtent", "cdn": "AS64500:0" }, - Example of an Error Description object reporting an unsupported - extension object: + Example of a JSON serialized Error Description object reporting an + unsupported extension object: { "errors.v2": [ { "extensions": [ { "generic-trigger-extension-type": , "generic-trigger-extension-value": { @@ -1062,21 +1170,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 { @@ -1191,21 +1299,21 @@ Example use cases: o Pre-position: Certain contracts allow for pre-positioning or availability of contract in all regions except for certain excluded regions in the world, including caches. For example, some content cannot ever knowingly touch servers in a specific country, including cached content. Therefore, these regions MUST be excluded from a pre-positioning operation. o Purge: In certain cases, content may have been located on servers - in regions where the content must not reside. In such cases a + in regions where the content must not reside. In such cases, a purge operation to remove content specifically from that region, is required. Object specification Property: locations Description: An Access List that allows or denies (blocks) the trigger execution per cache location. @@ -1220,23 +1328,23 @@ 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 generic trigger extension object - containing a location policy object that allows the trigger execution - in the US but blocks its execution in Canada: + The following is an example of a JSON serialized generic trigger + extension object containing a location policy object that allows the + trigger execution in the US but blocks its execution in Canada: { "generic-trigger-extension-type": "CIT.LocationPolicy", "generic-trigger-extension-value": { "locations": [ { "action": "allow", "footprints": [ { @@ -1325,24 +1433,24 @@ Type: LocalTimeWindow object as defined in Section 4.2.2. Mandatory: No, but exactly one of "unixEpochWindow", "utcWindow" or "localTimeWindow" 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. - 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: + Example of a JSON serialized 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": { "unix-time-window": { "start": 946717200, "end": 946746000 } } @@ -1367,30 +1475,31 @@ Property: end Description: The end time of the window. Type: Internet date and time as defined in [RFC3339]. Mandatory: No, but at least one of "start" or "end" MUST be present and non-empty. - Example UTCWindow object that describes a time window from 02:30 - 01/01/2000 UTC to 04:30 01/01/2000 UTC: + Example JSON serialized 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, "end": 2000-01-01T04:30:00.00Z, } - Example UTCWindow object that describes a time window in New York - time zone offset UTC-05:00 from 02:30 01/01/2000 to 04:30 01/01/2000: + Example JSON serialized UTCWindow object that describes a time window + in New York time zone offset UTC-05:00 from 02:30 01/01/2000 to 04:30 + 01/01/2000: { "start": 2000-01-01T02:30:00.00-05:00, "end": 2000-01-01T04:30:00.00-05:00, } 4.2.2. LocalTimeWindow A LocalTimeWindow object describes a time range in local time. The reader of this object MUST interpret it as "the local time at the @@ -1412,22 +1521,22 @@ Property: end Description: The end time of the window. Type: JSON string formatted as DateLocalTime as defined in Section 4.2.3. Mandatory: No, but at least one of "start" or "end" MUST be present and non-empty. - Example LocalTimeWindow object that describes a local time window - from 02:30 01/01/2000 to 04:30 01/01/2000. + Example JSON serialized LocalTimeWindow object that describes a local + time window from 02:30 01/01/2000 to 04:30 01/01/2000. { "start": 2000-01-01T02:30:00.00, "end": 2000-01-01T04:30:00.00, } 4.2.3. DateLocalTime DateLocalTime is a timestamp that follows the date and local time notation in Section 4.3.2 of [ISO8601] as a complete date and time @@ -1516,23 +1625,23 @@ Description: A list of version numbers. Type: An array of JSON strings Mandatory: No. The default is version 1. A missing or an empty versions list means that only version 1 of the interface and objects is supported. 5.1.1. CI/T Versions Capability Object Serialization - 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. + The following shows an example of a JSON serialized 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": [ "1", "2", "2.1" ] }, "footprints": [ @@ -1552,22 +1661,23 @@ Description: A list of media protocols. Type: A list of MediaProtocol (from the CDNI Triggers media protocol types Section 6.3) Mandatory: No. The default, in case of a missing or an empty list, is none supported. 5.2.1. CI/T Playlist Protocol Capability Object Serialization - The following shows an example of CI/T Playlist Protocol Capability - object serialization for a dCDN that supports "hls" and "dash". + The following shows an example of a JSON serialized CI/T Playlist + Protocol Capability object serialization for a dCDN that supports + "hls" and "dash". { "capabilities": [ { "capability-type": "FCI.TriggerPlaylistProtocol", "capability-value": { "media-protocols": ["hls", "dash"] }, "footprints": [ @@ -1592,23 +1702,23 @@ GenericExtensionObject objects. Mandatory: No. The default, in case of a missing or an empty list, MUST be interpreted as "no GenericExtensionObject types are supported". A non-empty list MUST be interpreted as containing "the only GenericExtensionObject types that are supported". 5.3.1. CI/T Trigger Extension Capability Object Serialization - 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. + The following shows an example of a JSON serialized 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": [ @@ -1752,41 +1862,42 @@ [RFC Editor: Please replace RFCthis with the published RFC number for this document.] 7. Security Considerations All security considerations listed in Section 8 of [RFC8007] and Section 7 of [RFC8008] apply to this document as well. This document defines the capability to use regular expression within - the trigger spec for more granular content selection. The usage of - regex introduced the risk of regex complexity attacks, a.k.a ReDos - attacks. An attacker may be able to craft a regular expression that - can exhaust server resources and may take exponential time in the - worst case. An implementation MUST protect itself by at least accept - triggers only from an authenticated party over a secured connection. - An implementation SHOULD also protect itself by using secure - programing techniques and decline trigger commands that use + the trigger specification for more granular content selection. The + usage of regex introduced the risk of regex complexity attacks, a.k.a + ReDos attacks. An attacker may be able to craft a regular expression + that can exhaust server resources and may take exponential time in + the worst case. An implementation MUST protect itself at a minimum + by accepting triggers only from an authenticated party over a secured + connection. An implementation SHOULD also protect itself by using + secure programing techniques and decline trigger commands that use potentially risky regex, such techniques are readily available in secure programming literature and are beyond the scope of this 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. + The authors thank all members of the "Streaming Video Alliance" (SVA) + and specifically contributions by members of Open Caching Working + Group in support of this document. The authors also thank Kevin Ma + for his guidance and careful and methodical reviews. 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, . @@ -1797,20 +1908,29 @@ [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . + [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, . + [RFC8006] Niven-Jenkins, B., Murray, R., Caulfield, M., and K. Ma, "Content Delivery Network Interconnection (CDNI) Metadata", RFC 8006, DOI 10.17487/RFC8006, December 2016, . [RFC8007] Murray, R. and B. Niven-Jenkins, "Content Delivery Network Interconnection (CDNI) Control Interface / Triggers", RFC 8007, DOI 10.17487/RFC8007, December 2016, . @@ -1853,29 +1973,20 @@ . [OCWG] Streaming Video Alliance, "Open Caching", . [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., Ed. and W. May, "HTTP Live Streaming", RFC 8216, DOI 10.17487/RFC8216, August 2017, . [SVA] "Streaming Video Alliance", . Authors' Addresses Ori Finkelman