idnits 2.17.1 draft-ietf-cdni-control-triggers-11.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 7, 2015) is 3060 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: 'RFCthis' is mentioned on line 1647, but not defined ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Downref: Normative reference to an Informational RFC: RFC 6707 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** 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) == Outdated reference: A later version (-11) exists of draft-greevenbosch-appsawg-cbor-cddl-07 == Outdated reference: A later version (-21) exists of draft-ietf-cdni-metadata-12 == Outdated reference: A later version (-20) exists of draft-ietf-cdni-redirection-13 Summary: 7 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Murray 3 Internet-Draft B. Niven-Jenkins 4 Intended status: Standards Track Velocix (Alcatel-Lucent) 5 Expires: June 9, 2016 December 7, 2015 7 CDNI Control Interface / Triggers 8 draft-ietf-cdni-control-triggers-11 10 Abstract 12 This document describes the part of the CDN Interconnection Control 13 Interface that allows a CDN to trigger activity in an interconnected 14 CDN that is configured to deliver content on its behalf. The 15 upstream CDN can use this mechanism to request that the downstream 16 CDN pre-positions metadata or content, or that it invalidates or 17 purges metadata or content. The upstream CDN can monitor the status 18 of activity that it has triggered in the downstream CDN. 20 Requirements Language 22 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 23 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 24 document are to be interpreted as described in RFC 2119 [RFC2119]. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on June 9, 2016. 43 Copyright Notice 45 Copyright (c) 2015 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 62 2. Model for CDNI Triggers . . . . . . . . . . . . . . . . . . . 4 63 2.1. Timing of Triggered Activity . . . . . . . . . . . . . . 6 64 2.2. Scope of Triggered Activity . . . . . . . . . . . . . . . 6 65 2.3. Trigger Results . . . . . . . . . . . . . . . . . . . . . 6 66 3. Collections of Trigger Status Resources . . . . . . . . . . . 7 67 4. CDNI Trigger Interface . . . . . . . . . . . . . . . . . . . 8 68 4.1. Creating Triggers . . . . . . . . . . . . . . . . . . . . 9 69 4.2. Checking Status . . . . . . . . . . . . . . . . . . . . . 10 70 4.2.1. Polling Trigger Status Resource collections . . . . . 10 71 4.2.2. Polling Trigger Status Resources . . . . . . . . . . 11 72 4.3. Cancelling Triggers . . . . . . . . . . . . . . . . . . . 11 73 4.4. Deleting Triggers . . . . . . . . . . . . . . . . . . . . 12 74 4.5. Expiry of Trigger Status Resources . . . . . . . . . . . 12 75 4.6. Loop Detection and Prevention . . . . . . . . . . . . . . 13 76 4.7. Error Handling . . . . . . . . . . . . . . . . . . . . . 13 77 4.8. Content URLs . . . . . . . . . . . . . . . . . . . . . . 14 78 5. CI/T Object Properties and Encoding . . . . . . . . . . . . . 14 79 5.1. CI/T Objects . . . . . . . . . . . . . . . . . . . . . . 15 80 5.1.1. CI/T Commands . . . . . . . . . . . . . . . . . . . . 15 81 5.1.2. Trigger Status Resource . . . . . . . . . . . . . . . 16 82 5.1.3. Trigger Collection . . . . . . . . . . . . . . . . . 17 83 5.2. Properties of CI/T Objects . . . . . . . . . . . . . . . 18 84 5.2.1. Trigger Specification . . . . . . . . . . . . . . . . 19 85 5.2.2. Trigger Type . . . . . . . . . . . . . . . . . . . . 20 86 5.2.3. Trigger Status . . . . . . . . . . . . . . . . . . . 21 87 5.2.4. PatternMatch . . . . . . . . . . . . . . . . . . . . 21 88 5.2.5. Absolute Time . . . . . . . . . . . . . . . . . . . . 22 89 5.2.6. Error Description . . . . . . . . . . . . . . . . . . 22 90 5.2.7. Error Code . . . . . . . . . . . . . . . . . . . . . 23 91 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 24 92 6.1. Creating Triggers . . . . . . . . . . . . . . . . . . . . 24 93 6.1.1. Preposition . . . . . . . . . . . . . . . . . . . . . 24 94 6.1.2. Invalidate . . . . . . . . . . . . . . . . . . . . . 25 95 6.2. Examining Trigger Status . . . . . . . . . . . . . . . . 27 96 6.2.1. Collection of All Triggers . . . . . . . . . . . . . 27 97 6.2.2. Filtered Collections of Trigger Status Resources . . 28 98 6.2.3. Individual Trigger Status Resources . . . . . . . . . 29 99 6.2.4. Polling for Change . . . . . . . . . . . . . . . . . 31 100 6.2.5. Deleting Trigger Status Resources . . . . . . . . . . 34 101 6.2.6. Error Reporting . . . . . . . . . . . . . . . . . . . 35 102 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 103 7.1. CDNI Payload Type Parameter Registrations . . . . . . . . 36 104 8. Security Considerations . . . . . . . . . . . . . . . . . . . 37 105 8.1. Authentication, Authorization, Confidentiality, Integrity 106 Protection . . . . . . . . . . . . . . . . . . . . . . . 37 107 8.2. Denial of Service . . . . . . . . . . . . . . . . . . . . 38 108 8.3. Privacy . . . . . . . . . . . . . . . . . . . . . . . . . 39 109 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 39 110 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 111 10.1. Normative References . . . . . . . . . . . . . . . . . . 39 112 10.2. Informative References . . . . . . . . . . . . . . . . . 40 113 Appendix A. Formalization of the JSON Data . . . . . . . . . . . 40 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 116 1. Introduction 118 [RFC6707] introduces the problem scope for CDN Interconnection (CDNI) 119 and lists the four categories of interfaces that may be used to 120 compose a CDNI solution (Control, Metadata, Request Routing, 121 Logging). 123 [RFC7336] expands on the information provided in [RFC6707] and 124 describes each of the interfaces and the relationships between them 125 in more detail. 127 This document describes the "CI/T" interface, "CDNI Control interface 128 / Triggers". It does not consider those parts of the control 129 interface that relate to configuration, bootstrapping or 130 authentication of CDN Interconnect interfaces. Section 4 of 131 [RFC7337] identifies the requirements specific to the CI interface, 132 requirements applicable to the CI/T interface are CI-1 to CI-6. 134 o Section 2 outlines the model for the CI/T Interface at a high 135 level. 137 o Section 3 describes collections of Trigger Status Resources. 139 o Section 4 defines the web service provided by the dCDN. 141 o Section 5 lists properties of CI/T Commands and Status Resources. 143 o Section 6 contains example messages. 145 1.1. Terminology 147 This document reuses the terminology defined in [RFC6707] and uses 148 "uCDN" and "dCDN" as shorthand for "Upstream CDN" and "Downstream 149 CDN", respectively. 151 2. Model for CDNI Triggers 153 A CI/T Command, sent from the uCDN to the dCDN, is a request for the 154 dCDN to do some work relating to data associated with content 155 requests originating from the uCDN. 157 There are two types of CI/T Command: CI/T Trigger Commands, and CI/T 158 Cancel Commands. The CI/T Cancel Command can be used to request 159 cancellation of an earlier CI/T Trigger Command. A CI/T Trigger 160 Command is of one of the following types: 162 o preposition - used to instruct the dCDN to fetch metadata from the 163 uCDN, or content from any origin including the uCDN. 165 o invalidate - used to instruct the dCDN to revalidate specific 166 metadata or content before re-using it. 168 o purge - used to instruct the dCDN to delete specific metadata or 169 content. 171 The CI/T interface is a web service offered by the dCDN. It allows 172 CI/T commands to be issued, and triggered activity to be tracked. 173 When the dCDN accepts a CI/T Command it creates a resource describing 174 status of the triggered activity, a Trigger Status Resource. The 175 uCDN can poll Trigger Status Resources to monitor progress. 177 The dCDN maintains at least one collection of Trigger Status 178 Resources for each uCDN. Each uCDN only has access to its own 179 collections, the locations of which are shared when CDN 180 interconnection is established. 182 To trigger activity in the dCDN, the uCDN POSTs a CI/T Command to the 183 collection of Trigger Status Resources. If the dCDN accepts the CI/T 184 Command, it creates a new Trigger Status Resource and returns its 185 location to the uCDN. To monitor progress, the uCDN can GET the 186 Trigger Status Resource. To request cancellation of a CI/T Trigger 187 Command the uCDN can POST to the collection of Trigger Status 188 Resources, or simply DELETE the Trigger Status Resource. 190 In addition to the collection of all Trigger Status Resources for the 191 uCDN, the dCDN can maintain filtered views of that collection. These 192 filtered views are defined in Section 3 and include collections of 193 Trigger Status Resources corresponding to active and completed CI/T 194 Trigger Commands. These collections provide a mechanism for polling 195 the status of multiple jobs. 197 Figure 1 is an example showing the basic message flow used by the 198 uCDN to trigger activity in the dCDN, and for the uCDN to discover 199 the status of that activity. Only successful triggering is shown. 200 Examples of the messages are given in Section 6. 202 uCDN dCDN 203 | (1) POST http://dcdn.example.com/triggers/uCDN | 204 [ ] --------------------------------------------------> [ ]--+ 205 | [ ] | (2) 206 | (3) HTTP 201 Response [ ]<-+ 207 [ ] <-------------------------------------------------- [ ] 208 | Loc: http://dcdn.example.com/triggers/uCDN/123 | 209 | | 210 . . . 211 . . . 212 . . . 213 | | 214 | (4) GET http://dcdn.example.com/triggers/uCDN/123 | 215 [ ] --------------------------------------------------> [ ] 216 | [ ] 217 | (5) HTTP 200 Trigger Status Resource [ ] 218 [ ] <-------------------------------------------------- [ ] 219 | | 220 | | 222 Figure 1: Basic CDNI Message Flow for Triggers 224 The steps in Figure 1 are: 226 1. The uCDN triggers action in the dCDN by posting a CI/T Command to 227 a collection of Trigger Status Resources, 228 "http://dcdn.example.com/triggers/uCDN". The URL of this was 229 given to the uCDN when the CI/T interface was established. 231 2. The dCDN authenticates the request, validates the CI/T Command 232 and, if it accepts the request, creates a new Trigger Status 233 Resource. 235 3. The dCDN responds to the uCDN with an HTTP 201 response status, 236 and the location of the Trigger Status Resource. 238 4. The uCDN can poll, possibly repeatedly, the Trigger Status 239 Resource in the dCDN. 241 5. The dCDN responds with the Trigger Status Resource, describing 242 progress or results of the CI/T Trigger Command. 244 The remainder of this document describes the messages, Trigger Status 245 Resources, and collections of Trigger Status Resources in more 246 detail. 248 2.1. Timing of Triggered Activity 250 Timing of the execution of CI/T Commands is under the dCDN's control, 251 including its start-time and pacing of the activity in the network. 253 CI/T invalidate and purge commands MUST be applied to all data 254 acquired before the command was accepted by the dCDN. The dCDN 255 SHOULD NOT apply CI/T invalidate and purge commands to data acquired 256 after the CI/T Command was accepted, but this may not always be 257 achievable so the uCDN cannot count on that. 259 If the uCDN wishes to invalidate or purge content then immediately 260 pre-position replacement content at the same URLs, it SHOULD ensure 261 the dCDN has completed the invalidate/purge before initiating the 262 prepositioning. Otherwise, there is a risk that the dCDN pre- 263 positions the new content, then immediately invalidates or purges it 264 (as a result of the two uCDN requests running in parallel). 266 Because the CI/T Command timing is under the dCDN's control, the dCDN 267 implementation can choose whether to apply CI/T invalidate and purge 268 commands to content acquisition that has already started when the 269 command is received. 271 2.2. Scope of Triggered Activity 273 Each CI/T Command can operate on multiple metadata and content URLs. 275 Multiple representations of an HTTP resource may share the same URL. 276 CI/T Trigger Commands that invalidate or purge metadata or content 277 apply to all resource representations with matching URLs. 279 The dCDN MUST reject CI/T Commands from a uCDN that act on another 280 uCDN's data. Security considerations are discussed further in 281 section Section 8. 283 2.3. Trigger Results 285 Possible states for a Trigger Status Resource are defined in section 286 Section 5.2.3. 288 The CI/T Trigger Command MUST NOT be reported as 'complete' until all 289 actions have been completed successfully. The reasons for failure, 290 and URLs or Patterns affected, SHOULD be enumerated in the Trigger 291 Status Resource. For more detail, see section Section 4.7. 293 If a dCDN is also acting as a uCDN in a cascade, it MUST forward CI/T 294 Commands to any downstream CDNs that may be affected. The CI/T 295 Trigger Command MUST NOT be reported as 'complete' in a CDN until it 296 is 'complete' in all of its downstream CDNs. If a CI/T Trigger 297 Command is reported as 'processed' in any dCDN, intermediate CDNs 298 MUST NOT report 'complete', instead they must also report 299 'processed'. A CI/T Command MAY be reported as 'failed' as soon as 300 it fails in a CDN or in any of its downstream CDNs. A cancelled CI/T 301 Trigger Command MUST be reported as 'cancelling' until it has been 302 reported as 'cancelled', 'complete', or 'failed' by all dCDNs in a 303 cascade. 305 3. Collections of Trigger Status Resources 307 As described in Section 2, Trigger Status Resources exist in the dCDN 308 to report the status of activity triggered by each uCDN. 310 A collection of Trigger Status Resources is a resource that contains 311 a reference to each Trigger Status Resource in that collection. 313 The dCDN MUST make a collection of a uCDN's Trigger Status Resources 314 available to that uCDN. This collection includes all of the Trigger 315 Status Resources created for CI/T Commands from the uCDN that have 316 been accepted by the dCDN, and have not yet been deleted by the uCDN, 317 or expired and removed by the dCDN (as described in section 318 Section 4.4). Trigger Status Resources belonging to a uCDN MUST NOT 319 be visible to any other CDN. The dCDN could, for example, achieve 320 this by offering different collection URLs to each uCDN, and/or by 321 filtering the response based on the uCDN with which the HTTP client 322 is associated. 324 To trigger activity in a dCDN, or to cancel triggered activity, the 325 uCDN POSTs a CI/T Command to the dCDN's collection of the uCDN's 326 Trigger Status Resources. 328 In order to allow the uCDN to check the status of multiple jobs in a 329 single request, the dCDN SHOULD also maintain collections 330 representing filtered views of the collection of all Trigger Status 331 Resources. These filtered collections are optional-to-implement but, 332 if implemented, the dCDN MUST include links to them in the collection 333 of all Trigger Status Resources. The filtered collections are: 335 o Pending - Trigger Status Resources for CI/T Trigger Commands that 336 have been accepted, but not yet acted upon. 338 o Active - Trigger Status Resources for CI/T Trigger Commands that 339 are currently being processed in the dCDN. 341 o Complete - Trigger Status Resources representing activity that 342 completed successfully, and 'processed' CI/T Trigger Commands for 343 which no further status updates will be made by the dCDN. 345 o Failed - Trigger Status Resources representing CI/T Commands that 346 failes or were cancelled by the uCDN. 348 4. CDNI Trigger Interface 350 This section describes an interface to enable an upstream CDN to 351 trigger activity in a downstream CDN. 353 The CI/T interface builds on top of HTTP, so dCDNs may make use of 354 any HTTP feature when implementing the CI/T interface. For example, 355 a dCDN SHOULD make use of HTTP's caching mechanisms to indicate that 356 a requested response/representation has not been modified, reducing 357 the uCDN's processing needed to determine whether the status of 358 triggered activity has changed. 360 All dCDNs implementing CI/T MUST support the HTTP GET, HEAD, POST and 361 DELETE methods as defined in [RFC7231]. 363 The only representation specified in this document is JSON, 364 [RFC7159]. It MUST be supported by the uCDN and by the dCDN. 366 The URL of the dCDN's collection of all Trigger Status Resources 367 needs to be either discovered by, or configured in, the uCDN. The 368 mechanism for discovery of that URL is outside the scope of this 369 document. 371 CI/T Commands are POSTed to the dCDN's collection of all Trigger 372 Status Resources. If a CI/T Trigger Command is accepted by the dCDN, 373 the dCDN creates a new Trigger Status Resource and returns its URI to 374 the uCDN in an HTTP 201 response. The triggered activity can then be 375 monitored by the uCDN using that resource and the collections 376 described in Section 3. 378 The URI of each Trigger Status Resource is returned to the uCDN when 379 it is created, and URIs of all Trigger Status Resources are listed in 380 the dCDN's collection of all Trigger Status Resources. This means 381 all Trigger Status Resources can be discovered by the uCDN, so dCDNs 382 are free to assign whatever structure they desire to the URIs for CI/ 383 T resources. Therefore uCDNs MUST NOT make any assumptions regarding 384 the structure of CI/T URIs or the mapping between CI/T objects and 385 their associated URIs. URIs present in the examples in this document 386 are purely illustrative and are not intended to impose a definitive 387 structure on CI/T interface implementations. 389 4.1. Creating Triggers 391 To issue a CI/T Command, the uCDN makes an HTTP POST to the dCDN's 392 collection of all of the uCDN's Trigger Status Resources. The 393 request body of that POST is a CI/T Command, as described in 394 Section 5.1.1. 396 The dCDN validates the CI/T Command. If the command is malformed or 397 the uCDN does not have sufficient access rights, the dCDN MUST either 398 respond with an appropriate 4xx HTTP error code and not create a 399 Trigger Status Resource, or create a 'failed' Trigger Status Resource 400 containing an appropriate error description. 402 When a CI/T Trigger Command is accepted, the uCDN MUST create a new 403 Trigger Status Resource which will convey a specification of the CI/T 404 Command and its current status. The HTTP response to the dCDN MUST 405 have status code 201 and MUST convey the URI of the Trigger Status 406 Resource in the Location header field. The HTTP response SHOULD 407 include the content of the newly created Trigger Status Resource. 408 This is particularly important in cases where the CI/T Trigger 409 Command has completed immediately. 411 Once a Trigger Status Resource has been created the dCDN MUST NOT re- 412 use its URI, even after that Trigger Status Resource has been 413 removed. 415 The dCDN SHOULD track and report on progress of CI/T Trigger 416 Commands. If the dCDN is not able to do that, it MUST indicate that 417 it has accepted the request but will not be providing further status 418 updates. To do this, it sets the "status" of the Trigger Status 419 Resource to "processed". In this case, CI/T processing should 420 continue as for a "complete" request, so the Trigger Status Resource 421 MUST be added to the dCDN's collection of Complete Trigger Status 422 Resources. The dCDN SHOULD also provide an estimated completion time 423 for the request, by using the "etime" property of the Trigger Status 424 Resource. This will allow the uCDN to schedule prepositioning after 425 an earlier delete of the same URLs is expected to have finished. 427 If the dCDN is able to track the execution of CI/T Commands and a CI/ 428 T Command is queued by the dCDN for later action, the "status" 429 property of the Trigger Status Resource MUST be "pending". Once 430 processing has started the "status" MUST be "active". Finally, once 431 the CI/T Command is complete, the status MUST be set to "complete" or 432 "failed". 434 A CI/T Trigger Command may result in no activity in the dCDN if, for 435 example, it is an invalidate or purge request for data the dCDN has 436 not yet acquired, or a prepopulate request for data it has already 437 acquired and which is still valid. In this case, the "status" of the 438 Trigger Status Resource MUST be "processed" or "complete", and the 439 Trigger Status Resource MUST be added to the dCDN's collection of 440 Complete Trigger Status Resources. 442 Once created, Trigger Status Resources can be cancelled or deleted by 443 the uCDN, but not modified. The dCDN MUST reject PUT and POST 444 requests from the uCDN to Trigger Status Resources by responding with 445 an appropriate HTTP status code, for example 405 "Method Not 446 Allowed". 448 4.2. Checking Status 450 The uCDN has two ways to check progress of CI/T Commands it has 451 issued to the dCDN, described in sections Section 4.2.1 and 452 Section 4.2.2. 454 To allow the uCDN to check for change in status of a Trigger Status 455 Resource or collection of Trigger Status Resources without re- 456 fetching the whole Resource or Collection, the dCDN SHOULD include 457 Entity Tags for the uCDN to use as cache validators, as defined in 458 [RFC7232]. 460 The dCDN SHOULD use the cache control headers for responses to GETs 461 for Trigger Status Resources and Collections to indicate the 462 frequency at which it recommends the uCDN should poll for change. 464 4.2.1. Polling Trigger Status Resource collections 466 The uCDN can fetch the collection of its Trigger Status Resources, or 467 filtered views of that collection. 469 This makes it possible to poll status of all CI/T Trigger Commands in 470 a single request. If the dCDN moves a Trigger Status Resource from 471 the Active to the Completed collection, the uCDN can fetch the result 472 of that activity. 474 When polling in this way, the uCDN SHOULD use HTTP Entity Tags to 475 monitor for change, rather than repeatedly fetching the whole 476 collection. An example of this is given in section Section 6.2.4. 478 4.2.2. Polling Trigger Status Resources 480 The uCDN has a URI provided by the dCDN for each Trigger Status 481 Resource it has created, it may fetch that Trigger Status Resource at 482 any time. 484 This can be used to retrieve progress information, and to fetch the 485 result of the CI/T Command. 487 When polling in this way, the uCDN SHOULD use HTTP Entity Tags to 488 monitor for change, rather than repeatedly fetching the Trigger 489 Status Resource. 491 4.3. Cancelling Triggers 493 The uCDN can request cancellation of a CI/T Trigger Command by 494 POSTing a CI/T Cancel Command to the collection of all Trigger Status 495 Resources. 497 The dCDN is required to accept and respond to the CI/T Cancel 498 Command, but the actual cancellation of a CI/T Trigger Command is 499 optional-to-implement. 501 The dCDN MUST respond to the CI/T Cancel Command appropriately, for 502 example with HTTP status code 200 "OK" if the cancellation has been 503 processed and the CI/T Command is inactive, 202 "Accepted" if the 504 command has been accepted but the CI/T Command remains active, or 501 505 "Not Implemented" if cancellation is not supported by the dCDN. 507 If cancellation of a "pending" Trigger Status Resource is accepted by 508 the dCDN, the dCDN SHOULD NOT start processing of that activity. 509 Issuing a CT/T Cancel Command for a "pending" Trigger Status Resource 510 does not however guarantee that the corresponding activity will not 511 be started, because the uCDN cannot control the timing of that 512 activity. Processing could, for example, start after the POST is 513 sent by the uCDN but before that request is processed by the dCDN. 515 If cancellation of an "active" or "processed" Trigger Status Resource 516 is accepted by the dCDN, the dCDN SHOULD stop processing the CI/T 517 Command. However, as with cancellation of a "pending" CI/T Command, 518 the dCDN does not guarantee this. 520 If the CI/T Command cannot be stopped immediately, the status in the 521 corresponding Trigger Status Resource MUST be set to "cancelling", 522 and the Trigger Status Resource MUST remain in the collection of 523 Trigger Status Resources for active CI/T Commands. If processing is 524 stopped before normal completion, the status value in the Trigger 525 Status Resource MUST be set to "cancelled", and the Trigger Status 526 Resource MUST be included in the collection of failed CT/T Trigger 527 Commands. 529 Cancellation of a "complete" or "failed" Trigger Status Resource 530 requires no processing in the dCDN, its status MUST NOT be changed to 531 "cancelled". 533 4.4. Deleting Triggers 535 The uCDN can delete Trigger Status Resources at any time, using the 536 HTTP DELETE method. The effect is similar to cancellation, but no 537 Trigger Status Resource remains afterwards. 539 Once deleted, the references to a Trigger Status Resource MUST be 540 removed from all Trigger Status Resource collections. Subsequent 541 requests to GET the deleted Trigger Status Resource SHOULD be 542 rejected by the dCDN with an HTTP error. 544 If a "pending" Trigger Status Resource is deleted, the dCDN SHOULD 545 NOT start processing of that activity. Deleting a "pending" Trigger 546 Status Resource does not however guarantee that it has not started 547 because the uCDN cannot control the timing of that activity. 548 Processing may, for example, start after the DELETE is sent by the 549 uCDN but before that request is processed by the dCDN. 551 If an "active" or "processed" Trigger Status Resource is deleted, the 552 dCDN SHOULD stop processing the CI/T Command. However, as with 553 deletion of a "pending" Trigger Status Resource, the dCDN does not 554 guarantee this. 556 Deletion of a "complete" or "failed" Trigger Status Resource requires 557 no processing in the dCDN other than deletion of the Trigger Status 558 Resource. 560 4.5. Expiry of Trigger Status Resources 562 The dCDN can choose to automatically delete Trigger Status Resources 563 some time after they become "complete", "processed", "failed" or 564 "cancelled". In this case, the dCDN will remove the Trigger Status 565 Resource and respond to subsequent requests for it with an HTTP 566 error. 568 If the dCDN performs this housekeeping, it MUST have reported the 569 length of time after which completed Trigger Status Resources will be 570 deleted via a property of the collection of all Trigger Status 571 Resources. It is RECOMMENDED that Trigger Status Resources are not 572 automatically deleted by the dCDN for at least 24 hours after they 573 become "complete", "processed", "failed" or "cancelled". 575 To ensure it is able to get the status of its Trigger Status 576 Resources for completed and failed CI/T Commands, it is RECOMMENDED 577 that the uCDN polling interval is less than the time after which 578 records for completed activity will be deleted. 580 4.6. Loop Detection and Prevention 582 Given three CDNs, A, B and C. If CDNs B and C delegate delivery of 583 CDN A's content to each other, CDN A's CI/T Commands could be passed 584 between CDNs B and C in a loop. More complex networks of CDNs could 585 contain similar loops involving more hops. 587 In order to prevent and detect such CI/T loops, each CDN uses a CDN 588 Provider ID to uniquely identify itself. In every CI/T Command it 589 originates or cascades, each CDN MUST append an array element 590 containing its CDN Provider ID to a JSON array under an entry named 591 "cdn-path". When receiving CI/T Commands a dCDN MUST check the cdn- 592 path and reject any CI/T Command which already contains its own CDN 593 Provider ID in the cdn-path. Transit CDNs MUST check the cdn-path 594 and not cascade the CI/T Command to dCDNs that are already listed in 595 cdn-path. 597 The CDN Provider Id consists of the two characters "AS" followed by 598 the CDN Provider's Autonomous System number, then a colon (':') and 599 an additional qualifier that is used to guarantee uniqueness in case 600 a particular AS has multiple independent CDNs deployed. For example 601 "AS64496:0". 603 If the CDN provider has multiple Autonomous Systems, the same AS 604 number SHOULD be used in all messages from that CDN provider, unless 605 there are multiple distinct CDNs. 607 If the RI interface described in [I-D.ietf-cdni-redirection] is 608 implemented by the dCDN, the CI/T and RI interfaces SHOULD use the 609 same CDN Provider Id. 611 4.7. Error Handling 613 A dCDN can signal rejection of a CI/T Command using HTTP status 614 codes. For example, 400 if the request is malformed, or 403 or 404 615 if the uCDN does not have permission to issue CI/T Commands or it is 616 trying to act on another CDN's data. 618 If any part of the CI/T Trigger Command fails, the trigger SHOULD be 619 reported as "failed" once its activity is complete or if no further 620 errors will be reported. The "errors" property in the Trigger Status 621 Resource will be used to enumerate which actions failed and the 622 reasons for failure, and can be present while the Trigger Status 623 Resource is still "pending" or "active", if the CI/T Trigger Command 624 is still running for some URLs or Patterns in the Trigger 625 Specification. 627 Once a request has been accepted, processing errors are reported in 628 the Trigger Status Resource using a list of Error Descriptions. Each 629 Error Description is used to report errors against one or more of the 630 URLs or Patterns in the Trigger Specification. 632 If a surrogate affected by a CI/T Trigger Command is offline in the 633 dCDN, or the dCDN is unable to pass a CI/T Command on to any of its 634 cascaded dCDNs: 636 o If the CI/T Command is abandoned by the dCDN, the dCDN SHOULD 637 report an error. 639 o A CI/T "invalidate" command may be reported as "complete" when 640 surrogates that may have the data are offline. In this case, 641 surrogates MUST NOT use the affected data without first 642 revalidating it when they are back online. 644 o CI/T "preposition" and "purge" commands can be reported as 645 "processed" if affected caches are offline and the activity will 646 complete when they return to service. 648 o Otherwise, the dCDN SHOULD keep the Trigger Status Resource in 649 state "pending" or "active" until the CI/T Command is acted upon, 650 or the uCDN chooses to cancel it. 652 4.8. Content URLs 654 If content URLs are transformed by an intermediate CDN in a cascade, 655 that intermediate CDN MUST transform URLs in CI/T Commands it passes 656 to its dCDN. 658 When processing Trigger Specifications, CDNs MUST ignore the URL 659 scheme (http or https) in comparing URLs. For example, for a CI/T 660 invalidate or purge command, content MUST be invalidated or purged 661 regardless of the protocol clients use to request it. 663 5. CI/T Object Properties and Encoding 665 CI/T Commands, Trigger Status Resources and Trigger Collections and 666 their properties are encoded using JSON, as defined in sections 667 Section 5.1.1, Section 5.2.1, and Section 5.1.2. They MUST use the 668 MIME Media Type 'application/cdni', with parameter 'ptype' values as 669 defined below and in Section 7.1. 671 Names in JSON are case sensitive. The names and literal values 672 specified in the present document MUST always use lower-case. 674 JSON types, including 'object', 'array', 'number' and 'string' are 675 defined in [RFC7159]. 677 Unrecognised name/value pairs in JSON objects SHOULD NOT be treated 678 as an error by either the uCDN or dCDN. They SHOULD be ignored in 679 the processing, and passed on by dCDN to any further dCDNs in a 680 cascade. 682 5.1. CI/T Objects 684 The top-level objects defined by the CI/T interface are described in 685 this section. 687 The encoding of values used by these objects is described in 688 Section 5.2. 690 5.1.1. CI/T Commands 692 CI/T Commands MUST use a MIME Media Type of 'application/cdni; 693 ptype=ci-trigger-command'. 695 A CI/T Command is encoded as a JSON object containing the following 696 name/value pairs. 698 Name: trigger 700 Description: A specification of the trigger type, and a set of 701 data to act upon. 703 Value: A Trigger Specification, as defined in Section 5.2.1. 705 Mandatory: No, but exactly one of "trigger" or "cancel" MUST be 706 present in a CI/T Command. 708 Name: cancel 710 Description: The URLs of Trigger Status Resources for CI/T 711 Trigger Commands that the uCDN wants to cancel. 713 Value: A non-empty JSON array of URLs represented as JSON 714 strings. 716 Mandatory: No, but exactly one of "trigger" or "cancel" MUST be 717 present in a CI/T Command. 719 Name: cdn-path 721 Description: The CDN Provider Identifiers of CDNs that have 722 already accepted the CI/T Command. 724 Value: A non-empty JSON array of JSON strings, where each 725 string is a CDN Provider Identifier as defined in Section 4.6. 727 Mandatory: Yes. 729 5.1.2. Trigger Status Resource 731 Trigger Status Resources MUST use a MIME Media Type of 'application/ 732 cdni; ptype=ci-trigger-status'. 734 A Trigger Status Resource is encoded as a JSON object containing the 735 following name/value pairs. 737 Name: trigger 739 Description: The Trigger Specification posted in the body of 740 the CI/T Command. Note that this need not be a byte-for-byte 741 copy. For example, in the JSON representation the dCDN may re- 742 serialise the information differently. 744 Value: A Trigger Specification, as defined in Section 5.2.1. 746 Mandatory: Yes 748 Name: ctime 750 Description: Time at which the CI/T Command was received by the 751 dCDN. Time is determined by the dCDN, there is no requirement 752 to synchronise clocks between interconnected CDNs. 754 Value: Absolute Time, as defined in Section 5.2.5. 756 Mandatory: Yes 758 Name: mtime 760 Description: Time at which the Trigger Status Resource was last 761 modified. Time is determined by the dCDN, there is no 762 requirement to synchronise clocks between interconnected CDNs. 764 Value: Absolute Time, as defined in Section 5.2.5. 766 Mandatory: Yes 768 Name: etime 770 Description: Estimate of the time at which the dCDN expects to 771 complete the activity. Time is determined by the dCDN, there 772 is no requirement to synchronise clocks between interconnected 773 CDNs. 775 Value: Absolute Time, as defined in Section 5.2.5. 777 Mandatory: No 779 Name: status 781 Description: Current status of the triggered activity. 783 Value: Trigger Status, as defined in Section 5.2.3. 785 Mandatory: Yes 787 Name: errors 789 Description: Descriptions of errors that have occurred while 790 processing a Trigger Command. 792 Value: An array of Error Description, as defined in 793 Section 5.2.6. An empty array is allowed, and equivalent to 794 omitting "errors" from the object. 796 Mandatory: No. 798 5.1.3. Trigger Collection 800 Trigger Collections MUST use a MIME Media Type of 'application/cdni; 801 ptype=ci-trigger-collection'. 803 A Trigger Collection is encoded as a JSON object containing the 804 following name/value pairs. 806 Name: triggers 808 Description: Links to Trigger Status Resources in the 809 collection. 811 Value: A JSON array of zero or more URLs, represented as JSON 812 strings. 814 Mandatory: Yes 816 Name: staleresourcetime 818 Description: The length of time for which the dCDN guarantees 819 to keep a completed Trigger Status Resource. After this time, 820 the dCDN SHOULD delete the Trigger Status Resource and all 821 references to it from collections. 823 Value: A JSON number, which must be a positive integer, 824 representing time in seconds. 826 Mandatory: Yes, in the collection of all Trigger Status 827 Resources if the dCDN deletes stale entries. If the property 828 is present in the filtered collections, it MUST have the same 829 value as in the collection of all Trigger Status Resources. 831 Names: coll-all, coll-pending, coll-active, coll-complete, coll- 832 failed 834 Description: Link to a Trigger Collection. 836 Value: A URL represented as a JSON string. 838 Mandatory: Links to all of the filtered collections are 839 mandatory in the collection of all Trigger Status Resources, if 840 the dCDN implements the filtered collections. Otherwise, 841 optional. 843 Name: cdn-id 845 Description: The CDN Provider Identifier of the dCDN. 847 Value: A JSON string, the dCDN's CDN Provider Identifier, as 848 defined in Section 4.6. 850 Mandatory: Only in the collection of all Trigger Status 851 Resources, if the dCDN implements the filtered collections. 852 Optional in the filtered collections (the uCDN can always find 853 the dCDN's cdn-id in the collection of all Trigger Status 854 Resources, but the dCDN can choose to repeat that information 855 in its implementation of filtered collections). 857 5.2. Properties of CI/T Objects 859 This section defines the values that can appear in the top level 860 objects described in Section 5.1, and their encodings. 862 5.2.1. Trigger Specification 864 A Trigger Collection is encoded as a JSON object containing the 865 following name/value pairs. 867 An unrecognised name/value pair in the Trigger Specification object 868 contained in a CI/T Command SHOULD be preserved in the Trigger 869 Specification of any Trigger Status Resource it creates. 871 Name: type 873 Description: This property defines the type of the CI/T Trigger 874 Command. 876 Value: Trigger Type, as defined in Section 5.2.2. 878 Mandatory: Yes 880 Name: metadata.urls 882 Description: The uCDN URLs of the metadata the CI/T Trigger 883 Command applies to. 885 Value: A JSON array of URLs represented as JSON strings. 887 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 888 MUST be present and non-empty. 890 Name: content.urls 892 Description: URLs of content the CI/T Trigger Command applies 893 to, see Section 4.8. 895 Value: A JSON array of URLs represented as JSON strings. 897 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 898 MUST be present and non-empty. 900 Name: content.ccid 902 Description: The Content Collection Identifier of content the 903 trigger applies to. The 'ccid' is a grouping of content, as 904 defined by [I-D.ietf-cdni-metadata]. 906 Value: A JSON array of strings, where each string is a Content 907 Collection Identifier. 909 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 910 MUST be present and non-empty. 912 Name: metadata.patterns 914 Description: The metadata the trigger applies to. 916 Value: A JSON array of Pattern Match, as defined in 917 Section 5.2.4. 919 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 920 MUST be present and non-empty, and metadata.patterns MUST NOT 921 be present if the TriggerType is Preposition. 923 Name: content.patterns 925 Description: The content data the trigger applies to. 927 Value: A JSON array of Pattern Match, as defined in 928 Section 5.2.4. 930 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 931 MUST be present and non-empty, and content.patterns MUST NOT be 932 present if the TriggerType is Preposition. 934 5.2.2. Trigger Type 936 Trigger Type is used in a Trigger Specification to describe trigger 937 action. It MUST be one of the JSON strings in the following table: 939 +-------------+-----------------------------------------------------+ 940 | JSON String | Description | 941 +-------------+-----------------------------------------------------+ 942 | preposition | A request for the dCDN to acquire metadata or | 943 | | content. | 944 | invalidate | A request for the dCDN to invalidate metadata or | 945 | | content. After servicing this request the dCDN will | 946 | | not use the specified data without first re- | 947 | | validating it using, for example, an "If-None- | 948 | | Match" HTTP request. The dCDN need not erase the | 949 | | associated data. | 950 | purge | A request for the dCDN to erase metadata or | 951 | | content. After servicing the request, the specified | 952 | | data MUST NOT be held on the dCDN (the dCDN should | 953 | | re-acquire the metadata or content from uCDN if it | 954 | | needs it). | 955 +-------------+-----------------------------------------------------+ 957 5.2.3. Trigger Status 959 This describes the current status of a Trigger. It MUST be one of 960 the JSON strings in the following table: 962 +------------+------------------------------------------------------+ 963 | JSON | Description | 964 | String | | 965 +------------+------------------------------------------------------+ 966 | pending | The CI/T Trigger Command has not yet been acted | 967 | | upon. | 968 | active | The CI/T Trigger Command is currently being acted | 969 | | upon. | 970 | complete | The CI/T Trigger Command completed successfully. | 971 | processed | The CI/T Trigger Command has been accepted and no | 972 | | further status update will be made (can be used in | 973 | | cases where completion cannot be confirmed). | 974 | failed | The CI/T Trigger Command could not be completed. | 975 | cancelling | Processing of the CI/T Trigger Command is still in | 976 | | progress, but the CI/T Trigger Command has been | 977 | | cancelled by the uCDN. | 978 | cancelled | The CI/T Trigger Command was cancelled by the uCDN. | 979 +------------+------------------------------------------------------+ 981 5.2.4. PatternMatch 983 A Pattern Match consists of a string pattern to match against a URI, 984 and flags describing the type of match. 986 It is encoded as a JSON object with the following name/value pairs: 988 Name: pattern 990 Description: A pattern for URI matching. 992 Value: A JSON string representing the pattern. The pattern may 993 contain the wildcards * and ?, where * matches any sequence of 994 characters (including the empty string) and ? matches exactly 995 one character. The three literals "\" , "*" and "?" MUST be 996 escaped as "\\", "\*" and "\?". 998 Mandatory: Yes. 1000 Name: case-sensitive 1002 Description: Flag indicating whether or not case-sensitive 1003 matching should be used. 1005 Value: One of the JSON values 'true' (the matching is case- 1006 sensitive) or 'false' (the matching is case-insensitive). 1008 Mandatory: No, default is case-insensitive match. 1010 Name: match-query-string 1012 Description: Flag indicating whether or not the query part of 1013 the URI should be included in the pattern match. 1015 Value: One of the JSON values 'true' (the full URI including 1016 the query part should be compared against the given pattern), 1017 or 'false' (the query part of the URI should be dropped before 1018 comparison with the given pattern). 1020 Mandatory: No, default is 'false', the query part of the URI 1021 should be dropped before comparison with the given pattern. 1023 Example of case-sensitive prefix match against 1024 "http://www.example.com/trailers/": 1026 { 1027 "pattern": "http://www.example.com/trailers/*", 1028 "case-sensitive": true 1029 } 1031 5.2.5. Absolute Time 1033 A JSON number, seconds since the UNIX epoch, 00:00:00 UTC on 1 1034 January 1970. 1036 5.2.6. Error Description 1038 An Error Description is used to report failure of a CI/T Command, or 1039 in the activity it triggered. It is encoded as a JSON object with 1040 the following name/value pairs: 1042 Name: error 1044 Value: Error Code, as defined in Section 5.2.7. 1046 Mandatory: Yes. 1048 Names: metadata.urls, content.urls, metadata.patterns, 1049 content.patterns 1051 Description: Metadata and content references copied from the 1052 Trigger Specification. Only those URLs and patterns to which 1053 the error applies are included in each property, but those URLs 1054 and patterns MUST be exactly as they appear in the request, the 1055 dCDN MUST NOT generalise the URLs. (For example, if the uCDN 1056 requests prepositioning of URLs "http://content.example.com/a" 1057 and "http://content.example.com/b", the dCDN must not 1058 generalise its error report to Pattern 1059 "http://content.example.com/*".) 1061 Value: A JSON array of JSON strings, where each string is 1062 copied from a 'content.*' or 'metadata.*' value in the 1063 corresponding Trigger Specification. 1065 Mandatory: At least one of these name/value pairs is mandatory 1066 in each Error Description object. 1068 Name: description 1070 Description: A human-readable description of the error. 1072 Value: A JSON string, the human-readable description. 1074 Mandatory: No. 1076 5.2.7. Error Code 1078 This type is used by the dCDN to report failures in trigger 1079 processing. 1081 +------------+------------------------------------------------------+ 1082 | Error Code | Description | 1083 +------------+------------------------------------------------------+ 1084 | emeta | The dCDN was unable to acquire metadata required to | 1085 | | fulfil the request. | 1086 | econtent | The dCDN was unable to acquire content (CT/T | 1087 | | preposition commands only). | 1088 | eperm | The uCDN does not have permission to issue the CI/T | 1089 | | Command (for example, the data is owned by another | 1090 | | CDN). | 1091 | ereject | The dCDN is not willing to fulfil the CI/T Command | 1092 | | (for example, a preposition request for content at a | 1093 | | time when the dCDN would not accept Request Routing | 1094 | | requests from the uCDN). | 1095 | ecdn | An internal error in the dCDN or one of its | 1096 | | downstream CDNs. | 1097 | ecancelled | The uCDN cancelled the request. | 1098 +------------+------------------------------------------------------+ 1100 6. Examples 1102 The following sections provide examples of different CI/T objects 1103 encoded as JSON. 1105 Discovery of the triggers interface is out of scope of this document. 1106 In an implementation, all CI/T URLs are under the control of the 1107 dCDN. The uCDN MUST NOT attempt to ascribe any meaning to individual 1108 elements of the path. 1110 In examples in this section, the URL 'http://dcdn.example.com/ 1111 triggers' is used as the location of the collection of all Trigger 1112 Status Resources, and the CDN Provider Id of uCDN is "AS64496:1". 1114 6.1. Creating Triggers 1116 Examples of the uCDN triggering activity in the dCDN: 1118 6.1.1. Preposition 1120 An example of a CI/T preposition command, a POST to the collection of 1121 all Trigger Status Resources. 1123 Note that "metadata.patterns" and "content.patterns" are not allowed 1124 in a preposition Trigger Specification. 1126 REQUEST: 1128 POST /triggers HTTP/1.1 1129 User-Agent: example-user-agent/0.1 1130 Host: dcdn.example.com 1131 Accept: */* 1132 Content-Type: application/cdni; ptype=ci-trigger-command 1133 Content-Length: 347 1135 { 1136 "trigger" : { 1137 "type": "preposition", 1139 "metadata.urls" : [ "http://metadata.example.com/a/b/c" ], 1140 "content.urls" : [ 1141 "http://www.example.com/a/b/c/1", 1142 "http://www.example.com/a/b/c/2", 1143 "http://www.example.com/a/b/c/3", 1144 "http://www.example.com/a/b/c/4" 1145 ] 1146 }, 1147 "cdn-path" : [ "AS64496:1" ] 1149 } 1151 RESPONSE: 1153 HTTP/1.1 201 Created 1154 Date: Sun, 06 Dec 2015 17:18:46 GMT 1155 Content-Length: 462 1156 Content-Type: application/cdni; ptype=ci-trigger-status 1157 Location: http://dcdn.example.com/triggers/0 1158 Server: example-server/0.1 1160 { 1161 "ctime": 1449422326, 1162 "etime": 1449422334, 1163 "mtime": 1449422326, 1164 "status": "pending", 1165 "trigger": { 1166 "content.urls": [ 1167 "http://www.example.com/a/b/c/1", 1168 "http://www.example.com/a/b/c/2", 1169 "http://www.example.com/a/b/c/3", 1170 "http://www.example.com/a/b/c/4" 1171 ], 1172 "metadata.urls": [ 1173 "http://metadata.example.com/a/b/c" 1174 ], 1175 "type": "preposition" 1176 } 1177 } 1179 6.1.2. Invalidate 1181 An example of a CI/T invalidate command, another POST to the 1182 collection of all Trigger Status Resources. This instructs the dCDN 1183 to re-validate the content at "http://www.example.com/a/index.html", 1184 as well as any metadata and content whose URLs are prefixed by 1185 "http://metadata.example.com/a/b/" using case-insensitive matching, 1186 and "http://www.example.com/a/b/" respectively, using case-sensitive 1187 matching. 1189 REQUEST: 1191 POST /triggers HTTP/1.1 1192 User-Agent: example-user-agent/0.1 1193 Host: dcdn.example.com 1194 Accept: */* 1195 Content-Type: application/cdni; ptype=ci-trigger-command 1196 Content-Length: 384 1197 { 1198 "trigger" : { 1199 "type": "invalidate", 1201 "metadata.patterns" : [ 1202 { "pattern" : "http://metadata.example.com/a/b/*" } 1203 ], 1205 "content.urls" : [ "http://www.example.com/a/index.html" ], 1206 "content.patterns" : [ 1207 { "pattern" : "http://www.example.com/a/b/*", 1208 "case-sensitive" : true 1209 } 1210 ] 1211 }, 1212 "cdn-path" : [ "AS64496:1" ] 1213 } 1215 RESPONSE: 1217 HTTP/1.1 201 Created 1218 Date: Sun, 06 Dec 2015 17:18:46 GMT 1219 Content-Length: 542 1220 Content-Type: application/cdni; ptype=ci-trigger-status 1221 Location: http://dcdn.example.com/triggers/1 1222 Server: example-server/0.1 1224 { 1225 "ctime": 1449422326, 1226 "etime": 1449422334, 1227 "mtime": 1449422326, 1228 "status": "pending", 1229 "trigger": { 1230 "content.patterns": [ 1231 { 1232 "case-sensitive": true, 1233 "pattern": "http://www.example.com/a/b/*" 1234 } 1235 ], 1236 "content.urls": [ 1237 "http://www.example.com/a/index.html" 1238 ], 1239 "metadata.patterns": [ 1240 { 1241 "pattern": "http://metadata.example.com/a/b/*" 1242 } 1243 ], 1244 "type": "invalidate" 1246 } 1247 } 1249 6.2. Examining Trigger Status 1251 Once Trigger Status Resources have been created, the uCDN can check 1252 their status as shown in these examples. 1254 6.2.1. Collection of All Triggers 1256 The uCDN can fetch the collection of all Trigger Status Resources it 1257 has created that have not yet been deleted or removed as expired. 1258 After creation of the "preposition" and "invalidate" triggers shown 1259 above, this collection might look as follows: 1261 REQUEST: 1263 GET /triggers HTTP/1.1 1264 User-Agent: example-user-agent/0.1 1265 Host: dcdn.example.com 1266 Accept: */* 1268 RESPONSE: 1270 HTTP/1.1 200 OK 1271 Content-Length: 339 1272 Expires: Sun, 06 Dec 2015 17:19:46 GMT 1273 Server: example-server/0.1 1274 ETag: "-8770885545613447380" 1275 Cache-Control: max-age=60 1276 Date: Sun, 06 Dec 2015 17:18:46 GMT 1277 Content-Type: application/cdni; ptype=ci-trigger-collection 1279 { 1280 "cdn-id": "AS64496:0", 1281 "coll-active": "/triggers/active", 1282 "coll-complete": "/triggers/complete", 1283 "coll-failed": "/triggers/failed", 1284 "coll-pending": "/triggers/pending", 1285 "staleresourcetime": 86400, 1286 "triggers": [ 1287 "http://dcdn.example.com/triggers/0", 1288 "http://dcdn.example.com/triggers/1" 1289 ] 1290 } 1292 6.2.2. Filtered Collections of Trigger Status Resources 1294 The filtered collections are also available to the uCDN. Before the 1295 dCDN starts processing the two CI/T Trigger Commands shown above, 1296 both will appear in the collection of Pending Triggers, for example: 1298 REQUEST: 1300 GET /triggers/pending HTTP/1.1 1301 User-Agent: example-user-agent/0.1 1302 Host: dcdn.example.com 1303 Accept: */* 1305 RESPONSE: 1307 HTTP/1.1 200 OK 1308 Content-Length: 150 1309 Expires: Sun, 06 Dec 2015 17:19:46 GMT 1310 Server: example-server/0.1 1311 ETag: "-1475121655268178613" 1312 Cache-Control: max-age=60 1313 Date: Sun, 06 Dec 2015 17:18:46 GMT 1314 Content-Type: application/cdni; ptype=ci-trigger-collection 1316 { 1317 "staleresourcetime": 86400, 1318 "triggers": [ 1319 "http://dcdn.example.com/triggers/0", 1320 "http://dcdn.example.com/triggers/1" 1321 ] 1322 } 1324 At this point, if no other Trigger Status Resources had been created, 1325 the other filtered views would be empty. For example: 1327 REQUEST: 1329 GET /triggers/complete HTTP/1.1 1330 User-Agent: example-user-agent/0.1 1331 Host: dcdn.example.com 1332 Accept: */* 1334 RESPONSE: 1336 HTTP/1.1 200 OK 1337 Content-Length: 54 1338 Expires: Sun, 06 Dec 2015 17:19:46 GMT 1339 Server: example-server/0.1 1340 ETag: "7958041393922269003" 1341 Cache-Control: max-age=60 1342 Date: Sun, 06 Dec 2015 17:18:46 GMT 1343 Content-Type: application/cdni; ptype=ci-trigger-collection 1345 { 1346 "staleresourcetime": 86400, 1347 "triggers": [] 1348 } 1350 6.2.3. Individual Trigger Status Resources 1352 The Trigger Status Resources can also be examined for detail about 1353 individual CI/T Trigger Commands. For example, for the CI/T 1354 "preposition" and "invalidate" commands from previous examples: 1356 REQUEST: 1358 GET /triggers/0 HTTP/1.1 1359 User-Agent: example-user-agent/0.1 1360 Host: dcdn.example.com 1361 Accept: */* 1363 RESPONSE: 1365 HTTP/1.1 200 OK 1366 Content-Length: 462 1367 Expires: Sun, 06 Dec 2015 17:19:46 GMT 1368 Server: example-server/0.1 1369 ETag: "-256278637448610056" 1370 Cache-Control: max-age=60 1371 Date: Sun, 06 Dec 2015 17:18:46 GMT 1372 Content-Type: application/cdni; ptype=ci-trigger-status 1374 { 1375 "ctime": 1449422326, 1376 "etime": 1449422334, 1377 "mtime": 1449422326, 1378 "status": "pending", 1379 "trigger": { 1380 "content.urls": [ 1381 "http://www.example.com/a/b/c/1", 1382 "http://www.example.com/a/b/c/2", 1383 "http://www.example.com/a/b/c/3", 1384 "http://www.example.com/a/b/c/4" 1385 ], 1386 "metadata.urls": [ 1387 "http://metadata.example.com/a/b/c" 1388 ], 1389 "type": "preposition" 1390 } 1391 } 1393 REQUEST: 1395 GET /triggers/1 HTTP/1.1 1396 User-Agent: example-user-agent/0.1 1397 Host: dcdn.example.com 1398 Accept: */* 1400 RESPONSE: 1402 HTTP/1.1 200 OK 1403 Content-Length: 542 1404 Expires: Sun, 06 Dec 2015 17:19:47 GMT 1405 Server: example-server/0.1 1406 ETag: "-1202970338696035175" 1407 Cache-Control: max-age=60 1408 Date: Sun, 06 Dec 2015 17:18:47 GMT 1409 Content-Type: application/cdni; ptype=ci-trigger-status 1411 { 1412 "ctime": 1449422326, 1413 "etime": 1449422334, 1414 "mtime": 1449422326, 1415 "status": "pending", 1416 "trigger": { 1417 "content.patterns": [ 1418 { 1419 "case-sensitive": true, 1420 "pattern": "http://www.example.com/a/b/*" 1421 } 1422 ], 1423 "content.urls": [ 1424 "http://www.example.com/a/index.html" 1425 ], 1426 "metadata.patterns": [ 1427 { 1428 "pattern": "http://metadata.example.com/a/b/*" 1429 } 1430 ], 1431 "type": "invalidate" 1432 } 1433 } 1435 6.2.4. Polling for Change 1437 The uCDN SHOULD use the Entity Tags of collections or Trigger Status 1438 Resources when polling for change in status, as shown in the 1439 following examples: 1441 REQUEST: 1443 GET /triggers/pending HTTP/1.1 1444 User-Agent: example-user-agent/0.1 1445 Host: dcdn.example.com 1446 Accept: */* 1447 If-None-Match: "-1475121655268178613" 1449 RESPONSE: 1451 HTTP/1.1 304 Not Modified 1452 Content-Length: 0 1453 Expires: Sun, 06 Dec 2015 17:19:46 GMT 1454 Server: example-server/0.1 1455 ETag: "-1475121655268178613" 1456 Cache-Control: max-age=60 1457 Date: Sun, 06 Dec 2015 17:18:46 GMT 1458 Content-Type: application/cdni; ptype=ci-trigger-collection 1460 REQUEST: 1462 GET /triggers/0 HTTP/1.1 1463 User-Agent: example-user-agent/0.1 1464 Host: dcdn.example.com 1465 Accept: */* 1466 If-None-Match: "-256278637448610056" 1468 RESPONSE: 1470 HTTP/1.1 304 Not Modified 1471 Content-Length: 0 1472 Expires: Sun, 06 Dec 2015 17:19:46 GMT 1473 Server: example-server/0.1 1474 ETag: "-256278637448610056" 1475 Cache-Control: max-age=60 1476 Date: Sun, 06 Dec 2015 17:18:46 GMT 1477 Content-Type: application/cdni; ptype=ci-trigger-status 1479 When the CI/T Trigger Command is complete, the contents of the 1480 filtered collections will be updated along with their Entity Tags. 1481 For example, when the two example CI/T Trigger Commands are complete, 1482 the collections of pending and complete Trigger Status Resources 1483 might look like: 1485 REQUEST: 1487 GET /triggers/pending HTTP/1.1 1488 User-Agent: example-user-agent/0.1 1489 Host: dcdn.example.com 1490 Accept: */* 1492 RESPONSE: 1494 HTTP/1.1 200 OK 1495 Content-Length: 54 1496 Expires: Sun, 06 Dec 2015 17:19:51 GMT 1497 Server: example-server/0.1 1498 ETag: "1337503181677633762" 1499 Cache-Control: max-age=60 1500 Date: Sun, 06 Dec 2015 17:18:51 GMT 1501 Content-Type: application/cdni; ptype=ci-trigger-collection 1503 { 1504 "staleresourcetime": 86400, 1505 "triggers": [] 1506 } 1508 REQUEST: 1510 GET /triggers/complete HTTP/1.1 1511 User-Agent: example-user-agent/0.1 1512 Host: dcdn.example.com 1513 Accept: */* 1515 RESPONSE: 1517 HTTP/1.1 200 OK 1518 Content-Length: 150 1519 Expires: Sun, 06 Dec 2015 17:19:58 GMT 1520 Server: example-server/0.1 1521 ETag: "-2588648306194498266" 1522 Cache-Control: max-age=60 1523 Date: Sun, 06 Dec 2015 17:18:58 GMT 1524 Content-Type: application/cdni; ptype=ci-trigger-collection 1526 { 1527 "staleresourcetime": 86400, 1528 "triggers": [ 1529 "http://dcdn.example.com/triggers/0", 1530 "http://dcdn.example.com/triggers/1" 1531 ] 1532 } 1534 6.2.5. Deleting Trigger Status Resources 1536 The dCDN can delete completed and failed Trigger Status Resources to 1537 reduce the size of the collections. For example, to delete the 1538 "preposition" request from earlier examples: 1540 REQUEST: 1542 DELETE /triggers/0 HTTP/1.1 1543 User-Agent: example-user-agent/0.1 1544 Host: dcdn.example.com 1545 Accept: */* 1547 RESPONSE: 1549 HTTP/1.1 204 No Content 1550 Date: Sun, 06 Dec 2015 17:18:59 GMT 1551 Content-Length: 0 1552 Content-Type: text/html; charset=UTF-8 1553 Server: example-server/0.1 1555 This would, for example, cause the collection of completed Trigger 1556 Status Resources shown in the example above to be updated to: 1558 REQUEST: 1560 GET /triggers/complete HTTP/1.1 1561 User-Agent: example-user-agent/0.1 1562 Host: dcdn.example.com 1563 Accept: */* 1565 RESPONSE: 1567 HTTP/1.1 200 OK 1568 Content-Length: 104 1569 Expires: Sun, 06 Dec 2015 17:19:59 GMT 1570 Server: example-server/0.1 1571 ETag: "6647924643429037709" 1572 Cache-Control: max-age=60 1573 Date: Sun, 06 Dec 2015 17:18:59 GMT 1574 Content-Type: application/cdni; ptype=ci-trigger-collection 1576 { 1577 "staleresourcetime": 86400, 1578 "triggers": [ 1579 "http://dcdn.example.com/triggers/1" 1580 ] 1581 } 1583 6.2.6. Error Reporting 1585 In this example the uCDN has requested prepositioning of 1586 "http://newsite.example.com/index.html", but the dCDN was unable to 1587 locate metadata for that site: 1589 REQUEST: 1591 GET /triggers/2 HTTP/1.1 1592 User-Agent: example-user-agent/0.1 1593 Host: dcdn.example.com 1594 Accept: */* 1596 RESPONSE: 1598 HTTP/1.1 200 OK 1599 Content-Length: 484 1600 Expires: Sun, 06 Dec 2015 17:20:08 GMT 1601 Server: example-server/0.1 1602 ETag: "8302815253703938792" 1603 Cache-Control: max-age=60 1604 Date: Sun, 06 Dec 2015 17:19:08 GMT 1605 Content-Type: application/cdni; ptype=ci-trigger-status 1607 { 1608 "ctime": 1449422340, 1609 "errors": [ 1610 { 1611 "content.urls": [ 1612 "http://newsite.example.com/index.html" 1613 ], 1614 "description": "newsite.example.com not in HostIndex", 1615 "error": "emeta" 1616 } 1617 ], 1618 "etime": 1449422348, 1619 "mtime": 1449422344, 1620 "status": "active", 1621 "trigger": { 1622 "content.urls": [ 1623 "http://newsite.example.com/index.html" 1624 ], 1625 "type": "preposition" 1626 } 1627 } 1629 7. IANA Considerations 1631 7.1. CDNI Payload Type Parameter Registrations 1633 The IANA is requested to register the following new Payload Types in 1634 the CDNI Payload Type Parameter registry defined by 1636 [I-D.ietf-cdni-media-type], for use with the 'application/cdni' MIME 1637 media type. 1639 RFC Editor Note: Please replace references to [RFCthis] below with 1640 this document's RFC number before publication. 1642 +-----------------------+---------------+ 1643 | Payload Type | Specification | 1644 +-----------------------+---------------+ 1645 | ci-trigger-command | [RFCthis] | 1646 | ci-trigger-status | [RFCthis] | 1647 | ci-trigger-collection | [RFCthis] | 1648 +-----------------------+---------------+ 1650 8. Security Considerations 1652 The CI/T interface provides a mechanism to allow a uCDN to generate 1653 requests into the dCDN and to inspect its own CI/T requests and their 1654 current state. The CI/T interface does not allow access to or 1655 modification of the uCDN or dCDN metadata relating to content 1656 delivery, or to the content itself. It can only control the presence 1657 of that metadata in the dCDN, and the processing work and network 1658 utilisation involved in ensuring that presence. 1660 By examining pre-positioning requests to a dCDN, and correctly 1661 interpreting content and metadata URLs, an attacker could learn the 1662 uCDN or content owner's predictions for future content popularity. 1663 By examining invalidate or purge requests, an attacker could learn 1664 about changes in the content owner's catalogue. 1666 By injecting CI/T commands an attacker, or a misbehaving uCDN, would 1667 generate work in the dCDN and uCDN as they process those requests. 1668 And so would a man in the middle attacker modifying valid CI/T 1669 commands generated by the uCDN. In both cases, that would decrease 1670 the dCDN caching efficiency by causing it to unnecessarily acquire or 1671 re-acquire content metadata and/or content. 1673 A dCDN implementation of CI/T MUST restrict the actions of a uCDN to 1674 the data corresponding to that uCDN. Failure to do so would allow 1675 uCDNs to detrimentally affect each other's efficiency by generating 1676 unnecessary acquisition or re-acquisition load. 1678 8.1. Authentication, Authorization, Confidentiality, Integrity 1679 Protection 1681 A CI/T implementation MUST support TLS transport for HTTP (https) as 1682 per [RFC2818] and [RFC7230]. 1684 The use of TLS for transport of the CI/T interface allows: 1686 o The dCDN and the uCDN to authenticate each other. 1688 And, once they have mutually authenticated each other, it allows: 1690 o The dCDN and the uCDN to authorize each other (to ensure they are 1691 receiving CI/T Commands from, or reporting status to, an 1692 authorized CDN). 1694 o CDNI commands and responses to be transmitted with 1695 confidentiality. 1697 o Protection of the integrity of CDNI commands and responses. 1699 In an environment where any such protection is required, mutually 1700 authenticated encrypted transport MUST be used to ensure 1701 confidentiality of the CI/T information. To that end, TLS MUST be 1702 used by CI/T, including authentication of the remote end. 1704 When TLS is used, the general TLS usage guidance in [RFC7525] MUST be 1705 followed. 1707 HTTP requests that attempt to access or operate on CI/T data 1708 belonging to another CDN MUST be rejected using, for example, HTTP 1709 "403 Forbidden" or "404 Not Found". This is intended to prevent 1710 unauthorised users from generating unnecessary load in dCDN or uCDN 1711 due to revalidation, reacquisition, or unnecessary acquisition. 1713 Note that in a "diamond" configuration, where one uCDN's content can 1714 be acquired via more than one directly-connected uCDN, it may not be 1715 possible for the dCDN to determine from which uCDN it acquired 1716 content. In this case, the dCDN MUST allow each uCDN from which the 1717 content could have been acquired to act upon that content using CI/T 1718 Commands. 1720 8.2. Denial of Service 1722 This document does not define a specific mechanism to protect against 1723 Denial of Service (DoS) attacks on the CI/T. However, CI/T endpoints 1724 can be protected against DoS attacks through the use of TLS transport 1725 and/or via mechanisms outside the scope of the CI/T interface, such 1726 as firewalling or use of Virtual Private Networks (VPNs). 1728 Depending on the implementation, triggered activity may consume 1729 significant processing and bandwidth in the dCDN. A malicious or 1730 faulty uCDN could use this to generate unnecessary load in the dCDN. 1731 The dCDN should consider mechanisms to avoid overload, for example by 1732 rate-limiting acceptance or processing of CI/T Commands, or batching 1733 up its processing. 1735 8.3. Privacy 1737 The CI/T protocol does not carry any information about individual End 1738 Users of a CDN, there are no privacy concerns for End Users. 1740 The CI/T protocol does carry information which could be considered 1741 commercially sensitive by CDN operators and content owners. The use 1742 of mutually authenticated TLS to establish a secure session for the 1743 transport of CI/T data, as discussed in Section 8.1, provides 1744 confidentiality while the CI/T data is in transit, and prevents 1745 parties other party than the authorised dCDN from gaining access to 1746 that data. The dCDN MUST ensure that it only exposes CI/T data 1747 related to a uCDN to clients it has authenticated as belonging to 1748 that uCDN. 1750 9. Acknowledgements 1752 The authors thank Kevin Ma for his input, and Carsten Bormann for his 1753 review and formalization of the JSON data. 1755 10. References 1757 10.1. Normative References 1759 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1760 Requirement Levels", BCP 14, RFC 2119, March 1997. 1762 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1764 [RFC6707] Niven-Jenkins, B., Le Faucheur, F., and N. Bitar, "Content 1765 Distribution Network Interconnection (CDNI) Problem 1766 Statement", RFC 6707, September 2012. 1768 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1769 Interchange Format", RFC 7159, March 2014. 1771 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1772 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 1773 2014. 1775 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1776 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 1778 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1779 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 1781 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 1782 "Recommendations for Secure Use of Transport Layer 1783 Security (TLS) and Datagram Transport Layer Security 1784 (DTLS)", BCP 195, RFC 7525, May 2015. 1786 10.2. Informative References 1788 [I-D.greevenbosch-appsawg-cbor-cddl] 1789 Vigano, C. and H. Birkholz, "CBOR data definition language 1790 (CDDL): a notational convention to express CBOR data 1791 structures", draft-greevenbosch-appsawg-cbor-cddl-07 (work 1792 in progress), October 2015. 1794 [I-D.ietf-cdni-media-type] 1795 Ma, K., "CDNI Media Type Registration", draft-ietf-cdni- 1796 media-type-06 (work in progress), October 2015. 1798 [I-D.ietf-cdni-metadata] 1799 Niven-Jenkins, B., Murray, R., Caulfield, M., and K. Ma, 1800 "CDN Interconnection Metadata", draft-ietf-cdni- 1801 metadata-12 (work in progress), October 2015. 1803 [I-D.ietf-cdni-redirection] 1804 Niven-Jenkins, B. and R. Brandenburg, "Request Routing 1805 Redirection Interface for CDN Interconnection", draft- 1806 ietf-cdni-redirection-13 (work in progress), October 2015. 1808 [RFC7336] Peterson, L., Davie, B., and R. van Brandenburg, 1809 "Framework for Content Distribution Network 1810 Interconnection (CDNI)", RFC 7336, August 2014. 1812 [RFC7337] Leung, K. and Y. Lee, "Content Distribution Network 1813 Interconnection (CDNI) Requirements", RFC 7337, August 1814 2014. 1816 Appendix A. Formalization of the JSON Data 1818 This appendix is non-normative. 1820 The JSON data described in this document has been formalised using 1821 CDDL [I-D.greevenbosch-appsawg-cbor-cddl] as follows: 1823 CIT-object = CIT-command / Trigger-Status-Resource / Trigger-Collection 1825 CIT-command ; use media type application/cdni; ptype=ci-trigger-command 1826 = { 1827 ? trigger: Triggerspec 1828 ? cancel: [* URI] 1829 cdn-path: [* Cdn-PID] 1830 } 1832 Trigger-Status-Resource ; application/cdni; ptype=ci-trigger-status 1833 = { 1834 trigger: Triggerspec 1835 ctime: Absolute-Time 1836 mtime: Absolute-Time 1837 ? etime: Absolute-Time 1838 status: Trigger-Status 1839 ? errors: [* Error-Description] 1840 } 1842 Trigger-Collection ; application/cdni; ptype=ci-trigger-collection 1843 = { 1844 triggers: [* URI] 1845 ? staleresourcetime: int ; time in seconds 1846 ? coll-all: URI 1847 ? coll-pending: URI 1848 ? coll-active: URI 1849 ? coll-complete: URI 1850 ? coll-failed: URI 1851 ? cdn-id: Cdn-PID 1852 } 1854 Triggerspec = { ; 5.2.1 1855 type: Trigger-Type 1856 ? metadata.urls: [* URI] 1857 ? content.urls: [* URI] 1858 ? content.ccid: [* Ccid] 1859 ? metadata.patterns: [* Pattern-Match] 1860 ? content.patterns: [* Pattern-Match] 1861 } 1863 Trigger-Type = "preposition" / "invalidate" / "purge" ; 5.2.2 1865 Trigger-Status = "pending" / "active" / "complete" / "processed" 1866 / "failed" / "cancelling" / "cancelled" ; 5.2.3 1868 Pattern-Match = { ; 5.2.4 1869 pattern: tstr 1870 ? case-sensitive: bool 1871 ? match-query-string: bool 1872 } 1874 Absolute-Time = number ; seconds since UNIX epoch, 5.2.5 1876 Error-Description = { ; 5.2.6 1877 error: Error-Code 1878 ? metadata.urls: [* URI] 1879 ? content.urls: [* URI] 1880 ? metadata.patterns: [* Pattern-Match] 1881 ? content.patterns: [* Pattern-Match] 1882 ? description: tstr 1883 } 1885 Error-Code = "emeta" / "econtent" / "eperm" / "ereject" 1886 / "ecdn" / "ecancelled" ; 5.2.7 1888 Ccid = tstr ; see I-D.ietf-cdni-metadata 1890 Cdn-PID = tstr .regexp "AS[0-9]+:[0-9]+" 1892 URI = tstr 1894 Authors' Addresses 1896 Rob Murray 1897 Velocix (Alcatel-Lucent) 1898 3 Ely Road 1899 Milton, Cambridge CB24 6DD 1900 UK 1902 Email: rob.murray@alcatel-lucent.com 1904 Ben Niven-Jenkins 1905 Velocix (Alcatel-Lucent) 1906 3 Ely Road 1907 Milton, Cambridge CB24 6DD 1908 UK 1910 Email: ben.niven-jenkins@alcatel-lucent.com