draft-ietf-cdni-triggers-extensions-06.txt   draft-ietf-cdni-triggers-extensions-07.txt 
Network Working Group O. Finkelman Network Working Group O. Finkelman
Internet-Draft Qwilt Internet-Draft Qwilt
Updates: 8007 (if approved) S. Mishra Updates: 8007 (if approved) S. Mishra
Intended status: Standards Track Verizon Intended status: Standards Track Verizon
Expires: March 28, 2021 N. Sopher Expires: June 26, 2021 N. Sopher
Qwilt Qwilt
September 24, 2020 December 23, 2020
CDNI Control Triggers Interface Extensions CDNI Control Triggers Interface Extensions
draft-ietf-cdni-triggers-extensions-06 draft-ietf-cdni-triggers-extensions-07
Abstract Abstract
This document updates RFC 8007 to include generic extensions and more Open Caching architecture is a use case of Content Delivery Network
granular content matching options, required by the Open Caching Interconnection (CDNI) in which the commercial Content Delivery
architecture. The Open Caching architeccture is a use case of Network (CDN) is the upstream CDN (uCDN) and the ISP caching layer
Content Delivery Network Interconnection (CDNI) in which the serves as the downstream CDN (dCDN). This document defines
commercial Content Delivery Network (CDN) is the upstream CDN (uCDN) extensions to the Content Delivery Network Interconnection (CDNI)
and the ISP caching layer serves as the downstream CDN (dCDN). This Control Interface/Triggers defined in RFC 8007. These extensions are
document defines extensions to the Content Delivery Network derived from requirements raised by Open Caching architecture but are
Interconnection (CDNI) Control Interface/Triggers. These extensions also applicable to CDNI use cases in general.
are derived from requirements raised by Open Caching architecture but
are also applicable to CDNI use cases in general.
Requirements Language Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119]. document are to be interpreted as described in RFC 2119 [RFC2119].
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 48 skipping to change at page 1, line 46
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." 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 Notice
Copyright (c) 2020 IETF Trust and the persons identified as the Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 36 skipping to change at page 2, line 36
2.1. CDNI Control Interface / Triggers Extensions . . . . . . 5 2.1. CDNI Control Interface / Triggers Extensions . . . . . . 5
2.1.1. CI/T Objects . . . . . . . . . . . . . . . . . . . . 5 2.1.1. CI/T Objects . . . . . . . . . . . . . . . . . . . . 5
2.1.2. Trigger Specification . . . . . . . . . . . . . . . . 5 2.1.2. Trigger Specification . . . . . . . . . . . . . . . . 5
2.1.3. Content Selection . . . . . . . . . . . . . . . . . . 5 2.1.3. Content Selection . . . . . . . . . . . . . . . . . . 5
2.1.4. Trigger Extensibility . . . . . . . . . . . . . . . . 6 2.1.4. Trigger Extensibility . . . . . . . . . . . . . . . . 6
2.1.5. Error Handling . . . . . . . . . . . . . . . . . . . 6 2.1.5. Error Handling . . . . . . . . . . . . . . . . . . . 6
2.2. CDNI Footprint and Capabilities Interface Extensions . . 7 2.2. CDNI Footprint and Capabilities Interface Extensions . . 7
3. CI/T Version 2 . . . . . . . . . . . . . . . . . . . . . . . 7 3. CI/T Version 2 . . . . . . . . . . . . . . . . . . . . . . . 7
3.1. CI/T Objects V2 . . . . . . . . . . . . . . . . . . . . . 7 3.1. CI/T Objects V2 . . . . . . . . . . . . . . . . . . . . . 7
3.2. Error Handling V2 . . . . . . . . . . . . . . . . . . . . 10 3.2. Error Handling V2 . . . . . . . . . . . . . . . . . . . . 10
3.3. Properties of CI/T Version 2 objects . . . . . . . . . . 11 3.2.1. Extension Errors . . . . . . . . . . . . . . . . . . 10
3.3.1. Trigger Specification Version 2 . . . . . . . . . . . 11 3.2.2. Error propagation . . . . . . . . . . . . . . . . . . 11
3.3.2. RegexMatch . . . . . . . . . . . . . . . . . . . . . 12 3.3. Properties of CI/T Version 2 objects . . . . . . . . . . 13
3.3.3. Playlist . . . . . . . . . . . . . . . . . . . . . . 14 3.3.1. Trigger Specification Version 2 . . . . . . . . . . . 14
3.3.4. MediaProtocol . . . . . . . . . . . . . . . . . . . . 14 3.3.2. RegexMatch . . . . . . . . . . . . . . . . . . . . . 15
3.3.5. CI/T Trigger Extensions . . . . . . . . . . . . . . . 15 3.3.3. Playlist . . . . . . . . . . . . . . . . . . . . . . 16
3.3.5.1. Enforcement Options . . . . . . . . . . . . . . . 15 3.3.4. MediaProtocol . . . . . . . . . . . . . . . . . . . . 17
3.3.5.2. GenericExtensionObject . . . . . . . . . . . . . 18 3.3.5. CI/T Trigger Extensions . . . . . . . . . . . . . . . 17
3.3.6. Error Description Version 2 . . . . . . . . . . . . . 20 3.3.5.1. Enforcement Options . . . . . . . . . . . . . . . 17
3.3.7. Error codes . . . . . . . . . . . . . . . . . . . . . 22 3.3.5.2. GenericExtensionObject . . . . . . . . . . . . . 20
3.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . 22 3.3.6. Error Description Version 2 . . . . . . . . . . . . . 22
3.4.1. Invalidation with Regex . . . . . . . . . . . . . . . 22 3.3.7. Error codes . . . . . . . . . . . . . . . . . . . . . 24
3.4.2. Preposition with Playlists . . . . . . . . . . . . . 24 3.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . 24
3.4.3. Extensions with Error Propagation . . . . . . . . . . 25 3.4.1. Invalidation with Regex . . . . . . . . . . . . . . . 24
4. Trigger Extension Objects . . . . . . . . . . . . . . . . . . 27 3.4.2. Preposition with Playlists . . . . . . . . . . . . . 26
4.1. LocationPolicy extension . . . . . . . . . . . . . . . . 27 3.4.3. Extensions with Error Propagation . . . . . . . . . . 27
4.2. TimePolicy Extension . . . . . . . . . . . . . . . . . . 29 4. Trigger Extension Objects . . . . . . . . . . . . . . . . . . 29
4.2.1. UTCWindow . . . . . . . . . . . . . . . . . . . . . . 31 4.1. LocationPolicy extension . . . . . . . . . . . . . . . . 29
4.2.2. LocalTimeWindow . . . . . . . . . . . . . . . . . . . 32 4.2. TimePolicy Extension . . . . . . . . . . . . . . . . . . 31
4.2.3. DateLocalTime . . . . . . . . . . . . . . . . . . . . 33 4.2.1. UTCWindow . . . . . . . . . . . . . . . . . . . . . . 33
4.2.3.1. Date and Local Time Format . . . . . . . . . . . 33 4.2.2. LocalTimeWindow . . . . . . . . . . . . . . . . . . . 34
4.2.3.2. Restrictions . . . . . . . . . . . . . . . . . . 34 4.2.3. DateLocalTime . . . . . . . . . . . . . . . . . . . . 35
5. Footprint and Capabilities . . . . . . . . . . . . . . . . . 34 4.2.3.1. Date and Local Time Format . . . . . . . . . . . 35
5.1. CI/T Versions Capability Object . . . . . . . . . . . . . 34 4.2.3.2. Restrictions . . . . . . . . . . . . . . . . . . 36
5.1.1. CI/T Versions Capability Object Serialization . . . . 35 5. Footprint and Capabilities . . . . . . . . . . . . . . . . . 36
5.2. CI/T Playlist Protocol Capability Object . . . . . . . . 35 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 5.2.1. CI/T Playlist Protocol Capability Object
Serialization . . . . . . . . . . . . . . . . . . . . 35 Serialization . . . . . . . . . . . . . . . . . . . . 37
5.3. CI/T Trigger Extension Capability Object . . . . . . . . 36 5.3. CI/T Trigger Extension Capability Object . . . . . . . . 38
5.3.1. CI/T Trigger Extension Capability Object 5.3.1. CI/T Trigger Extension Capability Object
Serialization . . . . . . . . . . . . . . . . . . . . 36 Serialization . . . . . . . . . . . . . . . . . . . . 38
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39
6.1. CDNI Payload Types . . . . . . . . . . . . . . . . . . . 37 6.1. CDNI Payload Types . . . . . . . . . . . . . . . . . . . 39
6.1.1. CDNI ci-trigger-command.v2 Payload Type . . . . . . . 37 6.1.1. CDNI ci-trigger-command.v2 Payload Type . . . . . . . 39
6.1.2. CDNI ci-trigger-status.v2 Payload Type . . . . . . . 38 6.1.2. CDNI ci-trigger-status.v2 Payload Type . . . . . . . 40
6.1.3. CDNI CI/T LocationPolicy Trigger Extension Type . . . 38 6.1.3. CDNI CI/T LocationPolicy Trigger Extension Type . . . 40
6.1.4. CDNI CI/T TimePolicy Trigger Extension Type . . . . . 38 6.1.4. CDNI CI/T TimePolicy Trigger Extension Type . . . . . 40
6.1.5. CDNI FCI CI/T Versions Payload Type . . . . . . . . . 38 6.1.5. CDNI FCI CI/T Versions Payload Type . . . . . . . . . 40
6.1.6. CDNI FCI CI/T Playlist Protocol Payload Type . . . . 38 6.1.6. CDNI FCI CI/T Playlist Protocol Payload Type . . . . 40
6.1.7. CDNI FCI CI/T Extension Objects Payload Type . . . . 39 6.1.7. CDNI FCI CI/T Extension Objects Payload Type . . . . 41
6.2. CDNI CI/T Trigger Error Codes types . . . . . . . . . . . 39 6.2. CDNI CI/T Trigger Error Codes types . . . . . . . . . . . 41
6.3. CDNI Media protocol types . . . . . . . . . . . . . . . . 39 6.3. CDNI Media protocol types . . . . . . . . . . . . . . . . 41
7. Security Considerations . . . . . . . . . . . . . . . . . . . 40 7. Security Considerations . . . . . . . . . . . . . . . . . . . 42
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 40 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 42
9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 40 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 42
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 41 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 43
10.1. Normative References . . . . . . . . . . . . . . . . . . 41 10.1. Normative References . . . . . . . . . . . . . . . . . . 43
10.2. Informative References . . . . . . . . . . . . . . . . . 42 10.2. Informative References . . . . . . . . . . . . . . . . . 44
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 43 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 45
1. Introduction 1. Introduction
The Streaming Video Alliance [SVA] is a global association that works The Streaming Video Alliance [SVA] is a global association that works
to solve streaming video challenges in an effort to improve end-user to solve streaming video challenges in an effort to improve end-user
experience and adoption. The Open Caching Working Group [OCWG] of experience and adoption. The Open Caching Working Group [OCWG] of
the Streaming Video Alliance [SVA] is focused on the delegation of the Streaming Video Alliance [SVA] is focused on the delegation of
video delivery requests from commerical CDNs to a caching layer at video delivery requests from commerical CDNs to a caching layer at
the ISP's network. Open Caching architecture is a specific use case 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 of CDNI where the commercial CDN is the upstream CDN (uCDN) and the
ISP caching layer is the downstream CDN (dCDN). The Open Caching ISP caching layer is the downstream CDN (dCDN). The Open Caching
Content Management Operations Specification [OC-CM] defines objects Content Management Operations Specification [OC-CM] defines objects
and extensions required by Open Caching architecture for granular and extensions required by Open Caching architecture for granular
content management operations such as new content selection options. content management operations. This document adds those extensions
This document defines the objects and extensions required for to the CDNI Control Interface / Triggers [RFC8007] as required for
granular content management operations. For that purpose it extends Open Caching content management options. This document also
CDNI Control Interface / Triggers [RFC8007] by adding new content specifies a generic extension mechanism to enable adding future
selection options to the trigger specification and specifying a functions for controlling the trigger execution>.
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].
The CDNI Metadata Interface is described in [RFC8006]. The CDNI Metadata Interface is described in [RFC8006].
The CDNI Footprint and Capability Interface is described in The CDNI Footprint and Capability Interface is described in
[RFC8008]. [RFC8008].
The CDNI Control Interface / Triggers is described in [RFC8007]. The CDNI Control Interface / Triggers is described in [RFC8007].
For consistency with other CDNI documents, this document follows the For consistency with other CDNI documents, this document follows the
CDNI convention of uCDN (upstream CDN) and dCDN downstream CDN) to CDNI convention of uCDN (upstream CDN) and dCDN (downstream CDN) as
represent the commercial CDN and ISP caching layer, respectively. described in [RFC6707] to represent the commercial CDN and ISP
caching layer, respectively.
1.1. Terminology 1.1. Terminology
This document reuses the terminology defined in [RFC6707], [RFC8006], This document reuses the terminology defined in [RFC6707], [RFC7736]
[RFC8007], and [RFC8008]. [RFC8006], [RFC8007], and [RFC8008].
Additionally, the following terms are used throughout this document Additionally, the following terms are used throughout this document
and are defined as follows: and are defined as follows:
o HLS - HTTP Live Streaming o HLS - HTTP Live Streaming
o DASH - Dynamic Adaptive Streaming Over HTTP o DASH - Dynamic Adaptive Streaming Over HTTP
o MSS - Microsoft Smooth Streaming o MSS - Microsoft Smooth Streaming
skipping to change at page 5, line 39 skipping to change at page 5, line 37
additional properties required by the use cases listed below in additional properties required by the use cases listed below in
Section 2.1.3 and Section 2.1.4. Section 2.1.3 and Section 2.1.4.
2.1.3. Content Selection 2.1.3. Content Selection
The trigger specification as defined in Section 5.2.1 of [RFC8007] The trigger specification as defined in Section 5.2.1 of [RFC8007]
provides means to select content objects by matching a full content provides means to select content objects by matching a full content
URL or patterns with wildcards. This document specifies two URL or patterns with wildcards. This document specifies two
additional selection options: 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 rules to select the content objects for the cases of
"invalidation" and "purge". For example, purging specific content "invalidation" and "purge". For example, purging specific content
within a specific directory path. within a specific directory path.
o Content Playlist - Using video playlist files, a uCDN can trigger o Content Playlist - Using video playlist files, a uCDN can trigger
an operation that will be applied to a collection of distinct an operation that will be applied to a collection of distinct
media files in a format that is natural for a streaming video media files in a format that is natural for a streaming video
content provider. A playlist may have several formats, content provider. A playlist may have several formats,
specifically HTTP Live Streaming (HLS) *.m3u8 manifest [RFC8216], specifically HTTP Live Streaming (HLS) *.m3u8 manifest [RFC8216],
Microsoft Smooth Streaming (MSS) *.ismc client manifest [MSS], and Microsoft Smooth Streaming (MSS) *.ismc client manifest [MSS], and
skipping to change at page 8, line 14 skipping to change at page 8, line 14
o Trigger Status Resource v2: A trigger status resource response o Trigger Status Resource v2: A trigger status resource response
using the payload type ci-trigger-status.v2. Version 2 MUST only 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 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 "trigger" object, as well as "errors.v2" array as defined in
Section 3.3.6, instead of a "errors" array. All other properties 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 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 [RFC8007]. The errors array "errors.v2" is a list of all errors
that occurred in any of the downstream CDNs along the execution that occurred in any of the downstream CDNs along the execution
path. When a downstream CDN, dCDN-A, propagates a trigger to 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 errors reported by dCDN-B in the trigger status resource and add
them to its own trigger status resource. them to its own trigger status resource.
o Trigger Collections: The payload type ci-trigger-collection is o Trigger Collections: The payload type ci-trigger-collection is
used with no changes and as defined in 5.1.3 of [RFC8007]. used with no changes and as defined in 5.1.3 of [RFC8007].
Usage example of version 2 of trigger command Usage example of version 2 of trigger command
REQUEST: REQUEST:
POST /triggers HTTP/1.1 POST /triggers HTTP/1.1
User-Agent: example-user-agent/0.1 User-Agent: example-user-agent/0.1
Host: triggers.dcdn.example.com Host: triggers.dcdn.example.com
Accept: */* Accept: */*
Content-Type: application/cdni; ptype=ci-trigger-command.v2 Content-Type: application/cdni; ptype=ci-trigger-command.v2
{ {
"trigger.v2": { <properties of a trigger.v2 object> }, "trigger.v2": { <properties of a trigger.v2 object> },
"cdn-path": [ "AS64496:0" ] "cdn-path": [ "AS64496:0" ]
} }
RESPONSE: RESPONSE:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Date: Wed, 04 May 2016 08:48:10 GMT Date: Wed, 04 May 2016 08:48:10 GMT
Content-Length: 467 Content-Length: 467
Content-Type: application/cdni; ptype=ci-trigger-status.v2 Content-Type: application/cdni; ptype=ci-trigger-status.v2
Location: https://triggers.dcdn.example.com/triggers/0 Location: https://triggers.dcdn.example.com/triggers/0
Server: example-server/0.1 Server: example-server/0.1
{ {
"errors.v2": [ { <properties of 1st error.v2 object> }, "errors.v2": [ { <properties of 1st error.v2 object> },
..., ...,
{ <properties of Nth error.v2 object> } { <properties of Nth error.v2 object> }
], ],
"ctime": 1462351690, "ctime": 1462351690,
"etime": 1462351698, "etime": 1462351698,
"mtime": 1462351690, "mtime": 1462351690,
"status": "pending", "status": "pending",
"trigger.v2": { <properties of a trigger.v2 object> } "trigger.v2": { <properties of a trigger.v2 object> }
} }
Usage example of version 2 of trigger status for the trigger created Usage example of version 2 of trigger status for the trigger created
in the above trigger command example: in the above trigger command example:
REQUEST: REQUEST:
GET /triggers/0 HTTP/1.1 GET /triggers/0 HTTP/1.1
User-Agent: example-user-agent/0.1 User-Agent: example-user-agent/0.1
Host: triggers.dcdn.example.com Host: triggers.dcdn.example.com
Accept: */* Accept: */*
RESPONSE: RESPONSE:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Length: 467 Content-Length: 467
Expires: Wed, 04 May 2016 08:49:10 GMT Expires: Wed, 04 May 2016 08:49:10 GMT
Server: example-server/0.1 Server: example-server/0.1
ETag: "6990548174277557683" ETag: "6990548174277557683"
Cache-Control: max-age=60 Cache-Control: max-age=60
Date: Wed, 04 May 2016 08:48:10 GMT Date: Wed, 04 May 2016 08:48:10 GMT
Content-Type: application/cdni; ptype=ci-trigger-status.v2 Content-Type: application/cdni; ptype=ci-trigger-status.v2
{ {
"errors.v2": [ { <properties of 1st error.v2 object> }, "errors.v2": [ { <properties of 1st error.v2 object> },
..., ...,
{ <properties of Nth error.v2 object> } { <properties of Nth error.v2 object> }
], ],
"ctime": 1462351690, "ctime": 1462351690,
"etime": 1462351698, "etime": 1462351698,
"mtime": 1462351690, "mtime": 1462351690,
"status": "pending", "status": "pending",
"trigger.v2": { <properties of a trigger.v2 object> } "trigger.v2": { <properties of a trigger.v2 object> }
} }
3.2. Error Handling V2 3.2. Error Handling V2
The CDNI CI/T interface defines a mechanism for error reporting (see The CDNI CI/T interface defines a mechanism for error reporting (see
Section 4.7 of [RFC8007]) and an Error Description object for Section 4.7 of [RFC8007]) and an Error Description object for
reporting errors (see Section 5.2.6 of [RFC8007]). This document reporting errors (see Section 5.2.6 of [RFC8007]). This document
specifies version 2 of CI/T error handling in order to support the specifies version 2 of CI/T error handling in order to support the
following: following:
o Extension errors - report an error that happened due to an 3.2.1. Extension Errors
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 Report an error that occures due to an extension object. As
dCDN in which it occurred. CDNI triggers may be propagated over a extension objects are expected to be added to the interface whenever
chain of downstream CDNs. Let us take for example an upstream new requirement comes along, it is expected that in some cases a dCDN
(uCDN-A) CDN A that is delegating to a downstream CDN B (dCDN-B) may receive a trigger that it cannot process or it does not
and dCDN-B is delegating to a downstream CDN C (dCDN-C). Triggers understand. It is therefore essential for the trigger caller to be
sent from uCDN-A to dCDN-B may be redistributed from dCDN-B to able to know when such errors occur so they can take actions to fix
dCDN-C and errors can happen anywhere along the path. Therefore, them. This document adds a mechanism to report extension errors.
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. 3.2.2. Error propagation
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 This subsection explains the mechanism for enabling the uCDN to
description. When a downstream dCDN-B propagates a trigger to traceback an error to the dCDN in which it occurred. CDNI triggers
another downstream dCDN-C, it MUST also propagate back the errors may be propagated over a chain of downstream CDNs. For example, an
received in the trigger status resource from dCDN-C by adding them upstream CDN A (uCDN-A) that is delegating to a downstream CDN B
to the errors array in its own status resource to be sent back to (dCDN-B) and dCDN-B is delegating to a downstream CDN C (dCDN-C).
the originating uCDN-A. While propagating back the errors, and Triggers sent from uCDN-A to dCDN-B may be redistributed from dCDN-B
depending on the implementation, downstream dCDN-B MAY also to dCDN-C and errors can occur anywhere along the path. Therefore,
specify the dCDN-C CDN identifier, indicating that the error it might be essential for uCDN-A that sets the trigger, to be able to
relates spefically to this CDN. The trigger originating upstream trace back an error to the downstream CDN where it occurred. This
CDN will receive an array of errors that occurred in all the CDNs document adds a mechanism to propagate the CDN Provider ID (PID) of
along the execution path, where each error MAY carrying its own the dCDN where the fault occured, back to the uCDN by adding the PID
CDN identifier. 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 3.3. Properties of CI/T Version 2 objects
This section defines the values that can appear in the top-level This section defines the values that can appear in the top-level
objects described in Section 3.1, and their encodings. objects described in Section 3.1, and their encodings.
3.3.1. Trigger Specification Version 2 3.3.1. Trigger Specification Version 2
Version 2 of the Trigger Specification adds the following properties Version 2 of the Trigger Specification adds the following properties
on top of the existing properties of the trigger specification on top of the existing properties of the trigger specification
skipping to change at page 12, line 19 skipping to change at page 14, line 40
Property: extensions Property: extensions
Description: Array of trigger extension data. Description: Array of trigger extension data.
Type: Array of GenericTriggerExtension objects (see Type: Array of GenericTriggerExtension objects (see
Section 3.3.5.2). Section 3.3.5.2).
Mandatory: No. The default is no extensions. Mandatory: No. The default is no extensions.
Example of an invalidation trigger.v2 with a list of regex objects, a Example of a JSON serialized invalidation trigger.v2 object with a
list of playlist objects, and extensions: list of regex objects, a list of playlist objects, and extensions:
{ {
"trigger.v2": { "trigger.v2": {
"type": "invalidate", "type": "invalidate",
"content.regexs": [ <list of RegexMatch objects> ], "content.regexs": [ <list of RegexMatch objects> ],
"content.playlists": [ <list of Playlist objects> ], "content.playlists": [ <list of Playlist objects> ],
"extensions": [ <list of GenericTriggerExtension objects ] "extensions": [ <list of GenericTriggerExtension objects ]
}, },
"cdn-path": [ "AS64496:0" ] "cdn-path": [ "AS64496:0" ]
} }
skipping to change at page 12, line 47 skipping to change at page 15, line 20
Property: regex Property: regex
Description: A regular expression for URI matching. Description: A regular expression for URI matching.
Type: A regular expression to match against the URI, i.e Type: A regular expression to match against the URI, i.e
against the path-absolute and the query string parameters against the path-absolute and the query string parameters
[RFC3986]. The regular expression string MUST be compatible [RFC3986]. The regular expression string MUST be compatible
with PCRE [PCRE841]. with PCRE [PCRE841].
Note: Because '\' has special meaning in JSON [RFC8259] as the Note: Because '\' has a special meaning in JSON [RFC8259] as
escape character within JSON strings, the regular expression the escape character within JSON strings, the regular
character '\' MUST be escaped as '\\'. expression character '\' MUST be escaped as '\\'.
Mandatory: Yes. Mandatory: Yes.
Property: case-sensitive Property: case-sensitive
Description: Flag indicating whether or not case-sensitive Description: Flag indicating whether or not case-sensitive
matching should be used. matching should be used.
Type: JSON boolean. Either "true" (the matching is case Type: JSON boolean. Either "true" (the matching is case
sensitive) or "false" (the matching is case insensitive). sensitive) or "false" (the matching is case insensitive).
skipping to change at page 14, line 33 skipping to change at page 17, line 7
Property: media-protocol Property: media-protocol
Description: Media protocol to be when parsing and interpreting Description: Media protocol to be when parsing and interpreting
this playlist. this playlist.
Type: MediaProtocol (see Section 3.3.4). Type: MediaProtocol (see Section 3.3.4).
Mandatory: Yes. Mandatory: Yes.
Example of a HLS playlist: Example of a JSON serialized HLS playlist object:
{ {
"playlist": "https://www.example.com/hls/title/index.m3u8", "playlist": "https://www.example.com/hls/title/index.m3u8",
"media-protocol": "hls" "media-protocol": "hls"
} }
3.3.4. MediaProtocol 3.3.4. MediaProtocol
Media Protocol objects are used to specify registered type of media Media Protocol objects are used to specify registered type of media
protocol (see Section 6.3) used for protocol related operations like protocol (see Section 6.3) used for protocol related operations like
skipping to change at page 15, line 34 skipping to change at page 18, line 7
The GenericTriggerExtension object defines the properties contained The GenericTriggerExtension object defines the properties contained
within it as well as whether or not the properties are "mandatory-to- 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". If the dCDN does not understand or support a mandatory-to-
enforce property, the dCDN MUST NOT execute the trigger command. If enforce property, the dCDN MUST NOT execute the trigger command. If
the extension is not mandatory-to-enforce, then that the extension is not mandatory-to-enforce, then that
GenericTriggerExtension object can be safely ignored and the trigger GenericTriggerExtension object can be safely ignored and the trigger
command can be processed in accordance with the rest of the CDNI command can be processed in accordance with the rest of the CDNI
Trigger spec. Trigger spec.
Although a CDN MUST NOT execute a trigger command if a mandatory-to- Although, a CDN MUST NOT execute a trigger command if a mandatory-to-
enforce extension cannot be enforced, it could still be safe to enforce extension cannot be enforced, it could still be safe to
redistribute that trigger (the "safe-to-redistribute" property) to redistribute that trigger (the "safe-to-redistribute" property) to
another CDN without modification. For example, in the cascaded CDN another CDN without modification. For example, in the cascaded CDN
case, a transit CDN (tCDN) could convey mandatory-to-enforce trigger case, a transit CDN (tCDN) could convey mandatory-to-enforce trigger
extension to a dCDN. For a trigger extension that does not require extension to a dCDN. For a trigger extension that does not require
customization or translation (i.e., trigger extension that is safe- customization or translation (i.e., trigger extension that is safe-
to-redistribute), the data representation received off the wire MAY to-redistribute), the data representation received off the wire MAY
be stored and redistributed without being understood or supported by be stored and redistributed without being understood or supported by
the tCDN. However, for trigger extension that requires translation, the tCDN. However, for trigger extension that requires translation,
transparent redistribution of the uCDN trigger values might not be transparent redistribution of the uCDN trigger values might not be
skipping to change at page 19, line 41 skipping to change at page 21, line 41
chain of delegation has failed to understand and/or failed to chain of delegation has failed to understand and/or failed to
properly transform this trigger extension object. Note: This properly transform this trigger extension object. Note: This
flag only applies to trigger extension objects whose safe-to- flag only applies to trigger extension objects whose safe-to-
redistribute property has a value of False. redistribute property has a value of False.
Type: Boolean Type: Boolean
Mandatory: No. Default is comprehensible (i.e., a value of Mandatory: No. Default is comprehensible (i.e., a value of
False). False).
Example of a GenericTriggerExtension containing a specific trigger Example of a JSON serialized GenericTriggerExtension object
extension object: containing a specific trigger extension object:
{ {
"generic-trigger-extension-type": "generic-trigger-extension-type":
<Type of this trigger extension object>, <Type of this trigger extension object>,
"generic-trigger-extension-value": "generic-trigger-extension-value":
{ {
<properties of this trigger extension object> <properties of this trigger extension object>
}, },
"mandatory-to-enforce": true, "mandatory-to-enforce": true,
"safe-to-redistribute": true, "safe-to-redistribute": true,
skipping to change at page 21, line 25 skipping to change at page 23, line 25
The "cdn" property is used by the originating uCDN or by The "cdn" property is used by the originating uCDN or by
propagating dCDN in order to distinguish in which CDN the error propagating dCDN in order to distinguish in which CDN the error
occured. occured.
Type: A non-empty JSON string, where the string is a CDN PID as Type: A non-empty JSON string, where the string is a CDN PID as
defined in Section 4.6 of [RFC8007]. defined in Section 4.6 of [RFC8007].
Mandatory: Yes. In the case the dCDN does not like to expose Mandatory: Yes. In the case the dCDN does not like to expose
this information, it should provide its own CDN PID. this information, it should provide its own CDN PID.
Example of an Error Description object reporting a malformed Example of a JSON serialized Error Description object reporting a
Playlist: malformed Playlist:
{ {
"content.playlists": [ "content.playlists": [
{ {
"playlist": "https://www.example.com/hls/title/index.m3u8", "playlist": "https://www.example.com/hls/title/index.m3u8",
"media-protocol": "hls" "media-protocol": "hls"
} }
], ],
"description": "Failed to parse HLS playlist", "description": "Failed to parse HLS playlist",
"error": "econtent", "error": "econtent",
"cdn": "AS64500:0" "cdn": "AS64500:0"
}, },
Example of an Error Description object reporting an unsupported Example of a JSON serialized Error Description object reporting an
extension object: unsupported extension object:
{ {
"errors.v2": [ "errors.v2": [
{ {
"extensions": [ "extensions": [
{ {
"generic-trigger-extension-type": "generic-trigger-extension-type":
<Type of this erroneous trigger extension object>, <Type of this erroneous trigger extension object>,
"generic-trigger-extension-value": "generic-trigger-extension-value":
{ {
<properties of this erroneous trigger extension object> <properties of this erroneous trigger extension object>
}, },
} }
], ],
"description": "unrecognized extension <type>", "description": "unrecognized extension <type>",
"error": "eextension", "error": "eextension",
"cdn": "AS64500:0" "cdn": "AS64500:0"
}, },
] ]
} }
3.3.7. Error codes 3.3.7. Error codes
This document adds the error code "eextension" to the error codes This document adds the error code "eextension" to the error codes
table defined in Section 5.2.6 of [RFC8007]. This error code table defined in Section 5.2.6 of [RFC8007]. This error code
designates that an error occurred while parsing a generic trigger designates that an error occurred while parsing a generic trigger
extension, or that the specific extension is not supported by the extension, or that the specific extension is not supported by the
CDN. A CDN that fails to execute a trigger due a generic extension CDN. A CDN that fails to execute a trigger due a generic extension
object which is "mandatory-to-enforce" MUST report it using the object which is "mandatory-to-enforce" MUST report it using the
"errors.v2" array within the trigger status resource, while setting "errors.v2" array within the trigger status resource, while setting
skipping to change at page 22, line 51 skipping to change at page 24, line 51
interface extensions being used by the trigger command and status interface extensions being used by the trigger command and status
resource. resource.
3.4.1. Invalidation with Regex 3.4.1. Invalidation with Regex
In the following example a CI/T "invalidate" command uses the Regex In the following example a CI/T "invalidate" command uses the Regex
property to specify the range of content objects for invalidation, property to specify the range of content objects for invalidation,
the command is rejected by the dCDN due to regex complexity, and an the command is rejected by the dCDN due to regex complexity, and an
appropriate error is reflected in the status response. appropriate error is reflected in the status response.
REQUEST: REQUEST:
POST /triggers HTTP/1.1 POST /triggers HTTP/1.1
User-Agent: example-user-agent/0.1 User-Agent: example-user-agent/0.1
Host: triggers.dcdn.example.com Host: triggers.dcdn.example.com
Accept: */* Accept: */*
Content-Type: application/cdni; ptype=ci-trigger-command.v2 Content-Type: application/cdni; ptype=ci-trigger-command.v2
{ {
"trigger.v2": { "trigger.v2": {
"type": "invalidate", "type": "invalidate",
"content.regexs": [ "content.regexs": [
{ {
"regex": "^(https:\\/\\/video\\.example\\.com)\\/ "regex": "^(https:\\/\\/video\\.example\\.com)\\/
([a-z])\\/movie1\\/([1-7])\\/*(index.m3u8|\\d{3}.ts)$", ([a-z])\\/movie1\\/([1-7])\\/*(index.m3u8|\\d{3}.ts)$",
"case-sensitive": true, "case-sensitive": true,
"match-query-string": false "match-query-string": false
}, },
{ <RegexMatch #2> }, { <RegexMatch #2> },
... ...
{ <RegexMatch #N> }, { <RegexMatch #N> },
], ],
}, },
"cdn-path": [ "AS64496:0" ] "cdn-path": [ "AS64496:0" ]
} }
RESPONSE: RESPONSE:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Date: Wed, 04 May 2016 08:48:10 GMT Date: Wed, 04 May 2016 08:48:10 GMT
Content-Length: 467 Content-Length: 467
Content-Type: application/cdni; ptype=ci-trigger-status.v2 Content-Type: application/cdni; ptype=ci-trigger-status.v2
Location: https://triggers.dcdn.example.com/triggers/0 Location: https://triggers.dcdn.example.com/triggers/0
Server: example-server/0.1 Server: example-server/0.1
{ {
"errors.v2": [ "errors.v2": [
{ {
"content.regexs": [ "content.regexs": [
{ {
"regex": "^(https:\\/\\/video\\.example\\.com)\\/ "regex": "^(https:\\/\\/video\\.example\\.com)\\/
([a-z])\\/movie1\\/([1-7])\\/*(index.m3u8|\\d{3}.ts)$", ([a-z])\\/movie1\\/([1-7])\\/*(index.m3u8|\\d{3}.ts)$",
"case-sensitive": true, "case-sensitive": true,
"match-query-string": false "match-query-string": false
}, },
], ],
"description": "The dCDN rejected a regex due to complexity", "description": "The dCDN rejected a regex due to complexity",
"error": "ereject", "error": "ereject",
"cdn": "AS64500:0" "cdn": "AS64500:0"
}, },
], ],
"ctime": 1462351690, "ctime": 1462351690,
"etime": 1462351698, "etime": 1462351698,
"mtime": 1462351690, "mtime": 1462351690,
"status": "failed", "status": "failed",
"trigger.v2": { <content of trigger object from the command> } "trigger.v2": { <content of trigger object from the command> }
} }
3.4.2. Preposition with Playlists 3.4.2. Preposition with Playlists
In the following example a CI/T "preposition" command uses the In the following example a CI/T "preposition" command uses the
Playlist property to specify the full media library of a specific Playlist property to specify the full media library of a specific
content. The command fails due to playlist parse error and an content. The command fails due to playlist parse error and an
appropriate error is reflected in the status response. appropriate error is reflected in the status response.
REQUEST: REQUEST:
POST /triggers HTTP/1.1 POST /triggers HTTP/1.1
User-Agent: example-user-agent/0.1 User-Agent: example-user-agent/0.1
Host: triggers.dcdn.example.com Host: triggers.dcdn.example.com
Accept: */* Accept: */*
Content-Type: application/cdni; ptype=ci-trigger-command.v2 Content-Type: application/cdni; ptype=ci-trigger-command.v2
{ {
"trigger.v2": { "trigger.v2": {
"type": "preposition", "type": "preposition",
"content.playlists": [ "content.playlists": [
{ {
"playlist": "https://www.example.com/hls/title/index.m3u8", "playlist": "https://www.example.com/hls/title/index.m3u8",
"media-protocol": "hls" "media-protocol": "hls"
}, },
{ <Playlist #2> }, { <Playlist #2> },
... ...
{ <Playlist #N> }, { <Playlist #N> },
], ],
}, },
"cdn-path": [ "AS64496:0" ] "cdn-path": [ "AS64496:0" ]
} }
RESPONSE: RESPONSE:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Date: Wed, 04 May 2016 08:48:10 GMT Date: Wed, 04 May 2016 08:48:10 GMT
Content-Length: 467 Content-Length: 467
Content-Type: application/cdni; ptype=ci-trigger-status.v2 Content-Type: application/cdni; ptype=ci-trigger-status.v2
Location: https://triggers.dcdn.example.com/triggers/0 Location: https://triggers.dcdn.example.com/triggers/0
Server: example-server/0.1 Server: example-server/0.1
{ {
"errors.v2": [ "errors.v2": [
{ {
"content.playlists": [ "content.playlists": [
{ {
"playlist": "https://www.example.com/hls/title/index.m3u8", "playlist": "https://www.example.com/hls/title/index.m3u8",
"media-protocol": "hls" "media-protocol": "hls"
}, },
], ],
"description": "The dCDN was not able to parse the playlist", "description": "The dCDN was not able to parse the playlist",
"error": "econtent", "error": "econtent",
"cdn": "AS64500:0" "cdn": "AS64500:0"
}, },
], ],
"ctime": 1462351690, "ctime": 1462351690,
"etime": 1462351698, "etime": 1462351698,
"mtime": 1462351690, "mtime": 1462351690,
"status": "failed", "status": "failed",
"trigger.v2": { <content of trigger object from the command> } "trigger.v2": { <content of trigger object from the command> }
} }
3.4.3. Extensions with Error Propagation 3.4.3. Extensions with Error Propagation
In the following example a CI/T "preposition" command is using two In the following example a CI/T "preposition" command is using two
extensions to control the way the trigger is executed. In this extensions to control the way the trigger is executed. In this
example the receiving dCDN identified as "AS64500:0" does not support example the receiving dCDN identified as "AS64500:0" does not support
the first extension in the extensions array. dCDN "AS64500:0" further the first extension in the extensions array. dCDN "AS64500:0" further
distributes this trigger to another downstream CDN that is identified distributes this trigger to another downstream CDN that is identified
as "AS64501:0", which does not support the second extension in the 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. "AS64500:0" and the errors.v2 array reflects both errors.
REQUEST: REQUEST:
POST /triggers HTTP/1.1 POST /triggers HTTP/1.1
User-Agent: example-user-agent/0.1 User-Agent: example-user-agent/0.1
Host: triggers.dcdn.example.com Host: triggers.dcdn.example.com
Accept: */* Accept: */*
Content-Type: application/cdni; ptype=ci-trigger-command.v2 Content-Type: application/cdni; ptype=ci-trigger-command.v2
{ {
"trigger.v2": { "trigger.v2": {
"type": "preposition", "type": "preposition",
"content.playlists": [ "content.playlists": [
{ {
"playlist": "https://www.example.com/hls/title/index.m3u8", "playlist": "https://www.example.com/hls/title/index.m3u8",
"media-protocol": "hls" "media-protocol": "hls"
}, },
], ],
"extensions": [ "extensions": [
{ {
"generic-trigger-extension-type": "generic-trigger-extension-type":
<Type of trigger extension object #1>, <Type of trigger extension object #1>,
"generic-trigger-extension-value": "generic-trigger-extension-value":
{ {
<properties of trigger extension object #1> <properties of trigger extension object #1>
}, },
"mandatory-to-enforce": true, "mandatory-to-enforce": true,
"safe-to-redistribute": true, "safe-to-redistribute": true,
}, },
{ {
"generic-trigger-extension-type": "generic-trigger-extension-type":
<Type of trigger extension object #2>, <Type of trigger extension object #2>,
"generic-trigger-extension-value": "generic-trigger-extension-value":
{ {
<properties of trigger extension object #2> <properties of trigger extension object #2>
}, },
"mandatory-to-enforce": true, "mandatory-to-enforce": true,
"safe-to-redistribute": true, "safe-to-redistribute": true,
}, },
], ],
}, },
"cdn-path": [ "AS64496:0" ] "cdn-path": [ "AS64496:0" ]
} }
RESPONSE: RESPONSE:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Date: Wed, 04 May 2016 08:48:10 GMT Date: Wed, 04 May 2016 08:48:10 GMT
Content-Length: 467 Content-Length: 467
Content-Type: application/cdni; ptype=ci-trigger-status.v2 Content-Type: application/cdni; ptype=ci-trigger-status.v2
Location: https://triggers.dcdn.example.com/triggers/0 Location: https://triggers.dcdn.example.com/triggers/0
Server: example-server/0.1 Server: example-server/0.1
{ {
"errors.v2": [ "errors.v2": [
{ {
"extensions": [ "extensions": [
{ {
"generic-trigger-extension-type": "generic-trigger-extension-type":
<Type of trigger extension object #1>, <Type of trigger extension object #1>,
"generic-trigger-extension-value": "generic-trigger-extension-value":
{ {
<properties of trigger extension object #1> <properties of trigger extension object #1>
}, },
"mandatory-to-enforce": true, "mandatory-to-enforce": true,
"safe-to-redistribute": true, "safe-to-redistribute": true,
}, },
], ],
"description": "unrecognized extension <type>", "description": "unrecognized extension <type>",
"error": "eextension", "error": "eextension",
"cdn": "AS64500:0" "cdn": "AS64500:0"
}, },
{ {
"extensions": [ "extensions": [
{ {
"generic-trigger-extension-type": "generic-trigger-extension-type":
<Type of trigger extension object #2>, <Type of trigger extension object #2>,
"generic-trigger-extension-value": "generic-trigger-extension-value":
{ {
<properties of trigger extension object #2> <properties of trigger extension object #2>
}, },
"mandatory-to-enforce": true, "mandatory-to-enforce": true,
"safe-to-redistribute": true, "safe-to-redistribute": true,
}, },
], ],
"description": "unrecognized extension <type>", "description": "unrecognized extension <type>",
"error": "eextension", "error": "eextension",
"cdn": "AS64501:0" "cdn": "AS64501:0"
}, },
], ],
"ctime": 1462351690, "ctime": 1462351690,
"etime": 1462351698, "etime": 1462351698,
"mtime": 1462351690, "mtime": 1462351690,
"status": "failed", "status": "failed",
"trigger.v2": { <content of trigger object from the command> } "trigger.v2": { <content of trigger object from the command> }
} }
4. Trigger Extension Objects 4. Trigger Extension Objects
The objects defined below are intended to be used in the The objects defined below are intended to be used in the
GenericTriggerExtension object's generic-trigger-extension-value GenericTriggerExtension object's generic-trigger-extension-value
field as defined in Section Section 3.3.5.2, and their generic- field as defined in Section Section 3.3.5.2, and their generic-
trigger-extension-type property MUST be set to the appropriate CDNI trigger-extension-type property MUST be set to the appropriate CDNI
Payload Type as defined in Section 6.1 . Payload Type as defined in Section 6.1 .
4.1. LocationPolicy extension 4.1. LocationPolicy extension
skipping to change at page 28, line 15 skipping to change at page 30, line 15
Example use cases: Example use cases:
o Pre-position: Certain contracts allow for pre-positioning or o Pre-position: Certain contracts allow for pre-positioning or
availability of contract in all regions except for certain availability of contract in all regions except for certain
excluded regions in the world, including caches. For example, excluded regions in the world, including caches. For example,
some content cannot ever knowingly touch servers in a specific some content cannot ever knowingly touch servers in a specific
country, including cached content. Therefore, these regions MUST country, including cached content. Therefore, these regions MUST
be excluded from a pre-positioning operation. be excluded from a pre-positioning operation.
o Purge: In certain cases, content may have been located on servers 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, purge operation to remove content specifically from that region,
is required. is required.
Object specification Object specification
Property: locations Property: locations
Description: An Access List that allows or denies (blocks) the Description: An Access List that allows or denies (blocks) the
trigger execution per cache location. trigger execution per cache location.
skipping to change at page 28, line 44 skipping to change at page 30, line 44
The trigger command is allowed, or denied, for a specific cache The trigger command is allowed, or denied, for a specific cache
location according to the action of the first location whose location according to the action of the first location whose
footprint matches against that cache's location. If two or more footprint matches against that cache's location. If two or more
footprints overlap, the first footprint that matches against the footprints overlap, the first footprint that matches against the
cache's location determines the action a CDN MUST take. If 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 "locations" property is an empty list or if none of the listed
footprints match the location of a specific cache location, then the footprints match the location of a specific cache location, then the
result is equivalent to a "deny" action. result is equivalent to a "deny" action.
The following is an example of generic trigger extension object The following is an example of a JSON serialized generic trigger
containing a location policy object that allows the trigger execution extension object containing a location policy object that allows the
in the US but blocks its execution in Canada: trigger execution in the US but blocks its execution in Canada:
{ {
"generic-trigger-extension-type": "CIT.LocationPolicy", "generic-trigger-extension-type": "CIT.LocationPolicy",
"generic-trigger-extension-value": "generic-trigger-extension-value":
{ {
"locations": [ "locations": [
{ {
"action": "allow", "action": "allow",
"footprints": [ "footprints": [
{ {
skipping to change at page 31, line 10 skipping to change at page 33, line 10
Type: LocalTimeWindow object as defined in Section 4.2.2. Type: LocalTimeWindow object as defined in Section 4.2.2.
Mandatory: No, but exactly one of "unixEpochWindow", Mandatory: No, but exactly one of "unixEpochWindow",
"utcWindow" or "localTimeWindow" MUST be present. "utcWindow" or "localTimeWindow" MUST be present.
If a time policy object is not listed within the trigger command, the 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 default behavior is to execute the trigger in a time frame most
suitable to the dCDN taking under consideration other constrains and suitable to the dCDN taking under consideration other constrains and
/ or obligations. / or obligations.
Example of a generic trigger extension object containing a time Example of a JSON serialized generic trigger extension object
policy object that schedules the trigger execution to a window containing a time policy object that schedules the trigger execution
between 09:00 01/01/2000 UTC and 17:00 01/01/2000 UTC, using the to a window between 09:00 01/01/2000 UTC and 17:00 01/01/2000 UTC,
"unix-time-window" property: using the "unix-time-window" property:
{ {
"generic-trigger-extension-type": "CIT.TimePolicy", "generic-trigger-extension-type": "CIT.TimePolicy",
"generic-trigger-extension-value": "generic-trigger-extension-value":
{ {
"unix-time-window": { "unix-time-window": {
"start": 946717200, "start": 946717200,
"end": 946746000 "end": 946746000
} }
} }
skipping to change at page 32, line 5 skipping to change at page 34, line 5
Property: end 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]. Type: Internet date and time as defined in [RFC3339].
Mandatory: No, but at least one of "start" or "end" MUST be Mandatory: No, but at least one of "start" or "end" MUST be
present and non-empty. present and non-empty.
Example UTCWindow object that describes a time window from 02:30 Example JSON serialized UTCWindow object that describes a time window
01/01/2000 UTC to 04:30 01/01/2000 UTC: from 02:30 01/01/2000 UTC to 04:30 01/01/2000 UTC:
{ {
"start": 2000-01-01T02:30:00.00Z, "start": 2000-01-01T02:30:00.00Z,
"end": 2000-01-01T04:30:00.00Z, "end": 2000-01-01T04:30:00.00Z,
} }
Example UTCWindow object that describes a time window in New York Example JSON serialized UTCWindow object that describes a time window
time zone offset UTC-05:00 from 02:30 01/01/2000 to 04:30 01/01/2000: 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, "start": 2000-01-01T02:30:00.00-05:00,
"end": 2000-01-01T04:30:00.00-05:00, "end": 2000-01-01T04:30:00.00-05:00,
} }
4.2.2. LocalTimeWindow 4.2.2. LocalTimeWindow
A LocalTimeWindow object describes a time range in local time. The A LocalTimeWindow object describes a time range in local time. The
reader of this object MUST interpret it as "the local time at the reader of this object MUST interpret it as "the local time at the
skipping to change at page 32, line 50 skipping to change at page 34, line 51
Property: end Property: end
Description: The end time of the window. Description: The end time of the window.
Type: JSON string formatted as DateLocalTime as defined in Type: JSON string formatted as DateLocalTime as defined in
Section 4.2.3. Section 4.2.3.
Mandatory: No, but at least one of "start" or "end" MUST be Mandatory: No, but at least one of "start" or "end" MUST be
present and non-empty. present and non-empty.
Example LocalTimeWindow object that describes a local time window Example JSON serialized LocalTimeWindow object that describes a local
from 02:30 01/01/2000 to 04:30 01/01/2000. time window from 02:30 01/01/2000 to 04:30 01/01/2000.
{ {
"start": 2000-01-01T02:30:00.00, "start": 2000-01-01T02:30:00.00,
"end": 2000-01-01T04:30:00.00, "end": 2000-01-01T04:30:00.00,
} }
4.2.3. DateLocalTime 4.2.3. DateLocalTime
DateLocalTime is a timestamp that follows the date and local time 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 notation in Section 4.3.2 of [ISO8601] as a complete date and time
skipping to change at page 35, line 13 skipping to change at page 37, line 13
Description: A list of version numbers. Description: A list of version numbers.
Type: An array of JSON strings Type: An array of JSON strings
Mandatory: No. The default is version 1. A missing or an Mandatory: No. The default is version 1. A missing or an
empty versions list means that only version 1 of the interface empty versions list means that only version 1 of the interface
and objects is supported. and objects is supported.
5.1.1. CI/T Versions Capability Object Serialization 5.1.1. CI/T Versions Capability Object Serialization
The following shows an example of CI/T Versions Capability object The following shows an example of a JSON serialized CI/T Versions
serialization for a dCDN that supports versions 2 and 2.1 of the CI/T Capability object serialization for a dCDN that supports versions 2
interface. and 2.1 of the CI/T interface.
{ {
"capabilities": [ "capabilities": [
{ {
"capability-type": "FCI.TriggerVersion", "capability-type": "FCI.TriggerVersion",
"capability-value": { "capability-value": {
"versions": [ "1", "2", "2.1" ] "versions": [ "1", "2", "2.1" ]
}, },
"footprints": [ "footprints": [
<Footprint objects> <Footprint objects>
skipping to change at page 35, line 49 skipping to change at page 37, line 49
Description: A list of media protocols. Description: A list of media protocols.
Type: A list of MediaProtocol (from the CDNI Triggers media Type: A list of MediaProtocol (from the CDNI Triggers media
protocol types Section 6.3) protocol types Section 6.3)
Mandatory: No. The default, in case of a missing or an empty Mandatory: No. The default, in case of a missing or an empty
list, is none supported. list, is none supported.
5.2.1. CI/T Playlist Protocol Capability Object Serialization 5.2.1. CI/T Playlist Protocol Capability Object Serialization
The following shows an example of CI/T Playlist Protocol Capability The following shows an example of a JSON serialized CI/T Playlist
object serialization for a dCDN that supports "hls" and "dash". Protocol Capability object serialization for a dCDN that supports
"hls" and "dash".
{ {
"capabilities": [ "capabilities": [
{ {
"capability-type": "FCI.TriggerPlaylistProtocol", "capability-type": "FCI.TriggerPlaylistProtocol",
"capability-value": { "capability-value": {
"media-protocols": ["hls", "dash"] "media-protocols": ["hls", "dash"]
}, },
"footprints": [ "footprints": [
<Footprint objects> <Footprint objects>
skipping to change at page 36, line 42 skipping to change at page 38, line 42
GenericExtensionObject objects. GenericExtensionObject objects.
Mandatory: No. The default, in case of a missing or an empty Mandatory: No. The default, in case of a missing or an empty
list, MUST be interpreted as "no GenericExtensionObject types list, MUST be interpreted as "no GenericExtensionObject types
are supported". A non-empty list MUST be interpreted as are supported". A non-empty list MUST be interpreted as
containing "the only GenericExtensionObject types that are containing "the only GenericExtensionObject types that are
supported". supported".
5.3.1. CI/T Trigger Extension Capability Object Serialization 5.3.1. CI/T Trigger Extension Capability Object Serialization
The following shows an example of CI/T Trigger Extension Capability The following shows an example of a JSON serialized CI/T Trigger
object serialization for a dCDN that supports the Extension Capability object serialization for a dCDN that supports
"CIT.LocationPolicy" and the "CIT.TimePolicy" objects. the "CIT.LocationPolicy" and the "CIT.TimePolicy" objects.
{ {
"capabilities": [ "capabilities": [
{ {
"capability-type": "FCI.TriggerGenericExtension", "capability-type": "FCI.TriggerGenericExtension",
"capability-value": { "capability-value": {
"trigger-extension": ["CIT.LocationPolicy", "CIT.TimePolicy"] "trigger-extension": ["CIT.LocationPolicy", "CIT.TimePolicy"]
}, },
"footprints": [ "footprints": [
<Footprint objects> <Footprint objects>
skipping to change at page 40, line 27 skipping to change at page 42, line 27
[RFC Editor: Please replace RFCthis with the published RFC number for [RFC Editor: Please replace RFCthis with the published RFC number for
this document.] this document.]
7. Security Considerations 7. Security Considerations
All security considerations listed in Section 8 of [RFC8007] and All security considerations listed in Section 8 of [RFC8007] and
Section 7 of [RFC8008] apply to this document as well. Section 7 of [RFC8008] apply to this document as well.
This document defines the capability to use regular expression within This document defines the capability to use regular expression within
the trigger spec for more granular content selection. The usage of the trigger specification for more granular content selection. The
regex introduced the risk of regex complexity attacks, a.k.a ReDos usage of regex introduced the risk of regex complexity attacks, a.k.a
attacks. An attacker may be able to craft a regular expression that ReDos attacks. An attacker may be able to craft a regular expression
can exhaust server resources and may take exponential time in the that can exhaust server resources and may take exponential time in
worst case. An implementation MUST protect itself by at least accept the worst case. An implementation MUST protect itself at a minimum
triggers only from an authenticated party over a secured connection. by accepting triggers only from an authenticated party over a secured
An implementation SHOULD also protect itself by using secure connection. An implementation SHOULD also protect itself by using
programing techniques and decline trigger commands that use secure programing techniques and decline trigger commands that use
potentially risky regex, such techniques are readily available in potentially risky regex, such techniques are readily available in
secure programming literature and are beyond the scope of this secure programming literature and are beyond the scope of this
document. document.
8. Acknowledgments 8. Acknowledgments
TBD TBD
9. Contributors 9. Contributors
The authors would like to thank all members of the "Streaming Video The authors thank all members of the "Streaming Video Alliance" (SVA)
Alliance" (SVA) Open Caching Working Group for their contribution in and specifically contributions by members of Open Caching Working
support of this document. Group in support of this document. The authors also thank Kevin Ma
for his guidance and careful and methodical reviews.
10. References 10. References
10.1. Normative References 10.1. Normative References
[ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008, DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>. <https://www.rfc-editor.org/info/rfc5234>.
skipping to change at page 41, line 28 skipping to change at page 43, line 28
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<https://www.rfc-editor.org/info/rfc3339>. <https://www.rfc-editor.org/info/rfc3339>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>. <https://www.rfc-editor.org/info/rfc3986>.
[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, <https://www.rfc-editor.org/info/rfc6707>.
[RFC7736] Ma, K., "Content Delivery Network Interconnection (CDNI)
Media Type Registration", RFC 7736, DOI 10.17487/RFC7736,
December 2015, <https://www.rfc-editor.org/info/rfc7736>.
[RFC8006] Niven-Jenkins, B., Murray, R., Caulfield, M., and K. Ma, [RFC8006] Niven-Jenkins, B., Murray, R., Caulfield, M., and K. Ma,
"Content Delivery Network Interconnection (CDNI) "Content Delivery Network Interconnection (CDNI)
Metadata", RFC 8006, DOI 10.17487/RFC8006, December 2016, Metadata", RFC 8006, DOI 10.17487/RFC8006, December 2016,
<https://www.rfc-editor.org/info/rfc8006>. <https://www.rfc-editor.org/info/rfc8006>.
[RFC8007] Murray, R. and B. Niven-Jenkins, "Content Delivery Network [RFC8007] Murray, R. and B. Niven-Jenkins, "Content Delivery Network
Interconnection (CDNI) Control Interface / Triggers", Interconnection (CDNI) Control Interface / Triggers",
RFC 8007, DOI 10.17487/RFC8007, December 2016, RFC 8007, DOI 10.17487/RFC8007, December 2016,
<https://www.rfc-editor.org/info/rfc8007>. <https://www.rfc-editor.org/info/rfc8007>.
skipping to change at page 42, line 35 skipping to change at page 44, line 45
<https://www.streamingvideoalliance.org/document/open- <https://www.streamingvideoalliance.org/document/open-
caching-content-management-operations-specification/>. caching-content-management-operations-specification/>.
[OCWG] Streaming Video Alliance, "Open Caching", [OCWG] Streaming Video Alliance, "Open Caching",
<https://www.streamingvideoalliance.org/technical-groups/ <https://www.streamingvideoalliance.org/technical-groups/
open-caching/>. open-caching/>.
[PCRE841] Hazel, P., "Perl Compatible Regular Expressions", [PCRE841] Hazel, P., "Perl Compatible Regular Expressions",
Version 8.41, July 2017, <http://www.pcre.org/>. Version 8.41, July 2017, <http://www.pcre.org/>.
[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, <https://www.rfc-editor.org/info/rfc6707>.
[RFC7736] Ma, K., "Content Delivery Network Interconnection (CDNI)
Media Type Registration", RFC 7736, DOI 10.17487/RFC7736,
December 2015, <https://www.rfc-editor.org/info/rfc7736>.
[RFC8216] Pantos, R., Ed. and W. May, "HTTP Live Streaming", [RFC8216] Pantos, R., Ed. and W. May, "HTTP Live Streaming",
RFC 8216, DOI 10.17487/RFC8216, August 2017, RFC 8216, DOI 10.17487/RFC8216, August 2017,
<https://www.rfc-editor.org/info/rfc8216>. <https://www.rfc-editor.org/info/rfc8216>.
[SVA] "Streaming Video Alliance", [SVA] "Streaming Video Alliance",
<https://www.streamingvideoalliance.org>. <https://www.streamingvideoalliance.org>.
Authors' Addresses Authors' Addresses
Ori Finkelman Ori Finkelman
 End of changes. 65 change blocks. 
397 lines changed or deleted 508 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/