idnits 2.17.1 draft-ietf-cdni-ci-triggers-rfc8007bis-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 6 instances of too long lines in the document, the longest one being 7 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Name: specs Description: Array of trigger spec objects based on from the corresponding "specs" array at the Trigger Specification. Each such spec holds in its "generic-trigger-spec-value" array only those values to which the error applies. TBD: Option 1: Specs with no failing values MAY(TODO?) be omitted. Option 2: Note that the order of the specs should be as listed in the Trigger Specification. Specs with no failing values MUST not be omitted but MAY(TODO?) be replaced with an empty object for simplicity. -- The document date (2 March 2022) is 778 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: '1-7' is mentioned on line 2822, but not defined ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 5 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group O. Finkelman 3 Internet-Draft Qwilt 4 Obsoletes: 8007 (if approved) S. Mishra 5 Intended status: Standards Track Verizon 6 Expires: 3 September 2022 N.B. Sopher 7 Qwilt 8 2 March 2022 10 Content Delivery Network Interconnection (CDNI) Control Interface / 11 Triggers 2nd Edition 12 draft-ietf-cdni-ci-triggers-rfc8007bis-01 14 Abstract 16 This document obsoletes RFC8007. This document describes the part of 17 the Content Delivery Network Interconnection (CDNI) Control interface 18 that allows a CDN to trigger activity in an interconnected CDN that 19 is configured to deliver content on its behalf. The upstream CDN can 20 use this mechanism to request that the downstream CDN pre-position 21 metadata or content or to request that it invalidate or purge 22 metadata or content. The upstream CDN can monitor the status of 23 activity that it has triggered in the downstream CDN. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on 3 September 2022. 42 Copyright Notice 44 Copyright (c) 2022 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 49 license-info) in effect on the date of publication of this document. 50 Please review these documents carefully, as they describe your rights 51 and restrictions with respect to this document. Code Components 52 extracted from this document must include Revised BSD License text as 53 described in Section 4.e of the Trust Legal Provisions and are 54 provided without warranty as described in the Revised BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 59 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 60 2. Model for CDNI Triggers . . . . . . . . . . . . . . . . . . . 5 61 2.1. Timing of Triggered Activity . . . . . . . . . . . . . . 8 62 2.2. Scope of Triggered Activity . . . . . . . . . . . . . . . 8 63 2.2.1. Multiple Interconnected CDNs . . . . . . . . . . . . 8 64 2.3. Trigger Results . . . . . . . . . . . . . . . . . . . . . 10 65 3. Trigger Spec . . . . . . . . . . . . . . . . . . . . . . . . 10 66 3.1. Content URLs . . . . . . . . . . . . . . . . . . . . . . 11 67 4. Trigger Extensibility . . . . . . . . . . . . . . . . . . . . 11 68 5. Collections of Trigger Status Resources . . . . . . . . . . . 12 69 6. CDNI Trigger Interface . . . . . . . . . . . . . . . . . . . 13 70 6.1. Creating Triggers . . . . . . . . . . . . . . . . . . . . 14 71 6.2. Checking Status . . . . . . . . . . . . . . . . . . . . . 15 72 6.2.1. Polling Trigger Status Resource Collections . . . . . 15 73 6.2.2. Polling Trigger Status Resources . . . . . . . . . . 16 74 6.3. Canceling Triggers . . . . . . . . . . . . . . . . . . . 16 75 6.4. Deleting Triggers . . . . . . . . . . . . . . . . . . . . 17 76 6.5. Expiry of Trigger Status Resources . . . . . . . . . . . 17 77 6.6. Loop Detection and Prevention . . . . . . . . . . . . . . 18 78 6.7. Error Handling . . . . . . . . . . . . . . . . . . . . . 19 79 6.7.1. Error propagation . . . . . . . . . . . . . . . . . . 20 80 7. CI/T Object Properties and Encoding . . . . . . . . . . . . . 22 81 7.1. CI/T Objects . . . . . . . . . . . . . . . . . . . . . . 23 82 7.1.1. CI/T Commands . . . . . . . . . . . . . . . . . . . . 23 83 7.1.2. Trigger Status Resources . . . . . . . . . . . . . . 24 84 7.1.3. Trigger Collections . . . . . . . . . . . . . . . . . 25 85 7.2. Properties of CI/T Objects . . . . . . . . . . . . . . . 26 86 7.2.1. Trigger Specification . . . . . . . . . . . . . . . . 26 87 7.2.2. Trigger Action Type . . . . . . . . . . . . . . . . . 27 88 7.2.3. CI/T Trigger Specs . . . . . . . . . . . . . . . . . 28 89 7.2.4. CI/T Trigger Extensions . . . . . . . . . . . . . . . 30 90 7.2.5. Absolute Time . . . . . . . . . . . . . . . . . . . . 35 91 7.2.6. Error Description . . . . . . . . . . . . . . . . . . 35 92 7.2.7. Trigger Status . . . . . . . . . . . . . . . . . . . 37 93 8. Trigger Spec Objects . . . . . . . . . . . . . . . . . . . . 40 94 8.1. URLs Spec . . . . . . . . . . . . . . . . . . . . . . . . 40 95 8.2. CCIDs Spec . . . . . . . . . . . . . . . . . . . . . . . 40 96 8.3. URI Patterns Spec . . . . . . . . . . . . . . . . . . . . 41 97 8.3.1. UriPatternMatch . . . . . . . . . . . . . . . . . . . 41 98 8.4. URI Regexes Spec . . . . . . . . . . . . . . . . . . . . 42 99 8.4.1. RegexMatch . . . . . . . . . . . . . . . . . . . . . 43 100 8.5. Content Playlists Spec . . . . . . . . . . . . . . . . . 44 101 8.5.1. Playlist . . . . . . . . . . . . . . . . . . . . . . 44 102 8.5.2. MediaProtocol . . . . . . . . . . . . . . . . . . . . 45 103 9. Trigger Extension Objects . . . . . . . . . . . . . . . . . . 45 104 9.1. LocationPolicy extension . . . . . . . . . . . . . . . . 46 105 9.2. TimePolicy Extension . . . . . . . . . . . . . . . . . . 48 106 9.2.1. UTCWindow . . . . . . . . . . . . . . . . . . . . . . 49 107 9.2.2. LocalTimeWindow . . . . . . . . . . . . . . . . . . . 50 108 9.2.3. DateLocalTime . . . . . . . . . . . . . . . . . . . . 51 109 10. Footprint and Capabilities . . . . . . . . . . . . . . . . . 53 110 10.1. CI/T Versions Capability Object . . . . . . . . . . . . 53 111 10.1.1. CI/T Versions Capability Object Serialization . . . 53 112 10.2. CI/T Trigger Scope Capability Object . . . . . . . . . . 54 113 10.2.1. CI/T Trigger Scope Capability Object 114 Serialization . . . . . . . . . . . . . . . . . . . . 56 115 10.3. CI/T Playlist Protocol Capability Object . . . . . . . . 56 116 10.3.1. CI/T Playlist Protocol Capability Object 117 Serialization . . . . . . . . . . . . . . . . . . . . 57 118 11. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 57 119 11.1. Creating Triggers . . . . . . . . . . . . . . . . . . . 57 120 11.1.1. Preposition . . . . . . . . . . . . . . . . . . . . 57 121 11.1.2. Invalidate . . . . . . . . . . . . . . . . . . . . . 59 122 11.1.3. Invalidation with Regex . . . . . . . . . . . . . . 62 123 11.1.4. Preposition with Playlists . . . . . . . . . . . . . 63 124 11.2. Examining Trigger Status . . . . . . . . . . . . . . . . 65 125 11.2.1. Collection of All Triggers . . . . . . . . . . . . . 65 126 11.2.2. Filtered Collections of Trigger Status Resources . . 66 127 11.2.3. Individual Trigger Status Resources . . . . . . . . 68 128 11.2.4. Polling for Changes in Status . . . . . . . . . . . 70 129 11.2.5. Deleting Trigger Status Resources . . . . . . . . . 73 130 11.2.6. Extensions with Error Propagation . . . . . . . . . 74 131 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 76 132 12.1. CDNI Payload Type Parameter Registrations . . . . . . . 76 133 12.1.1. CDNI ci-trigger-command.v2 Payload Type . . . . . . 78 134 12.1.2. CDNI ci-trigger-status.v2 Payload Type . . . . . . . 78 135 12.1.3. CDNI ci-trigger-collection.v2 Payload Type . . . . . 78 136 12.1.4. CDNI CI/T Trigger Action Payload Types . . . . . . . 78 137 12.1.5. CDNI CI/T Trigger Spec Payload Types . . . . . . . . 79 138 12.1.6. CDNI CI/T Trigger Subject types . . . . . . . . . . 80 139 12.1.7. CDNI CI/T Trigger Extension Payload Types . . . . . 80 140 12.1.8. CDNI FCI CI/T Payload Types . . . . . . . . . . . . 81 141 12.2. "CDNI CI/T Trigger Types" Registry . . . . . . . . . . . 81 142 12.3. "CDNI CI/T Error Codes" Registry . . . . . . . . . . . . 81 143 12.4. CDNI Media protocol types . . . . . . . . . . . . . . . 82 144 13. Security Considerations . . . . . . . . . . . . . . . . . . . 83 145 13.1. Authentication, Authorization, Confidentiality, Integrity 146 Protection . . . . . . . . . . . . . . . . . . . . . . . 83 147 13.2. Denial of Service . . . . . . . . . . . . . . . . . . . 84 148 13.3. Privacy . . . . . . . . . . . . . . . . . . . . . . . . 85 149 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 85 150 14.1. Normative References . . . . . . . . . . . . . . . . . . 85 151 14.2. Informative References . . . . . . . . . . . . . . . . . 86 152 Appendix A. Formalization of the JSON Data . . . . . . . . . . . 88 153 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 90 154 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 90 156 1. Introduction 158 [RFC6707] introduces the problem scope for Content Delivery Network 159 Interconnection (CDNI) and lists the four categories of interfaces 160 that may be used to compose a CDNI solution (Control, Metadata, 161 Request Routing, and Logging). 163 [RFC7336] expands on the information provided in [RFC6707] and 164 describes each of the interfaces and the relationships between them 165 in more detail. 167 This document describes the "CI/T" interface -- "CDNI Control 168 interface / Triggers". It does not consider those parts of the 169 Control interface that relate to configuration, bootstrapping, or 170 authentication of CDN Interconnect interfaces. Section 4 of 171 [RFC7337] identifies the requirements specific to the CI/T interface; 172 requirements applicable to the CI/T interface are CI-1 to CI-6. 174 * Section 2 outlines the model for the CI/T interface at a high 175 level. 177 * Section 5 describes collections of Trigger Status Resources. 179 * Section 6 defines the web service provided by the downstream CDN. 181 * Section 7 lists properties of CI/T Commands and Status Resources. 183 * Section 8 describes the Trigger's Spec object. 185 * Section 9 describes the Trigger's Extensions object. 187 * Section 10 describes the FCI capabilities objects used to inform 188 on the supported CI/T capabilities. 190 * Section 11 contains example messages. 192 1.1. Terminology 194 This document reuses the terminology defined in [RFC6707] and uses 195 "uCDN" and "dCDN" as shorthand for "upstream CDN" and "downstream 196 CDN", respectively. 198 Additionally, the following terms are used throughout this document 199 and are defined as follows: 201 * HLS - HTTP Live Streaming 203 * DASH - Dynamic Adaptive Streaming Over HTTP 205 * MSS - Microsoft Smooth Streaming 207 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 208 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 209 document are to be interpreted as described in RFC 2119 [RFC2119]. 211 2. Model for CDNI Triggers 213 A CI/T Command, sent from the uCDN to the dCDN, is a request for the 214 dCDN to do some work relating to data associated with content 215 requests originating from the uCDN. 217 There are two types of CI/T Commands: CI/T Trigger Commands and CI/T 218 Cancel Commands. The CI/T Cancel Command can be used to request 219 cancellation of an earlier CI/T Trigger Command. A CI/T Trigger 220 Action is of one of the following types: 222 * preposition - used to instruct the dCDN to fetch metadata from the 223 uCDN, or content from any origin including the uCDN. 225 * invalidate - used to instruct the dCDN to revalidate specific 226 metadata or content before reusing it. 228 * purge - used to instruct the dCDN to delete specific metadata or 229 content. 231 Note that additional CI/T Trigger Action Types may be defined and 232 registered in the future. 234 The CI/T interface is a web service offered by the dCDN. It allows 235 CI/T Commands to be issued and allows triggered activity to be 236 tracked. The CI/T interface builds on top of HTTP/1.1 [RFC7230]. 237 References to URL in this document relate to HTTP/HTTPS URIs, as 238 defined in Section 2.7 of [RFC7230]. 240 When the dCDN accepts a CI/T Command, it creates a resource 241 describing the status of the triggered activity -- a Trigger Status 242 Resource. The uCDN can poll Trigger Status Resources to monitor 243 progress. 245 The dCDN maintains at least one collection of Trigger Status 246 Resources for each uCDN. Each uCDN only has access to its own 247 collections, the locations of which are shared when CDNI is 248 established. 250 To trigger activity in the dCDN, the uCDN POSTs a CI/T Command to the 251 collection of Trigger Status Resources. If the dCDN accepts the CI/T 252 Command, it creates a new Trigger Status Resource and returns its 253 location to the uCDN. To monitor progress, the uCDN can GET the 254 Trigger Status Resource. To request cancellation of a CI/T Trigger 255 Command, the uCDN can POST to the collection of Trigger Status 256 Resources or simply delete the Trigger Status Resource. 258 In addition to the collection of all Trigger Status Resources for the 259 uCDN, the dCDN can maintain filtered views of that collection. These 260 filtered views are defined in Section 5 and include collections of 261 Trigger Status Resources corresponding to active and completed CI/T 262 Trigger Commands. These collections provide a mechanism for polling 263 the status of multiple jobs. 265 Figure 1 is an example showing the basic message flow used by the 266 uCDN to trigger activity in the dCDN and for the uCDN to discover the 267 status of that activity. Only successful triggering is shown. 268 Examples of the messages are given in Section 11. 270 uCDN dCDN 271 | (1) POST https://dcdn.example.com/triggers/uCDN | 272 [ ] --------------------------------------------------> [ ]--+ 273 | [ ] | (2) 274 | (3) HTTP 201 Response [ ]<-+ 275 [ ] <-------------------------------------------------- [ ] 276 | Loc: https://dcdn.example.com/triggers/uCDN/123 | 277 | | 278 . . . 279 . . . 280 . . . 281 | | 282 | (4) GET https://dcdn.example.com/triggers/uCDN/123 | 283 [ ] --------------------------------------------------> [ ] 284 | [ ] 285 | (5) HTTP 200 Trigger Status Resource [ ] 286 [ ] <-------------------------------------------------- [ ] 287 | | 288 | | 290 Figure 1: Basic CDNI Message Flow for Triggers 292 The steps in Figure 1 are as follows: 294 1. The uCDN triggers action in the dCDN by POSTing a CI/T Command to 295 a collection of Trigger Status Resources -- 296 "https://dcdn.example.com/triggers/uCDN". This URL was given to 297 the uCDN when the CI/T interface was established. 299 2. The dCDN authenticates the request, validates the CI/T Command, 300 and, if it accepts the request, creates a new Trigger Status 301 Resource. 303 3. The dCDN responds to the uCDN with an HTTP 201 response status 304 and the location of the Trigger Status Resource. 306 4. The uCDN can poll, possibly repeatedly, the Trigger Status 307 Resource in the dCDN. 309 5. The dCDN responds with the Trigger Status Resource, describing 310 the progress or results of the CI/T Trigger Command. 312 The remainder of this document describes the messages, Trigger Status 313 Resources, and collections of Trigger Status Resources in more 314 detail. 316 2.1. Timing of Triggered Activity 318 Timing of the execution of CI/T Commands is under the dCDN's control, 319 including its start time and pacing of the activity in the network. 320 Instructions regarding this timing may be included in the trigger 321 using one of the Trigger Extension Objects defined in Section 9 323 CI/T "invalidate" and "purge" commands MUST be applied to all data 324 acquired before the command was accepted by the dCDN. The dCDN 325 SHOULD NOT apply CI/T "invalidate" and "purge" commands to data 326 acquired after the CI/T Command was accepted, but this may not always 327 be achievable, so the uCDN cannot count on that. 329 If the uCDN wishes to invalidate or purge content and then 330 immediately pre-position replacement content at the same URLs, it 331 SHOULD ensure that the dCDN has completed the invalidate/purge before 332 initiating the pre-positioning. Otherwise, there is a risk that the 333 dCDN pre-positions the new content, then immediately invalidates or 334 purges it (as a result of the two uCDN requests running in parallel). 336 Because the CI/T Command timing is under the dCDN's control, the dCDN 337 implementation can choose whether to apply CI/T "invalidate" and 338 "purge" commands to content acquisition that has already started when 339 the command is received. 341 2.2. Scope of Triggered Activity 343 Each CI/T Command can operate on multiple metadata and content 344 elements, usually refered by their URLs. These elements are targeted 345 by specifying both their subject (i.e. "metadata" or "content") as 346 well as specification method (e.g. URL Regexes) 348 Multiple representations of an HTTP resource may share the same URL. 349 CI/T Trigger Commands that invalidate or purge metadata or content 350 apply to all resource representations with matching URLs. 352 2.2.1. Multiple Interconnected CDNs 354 In a network of interconnected CDNs, a single uCDN will originate a 355 given item of metadata and associated content. It may distribute 356 that metadata and content to more than one dCDN, which may in turn 357 distribute that metadata and content to CDNs located further 358 downstream. 360 An intermediate CDN is a dCDN that passes on CDNI Metadata and 361 content to dCDNs located further downstream. 363 A "diamond" configuration is one where a dCDN can acquire metadata 364 and content originated in one uCDN from that uCDN itself and an 365 intermediate CDN, or via more than one intermediate CDN. 367 CI/T Commands originating in the single source uCDN affect metadata 368 and content in all dCDNs; however, in a diamond configuration, it may 369 not be possible for the dCDN to determine which uCDN it acquired 370 content from. In this case, a dCDN MUST allow each uCDN from which 371 it may have acquired the content to act upon that content using CI/T 372 Commands. 374 In all other cases, a dCDN MUST reject CI/T Commands from a uCDN that 375 attempts to act on another uCDN's content by using, for example, HTTP 376 403 ("Forbidden"). 378 Security considerations are discussed further in Section 13. 380 The diamond configuration may lead to inefficient interactions, but 381 the interactions are otherwise harmless. For example: 383 * When the uCDN issues an "invalidate" CI/T Command, a dCDN will 384 receive that command from multiple directly connected uCDNs. The 385 dCDN may schedule multiple such commands separately, and the last 386 scheduled command may affect content already revalidated following 387 execution of the "invalidate" command that was scheduled first. 389 * If one of a dCDN's directly connected uCDNs loses its rights to 390 distribute content, it may issue a CI/T "purge" command. That 391 purge may affect content the dCDN could retain because it's 392 distributed by another directly connected uCDN. But, that content 393 can be reacquired by the dCDN from the remaining uCDN. 395 * When the uCDN originating an item of content issues a CI/T purge 396 followed by a pre-position, two directly connected uCDNs will pass 397 those commands to a dCDN. That dCDN implementation need not merge 398 those operations or notice the repetition, in which case the purge 399 issued by one uCDN will complete before the other. The first uCDN 400 to finish its purge may then forward the "preposition" trigger, 401 and content pre-positioned as a result might be affected by the 402 still-running purge issued by the other uCDN. However, the dCDN 403 will reacquire that content as needed, or when it's asked to pre- 404 position the content by the second uCDN. A dCDN implementation 405 could avoid this interaction by knowing which uCDN it acquired the 406 content from, or it could minimize the consequences by recording 407 the time at which the "invalidate"/"purge" command was received 408 and not applying it to content acquired after that time. 410 2.3. Trigger Results 412 Possible states for a Trigger Status Resource are defined in 413 Section 7.2.7. 415 The CI/T Trigger Command MUST NOT be reported as "complete" until all 416 actions have been completed successfully. The reasons for failure, 417 and URLs or patterns affected, SHOULD be enumerated in the Trigger 418 Status Resource. For more details, see Section 6.7. 420 If a dCDN is also acting as a uCDN in a cascade, it MUST forward CI/T 421 Commands to any dCDNs that may be affected. The CI/T Trigger Command 422 MUST NOT be reported as "complete" in a CDN until it is "complete" in 423 all of its dCDNs. If a CI/T Trigger Command is reported as 424 "processed" in any dCDN, intermediate CDNs MUST NOT report 425 "complete"; instead, they MUST also report "processed". A CI/T 426 Command MAY be reported as "failed" as soon as it fails in a CDN or 427 in any of its dCDNs. A canceled CI/T Trigger Command MUST be 428 reported as "cancelling" until it has been reported as "cancelled", 429 "complete", or "failed" by all dCDNs in a cascade. 431 3. Trigger Spec 433 The CDNI Control Interface / Triggers [RFC8007] defines a set of 434 properties and objects used by the trigger commands in order to 435 specify the targets the trigger is applied on. In this document we 436 introduce additional flexibility to the trigger interface, allowing 437 the specification of the trigger's targets via a list of "trigger 438 specs" objects. Furthermore, the document defines a generic trigger 439 spec object that act as a wrapper for managing individual CDNI 440 trigger spec in an opaque manner, allowing future extension of the 441 interface. 443 This document also defines an initial set of trigger spec objects, 444 and registers the defined trigger specs' types as CDNI Payload Types 445 [RFC7736] under the namespace CIT: 447 * CIT.UrlsSpec (for TODO) 449 * CIT.CcidsSpec (for TODO) 451 * CIT.UriPatternsSpec (for TODO) 453 * CIT.UrlRegexesSpec (for TODO) 455 * CIT.ContentPlaylistsSpec (for TODO) 456 Furthermore, as the scope of the trigger may relate to either uCDN 457 metadata as well as uCDN content, the "trigger spec object" also 458 specify the trigger's target subject (i.e. metadata or content) to be 459 matched with. The document registers additional as CDNI Payload 460 Types [RFC7736] under the namespace CIT, the initial set of available 461 trigger subjects: 463 * CIT.MetadataSubject (for TODO) 465 * CIT.ContentSubject (for TODO) 467 3.1. Content URLs 469 TBD only content? what about metadata? 471 Each CI/T Command usually refers the target content by the content 472 URLs (e.g. using a CIT.UrlSpec trigger spec object). If content URLs 473 are transformed by an intermediate CDN in a cascade, that 474 intermediate CDN MUST similarly transform URLs in CI/T Commands it 475 passes to its dCDN. 477 When processing Trigger Specifications, CDNs MUST ignore the URL 478 scheme (HTTP or HTTPS) in comparing URLs. For example, for a CI/T 479 "invalidate" or "purge" command, content MUST be invalidated or 480 purged regardless of the protocol clients used to request it. 482 4. Trigger Extensibility 484 The CDNI Control Interface / Triggers [RFC8007] defines a set of 485 properties and objects used by the trigger commands. In this 486 document we define an extension mechanism to the triggers interface 487 that enables the application to add various functions that allow 488 finer control over the trigger execution. This document specifies a 489 generic trigger extension object wrapper for managing individual CDNI 490 trigger extensions in an opaque manner. 492 This document also registers CDNI Payload Types [RFC7736] under the 493 namespace CIT for the initial set of trigger extension types: 495 * CIT.LocationPolicy (for controlling the locations in which the 496 trigger is executed) 498 * CIT.TimePolicy (for scheduling a trigger to run in a specific time 499 window) 501 Example use cases 503 * Pre-position with cache location policy 504 * Purge content with cache location policy 506 * Pre-position at a specific time 508 * Purge by content acquisition time (e.g. purge all content acquired 509 in the past X hours) 511 5. Collections of Trigger Status Resources 513 As described in Section 2, Trigger Status Resources exist in the dCDN 514 to report the status of activity triggered by each uCDN. 516 A collection of Trigger Status Resources is a resource that contains 517 a reference to each Trigger Status Resource in that collection. 519 The dCDN MUST make a collection of a uCDN's Trigger Status Resources 520 available to that uCDN. This collection includes all of the Trigger 521 Status Resources created for CI/T Commands from the uCDN that have 522 been accepted by the dCDN, and have not yet been deleted by the uCDN, 523 or expired and removed by the dCDN (as described in Section 6.4). 524 Trigger Status Resources belonging to a uCDN MUST NOT be visible to 525 any other CDN. The dCDN could, for example, achieve this by offering 526 different collection URLs to each uCDN and by filtering the response 527 based on the uCDN with which the HTTP client is associated. 529 To trigger activity in a dCDN or to cancel triggered activity, the 530 uCDN POSTs a CI/T Command to the dCDN's collection of the uCDN's 531 Trigger Status Resources. 533 In order to allow the uCDN to check the status of multiple jobs in a 534 single request, the dCDN MAY also maintain collections representing 535 filtered views of the collection of all Trigger Status Resources. 536 These filtered collections are "optional-to-implement", but if they 537 are implemented, the dCDN MUST include links to them in the 538 collection of all Trigger Status Resources. The filtered collections 539 are: 541 * Pending - Trigger Status Resources for CI/T Trigger Commands that 542 have been accepted but not yet acted upon. 544 * Active - Trigger Status Resources for CI/T Trigger Commands that 545 are currently being processed in the dCDN. 547 * Complete - Trigger Status Resources representing activity that 548 completed successfully, and "processed" CI/T Trigger Commands for 549 which no further status updates will be made by the dCDN. 551 * Failed - Trigger Status Resources representing CI/T Commands that 552 failed or were canceled by the uCDN. 554 6. CDNI Trigger Interface 556 This section describes an interface to enable a uCDN to trigger 557 activity in a dCDN. 559 The CI/T interface builds on top of HTTP, so dCDNs may make use of 560 any HTTP feature when implementing the CI/T interface. For example, 561 a dCDN SHOULD make use of HTTP's caching mechanisms to indicate that 562 a requested response/representation has not been modified, reducing 563 the uCDN's processing needed to determine whether the status of 564 triggered activity has changed. 566 All dCDNs implementing CI/T MUST support the HTTP GET, HEAD, POST, 567 and DELETE methods as defined in [RFC7231]. 569 The only representation specified in this document is JSON [RFC8259]. 570 It MUST be supported by the uCDN and by the dCDN. 572 The URL of the dCDN's collection of all Trigger Status Resources 573 needs to be either discovered by or configured in the uCDN. The 574 mechanism for discovery of that URL is outside the scope of this 575 document. 577 CI/T Commands are POSTed to the dCDN's collection of all Trigger 578 Status Resources. If a CI/T Trigger Command is accepted by the dCDN, 579 the dCDN creates a new Trigger Status Resource and returns its URI to 580 the uCDN in an HTTP 201 response. The triggered activity can then be 581 monitored by the uCDN using that resource and the collections 582 described in Section 5. 584 The URI of each Trigger Status Resource is returned to the uCDN when 585 it is created, and URIs of all Trigger Status Resources are listed in 586 the dCDN's collection of all Trigger Status Resources. This means 587 all Trigger Status Resources can be discovered by the uCDN, so dCDNs 588 are free to assign whatever structure they desire to the URIs for CI/ 589 T resources. Therefore, uCDNs MUST NOT make any assumptions 590 regarding the structure of CI/T URIs or the mapping between CI/T 591 objects and their associated URIs. URIs present in the examples in 592 this document are purely illustrative and are not intended to impose 593 a definitive structure on CI/T interface implementations. 595 6.1. Creating Triggers 597 To issue a CI/T Command, the uCDN makes an HTTP POST to the dCDN's 598 collection of all of the uCDN's Trigger Status Resources. The 599 request body of that POST is a CI/T Command, as described in 600 Section 7.1.1. 602 The dCDN validates the CI/T Command. If the command is malformed or 603 the uCDN does not have sufficient access rights, the dCDN MUST either 604 respond with an appropriate 4xx HTTP error code and not create a 605 Trigger Status Resource or create a "failed" Trigger Status Resource 606 containing an appropriate Error Description. 608 When a CI/T Trigger Command is accepted, the dCDN MUST create a new 609 Trigger Status Resource that will convey a specification of the CI/T 610 Command and its current status. The HTTP response to the uCDN MUST 611 have status code 201 and MUST convey the URI of the Trigger Status 612 Resource in the Location header field [RFC7231]. The HTTP response 613 SHOULD include the content of the newly created Trigger Status 614 Resource. This is particularly important in cases where the CI/T 615 Trigger Command has completed immediately. 617 Once a Trigger Status Resource has been created, the dCDN MUST NOT 618 reuse its URI, even after that Trigger Status Resource has been 619 removed. 621 The dCDN SHOULD track and report on the progress of CI/T Trigger 622 Commands using a Trigger Status Resource (Section 7.1.2). If the 623 dCDN is not able to do that, it MUST indicate that it has accepted 624 the request but will not be providing further status updates. To do 625 this, it sets the status of the Trigger Status Resource to 626 "processed". In this case, CI/T processing should continue as for a 627 "complete" request, so the Trigger Status Resource MUST be added to 628 the dCDN's collection of complete Trigger Status Resources. The dCDN 629 SHOULD also provide an estimated completion time for the request by 630 using the "etime" property of the Trigger Status Resource. This will 631 allow the uCDN to schedule pre-positioning after an earlier delete of 632 the same URLs is expected to have finished. 634 If the dCDN is able to track the execution of CI/T Commands and a CI/ 635 T Command is queued by the dCDN for later action, the "status" 636 property of the Trigger Status Resource MUST be "pending". Once 637 processing has started, the status MUST be "active". Finally, once 638 the CI/T Command is complete, the status MUST be set to "complete" or 639 "failed". 641 A CI/T Trigger Command may result in no activity in the dCDN if, for 642 example, it is an "invalidate" or "purge" request for data the dCDN 643 has not yet acquired, or a "preposition" request for data that it has 644 already acquired and that is still valid. In this case, the status 645 of the Trigger Status Resource MUST be "processed" or "complete", and 646 the Trigger Status Resource MUST be added to the dCDN's collection of 647 complete Trigger Status Resources. 649 Once created, Trigger Status Resources can be canceled or deleted by 650 the uCDN, but not modified. The dCDN MUST reject PUT and POST 651 requests from the uCDN to Trigger Status Resources by responding with 652 an appropriate HTTP status code -- for example, 405 ("Method Not 653 Allowed"). 655 6.2. Checking Status 657 The uCDN has two ways to check the progress of CI/T Commands it has 658 issued to the dCDN, as described in Sections Section 6.2.1 and 659 Section 6.2.2. 661 To allow the uCDN to check for changes in the status of a Trigger 662 Status Resource or collection of Trigger Status Resources without 663 refetching the whole resource or collection, the dCDN SHOULD include 664 entity-tags (ETags) for the uCDN to use as cache validators, as 665 defined in [RFC7232]. 667 The dCDN SHOULD use the cache control headers for responses to GETs 668 for Trigger Status Resources and Collections to indicate the 669 frequency at which it recommends that the uCDN should poll for 670 change. 672 6.2.1. Polling Trigger Status Resource Collections 674 The uCDN can fetch the collection of its Trigger Status Resources or 675 filtered views of that collection. 677 This makes it possible to poll the status of all CI/T Trigger 678 Commands in a single request. If the dCDN moves a Trigger Status 679 Resource from the active to the completed collection, the uCDN can 680 fetch the result of that activity. 682 When polling in this way, the uCDN SHOULD use HTTP ETags to monitor 683 for change, rather than repeatedly fetching the whole collection. An 684 example of this is given in Section 11.2.4. 686 6.2.2. Polling Trigger Status Resources 688 The uCDN has a URI provided by the dCDN for each Trigger Status 689 Resource it has created. It may fetch that Trigger Status Resource 690 at any time. 692 This can be used to retrieve progress information and to fetch the 693 result of the CI/T Command. 695 When polling in this way, the uCDN SHOULD use HTTP ETags to monitor 696 for change, rather than repeatedly fetching the Trigger Status 697 Resource. 699 6.3. Canceling Triggers 701 The uCDN can request cancellation of a CI/T Trigger Command by 702 POSTing a CI/T Cancel Command to the collection of all Trigger Status 703 Resources. 705 The dCDN is required to accept and respond to the CI/T Cancel 706 Command, but the actual cancellation of a CI/T Trigger Command is 707 optional-to-implement. 709 The dCDN MUST respond to the CI/T Cancel Command appropriately -- for 710 example, with HTTP status code 200 ("OK") if the cancellation has 711 been processed and the CI/T Command is inactive, 202 ("Accepted") if 712 the command has been accepted but the CI/T Command remains active, or 713 501 ("Not Implemented") if cancellation is not supported by the dCDN. 715 If cancellation of a "pending" Trigger Status Resource is accepted by 716 the dCDN, the dCDN SHOULD NOT start the processing of that activity. 717 Issuing a CI/T Cancel Command for a "pending" Trigger Status Resource 718 does not, however, guarantee that the corresponding activity will not 719 be started, because the uCDN cannot control the timing of that 720 activity. Processing could, for example, start after the POST is 721 sent by the uCDN but before that request is processed by the dCDN. 723 If cancellation of an "active" or "processed" Trigger Status Resource 724 is accepted by the dCDN, the dCDN SHOULD stop processing the CI/T 725 Command. However, as with cancellation of a "pending" CI/T Command, 726 the dCDN does not guarantee this. 728 If the CI/T Command cannot be stopped immediately, the status in the 729 corresponding Trigger Status Resource MUST be set to "cancelling", 730 and the Trigger Status Resource MUST remain in the collection of 731 Trigger Status Resources for active CI/T Commands. If processing is 732 stopped before normal completion, the status value in the Trigger 733 Status Resource MUST be set to "cancelled", and the Trigger Status 734 Resource MUST be included in the collection of failed CI/T Trigger 735 Commands. 737 Cancellation of a "complete" or "failed" Trigger Status Resource 738 requires no processing in the dCDN. Its status MUST NOT be changed 739 to "cancelled". 741 6.4. Deleting Triggers 743 The uCDN can delete Trigger Status Resources at any time, using the 744 HTTP DELETE method. The effect is similar to cancellation, but no 745 Trigger Status Resource remains afterwards. 747 Once deleted, the references to a Trigger Status Resource MUST be 748 removed from all Trigger Status Resource collections. Subsequent 749 requests to GET the deleted Trigger Status Resource SHOULD be 750 rejected by the dCDN with an HTTP error. 752 If a "pending" Trigger Status Resource is deleted, the dCDN SHOULD 753 NOT start the processing of that activity. Deleting a "pending" 754 Trigger Status Resource does not, however, guarantee that it has not 755 started, because the uCDN cannot control the timing of that activity. 756 Processing may, for example, start after the DELETE is sent by the 757 uCDN but before that request is processed by the dCDN. 759 If an "active" or "processed" Trigger Status Resource is deleted, the 760 dCDN SHOULD stop processing the CI/T Command. However, as with 761 deletion of a "pending" Trigger Status Resource, the dCDN does not 762 guarantee this. 764 Deletion of a "complete" or "failed" Trigger Status Resource requires 765 no processing in the dCDN other than deletion of the Trigger Status 766 Resource. 768 6.5. Expiry of Trigger Status Resources 770 The dCDN can choose to automatically delete Trigger Status Resources 771 some time after they become "complete", "processed", "failed", or 772 "cancelled". In this case, the dCDN will remove the Trigger Status 773 Resource and respond to subsequent requests for it with an HTTP 774 error. 776 If the dCDN does remove Trigger Status Resources automatically, it 777 MUST report the length of time after which it will do so, using a 778 property of the collection of all Trigger Status Resources. It is 780 RECOMMENDED that Trigger Status Resources are not automatically 781 deleted by the dCDN for at least 24 hours after they become 782 "complete", "processed", "failed", or "cancelled". 784 To ensure that it is able to get the status of its Trigger Status 785 Resources for completed and failed CI/T Commands, it is RECOMMENDED 786 that the uCDN polling interval is less than the time after which 787 records for completed activity will be deleted. 789 6.6. Loop Detection and Prevention 791 Given three CDNs, A, B, and C, if CDNs B and C delegate delivery of 792 CDN A's content to each other, CDN A's CI/T Commands could be passed 793 between CDNs B and C in a loop. More complex networks of CDNs could 794 contain similar loops involving more hops. 796 In order to prevent and detect such CI/T loops, each CDN uses a CDN 797 Provider ID (PID) to uniquely identify itself. In every CI/T Command 798 it originates or cascades, each CDN MUST append an array element 799 containing its CDN PID to a JSON array under an entry named "cdn- 800 path". When receiving CI/T Commands, a dCDN MUST check the cdn-path 801 and reject any CI/T Command that already contains its own CDN PID in 802 the cdn-path. Transit CDNs MUST check the cdn-path and not cascade 803 the CI/T Command to dCDNs that are already listed in the cdn-path. 805 The CDN PID consists of the two characters "AS" followed by the CDN 806 provider's Autonomous System number [RFC1930], then a colon (":") and 807 an additional qualifier that is used to guarantee uniqueness in case 808 a particular AS has multiple independent CDNs deployed -- for 809 example, "AS64496:0". 811 If the CDN provider has multiple ASes, the same AS number SHOULD be 812 used in all messages from that CDN provider, unless there are 813 multiple distinct CDNs. 815 If the CDNI Request Routing Redirection interface (RI) described in 816 [RFC7975] is implemented by the dCDN, the CI/T interface and the RI 817 SHOULD use the same CDN PID. 819 6.7. Error Handling 821 A dCDN can signal rejection of a CI/T Command using HTTP status codes 822 -- for example, 400 ("Bad Request") if the request is malformed, or 823 403 ("Forbidden") or 404 ("Not Found") if the uCDN does not have 824 permission to issue CI/T Commands or it is trying to act on another 825 CDN's data. 827 If any part of the CI/T Trigger Command fails, the trigger SHOULD be 828 reported as "failed" once its activity is complete or if no further 829 errors will be reported. The "errors" property in the Trigger Status 830 Resource will be used to enumerate which actions failed and the 831 reasons for failure, and can be present while the Trigger Status 832 Resource is still "pending" or "active", if the CI/T Trigger Command 833 is still running for some URLs or patterns in the Trigger 834 Specification. 836 Once a request has been accepted, processing errors are reported in 837 the Trigger Status Resource using a list of Error Descriptions. Each 838 Error Description is used to report errors against one or more of the 839 URLs or patterns in the Trigger Specification. 841 If a Surrogate affected by a CI/T Trigger Command is offline in the 842 dCDN or the dCDN is unable to pass a CI/T Command on to any of its 843 cascaded dCDNs: 845 * If the CI/T Command is abandoned by the dCDN, the dCDN SHOULD 846 report an error. 848 * A CI/T "invalidate" command may be reported as "complete" when 849 Surrogates that may have the data are offline. In this case, 850 Surrogates MUST NOT use the affected data without first 851 revalidating it when they are back online. 853 * CI/T "preposition" and "purge" commands can be reported as 854 "processed" if affected caches are offline and the activity will 855 complete when they return to service. 857 * Otherwise, the dCDN SHOULD keep the Trigger Status Resource in 858 state "pending" or "active" until either the CI/T Command is acted 859 upon or the uCDN chooses to cancel it. 861 6.7.1. Error propagation 863 This subsection explains the mechanism for enabling the uCDN to 864 traceback an error to the dCDN in which it occurred. CDNI triggers 865 may be propagated over a chain of downstream CDNs. For example, an 866 upstream CDN A (uCDN-A) that is delegating to a downstream CDN B 867 (dCDN-B) and dCDN-B is delegating to a downstream CDN C (dCDN-C). 868 Triggers sent from uCDN-A to dCDN-B may be redistributed from dCDN-B 869 to dCDN-C and errors can occur anywhere along the path. Therefore, 870 it might be essential for uCDN-A that sets the trigger, to be able to 871 trace back an error to the downstream CDN where it occurred. This 872 document adds a mechanism to propagate the CDN Provider ID (PID) of 873 the dCDN where the fault occurred, back to the uCDN by adding the PID 874 to the error description. When dCDN-B propagates a trigger to the 875 further downstream dCDN-C, it MUST also propagate back the errors 876 received in the trigger status resource from dCDN-C by adding them to 877 the errors array in its own status resource to be sent back to the 878 originating uCDN-A. While propagating back the errors, and depending 879 on the implementation, dCDN-B MAY also specify the dCDN-C PID, 880 indicating to which CDN the error relates spefically. The trigger 881 originating upstream CDN will receive an array of errors that 882 occurred in all the CDNs along the execution path, where each error 883 MAY be carrying its own CDN identifier. 885 Figure 2 below is an example showing the message flow used by uCDN-A 886 to trigger activity in the dCDN-B, followed by dCDN-C, as well as the 887 discovery of the status of that activity, including the Error 888 Propagation. 890 uCDN-A dCDN-B dCDN-C 891 | | | 892 | (1) POST | | 893 | https://dcdn-b.example.com | | 894 | /triggers/uCDN-A | | 895 [ ]--------------------------->[ ]--+ | 896 | [ ] | (2) | 897 | [ ]<-+ | 898 | (3) HTTP 201 Response. [ ] | 899 |<----------------------------[ ] | 900 | Loc: [ ] | 901 | https://dcdn-b.example.com [ ] (4) POST | 902 | /triggers/uCDN-A/123 [ ] https://dcdn-c.example.com | 903 | [ ] /triggers/uCDN-A | (5) 904 | [ ]--------------------------->[ ]--+ 905 | | [ ] | 906 | | [ ]<-+ 907 | | (6) HTTP 201 Response. [ ] 908 | [ ]<---------------------------[ ] 909 | | Loc: | 910 | | https://dcdn-c.example.com | 911 | | /triggers/dCDN-B/456 | 912 | | | 913 | [ ]--+ | 914 | [ ] | (7.1) | 915 | [ ]<-+ [ ]--+ 916 | | (7.2) [ ] | 917 | | [ ]<-+ 918 | | | 919 . . . 920 . . . 921 . . . 922 | | (8) GET | 923 | | https://dcdn-c.example.com | 924 | | /triggers/dCDN-B/456 | 925 | [ ]--------------------------->[ ] 926 | | [ ] 927 | | (9) HTTP 200 [ ] 928 | | Trigger Status Resource [ ] 929 | [ ]<---------------------------[ ] 930 | | | 931 . . . 932 . . . 933 . . . 934 | (10) GET | | 935 | https://dcdn-b.example.com | | 936 | /triggers/uCDN-A/123 | | 937 [ ]--------------------------->[ ] | 938 | [ ] | 939 | (11) HTTP 200 [ ] | 940 | Trigger Status Resource [ ] | 941 [ ]<---------------------------[ ] | 943 Figure 2: CDNI Message Flow for Triggers, Including Error Propagation 945 The steps in Figure 2 are as follows: 947 1. The uCDN-A triggers action in the dCDN-B by POSTing a CI/T 948 Command to a collection of Trigger Status Resources 949 "https://dcdn-b.example.com/triggers/uCDN-A". This URL was 950 given to the uCDN-A when the CI/T interface was established. 952 2. The dCDN-B authenticates the request, validates the CI/T 953 Command, and, if it accepts the request, creates a new Trigger 954 Status Resource. 956 3. The dCDN-B responds to the uCDN-A with an HTTP 201 response 957 status and the location of the Trigger Status Resource. 959 4. The dCDN-B triggers the action in the dCDN-C by POSTing a CI/T 960 Command to a collection of Trigger Status Resources 961 "https://dcdn-c.example.com/triggers/dCDN-B". This URL was 962 given to the uCDN-A when the CI/T interface was established. 964 5. The dCDN-C authenticates the request, validates the CI/T 965 Command, and, if it accepts the request, creates a new Trigger 966 Status Resource. 968 6. The dCDN-C responds to the dCDN-B with an HTTP 201 response 969 status and the location of the Trigger Status Resource. 971 7. The dCDN-C acts upon the CI/T Command. However, the command 972 fails at dCDN-C as, for example, the Trigger Specification 973 contains a "action type" that is not supported by dCDN-C. 975 8. The dCDN-B can poll, possibly repeatedly, the Trigger Status 976 Resource in dCDN-C. 978 9. The dCDN-C responds with the Trigger Status Resource, describing 979 the progress or results of the CI/T Trigger Command. In the 980 described flow, the returned Status is "failed", with an Error 981 Description Object holding an "eunsupported" Error Code 982 reflecting the status response. 984 10. The uCDN-A can poll, possibly repeatedly, the Trigger Status 985 Resource in dCDN-B. 987 11. The dCDN-B responds with the Trigger Status Resource, describing 988 the progress or results of the CI/T Trigger Command. In the 989 flow described above, the returned Status is "failed", and the 990 "eunsupported" error received in the trigger status resource 991 from dCDN-C is propagated along with dCDN-C PID by adding it to 992 the errors array in dCDN-B's own status resource to be sent back 993 to the originating uCDN-A. 995 7. CI/T Object Properties and Encoding 997 The CI/T Commands, Trigger Status Resources, and Trigger Collections, 998 as well as their properties, are encoded using JSON, as defined in 999 Sections Section 7.1.1, Section 7.1.2, and Section 7.1.3. They MUST 1000 use the MIME media type "application/cdni", with parameter "ptype" 1001 values as defined below and in Section 12.1. 1003 Names in JSON are case sensitive. The names and literal values 1004 specified in the present document MUST always use lowercase. 1006 JSON types, including "object", "array", "number", and "string", are 1007 defined in [RFC8259]. 1009 Unrecognized name/value pairs in JSON objects SHOULD NOT be treated 1010 as an error by either the uCDN or dCDN. They SHOULD be ignored 1011 during processing and passed on by the dCDN to any further dCDNs in a 1012 cascade. 1014 7.1. CI/T Objects 1016 The top-level objects defined by the CI/T interface are described in 1017 this section. 1019 The encoding of values used by these objects is described in 1020 Section 7.2. 1022 7.1.1. CI/T Commands 1024 CI/T Commands MUST use a MIME media type of "application/cdni; 1025 ptype=ci-trigger-command.v2". 1027 A CI/T Command is encoded as a JSON object containing the following 1028 name/value pairs. 1030 Name: trigger.v2 1031 Description: A specification of the trigger action type and a 1032 set of data to act upon. 1034 Value: A Trigger Specification, as defined in Section 7.2.1. 1036 Mandatory: No, but exactly one of "trigger" or "cancel" MUST be 1037 present in a CI/T Command. 1039 Name: cancel 1040 Description: The URLs of Trigger Status Resources for CI/T 1041 Trigger Commands that the uCDN wants to cancel. 1043 Value: A non-empty JSON array of URLs represented as JSON 1044 strings. 1046 Mandatory: No, but exactly one of "trigger" or "cancel" MUST be 1047 present in a CI/T Command. 1049 Name: cdn-path 1050 Description: The CDN PIDs of CDNs that have already issued the 1051 CI/T Command to their dCDNs. 1053 Value: A non-empty JSON array of JSON strings, where each 1054 string is a CDN PID as defined in Section 6.6. 1056 Mandatory: Yes. 1058 7.1.2. Trigger Status Resources 1060 Trigger Status Resources MUST use a MIME media type of "application/ 1061 cdni; ptype=ci-trigger-status". 1063 A Trigger Status Resource is encoded as a JSON object containing the 1064 following name/value pairs. 1066 Name: trigger.v2 1067 Description: The Trigger Specification POSTed in the body of 1068 the CI/T Command. Note that this need not be a byte-for-byte 1069 copy. For example, in the JSON representation the dCDN may re- 1070 serialize the information differently. 1072 Value: A Trigger Specification, as defined in Section 7.2.1. 1074 Mandatory: Yes. 1076 Name: ctime 1077 Description: Time at which the CI/T Command was received by the 1078 dCDN. Time is determined by the dCDN; there is no requirement 1079 to synchronize clocks between interconnected CDNs. 1081 Value: Absolute Time, as defined in Section 7.2.5. 1083 Mandatory: Yes. 1085 Name: mtime 1086 Description: Time at which the Trigger Status Resource was last 1087 modified. Time is determined by the dCDN; there is no 1088 requirement to synchronize clocks between interconnected CDNs. 1090 Value: Absolute Time, as defined in Section 7.2.5. 1092 Mandatory: Yes. 1094 Name: etime 1095 Description: Estimate of the time at which the dCDN expects to 1096 complete the activity. Time is determined by the dCDN; there 1097 is no requirement to synchronize clocks between interconnected 1098 CDNs. 1100 Value: Absolute Time, as defined in Section 7.2.5. 1102 Mandatory: No. 1104 Name: status 1105 Description: Current status of the triggered activity. 1107 Value: Trigger Status, as defined in Section 7.2.7. 1109 Mandatory: Yes. 1111 Name: errors 1112 Description: Descriptions of errors that have occurred while 1113 processing a Trigger Command. 1115 Value: An array of Error Descriptions, as defined in 1116 Section 7.2.6. An empty array is allowed and is equivalent to 1117 omitting "errors" from the object. 1119 Mandatory: No. 1121 7.1.3. Trigger Collections 1123 Trigger Collections MUST use a MIME media type of "application/cdni; 1124 ptype=ci-trigger-collection". 1126 A Trigger Collection is encoded as a JSON object containing the 1127 following name/value pairs. 1129 Name: triggers 1130 Description: Links to Trigger Status Resources in the 1131 collection. 1133 Value: A JSON array of zero or more URLs, represented as JSON 1134 strings. 1136 Mandatory: Yes. 1138 Name: staleresourcetime 1139 Description: The length of time for which the dCDN guarantees 1140 to keep a completed Trigger Status Resource. After this time, 1141 the dCDN SHOULD delete the Trigger Status Resource and all 1142 references to it from collections. 1144 Value: A JSON number, which must be a positive integer, 1145 representing time in seconds. 1147 Mandatory: Yes, in the collection of all Trigger Status 1148 Resources if the dCDN deletes stale entries. If the property 1149 is present in the filtered collections, it MUST have the same 1150 value as in the collection of all Trigger Status Resources. 1152 Names: coll-all, coll-pending, coll-active, coll-complete, coll- 1153 failed 1155 Description: Link to a Trigger Collection. 1157 Value: A URL represented as a JSON string. 1159 Mandatory: Links to all of the filtered collections are 1160 mandatory in the collection of all Trigger Status Resources, if 1161 the dCDN implements the filtered collections. Otherwise, 1162 optional. 1164 Name: cdn-id 1165 Description: The CDN PID of the dCDN. 1167 Value: A JSON string, the dCDN's CDN PID, as defined in 1168 Section 6.6. 1170 Mandatory: Only in the collection of all Trigger Status 1171 Resources, if the dCDN implements the filtered collections. 1172 Optional in the filtered collections (the uCDN can always find 1173 the dCDN's cdn-id in the collection of all Trigger Status 1174 Resources, but the dCDN can choose to repeat that information 1175 in its implementation of filtered collections). 1177 7.2. Properties of CI/T Objects 1179 This section defines the values that can appear in the top-level 1180 objects described in Section 7.1, and their encodings. 1182 7.2.1. Trigger Specification 1184 A Trigger.v2 Specification is encoded as a JSON object containing the 1185 following name/value pairs. 1187 An unrecognized name/value pair in the Trigger Specification object 1188 contained in a CI/T Command SHOULD be preserved in the Trigger 1189 Specification of any Trigger Status Resource it creates. 1191 Name: action 1192 Description: Defines the type of the CI/T Trigger Action. 1194 Value: Trigger Action Type, as defined in Section 7.2.2. 1196 Mandatory: Yes. 1198 Name: specs 1199 Description: Array of trigger spec data. 1201 Value: Array of GenericTriggerSpec objects (see 1202 Section 7.2.3.1). 1204 Mandatory: Yes. TBD(nirs): Can the list be empty??? 1206 Name: extensions 1207 Description: Array of trigger extension data. 1209 Value:Array of GenericTriggerExtension objects (see 1210 Section 7.2.4.2). 1212 Mandatory: No. The default is no extensions. 1214 7.2.2. Trigger Action Type 1216 Trigger Action Type is used in a Trigger Specification to describe 1217 trigger action. 1219 All trigger types MUST be registered in the IANA "CDNI CI/T Trigger 1220 Action Types" registry (see Section 12.2). 1222 A dCDN receiving a request containing a trigger action type it does 1223 not recognize or does not support MUST reject the request by creating 1224 a Trigger Status Resource with a status of "failed" and the "errors" 1225 array containing an Error Description with error "eunsupported". 1227 The following trigger types are defined by this document: 1229 +=================+===============================================+ 1230 | JSON String | Description | 1231 +=================+===============================================+ 1232 | CIT.Preposition | A request for the dCDN to acquire metadata or | 1233 +-----------------+-----------------------------------------------+ 1234 | | content. | 1235 +-----------------+-----------------------------------------------+ 1236 | CIT.invalidate | A request for the dCDN to invalidate metadata | 1237 | | or | 1238 +-----------------+-----------------------------------------------+ 1239 | | content. After servicing this request, the | 1240 | | dCDN | 1241 +-----------------+-----------------------------------------------+ 1242 | | will not use the specified data without first | 1243 +-----------------+-----------------------------------------------+ 1244 | | revalidating it using, for example, an | 1245 +-----------------+-----------------------------------------------+ 1246 | | "If-None-Match" HTTP request. The dCDN need | 1247 | | not | 1248 +-----------------+-----------------------------------------------+ 1249 | | erase the associated data. | 1250 +-----------------+-----------------------------------------------+ 1251 | CIT.purge | A request for the dCDN to erase metadata or | 1252 +-----------------+-----------------------------------------------+ 1253 | | content. After servicing the request, the | 1254 +-----------------+-----------------------------------------------+ 1255 | | specified data MUST NOT be held on the dCDN | 1256 | | (the | 1257 +-----------------+-----------------------------------------------+ 1258 | | dCDN should reacquire the metadata or content | 1259 | | from | 1260 +-----------------+-----------------------------------------------+ 1261 | | the uCDN if it needs it). | 1262 +-----------------+-----------------------------------------------+ 1264 Table 1 1266 7.2.3. CI/T Trigger Specs 1268 A "trigger.v2" object, as defined in Section 7.2.1 includes an array 1269 of trigger spec objects. The trigger spec object contains properties 1270 that are used as trigger target selection directives for dCDN when 1271 executing the trigger command -- for example content urls or metadata 1272 uri patterns. Each such CDNI Trigger Spec is a specialization of a 1273 CDNI GenericTriggerSpec object. The GenericTriggerSpec object 1274 abstracts the basic information required for trigger distribution 1275 from the specifics of any given property (i.e., property semantics, 1276 enforcement options, etc.). The semantics of the Trigger Specs list 1277 is addative, i.e. the trigger applies to any object matching one of 1278 the listed specs. 1280 7.2.3.1. Generic Spec Object 1282 A GenericSpecObject object is a wrapper for managing individual CDNI 1283 Trigger spec in an opaque manner. 1285 Property: generic-trigger-spec-type 1287 Description: Case-insensitive CDNI Trigger spec type. 1289 Type: String containing the spec type of the object contained 1290 in the generic-trigger-spec-value property (see table in 1291 Section 12.1). 1293 Mandatory: Yes. 1295 Property: generic-trigger-spec-values 1297 Description: An array of CDNI Trigger spec object values. 1299 Type: Format/Type is defined by the value of the generic- 1300 trigger-spec-type property above. 1302 Mandatory: Yes. 1304 Property: trigger-subject 1306 Description: Case-insensitive CDNI Trigger subject. 1308 Type: String containing the type of the subject matching the 1309 generic-trigger-spec-value property, such as "content" or 1310 "metadata" as define in TODO. 1312 Mandatory: Yes. 1314 Example of a JSON serialized GenericTriggerExtension object 1315 containing a specific trigger extension object: 1317 { 1318 "generic-trigger-spec-type": 1319 , 1320 "generic-trigger-spec-value": 1321 { 1322 1323 }, 1324 "generic-trigger-spec-subject": 1325 1327 } 1329 7.2.4. CI/T Trigger Extensions 1331 A "trigger.v2" object, as defined in Section 7.2.1 includes an 1332 optional array of trigger extension objects. A trigger extension 1333 contain properties that are used as directives for dCDN when 1334 executing the trigger command -- for example, location policies, time 1335 policies and so on. Each such CDNI Trigger extension is a 1336 specialization of a CDNI GenericTriggerExtension object. The 1337 GenericTriggerExtension object abstracts the basic information 1338 required for trigger distribution from the specifics of any given 1339 property (i.e., property semantics, enforcement options, etc.). All 1340 trigger extensions are optional, and it is thus the responsibility of 1341 the extension specification to define a consistent default behavior 1342 for the case the extension is not present. 1344 7.2.4.1. Enforcement Options 1346 The trigger enforcement options concept is in accordance with the 1347 metadata enforcement options as defined in Section 3.2 of [RFC8006]. 1349 The GenericTriggerExtension object defines the properties contained 1350 within it as well as whether or not the properties are "mandatory-to- 1351 enforce". If the dCDN does not understand or support a mandatory-to- 1352 enforce property, the dCDN MUST NOT execute the trigger command. If 1353 the extension is not mandatory-to-enforce, then that 1354 GenericTriggerExtension object can be safely ignored and the trigger 1355 command can be processed in accordance with the rest of the CDNI 1356 Trigger spec. 1358 Although, a CDN MUST NOT execute a trigger command if a mandatory-to- 1359 enforce extension cannot be enforced, it could still be safe to 1360 redistribute that trigger (the "safe-to-redistribute" property) to 1361 another CDN without modification. For example, in the cascaded CDN 1362 case, a transit CDN (tCDN) could convey mandatory-to-enforce trigger 1363 extension to a dCDN. For a trigger extension that does not require 1364 customization or translation (i.e., trigger extension that is safe- 1365 to-redistribute), the data representation received off the wire MAY 1366 be stored and redistributed without being understood or supported by 1367 the tCDN. However, for trigger extension that requires translation, 1368 transparent redistribution of the uCDN trigger values might not be 1369 appropriate. Certain triggers extensions can be safely, though 1370 perhaps not optimally, redistributed unmodified. For example, pre- 1371 position command might be executed in suboptimal times for some 1372 geographies if transparently redistributed, but it might still work. 1374 Redistribution safety MUST be specified for each 1375 GenericTriggerExtension property. If a CDN does not understand or 1376 support a given GenericTriggerExtension property that is not safe-to- 1377 redistribute, the CDN MUST set the "incomprehensible" flag to true 1378 for that GenericTriggerExtension object before redistributing it. 1379 The "incomprehensible" flag signals to a dCDN that trigger metadata 1380 was not properly transformed by the tCDN. A CDN MUST NOT attempt to 1381 execute a trigger with an extension that has been marked as 1382 "incomprehensible" by a uCDN. 1384 tCDNs MUST NOT change the value of mandatory-to-enforce or safe-to- 1385 redistribute when propagating a trigger to a dCDN. Although a tCDN 1386 can set the value of "incomprehensible" to true, a tCDN MUST NOT 1387 change the value of "incomprehensible" from true to false. 1389 Table 2 describes the action to be taken by a tCDN for the different 1390 combinations of mandatory-to-enforce ("MtE") and safe-to-redistribute 1391 ("StR") properties when the tCDN either does or does not understand 1392 the trigger extension object in question: 1394 +=======+=======+============+=================================+ 1395 | MtE | StR | Extension | Trigger action | 1396 | | | object | | 1397 | | | understood | | 1398 | | | by tCDN | | 1399 +=======+=======+============+=================================+ 1400 | False | True | True | Can execute and redistribute. | 1401 +-------+-------+------------+---------------------------------+ 1402 | False | True | False | Can execute and redistribute. | 1403 +-------+-------+------------+---------------------------------+ 1404 | False | False | False | Can execute. MUST set | 1405 | | | | "incomprehensible" to true when | 1406 | | | | redistributing. | 1407 +-------+-------+------------+---------------------------------+ 1408 | False | False | True | Can execute. Can redistribute | 1409 | | | | after transforming the trigger | 1410 | | | | extension (if the CDN knows how | 1411 | | | | to do so safely); otherwise, | 1412 | | | | MUST set "incomprehensible" to | 1413 | | | | true when redistributing. | 1414 +-------+-------+------------+---------------------------------+ 1415 | True | True | True | Can execute and redistribute. | 1416 +-------+-------+------------+---------------------------------+ 1417 | True | True | False | MUST NOT execute but can | 1418 | | | | redistribute. | 1419 +-------+-------+------------+---------------------------------+ 1420 | True | False | True | Can execute. Can redistribute | 1421 | | | | after transforming the trigger | 1422 | | | | extension (if the CDN knows how | 1423 | | | | to do so safely); otherwise, | 1424 | | | | MUST set "incomprehensible" to | 1425 | | | | true when redistributing. | 1426 +-------+-------+------------+---------------------------------+ 1427 | True | False | False | MUST NOT serve. MUST set | 1428 | | | | "incomprehensible" to true when | 1429 | | | | redistributing. | 1430 +-------+-------+------------+---------------------------------+ 1432 Table 2: Action to be taken by a tCDN for the different 1433 combinations of MtE and StR properties 1435 Table 3 describes the action to be taken by a dCDN for the different 1436 combinations of mandatory-to-enforce and "incomprehensible" 1437 ("Incomp") properties, when the dCDN either does or does not 1438 understand the trigger extension object in question: 1440 +=======+========+==================+==========================+ 1441 | MtE | Incomp | Extension object | Trigger action | 1442 | | | understood by | | 1443 | | | dCDN | | 1444 +=======+========+==================+==========================+ 1445 | False | False | True | Can execute. | 1446 +-------+--------+------------------+--------------------------+ 1447 | False | True | True | Can execute but MUST NOT | 1448 | | | | interpret/apply any | 1449 | | | | trigger extension marked | 1450 | | | | as "incomprehensible". | 1451 +-------+--------+------------------+--------------------------+ 1452 | False | False | False | Can execute. | 1453 +-------+--------+------------------+--------------------------+ 1454 | False | True | False | Can execute but MUST NOT | 1455 | | | | interpret/apply any | 1456 | | | | trigger extension marked | 1457 | | | | as "incomprehensible". | 1458 +-------+--------+------------------+--------------------------+ 1459 | True | False | True | Can execute. | 1460 +-------+--------+------------------+--------------------------+ 1461 | True | True | True | MUST NOT execute. | 1462 +-------+--------+------------------+--------------------------+ 1463 | True | False | False | MUST NOT execute. | 1464 +-------+--------+------------------+--------------------------+ 1465 | True | True | False | MUST NOT execute. | 1466 +-------+--------+------------------+--------------------------+ 1468 Table 3: Action to be taken by a dCDN for the different 1469 combinations of MtE and Incomp properties 1471 7.2.4.2. GenericExtensionObject 1473 A GenericTriggerExtension object is a wrapper for managing individual 1474 CDNI Trigger extensions in an opaque manner. 1476 Property: generic-trigger-extension-type 1478 Description: Case-insensitive CDNI Trigger extension object 1479 type. 1481 Type: String containing the CDNI Payload Type [RFC7736] of the 1482 object contained in the generic-trigger-extension-value 1483 property (see table in Section 12.1). 1485 Mandatory: Yes. 1487 Property: generic-trigger-extension-value 1488 Description: CDNI Trigger extension object. 1490 Type: Format/Type is defined by the value of the generic- 1491 trigger-extension-type property above. 1493 Mandatory: Yes. 1495 Property: mandatory-to-enforce 1497 Description: Flag identifying whether or not the enforcement of 1498 this trigger extension is mandatory. 1500 Type: Boolean 1502 Mandatory: No. Default is to treat the trigger extension as 1503 mandatory-to-enforce (i.e., a value of True). 1505 Property: safe-to-redistribute 1507 Description: Flag identifying whether or not this trigger 1508 extension can be safely redistributed without modification, 1509 even if the CDN fails to understand the extension. 1511 Type: Boolean 1513 Mandatory: No. Default is to allow transparent redistribution 1514 (i.e., a value of True). 1516 Property: incomprehensible 1518 Description: Flag identifying whether or not any CDN in the 1519 chain of delegation has failed to understand and/or failed to 1520 properly transform this trigger extension object. Note: This 1521 flag only applies to trigger extension objects whose safe-to- 1522 redistribute property has a value of False. 1524 Type: Boolean 1526 Mandatory: No. Default is comprehensible (i.e., a value of 1527 False). 1529 Example of a JSON serialized GenericTriggerExtension object 1530 containing a specific trigger extension object: 1532 { 1533 "generic-trigger-extension-type": 1534 , 1535 "generic-trigger-extension-value": 1536 { 1537 1538 }, 1539 "mandatory-to-enforce": true, 1540 "safe-to-redistribute": true, 1541 "incomprehensible": false 1542 } 1544 7.2.5. Absolute Time 1546 A JSON number, seconds since the UNIX epoch (00:00:00 UTC on 1 1547 January 1970). 1549 7.2.6. Error Description 1551 An Error Description is used to report the failure of a CI/T Command 1552 or failure in the activity it triggered. It is encoded as a JSON 1553 object with the following name/value pairs: 1555 Name: error 1556 Value: Error Code, as defined in Section 7.2.7.1. 1558 Mandatory: Yes. 1560 Name: description 1561 Description: A human-readable description of the error. 1563 Value: A JSON string, the human-readable description. 1565 Mandatory: No. 1567 Name: specs 1568 Description: Array of trigger spec objects based on from the 1569 corresponding "specs" array at the Trigger Specification. Each 1570 such spec holds in its "generic-trigger-spec-value" array only 1571 those values to which the error applies. TBD: Option 1: Specs 1572 with no failing values MAY(TODO?) be omitted. Option 2: Note 1573 that the order of the specs should be as listed in the Trigger 1574 Specification. Specs with no failing values MUST not be 1575 omitted but MAY(TODO?) be replaced with an empty object for 1576 simplicity. 1578 Value: Array of GenericTriggerSpec objects, where each spec 1579 object is based on the "specs" array values in the Trigger 1580 Specification. TBD: or an empty object ('{}') as a place 1581 holder. 1583 Mandatory: Yes. 1585 Name: extensions 1586 Description: Array of trigger extension objects copied from the 1587 corresponding "extensions" array from the Trigger 1588 Specification. Only those extensions to which the error 1589 applies are included, but those extensions MUST be exactly as 1590 they appear in the request. 1592 Value: Array of GenericTriggerExtension objects, where each 1593 extension object is copied from the "extensions" array values 1594 in the Trigger Specification. 1596 Mandatory: No. The "extensions" array SHOULD be used only if 1597 the error relates to extension objects. Missing property 1598 should be interpreted as "the error is not related to any 1599 extension". 1601 Name: cdn 1602 Description: The CDN PID of the CDN where the error occurred. 1603 The "cdn" property is used by the originating uCDN or by 1604 propagating dCDN in order to distinguish in which CDN the error 1605 occurred. 1607 Value: A non-empty JSON string, where the string is a CDN PID 1608 as defined in Section Section 6.6 1610 Mandatory: Yes. In the case the dCDN does not like to expose 1611 this information, it should provide its own CDN PID. 1613 Example of a JSON serialized Error Description object reporting a 1614 malformed Playlist: 1616 { 1617 "content.playlists": [ 1618 { 1619 "playlist": "https://www.example.com/hls/title/index.m3u8", 1620 "media-protocol": "hls" 1621 } 1622 ], 1623 "description": "Failed to parse HLS playlist", 1624 "error": "econtent", 1625 "cdn": "AS64500:0" 1626 }, 1628 Example of a JSON serialized Error Description object reporting an 1629 unsupported extension object: 1631 { 1632 "errors.v2": [ 1633 { 1634 "extensions": [ 1635 { 1636 "generic-trigger-extension-type": 1637 , 1638 "generic-trigger-extension-value": 1639 { 1640 1641 }, 1642 } 1643 ], 1644 "description": "unrecognized extension ", 1645 "error": "eextension", 1646 "cdn": "AS64500:0" 1647 }, 1648 ] 1649 } 1651 7.2.7. Trigger Status 1653 Trigger Status describes the current status of the triggered 1654 activity. It MUST be one of the JSON strings in the following table: 1656 +=============+==============================+ 1657 | JSON String | Description | 1658 +=============+==============================+ 1659 | pending | The CI/T Trigger Command has | 1660 | | not yet been acted upon. | 1661 +-------------+------------------------------+ 1662 | active | The CI/T Trigger Command is | 1663 | | currently being acted | 1664 +-------------+------------------------------+ 1665 | | upon. | 1666 +-------------+------------------------------+ 1667 | complete | The CI/T Trigger Command | 1668 | | completed successfully. | 1669 +-------------+------------------------------+ 1670 | processed | The CI/T Trigger Command has | 1671 | | been accepted, and no | 1672 +-------------+------------------------------+ 1673 | | further status update will | 1674 | | be made (can be used in | 1675 +-------------+------------------------------+ 1676 | | cases where completion | 1677 | | cannot be confirmed). | 1678 +-------------+------------------------------+ 1679 | failed | The CI/T Trigger Command | 1680 | | could not be completed. | 1681 +-------------+------------------------------+ 1682 | cancelling | Processing of the CI/T | 1683 | | Trigger Command is still in | 1684 +-------------+------------------------------+ 1685 | | progress, but the CI/T | 1686 | | Trigger Command has been | 1687 +-------------+------------------------------+ 1688 | | canceled by the uCDN. | 1689 +-------------+------------------------------+ 1690 | cancelled | The CI/T Trigger Command was | 1691 | | canceled by the uCDN. | 1692 +-------------+------------------------------+ 1694 Table 4 1696 7.2.7.1. Error Code 1698 This type is used by the dCDN to report failures in trigger 1699 processing. All Error Codes MUST be registered in the IANA "CDNI CI/ 1700 T Error Codes" registry (see Section 12.3). Unknown Error Codes MUST 1701 be treated as fatal errors, and the request MUST NOT be automatically 1702 retried without modification. 1704 The following Error Codes are defined by this document and MUST be 1705 supported by an implementation of the CI/T interface. 1707 +==============+====================================================+ 1708 | Error Code | Description | 1709 +==============+====================================================+ 1710 | emeta | The dCDN was unable to acquire metadata required | 1711 +--------------+----------------------------------------------------+ 1712 | | to fulfill the request. | 1713 +--------------+----------------------------------------------------+ 1714 | econtent | The dCDN was unable to acquire content (CI/T | 1715 +--------------+----------------------------------------------------+ 1716 | | "preposition" commands only). | 1717 +--------------+----------------------------------------------------+ 1718 | eperm | The uCDN does not have permission to issue the | 1719 +--------------+----------------------------------------------------+ 1720 | | CI/T Command (for example, the data is owned by | 1721 +--------------+----------------------------------------------------+ 1722 | | another CDN). | 1723 +--------------+----------------------------------------------------+ 1724 | ereject | The dCDN is not willing to fulfill the CI/T | 1725 +--------------+----------------------------------------------------+ 1726 | | Command (for example, a "preposition" request for | 1727 +--------------+----------------------------------------------------+ 1728 | | content at a time when the dCDN would not accept | 1729 +--------------+----------------------------------------------------+ 1730 | | Request Routing requests from the uCDN). | 1731 +--------------+----------------------------------------------------+ 1732 | ecdn | An internal error in the dCDN or one of its | 1733 | | dCDNs. | 1734 +--------------+----------------------------------------------------+ 1735 | ecancelled | The uCDN canceled the request. | 1736 +--------------+----------------------------------------------------+ 1737 | eunsupported | The Trigger Specification contained an "action | 1738 | | type" that | 1739 +--------------+----------------------------------------------------+ 1740 | | is not supported by the dCDN. No action was | 1741 | | taken | 1742 +--------------+----------------------------------------------------+ 1743 | | by the dCDN other than to create a Trigger Status | 1744 +--------------+----------------------------------------------------+ 1745 | | Resource in state "failed". | 1746 +--------------+----------------------------------------------------+ 1747 | eextension | An error occurred while parsing a generic trigger | 1748 +--------------+----------------------------------------------------+ 1749 | | extension, or that the specific extension is not | 1750 +--------------+----------------------------------------------------+ 1751 | | supported by the CDN. | 1752 +--------------+----------------------------------------------------+ 1754 Table 5 1756 8. Trigger Spec Objects 1758 The objects defined below are intended to be used in the 1759 GenericTriggerSpec object's generic-trigger-spec-value field as 1760 defined in Section Section 7.2.3.1, and their generic-trigger-spec- 1761 type property MUST be set to the appropriate CDNI Payload Type as 1762 defined in Section 12.1 . 1764 8.1. URLs Spec 1766 The urls spec type allows the uCDN to manage uCDN content or metadata 1767 objects held by the dCDN based on the objects' URLs. 1769 Spec object specification 1771 Property: urls 1773 Description: An array of URLs to on which the trigger MUST be 1774 executed. 1776 Value: A JSON array of URLs represented as JSON strings. 1778 Mandatory: Yes. 1780 Below is an example of a JSON serialized generic trigger spec object, 1781 matching the metadata at metadata.example.com/a/b/c. 1783 { 1784 "generic-trigger-spec-type": "CIT.UrlsSpec", 1785 "generic-trigger-spec-value": { 1786 "urls": [ 1787 "https://metadata.example.com/a/b/c" 1788 ] 1789 }, 1790 "trigger-subject": "CIT.Metadata" 1791 } 1793 8.2. CCIDs Spec 1795 The content-ccids spec type allows to specify the Content Collection 1796 IDentifier of content the trigger applies to. The "ccid" is a 1797 grouping of content, as defined by [RFC8006]. The ccid spec type is 1798 valid only for CIT.Content spec subject. 1800 Spec object specification 1802 Property: ccids 1804 Description: An array of Content Collection IDentifier to on 1805 which the trigger MUST be executed. 1807 Value: A JSON array of strings, where each string is a Content 1808 Collection IDentifier. 1810 Mandatory: Yes. 1812 8.3. URI Patterns Spec 1814 The uri-patterns spec type allows the uCDN to manage uCDN content or 1815 metadata objects held by the dCDN based on the objects' URI patterns. 1817 Spec object specification 1819 Property: patterns 1821 Description: The objects' URI patterns the trigger applies to. 1823 Value: A JSON array of UriPatternMatch objects, as defined in 1824 Section 8.3.1. 1826 Mandatory: Yes. 1828 8.3.1. UriPatternMatch 1830 A UriPatternMatch consists of a string pattern to match against a 1831 URI, and flags describing the type of match. 1833 It is encoded as a JSON object with the following name/value 1834 pairs: 1835 Name: pattern 1837 Description: A pattern for URI matching. 1839 Value: A JSON string representing the pattern. The pattern can 1840 contain the wildcards * and ?, where * matches any sequence of 1841 [RFC3986] pchar or "/" characters (including the empty string) and 1842 ? matches exactly one [RFC3986] pchar character. The three 1843 literals $, * and ? MUST be escaped as $$, $* and $? (where $ is 1844 the designated escape character). All other characters are 1845 treated as literals. 1847 Mandatory: Yes. 1849 Name: case-sensitive 1850 Description: Flag indicating whether or not case-sensitive 1851 matching should be used. 1853 Value: One of the JSON values "true" (the matching is case 1854 sensitive) or "false" (the matching is case insensitive). 1856 Mandatory: No; default is case-insensitive match. 1858 Name: match-query-string 1859 Description: Flag indicating whether to include the query part 1860 of the URI when comparing against the pattern. 1862 Value: One of the JSON values "true" (the full URI, including 1863 the query part, should be compared against the given pattern) 1864 or "false" (the query part of the URI should be dropped before 1865 comparison with the given pattern). 1867 Mandatory: No; default is "false". The query part of the URI 1868 should be dropped before comparison with the given pattern. 1870 Example of case-sensitive prefix match against 1871 "https://www.example.com/trailers/": 1873 { 1874 "pattern": "https://www.example.com/trailers/*", 1875 "case-sensitive": true 1876 } 1878 8.4. URI Regexes Spec 1880 The content-uri-regexes spec type allows the uCDN to manage content 1881 or metadata objects held by the dCDN based on the objects' URI 1882 regexes. 1884 Spec object specification 1886 Property: regexes 1888 Description: The content URI regexes the trigger applies to. 1890 Value: A JSON array of RegexMatch objects (see Section 8.4.1). 1892 Mandatory: Yes. 1894 8.4.1. RegexMatch 1896 A RegexMatch consists of a regular expression string a URI is matched 1897 against, and flags describing the type of match. It is encoded as a 1898 JSON object with following properties: 1900 Property: regex 1902 Description: A regular expression for URI matching. 1904 Type: A regular expression to match against the URI, i.e 1905 against the path-absolute and the query string parameters 1906 [RFC3986]. The regular expression string MUST be compatible 1907 with PCRE [PCRE841]. 1909 Note: Because '\' has a special meaning in JSON [RFC8259] as 1910 the escape character within JSON strings, the regular 1911 expression character '\' MUST be escaped as '\\'. 1913 Mandatory: Yes. 1915 Property: case-sensitive 1917 Description: Flag indicating whether or not case-sensitive 1918 matching should be used. 1920 Type: JSON boolean. Either "true" (the matching is case 1921 sensitive) or "false" (the matching is case insensitive). 1923 Mandatory: No; default is case-insensitive match (i.e., a value 1924 of "false"). 1926 Property: match-query-string 1928 Description: Flag indicating whether to include the query part 1929 of the URI when comparing against the regex. 1931 Type: JSON boolean. Either "true" (the full URI, including the 1932 query part, should be compared against the regex) or "false" 1933 (the query part of the URI should be dropped before comparison 1934 with the given regex). 1936 Mandatory: No; default is "false". The query part of the URI 1937 MUST be dropped before comparison with the given regex. This 1938 makes the regular expression simpler and safer for cases in 1939 which the query parameters are not relevant for the match. 1941 Example of a case sensitive, no query parameters, regex match 1942 against: 1944 "^(https:\/\/video\.example\.com)\/([a-z])\/ 1945 movie1\/([1-7])\/*(index.m3u8|\d{3}.ts)$" 1947 { 1948 "regex": "^(https:\\/\\/video\\.example\\.com)\\/([a-z])\\/movie1\ 1949 \/([1-7])\\/*(index.m3u8|\\d{3}.ts)$", 1950 "case-sensitive": true, 1951 "match-query-string": false 1952 } 1954 This regex matches URLs of domain video.example.com where the path 1955 structure is /(single lower case letter)/(name-of-title)/(single 1956 digit between 1 to 7)/(index.m3u8 or a 3 digit number with ts 1957 extension). For example: 1959 https://video.example.com/d/movie1/5/index.m3u8 1960 or 1961 https://video.example.com/k/movie1/4/013.ts 1963 8.5. Content Playlists Spec 1965 The content-playlists spec type allows the uCDN to manage content 1966 held by the dCDN based on the content's playlists. The content- 1967 playlists spec type is valid only for CIT.Content spec subject. 1969 Spec object specification 1971 Property: playlists 1973 Description: The content playlists the trigger applies to. 1975 Value: A JSON array of Playlist objects (see Section 8.5.1). 1977 Mandatory: Yes. 1979 8.5.1. Playlist 1981 A Playlist consists of a full URL and a media protocol identifier. 1982 An implementation that supports a specific playlist media protocol 1983 MUST be able to parse playlist files of that protocol type and 1984 extract, possibly recursively, the URLs to all media objects and/or 1985 sub playlist files, and apply the trigger to each one of them 1986 separately. 1988 Playlist is encoded as a JSON object with following properties: 1990 Property: playlist 1992 Description: A URL to the playlist file. 1994 Type: A URL represented as a JSON string. 1996 Mandatory: Yes. 1998 Property: media-protocol 2000 Description: Media protocol to be when parsing and interpreting 2001 this playlist. 2003 Type: MediaProtocol (see Section 8.5.2). 2005 Mandatory: Yes. 2007 Example of a JSON serialized HLS playlist object: 2009 { 2010 "playlist": "https://www.example.com/hls/title/index.m3u8", 2011 "media-protocol": "hls" 2012 } 2014 8.5.2. MediaProtocol 2016 Media Protocol objects are used to specify registered type of media 2017 protocol (see Section 12.4) used for protocol related operations like 2018 pre-position according to playlist. 2020 Type: JSON string 2022 Example: 2024 "dash" 2026 9. Trigger Extension Objects 2028 The objects defined below are intended to be used in the 2029 GenericTriggerExtension object's generic-trigger-extension-value 2030 field as defined in Section Section 7.2.4.2, and their generic- 2031 trigger-extension-type property MUST be set to the appropriate CDNI 2032 Payload Type as defined in Section 12.1 . 2034 9.1. LocationPolicy extension 2036 A content operation may be relevant for a specific geographical 2037 region, or need to be excluded from a specific region. In this case, 2038 the trigger should be applied only to parts of the network that are 2039 either "included" or "not excluded" by the location policy. Note 2040 that the restrictions here are on the cache location rather than the 2041 client location. 2043 The LocationPolicy object defines which CDN or cache locations for 2044 which the trigger command is relevant. 2046 Example use cases: 2048 * Pre-position: Certain contracts allow for pre-positioning or 2049 availability of contract in all regions except for certain 2050 excluded regions in the world, including caches. For example, 2051 some content cannot ever knowingly touch servers in a specific 2052 country, including cached content. Therefore, these regions MUST 2053 be excluded from a pre-positioning operation. 2055 * Purge: In certain cases, content may have been located on servers 2056 in regions where the content must not reside. In such cases, a 2057 purge operation to remove content specifically from that region is 2058 required. 2060 Object specification 2062 Property: locations 2064 Description: An Access List that allows or denies (blocks) the 2065 trigger execution per cache location. 2067 Type: Array of LocationRule objects (see Section 4.2.2.1 of 2068 [RFC8006]) 2070 Mandatory: Yes. 2072 If a location policy object is not listed within the trigger command, 2073 the default behavior is to execute the trigger in all available 2074 caches and locations of the dCDN. 2076 The trigger command is allowed, or denied, for a specific cache 2077 location according to the action of the first location whose 2078 footprint matches against that cache's location. If two or more 2079 footprints overlap, the first footprint that matches against the 2080 cache's location determines the action a CDN MUST take. If the 2081 "locations" property is an empty list or if none of the listed 2082 footprints match the location of a specific cache location, then the 2083 result is equivalent to a "deny" action. 2085 The following is an example of a JSON serialized generic trigger 2086 extension object containing a location policy object that allows the 2087 trigger execution in the US but blocks its execution in Canada: 2089 { 2090 "generic-trigger-extension-type": "CIT.LocationPolicy", 2091 "generic-trigger-extension-value": 2092 { 2093 "locations": [ 2094 { 2095 "action": "allow", 2096 "footprints": [ 2097 { 2098 "footprint-type": "countrycode", 2099 "footprint-value": ["us"] 2100 } 2101 ] 2102 }, 2103 { 2104 "action": "deny", 2105 "footprints": [ 2106 { 2107 "footprint-type": "countrycode", 2108 "footprint-value": ["ca"] 2109 } 2110 ] 2111 } 2112 ] 2113 }, 2114 "mandatory-to-enforce": true, 2115 "safe-to-redistribute": true, 2116 "incomprehensible": false 2117 } 2119 9.2. TimePolicy Extension 2121 A uCDN may wish to perform content management operations on the dCDN 2122 in a specific schedule. The TimePolicy extensions allows the uCDN to 2123 instruct the dCDN to execute the trigger command in a desired time 2124 window. For example, a content provider that wishes to pre-populate 2125 a new episode at off-peak time so that it would be ready on caches at 2126 prime time when the episode is released for viewing. A scheduled 2127 operation enables the uCDN to direct the dCDN in what time frame to 2128 execute the trigger. 2130 A uCDN may wish to to schedule a trigger such that the dCDN will 2131 execute it in local time, as it is measured in each region. For 2132 example, a uCDN may wish the dCDN to pull the content at off-peak 2133 hours, between 2AM-4AM, however, as a CDN is distributed across 2134 multiple time zones, the UTC definition of 2AM depends on the actual 2135 location. 2137 We define two alternatives for localized scheduling: 2139 * Regional schedule: When used in conjunction with the Location 2140 Policy defined in Section 9.1, the uCDN can trigger separate 2141 commands for different geographical regions, for each region using 2142 a different schedule. This allows the uCDN to control the 2143 execution time per region. 2145 * Local Time schedule: We introduce a "local time" version for 2146 Internet timestamps that follows the notation for local time as 2147 defined in Section 4.2.2 of [ISO8601]. When local time is used, 2148 that dCDN SHOULD execute the triggers at different absolute times, 2149 according the local time of each execution location. 2151 Object specification 2153 Property: unix-time-window 2155 Description: A UNIX epoch time window in which the trigger 2156 SHOULD be executed. 2158 Type: TimeWindow object using UNIX epoch timestamps (see 2159 Section 4.2.3.2 of [RFC8006]) 2161 Mandatory: No, but exactly one of "unixEpochWindow", 2162 "utcWindow" or "localTimeWindow" MUST be present. 2164 Property: utc-window 2165 Description: A UTC time window in which the trigger SHOULD be 2166 executed. 2168 Type: UTCWindow object as defined in Section 9.2.1. 2170 Mandatory: No, but exactly one of "unixEpochWindow", 2171 "utcWindow" or "localTimeWindow" MUST be present. 2173 Property: local-time-window 2175 Description: A local time window. The dCDN SHOULD execute the 2176 trigger at the defined time frame, interpreted as the the local 2177 time per location. 2179 Type: LocalTimeWindow object as defined in Section 9.2.2. 2181 Mandatory: No, but exactly one of "unixEpochWindow", 2182 "utcWindow" or "localTimeWindow" MUST be present. 2184 If a time policy object is not listed within the trigger command, the 2185 default behavior is to execute the trigger in a time frame most 2186 suitable to the dCDN taking under consideration other constrains and 2187 / or obligations. 2189 Example of a JSON serialized generic trigger extension object 2190 containing a time policy object that schedules the trigger execution 2191 to a window between 09:00 01/01/2000 UTC and 17:00 01/01/2000 UTC, 2192 using the "unix-time-window" property: 2194 { 2195 "generic-trigger-extension-type": "CIT.TimePolicy", 2196 "generic-trigger-extension-value": 2197 { 2198 "unix-time-window": { 2199 "start": 946717200, 2200 "end": 946746000 2201 } 2202 } 2203 "mandatory-to-enforce": true, 2204 "safe-to-redistribute": true, 2205 "incomprehensible": false 2206 } 2208 9.2.1. UTCWindow 2210 A UTCWindow object describes a time range in UTC or UTC and a zone 2211 offset that can be applied by a TimePolicy. 2213 Property: start 2215 Description: The start time of the window. 2217 Type: Internet date and time as defined in [RFC3339]. 2219 Mandatory: No, but at least one of "start" or "end" MUST be 2220 present and non-empty. 2222 Property: end 2224 Description: The end time of the window. 2226 Type: Internet date and time as defined in [RFC3339]. 2228 Mandatory: No, but at least one of "start" or "end" MUST be 2229 present and non-empty. 2231 Example JSON serialized UTCWindow object that describes a time window 2232 from 02:30 01/01/2000 UTC to 04:30 01/01/2000 UTC: 2234 { 2235 "start": 2000-01-01T02:30:00.00Z, 2236 "end": 2000-01-01T04:30:00.00Z, 2237 } 2239 Example JSON serialized UTCWindow object that describes a time window 2240 in New York time zone offset UTC-05:00 from 02:30 01/01/2000 to 04:30 2241 01/01/2000: 2243 { 2244 "start": 2000-01-01T02:30:00.00-05:00, 2245 "end": 2000-01-01T04:30:00.00-05:00, 2246 } 2248 9.2.2. LocalTimeWindow 2250 A LocalTimeWindow object describes a time range in local time. The 2251 reader of this object MUST interpret it as "the local time at the 2252 location of execution". For example, if the time window states 2AM 2253 to 4AM local time then a dCDN that has presence in both London (UTC) 2254 and New York (UTC-05:00) will execute the trigger at 2AM-4AM UTC in 2255 London and at 2AM-4AM UTC-05:00 in New York. 2257 Property: start 2259 Description: The start time of the window. 2261 Type: JSON string formatted as DateLocalTime as defined in 2262 Section 9.2.3. 2264 Mandatory: No, but at least one of "start" or "end" MUST be 2265 present and non-empty. 2267 Property: end 2269 Description: The end time of the window. 2271 Type: JSON string formatted as DateLocalTime as defined in 2272 Section 9.2.3. 2274 Mandatory: No, but at least one of "start" or "end" MUST be 2275 present and non-empty. 2277 Example JSON serialized LocalTimeWindow object that describes a local 2278 time window from 02:30 01/01/2000 to 04:30 01/01/2000. 2280 { 2281 "start": 2000-01-01T02:30:00.00, 2282 "end": 2000-01-01T04:30:00.00, 2283 } 2285 9.2.3. DateLocalTime 2287 DateLocalTime is a timestamp that follows the date and local time 2288 notation in Section 4.3.2 of [ISO8601] as a complete date and time 2289 extended representation, where the time zone designator is omitted. 2290 In addition, for simplicity and as exact accuracy is not an objective 2291 in this case, this specification does not support the decimal 2292 fractions of seconds, and does not take leap second into 2293 consideration. 2295 Type: JSON string using the format "date-local-time" as defined in 2296 Section 9.2.3.1. 2298 9.2.3.1. Date and Local Time Format 2300 The Date and Local Time format is specified here using the syntax 2301 description notation defined in [ABNF]. 2303 date-fullyear = 4DIGIT 2304 date-month = 2DIGIT ; 01-12 2305 date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on 2306 ; month/year 2307 time-hour = 2DIGIT ; 00-23 2308 time-minute = 2DIGIT ; 00-59 2309 time-second = 2DIGIT ; 00-59 leap seconds are not supported 2311 local-time = time-hour ":" time-minute ":" time-second 2312 full-date = date-fullyear "-" date-month "-" date-mday 2313 date-local-time = full-date "T" local-time 2315 Example time representing 09:00AM on 01/01/2000 local time: 2317 2000-01-01T09:00:00.00 2319 NOTE: Per [ABNF] and [ISO8601], the "T" character in this syntax 2320 may alternatively be lower case "t". For simplicity, Applications 2321 that generate the "date-local-time" format defined here, SHOULD 2322 only use the upper case letter "T". 2324 9.2.3.2. Restrictions 2326 The grammar element date-mday represents the day number within the 2327 current month. The maximum value varies based on the month and year 2328 as follows: 2330 Month Number Month/Year Maximum value of date-mday 2331 ------------ ---------- -------------------------- 2332 01 January 31 2333 02 February, normal 28 2334 02 February, leap year 29 2335 03 March 31 2336 04 April 30 2337 05 May 31 2338 06 June 30 2339 07 July 31 2340 08 August 31 2341 09 September 30 2342 10 October 31 2343 11 November 30 2344 12 December 31 2346 See Appendix C of [RFC3339] for a sample C code that determines if a 2347 year is a leap year. 2349 The grammar element time-second may have the values 0-59. The value 2350 of 60 that is used in [ISO8601] to represent a leap second MUST NOT 2351 be used. 2353 Although [ISO8601] permits the hour to be "24", this profile of 2354 [ISO8601] only allows values between "00" and "23" for the hour in 2355 order to reduce confusion. 2357 10. Footprint and Capabilities 2359 This section covers the FCI objects required for advertisement of the 2360 specs, extensions and properties introduced in this document. 2362 10.1. CI/T Versions Capability Object 2364 The CI/T versions capability object is used to indicate support for 2365 one or more CI/T objects versions. Note that the default version as 2366 originally defined in [RFC8007] MUST be implicitly supported 2367 regardless of the versions listed in this capability object. 2369 Property: versions 2371 Description: A list of version numbers. 2373 Type: An array of JSON strings 2375 Mandatory: No. The default is version 1. A missing or an 2376 empty versions list means that only version 1 of the interface 2377 and objects is supported. 2379 10.1.1. CI/T Versions Capability Object Serialization 2381 The following shows an example of CI/T Versions Capability object 2382 serialization for a dCDN that supports versions 2 and 2.1 of the CI/T 2383 interface. 2385 { 2386 "capabilities": [ 2387 { 2388 "capability-type": "FCI.TriggerVersion", 2389 "capability-value": { 2390 "versions": [ "1", "2", "2.1" ] 2391 }, 2392 "footprints": [ 2393 2394 ] 2395 } 2396 ] 2397 } 2399 10.2. CI/T Trigger Scope Capability Object 2401 The CI/T supports several trigger types for different trigger's 2402 subjects as defined at Section 7.2.2 and Section 3. Additional 2403 types, as well as subjects, may be defined in the future. The 2404 Trigger Scope capability object is used to indicate support of a 2405 Trigger Action Type for a subject. It further specifies the Trigger 2406 Generic Spec types that may be used for selecting the targets the 2407 triggers is applied on, along with the supported Trigger Generic 2408 Extension types. 2410 Property: trigger-scope-capabilities 2412 Description: A list of supported CDNI CI/T Trigger types and 2413 subjects with the relevant Trigger Generic Spec and Trigger 2414 Generic Extension objects. 2416 Type: List trigger-scope-capability objects. 2418 Mandatory: No. The default, in case of a missing or an empty 2419 list, MUST be interpreted as "no GenericSpecObject types are 2420 supported". A non-empty list MUST be interpreted as containing 2421 "the only GenericSpecObject types that are supported". 2423 The trigger-scope-capability object is defined as follows: 2425 Property: trigger-action 2427 Description: The supported CDNI CI/T Trigger Action Type. 2429 Type: A string corresponding to an entry from the "CDNI Payload 2430 Types" registry [RFC7736] that is under the CIT namespace, and 2431 that correspond to CDNI CI/T Trigger Action Type. 2433 Mandatory: Yes. 2435 Property: trigger-subject 2437 Description: The supported CDNI CI/T Trigger Subject type. 2439 Type: A string corresponding to an entry from the "CDNI Payload 2440 Types" registry [RFC7736] that is under the CIT namespace, and 2441 that correspond to CDNI CI/T Trigger Subject type. 2443 Mandatory: Yes. 2445 Property: trigger-specs 2447 Description: A list of supported CDNI CI/T GenericSpecObject 2448 types for the Trigger Type and Subject. 2450 Type: List of strings corresponding to entries from the "CDNI 2451 Payload Types" registry [RFC7736] that are under the CIT 2452 namespace, and that correspond to CDNI CI/T GenericSpecObject 2453 objects. 2455 Mandatory: No. The default, in case of a missing or an empty 2456 list, MUST be interpreted as "no GenericExtensionObject types 2457 are supported". A non-empty list MUST be interpreted as 2458 containing "the only GenericExtensionObject types that are 2459 supported". 2461 Property: trigger-extensions 2463 Description: A list of supported CDNI CI/T 2464 GenericExtensionObject types for the Trigger Type and Subject. 2466 Type: List of strings corresponding to entries from the "CDNI 2467 Payload Types" registry [RFC7736] that are under the CIT 2468 namespace, and that correspond to CDNI CI/T 2469 GenericExtensionObject objects. 2471 Mandatory: No. The default, in case of a missing or an empty 2472 list, MUST be interpreted as "no GenericExtensionObject types 2473 are supported". A non-empty list MUST be interpreted as 2474 containing "the only GenericExtensionObject types that are 2475 supported". 2477 10.2.1. CI/T Trigger Scope Capability Object Serialization 2479 The following shows an example of a JSON serialized CI/T Trigger 2480 Scope Capability object serialization for a dCDN that supports the 2481 preposition and invalidation of content, using "CIT.UrlsSpec" and 2482 "CIT.CcidSpec" Generic Spec types, with "CIT.TimePolicy" but only for 2483 the preposition. Note that in this example purge is not supported 2484 neigher the operations on metadata. 2486 { 2487 "capabilities": [ 2488 { 2489 "capability-type": "FCI.TriggerScope", 2490 "capability-value": { 2491 "trigger-scope-capabilities": [ 2492 { 2493 "trigger-action": "CIT.Preposition", 2494 "trigger-subject": "CIT.Content", 2495 "trigger-specs": ["CIT.UrlsSpec", "CIT.CcidSpec"], 2496 "trigger-extensions": ["CIT.TimePolicy"] 2497 }, 2498 { 2499 "trigger-action": "CIT.Invalidate", 2500 "trigger-subject": "CIT.Content", 2501 "trigger-specs": ["CIT.UrlsSpec", "CIT.CcidSpec"] 2502 } 2503 ] 2504 }, 2505 "footprints": [ 2506 2507 ] 2508 } 2509 ] 2510 } 2512 10.3. CI/T Playlist Protocol Capability Object 2514 The CI/T Playlist Protocol capability object is used to indicate 2515 support for one or more MediaProtocol types listed in Section 12.4 by 2516 the playlists property of the "trigger.v2" object. 2518 Property: media-protocols 2520 Description: A list of media protocols. 2522 Type: A list of MediaProtocol (from the CDNI Triggers media 2523 protocol types Section 12.4) 2524 Mandatory: No. The default, in case of a missing or an empty 2525 list, is none supported. 2527 10.3.1. CI/T Playlist Protocol Capability Object Serialization 2529 The following shows an example of a JSON serialized CI/T Playlist 2530 Protocol Capability object serialization for a dCDN that supports 2531 "hls" and "dash". 2533 { 2534 "capabilities": [ 2535 { 2536 "capability-type": "FCI.TriggerPlaylistProtocol", 2537 "capability-value": { 2538 "media-protocols": ["hls", "dash"] 2539 }, 2540 "footprints": [ 2541 2542 ] 2543 } 2544 ] 2545 } 2547 11. Examples 2549 The following subsections provide examples of different CI/T objects 2550 encoded as JSON. 2552 Discovery of the CI/T interface is out of scope for this document. 2553 In an implementation, all CI/T URLs are under the control of the 2554 dCDN. The uCDN MUST NOT attempt to ascribe any meaning to individual 2555 elements of the path. 2557 In examples in this section, the URL "https://dcdn.example.com/ 2558 triggers" is used as the location of the collection of all Trigger 2559 Status Resources, and the CDN PID of the uCDN is "AS64496:1". 2561 11.1. Creating Triggers 2563 Examples of the uCDN triggering activity in the dCDN: 2565 11.1.1. Preposition 2567 Below is an example of a CI/T "preposition" command -- a POST to the 2568 collection of all Trigger Status Resources. 2570 Note that "metadata.patterns" and "content.patterns" are not allowed 2571 in a pre-position Trigger Specification. 2573 REQUEST: 2575 POST /triggers HTTP/1.1 2576 User-Agent: example-user-agent/0.1 2577 Host: dcdn.example.com 2578 Accept: */* 2579 Content-Type: application/cdni; ptype=ci-trigger-command.v2 2580 Content-Length: 352 2582 { 2583 "trigger.v2": { 2584 "action": "CIT.Preposition", 2585 "specs": [ 2586 { 2587 "generic-trigger-spec-type": "CIT.UrlsSpec", 2588 "generic-trigger-spec-value": { 2589 "urls": [ 2590 "https://metadata.example.com/a/b/c" 2591 ] 2592 }, 2593 "trigger-subject": "CIT.Metadata" 2594 }, 2595 { 2596 "generic-trigger-spec-type": "CIT.UrlsSpec", 2597 "generic-trigger-spec-value": { 2598 "urls": [ 2599 "https://www.example.com/a/b/c/1", 2600 "https://www.example.com/a/b/c/2", 2601 "https://www.example.com/a/b/c/3", 2602 "https://www.example.com/a/b/c/4" 2603 ] 2604 }, 2605 "trigger-subject": "CIT.Content" 2606 } 2607 ], 2608 }, 2609 "cdn-path": [ "AS64496:1" ] 2610 } 2612 RESPONSE: 2614 HTTP/1.1 201 Created 2615 Date: Wed, 04 May 2016 08:48:10 GMT 2616 Content-Length: 467 2617 Content-Type: application/cdni; ptype=ci-trigger-status 2618 Location: https://dcdn.example.com/triggers/0 2619 Server: example-server/0.1 2620 { 2621 "ctime": 1462351690, 2622 "etime": 1462351698, 2623 "mtime": 1462351690, 2624 "status": "pending", 2625 "trigger.v2": { 2626 "action": "CIT.Preposition" 2627 "specs": [ 2628 { 2629 "generic-trigger-spec-type": "CIT.UrlsSpec", 2630 "generic-trigger-spec-value": { 2631 "urls": [ 2632 "https://metadata.example.com/a/b/c" 2633 ] 2634 }, 2635 "trigger-subject": "CIT.Metadata" 2636 }, 2637 { 2638 "generic-trigger-spec-type": "CIT.UrlsSpec", 2639 "generic-trigger-spec-value": { 2640 "urls": [ 2641 "https://www.example.com/a/b/c/1", 2642 "https://www.example.com/a/b/c/2", 2643 "https://www.example.com/a/b/c/3", 2644 "https://www.example.com/a/b/c/4" 2645 ] 2646 }, 2647 "trigger-subject": "CIT.Content" 2648 } 2649 ] 2650 } 2651 } 2653 11.1.2. Invalidate 2655 Below is an example of a CI/T "invalidate" command -- another POST to 2656 the collection of all Trigger Status Resources. This instructs the 2657 dCDN to revalidate the content at "https://www.example.com/a/ 2658 index.html", as well as any metadata and content whose URLs are 2659 prefixed by "https://metadata.example.com/a/b/" using case- 2660 insensitive matching, and "https://www.example.com/a/b/" using case- 2661 sensitive matching, respectively. 2663 REQUEST: 2665 POST /triggers HTTP/1.1 2666 User-Agent: example-user-agent/0.1 2667 Host: dcdn.example.com 2668 Accept: */* 2669 Content-Type: application/cdni; ptype=ci-trigger-command.v2 2670 Content-Length: 387 2672 { 2673 "trigger.v2": { 2674 "action": "CIT.Invalidate", 2675 "specs": [ 2676 { 2677 "generic-trigger-spec-type": "CIT.UriPatterns", 2678 "generic-trigger-spec-value": { 2679 "patterns": [ 2680 { "pattern": "https://metadata.example.com/a/b/*" } 2681 ] 2682 }, 2683 "trigger-subject": "CIT.Metadata" 2684 }, 2685 { 2686 "generic-trigger-spec-type": "CIT.UrlsSpec", 2687 "generic-trigger-spec-value": { 2688 "urls": [ 2689 "https://www.example.com/a/index.html" 2690 ] 2691 }, 2692 "trigger-subject": "CIT.Content" 2693 }, 2694 { 2695 "generic-trigger-spec-type": "CIT.UriPatterns", 2696 "generic-trigger-spec-value": { 2697 "patterns": [ 2698 { "pattern": "https://www.example.com/a/b/*", 2699 "case-sensitive": true 2700 } 2701 ] 2702 }, 2703 "trigger-subject": "CIT.Content" 2704 } 2705 ] 2706 }, 2707 "cdn-path": [ "AS64496:1" ] 2708 } 2710 RESPONSE: 2712 HTTP/1.1 201 Created 2713 Date: Wed, 04 May 2016 08:48:11 GMT 2714 Content-Length: 545 2715 Content-Type: application/cdni; ptype=ci-trigger-status 2716 Location: https://dcdn.example.com/triggers/1 2717 Server: example-server/0.1 2719 { 2720 "ctime": 1462351691, 2721 "etime": 1462351699, 2722 "mtime": 1462351691, 2723 "status": "pending", 2724 "trigger.v2": { 2725 "action": "CIT.Invalidate", 2726 "specs": [ 2727 { 2728 "generic-trigger-spec-type": "CIT.UriPatterns", 2729 "generic-trigger-spec-value": { 2730 "patterns": [ 2731 { "pattern": "https://metadata.example.com/a/b/*" } 2732 ] 2733 }, 2734 "trigger-subject": "CIT.Metadata" 2735 }, 2736 { 2737 "generic-trigger-spec-type": "CIT.UrlsSpec", 2738 "generic-trigger-spec-value": { 2739 "urls": [ 2740 "https://www.example.com/a/index.html" 2741 ] 2742 }, 2743 "trigger-subject": "CIT.Content" 2744 }, 2745 { 2746 "generic-trigger-spec-type": "CIT.UriPatterns", 2747 "generic-trigger-spec-value": { 2748 "patterns": [ 2749 { "pattern": "https://www.example.com/a/b/*", 2750 "case-sensitive": true 2751 } 2752 ] 2753 }, 2754 "trigger-subject": "CIT.Content" 2755 } 2756 ] 2757 } 2758 } 2760 11.1.3. Invalidation with Regex 2762 In the following example a CI/T "invalidate" command uses the Regex 2763 property to specify the range of content objects for invalidation, 2764 the command is rejected by the dCDN due to regex complexity, and an 2765 appropriate error is reflected in the status response. 2767 TBD: in case of failure in one object, maybe leave empty places in 2768 the triggers list for the objects that has not failed> 2770 REQUEST: 2772 POST /triggers HTTP/1.1 2773 User-Agent: example-user-agent/0.1 2774 Host: triggers.dcdn.example.com 2775 Accept: */* 2776 Content-Type: application/cdni; ptype=ci-trigger-command.v2 2777 { 2778 "trigger.v2": { 2779 "action": "CIT.Invalidate", 2780 "specs": [ 2781 { 2782 "generic-trigger-spec-type": "CIT.UriRegexes", 2783 "generic-trigger-spec-value": { 2784 "regexes": [ 2785 { 2786 "regex": "^(https:\\/\\/video\\.example\\.com)\\/ 2787 ([a-z])\\/movie1\\/([1-7])\\/*(index.m3u8|\\d{3}.ts)$", 2788 "case-sensitive": true, 2789 "match-query-string": false 2790 }, 2791 { }, 2792 ... 2793 { } 2794 ] 2795 }, 2796 "trigger-subject": "CIT.Content" 2797 } 2798 ] 2799 }, 2800 "cdn-path": [ "AS64496:0" ] 2801 } 2803 RESPONSE: 2805 HTTP/1.1 201 Created 2806 Date: Wed, 04 May 2016 08:48:10 GMT 2807 Content-Length: 467 2808 Content-Type: application/cdni; ptype=ci-trigger-status.v2 2809 Location: https://triggers.dcdn.example.com/triggers/0 2810 Server: example-server/0.1 2812 { 2813 "errors.v2": [ 2814 { 2815 "specs": [ 2816 { 2817 "generic-trigger-spec-type": "CIT.UriRegexes", 2818 "generic-trigger-spec-value": { 2819 "regexes": [ 2820 { 2821 "regex": "^(https:\\/\\/video\\.example\\.com)\\/ 2822 ([a-z])\\/movie1\\/([1-7])\\/*(index.m3u8|\\d{3}.ts)$", 2823 "case-sensitive": true, 2824 "match-query-string": false 2825 } 2826 ] 2827 }, 2828 "trigger-subject": "CIT.Content" 2829 } 2830 ], 2831 "description": "The dCDN rejected a regex due to complexity", 2832 "error": "ereject", 2833 "cdn": "AS64500:0" 2834 }, 2835 ], 2836 "ctime": 1462351690, 2837 "etime": 1462351698, 2838 "mtime": 1462351690, 2839 "status": "failed", 2840 "trigger.v2": { } 2841 } 2843 11.1.4. Preposition with Playlists 2845 In the following example a CI/T "preposition" command uses the 2846 Playlist property to specify the full media library of a specific 2847 content. The command fails due to playlist parse error and an 2848 appropriate error is reflected in the status response. 2850 REQUEST: 2852 POST /triggers HTTP/1.1 2853 User-Agent: example-user-agent/0.1 2854 Host: triggers.dcdn.example.com 2855 Accept: */* 2856 Content-Type: application/cdni; ptype=ci-trigger-command.v2 2857 { 2858 "trigger.v2": { 2859 "action": "CIT.Preposition", 2860 "specs": [ 2861 { 2862 "generic-trigger-spec-type": "CIT.ContentPlaylists", 2863 "generic-trigger-spec-value": { 2864 "playlists": [ 2865 { 2866 "playlist": "https://www.example.com/hls/title/index.m3u8", 2867 "media-protocol": "hls" 2868 }, 2869 { }, 2870 ... 2871 { } 2872 ] 2873 }, 2874 "trigger-subject": "CIT.Content" 2875 } 2876 ] 2877 }, 2878 "cdn-path": [ "AS64496:0" ] 2879 } 2881 RESPONSE: 2883 HTTP/1.1 201 Created 2884 Date: Wed, 04 May 2016 08:48:10 GMT 2885 Content-Length: 467 2886 Content-Type: application/cdni; ptype=ci-trigger-status.v2 2887 Location: https://triggers.dcdn.example.com/triggers/0 2888 Server: example-server/0.1 2890 { 2891 "errors.v2": [ 2892 { 2893 "specs": [ 2894 { 2895 "generic-trigger-spec-type": "CIT.ContentPlaylists", 2896 "generic-trigger-spec-value": { 2897 "playlists": [ 2898 { 2899 "playlist": "https://www.example.com/hls/title/index.m3u8", 2900 "media-protocol": "hls" 2901 } 2902 ] 2903 }, 2904 "trigger-subject": "CIT.Content" 2905 } 2906 ], 2907 "description": "The dCDN was not able to parse the playlist", 2908 "error": "econtent", 2909 "cdn": "AS64500:0" 2910 }, 2911 ], 2912 "ctime": 1462351690, 2913 "etime": 1462351698, 2914 "mtime": 1462351690, 2915 "status": "failed", 2916 "trigger.v2": { } 2917 } 2919 11.2. Examining Trigger Status 2921 Once Trigger Status Resources have been created, the uCDN can check 2922 their status as shown in the following examples. 2924 11.2.1. Collection of All Triggers 2926 The uCDN can fetch the collection of all Trigger Status Resources it 2927 has created that have not yet been deleted or removed as expired. 2928 After creation of the "preposition" and "invalidate" triggers shown 2929 above, this collection might look as follows: 2931 REQUEST: 2933 GET /triggers HTTP/1.1 2934 User-Agent: example-user-agent/0.1 2935 Host: dcdn.example.com 2936 Accept: */* 2938 RESPONSE: 2940 HTTP/1.1 200 OK 2941 Content-Length: 341 2942 Expires: Wed, 04 May 2016 08:49:11 GMT 2943 Server: example-server/0.1 2944 ETag: "-936094426920308378" 2945 Cache-Control: max-age=60 2946 Date: Wed, 04 May 2016 08:48:11 GMT 2947 Content-Type: application/cdni; ptype=ci-trigger-collection 2949 { 2950 "cdn-id": "AS64496:0", 2951 "coll-active": "/triggers/active", 2952 "coll-complete": "/triggers/complete", 2953 "coll-failed": "/triggers/failed", 2954 "coll-pending": "/triggers/pending", 2955 "staleresourcetime": 86400, 2956 "triggers": [ 2957 "https://dcdn.example.com/triggers/0", 2958 "https://dcdn.example.com/triggers/1" 2959 ] 2960 } 2962 11.2.2. Filtered Collections of Trigger Status Resources 2964 The filtered collections are also available to the uCDN. Before the 2965 dCDN starts processing the two CI/T Trigger Commands shown above, 2966 both will appear in the collection of pending triggers. For example: 2968 REQUEST: 2970 GET /triggers/pending HTTP/1.1 2971 User-Agent: example-user-agent/0.1 2972 Host: dcdn.example.com 2973 Accept: */* 2975 RESPONSE: 2977 HTTP/1.1 200 OK 2978 Content-Length: 152 2979 Expires: Wed, 04 May 2016 08:49:11 GMT 2980 Server: example-server/0.1 2981 ETag: "4331492443626270781" 2982 Cache-Control: max-age=60 2983 Date: Wed, 04 May 2016 08:48:11 GMT 2984 Content-Type: application/cdni; ptype=ci-trigger-collection 2986 { 2987 "staleresourcetime": 86400, 2988 "triggers": [ 2989 "https://dcdn.example.com/triggers/0", 2990 "https://dcdn.example.com/triggers/1" 2991 ] 2992 } 2994 At this point, if no other Trigger Status Resources had been created, 2995 the other filtered views would be empty. For example: 2997 REQUEST: 2999 GET /triggers/complete HTTP/1.1 3000 User-Agent: example-user-agent/0.1 3001 Host: dcdn.example.com 3002 Accept: */* 3004 RESPONSE: 3006 HTTP/1.1 200 OK 3007 Content-Length: 54 3008 Expires: Wed, 04 May 2016 08:49:11 GMT 3009 Server: example-server/0.1 3010 ETag: "7958041393922269003" 3011 Cache-Control: max-age=60 3012 Date: Wed, 04 May 2016 08:48:11 GMT 3013 Content-Type: application/cdni; ptype=ci-trigger-collection 3015 { 3016 "staleresourcetime": 86400, 3017 "triggers": [] 3018 } 3020 11.2.3. Individual Trigger Status Resources 3022 The Trigger Status Resources can also be examined for details about 3023 individual CI/T Trigger Commands. For example, for the CI/T 3024 "preposition" and "invalidate" commands from previous examples: 3026 REQUEST: 3028 GET /triggers/0 HTTP/1.1 3029 User-Agent: example-user-agent/0.1 3030 Host: dcdn.example.com 3031 Accept: */* 3033 RESPONSE: 3035 HTTP/1.1 200 OK 3036 Content-Length: 467 3037 Expires: Wed, 04 May 2016 08:49:10 GMT 3038 Server: example-server/0.1 3039 ETag: "6990548174277557683" 3040 Cache-Control: max-age=60 3041 Date: Wed, 04 May 2016 08:48:10 GMT 3042 Content-Type: application/cdni; ptype=ci-trigger-status 3044 { 3045 "ctime": 1462351690, 3046 "etime": 1462351698, 3047 "mtime": 1462351690, 3048 "status": "pending", 3049 "trigger": { 3050 "action": "CIT.Preposition", 3051 "specs": [ 3052 { 3053 "generic-trigger-spec-type": "CIT.UrlsSpec", 3054 "generic-trigger-spec-value": { 3055 "urls": [ 3056 "https://metadata.example.com/a/b/c" 3057 ] 3058 }, 3059 "trigger-subject": "CIT.Metadata" 3060 }, 3061 { 3062 "generic-trigger-spec-type": "CIT.UrlsSpec", 3063 "generic-trigger-spec-value": { 3064 "urls": [ 3065 "https://www.example.com/a/b/c/1", 3066 "https://www.example.com/a/b/c/2", 3067 "https://www.example.com/a/b/c/3", 3068 "https://www.example.com/a/b/c/4" 3069 ] 3070 }, 3071 "trigger-subject": "CIT.Content" 3072 } 3073 ] 3074 } 3075 } 3077 REQUEST: 3079 GET /triggers/1 HTTP/1.1 3080 User-Agent: example-user-agent/0.1 3081 Host: dcdn.example.com 3082 Accept: */* 3084 RESPONSE: 3086 HTTP/1.1 200 OK 3087 Content-Length: 545 3088 Expires: Wed, 04 May 2016 08:49:11 GMT 3089 Server: example-server/0.1 3090 ETag: "-554385204989405469" 3091 Cache-Control: max-age=60 3092 Date: Wed, 04 May 2016 08:48:11 GMT 3093 Content-Type: application/cdni; ptype=ci-trigger-status 3094 { 3095 "ctime": 1462351691, 3096 "etime": 1462351699, 3097 "mtime": 1462351691, 3098 "status": "pending", 3099 "trigger": { 3100 "action": "CIT.Invalidate", 3101 "specs": [ 3102 { 3103 "generic-trigger-spec-type": "CIT.UriPatterns", 3104 "generic-trigger-spec-value": { 3105 "patterns": [ 3106 { "pattern": "https://metadata.example.com/a/b/*" } 3107 ] 3108 }, 3109 "trigger-subject": "CIT.Metadata" 3110 }, 3111 { 3112 "generic-trigger-spec-type": "CIT.UrlsSpec", 3113 "generic-trigger-spec-value": { 3114 "urls": [ 3115 "https://www.example.com/a/index.html" 3116 ] 3117 }, 3118 "trigger-subject": "CIT.Content" 3119 }, 3120 { 3121 "generic-trigger-spec-type": "CIT.UriPatterns", 3122 "generic-trigger-spec-value": { 3123 "patterns": [ 3124 { "pattern": "https://www.example.com/a/b/*", 3125 "case-sensitive": true 3126 } 3127 ] 3128 }, 3129 "trigger-subject": "CIT.Content" 3130 } 3131 ] 3132 } 3133 } 3135 11.2.4. Polling for Changes in Status 3137 The uCDN SHOULD use the ETags of collections or Trigger Status 3138 Resources when polling for changes in status, as shown in the 3139 following examples: 3141 REQUEST: 3143 GET /triggers/pending HTTP/1.1 3144 User-Agent: example-user-agent/0.1 3145 Host: dcdn.example.com 3146 Accept: */* 3147 If-None-Match: "4331492443626270781" 3149 RESPONSE: 3150 HTTP/1.1 304 Not Modified 3151 Content-Length: 0 3152 Expires: Wed, 04 May 2016 08:49:11 GMT 3153 Server: example-server/0.1 3154 ETag: "4331492443626270781" 3155 Cache-Control: max-age=60 3156 Date: Wed, 04 May 2016 08:48:11 GMT 3157 Content-Type: application/cdni; ptype=ci-trigger-collection 3159 REQUEST: 3161 GET /triggers/0 HTTP/1.1 3162 User-Agent: example-user-agent/0.1 3163 Host: dcdn.example.com 3164 Accept: */* 3165 If-None-Match: "6990548174277557683" 3167 RESPONSE: 3169 HTTP/1.1 304 Not Modified 3170 Content-Length: 0 3171 Expires: Wed, 04 May 2016 08:49:10 GMT 3172 Server: example-server/0.1 3173 ETag: "6990548174277557683" 3174 Cache-Control: max-age=60 3175 Date: Wed, 04 May 2016 08:48:10 GMT 3176 Content-Type: application/cdni; ptype=ci-trigger-status 3178 When the CI/T Trigger Command is complete, the contents of the 3179 filtered collections will be updated along with their ETags. For 3180 example, when the two example CI/T Trigger Commands are complete, the 3181 collections of pending and complete Trigger Status Resources might 3182 look like: 3184 REQUEST: 3186 GET /triggers/pending HTTP/1.1 3187 User-Agent: example-user-agent/0.1 3188 Host: dcdn.example.com 3189 Accept: */* 3191 RESPONSE: 3193 HTTP/1.1 200 OK 3194 Content-Length: 54 3195 Expires: Wed, 04 May 2016 08:49:15 GMT 3196 Server: example-server/0.1 3197 ETag: "1337503181677633762" 3198 Cache-Control: max-age=60 3199 Date: Wed, 04 May 2016 08:48:15 GMT 3200 Content-Type: application/cdni; ptype=ci-trigger-collection 3202 { 3203 "staleresourcetime": 86400, 3204 "triggers": [] 3205 } 3207 REQUEST: 3209 GET /triggers/complete HTTP/1.1 3210 User-Agent: example-user-agent/0.1 3211 Host: dcdn.example.com 3212 Accept: */* 3214 RESPONSE: 3216 HTTP/1.1 200 OK 3217 Content-Length: 152 3218 Expires: Wed, 04 May 2016 08:49:22 GMT 3219 Server: example-server/0.1 3220 ETag: "4481489539378529796" 3221 Cache-Control: max-age=60 3222 Date: Wed, 04 May 2016 08:48:22 GMT 3223 Content-Type: application/cdni; ptype=ci-trigger-collection 3225 { 3226 "staleresourcetime": 86400, 3227 "triggers": [ 3228 "https://dcdn.example.com/triggers/0", 3229 "https://dcdn.example.com/triggers/1" 3230 ] 3231 } 3233 11.2.5. Deleting Trigger Status Resources 3235 The uCDN can delete completed and failed Trigger Status Resources to 3236 reduce the size of the collections, as described in Section 6.4. For 3237 example, to delete the "preposition" request from earlier examples: 3239 REQUEST: 3241 DELETE /triggers/0 HTTP/1.1 3242 User-Agent: example-user-agent/0.1 3243 Host: dcdn.example.com 3244 Accept: */* 3246 RESPONSE: 3248 HTTP/1.1 204 No Content 3249 Date: Wed, 04 May 2016 08:48:22 GMT 3250 Content-Length: 0 3251 Content-Type: text/html; charset=UTF-8 3252 Server: example-server/0.1 3254 This would, for example, cause the collection of completed Trigger 3255 Status Resources shown in the example above to be updated to: 3257 REQUEST: 3259 GET /triggers/complete HTTP/1.1 3260 User-Agent: example-user-agent/0.1 3261 Host: dcdn.example.com 3262 Accept: */* 3264 RESPONSE: 3266 HTTP/1.1 200 OK 3267 Content-Length: 105 3268 Expires: Wed, 04 May 2016 08:49:22 GMT 3269 Server: example-server/0.1 3270 ETag: "-6938620031669085677" 3271 Cache-Control: max-age=60 3272 Date: Wed, 04 May 2016 08:48:22 GMT 3273 Content-Type: application/cdni; ptype=ci-trigger-collection 3275 { 3276 "staleresourcetime": 86400, 3277 "triggers": [ 3278 "https://dcdn.example.com/triggers/1" 3279 ] 3280 } 3282 11.2.6. Extensions with Error Propagation 3284 In the following example a CI/T "preposition" command is using two 3285 extensions to control the way the trigger is executed. In this 3286 example the receiving dCDN identified as "AS64500:0" does not support 3287 the first extension in the extensions array. dCDN "AS64500:0" further 3288 distributes this trigger to another downstream CDN that is identified 3289 as "AS64501:0", which does not support the second extension in the 3290 extensions array. The error is propagated from "AS64501:0" to 3291 "AS64500:0" and the errors.v2 array reflects both errors. 3293 REQUEST: 3295 POST /triggers HTTP/1.1 3296 User-Agent: example-user-agent/0.1 3297 Host: triggers.dcdn.example.com 3298 Accept: */* 3299 Content-Type: application/cdni; ptype=ci-trigger-command.v2 3300 { 3301 "trigger.v2": { 3302 "action": "CIT.Preposition", 3303 "specs": [ 3304 { 3305 "generic-trigger-spec-type": "CIT.ContentPlaylists", 3306 "generic-trigger-spec-value": { 3307 "playlists": [ 3308 { 3309 "playlist": "https://www.example.com/hls/title/index.m3u8", 3310 "media-protocol": "hls" 3311 } 3312 ] 3313 }, 3314 "trigger-subject": "CIT.Content" 3315 } 3316 ], 3317 "extensions": [ 3318 { 3319 "generic-trigger-extension-type": 3320 , 3321 "generic-trigger-extension-value": 3322 { 3323 3324 }, 3325 "mandatory-to-enforce": true, 3326 "safe-to-redistribute": true, 3327 }, 3328 { 3329 "generic-trigger-extension-type": 3331 , 3332 "generic-trigger-extension-value": 3333 { 3334 3335 }, 3336 "mandatory-to-enforce": true, 3337 "safe-to-redistribute": true, 3338 }, 3339 ], 3340 }, 3341 "cdn-path": [ "AS64496:0" ] 3342 } 3344 RESPONSE: 3346 HTTP/1.1 201 Created 3347 Date: Wed, 04 May 2016 08:48:10 GMT 3348 Content-Length: 467 3349 Content-Type: application/cdni; ptype=ci-trigger-status.v2 3350 Location: https://triggers.dcdn.example.com/triggers/0 3351 Server: example-server/0.1 3353 { 3354 "errors.v2": [ 3355 { 3356 "extensions": [ 3357 { 3358 "generic-trigger-extension-type": 3359 , 3360 "generic-trigger-extension-value": 3361 { 3362 3363 }, 3364 "mandatory-to-enforce": true, 3365 "safe-to-redistribute": true, 3366 }, 3367 ], 3368 "description": "unrecognized extension ", 3369 "error": "eextension", 3370 "cdn": "AS64500:0" 3371 }, 3372 { 3373 "extensions": [ 3374 { 3375 "generic-trigger-extension-type": 3376 , 3377 "generic-trigger-extension-value": 3378 { 3379 3380 }, 3381 "mandatory-to-enforce": true, 3382 "safe-to-redistribute": true, 3383 }, 3384 ], 3385 "description": "unrecognized extension ", 3386 "error": "eextension", 3387 "cdn": "AS64501:0" 3388 }, 3389 ], 3390 "ctime": 1462351690, 3391 "etime": 1462351698, 3392 "mtime": 1462351690, 3393 "status": "failed", 3394 "trigger.v2": { } 3395 } 3397 12. IANA Considerations 3399 12.1. CDNI Payload Type Parameter Registrations 3401 The IANA is requested to register the following new Payload Types in 3402 the "CDNI Payload Types" registry defined by [RFC7736], for use with 3403 the "application/cdni" MIME media type. 3405 +=============================+===============+ 3406 | Payload Type | Specification | 3407 +=============================+===============+ 3408 | ci-trigger-collection | RFCthis | 3409 +-----------------------------+---------------+ 3410 | ci-trigger-command.v2 | RFCthis | 3411 +-----------------------------+---------------+ 3412 | ci-trigger-status.v2 | RFCthis | 3413 +-----------------------------+---------------+ 3414 | CIT.Preposition | RFCthis | 3415 +-----------------------------+---------------+ 3416 | CIT.Invalidate | RFCthis | 3417 +-----------------------------+---------------+ 3418 | CIT.Purge | RFCthis | 3419 +-----------------------------+---------------+ 3420 | CIT.UrlsSpec | RFCthis | 3421 +-----------------------------+---------------+ 3422 | CIT.CcidsSpec | RFCthis | 3423 +-----------------------------+---------------+ 3424 | CIT.UriPatternsSpec | RFCthis | 3425 +-----------------------------+---------------+ 3426 | CIT.UrisRegexesSpec | RFCthis | 3427 +-----------------------------+---------------+ 3428 | CIT.ContentPlaylistsSpec | RFCthis | 3429 +-----------------------------+---------------+ 3430 | CIT.MetadataSubject | RFCthis | 3431 +-----------------------------+---------------+ 3432 | CIT.ContentSubject | RFCthis | 3433 +-----------------------------+---------------+ 3434 | CIT.LocationPolicy | RFCthis | 3435 +-----------------------------+---------------+ 3436 | CIT.TimePolicy | RFCthis | 3437 +-----------------------------+---------------+ 3438 | FCI.TriggerVersion | RFCthis | 3439 +-----------------------------+---------------+ 3440 | FCI.TriggerScope | RFCthis | 3441 +-----------------------------+---------------+ 3442 | FCI.TriggerType | RFCthis | 3443 +-----------------------------+---------------+ 3444 | FCI.TriggerGenericSpec | RFCthis | 3445 +-----------------------------+---------------+ 3446 | FCI.TriggerGenericExtension | RFCthis | 3447 +-----------------------------+---------------+ 3448 | FCI.TriggerPlaylistProtocol | RFCthis | 3449 +-----------------------------+---------------+ 3451 Table 6 3453 [RFC Editor: Please replace RFCthis with the published RFC number for 3454 this document.] 3456 12.1.1. CDNI ci-trigger-command.v2 Payload Type 3458 Purpose: TODO: The purpose of this payload type is to distinguish 3459 version 2 of the CI/T command (and any associated capability 3460 advertisement) 3462 Interface: CI/T 3464 Encoding: see Section 7.1.1 3466 12.1.2. CDNI ci-trigger-status.v2 Payload Type 3468 Purpose: TODO: The purpose of this payload type is to distinguish 3469 version 2 of the CI/T status resource response (and any associated 3470 capability advertisement) 3472 Interface: CI/T 3474 Encoding: see Section 7.1.2 3476 12.1.3. CDNI ci-trigger-collection.v2 Payload Type 3478 Purpose: TODO (came from 8007) 3480 Interface: CI/T 3482 Encoding: see Section 7.1.3 3484 12.1.4. CDNI CI/T Trigger Action Payload Types 3486 12.1.4.1. CDNI CI/T Preposition Trigger Action Payload Type 3488 Purpose: The purpose of this Trigger action type is to distinguish 3489 Preposition CIT Trigger Types Triggers. 3491 Interface: CI/T 3493 Encoding: see Section 7.2.2 3495 12.1.4.2. CDNI CI/T Invalidate Trigger Action Payload Type 3497 Purpose: The purpose of this Trigger action type is to distinguish 3498 Invalidate CIT Trigger Types Triggers. 3500 Interface: CI/T 3501 Encoding: see Section 7.2.2 3503 12.1.4.3. CDNI CI/T Purge Trigger Action Payload Type 3505 Purpose: The purpose of this Trigger action type is to distinguish 3506 Purge CIT Trigger Types Triggers. 3508 Interface: CI/T 3510 Encoding: see Section 7.2.2 3512 12.1.5. CDNI CI/T Trigger Spec Payload Types 3514 12.1.5.1. CDNI CI/T Urls Trigger Spec Payload Type 3516 Purpose: The purpose of this Trigger Spec type is to distinguish Urls 3517 CIT Trigger Spec objects. 3519 Interface: CI/T 3521 Encoding: see Section 8.1 3523 12.1.5.2. CDNI CI/T Ccids Trigger Spec Payload Type 3525 Purpose: The purpose of this Trigger Spec type is to distinguish 3526 Ccids CIT Trigger Spec objects. 3528 Interface: CI/T 3530 Encoding: see Section 8.2 3532 12.1.5.3. CDNI CI/T UriPatterns Trigger Spec Payload Type 3534 Purpose: The purpose of this Trigger Spec type is to distinguish 3535 UriPatterns CIT Trigger Spec objects. 3537 Interface: CI/T 3539 Encoding: see Section 8.3 3541 12.1.5.4. CDNI CI/T UriRegexes Trigger Spec Payload Type 3543 Purpose: The purpose of this Trigger Spec type is to distinguish 3544 UriRegexes CIT Trigger Spec objects. 3546 Interface: CI/T 3548 Encoding: see Section 8.4 3550 12.1.5.5. CDNI CI/T ContentPlaylists Trigger Spec Payload Type 3552 Purpose: The purpose of this Trigger Spec type is to distinguish 3553 ContentPlaylists CIT Trigger Spec objects. 3555 Interface: CI/T 3557 Encoding: see Section 8.5 3559 12.1.6. CDNI CI/T Trigger Subject types 3561 12.1.6.1. CDNI CI/T Metadata Trigger Subject Type 3563 Purpose: The purpose of this Trigger Spec subejct type is to 3564 distinguish Metadata CIT Trigger Spec objects. 3566 Interface: CI/T 3568 Encoding: see TODO - string "metatdata" - should we register it???? 3570 12.1.6.2. CDNI CI/T Content Trigger Subject Type 3572 Purpose: The purpose of this Trigger Spec subejct type is to 3573 distinguish Content CIT Trigger Spec objects. 3575 Interface: CI/T 3577 Encoding: see TODO - string "metatdata" - should we register it???? 3579 12.1.7. CDNI CI/T Trigger Extension Payload Types 3581 12.1.7.1. CDNI CI/T LocationPolicy Trigger Extension Type 3583 Purpose: The purpose of this Trigger Extension type is to distinguish 3584 LocationPolicy CIT Trigger Extension objects. 3586 Interface: CI/T 3588 Encoding: see Section 9.1 3590 12.1.7.2. CDNI CI/T TimePolicy Trigger Extension Type 3592 Purpose: The purpose of this Trigger Extension type is to distinguish 3593 TimePolicy CI/T Trigger Extension objects. 3595 Interface: CI/T 3597 Encoding: see Section 9.2 3599 12.1.8. CDNI FCI CI/T Payload Types 3601 12.1.8.1. CDNI FCI CI/T Versions Payload Type 3603 Purpose: The purpose of this payload type is to distinguish FCI 3604 advertisement objects for CI/T Triggers Versions objects 3606 Interface: FCI 3608 Encoding: see Section 10.1.1 3610 12.1.8.2. CDNI FCI CI/T Trigger Scope Payload Type 3612 Purpose: The purpose of this payload type is to distinguish FCI 3613 advertisement objects for CI/T Trigger Scope 3615 Interface: FCI 3617 Encoding: see Section 10.2.1 3619 12.1.8.3. CDNI FCI CI/T Playlist Protocol Payload Type 3621 Purpose: The purpose of this payload type is to distinguish FCI 3622 advertisement objects for CI/T Playlist Protocol objects 3624 Interface: FCI 3626 Encoding: see Section 10.3.1 3628 12.2. "CDNI CI/T Trigger Types" Registry 3630 The IANA is requested to create a new "CDNI CI/T Trigger Types" 3631 subregistry under the "Content Delivery Network Interconnection 3632 (CDNI) Parameters" registry. 3634 Additions to the "CDNI CI/T Trigger Types" registry will be made via 3635 the RFC Required policy as defined in [RFC8126]. 3637 The initial contents of the "CDNI CI/T Trigger Types" registry 3638 comprise the names and descriptions listed in Section 5.2.2 of this 3639 document, with this document acting as the specification. 3641 12.3. "CDNI CI/T Error Codes" Registry 3643 The IANA is requested to create a new "CDNI CI/T Error Codes" 3644 subregistry under the "Content Delivery Network Interconnection 3645 (CDNI) Parameters" registry. 3647 Additions to the "CDNI CI/T Error Codes" registry will be made via 3648 the Specification Required policy as defined in [RFC8126]. The 3649 Designated Expert will verify that new Error Code registrations do 3650 not duplicate existing Error Code definitions (in name or 3651 functionality), prevent gratuitous additions to the namespace, and 3652 prevent any additions to the namespace that would impair the 3653 interoperability of CDNI implementations. 3655 The initial contents of the "CDNI CI/T Error Codes" registry comprise 3656 the names and descriptions of the Error Codes listed in Section 5.2.7 3657 of this document, with this document acting as the specification. 3659 12.4. CDNI Media protocol types 3661 The IANA is requested to create a new "CDNI MediaProtocol Types" 3662 subregistry in the "Content Delivery Networks Interconnection (CDNI) 3663 Parameters" registry. The "CDNI MediaProtocol Types" namespace 3664 defines the valid MediaProtocol object values in 3665 Section Section 8.5.2, used by the Playlist object. Additions to the 3666 MediaProtocol namespace conform to the "Specification Required" 3667 policy as defined in Section 4.6 of [RFC8126], where the 3668 specification defines the MediaProtocol Type and the protocol to 3669 which it is associated. The designated expert will verify that new 3670 protocol definitions do not duplicate existing protocol definitions 3671 and prevent gratuitous additions to the namespace. 3673 The following table defines the initial MediaProtocol values 3674 corresponding to the HLS, MSS, and DASH protocols: 3676 +===============+==================+===============+===============+ 3677 | MediaProtocol | Description | Specification | Protocol | 3678 | Type | | | Specification | 3679 +===============+==================+===============+===============+ 3680 | hls | HTTP Live | RFCthis | RFC 8216 | 3681 | | Streaming | | [RFC8216] | 3682 +---------------+------------------+---------------+---------------+ 3683 | mss | Microsoft Smooth | RFCthis | MSS [MSS] | 3684 | | Streaming | | | 3685 +---------------+------------------+---------------+---------------+ 3686 | dash | Dynamic Adaptive | RFCthis | MPEG-DASH | 3687 | | Streaming over | | [MPEG-DASH] | 3688 | | HTTP (MPEG-DASH) | | | 3689 +---------------+------------------+---------------+---------------+ 3691 Table 7 3693 [RFC Editor: Please replace RFCthis with the published RFC number for 3694 this document.] 3696 13. Security Considerations 3698 The CI/T interface provides a mechanism to allow a uCDN to generate 3699 requests into the dCDN and to inspect its own CI/T requests and their 3700 current states. The CI/T interface does not allow access to, or 3701 modification of, the uCDN or dCDN metadata relating to content 3702 delivery or to the content itself. It can only control the presence 3703 of that metadata in the dCDN, and the processing work and network 3704 utilization involved in ensuring that presence. 3706 By examining "preposition" requests to a dCDN, and correctly 3707 interpreting content and metadata URLs, an attacker could learn the 3708 uCDN's or content owner's predictions for future content popularity. 3709 By examining "invalidate" or "purge" requests, an attacker could 3710 learn about changes in the content owner's catalog. 3712 By injecting CI/T Commands, an attacker or a misbehaving uCDN would 3713 generate work in the dCDN and uCDN as they process those requests. 3714 So would a man-in-the-middle attacker modifying valid CI/T Commands 3715 generated by the uCDN. In both cases, that would decrease the dCDN's 3716 caching efficiency by causing it to unnecessarily acquire or 3717 reacquire content metadata and/or content. 3719 A dCDN implementation of CI/T MUST restrict the actions of a uCDN to 3720 the data corresponding to that uCDN. Failure to do so would allow 3721 uCDNs to detrimentally affect each other's efficiency by generating 3722 unnecessary acquisition or reacquisition load. 3724 An origin that chooses to delegate its delivery to a CDN is trusting 3725 that CDN to deliver content on its behalf; the interconnection of 3726 CDNs is an extension of that trust to dCDNs. That trust relationship 3727 is a commercial arrangement, outside the scope of the CDNI protocols. 3728 So, while a malicious CDN could deliberately generate load on a dCDN 3729 using the CI/T interface, the protocol does not otherwise attempt to 3730 address malicious behavior between interconnected CDNs. 3732 13.1. Authentication, Authorization, Confidentiality, Integrity 3733 Protection 3735 A CI/T implementation MUST support Transport Layer Security (TLS) 3736 transport for HTTP (HTTPS) as per [RFC2818] and [RFC7230]. 3738 TLS MUST be used by the server side (dCDN) and the client side (uCDN) 3739 of the CI/T interface, including authentication of the remote end, 3740 unless alternate methods are used for ensuring the security of the 3741 information in the CI/T interface requests and responses (such as 3742 setting up an IPsec tunnel between the two CDNs or using a physically 3743 secured internal network between two CDNs that are owned by the same 3744 corporate entity). 3746 The use of TLS for transport of the CI/T interface allows the dCDN 3747 and the uCDN to authenticate each other using TLS client 3748 authentication and TLS server authentication. 3750 Once the dCDN and the uCDN have mutually authenticated each other, 3751 TLS allows: 3753 * The dCDN and the uCDN to authorize each other (to ensure that they 3754 are receiving CI/T Commands from, or reporting status to, an 3755 authorized CDN). 3757 * CDNI commands and responses to be transmitted with 3758 confidentiality. 3760 * Protection of the integrity of CDNI commands and responses. 3762 When TLS is used, the general TLS usage guidance in [RFC7525] MUST be 3763 followed. 3765 The mechanisms for access control are dCDN-specific and are not 3766 standardized as part of this CI/T specification. 3768 HTTP requests that attempt to access or operate on CI/T data 3769 belonging to another CDN MUST be rejected using, for example, HTTP 3770 403 ("Forbidden") or 404 ("Not Found"). This is intended to prevent 3771 unauthorized users from generating unnecessary load in dCDNs or uCDNs 3772 due to revalidation, reacquisition, or unnecessary acquisition. 3774 When deploying a network of interconnected CDNs, the possible 3775 inefficiencies related to the diamond configuration discussed in 3776 Section 2.2.1 should be considered. 3778 13.2. Denial of Service 3780 This document does not define a specific mechanism to protect against 3781 Denial-of-Service (DoS) attacks on the CI/T interface. However, CI/T 3782 endpoints can be protected against DoS attacks through the use of TLS 3783 transport and/or via mechanisms outside the scope of the CI/T 3784 interface, such as firewalling or the use of Virtual Private Networks 3785 (VPNs). 3787 Depending on the implementation, triggered activity may consume 3788 significant processing and bandwidth in the dCDN. A malicious or 3789 faulty uCDN could use this to generate unnecessary load in the dCDN. 3790 The dCDN should consider mechanisms to avoid overload -- for example, 3791 by rate-limiting acceptance or processing of CI/T Commands, or by 3792 performing batch processing. 3794 13.3. Privacy 3796 The CI/T protocol does not carry any information about individual end 3797 users of a CDN; there are no privacy concerns for end users. 3799 The CI/T protocol does carry information that could be considered 3800 commercially sensitive by CDN operators and content owners. The use 3801 of mutually authenticated TLS to establish a secure session for the 3802 transport of CI/T data, as discussed in Section 13.1, provides 3803 confidentiality while the CI/T data is in transit and prevents 3804 parties other than the authorized dCDN from gaining access to that 3805 data. The dCDN MUST ensure that it only exposes CI/T data related to 3806 a uCDN to clients it has authenticated as belonging to that uCDN. 3808 14. References 3810 14.1. Normative References 3812 [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 3813 Specifications: ABNF", STD 68, RFC 5234, 3814 DOI 10.17487/RFC5234, January 2008, 3815 . 3817 [RFC1930] Hawkinson, J. and T. Bates, "Guidelines for creation, 3818 selection, and registration of an Autonomous System (AS)", 3819 BCP 6, RFC 1930, DOI 10.17487/RFC1930, March 1996, 3820 . 3822 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3823 Requirement Levels", BCP 14, RFC 2119, 3824 DOI 10.17487/RFC2119, March 1997, 3825 . 3827 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 3828 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 3829 . 3831 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3832 Resource Identifier (URI): Generic Syntax", STD 66, 3833 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3834 . 3836 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3837 Protocol (HTTP/1.1): Message Syntax and Routing", 3838 RFC 7230, DOI 10.17487/RFC7230, June 2014, 3839 . 3841 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3842 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 3843 DOI 10.17487/RFC7231, June 2014, 3844 . 3846 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3847 Protocol (HTTP/1.1): Conditional Requests", RFC 7232, 3848 DOI 10.17487/RFC7232, June 2014, 3849 . 3851 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 3852 "Recommendations for Secure Use of Transport Layer 3853 Security (TLS) and Datagram Transport Layer Security 3854 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 3855 2015, . 3857 [RFC8006] Niven-Jenkins, B., Murray, R., Caulfield, M., and K. Ma, 3858 "Content Delivery Network Interconnection (CDNI) 3859 Metadata", RFC 8006, DOI 10.17487/RFC8006, December 2016, 3860 . 3862 [RFC8007] Murray, R. and B. Niven-Jenkins, "Content Delivery Network 3863 Interconnection (CDNI) Control Interface / Triggers", 3864 RFC 8007, DOI 10.17487/RFC8007, December 2016, 3865 . 3867 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3868 Writing an IANA Considerations Section in RFCs", BCP 26, 3869 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3870 . 3872 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3873 Interchange Format", STD 90, RFC 8259, 3874 DOI 10.17487/RFC8259, December 2017, 3875 . 3877 14.2. Informative References 3879 [I-D.greevenbosch-appsawg-cbor-cddl] 3880 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 3881 definition language (CDDL): a notational convention to 3882 express CBOR data structures", Work in Progress, Internet- 3883 Draft, draft-greevenbosch-appsawg-cbor-cddl-11, 3 July 3884 2017, . 3887 [ISO8601] ISO, "Data elements and interchange formats -- Information 3888 interchange -- Representation of dates and times", 3889 ISO 8601:2004, Edition 3, December 2004, 3890 . 3892 [MPEG-DASH] 3893 ISO, "Information technology -- Dynamic adaptive streaming 3894 over HTTP (DASH) -- Part 1: Media presentation description 3895 and segment format", ISO/IEC 23009-1:2014, Edition 2, May 3896 2014, . 3898 [MSS] Microsoft, "[MS-SSTR]: Smooth Streaming Protocol", 3899 Protocol Revision 8.0, September 2017, 3900 . 3902 [PCRE841] Hazel, P., "Perl Compatible Regular Expressions", 3903 Version 8.41, 5 July 2017, . 3905 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 3906 DOI 10.17487/RFC2818, May 2000, 3907 . 3909 [RFC6707] Niven-Jenkins, B., Le Faucheur, F., and N. Bitar, "Content 3910 Distribution Network Interconnection (CDNI) Problem 3911 Statement", RFC 6707, DOI 10.17487/RFC6707, September 3912 2012, . 3914 [RFC7336] Peterson, L., Davie, B., and R. van Brandenburg, Ed., 3915 "Framework for Content Distribution Network 3916 Interconnection (CDNI)", RFC 7336, DOI 10.17487/RFC7336, 3917 August 2014, . 3919 [RFC7337] Leung, K., Ed. and Y. Lee, Ed., "Content Distribution 3920 Network Interconnection (CDNI) Requirements", RFC 7337, 3921 DOI 10.17487/RFC7337, August 2014, 3922 . 3924 [RFC7736] Ma, K., "Content Delivery Network Interconnection (CDNI) 3925 Media Type Registration", RFC 7736, DOI 10.17487/RFC7736, 3926 December 2015, . 3928 [RFC7975] Niven-Jenkins, B., Ed. and R. van Brandenburg, Ed., 3929 "Request Routing Redirection Interface for Content 3930 Delivery Network (CDN) Interconnection", RFC 7975, 3931 DOI 10.17487/RFC7975, October 2016, 3932 . 3934 [RFC8216] Pantos, R., Ed. and W. May, "HTTP Live Streaming", 3935 RFC 8216, DOI 10.17487/RFC8216, August 2017, 3936 . 3938 Appendix A. Formalization of the JSON Data 3940 This appendix is non-normative. 3942 TODO should we remove it or compile a CDDL on our own 3944 The JSON data described in this document has been formalized using 3945 the CBOR Data Definition Language (CDDL) 3946 [I-D.greevenbosch-appsawg-cbor-cddl] (where "CBOR" means "Concise 3947 Binary Object Representation"), as follows: 3949 CIT-object = CIT-command / Trigger-Status-Resource / Trigger-Collection 3951 CIT-command ; use media type application/cdni; ptype=ci-trigger-command 3952 = { 3953 ? trigger: Triggerspec 3954 ? cancel: [* URI] 3955 cdn-path: [* Cdn-PID] 3956 } 3958 Trigger-Status-Resource ; application/cdni; ptype=ci-trigger-status 3959 = { 3960 trigger: Triggerspec 3961 ctime: Absolute-Time 3962 mtime: Absolute-Time 3963 ? etime: Absolute-Time 3964 status: Trigger-Status 3965 ? errors: [* Error-Description] 3966 } 3968 Trigger-Collection ; application/cdni; ptype=ci-trigger-collection 3969 = { 3970 triggers: [* URI] 3971 ? staleresourcetime: int ; time in seconds 3972 ? coll-all: URI 3973 ? coll-pending: URI 3974 ? coll-active: URI 3975 ? coll-complete: URI 3976 ? coll-failed: URI 3977 ? cdn-id: Cdn-PID 3978 } 3980 Triggerspec = { ; see Section 5.2.1 3981 type: Trigger-Type 3982 ? metadata.urls: [* URI] 3983 ? content.urls: [* URI] 3984 ? content.ccid: [* Ccid] 3985 ? metadata.patterns: [* Pattern-Match] 3986 ? content.patterns: [* Pattern-Match] 3987 } 3989 Trigger-Type = "preposition" / "invalidate" 3990 / "purge" ; see Section 5.2.2 3992 Trigger-Status = "pending" / "active" / "complete" / "processed" 3993 / "failed" / "cancelling" / "cancelled" ; see Section 5.2.3 3995 Pattern-Match = { ; see Section 5.2.4 3996 pattern: tstr 3997 ? case-sensitive: bool 3998 ? match-query-string: bool 3999 } 4001 Absolute-Time = number ; seconds since UNIX epoch (Section 5.2.5) 4003 Error-Description = { ; see Section 5.2.6 4004 error: Error-Code 4005 ? metadata.urls: [* URI] 4006 ? content.urls: [* URI] 4007 ? metadata.patterns: [* Pattern-Match] 4008 ? content.patterns: [* Pattern-Match] 4009 ? description: tstr 4010 } 4012 Error-Code = "emeta" / "econtent" / "eperm" / "ereject" 4013 / "ecdn" / "ecancelled" ; see Section 5.2.7 4015 Ccid = tstr ; see RFC 8006 4017 Cdn-PID = tstr .regexp "AS[0-9]+:[0-9]+" 4019 URI = tstr 4021 Acknowledgments 4023 The authors thank Kevin Ma for his input, and Carsten Bormann for his 4024 review and formalization of the JSON data. 4026 Authors' Addresses 4028 Ori Finkelman 4029 Qwilt 4030 6, Ha'harash 4031 Hod HaSharon 4524079 4032 Israel 4033 Email: ori.finkelman.ietf@gmail.com 4035 Sanjay Mishra 4036 Verizon 4037 13100 Columbia Pike 4038 Silver Spring, MD 20904 4039 United States of America 4040 Email: sanjay.mishra@verizon.com 4042 Nir B. Sopher 4043 Qwilt 4044 6, Ha'harash 4045 Hod HaSharon 4524079 4046 Israel 4047 Email: nir@apache.org