idnits 2.17.1 draft-ietf-cdni-control-triggers-02.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 2, 2013) is 3769 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: 'HIGH' is mentioned on line 150, but not defined == Missing Reference: 'MED' is mentioned on line 160, but not defined == Unused Reference: 'RFC3986' is defined on line 1522, but no explicit reference was found in the text == Unused Reference: 'RFC4287' is defined on line 1545, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) == Outdated reference: A later version (-14) exists of draft-ietf-cdni-framework-07 == Outdated reference: A later version (-21) exists of draft-ietf-cdni-metadata-03 == Outdated reference: A later version (-17) exists of draft-ietf-cdni-requirements-13 Summary: 1 error (**), 0 flaws (~~), 8 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 5, 2014 December 2, 2013 7 CDNI Control Interface / Triggers 8 draft-ietf-cdni-control-triggers-02 10 Abstract 12 This document describes the part of the CDN Interconnect 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 re-validate or 17 purge 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 5, 2014. 43 Copyright Notice 45 Copyright (c) 2013 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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 62 2. Model for CDNI Triggers . . . . . . . . . . . . . . . . . . . 5 63 2.1. Timing of Triggered Activity . . . . . . . . . . . . . . . 7 64 2.2. Trigger Results . . . . . . . . . . . . . . . . . . . . . 7 65 3. Collections of Trigger Status Resources . . . . . . . . . . . 7 66 4. CDNI Trigger interface . . . . . . . . . . . . . . . . . . . . 8 67 4.1. Creating Triggers . . . . . . . . . . . . . . . . . . . . 9 68 4.2. Checking Status . . . . . . . . . . . . . . . . . . . . . 10 69 4.2.1. Polling Trigger Status Resource collections . . . . . 11 70 4.2.2. Polling Trigger Status Resources . . . . . . . . . . . 11 71 4.3. Deleting Triggers . . . . . . . . . . . . . . . . . . . . 11 72 4.4. Expiry of Trigger Status Resources . . . . . . . . . . . . 12 73 4.5. Error Handling . . . . . . . . . . . . . . . . . . . . . . 12 74 5. Properties of Triggers . . . . . . . . . . . . . . . . . . . . 13 75 5.1. Properties of Trigger Requests . . . . . . . . . . . . . . 13 76 5.1.1. Content URLs . . . . . . . . . . . . . . . . . . . . . 14 77 5.2. Properties of Trigger Status Resources . . . . . . . . . . 14 78 5.3. Properties of ErrorDesc . . . . . . . . . . . . . . . . . 15 79 5.4. Properties of Trigger Collections . . . . . . . . . . . . 15 80 5.5. Trigger Resource Simple Data Type Descriptions . . . . . . 16 81 5.5.1. TriggerType . . . . . . . . . . . . . . . . . . . . . 16 82 5.5.2. TriggerStatus . . . . . . . . . . . . . . . . . . . . 16 83 5.5.3. URLs . . . . . . . . . . . . . . . . . . . . . . . . . 16 84 5.5.4. AbsoluteTime . . . . . . . . . . . . . . . . . . . . . 17 85 5.5.5. ErrorCode . . . . . . . . . . . . . . . . . . . . . . 17 86 6. JSON Encoding of Objects . . . . . . . . . . . . . . . . . . . 17 87 6.1. JSON Encoding of Embedded Types . . . . . . . . . . . . . 18 88 6.1.1. TriggerType . . . . . . . . . . . . . . . . . . . . . 18 89 6.1.2. TriggerStatus . . . . . . . . . . . . . . . . . . . . 18 90 6.1.3. PatternMatch . . . . . . . . . . . . . . . . . . . . . 18 91 6.1.4. ErrorDesc . . . . . . . . . . . . . . . . . . . . . . 19 92 6.1.5. ErrorCode . . . . . . . . . . . . . . . . . . . . . . 19 93 6.1.6. Relationship . . . . . . . . . . . . . . . . . . . . . 19 94 6.1.7. Link Object . . . . . . . . . . . . . . . . . . . . . 20 95 6.2. MIME Media Types . . . . . . . . . . . . . . . . . . . . . 20 97 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 98 7.1. Creating Triggers . . . . . . . . . . . . . . . . . . . . 21 99 7.1.1. Preposition . . . . . . . . . . . . . . . . . . . . . 21 100 7.1.2. Invalidate . . . . . . . . . . . . . . . . . . . . . . 22 101 7.2. Examining Trigger Status . . . . . . . . . . . . . . . . . 23 102 7.2.1. Collection of All Triggers . . . . . . . . . . . . . . 24 103 7.2.2. Filtered Collections of Triggers . . . . . . . . . . . 25 104 7.2.3. Trigger Status Resources . . . . . . . . . . . . . . . 26 105 7.2.4. Polling for Change . . . . . . . . . . . . . . . . . . 28 106 7.2.5. Cancelling or Removing a Trigger . . . . . . . . . . . 31 107 7.2.6. Error Reporting . . . . . . . . . . . . . . . . . . . 33 108 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 109 8.1. CI/T MIME Media Types . . . . . . . . . . . . . . . . . . 35 110 9. Security Considerations . . . . . . . . . . . . . . . . . . . 35 111 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 35 112 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 35 113 11.1. Normative References . . . . . . . . . . . . . . . . . . . 35 114 11.2. Informative References . . . . . . . . . . . . . . . . . . 36 115 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 36 117 1. Introduction 119 [RFC6707] introduces the Problem scope for CDN Interconnection (CDNI) 120 and lists the four categories of interfaces that may be used to 121 compose a CDNI solution (Control, Metadata, Request Routing, 122 Logging). 124 [I-D.ietf-cdni-framework] expands on the information provided in 125 [RFC6707] and describes each of the interfaces and the relationships 126 between them in more detail. 128 This document describes the "CI/T" interface, "CDNI Control interface 129 / Triggers". It does not consider those parts of the control 130 interface that relate to configuration, bootstrapping or 131 authentication of CDN Interconnect interfaces. Requirements for CI/T 132 are the "High" and "Medium" priority requirements for the CI 133 identified in section 4 of [I-D.ietf-cdni-requirements], reproduced 134 here for convenience: 136 CI-1 [HIGH] The CDNI Control interface shall allow the Upstream 137 CDN to request that the Downstream CDN, including downstream 138 cascaded CDNs, delete an object or set of objects and/or its CDNI 139 metadata from the CDN surrogates and any storage. Only the 140 object(s) and CDNI metadata that pertain to the requesting 141 Upstream CDN are allowed to be purged. 142 CI-2 [MED] The CDNI Control interface should allow for multiple 143 content items identified by a Content Collection ID to be purged 144 using a single Content Purge action. 145 CI-3 [MED] The CDNI Control interface should allow the Upstream 146 CDN to request that the Downstream CDN, including downstream 147 cascaded CDNs, mark an object or set of objects and/or its CDNI 148 metadata as "stale" and revalidate them before they are delivered 149 again. 150 CI-4 [HIGH] The CDNI Control interface shall allow the Downstream 151 CDN to report on the completion of these actions (by itself, and 152 including downstream cascaded CDNs, in a manner appropriate for 153 the action (e.g. synchronously or asynchronously). The 154 confirmation receipt should include a success or failure 155 indication. The failure indication along with the reason are used 156 if the Downstream CDN cannot delete the content in its storage. 157 CI-5 [MED] The CDNI Control interface should support initiation 158 and control by the Upstream CDN of pre-positioned CDNI metadata 159 acquisition by the Downstream CDN. 160 CI-6 [MED] The CDNI Control interface should support initiation 161 and control by the Upstream CDN of pre-positioned content 162 acquisition by the Downstream CDN. 164 o Section 2 outlines the model for the CI/T Interface at a high 165 level. 166 o Section 3 describes collections of Trigger Resources. 167 o Section 4 defines the RESTful web service provided by dCDN. 168 o Section 5 lists properties of Trigger Requests and Status 169 Resources. 170 o Section 6 defines a JSON encoding for Trigger Requests and Status 171 Resources. 172 o Section 7 contains example messages. 174 1.1. Terminology 176 This document reuses the terminology defined in [RFC6707]. 178 2. Model for CDNI Triggers 180 A trigger, sent from uCDN to dCDN, is a request for dCDN to do some 181 work relating to data originating from uCDN. 183 The trigger may request action on either metadata or content, the 184 following actions can be requested: 186 o preposition - used to instruct dCDN to fetch metadata from uCDN, 187 or content from any origin including uCDN. 188 o invalidate - used to instruct dCDN to revalidate specific metadata 189 or content before re-using it. 190 o purge - used to instruct dCDN to delete specific metadata or 191 content. 193 The CI/T interface is a RESTful web service offered by dCDN. It 194 allows creation and deletion of triggers, and tracking of the 195 triggered activity. When dCDN accepts a trigger it creates a 196 resource describing status of the triggered activity, a Trigger 197 Status Resource. The uCDN may poll Trigger Status Resources to 198 monitor progress. 200 Requests to invalidate and purge metadata or content apply to all 201 variants of that data with a given URI. 203 The dCDN maintains a collection of Trigger Status Resources for each 204 uCDN, each uCDN only has access to its own collection and the 205 location of that collection is shared when CDN interconnection is 206 established. 208 To trigger activity in dCDN, uCDN will POST to the collection of 209 Trigger Status Resources. If dCDN accepts the trigger, it creates a 210 new Trigger Status Resource and returns its location to uCDN. To 211 monitor progress, uCDN may GET the Trigger Status Resource. To 212 cancel a trigger, or remove a trigger from the collection once its 213 activity has been completed, uCDN may DELETE the Trigger Status 214 Resource. 216 In addition to the collection of all Trigger Status Resources for 217 uCDN, uCDN shall have access to filtered views of that collection. 218 These filtered views are defined in Section 3 and include collections 219 of active and completed triggers. These collections provide a 220 mechanism for polling the status of multiple jobs. 222 Figure 1 is an example showing the basic message flow used by the 223 uCDN to trigger activity in dCDN, and for uCDN to discover the status 224 of that activity. Only successful triggering is shown. Examples of 225 the messages are given in Section 7. 226 uCDN dCDN 227 | (1) POST http://dcdn.example.com/triggers/uCDN | 228 [ ] --------------------------------------------------> [ ]--+ 229 | [ ] | (2) 230 | (3) HTTP 201 Response [ ]<-+ 231 [ ] <-------------------------------------------------- [ ] 232 | Loc: http://dcdn.example.com/triggers/uCDN/123 | 233 | | 234 . . . 235 . . . 236 . . . 237 | | 238 | (4) GET http://dcdn.example.com/triggers/uCDN/123 | 239 [ ] --------------------------------------------------> [ ] 240 | [ ] 241 | (5) HTTP 200 Trigger Status Resource [ ] 242 [ ] <-------------------------------------------------- [ ] 243 | | 244 | | 246 Figure 1: Basic CDNI Message Flow for Triggers 248 The steps in Figure 1 are: 250 1. uCDN triggers action in dCDN by posting to a collection of 251 Trigger Status Resources, 252 "http://dcdn.example.com/triggers/uCDN". The URL of this was 253 given to uCDN when the trigger interface was established. 254 2. dCDN authenticates the request, validates the trigger and if it 255 accepts the request, creates a new Trigger Status Resource. 256 3. dCDN responds to uCDN with an HTTP 201 response status, and the 257 location of the Trigger Status Resource. 259 4. uCDN may repeatedly poll the Trigger Status Resource in dCDN. 260 5. dCDN responds with the Trigger Status Resource, describing 261 progress or results of the triggered activity. 263 The remainder of this document describes the messages, Trigger Status 264 Resources, and collections of Trigger Status Resources in more 265 detail. 267 2.1. Timing of Triggered Activity 269 Timing of triggered activity is under dCDN control, including its 270 start-time and pacing of the activity in the network. 272 Invalidate and purge triggers MUST be applied to all data acquired 273 before the trigger was created in dCDN. The dCDN MAY apply the 274 triggers to data acquired after trigger creation. 276 If uCDN wishes to invalidate or purge content, then immediately 277 preposition replacement content at the same URLs, it must ensure the 278 dCDN has completed the invalidate/purge before initiating the 279 prepositioning. If it fails to do that and the requests overlap, and 280 dCDN passes the triggers on to a further dCDN in a cascade, that CDN 281 may preposition content that has not yet been invalidated/purged in 282 its uCDN. 284 2.2. Trigger Results 286 Each Trigger Request may operate on multiple data items. The trigger 287 shall be reported as "complete" only if all actions can be completed 288 successfully, otherwise it shall be reported as "failed". The 289 reasons for failure and URLs or Patterns affected shall be enumerated 290 in the Trigger Status Resource. For more detail, see section 291 Section 4.5. 293 If a dCDN is also acting as uCDN in a cascade, it MUST forward 294 triggers to any downstream CDNs that may have data affected by the 295 trigger. The trigger MUST NOT be reported as complete in a CDN until 296 it is complete in all of its downstream CDNs. A trigger MAY be 297 reported as failed as soon as it fails in a CDN or in any of its 298 downstream CDNs. 300 3. Collections of Trigger Status Resources 302 As described in Section 2, Trigger Status Resources exist in dCDN to 303 report the status of activity triggered by each uCDN. 305 A collection of Trigger Status Resources is a resource that contains 306 a reference to each Trigger Status Resource in that collection. 308 To trigger activity in dCDN, uCDN creates a new Trigger Status 309 Resource by posting to dCDN's collection of uCDN's Trigger Status 310 Resources. The URL of each Trigger Status Resource is generated by 311 the dCDN when it accepts the trigger, and returned to uCDN. This 312 immediately enables uCDN to check the status of that trigger. 314 The dCDN must present a different set of Trigger Status Resources to 315 each interconnected uCDN, only Trigger Status Resources belonging to 316 a uCDN shall be visible to it. The dCDN may, for example, achieve 317 this by offering different collection URLs to uCDNs, or by filtering 318 the response based on the client uCDN. 320 The dCDN resource representing the collection of all uCDN's Trigger 321 Status Resources is accessible to uCDN. This collection lists all 322 uCDN triggers that have been accepted by dCDN, and have not yet been 323 deleted by uCDN or expired and removed by dCDN. 325 In order to allow uCDN to check status of multiple jobs in a single 326 request, dCDN shall also maintain collections representing filtered 327 views of the collection of all Trigger Status Resources. The 328 filtered collections are: 329 o Pending - Trigger Status Resources for triggers that have been 330 accepted, but not yet acted upon. 331 o Active - Trigger Status Resources for triggered activity that is 332 currently being processed in dCDN. 333 o Complete - Trigger Status Resources representing activity that 334 completed successfully. 335 o Failed - Trigger Status Resources representing activity that 336 failed. 338 4. CDNI Trigger interface 340 This section describes an interface to enable an upstream CDN to 341 trigger defined activities in a downstream CDN. The interface is 342 intended to be independent of the set of activities defined now, or 343 that may be defined in future. 345 CI/T is built on the principles of RESTful web services. Requests 346 are made over HTTP, and the HTTP Method defines the operation the 347 request would like to perform. The corresponding HTTP Response 348 returns the status of the operation in the HTTP Status Code and 349 returns the current representation of the resource (if appropriate) 350 in the Response Body. HTTP Responses from servers implementing CI/T 351 that contain a response body SHOULD include an ETag to enable 352 validation of cached versions of returned resources. 354 Servers implementing CI/T MUST support the HTTP GET, HEAD, POST and 355 DELETE methods. The only representation specified in this document 356 is JSON. 358 Trigger Requests are POSTed to a URI in dCDN. If the trigger is 359 accepted by dCDN, it creates a Trigger Status Resource and returns 360 its URI to dCDN in an HTTP 201 response. The triggered activity can 361 then be monitored by uCDN using that resource and the collections 362 described in Section 3. 364 The URI that Trigger Requests should be POSTed to needs to be either 365 discovered by or configured in the upstream CDN. Performing a GET on 366 that URI retrieves a collection of the URIs of all Trigger Status 367 Resources. The URI of each Trigger Status Resource is also returned 368 to uCDN when it is created. This means all Trigger Status Resources 369 can be discovered, so CI/T servers are free to assign whatever 370 structure they desire to the URIs for CI/T resources. CI/T clients 371 MUST NOT make any assumptions regarding the structure of CI/T URIs or 372 the mapping between CI/T objects and their associated URIs. 373 Therefore any URIs present in the examples below are purely 374 illustrative and are not intended to impose a definitive structure on 375 CI/T interface implementations. 377 The CI/T interface builds on top of HTTP, so CI/T servers may make 378 use of any HTTP feature when implementing the CI/T interface. For 379 example, a CI/T server may make use of HTTP's caching mechanisms to 380 indicate that the returned response/representation has not been 381 modified since it was last returned, reducing the processing needed 382 to determine whether the status of triggered activity has changed. 384 This specification is neutral with regard to the transport below the 385 HTTP layer. 387 Discovery of the CI/T Interface is outside the scope of this 388 document. It is anticipated that a common mechanism for discovery of 389 all CDNI interfaces will be defined. 391 The dCDN must ensure that activity triggered by uCDN only affects 392 metadata or content originating from that uCDN. Since only one CDN 393 can be authoritative for a given item of metadata or content, this 394 requirement means there cannot be any "loops" in trigger requests 395 between CDNs. 397 4.1. Creating Triggers 399 To create a new trigger, uCDN makes an HTTP POST to the unfiltered 400 collection of its triggers. The request body of that POST is a 401 Trigger Request. 403 dCDN validates and authenticates that request, if it is malformed or 404 uCDN does not have sufficient access rights it MAY reject the request 405 immediately. In this case, it SHALL respond with an appropriate 4xx 406 HTTP error code and no resource shall be created on dCDN. 408 If the request is accepted, uCDN SHALL create a new Trigger Status 409 Resource. The HTTP response to dCDN SHALL have status code 201 and 410 the URI of the Trigger Status Resource in the Location header field. 411 The HTTP response MAY include the content of the newly created 412 Trigger Status Resource, this is recommended particularly in cases 413 where the trigger has completed immediately. 415 Once a Trigger Status Resource has been created dCDN MUST NOT re-use 416 its location, even after that resource has been removed through 417 deletion or expiry. 419 The "request" property of the Trigger Status Resource SHALL contain 420 the information posted in the body of the Trigger Request. Note that 421 this need not be a byte-for-byte copy. For example, in the JSON 422 representation the dCDN may re-serialise the information differently. 424 If the trigger is queued by dCDN for later action, the "status" 425 property of the Trigger Status Resource SHALL be "pending". Once 426 trigger processing has started the "status" SHALL be "active". 428 A trigger may result in no activity in dCDN if, for example, it is an 429 invalidate or purge request for data the dCDN has not acquired, or a 430 prepopulate request for data it has already acquired. In this case, 431 the "status" of the Trigger Status Resource shall be "complete" and 432 the Trigger Status Resource shall be added to the dCDN collection of 433 Complete Triggers. 435 If dCDN is not able to track triggered activity, it MAY indicate that 436 it has undertaken to complete the activity but will not report 437 completion or any further errors. To do this, it must set the 438 trigger status to "complete", with an estimated completion time in 439 the future ("etime" greater than "mtime"). 441 Once created, Trigger Status Resources may be deleted by uCDN but not 442 modified. The dCDN MUST reject PUT and POST requests from uCDN to 443 Trigger Status Resources using HTTP status code 403. 445 4.2. Checking Status 447 The uCDN has two ways to check progress of activity it has triggered 448 in dCDN, described in the following sections. 450 Because the triggers protocol is based on HTTP, Entity Tags may be 451 used by the uCDN as cache validators, as defined in section 3.11 of 452 [RFC2616], to check for change in status of a resource or collection 453 of resources without re-fetching the whole resource or collection. 455 The dCDN should use the cache control headers for responses to GETs 456 for Trigger Status Resources and Collections to indicate the 457 frequency at which it recommends uCDN should poll for change. 459 4.2.1. Polling Trigger Status Resource collections 461 uCDN can fetch the collection of its Trigger Status Resources, or 462 filtered views of that collection. 464 This makes it possible to poll status of all triggered activity in a 465 single request. If dCDN moves a Trigger Status Resource from the 466 Active to the Completed collection, uCDN may chose to fetch the 467 result of that activity. 469 When polling in this way, uCDN may choose to use HTTP Entity Tags to 470 monitor for change, rather than repeatedly fetching the whole 471 collection. 473 4.2.2. Polling Trigger Status Resources 475 uCDN has a reference (URI provided by the dCDN) for each Trigger 476 Status Resource it has created, it may fetch that resource at any 477 time. 479 This may be used to retrieve progress information, and to fetch the 480 result of triggered activity. 482 4.3. Deleting Triggers 484 The uCDN MAY delete Trigger Status Resources at any time, using the 485 HTTP DELETE method. 487 Once deleted, the references to a Trigger Status Resource MUST be 488 removed from all Trigger Status Resource collections. Subsequent 489 requests for the resource shall be handled as required by HTTP, and 490 so will receive responses with status 404 or 410. 492 If a "pending" Trigger Status Resource is deleted, dCDN SHOULD NOT 493 start processing of that activity. Deleting a "pending" trigger does 494 not however guarantee that it is not started because, once it has 495 triggered activity, uCDN cannot control the timing of that activity. 496 Processing may, for example, start after the DELETE is sent by uCDN 497 and before the DELETE is processed by dCDN. 499 If an "active" Trigger Status Resource is deleted, dCDN MAY stop 500 processing the triggered activity. However, as with deletion of a 501 "pending" trigger, dCDN does not guarantee this. 503 Deletion of a "complete" or "failed" Trigger Status Resource requires 504 no processing in dCDN other than deletion of the resource. 506 4.4. Expiry of Trigger Status Resources 508 The dCDN MAY choose to automatically delete Trigger Status Resources 509 some time after they become completed or failed. In this case, dCDN 510 will remove the resource and respond to subsequent requests for it 511 with HTTP status 404 or 410. 513 If dCDN performs this housekeeping, it MUST have reported the length 514 of time after which completed Trigger Status Resources become stale 515 via a property of the collection of all Trigger Status Resources. It 516 is recommended that Trigger Status Resources are automatically 517 deleted 24 hours after they become completed or failed. 519 To ensure it has access to the status of its completed and failed 520 triggers, it is recommended that uCDN's polling interval is half the 521 time after which records for completed activity will be considered 522 stale. 524 4.5. Error Handling 526 A CI/T server may reject a trigger request using HTTP status codes, 527 for example 400 if the request is malformed or 401 if the client does 528 not have permission to create triggers or it is trying to act on 529 another CDN's data. 531 If any part of the trigger request fails the trigger shall be 532 reported as "failed" once its activity is complete, or if no further 533 errors will be reported. The "errors" property in the Trigger Status 534 Resource will be used to enumerate which actions failed and the 535 reasons for failure, and may be present while the trigger is still 536 "pending" or "active" if the trigger is still running for some URLs 537 or Patterns in the trigger request. 539 Once a request has been accepted, processing errors are reported in 540 the Trigger Status Resource using a list of "ErrorDesc". Each 541 ErrorDesc is used to report errors against one or more of the URLs or 542 Patterns in the trigger request. 544 If a surrogate affected by a trigger is offline in dCDN, or dCDN is 545 unable to pass a trigger request on to any of its affected dCDNs; 546 dCDN should report an error if the request is abandoned, otherwise it 547 must keep the trigger in state "pending" or "active" until it's acted 548 upon or uCDN chooses to cancel it. Or, if the request is queued and 549 dCDN will not report further status, dCDN may report the trigger as 550 "complete" with an "etime" in the future. 552 Note that an "invalidate" trigger may be reported as "complete" when 553 surrogates that may have the data are offline, if those surrogates 554 will not use the affected data without first revalidating it when 555 they are back online. This does not apply to "preposition" or 556 "purge" triggers. 558 5. Properties of Triggers 560 5.1. Properties of Trigger Requests 562 Properties of Trigger Requests are defined in the following 563 subsections. 565 Property: type 566 Description: This property defines the type of the trigger: 567 Type: TriggerType 568 Mandatory: Yes 570 Property: metadata.urls 571 Description: The uCDN URL for the metadata the trigger applies 572 to. 573 Type: URLs 574 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 575 MUST be present and non-empty. 576 Property: content.urls 577 Description: URLs of content data the trigger applies to, see 578 Section 5.1.1. 579 Type: URLs 580 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 581 MUST be present and non-empty. 582 Property: content.ccid 583 Description: The Content Collection IDentifier of data the 584 trigger applies to. 585 Type: List of strings 586 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 587 MUST be present and non-empty. 588 Property: metadata.patterns 589 Description: The metadata the trigger applies to. 590 Type: List of PatternMatch 591 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 592 MUST be present and non-empty, and metadata.patterns MUST NOT 593 be present if the TriggerType is Preposition. 595 Property: content.patterns 596 Description: The content data the trigger applies to. 597 Type: List of PatternMatch 598 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 599 MUST be present and non-empty, and content.patterns MUST NOT be 600 present if the TriggerType is Preposition. 602 5.1.1. Content URLs 604 To refer to content in dCDN, uCDN must present URLs in the same form 605 clients will use to access content in that dCDN, after transformation 606 to remove any surrogate-specific parts of a 302-redirect URL form. 607 By definition, it is always possible to locate content based on URLs 608 in this form. 610 If content URLs are transformed by an intermediate CDN in a cascade, 611 that intermediate CDN must transform URLs in trigger requests it 612 passes to its dCDN. 614 When processing trigger requests, CDNs SHOULD ignore the URL scheme 615 (http or https) in comparing URLs. For example, for an invalidate or 616 purge trigger, content may invalidated or purged regardless of the 617 protocol clients use to request it. 619 5.2. Properties of Trigger Status Resources 621 Property: trigger 622 Description: The properties of trigger request that created 623 this record. 624 Type: TriggerRequest 625 Mandatory: Yes 627 Property: ctime 628 Description: Time at which the request was received by dCDN. 629 Time is local to dCDN, there is no requirement to synchronise 630 clocks between interconnected CDNs. 631 Type: AbsoluteTime 632 Mandatory: Yes 634 Property: mtime 635 Description: Time at which the resource was last modified. 636 Time is local to dCDN, there is no requirement to synchronise 637 clocks between interconnected CDNs. 638 Type: AbsoluteTime 639 Mandatory: Yes 640 Property: etime 641 Description: Estimate of the time at which dCDN expects to 642 complete the activity. Time is local to dCDN, there is no 643 requirement to synchronise clocks between interconnected CDNs. 644 Type: AbsoluteTime 645 Mandatory: No 647 Property: status 648 Description: Current status of the triggered activity. 649 Type: TriggerStatus 650 Mandatory: Yes 652 Property: errors 653 Description: List of ErrorDesc. 654 Mandatory: No. 656 5.3. Properties of ErrorDesc 658 An ErrorDesc object is used to report failure for URLs and patterns 659 in a trigger request. 660 Property: error 661 Type: ErrorCode. 662 Mandatory: Yes. 663 Property: metadata.urls, content.urls, metadata.patterns, 664 content.patterns 666 Description: Metadata and content references copied from the 667 trigger request. Only those URLs and patterns to which the 668 error applies shall be included in each property, but those 669 URLs and patterns shall be exactly as they appear in the 670 request, dCDN must not generalise the URLs. (For example, if 671 uCDN requests prepositioning of URLs 672 "http://ucdn.example.com/a" and "http://ucdn.example.com/b", 673 dCDN may not generalise its error report to Pattern 674 "http://ucdn.example.com/*"). 675 Mandatory: At least one of these properties is mandatory in 676 each ErrorDesc. 677 Property: description 678 Description: A String containing a human-readable description 679 of the error. 680 Mandatory: No. 682 5.4. Properties of Trigger Collections 684 Property: links 685 Description: References to Trigger Status Resources in the 686 collection. 688 Type: List of Relationships. 689 Mandatory: Yes 690 Property: staleresourcetime 691 Description: The length of time for which dCDN guarantees to 692 keep a completed Trigger Status Resource. After this time, 693 dCDN MAY delete the resource and all references to it from 694 collections. 695 Type: Integer, time in seconds. 696 Mandatory: Yes, in the collection of all Trigger Status 697 Resources if dCDN deletes stale entries. If the property is 698 present in the filtered collections, it MUST have the same 699 value as in the collection of all Trigger Status Resources. 701 5.5. Trigger Resource Simple Data Type Descriptions 703 This section describes the simpler data types that are used for 704 properties of Trigger Status resources. 706 5.5.1. TriggerType 708 This type defines the type of action being triggered, permitted 709 actions are: 710 o Preposition - a request for dCDN to acquire metadata or content. 711 o Invalidate - a request for dCDN to invalidate metadata or content. 712 After servicing this request the dCDN will not use the specified 713 data without first re-validating it using, for example, an "If- 714 None-Match" HTTP request. The dCDN need not erase the associated 715 data. 716 o Purge - a request for dCDN to erase metadata or content. After 717 servicing the request, the specified data must not be held on 718 dCDN. 720 5.5.2. TriggerStatus 722 This type describes the current status of a Trigger, possible values 723 are: 725 o Pending - the trigger has not yet been acted upon. 726 o Active - the trigger is currently being acted upon. 727 o Complete - the triggered activity completed successfully, or the 728 trigger has been accepted and no further status update will be 729 made. 730 o Failed - the triggered activity could not be completed. 732 5.5.3. URLs 734 This type describes a set of references to metadata or content, it is 735 simply a list of absolute URLs. 737 5.5.4. AbsoluteTime 739 Times are expressed in seconds since the UNIX epoch. 741 5.5.5. ErrorCode 743 This type is used by dCDN to report failures in trigger processing. 745 o EMETA - dCDN was unable to acquire metadata required to fulfil the 746 request. 747 o ECONTENT - dCDN was unable to acquire content (preposition 748 triggers only). 749 o EPERM - uCDN does not have permission to trigger the requested 750 activity (for example, the data is owned by another CDN). 751 o EREJECT - dCDN is not willing to fulfil the request (for example, 752 a preposition request for content at a time when dCDN would not 753 accept Request Routing requests from uCDN). 754 o ECDN - An internal error in dCDN or one of its downstream CDNs. 756 6. JSON Encoding of Objects 758 This encoding is based on that described in [I-D.ietf-cdni-metadata], 759 but has been reproduced here while metadata work is in progress. 760 Once that work is complete, the authors would look to align with the 761 structure of the metadata draft and make reference to common 762 definitions as appropriate. 764 The encoding for a CI/T object is a JSON object containing a 765 dictionary of (key,value) pairs where the keys are the property 766 names, and the values are the associated property values. 768 The keys of the dictionary are the names of the properties associated 769 with the object and are therefore dependent on the specific object 770 being encoded (i.e. dependent on the MIME Media Type of the returned 771 resource). Likewise, the values associated with each key are 772 dependent on the specific object being encoded (i.e. dependent on the 773 MIME Media Type of the returned resource). 775 The "trigger" property of the top level JSON object lists the 776 requested action. 778 Key: trigger 779 Description: An object specifying the trigger type and a set of 780 data to act upon. 781 Type: A JSON object. 783 Mandatory: Yes. 785 Object keys in JSON are case sensitive and therefore any dictionary 786 key defined by this document (for example the names of CI/T object 787 properties) MUST always be represented in lowercase. 789 In addition to the properties of an object, the following additional 790 keys may be present. 792 Key: base 793 Description: Provides a prefix for any relative URLs in the 794 object. This is similar to the XML base tag [XML-BASE]. If 795 absent, all URLs in the remainder of the document must be 796 absolute URLs. 797 Type: URI 798 Mandatory: No 800 Key: links 801 Description: The relationships of this object to other 802 addressable objects. 803 Type: Array of Relationships. 804 Mandatory: Yes 806 6.1. JSON Encoding of Embedded Types 808 6.1.1. TriggerType 810 Key: type 811 Description: One of "preposition", "invalidate" or "purge". 812 Type: string 814 6.1.2. TriggerStatus 816 Key: status 817 Description: One of "pending", "active", "failed", "complete" 818 Type: string 820 6.1.3. PatternMatch 822 A PatternMatch is encoded as a JSON Object containing a string to 823 match and flags describing the type of match. 825 Key: pattern 826 Description: A pattern for string matching. The pattern may 827 contain the wildcards * and ?, where * matches any sequence of 828 characters (including the empty string) and ? matches exactly 829 one character. The three literals \ , * and ? should be 830 escaped as \\, \* and \? 831 Type: String 832 Mandatory: Yes 833 Key: case-sensitive 834 Description: Flag indicating whether or not case-sensitive 835 matching should be used. 836 Type: Boolean 837 Mandatory: No, default is case-insensitive match. 838 Key: match-query-string 839 Description: Flag indicating whether or not the query string 840 should be included in the pattern match. 841 Type: Boolean 842 Mandatory: No, default is not to include query. 843 Example of case-sensitive prefix match against 844 "http://www.example.com/trailers/": 845 { 846 "pattern": "http://www.example.com/trailers/*", 847 "case-sensitive": true 848 } 850 6.1.4. ErrorDesc 852 ErrorDesc shall be encoded as a JSON object with the following keys: 854 Key: error 855 Type: ErrorCode 856 Mandatory: Yes 857 Keys: metadata.urls, content.urls 858 Type: Array of strings 859 Mandatory: At least one of metadata.* or content.* must be 860 present. 861 Keys: metadata.patterns, content.patterns 862 Type: Array of PatternMatch 863 Mandatory: At least one of metadata.* or content.* must be 864 present. 865 Key: description 866 Type: String 867 Mandatory: No. 869 6.1.5. ErrorCode 871 One of the strings "EMETA", "ECONTENT", "EPERM", "EREJECT" or "ECDN". 873 6.1.6. Relationship 875 The key "_links" in a dictionary object may be used to define 876 ralationships to other resources. Keys of the "_links" dictionary 877 are link relation types, the value for each relation type can either 878 be a Link Object or an array of Link Objects. 880 The relation type "self" SHOULD be included, with the target being 881 the containing resource. 883 6.1.7. Link Object 885 A Link Object is a JSON dictionary containing the following keys: 887 o "href" - With a value containing the URI of the of the addressable 888 object being referenced. The "href" must be specified. 889 o "type" - The MIME Media Type of the referenced object. It is 890 optional to specify "type". See Section 6.2 for the MIME Media 891 Types of objects specified in this document. 893 6.2. MIME Media Types 895 Table 1 lists the MIME Media Type for the trigger request, and each 896 trigger object (resource) that is retrievable through the CI/T 897 interface. 899 +-------------------+--------------------------------------------+ 900 | Data Object | MIME Media Type | 901 +-------------------+--------------------------------------------+ 902 | TriggerRequest | application/cdni.ci.TriggerRequest+json | 903 | TriggerStatus | application/cdni.ci.TriggerStatus+json | 904 | TriggerCollection | application/cdni.ci.TriggerCollection+json | 905 +-------------------+--------------------------------------------+ 907 Table 1: MIME Media Types for CDNI Trigger resources 909 7. Examples 911 The following sections provide examples of different CI/T objects 912 encoded as JSON. 914 No authentication is shown in the following illustrative examples, it 915 is anticipated that authentication mechanisms will be aligned with 916 other CDNI Interfaces as and when those mechanisms are defined. 918 Discovery of the triggers interface is out of scope of this document. 919 In an implementation, all URLs are under control of dCDN and the uCDN 920 must not attempt to ascribe any meaning to individual elements of the 921 path. In examples in this section, the following URLs are used as 922 the location of the collections of triggers: 924 o Collection of all Triggers belonging to one uCDN: 926 http://dcdn.example.com/triggers 927 o Filtered collections: 928 Pending: http://dcdn.example.com/triggers/pending 929 Active: http://dcdn.example.com/triggers/active 930 Complete: http://dcdn.example.com/triggers/complete 931 Failed: http://dcdn.example.com/triggers/failed 933 7.1. Creating Triggers 935 Examples of uCDN triggering activity in dCDN: 937 7.1.1. Preposition 939 An example of a preposition request, a POST to the "AllTriggers" 940 collection. 942 Note that "metadata.patterns" and "content.patterns" are not allowed 943 in a preposition trigger request. 944 REQUEST: 946 POST /triggers HTTP/1.1 947 User-Agent: example-user-agent/0.1 948 Host: dcdn.example.com 949 Accept: */* 950 Content-Type: application/cdni.ci.TriggerRequest+json 951 Content-Length: 315 953 { 954 "trigger" : { 955 "type": "preposition", 957 "metadata.urls" : [ "http://metadata.example.com/a/b/c" ], 958 "content.urls" : [ 959 "http://www.example.com/a/b/c/1", 960 "http://www.example.com/a/b/c/2", 961 "http://www.example.com/a/b/c/3", 962 "http://www.example.com/a/b/c/4" 963 ] 964 } 965 } 967 RESPONSE: 969 HTTP/1.1 201 Created 970 Date: Mon, 11 Nov 2013 03:28:27 GMT 971 Content-Length: 472 972 Content-Type: application/cdni.ci.TriggerStatus+json 973 Location: http://dcdn.example.com/triggers/0 974 Server: example-server/0.1 976 { 977 "ctime": 1384140507, 978 "etime": 1384140515, 979 "mtime": 1384140507, 980 "status": "pending", 981 "trigger": { 982 "content.urls": [ 983 "http://www.example.com/a/b/c/1", 984 "http://www.example.com/a/b/c/2", 985 "http://www.example.com/a/b/c/3", 986 "http://www.example.com/a/b/c/4" 987 ], 988 "metadata.urls": [ 989 "http://metadata.example.com/a/b/c" 990 ], 991 "type": "preposition" 992 } 993 } 995 7.1.2. Invalidate 997 An example of an invalidate request, another POST to the 998 "AllTriggers" collection. This instructs dCDN to re-validate the 999 content at "http://www.example.com/a/index.html", as well as any 1000 metadata and content whose URLs are prefixed by 1001 "http://metadata.example.com/a/b/" and "http://www.example.com/a/b/" 1002 respectively, using case-insensitive matching. 1003 REQUEST: 1005 POST /triggers HTTP/1.1 1006 User-Agent: example-user-agent/0.1 1007 Host: dcdn.example.com 1008 Accept: */* 1009 Content-Type: application/cdni.ci.TriggerRequest+json 1010 Content-Length: 352 1012 { 1013 "trigger" : { 1014 "type": "invalidate", 1016 "metadata.patterns" : [ 1017 { "pattern" : "http://metadata.example.com/a/b/*" } 1018 ], 1020 "content.urls" : [ "http://www.example.com/a/index.html" ], 1021 "content.patterns" : [ 1022 { "pattern" : "http://www.example.com/a/b/*", 1023 "case-sensitive" : true 1024 } 1025 ] 1026 } 1027 } 1029 RESPONSE: 1031 HTTP/1.1 201 Created 1032 Date: Mon, 11 Nov 2013 03:28:28 GMT 1033 Content-Length: 551 1034 Content-Type: application/cdni.ci.TriggerStatus+json 1035 Location: http://dcdn.example.com/triggers/1 1036 Server: example-server/0.1 1038 { 1039 "ctime": 1384140508, 1040 "etime": 1384140516, 1041 "mtime": 1384140508, 1042 "status": "pending", 1043 "trigger": { 1044 "content.patterns": [ 1045 { 1046 "case-sensitive": true, 1047 "pattern": "http://www.example.com/a/b/*" 1048 } 1049 ], 1050 "content.urls": [ 1051 "http://www.example.com/a/index.html" 1052 ], 1053 "metadata.patterns": [ 1054 { 1055 "pattern": "http://metadata.example.com/a/b/*" 1056 } 1057 ], 1058 "type": "invalidate" 1059 } 1060 } 1062 7.2. Examining Trigger Status 1064 Once triggers have been created, uCDN can check their status as shown 1065 in these examples. 1067 7.2.1. Collection of All Triggers 1069 The uCDN can fetch the set of all the triggers it has created and 1070 which have not yet been deleted or removed as expired. After 1071 creation of the "preposition" and "invalidate" triggers shown above, 1072 this collection might look as follows: 1073 REQUEST: 1075 GET /triggers HTTP/1.1 1076 User-Agent: example-user-agent/0.1 1077 Host: dcdn.example.com 1078 Accept: */* 1080 RESPONSE: 1082 HTTP/1.1 200 OK 1083 Content-Length: 489 1084 Expires: Mon, 11 Nov 2013 03:29:28 GMT 1085 Server: example-server/0.1 1086 ETag: "8477575226503289820" 1087 Cache-Control: max-age=60 1088 Date: Mon, 11 Nov 2013 03:28:28 GMT 1089 Content-Type: application/cdni.ci.TriggerCollection+json 1091 { 1092 "_links": { 1093 "Trigger": [ 1094 { 1095 "href": "http://dcdn.example.com/triggers/0", 1096 "type": "application/cdni.ci.TriggerStatus+json" 1097 }, 1098 { 1099 "href": "http://dcdn.example.com/triggers/1", 1100 "type": "application/cdni.ci.TriggerStatus+json" 1101 } 1102 ], 1103 "self": { 1104 "href": "http://dcdn.example.com/triggers" 1105 } 1106 }, 1107 "staleresourcetime": 86400 1108 } 1110 7.2.2. Filtered Collections of Triggers 1112 The filtered collections are also available to uCDN. Before dCDN 1113 starts processing the two triggers shown above, both will appear in 1114 the collection of Pending Triggers, for example: 1115 REQUEST: 1117 GET /triggers/pending HTTP/1.1 1118 User-Agent: example-user-agent/0.1 1119 Host: dcdn.example.com 1120 Accept: */* 1122 RESPONSE: 1124 HTTP/1.1 200 OK 1125 Content-Length: 497 1126 Expires: Mon, 11 Nov 2013 03:29:28 GMT 1127 Server: example-server/0.1 1128 ETag: "-4197252672546627852" 1129 Cache-Control: max-age=60 1130 Date: Mon, 11 Nov 2013 03:28:28 GMT 1131 Content-Type: application/cdni.ci.TriggerCollection+json 1133 { 1134 "_links": { 1135 "Trigger": [ 1136 { 1137 "href": "http://dcdn.example.com/triggers/0", 1138 "type": "application/cdni.ci.TriggerStatus+json" 1139 }, 1140 { 1141 "href": "http://dcdn.example.com/triggers/1", 1142 "type": "application/cdni.ci.TriggerStatus+json" 1143 } 1144 ], 1145 "self": { 1146 "href": "http://dcdn.example.com/triggers/pending" 1147 } 1148 }, 1149 "staleresourcetime": 86400 1150 } 1152 At this point, if no other triggers had been created, the other 1153 filtered views of the triggers would be empty. For example: 1155 REQUEST: 1157 GET /triggers/complete HTTP/1.1 1158 User-Agent: example-user-agent/0.1 1159 Host: dcdn.example.com 1160 Accept: */* 1162 RESPONSE: 1164 HTTP/1.1 200 OK 1165 Content-Length: 151 1166 Expires: Mon, 11 Nov 2013 03:29:28 GMT 1167 Server: example-server/0.1 1168 ETag: "-3759884165278932652" 1169 Cache-Control: max-age=60 1170 Date: Mon, 11 Nov 2013 03:28:28 GMT 1171 Content-Type: application/cdni.ci.TriggerCollection+json 1173 { 1174 "_links": { 1175 "self": { 1176 "href": "http://dcdn.example.com/triggers/complete" 1177 } 1178 }, 1179 "staleresourcetime": 86400 1180 } 1182 7.2.3. Trigger Status Resources 1184 The Trigger Status Resources can also be examined for detail about 1185 individual triggers. For example, for the "preposition" and 1186 "invalidate" triggers from previous examples: 1188 REQUEST: 1190 GET /triggers/0 HTTP/1.1 1191 User-Agent: example-user-agent/0.1 1192 Host: dcdn.example.com 1193 Accept: */* 1195 RESPONSE: 1197 HTTP/1.1 200 OK 1198 Content-Length: 472 1199 Expires: Mon, 11 Nov 2013 03:29:28 GMT 1200 Server: example-server/0.1 1201 ETag: "4936922742974586536" 1202 Cache-Control: max-age=60 1203 Date: Mon, 11 Nov 2013 03:28:28 GMT 1204 Content-Type: application/cdni.ci.TriggerStatus+json 1206 { 1207 "ctime": 1384140507, 1208 "etime": 1384140515, 1209 "mtime": 1384140507, 1210 "status": "pending", 1211 "trigger": { 1212 "content.urls": [ 1213 "http://www.example.com/a/b/c/1", 1214 "http://www.example.com/a/b/c/2", 1215 "http://www.example.com/a/b/c/3", 1216 "http://www.example.com/a/b/c/4" 1217 ], 1218 "metadata.urls": [ 1219 "http://metadata.example.com/a/b/c" 1220 ], 1221 "type": "preposition" 1222 } 1223 } 1225 REQUEST: 1227 GET /triggers/1 HTTP/1.1 1228 User-Agent: example-user-agent/0.1 1229 Host: dcdn.example.com 1230 Accept: */* 1232 RESPONSE: 1234 HTTP/1.1 200 OK 1235 Content-Length: 551 1236 Expires: Mon, 11 Nov 2013 03:29:28 GMT 1237 Server: example-server/0.1 1238 ETag: "-4441420523993853535" 1239 Cache-Control: max-age=60 1240 Date: Mon, 11 Nov 2013 03:28:28 GMT 1241 Content-Type: application/cdni.ci.TriggerStatus+json 1243 { 1244 "ctime": 1384140508, 1245 "etime": 1384140516, 1246 "mtime": 1384140508, 1247 "status": "pending", 1248 "trigger": { 1249 "content.patterns": [ 1250 { 1251 "case-sensitive": true, 1252 "pattern": "http://www.example.com/a/b/*" 1253 } 1254 ], 1255 "content.urls": [ 1256 "http://www.example.com/a/index.html" 1257 ], 1258 "metadata.patterns": [ 1259 { 1260 "pattern": "http://metadata.example.com/a/b/*" 1261 } 1262 ], 1263 "type": "invalidate" 1264 } 1265 } 1267 7.2.4. Polling for Change 1269 The uCDN may use the Entity Tags of collections or resources when 1270 polling for change in status, as shown in the following examples: 1272 REQUEST: 1274 GET /triggers/pending HTTP/1.1 1275 User-Agent: example-user-agent/0.1 1276 Host: dcdn.example.com 1277 Accept: */* 1278 If-None-Match: "-4197252672546627852" 1280 RESPONSE: 1282 HTTP/1.1 304 Not Modified 1283 Content-Length: 0 1284 Expires: Mon, 11 Nov 2013 03:29:28 GMT 1285 Server: example-server/0.1 1286 ETag: "-4197252672546627852" 1287 Cache-Control: max-age=60 1288 Date: Mon, 11 Nov 2013 03:28:28 GMT 1289 Content-Type: application/cdni.ci.TriggerCollection+json 1290 REQUEST: 1292 GET /triggers/0 HTTP/1.1 1293 User-Agent: example-user-agent/0.1 1294 Host: dcdn.example.com 1295 Accept: */* 1296 If-None-Match: "4936922742974586536" 1298 RESPONSE: 1300 HTTP/1.1 304 Not Modified 1301 Content-Length: 0 1302 Expires: Mon, 11 Nov 2013 03:29:28 GMT 1303 Server: example-server/0.1 1304 ETag: "4936922742974586536" 1305 Cache-Control: max-age=60 1306 Date: Mon, 11 Nov 2013 03:28:28 GMT 1307 Content-Type: application/cdni.ci.TriggerStatus+json 1309 When the triggered activity is complete, the contents of the filtered 1310 collections will be updated, along with their Entity Tags. For 1311 example, when the two example triggers are complete, the collections 1312 of pending and complete triggers may look like: 1314 REQUEST: 1316 GET /triggers/pending HTTP/1.1 1317 User-Agent: example-user-agent/0.1 1318 Host: dcdn.example.com 1319 Accept: */* 1321 RESPONSE: 1323 HTTP/1.1 200 OK 1324 Content-Length: 150 1325 Expires: Mon, 11 Nov 2013 03:29:39 GMT 1326 Server: example-server/0.1 1327 ETag: "-8587750650096537234" 1328 Cache-Control: max-age=60 1329 Date: Mon, 11 Nov 2013 03:28:39 GMT 1330 Content-Type: application/cdni.ci.TriggerCollection+json 1332 { 1333 "_links": { 1334 "self": { 1335 "href": "http://dcdn.example.com/triggers/pending" 1336 } 1337 }, 1338 "staleresourcetime": 86400 1339 } 1341 REQUEST: 1343 GET /triggers/complete HTTP/1.1 1344 User-Agent: example-user-agent/0.1 1345 Host: dcdn.example.com 1346 Accept: */* 1348 RESPONSE: 1350 HTTP/1.1 200 OK 1351 Content-Length: 498 1352 Expires: Mon, 11 Nov 2013 03:29:39 GMT 1353 Server: example-server/0.1 1354 ETag: "2680225545549998872" 1355 Cache-Control: max-age=60 1356 Date: Mon, 11 Nov 2013 03:28:39 GMT 1357 Content-Type: application/cdni.ci.TriggerCollection+json 1359 { 1360 "_links": { 1361 "Trigger": [ 1362 { 1363 "href": "http://dcdn.example.com/triggers/0", 1364 "type": "application/cdni.ci.TriggerStatus+json" 1365 }, 1366 { 1367 "href": "http://dcdn.example.com/triggers/1", 1368 "type": "application/cdni.ci.TriggerStatus+json" 1369 } 1370 ], 1371 "self": { 1372 "href": "http://dcdn.example.com/triggers/complete" 1373 } 1374 }, 1375 "staleresourcetime": 86400 1376 } 1378 7.2.5. Cancelling or Removing a Trigger 1380 To request dCDN to cancel a Trigger, uCDN may delete the Trigger 1381 Resource. It may also delete completed and failed triggers to reduce 1382 the size of the collections. For example, to remove the 1383 "preposition" request from earlier examples: 1385 REQUEST: 1387 DELETE /triggers/0 HTTP/1.1 1388 User-Agent: example-user-agent/0.1 1389 Host: dcdn.example.com 1390 Accept: */* 1392 RESPONSE: 1394 HTTP/1.1 204 No Content 1395 Date: Mon, 11 Nov 2013 03:28:39 GMT 1396 Content-Length: 0 1397 Content-Type: text/html; charset=UTF-8 1398 Server: example-server/0.1 1400 This would, for example, cause the collection of completed triggers 1401 shown in the example above to be updated to: 1403 REQUEST: 1405 GET /triggers/complete HTTP/1.1 1406 User-Agent: example-user-agent/0.1 1407 Host: dcdn.example.com 1408 Accept: */* 1410 RESPONSE: 1412 HTTP/1.1 200 OK 1413 Content-Length: 304 1414 Expires: Mon, 11 Nov 2013 03:29:39 GMT 1415 Server: example-server/0.1 1416 ETag: "535044172999094664" 1417 Cache-Control: max-age=60 1418 Date: Mon, 11 Nov 2013 03:28:39 GMT 1419 Content-Type: application/cdni.ci.TriggerCollection+json 1421 { 1422 "_links": { 1423 "Trigger": { 1424 "href": "http://dcdn.example.com/triggers/1", 1425 "type": "application/cdni.ci.TriggerStatus+json" 1426 }, 1427 "self": { 1428 "href": "http://dcdn.example.com/triggers/complete" 1429 } 1430 }, 1431 "staleresourcetime": 86400 1432 } 1434 7.2.6. Error Reporting 1436 In this example uCDN has requested prepositioning of 1437 "http://newsite.example.com/index.html", but dCDN was unable to 1438 locate metadata for that site: 1440 REQUEST: 1442 GET /triggers/2 HTTP/1.1 1443 User-Agent: example-user-agent/0.1 1444 Host: dcdn.example.com 1445 Accept: */* 1447 RESPONSE: 1449 HTTP/1.1 200 OK 1450 Content-Length: 505 1451 Expires: Mon, 11 Nov 2013 03:29:43 GMT 1452 Server: example-server/0.1 1453 ETag: "3841389629056746224" 1454 Cache-Control: max-age=60 1455 Date: Mon, 11 Nov 2013 03:28:43 GMT 1456 Content-Type: application/cdni.ci.TriggerStatus+json 1458 { 1459 "ctime": 1384140519, 1460 "errors": [ 1461 { 1462 "content.urls": [ 1463 "http://newsite.example.com/index.html" 1464 ], 1465 "description": 1466 "No HostIndex entry found for newsite.example.com", 1467 "error": "EMETA" 1468 } 1469 ], 1470 "etime": 1384140527, 1471 "mtime": 1384140523, 1472 "status": "active", 1473 "trigger": { 1474 "content.urls": [ 1475 "http://newsite.example.com/index.html" 1476 ], 1477 "type": "preposition" 1478 } 1479 } 1481 8. IANA Considerations 1482 8.1. CI/T MIME Media Types 1484 The IANA is requested to allocate the following MIME Media Types in 1485 the MIME Media Types registry: 1487 o application/cdni.ci.TriggerRequest 1488 o application/cdni.ci.TriggerStatus 1489 o application/cdni.ci.TriggerCollection 1490 Use of these types is specified in Section 6.2 of the present 1491 document. 1493 9. Security Considerations 1495 The dCDN must ensure that each uCDN only has access to its own 1496 Trigger Status Resources. 1498 It is anticipated that a common authentication mechanism will be used 1499 by this and other CDNI Interconnect interfaces, the mechanism must 1500 exist but is not identified in this document. 1502 The dCDN must ensure that activity triggered by uCDN only affects 1503 metadata or content originating from that uCDN. 1505 10. Acknowledgements 1507 The structure of the Relationship and Link Objects specified in 1508 Section 6 is based on Mike Kelly's work on JSON Hypertext Application 1509 Language. 1511 11. References 1513 11.1. Normative References 1515 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1516 Requirement Levels", BCP 14, RFC 2119, March 1997. 1518 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1519 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1520 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1522 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1523 Resource Identifier (URI): Generic Syntax", STD 66, 1524 RFC 3986, January 2005. 1526 11.2. Informative References 1528 [I-D.ietf-cdni-framework] 1529 Peterson, L. and B. Davie, "Framework for CDN 1530 Interconnection", draft-ietf-cdni-framework-07 (work in 1531 progress), November 2013. 1533 [I-D.ietf-cdni-metadata] 1534 Niven-Jenkins, B., Murray, R., Watson, G., Caulfield, M., 1535 Leung, K., and K. Ma, "CDN Interconnect Metadata", 1536 draft-ietf-cdni-metadata-03 (work in progress), 1537 October 2013. 1539 [I-D.ietf-cdni-requirements] 1540 Leung, K. and Y. Lee, "Content Distribution Network 1541 Interconnection (CDNI) Requirements", 1542 draft-ietf-cdni-requirements-13 (work in progress), 1543 November 2013. 1545 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1546 Syndication Format", RFC 4287, December 2005. 1548 [RFC6707] Niven-Jenkins, B., Le Faucheur, F., and N. Bitar, "Content 1549 Distribution Network Interconnection (CDNI) Problem 1550 Statement", RFC 6707, September 2012. 1552 [XML-BASE] 1553 Marsh, J., Ed. and R. Tobin, Ed., "XML Base (Second 1554 Edition) - http://www.w3.org/TR/xmlbase/", January 2009. 1556 Authors' Addresses 1558 Rob Murray 1559 Velocix (Alcatel-Lucent) 1560 3 Ely Road 1561 Milton, Cambridge CB24 6DD 1562 UK 1564 Email: rmurray@velocix.com 1565 Ben Niven-Jenkins 1566 Velocix (Alcatel-Lucent) 1567 3 Ely Road 1568 Milton, Cambridge CB24 6DD 1569 UK 1571 Email: ben@velocix.com