idnits 2.17.1 draft-ietf-cdni-control-triggers-05.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 29, 2014) is 3406 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 1727, but not defined == Unused Reference: 'RFC3986' is defined on line 1818, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) == Outdated reference: A later version (-21) exists of draft-ietf-cdni-metadata-08 == Outdated reference: A later version (-20) exists of draft-ietf-cdni-redirection-06 -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 3 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: July 2, 2015 December 29, 2014 7 CDNI Control Interface / Triggers 8 draft-ietf-cdni-control-triggers-05 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 July 2, 2015. 43 Copyright Notice 45 Copyright (c) 2014 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 . . . . . . . . . . . . . 15 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 . . . . . . . . . . . . . . . . 18 85 5.2.2. Trigger Type . . . . . . . . . . . . . . . . . . . . 20 86 5.2.3. Trigger Status . . . . . . . . . . . . . . . . . . . 20 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 23 92 6.1. Creating Triggers . . . . . . . . . . . . . . . . . . . . 24 93 6.1.1. Preposition . . . . . . . . . . . . . . . . . . . . . 24 94 6.1.2. Invalidate . . . . . . . . . . . . . . . . . . . . . 25 95 6.2. Examining Trigger Status . . . . . . . . . . . . . . . . 26 96 6.2.1. Collection of All Triggers . . . . . . . . . . . . . 26 97 6.2.2. Filtered Collections of Trigger Status Resources . . 27 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. Media type registrations . . . . . . . . . . . . . . . . 37 104 7.1.1. CI/T Commands . . . . . . . . . . . . . . . . . . . . 37 105 7.1.2. CI/T Trigger Status Resource . . . . . . . . . . . . 38 106 7.1.3. CI/T Trigger Collection . . . . . . . . . . . . . . . 39 107 8. Security Considerations . . . . . . . . . . . . . . . . . . . 40 108 8.1. Authentication, Confidentiality, Integrity Protection . . 40 109 8.2. Denial of Service . . . . . . . . . . . . . . . . . . . . 40 110 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 41 111 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 41 112 10.1. Normative References . . . . . . . . . . . . . . . . . . 41 113 10.2. Informative References . . . . . . . . . . . . . . . . . 41 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]. 149 2. Model for CDNI Triggers 151 A CI/T Command, sent from the uCDN to the dCDN, is a request for the 152 dCDN to do some work relating to data associated with content 153 requests originating from the uCDN. 155 There are two types of CI/T Command, CI/T Trigger Commands and CI/T 156 Cancel Commands. The CI/T Cancel Command can be used to request 157 cancellation of an earlier CI/T Trigger Command. A CI/T Trigger 158 Command is of one of the following types: 160 o preposition - used to instruct the dCDN to fetch metadata from the 161 uCDN, or content from any origin including the uCDN. 163 o invalidate - used to instruct the dCDN to revalidate specific 164 metadata or content before re-using it. 166 o purge - used to instruct the dCDN to delete specific metadata or 167 content. 169 The CI/T interface is a web service offered by the dCDN. It allows 170 CI/T commands to be issued, and triggered activity to be tracked. 171 When the dCDN accepts a CI/T Command it creates a resource describing 172 status of the triggered activity, a Trigger Status Resource. The 173 uCDN can poll Trigger Status Resources to monitor progress. 175 The dCDN maintains at least one collection of Trigger Status 176 Resources for each uCDN. Each uCDN only has access to its own 177 collections, the locations of which are shared when CDN 178 interconnection is established. 180 To trigger activity in the dCDN, the uCDN POSTs a CI/T Command to the 181 collection of Trigger Status Resources. If the dCDN accepts the CI/T 182 Command, it creates a new Trigger Status Resource and returns its 183 location to the uCDN. To monitor progress, the uCDN can GET the 184 Trigger Status Resource. To request cancellation of a CI/T Trigger 185 Command the uCDN can POST to the collection of Trigger Status 186 Resources, or simply DELETE the Trigger Status Resource. 188 In addition to the collection of all Trigger Status Resources for the 189 uCDN, the dCDN can maintain filtered views of that collection. These 190 filtered views are defined in Section 3 and include collections of 191 Trigger Status Resources corresponding to active and completed CI/T 192 Trigger Commands. These collections provide a mechanism for polling 193 the status of multiple jobs. 195 Figure 1 is an example showing the basic message flow used by the 196 uCDN to trigger activity in the dCDN, and for the uCDN to discover 197 the status of that activity. Only successful triggering is shown. 198 Examples of the messages are given in Section 6. 200 uCDN dCDN 201 | (1) POST http://dcdn.example.com/triggers/uCDN | 202 [ ] --------------------------------------------------> [ ]--+ 203 | [ ] | (2) 204 | (3) HTTP 201 Response [ ]<-+ 205 [ ] <-------------------------------------------------- [ ] 206 | Loc: http://dcdn.example.com/triggers/uCDN/123 | 207 | | 208 . . . 209 . . . 210 . . . 211 | | 212 | (4) GET http://dcdn.example.com/triggers/uCDN/123 | 213 [ ] --------------------------------------------------> [ ] 214 | [ ] 215 | (5) HTTP 200 Trigger Status Resource [ ] 216 [ ] <-------------------------------------------------- [ ] 217 | | 218 | | 220 Figure 1: Basic CDNI Message Flow for Triggers 222 The steps in Figure 1 are: 224 1. The uCDN triggers action in the dCDN by posting a CI/T Command to 225 a collection of Trigger Status Resources, 226 "http://dcdn.example.com/triggers/uCDN". The URL of this was 227 given to the uCDN when the CI/T interface was established. 229 2. The dCDN authenticates the request, validates the CI/T Command 230 and, if it accepts the request, creates a new Trigger Status 231 Resource. 233 3. The dCDN responds to the uCDN with an HTTP 201 response status, 234 and the location of the Trigger Status Resource. 236 4. The uCDN can poll, possibly repeatedly, the Trigger Status 237 Resource in the dCDN. 239 5. The dCDN responds with the Trigger Status Resource, describing 240 progress or results of the CI/T Trigger Command. 242 The remainder of this document describes the messages, Trigger Status 243 Resources, and collections of Trigger Status Resources in more 244 detail. 246 2.1. Timing of Triggered Activity 248 Timing of the execution of CI/T Commands is under the dCDN's control, 249 including its start-time and pacing of the activity in the network. 251 CI/T invalidate and purge commands MUST be applied to all data 252 acquired before the command was accepted by the dCDN. The dCDN 253 SHOULD NOT apply CI/T invalidate and purge commands to data acquired 254 after the CI/T Command was accepted, but this may not always be 255 achievable so the uCDN cannot count on that. 257 If the uCDN wishes to invalidate or purge content then immediately 258 pre-position replacement content at the same URLs, it SHOULD ensure 259 the dCDN has completed the invalidate/purge before initiating the 260 prepositioning. Otherwise, there is a risk that the dCDN pre- 261 positions the new content, then immediately invalidates or purges it 262 (as a result of the two uCDN requests running in parallel). 264 Because the CI/T Command timing is under the dCDN's control, the dCDN 265 implementation can choose whether to apply CI/T invalidate and purge 266 commands to content acquisition that has already started when the 267 command is received. 269 2.2. Scope of Triggered Activity 271 Each CI/T Command can operate on multiple metadata and content URLs. 273 Multiple representations of an HTTP resource may share the same URL. 274 CI/T Trigger Commands that invalidate or purge metadata or content 275 apply to all resource representations with matching URLs. 277 The dCDN MUST reject CI/T Commands from a uCDN that act on another 278 uCDN's data. Security considerations are discussed further in 279 section Section 8. 281 2.3. Trigger Results 283 Possible states for a Trigger Status Resource are defined in section 284 Section 5.2.3. 286 The CI/T Trigger Command MUST NOT be reported as 'complete' until all 287 actions have been completed successfully. The reasons for failure, 288 and URLs or Patterns affected, SHOULD be enumerated in the Trigger 289 Status Resource. For more detail, see section Section 4.7. 291 If a dCDN is also acting as a uCDN in a cascade, it MUST forward CI/T 292 Commands to any downstream CDNs that may be affected. The CI/T 293 Trigger Command MUST NOT be reported as 'complete' in a CDN until it 294 is 'complete' in all of its downstream CDNs. If a CI/T Trigger 295 Command is reported as 'processed' in any dCDN, intermediate CDNs 296 MUST NOT report 'complete', instead they must also report 297 'processed'. A CI/T Command MAY be reported as 'failed' as soon as 298 it fails in a CDN or in any of its downstream CDNs. A cancelled CI/T 299 Trigger Command MUST be reported as 'cancelling' until it has been 300 reported as 'cancelled', 'complete', or 'failed' by all dCDNs in a 301 cascade. 303 3. Collections of Trigger Status Resources 305 As described in Section 2, Trigger Status Resources exist in the dCDN 306 to report the status of activity triggered by each uCDN. 308 A collection of Trigger Status Resources is a resource that contains 309 a reference to each Trigger Status Resource in that collection. 311 The dCDN MUST make a collection of a uCDN's Trigger Status Resources 312 available to that uCDN. This collection includes all of the Trigger 313 Status Resources created for CI/T Commands from the uCDN that have 314 been accepted by the dCDN, and have not yet been deleted by the uCDN, 315 or expired and removed by the dCDN (as described in section 316 Section 4.4). Trigger Status Resources belonging to a uCDN MUST NOT 317 be visible to any other CDN. The dCDN could, for example, achieve 318 this by offering different collection URLs to each uCDN, and/or by 319 filtering the response based on the uCDN with which the HTTP client 320 is associated. 322 To trigger activity in a dCDN, or to cancel triggered activity, the 323 uCDN POSTs a CI/T Command to the dCDN's collection of the uCDN's 324 Trigger Status Resources. 326 In order to allow the uCDN to check the status of multiple jobs in a 327 single request, the dCDN SHOULD also maintain collections 328 representing filtered views of the collection of all Trigger Status 329 Resources. These filtered collections are optional-to-implement but, 330 if implemented, the dCDN MUST include links to them in the collection 331 of all Trigger Status Resources. The filtered collections are: 333 o Pending - Trigger Status Resources for CI/T Trigger Commands that 334 have been accepted, but not yet acted upon. 336 o Active - Trigger Status Resources for CI/T Trigger Commands that 337 are currently being processed in the dCDN. 339 o Complete - Trigger Status Resources representing activity that 340 completed successfully, and 'processed' CI/T Trigger Commands for 341 which no further status updates will be made by the dCDN. 343 o Failed - Trigger Status Resources representing CI/T Commands that 344 failes or were cancelled by the uCDN. 346 4. CDNI Trigger Interface 348 This section describes an interface to enable an upstream CDN to 349 trigger activity in a downstream CDN. 351 The CI/T interface builds on top of HTTP, so dCDNs may make use of 352 any HTTP feature when implementing the CI/T interface. For example, 353 a dCDN SHOULD make use of HTTP's caching mechanisms to indicate that 354 a requested response/representation has not been modified, reducing 355 the uCDN's processing needed to determine whether the status of 356 triggered activity has changed. 358 All dCDNs implementing CI/T MUST support the HTTP GET, HEAD, POST and 359 DELETE methods as defined in [RFC7231]. 361 The only representation specified in this document is JSON, 362 [RFC7159]. It MUST be supported by the uCDN and by the dCDN. 364 The URL of the dCDN's collection of all Trigger Status Resources 365 needs to be either discovered by, or configured in, the uCDN. The 366 mechanism for discovery of that URL is outside the scope of this 367 document. 369 CI/T Commands are POSTed to the dCDN's collection of all Trigger 370 Status Resources. If a CI/T Trigger Command is accepted by the dCDN, 371 the dCDN creates a new Trigger Status Resource and returns its URI to 372 the uCDN in an HTTP 201 response. The triggered activity can then be 373 monitored by the uCDN using that resource and the collections 374 described in Section 3. 376 The URI of each Trigger Status Resource is returned to the uCDN when 377 it is created, and URIs of all Trigger Status Resources are listed in 378 the dCDN's collection of all Trigger Status Resources. This means 379 all Trigger Status Resources can be discovered by the uCDN, so dCDNs 380 are free to assign whatever structure they desire to the URIs for CI/ 381 T resources. Therefore uCDNs MUST NOT make any assumptions regarding 382 the structure of CI/T URIs or the mapping between CI/T objects and 383 their associated URIs. URIs present in the examples in this document 384 are purely illustrative and are not intended to impose a definitive 385 structure on CI/T interface implementations. 387 4.1. Creating Triggers 389 To issue a CI/T Command, the uCDN makes an HTTP POST to the dCDN's 390 collection of all of the uCDN's Trigger Status Resources. The 391 request body of that POST is a CI/T Command, as described in 392 Section 5.1.1. 394 The dCDN validates and authenticates that CI/T Command, if it is 395 malformed or the uCDN does not have sufficient access rights it MUST 396 either respond with an appropriate 4xx HTTP error code and a Trigger 397 Status Resource MUST NOT be created on the dCDN, or create a 'failed' 398 Trigger Status Resource containing an appropriate error description. 400 When a CI/T Trigger Command is accepted, the uCDN MUST create a new 401 Trigger Status Resource which will convey a specification of the CI/T 402 Command and its current status. The HTTP response to the dCDN MUST 403 have status code 201 and MUST convey the URI of the Trigger Status 404 Resource in the Location header field. The HTTP response SHOULD 405 include the content of the newly created Trigger Status Resource, 406 this is recommended particularly in cases where the CI/T Trigger 407 Command has completed immediately. 409 Once a Trigger Status Resource has been created the dCDN MUST NOT re- 410 use its URI, even after that Trigger Status Resource has been 411 removed. 413 The dCDN SHOULD track and report on progress of CI/T Trigger 414 Commands. If the dCDN is not able to do that, it MUST indicate that 415 it has accepted the request but will not be providing further status 416 updates. To do this, it sets the "status" of the Trigger Status 417 Resource to "processed". In this case, CI/T processing should 418 continue as for a "complete" request, so the Trigger Status Resource 419 MUST be added to the dCDN's collection of Complete Trigger Status 420 Resources. The dCDN SHOULD also provide an estimated completion time 421 for the request, by using the "etime" property of the Trigger Status 422 Resource. This will allow the uCDN to schedule prepositioning after 423 an earlier delete of the same URLs is expected to have finished. 425 If the dCDN is able to track the execution of CI/T Commands and a CI/ 426 T Command is queued by the dCDN for later action, the "status" 427 property of the Trigger Status Resource MUST be "pending". Once 428 processing has started the "status" MUST be "active". Finally, once 429 the CI/T Command is complete, the status MUST be set to "complete" or 430 "failed". 432 A CI/T Trigger Command may result in no activity in the dCDN if, for 433 example, it is an invalidate or purge request for data the dCDN has 434 not yet acquired, or a prepopulate request for data it has already 435 acquired and which is still valid. In this case, the "status" of the 436 Trigger Status Resource MUST be "processed" or "complete", and the 437 Trigger Status Resource MUST be added to the dCDN's collection of 438 Complete Trigger Status Resources. 440 Once created, Trigger Status Resources can be cancelled or deleted by 441 the uCDN, but not modified. The dCDN MUST reject PUT and POST 442 requests from the uCDN to Trigger Status Resources by responding with 443 an appropriate HTTP status code. 445 4.2. Checking Status 447 The uCDN has two ways to check progress of CI/T Commands it has 448 issued to the dCDN, described in sections Section 4.2.1 and 449 Section 4.2.2. 451 To check for change in status of a Trigger Status Resource or 452 collection of Trigger Status Resources without re-fetching the whole 453 Resource or Collection, Entity Tags SHOULD be included by the dCDN 454 for the uCDN to use as cache validators, as defined in [RFC7232]. 456 The dCDN SHOULD use the cache control headers for responses to GETs 457 for Trigger Status Resources and Collections to indicate the 458 frequency at which it recommends the uCDN should poll for change. 460 4.2.1. Polling Trigger Status Resource collections 462 The uCDN can fetch the collection of its Trigger Status Resources, or 463 filtered views of that collection. 465 This makes it possible to poll status of all CI/T Trigger Commands in 466 a single request. If the dCDN moves a Trigger Status Resource from 467 the Active to the Completed collection, the uCDN can fetch the result 468 of that activity. 470 When polling in this way, the uCDN SHOULD use HTTP Entity Tags to 471 monitor for change, rather than repeatedly fetching the whole 472 collection. 474 4.2.2. Polling Trigger Status Resources 476 The uCDN has a URI provided by the dCDN for each Trigger Status 477 Resource it has created, it may fetch that Trigger Status Resource at 478 any time. 480 This can be used to retrieve progress information, and to fetch the 481 result of the CI/T Command. 483 When polling in this way, the uCDN SHOULD use HTTP Entity Tags to 484 monitor for change, rather than repeatedly fetching the Trigger 485 Status Resource. 487 4.3. Cancelling Triggers 489 The uCDN can request cancellation of a CI/T Trigger Command by 490 POSTing a CI/T Cancel Command to the collection of all Trigger Status 491 Resources. 493 Cancellation of a CI/T Trigger Command is optional-to-implement in 494 the dCDN. 496 The dCDN MUST respond to the CI/T Cancel Command appropriately, for 497 example with HTTP status code 200 "OK" if the cancellation has been 498 processed and the CI/T Command is inactive, 202 "Accepted" if the 499 command has been accepted but the CI/T Command remains active, or 403 500 "Forbidden" if cancellation is not supported by the dCDN. 502 If cancellation of a "pending" Trigger Status Resource is accepted by 503 the dCDN, the dCDN SHOULD NOT start processing of that activity. 504 Issuing a CT/T cancel command for a "pending" Trigger Status Resource 505 does not however guarantee that the corresponding activity will not 506 be started, because the uCDN cannot control the timing of that 507 activity. Processing could, for example, start after the POST is 508 sent by the uCDN but before that request is processed by the dCDN. 510 If cancellation of an "active" or "processed" Trigger Status Resource 511 is accepted by the dCDN, the dCDN SHOULD stop processing the CI/T 512 Command. However, as with cancellation of a "pending" CI/T Command, 513 the dCDN does not guarantee this. 515 If the CI/T Command cannot be stopped immediately, the status in the 516 corresponding Trigger Status Resource MUST be set to "cancelling", 517 and the Trigger Status Resource MUST remain in the collection of 518 Trigger Status Resources for active CI/T Commands. If processing is 519 stopped before normal completion, the status value in the Trigger 520 Status Resource MUST be set to "cancelled", and the Trigger Status 521 Resource MUST be included in the collection of failed CT/T Trigger 522 Commands. 524 Cancellation of a "complete" or "failed" Trigger Status Resource 525 requires no processing in the dCDN, its status MUST NOT be changed to 526 "cancelled". 528 4.4. Deleting Triggers 530 The uCDN can delete Trigger Status Resources at any time, using the 531 HTTP DELETE method. The effect is similar to cancellation, but no 532 Trigger Status Resource remains afterwards. 534 Once deleted, the references to a Trigger Status Resource MUST be 535 removed from all Trigger Status Resource collections. Subsequent 536 requests to GET the deleted Trigger Status Resource SHOULD be 537 rejected by the dCDN with an HTTP error. 539 If a "pending" Trigger Status Resource is deleted, the dCDN SHOULD 540 NOT start processing of that activity. Deleting a "pending" Trigger 541 Status Resource does not however guarantee that it has not started 542 because the uCDN cannot control the timing of that activity. 543 Processing may, for example, start after the DELETE is sent by the 544 uCDN but before that request is processed by the dCDN. 546 If an "active" or "processed" Trigger Status Resource is deleted, the 547 dCDN SHOULD stop processing the CI/T Command. However, as with 548 deletion of a "pending" Trigger Status Resource, the dCDN does not 549 guarantee this. 551 Deletion of a "complete" or "failed" Trigger Status Resource requires 552 no processing in the dCDN other than deletion of the Trigger Status 553 Resource. 555 4.5. Expiry of Trigger Status Resources 557 The dCDN can choose to automatically delete Trigger Status Resources 558 some time after they become "complete", "processed", "failed" or 559 "cancelled". In this case, the dCDN will remove the Trigger Status 560 Resource and respond to subsequent requests for it with an HTTP 561 error. 563 If the dCDN performs this housekeeping, it MUST have reported the 564 length of time after which completed Trigger Status Resources will be 565 deleted via a property of the collection of all Trigger Status 566 Resources. It is RECOMMENDED that Trigger Status Resources are not 567 automatically deleted by the dCDN for at least 24 hours after they 568 become "complete", "processed", "failed" or "cancelled". 570 To ensure it is able to get the status of its Trigger Status 571 Resources for completed and failed CI/T Commands, it is RECOMMENDED 572 that the uCDN polling interval is less than the time after which 573 records for completed activity will be deleted. 575 4.6. Loop Detection and Prevention 577 Given three CDNs, A, B and C. If CDNs B and C delegate delivery of 578 CDN A's content to each other, CDN A's CI/T Commands could be passed 579 between CDNs B and C in a loop. More complex networks of CDNs could 580 contain similar loops involving more hops. 582 In order to prevent and detect such CI/T loops, each CDN uses a CDN 583 Provider ID to uniquely identify itself. Each CDN MUST insert its 584 CDN Provider ID into the cdn-path key of every CI/T Command it 585 originates or cascades. When receiving CI/T Commands a dCDN MUST 586 check the cdn-path and reject any CI/T Command which already contains 587 its own CDN Provider ID in the cdn-path. Transit CDNs MUST check the 588 cdn-path and not cascade the CI/T Command to dCDNs that are already 589 listed in cdn-path. 591 The CDN Provider Id consists of the two characters "AS" followed by 592 the CDN Provider's Autonomous System number, then a colon (':') and 593 an additional qualifier that is used to guarantee uniqueness in case 594 a particular AS has multiple independent CDNs deployed. For example 595 "AS64496:0". 597 If the CDN provider has multiple Autonomous Systems, the same AS 598 number SHOULD be used in all messages from that CDN provider, unless 599 there are multiple distinct CDNs. 601 If the RI interface described in [I-D.ietf-cdni-redirection] is 602 implemented by the dCDN, the CI/T and RI interfaces SHOULD use the 603 same CDN Provider Id. 605 4.7. Error Handling 607 A dCDN can signal rejection of a CI/T Command using HTTP status 608 codes. For example, 400 if the request is malformed, or 401 if the 609 uCDN does not have permission to issue CI/T Commands or it is trying 610 to act on another CDN's data. 612 If any part of the CI/T Trigger Command fails, the trigger SHOULD be 613 reported as "failed" once its activity is complete or if no further 614 errors will be reported. The "errors" property in the Trigger Status 615 Resource will be used to enumerate which actions failed and the 616 reasons for failure, and can be present while the Trigger Status 617 Resource is still "pending" or "active", if the CI/T Trigger Command 618 is still running for some URLs or Patterns in the Trigger 619 Specification. 621 Once a request has been accepted, processing errors are reported in 622 the Trigger Status Resource using a list of Error Descriptions. Each 623 Error Description is used to report errors against one or more of the 624 URLs or Patterns in the Trigger Specification. 626 If a surrogate affected by a CI/T Trigger Command is offline in the 627 dCDN, or the dCDN is unable to pass a CI/T Command on to any of its 628 cascaded dCDNs: 630 o If the CI/T Command is abandoned by the dCDN, the dCDN SHOULD 631 report an error. 633 o A CI/T "invalidate" command may be reported as "complete" when 634 surrogates that may have the data are offline. In this case, 635 surrogates MUST NOT use the affected data without first 636 revalidating it when they are back online. 638 o CI/T "preposition" and "purge" commands can be reported as 639 "processed" if affected caches are offline and the activity will 640 complete when they return to service. 642 o Otherwise, the dCDN SHOULD keep the Trigger Status Resource in 643 state "pending" or "active" until the CI/T Command is acted upon, 644 or the uCDN chooses to cancel it. 646 4.8. Content URLs 648 To refer to content in the dCDN, the uCDN MUST present URLs in the 649 same form as in the metadata it supplied to the dCDN. By definition, 650 it is always possible for the dCDN to locate content based on URLs in 651 this form. 653 Therefore, if content URLs are transformed by an intermediate CDN in 654 a cascade, that intermediate CDN MUST transform URLs in CI/T Commands 655 it passes to its dCDN. 657 When processing Trigger Specifications, CDNs MUST ignore the URL 658 scheme (http or https) in comparing URLs. For example, for a CI/T 659 invalidate or purge command, content MUST be invalidated or purged 660 regardless of the protocol clients use to request it. 662 5. CI/T Object Properties and Encoding 664 CI/T Commands, Trigger Status Resources and Trigger Collections and 665 their properties are encoded using JSON, as defined in sections 666 Section 5.1.1, Section 5.2.1, and Section 5.1.2. 668 Names in JSON are case sensitive. The names and literal values 669 specified in the present document MUST always use lower-case. 671 Unrecognised name/value pairs in JSON objects SHOULD NOT be treated 672 as an error by either the uCDN or dCDN. They SHOULD be ignored in 673 the processing, and passed on by dCDN to any further dCDNs in a 674 cascade. 676 5.1. CI/T Objects 678 The top-level objects defined by the CI/T interface are described in 679 this section. Each has an associated MIME Media Type. The encoding 680 of values used by these objects is described in Section 5.2. 682 5.1.1. CI/T Commands 684 CI/T Commands SHOULD use a MIME Media Type of application/ 685 cdni.ci.TriggerCommand+json. 687 A CI/T Command is encoded as a JSON object containing the following 688 name/value pairs. 690 Name: trigger 692 Description: A specification of the trigger type, and a set of 693 data to act upon. 695 Value: A Trigger Specification, as defined in Section 5.2.1. 697 Mandatory: No, but exactly one of "trigger" or "cancel" MUST be 698 present in a CI/T Command. 700 Name: cancel 702 Description: The URLs of Trigger Status Resources for CI/T 703 Trigger Commands that the uCDN wants to cancel. 705 Value: A JSON array of URLs represented as JSON strings. 707 Mandatory: No, but exactly one of "trigger" or "cancel" MUST be 708 present in a CI/T Command. 710 Name: cdn-path 712 Description: The CDN Provider Identifiers of CDNs that have 713 already accepted the CI/T Command. 715 Value: A JSON array of JSON strings, where each string is a CDN 716 Provider Identifier as defined in Section 4.6. 718 Mandatory: Yes. 720 5.1.2. Trigger Status Resource 722 Trigger Status Resources SHOULD use a MIME Media Type of application/ 723 cdni.ci.TriggerStatus+json. 725 A Trigger Status Resource is encoded as a JSON object containing the 726 following name/value pairs. 728 Name: trigger 730 Description: The Trigger Specification posted in the body of 731 the CI/T Command. Note that this need not be a byte-for-byte 732 copy. For example, in the JSON representation the dCDN may re- 733 serialise the information differently. 735 Value: A Trigger Specification, as defined in Section 5.2.1. 737 Mandatory: Yes 739 Name: ctime 741 Description: Time at which the CI/T Command was received by the 742 dCDN. Time is determined by the dCDN, there is no requirement 743 to synchronise clocks between interconnected CDNs. 745 Value: Absolute Time, as defined in Section 5.2.5. 747 Mandatory: Yes 749 Name: mtime 751 Description: Time at which the Trigger Status Resource was last 752 modified. Time is determined by the dCDN, there is no 753 requirement to synchronise clocks between interconnected CDNs. 755 Value: Absolute Time, as defined in Section 5.2.5. 757 Mandatory: Yes 759 Name: etime 761 Description: Estimate of the time at which the dCDN expects to 762 complete the activity. Time is determined by the dCDN, there 763 is no requirement to synchronise clocks between interconnected 764 CDNs. 766 Value: Absolute Time, as defined in Section 5.2.5. 768 Mandatory: No 770 Name: status 772 Description: Current status of the triggered activity. 774 Value: Trigger Status, as defined in Section 5.2.3. 776 Mandatory: Yes 778 Name: errors 780 Description: Descriptions of errors that have occurred while 781 processing a Trigger Command. 783 Value: A list of Error Descriptions, as defined in 784 Section 5.2.6. 786 Mandatory: No. 788 5.1.3. Trigger Collection 790 Trigger Collections SHOULD use a MIME Media Type of application/ 791 cdni.ci.TriggerCollection+json. 793 A Trigger Collection is encoded as a JSON object containing the 794 following name/value pairs. 796 Name: triggers 798 Description: Links to Trigger Status Resources in the 799 collection. 801 Value: A JSON array of URLs represented as JSON strings. 803 Mandatory: Yes 805 Name: staleresourcetime 806 Description: The length of time for which the dCDN guarantees 807 to keep a completed Trigger Status Resource. After this time, 808 the dCDN SHOULD delete the Trigger Status Resource and all 809 references to it from collections. 811 Value: A JSON number, integer time in seconds. 813 Mandatory: Yes, in the collection of all Trigger Status 814 Resources if the dCDN deletes stale entries. If the property 815 is present in the filtered collections, it MUST have the same 816 value as in the collection of all Trigger Status Resources. 818 Names: coll-all, coll-pending, coll-active, coll-complete, coll- 819 failed 821 Description: Link to a Trigger Collection. 823 Value: A URL represented as a JSON string. 825 Mandatory: Links to all of the filtered collections are 826 mandatory in the collection of all Trigger Status Resources, if 827 the dCDN implements the filtered collections. Otherwise, 828 optional. 830 Name: cdn-id 832 Description: The CDN Provider Identifier of the dCDN. 834 Value: A JSON string, the dCDN's CDN Provider Identifier, as 835 defined in Section 4.6. 837 Mandatory: Only in the collection of all Trigger Status 838 Resources, if the dCDN implements the filtered collections. 839 Optional in the filtered collections (the uCDN can always find 840 the dCDN's cdn-id in the collection of all Trigger Status 841 Resources, but the dCDN can choose to repeat that information 842 in its implementation of filtered collections). 844 5.2. Properties of CI/T Objects 846 This section defines the values that can appear in the top level 847 objects described in Section 5.1, and their encodings. 849 5.2.1. Trigger Specification 851 A Trigger Collection is encoded as a JSON object containing the 852 following name/value pairs. 854 An unrecognised name/value pair in the Trigger Specification object 855 contained in a CI/T Command SHOULD be preserved in the Trigger 856 Specification of any Trigger Status Resource it creates. 858 Name: type 860 Description: This property defines the type of the CI/T Trigger 861 Command. 863 Value: Trigger Type, as defined in Section 5.2.2. 865 Mandatory: Yes 867 Name: metadata.urls 869 Description: The uCDN URLs of the metadata the CI/T Trigger 870 Command applies to. 872 Value: A JSON array of URLs represented as JSON strings. 874 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 875 MUST be present and non-empty. 877 Name: content.urls 879 Description: URLs of content the CI/T Trigger Command applies 880 to, see Section 4.8. 882 Value: A JSON array of URLs represented as JSON strings. 884 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 885 MUST be present and non-empty. 887 Name: content.ccid 889 Description: The Content Collection Identifier of content the 890 trigger applies to. The 'ccid' is a grouping of content, as 891 defined by [I-D.ietf-cdni-metadata]. 893 Value: A JSON array of strings, where each string is a Content 894 Collection Identifier. 896 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 897 MUST be present and non-empty. 899 Name: metadata.patterns 901 Description: The metadata the trigger applies to. 903 Value: A JSON array of Pattern Match, as defined in 904 Section 5.2.4. 906 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 907 MUST be present and non-empty, and metadata.patterns MUST NOT 908 be present if the TriggerType is Preposition. 910 Name: content.patterns 912 Description: The content data the trigger applies to. 914 Value: A JSON array of Pattern Match, as defined in 915 Section 5.2.4. 917 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 918 MUST be present and non-empty, and content.patterns MUST NOT be 919 present if the TriggerType is Preposition. 921 5.2.2. Trigger Type 923 Trigger Type is used in a Trigger Specification to describe trigger 924 action. It MUST be one of the JSON strings in the following table: 926 +-------------+-----------------------------------------------------+ 927 | JSON String | Description | 928 +-------------+-----------------------------------------------------+ 929 | preposition | A request for the dCDN to acquire metadata or | 930 | | content. | 931 | invalidate | A request for the dCDN to invalidate metadata or | 932 | | content. After servicing this request the dCDN will | 933 | | not use the specified data without first re- | 934 | | validating it using, for example, an "If-None- | 935 | | Match" HTTP request. The dCDN need not erase the | 936 | | associated data. | 937 | purge | A request for the dCDN to erase metadata or | 938 | | content. After servicing the request, the specified | 939 | | data MUST NOT be held on the dCDN (the dCDN should | 940 | | re-acquire the metadata or content from uCDN if it | 941 | | needs it). | 942 +-------------+-----------------------------------------------------+ 944 5.2.3. Trigger Status 946 This describes the current status of a Trigger. It MUST be one of 947 the JSON strings in the following table: 949 +------------+------------------------------------------------------+ 950 | JSON | Description | 951 | String | | 952 +------------+------------------------------------------------------+ 953 | pending | The CI/T Trigger Command has not yet been acted | 954 | | upon. | 955 | active | The CI/T Trigger Command is currently being acted | 956 | | upon. | 957 | complete | The CI/T Trigger Command completed successfully. | 958 | processed | The CI/T Trigger Command has been accepted and no | 959 | | further status update will be made (can be used in | 960 | | cases where completion cannot be confirmed). | 961 | failed | The CI/T Trigger Command could not be completed. | 962 | cancelling | Processing of the CI/T Trigger Command is still in | 963 | | progress, but the CI/T Trigger Command has been | 964 | | cancelled by the uCDN. | 965 | cancelled | The CI/T Trigger Command was cancelled by the uCDN. | 966 +------------+------------------------------------------------------+ 968 5.2.4. PatternMatch 970 A Pattern Match consists of a string pattern to match, and flags 971 describing the type of match. 973 It is encoded as a JSON object with the following name/value pairs: 975 Name: pattern 977 Description: A pattern for string matching. 979 Value: A JSON string representing the pattern. The pattern may 980 contain the wildcards * and ?, where * matches any sequence of 981 characters (including the empty string) and ? matches exactly 982 one character. The three literals "\" , "*" and "?" MUST be 983 escaped as "\\", "\*" and "\?". 985 Mandatory: Yes. 987 Name: case-sensitive 989 Description: Flag indicating whether or not case-sensitive 990 matching should be used. 992 Value: One of the JSON values 'true' or 'false'. 994 Mandatory: No, default is case-insensitive match. 996 Name: match-query-string 997 Description: Flag indicating whether or not the query string 998 should be included in the pattern match. 1000 Value: One of the JSON values 'true' or 'false'. 1002 Mandatory: No, default is not to include the query string in 1003 the pattern match. 1005 Example of case-sensitive prefix match against 1006 "http://www.example.com/trailers/": 1008 { 1009 "pattern": "http://www.example.com/trailers/*", 1010 "case-sensitive": true 1011 } 1013 5.2.5. Absolute Time 1015 A JSON number, seconds since the UNIX epoch. 1017 5.2.6. Error Description 1019 An Error Description is used to report failure of a CI/T Command, or 1020 in the activity it triggered. 1022 Name: error 1024 Value: Error Code, as defined in Section 5.2.7. 1026 Mandatory: Yes. 1028 Names: metadata.urls, content.urls, metadata.patterns, 1029 content.patterns 1031 Description: Metadata and content references copied from the 1032 Trigger Specification. Only those URLs and patterns to which 1033 the error applies are included in each property, but those URLs 1034 and patterns MUST be exactly as they appear in the request, the 1035 dCDN MUST NOT generalise the URLs. (For example, if the uCDN 1036 requests prepositioning of URLs "http://content.example.com/a" 1037 and "http://content.example.com/b", the dCDN must not 1038 generalise its error report to Pattern 1039 "http://content.example.com/*".) 1041 Value: A JSON array of JSON strings, where each string is 1042 copied from a 'content.*' or 'metadata.*' value in the 1043 corresponding Trigger Specification. 1045 Mandatory: At least one of these name/value pairs is mandatory 1046 in each Error Description object. 1048 Name: description 1050 Description: A human-readable description of the error. 1052 Value: A JSON string, the human-readable description. 1054 Mandatory: No. 1056 5.2.7. Error Code 1058 This type is used by the dCDN to report failures in trigger 1059 processing. 1061 +------------+------------------------------------------------------+ 1062 | Error Code | Description | 1063 +------------+------------------------------------------------------+ 1064 | emeta | The dCDN was unable to acquire metadata required to | 1065 | | fulfil the request. | 1066 | econtent | The dCDN was unable to acquire content (CT/T | 1067 | | preposition commands only). | 1068 | eperm | The uCDN does not have permission to issue the CI/T | 1069 | | Command (for example, the data is owned by another | 1070 | | CDN). | 1071 | ereject | The dCDN is not willing to fulfil the CI/T Command | 1072 | | (for example, a preposition request for content at a | 1073 | | time when the dCDN would not accept Request Routing | 1074 | | requests from the uCDN). | 1075 | ecdn | An internal error in the dCDN or one of its | 1076 | | downstream CDNs. | 1077 | ecancelled | The uCDN cancelled the request. | 1078 +------------+------------------------------------------------------+ 1080 6. Examples 1082 The following sections provide examples of different CI/T objects 1083 encoded as JSON. 1085 Discovery of the triggers interface is out of scope of this document. 1086 In an implementation, all CI/T URLs are under the control of the 1087 dCDN. The uCDN MUST NOT attempt to ascribe any meaning to individual 1088 elements of the path. 1090 In examples in this section, the URL 'http://dcdn.example.com/ 1091 triggers' is used as the location of the collection of all Trigger 1092 Status Resources, and the CDN Provider Id of uCDN is "AS64496:1". 1094 6.1. Creating Triggers 1096 Examples of the uCDN triggering activity in the dCDN: 1098 6.1.1. Preposition 1100 An example of a CI/T preposition command, a POST to the collection of 1101 all Trigger Status Resources. 1103 Note that "metadata.patterns" and "content.patterns" are not allowed 1104 in a preposition Trigger Specification. 1106 REQUEST: 1108 POST /triggers HTTP/1.1 1109 User-Agent: example-user-agent/0.1 1110 Host: dcdn.example.com 1111 Accept: */* 1112 Content-Type: application/cdni.ci.TriggerCommand+json 1113 Content-Length: 347 1115 { 1116 "trigger" : { 1117 "type": "preposition", 1119 "metadata.urls" : [ "http://metadata.example.com/a/b/c" ], 1120 "content.urls" : [ 1121 "http://www.example.com/a/b/c/1", 1122 "http://www.example.com/a/b/c/2", 1123 "http://www.example.com/a/b/c/3", 1124 "http://www.example.com/a/b/c/4" 1125 ] 1126 }, 1127 "cdn-path" : [ "AS64496:1" ] 1128 } 1130 RESPONSE: 1132 HTTP/1.1 201 Created 1133 Date: Sun, 31 Aug 2014 09:53:18 GMT 1134 Content-Length: 472 1135 Content-Type: application/cdni.ci.TriggerStatus+json 1136 Location: http://dcdn.example.com/triggers/0 1137 Server: example-server/0.1 1139 { 1140 "ctime": 1409478798, 1141 "etime": 1409478806, 1142 "mtime": 1409478798, 1143 "status": "pending", 1144 "trigger": { 1145 "content.urls": [ 1146 "http://www.example.com/a/b/c/1", 1147 "http://www.example.com/a/b/c/2", 1148 "http://www.example.com/a/b/c/3", 1149 "http://www.example.com/a/b/c/4" 1150 ], 1151 "metadata.urls": [ 1152 "http://metadata.example.com/a/b/c" 1153 ], 1154 "type": "preposition" 1155 } 1156 } 1158 6.1.2. Invalidate 1160 An example of a CI/T invalidate command, another POST to the 1161 collection of all Trigger Status Resources. This instructs the dCDN 1162 to re-validate the content at "http://www.example.com/a/index.html", 1163 as well as any metadata and content whose URLs are prefixed by 1164 "http://metadata.example.com/a/b/" using case-insensitive matching, 1165 and "http://www.example.com/a/b/" respectively, using case-sensitive 1166 matching. 1168 REQUEST: 1170 POST /triggers HTTP/1.1 1171 User-Agent: example-user-agent/0.1 1172 Host: dcdn.example.com 1173 Accept: */* 1174 Content-Type: application/cdni.ci.TriggerCommand+json 1175 Content-Length: 384 1177 { 1178 "trigger" : { 1179 "type": "invalidate", 1181 "metadata.patterns" : [ 1182 { "pattern" : "http://metadata.example.com/a/b/*" } 1183 ], 1185 "content.urls" : [ "http://www.example.com/a/index.html" ], 1186 "content.patterns" : [ 1187 { "pattern" : "http://www.example.com/a/b/*", 1188 "case-sensitive" : true 1189 } 1191 ] 1192 }, 1193 "cdn-path" : [ "AS64496:1" ] 1194 } 1196 RESPONSE: 1198 HTTP/1.1 201 Created 1199 Date: Sun, 31 Aug 2014 09:53:19 GMT 1200 Content-Length: 551 1201 Content-Type: application/cdni.ci.TriggerStatus+json 1202 Location: http://dcdn.example.com/triggers/1 1203 Server: example-server/0.1 1205 { 1206 "ctime": 1409478799, 1207 "etime": 1409478807, 1208 "mtime": 1409478799, 1209 "status": "pending", 1210 "trigger": { 1211 "content.patterns": [ 1212 { 1213 "case-sensitive": true, 1214 "pattern": "http://www.example.com/a/b/*" 1215 } 1216 ], 1217 "content.urls": [ 1218 "http://www.example.com/a/index.html" 1219 ], 1220 "metadata.patterns": [ 1221 { 1222 "pattern": "http://metadata.example.com/a/b/*" 1223 } 1224 ], 1225 "type": "invalidate" 1226 } 1227 } 1229 6.2. Examining Trigger Status 1231 Once Trigger Status Resources have been created, the uCDN can check 1232 their status as shown in these examples. 1234 6.2.1. Collection of All Triggers 1236 The uCDN can fetch the collection of all Trigger Status Resources it 1237 has created that have not yet been deleted or removed as expired. 1239 After creation of the "preposition" and "invalidate" triggers shown 1240 above, this collection might look as follows: 1242 REQUEST: 1244 GET /triggers HTTP/1.1 1245 User-Agent: example-user-agent/0.1 1246 Host: dcdn.example.com 1247 Accept: */* 1249 RESPONSE: 1251 HTTP/1.1 200 OK 1252 Content-Length: 347 1253 Expires: Sun, 31 Aug 2014 09:54:19 GMT 1254 Server: example-server/0.1 1255 Etag: "-6516741166528256414" 1256 Cache-Control: max-age=60 1257 Date: Sun, 31 Aug 2014 09:53:19 GMT 1258 Content-Type: application/cdni.ci.TriggerCollection+json 1260 { 1261 "cdn-id": "AS64496:0", 1262 "coll-active": "/triggers/active", 1263 "coll-complete": "/triggers/complete", 1264 "coll-failed": "/triggers/failed", 1265 "coll-pending": "/triggers/pending", 1266 "staleresourcetime": 86400, 1267 "triggers": [ 1268 "http://dcdn.example.com/triggers/0", 1269 "http://dcdn.example.com/triggers/1" 1270 ] 1271 } 1273 6.2.2. Filtered Collections of Trigger Status Resources 1275 The filtered collections are also available to the uCDN. Before the 1276 dCDN starts processing the two CI/T Trigger Commands shown above, 1277 both will appear in the collection of Pending Triggers, for example: 1279 REQUEST: 1281 GET /triggers/pending HTTP/1.1 1282 User-Agent: example-user-agent/0.1 1283 Host: dcdn.example.com 1284 Accept: */* 1286 RESPONSE: 1288 HTTP/1.1 200 OK 1289 Content-Length: 153 1290 Expires: Sun, 31 Aug 2014 09:54:19 GMT 1291 Server: example-server/0.1 1292 Etag: "5012053611544832286" 1293 Cache-Control: max-age=60 1294 Date: Sun, 31 Aug 2014 09:53:19 GMT 1295 Content-Type: application/cdni.ci.TriggerCollection+json 1297 { 1298 "staleresourcetime": 86400, 1299 "triggers": [ 1300 "http://dcdn.example.com/triggers/0", 1301 "http://dcdn.example.com/triggers/1" 1302 ] 1303 } 1305 At this point, if no other Trigger Status Resources had been created, 1306 the other filtered views would be empty. For example: 1308 REQUEST: 1310 GET /triggers/complete HTTP/1.1 1311 User-Agent: example-user-agent/0.1 1312 Host: dcdn.example.com 1313 Accept: */* 1315 RESPONSE: 1317 HTTP/1.1 200 OK 1318 Content-Length: 56 1319 Expires: Sun, 31 Aug 2014 09:54:19 GMT 1320 Server: example-server/0.1 1321 Etag: "2986340333785000363" 1322 Cache-Control: max-age=60 1323 Date: Sun, 31 Aug 2014 09:53:19 GMT 1324 Content-Type: application/cdni.ci.TriggerCollection+json 1326 { 1327 "staleresourcetime": 86400, 1328 "triggers": [] 1329 } 1331 6.2.3. Individual Trigger Status Resources 1333 The Trigger Status Resources can also be examined for detail about 1334 individual CI/T Trigger Commands. For example, for the CI/T 1335 "preposition" and "invalidate" commands from previous examples: 1337 REQUEST: 1339 GET /triggers/0 HTTP/1.1 1340 User-Agent: example-user-agent/0.1 1341 Host: dcdn.example.com 1342 Accept: */* 1344 RESPONSE: 1346 HTTP/1.1 200 OK 1347 Content-Length: 472 1348 Expires: Sun, 31 Aug 2014 09:54:19 GMT 1349 Server: example-server/0.1 1350 Etag: "-4765587034697674779" 1351 Cache-Control: max-age=60 1352 Date: Sun, 31 Aug 2014 09:53:19 GMT 1353 Content-Type: application/cdni.ci.TriggerStatus+json 1355 { 1356 "ctime": 1409478798, 1357 "etime": 1409478806, 1358 "mtime": 1409478798, 1359 "status": "pending", 1360 "trigger": { 1361 "content.urls": [ 1362 "http://www.example.com/a/b/c/1", 1363 "http://www.example.com/a/b/c/2", 1364 "http://www.example.com/a/b/c/3", 1365 "http://www.example.com/a/b/c/4" 1366 ], 1367 "metadata.urls": [ 1368 "http://metadata.example.com/a/b/c" 1369 ], 1370 "type": "preposition" 1371 } 1372 } 1374 REQUEST: 1376 GET /triggers/1 HTTP/1.1 1377 User-Agent: example-user-agent/0.1 1378 Host: dcdn.example.com 1379 Accept: */* 1381 RESPONSE: 1383 HTTP/1.1 200 OK 1384 Content-Length: 551 1385 Expires: Sun, 31 Aug 2014 09:54:19 GMT 1386 Server: example-server/0.1 1387 Etag: "-7657333837290433420" 1388 Cache-Control: max-age=60 1389 Date: Sun, 31 Aug 2014 09:53:19 GMT 1390 Content-Type: application/cdni.ci.TriggerStatus+json 1392 { 1393 "ctime": 1409478799, 1394 "etime": 1409478807, 1395 "mtime": 1409478799, 1396 "status": "pending", 1397 "trigger": { 1398 "content.patterns": [ 1399 { 1400 "case-sensitive": true, 1401 "pattern": "http://www.example.com/a/b/*" 1402 } 1403 ], 1404 "content.urls": [ 1405 "http://www.example.com/a/index.html" 1406 ], 1407 "metadata.patterns": [ 1408 { 1409 "pattern": "http://metadata.example.com/a/b/*" 1410 } 1411 ], 1412 "type": "invalidate" 1413 } 1414 } 1416 6.2.4. Polling for Change 1418 The uCDN SHOULD use the Entity Tags of collections or Trigger Status 1419 Resources when polling for change in status, as shown in the 1420 following examples: 1422 REQUEST: 1424 GET /triggers/pending HTTP/1.1 1425 User-Agent: example-user-agent/0.1 1426 Host: dcdn.example.com 1427 Accept: */* 1428 If-None-Match: "5012053611544832286" 1430 RESPONSE: 1432 HTTP/1.1 304 Not Modified 1433 Content-Length: 0 1434 Expires: Sun, 31 Aug 2014 09:54:19 GMT 1435 Server: example-server/0.1 1436 Etag: "5012053611544832286" 1437 Cache-Control: max-age=60 1438 Date: Sun, 31 Aug 2014 09:53:19 GMT 1439 Content-Type: application/cdni.ci.TriggerCollection+json 1441 REQUEST: 1443 GET /triggers/0 HTTP/1.1 1444 User-Agent: example-user-agent/0.1 1445 Host: dcdn.example.com 1446 Accept: */* 1447 If-None-Match: "-4765587034697674779" 1449 RESPONSE: 1451 HTTP/1.1 304 Not Modified 1452 Content-Length: 0 1453 Expires: Sun, 31 Aug 2014 09:54:19 GMT 1454 Server: example-server/0.1 1455 Etag: "-4765587034697674779" 1456 Cache-Control: max-age=60 1457 Date: Sun, 31 Aug 2014 09:53:19 GMT 1458 Content-Type: application/cdni.ci.TriggerStatus+json 1460 When the CI/T Trigger Command is complete, the contents of the 1461 filtered collections will be updated along with their Entity Tags. 1462 For example, when the two example CI/T Trigger Commands are complete, 1463 the collections of pending and complete Trigger Status Resources 1464 might look like: 1466 REQUEST: 1468 GET /triggers/pending HTTP/1.1 1469 User-Agent: example-user-agent/0.1 1470 Host: dcdn.example.com 1471 Accept: */* 1473 RESPONSE: 1475 HTTP/1.1 200 OK 1476 Content-Length: 56 1477 Expires: Sun, 31 Aug 2014 09:54:29 GMT 1478 Server: example-server/0.1 1479 Etag: "-4471185573414616962" 1480 Cache-Control: max-age=60 1481 Date: Sun, 31 Aug 2014 09:53:29 GMT 1482 Content-Type: application/cdni.ci.TriggerCollection+json 1484 { 1485 "staleresourcetime": 86400, 1486 "triggers": [] 1487 } 1489 REQUEST: 1491 GET /triggers/complete HTTP/1.1 1492 User-Agent: example-user-agent/0.1 1493 Host: dcdn.example.com 1494 Accept: */* 1496 RESPONSE: 1498 HTTP/1.1 200 OK 1499 Content-Length: 153 1500 Expires: Sun, 31 Aug 2014 09:54:30 GMT 1501 Server: example-server/0.1 1502 Etag: "-1508172875796647067" 1503 Cache-Control: max-age=60 1504 Date: Sun, 31 Aug 2014 09:53:30 GMT 1505 Content-Type: application/cdni.ci.TriggerCollection+json 1507 { 1508 "staleresourcetime": 86400, 1509 "triggers": [ 1510 "http://dcdn.example.com/triggers/0", 1511 "http://dcdn.example.com/triggers/1" 1512 ] 1513 } 1515 6.2.5. Deleting Trigger Status Resources 1517 The dCDN can delete completed and failed Trigger Status Resources to 1518 reduce the size of the collections. For example, to delete the 1519 "preposition" request from earlier examples: 1521 REQUEST: 1523 DELETE /triggers/0 HTTP/1.1 1524 User-Agent: example-user-agent/0.1 1525 Host: dcdn.example.com 1526 Accept: */* 1528 RESPONSE: 1530 HTTP/1.1 204 No Content 1531 Date: Sun, 31 Aug 2014 09:53:30 GMT 1532 Content-Length: 0 1533 Content-Type: text/html; charset=UTF-8 1534 Server: example-server/0.1 1536 This would, for example, cause the collection of completed Trigger 1537 Status Resources shown in the example above to be updated to: 1539 REQUEST: 1541 GET /triggers/complete HTTP/1.1 1542 User-Agent: example-user-agent/0.1 1543 Host: dcdn.example.com 1544 Accept: */* 1546 RESPONSE: 1548 HTTP/1.1 200 OK 1549 Content-Length: 106 1550 Expires: Sun, 31 Aug 2014 09:54:30 GMT 1551 Server: example-server/0.1 1552 Etag: "-1842390246836476263" 1553 Cache-Control: max-age=60 1554 Date: Sun, 31 Aug 2014 09:53:30 GMT 1555 Content-Type: application/cdni.ci.TriggerCollection+json 1557 { 1558 "staleresourcetime": 86400, 1559 "triggers": [ 1560 "http://dcdn.example.com/triggers/1" 1561 ] 1562 } 1564 6.2.6. Error Reporting 1566 In this example the uCDN has requested prepositioning of 1567 "http://newsite.example.com/index.html", but the dCDN was unable to 1568 locate metadata for that site: 1570 REQUEST: 1572 GET /triggers/2 HTTP/1.1 1573 User-Agent: example-user-agent/0.1 1574 Host: dcdn.example.com 1575 Accept: */* 1577 RESPONSE: 1579 HTTP/1.1 200 OK 1580 Content-Length: 505 1581 Expires: Sun, 31 Aug 2014 09:54:38 GMT 1582 Server: example-server/0.1 1583 Etag: "-3893590191073700822" 1584 Cache-Control: max-age=60 1585 Date: Sun, 31 Aug 2014 09:53:38 GMT 1586 Content-Type: application/cdni.ci.TriggerStatus+json 1588 { 1589 "ctime": 1409478810, 1590 "errors": [ 1591 { 1592 "content.urls": [ 1593 "http://newsite.example.com/index.html" 1594 ], 1595 "description": 1596 "No HostIndex entry found for newsite.example.com", 1597 "error": "emeta" 1598 } 1599 ], 1600 "etime": 1409478818, 1601 "mtime": 1409478814, 1602 "status": "active", 1603 "trigger": { 1604 "content.urls": [ 1605 "http://newsite.example.com/index.html" 1606 ], 1607 "type": "preposition" 1608 } 1609 } 1611 7. IANA Considerations 1612 7.1. Media type registrations 1614 7.1.1. CI/T Commands 1616 The MIME media type for CI/T Commands is application/ 1617 cdni.ci.TriggerCommand+json. 1619 Type Name: application 1621 Subtype name: cdni.ci.TriggerCommand+json 1623 Required parameters: N/A 1625 Optional parameters: N/A 1627 Encoding considerations: binary 1629 Security Considerations: See [RFCthis], Section 8 1631 Interoperability Considerations: Described in [RFCthis] 1633 Published Specification: [RFCthis] 1635 Applications that use this media type: No known applications 1636 currently use this media type. 1638 Additional Information: 1640 Deprecated alias names for this type: N/A 1642 Magic number(s): N/A 1644 File Extensions: N/A 1646 Macintosh file type code(s): TEXT 1648 Person & email address to contact for further information: IESG 1649 1651 Intended Usage: COMMON 1653 Restrictions on usage: None 1655 Author: Rob Murray 1657 Change controller: IESG 1658 Note: No "charset" parameter is defined for this registration because 1659 a charset parameter is not defined for application/json [RFC7159]. 1661 7.1.2. CI/T Trigger Status Resource 1663 The MIME media type for CI/T Trigger Status Resources is application/ 1664 cdni.ci.TriggerStatus+json. 1666 Type Name: application 1668 Subtype name: cdni.ci.TriggerStatus+json 1670 Required parameters: N/A 1672 Optional parameters: N/A 1674 Encoding considerations: binary 1676 Security Considerations: See [RFCthis], Section 8 1678 Interoperability Considerations: Described in [RFCthis] 1680 Published Specification: [RFCthis] 1682 Applications that use this media type: No known applications 1683 currently use this media type. 1685 Additional Information: 1687 Deprecated alias names for this type: N/A 1689 Magic number(s): N/A 1691 File Extensions: N/A 1693 Macintosh file type code(s): TEXT 1695 Person & email address to contact for further information: IESG 1696 1698 Intended Usage: COMMON 1700 Restrictions on usage: None 1702 Author: Rob Murray 1704 Change controller: IESG 1705 Note: No "charset" parameter is defined for this registration because 1706 a charset parameter is not defined for application/json [RFC7159]. 1708 7.1.3. CI/T Trigger Collection 1710 The MIME media type for CI/T Trigger Collections is application/ 1711 cdni.ci.TriggerCollection+json. 1713 Type Name: application 1715 Subtype name: cdni.ci.TriggerCollection+json 1717 Required parameters: N/A 1719 Optional parameters: N/A 1721 Encoding considerations: binary 1723 Security Considerations: See [RFCthis], Section 8 1725 Interoperability Considerations: Described in [RFCthis] 1727 Published Specification: [RFCthis] 1729 Applications that use this media type: No known applications 1730 currently use this media type. 1732 Additional Information: 1734 Deprecated alias names for this type: N/A 1736 Magic number(s): N/A 1738 File Extensions: N/A 1740 Macintosh file type code(s): TEXT 1742 Person & email address to contact for further information: IESG 1743 1745 Intended Usage: COMMON 1747 Restrictions on usage: None 1749 Author: Rob Murray 1751 Change controller: IESG 1752 Note: No "charset" parameter is defined for this registration because 1753 a charset parameter is not defined for application/json [RFC7159]. 1755 8. Security Considerations 1757 8.1. Authentication, Confidentiality, Integrity Protection 1759 A CI/T implementation MUST support TLS transport for HTTP (https) as 1760 per [RFC2818]. The use of TLS for transport of the CI/T interface 1761 allows the dCDN and the uCDN to authenticate each other (to ensure 1762 they are receiving CI/T Commands from, or reporting status to, an 1763 authenticated CDN). 1765 In an environment where any such protection is required, TLS SHOULD 1766 be used for transport of the CI/T requests and responses, unless 1767 alternate methods are used for ensuring that only authorised clients 1768 are able to access their own data (such as setting up an IPsec tunnel 1769 between the two CDNs, or using a physically secured internal network 1770 between two CDNs that are owned by the same corporate entity). Both 1771 parties of the transaction (the uCDN and the dCDN) SHOULD use mutual 1772 authentication. 1774 A TLS implementation of CI/T MUST support the 1775 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 cipher suite ([RFC5288]). An 1776 implementation of the CI/T Interface SHOULD prefer cipher suites 1777 which support perfect forward secrecy over cipher suites that don't. 1779 HTTP requests that attempt to access or operate on CI/T data 1780 belonging to another CDN MUST be rejected using, for example, HTTP 1781 "403 Forbidden" or "404 Not Found". This is intended to prevent 1782 unauthorised users from generating unnecessary load in dCDN or uCDN 1783 due to revalidation, reacquisition, or unnecessary acquisition. 1785 Note that in a "diamond" configuration, where one uCDN's content can 1786 be acquired via more than one directly-connected uCDN, it may not be 1787 possible for the dCDN to determine from which uCDN it acquired 1788 content. In this case, the dCDN MUST allow each uCDN from which the 1789 content could have been acquired to act upon that content using CI/T 1790 Commands. 1792 8.2. Denial of Service 1794 This document does not define a specific mechanism to protect against 1795 Denial of Service (DoS) attacks on the CI/T. However, CI/T endpoints 1796 can be protected against DoS attacks through the use of TLS transport 1797 and/or via mechanisms outside the scope of the CI/T interface, such 1798 as firewalling or use of Virtual Private Networks (VPNs). 1800 Depending on the implementation, triggered activity may consume 1801 significant processing and bandwidth in the dCDN. A malicious or 1802 faulty uCDN could use this to generate unnecessary load in the dCDN. 1803 The dCDN should consider mechanisms to avoid overload, for example by 1804 rate-limiting acceptance or processing of CI/T Commands, or batching 1805 up its processing. 1807 9. Acknowledgements 1809 The authors thank Kevin Ma for his input. 1811 10. References 1813 10.1. Normative References 1815 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1816 Requirement Levels", BCP 14, RFC 2119, March 1997. 1818 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1819 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1820 3986, January 2005. 1822 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1823 Interchange Format", RFC 7159, March 2014. 1825 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1826 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 1828 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1829 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 1831 10.2. Informative References 1833 [I-D.ietf-cdni-metadata] 1834 Niven-Jenkins, B., Murray, R., Caulfield, M., and K. Ma, 1835 "CDN Interconnection Metadata", draft-ietf-cdni- 1836 metadata-08 (work in progress), October 2014. 1838 [I-D.ietf-cdni-redirection] 1839 Niven-Jenkins, B. and R. Brandenburg, "Request Routing 1840 Redirection Interface for CDN Interconnection", draft- 1841 ietf-cdni-redirection-06 (work in progress), December 1842 2014. 1844 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1846 [RFC5288] Salowey, J., Choudhury, A., and D. McGrew, "AES Galois 1847 Counter Mode (GCM) Cipher Suites for TLS", RFC 5288, 1848 August 2008. 1850 [RFC6707] Niven-Jenkins, B., Le Faucheur, F., and N. Bitar, "Content 1851 Distribution Network Interconnection (CDNI) Problem 1852 Statement", RFC 6707, September 2012. 1854 [RFC7336] Peterson, L., Davie, B., and R. van Brandenburg, 1855 "Framework for Content Distribution Network 1856 Interconnection (CDNI)", RFC 7336, August 2014. 1858 [RFC7337] Leung, K. and Y. Lee, "Content Distribution Network 1859 Interconnection (CDNI) Requirements", RFC 7337, August 1860 2014. 1862 Authors' Addresses 1864 Rob Murray 1865 Velocix (Alcatel-Lucent) 1866 3 Ely Road 1867 Milton, Cambridge CB24 6DD 1868 UK 1870 Email: rob.murray@alcatel-lucent.com 1872 Ben Niven-Jenkins 1873 Velocix (Alcatel-Lucent) 1874 3 Ely Road 1875 Milton, Cambridge CB24 6DD 1876 UK 1878 Email: ben.niven-jenkins@alcatel-lucent.com