idnits 2.17.1 draft-murray-cdni-triggers-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 3, 2013) is 4012 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 148, but not defined == Missing Reference: 'MED' is mentioned on line 154, but not defined == Unused Reference: 'RFC3986' is defined on line 1510, 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-03 == Outdated reference: A later version (-21) exists of draft-ietf-cdni-metadata-01 == Outdated reference: A later version (-17) exists of draft-ietf-cdni-requirements-05 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: October 5, 2013 April 3, 2013 7 CDNI Control Interface / Triggers 8 draft-murray-cdni-triggers-03 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 October 5, 2013. 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 . . . . . . . . . . . . . . . . . . . . 10 68 4.2. Checking Status . . . . . . . . . . . . . . . . . . . . . 11 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 . . . . . . . . . . . . 16 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 . . . . . . . . . . . . . . . . . . . . . . . . . 17 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 . . . . . . . . . . . . . . . . . . . . . 19 91 6.1.4. ErrorDesc . . . . . . . . . . . . . . . . . . . . . . 19 92 6.1.5. ErrorCode . . . . . . . . . . . . . . . . . . . . . . 20 93 6.1.6. Relationship . . . . . . . . . . . . . . . . . . . . . 20 94 6.2. MIME Media Types . . . . . . . . . . . . . . . . . . . . . 20 95 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 96 7.1. Creating Triggers . . . . . . . . . . . . . . . . . . . . 21 97 7.1.1. Preposition . . . . . . . . . . . . . . . . . . . . . 21 98 7.1.2. Invalidate . . . . . . . . . . . . . . . . . . . . . . 23 99 7.2. Examining Trigger Status . . . . . . . . . . . . . . . . . 24 100 7.2.1. Collection of All Triggers . . . . . . . . . . . . . . 24 101 7.2.2. Filtered Collections of Triggers . . . . . . . . . . . 25 102 7.2.3. Trigger Status Resources . . . . . . . . . . . . . . . 27 103 7.2.4. Polling for Change . . . . . . . . . . . . . . . . . . 29 104 7.2.5. Cancelling or Removing a Trigger . . . . . . . . . . . 32 105 7.2.6. Error Reporting . . . . . . . . . . . . . . . . . . . 34 106 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 107 9. Security Considerations . . . . . . . . . . . . . . . . . . . 35 108 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 35 109 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 35 110 11.1. Normative References . . . . . . . . . . . . . . . . . . . 35 111 11.2. Informative References . . . . . . . . . . . . . . . . . . 35 112 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 36 114 1. Introduction 116 [RFC6707] introduces the Problem scope for CDN Interconnection (CDNI) 117 and lists the four categories of interfaces that may be used to 118 compose a CDNI solution (Control, Metadata, Request Routing, 119 Logging). 121 [I-D.ietf-cdni-framework] expands on the information provided in 122 [RFC6707] and describes each of the interfaces and the relationships 123 between them in more detail. 125 This draft concentrates on the "High" and "Medium" priority 126 requirements for the CDNI Control Interface identified in section 4 127 of [I-D.ietf-cdni-requirements], reproduced here for convenience: 129 CNTL-1 [HIGH] The CDNI Control interface shall allow the Upstream 130 CDN to request that the Downstream CDN (and, if cascaded CDNs are 131 supported by the solution, that the potential cascaded Downstream 132 CDNs) perform the following actions on an object or object set: 134 * Mark an object or set of objects and/or its CDNI metadata as 135 "stale" and revalidate them before they are delivered again 136 * Delete an object or set of objects and/or its CDNI metadata 137 from the CDN surrogates and any storage. Only the object(s) 138 and CDNI metadata that pertain to the requesting Upstream CDN 139 are allowed to be purged. 140 CNTL-2 [HIGH] The CDNI Control interface shall allow the 141 Downstream CDN to report on the completion of these actions (by 142 itself, and if cascaded CDNs are supported by the solution, by 143 potential cascaded Downstream CDNs), in a manner appropriate for 144 the action (e.g. synchronously or asynchronously). The 145 confirmation receipt should include a success or failure 146 indication. The failure indication is used if the Downstream CDN 147 cannot delete the content in its storage. 148 CNTL-3 [HIGH] The CDNI Control interface shall support initiation 149 and control by the Upstream CDN of pre-positioned CDNI metadata 150 acquisition by the Downstream CDN. 151 CNTL-4 [MED] The CDNI Control interface should support initiation 152 and control by the Upstream CDN of pre-positioned content 153 acquisition by the Downstream CDN. 154 CNTL-12 [MED] The CDNI Control interface should allow for multiple 155 content items identified by a Content Collection ID to be purged 156 using a single Content Purge action. 158 This document describes the CI/T interface, Control Interface / 159 Triggers. It does not consider those parts of the control interface 160 that relate to configuration, bootstrapping or authentication of CDN 161 Interconnect interfaces. 163 o Section 2 outlines the model for the Trigger Interface at a high 164 level. 165 o Section 3 describes collections of Trigger Resources. 166 o Section 4 defines the RESTful web service provided by dCDN. 167 o Section 5 lists properties of Trigger Requests and Status 168 Resources. 169 o Section 6 defines a JSON encoding for Trigger Requests and Status 170 Resources. 171 o Section 7 contains example messages. 173 1.1. Terminology 175 This document reuses the terminology defined in [RFC6707]. 177 2. Model for CDNI Triggers 179 A trigger, sent from uCDN to dCDN, is a request for dCDN to do some 180 work relating to data originating from uCDN. 182 The trigger may request action on either metadata or content, the 183 following actions can be requested: 185 o preposition - used to instruct dCDN to fetch metadata from uCDN, 186 or content from any origin including uCDN. 187 o invalidate - used to instruct dCDN to revalidate specific metadata 188 or content before re-using it. 189 o purge - used to instruct dCDN to delete specific metadata or 190 content. 192 The CI/T interface is a RESTful web service offered by dCDN. It 193 allows creation and deletion of triggers, and tracking of the 194 triggered activity. When dCDN accepts a trigger it creates a 195 resource describing status of the triggered activity, a Trigger 196 Status Resource. The uCDN may poll Trigger Status Resources to 197 monitor progress. 199 Requests to invalidate and purge metadata or content apply to all 200 variants of that data with a given URI. 202 The dCDN maintains a collection of Trigger Status Resources for each 203 uCDN, each uCDN only has access to its own collection and the 204 location of that collection is shared when CDN interconnection is 205 established. 207 To trigger activity in dCDN, uCDN will POST to the collection of 208 Trigger Status Resources. If dCDN accepts the trigger, it creates a 209 new Trigger Status Resource and returns its location to uCDN. To 210 monitor progress, uCDN may GET the Trigger Status Resource. To 211 cancel a trigger, or remove a trigger from the collection once its 212 activity has been completed, uCDN may DELETE the Trigger Status 213 Resource. 215 In addition to the collection of all Trigger Status Resources for 216 uCDN, uCDN shall have access to filtered views of that collection. 217 These filtered views are defined in Section 3 and include collections 218 of active and completed triggers. These collections provide a 219 mechanism for polling the status of multiple jobs. 221 Figure 1 is an example showing the basic message flow used by the 222 uCDN to trigger activity in dCDN, and for uCDN to discover the status 223 of that activity. Only successful triggering is shown. Examples of 224 the messages are given in Section 7. 225 uCDN dCDN 226 | (1) POST http://dcdn.example.com/triggers/uCDN | 227 [ ] --------------------------------------------------> [ ]--+ 228 | [ ] | (2) 229 | (3) HTTP 201 Response [ ]<-+ 230 [ ] <-------------------------------------------------- [ ] 231 | Loc: http://dcdn.example.com/triggers/uCDN/123 | 232 | | 233 . . . 234 . . . 235 . . . 236 | | 237 | (4) GET http://dcdn.example.com/triggers/uCDN/123 | 238 [ ] --------------------------------------------------> [ ] 239 | [ ] 240 | (5) HTTP 200 Trigger Status Resource [ ] 241 [ ] <-------------------------------------------------- [ ] 242 | | 243 | | 245 Figure 1: Basic CDNI Message Flow for Triggers 247 The steps in Figure 1 are: 249 1. uCDN triggers action in dCDN by posting to a collection of 250 Trigger Status Resources, 251 "http://dcdn.example.com/triggers/uCDN". The URL of this was 252 given to uCDN when the trigger interface was established. 253 2. dCDN authenticates the request, validates the trigger and if it 254 accepts the request, creates a new Trigger Status Resource. 255 3. dCDN responds to uCDN with an HTTP 201 response status, and the 256 location of the Trigger Status Resource. 258 4. uCDN may repeatedly poll the Trigger Status Resource in dCDN. 259 5. dCDN responds with the Trigger Status Resource, describing 260 progress or results of the triggered activity. 262 The remainder of this document describes the messages, Trigger Status 263 Resources, and collections of Trigger Status Resources in more 264 detail. 266 2.1. Timing of Triggered Activity 268 Timing of triggered activity is under dCDN control, including its 269 start-time and pacing of the activity in the network. 271 Invalidate and purge triggers MUST be applied to all data acquired 272 before the trigger was created in dCDN. The dCDN MAY apply the 273 triggers to data acquired after trigger creation. 275 If uCDN wishes to invalidate or purge content, then immediately 276 preposition replacement content at the same URLs, it must ensure the 277 dCDN has completed the invalidate/purge before initiating the 278 prepositioning. If it fails to do that and the requests overlap, and 279 dCDN passes the triggers on to a further dCDN in a cascade, that CDN 280 may preposition content that has not yet been invalidated/purged in 281 its uCDN. 283 2.2. Trigger Results 285 Each Trigger Request may operate on multiple data items. The trigger 286 shall be reported as "complete" only if all actions can be completed 287 successfully, otherwise it shall be reported as "failed". The 288 reasons for failure and URLs or Patterns affected shall be enumerated 289 in the Trigger Status Resource. For more detail, see section 290 Section 4.5. 292 If a dCDN is also acting as uCDN in a cascade, it MUST forward 293 triggers to any downstream CDNs that may have data affected by the 294 trigger. The trigger MUST NOT be reported as complete in a CDN until 295 it is complete in all of its downstream CDNs. A trigger MAY be 296 reported as failed as soon as it fails in a CDN or in any of its 297 downstream CDNs. 299 3. Collections of Trigger Status Resources 301 As described in Section 2, Trigger Status Resources exist in dCDN to 302 report the status of activity triggered by each uCDN. 304 A collection of Trigger Status Resources is a resource that contains 305 a reference to each Trigger Status Resource in that collection. 307 To trigger activity in dCDN, uCDN creates a new Trigger Status 308 Resource by posting to dCDN's collection of uCDN's Trigger Status 309 Resources. The URL of each Trigger Status Resource is generated by 310 the dCDN when it accepts the trigger, and returned to uCDN. This 311 immediately enables uCDN to check the status of that trigger. 313 The dCDN must present a different set of Trigger Status Resources to 314 each interconnected uCDN, only Trigger Status Resources belonging to 315 a uCDN shall be visible to it. The dCDN may, for example, achieve 316 this by offering different collection URLs to uCDNs, or by filtering 317 the response based on the client uCDN. 319 The dCDN resource representing the collection of all uCDN's Trigger 320 Status Resources is accessible to uCDN. This collection lists all 321 uCDN triggers that have been accepted by dCDN, and have not yet been 322 deleted by uCDN or expired and removed by dCDN. 324 In order to allow uCDN to check status of multiple jobs in a single 325 request, dCDN shall also maintain collections representing filtered 326 views of the collection of all Trigger Status Resources. The 327 filtered collections are: 328 o Pending - Trigger Status Resources for triggers that have been 329 accepted, but not yet acted upon. 330 o Active - Trigger Status Resources for triggered activity that is 331 currently being processed in dCDN. 332 o Complete - Trigger Status Resources representing activity that 333 completed successfully. 334 o Failed - Trigger Status Resources representing activity that 335 failed. 337 4. CDNI Trigger interface 339 This section describes an interface to enable an upstream CDN to 340 trigger defined activities in a downstream CDN. The interface is 341 intended to be independent of the set of activities defined now, or 342 that may be defined in future. 344 The CI/T interface is built on the principles of RESTful web 345 services. Requests are made over HTTP, and the HTTP Method defines 346 the operation the request would like to perform. The corresponding 347 HTTP Response returns the status of the operation in the HTTP Status 348 Code and returns the current representation of the resource (if 349 appropriate) in the Response Body. HTTP Responses from servers 350 implementing the CI/T interface that contain a response body SHOULD 351 include an ETag to enable validation of cached versions of returned 352 resources. 354 Servers implementing the CI/T interface MUST support the HTTP GET, 355 HEAD, POST and DELETE methods. The only representation specified in 356 this document 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 [Editor's note: It is anticipated that decisions on use of HTTPS for 388 other CDNI interfaces will be adopted for Triggers.] 390 Discovery of the CI/T Interface is outside the scope of this 391 document. It is anticipated that a common mechanism for discovery of 392 all CDNI interfaces will be defined. 394 The dCDN must ensure that activity triggered by uCDN only affects 395 metadata or content originating from that uCDN. Since only one CDN 396 can be authoritative for a given item of metadata or content, this 397 requirement means there cannot be any "loops" in trigger requests 398 between CDNs. 400 4.1. Creating Triggers 402 To create a new trigger, uCDN makes an HTTP POST to the unfiltered 403 collection of its triggers. The request body of that POST is a 404 Trigger Request. 406 dCDN validates and authenticates that request, if it is malformed or 407 uCDN does not have sufficient access rights it MAY reject the request 408 immediately. In this case, it SHALL respond with an appropriate 4xx 409 HTTP error code and no resource shall be created on dCDN. 411 If the request is accepted, uCDN SHALL create a new Trigger Status 412 Resource. The HTTP response to dCDN SHALL have status code 201 and 413 the URI of the Trigger Status Resource in the Location header field. 414 The HTTP response MAY include the content of the newly created 415 Trigger Status Resource, this is recommended particularly in cases 416 where the trigger has completed immediately. 418 Once a Trigger Status Resource has been created dCDN MUST NOT re-use 419 its location, even after that resource has been removed through 420 deletion or expiry. 422 The "request" property of the Trigger Status Resource SHALL contain 423 the information posted in the body of the Trigger Request. Note that 424 this need not be a byte-for-byte copy. For example, in the JSON 425 representation the dCDN may re-serialise the information differently. 427 If the trigger is queued by dCDN for later action, the "status" 428 property of the Trigger Status Resource SHALL be "pending". Once 429 trigger processing has started the "status" SHALL be "active". 431 A trigger may result in no activity in dCDN if, for example, it is an 432 invalidate or purge request for data the dCDN has not acquired, or a 433 prepopulate request for data it has already acquired. In this case, 434 the "status" of the Trigger Status Resource shall be "complete" and 435 the Trigger Status Resource shall be added to the dCDN collection of 436 Complete Triggers. 438 If dCDN is not able to track triggered activity, it MAY indicate that 439 it has undertaken to complete the activity but will not report 440 completion or any further errors. To do this, it must set the 441 trigger status to "complete", with an estimated completion time in 442 the future ("etime" greater than "mtime"). 444 Once created, Trigger Status Resources may be deleted by uCDN but not 445 modified. The dCDN MUST reject PUT and POST requests from uCDN to 446 Trigger Status Resources using HTTP status code 403. 448 4.2. Checking Status 450 The uCDN has two ways to check progress of activity it has triggered 451 in dCDN, described in the following sections. 453 Because the triggers protocol is based on HTTP, Entity Tags may be 454 used by the uCDN as cache validators, as defined in section 3.11 of 455 [RFC2616], to check for change in status of a resource or collection 456 of resources without re-fetching the whole resource or collection. 458 The dCDN should use the cache control headers for responses to GETs 459 for Trigger Status Resources and Collections to indicate the 460 frequency at which it recommends uCDN should poll for change. 462 4.2.1. Polling Trigger Status Resource collections 464 uCDN can fetch the collection of its Trigger Status Resources, or 465 filtered views of that collection. 467 This makes it possible to poll status of all triggered activity in a 468 single request. If dCDN moves a Trigger Status Resource from the 469 Active to the Completed collection, uCDN may chose to fetch the 470 result of that activity. 472 When polling in this way, uCDN may choose to use HTTP Entity Tags to 473 monitor for change, rather than repeatedly fetching the whole 474 collection. 476 4.2.2. Polling Trigger Status Resources 478 uCDN has a reference (URI provided by the dCDN) for each Trigger 479 Status Resource it has created, it may fetch that resource at any 480 time. 482 This may be used to retrieve progress information, and to fetch the 483 result of triggered activity. 485 4.3. Deleting Triggers 487 The uCDN MAY delete Trigger Status Resources at any time, using the 488 HTTP DELETE method. 490 Once deleted, the references to a Trigger Status Resource MUST be 491 removed from all Trigger Status Resource collections. Subsequent 492 requests for the resource shall be handled as required by HTTP, and 493 so will receive responses with status 404 or 410. 495 If a "pending" Trigger Status Resource is deleted, dCDN SHOULD NOT 496 start processing of that activity. Deleting a "pending" trigger does 497 not however guarantee that it is not started because, once it has 498 triggered activity, uCDN cannot control the timing of that activity. 499 Processing may, for example, start after the DELETE is sent by uCDN 500 and before the DELETE is processed by dCDN. 502 If an "active" Trigger Status Resource is deleted, dCDN MAY stop 503 processing the triggered activity. However, as with deletion of a 504 "pending" trigger, dCDN does not guarantee this. 506 Deletion of a "complete" or "failed" Trigger Status Resource requires 507 no processing in dCDN other than deletion of the resource. 509 4.4. Expiry of Trigger Status Resources 511 The dCDN MAY choose to automatically delete Trigger Status Resources 512 some time after they become completed or failed. In this case, dCDN 513 will remove the resource and respond to subsequent requests for it 514 with HTTP status 404 or 410. 516 If dCDN performs this housekeeping, it MUST have reported the length 517 of time after which completed Trigger Status Resources become stale 518 via a property of the collection of all Trigger Status Resources. It 519 is recommended that Trigger Status Resources are automatically 520 deleted 24 hours after they become completed or failed. 522 To ensure it has access to the status of its completed and failed 523 triggers, it is recommended that uCDN's polling interval is half the 524 time after which records for completed activity will be considered 525 stale. 527 4.5. Error Handling 529 A CI/T server may reject a trigger request using HTTP status codes, 530 for example 400 if the request is malformed or 401 if the client does 531 not have permission to create triggers or it is trying to act on 532 another CDN's data. 534 If any part of the trigger request fails the trigger shall be 535 reported as "failed" once its activity is complete, or if no further 536 errors will be reported. The "errors" property in the Trigger Status 537 Resource will be used to enumerate which actions failed and the 538 reasons for failure, and may be present while the trigger is still 539 "pending" or "active" if the trigger is still running for some URLs 540 or Patterns in the trigger request. 542 Once a request has been accepted, processing errors are reported in 543 the Trigger Status Resource using a list of "ErrorDesc". Each 544 ErrorDesc is used to report errors against one or more of the URLs or 545 Patterns in the trigger request. 547 If a surrogate affected by a trigger is offline in dCDN, or dCDN is 548 unable to pass a trigger request on to any of its affected dCDNs; 549 dCDN should report an error if the request is abandoned, otherwise it 550 must keep the trigger in state "pending" or "active" until it's acted 551 upon or uCDN chooses to cancel it. Or, if the request is queued and 552 dCDN will not report further status, dCDN may report the trigger as 553 "complete" with an "etime" in the future. 555 Note that an "invalidate" trigger may be reported as "complete" when 556 surrogates that may have the data are offline, if those surrogates 557 will not use the affected data without first revalidating it when 558 they are back online. This does not apply to "preposition" or 559 "purge" triggers. 561 5. Properties of Triggers 563 5.1. Properties of Trigger Requests 565 Properties of Trigger Requests are defined in the following 566 subsections. 568 Property: type 569 Description: This property defines the type of the trigger: 570 Type: TriggerType 571 Mandatory: Yes 573 Property: metadata.urls 574 Description: The uCDN URL for the metadata the trigger applies 575 to. 576 Type: URLs 577 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 578 MUST be present and non-empty. 579 Property: content.urls 580 Description: URLs of content data the trigger applies to, see 581 Section 5.1.1. 582 Type: URLs 583 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 584 MUST be present and non-empty. 585 Property: content.ccid 586 Description: The Content Collection IDentifier of data the 587 trigger applies to. 588 Type: List of strings 589 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 590 MUST be present and non-empty. 591 Property: metadata.patterns 592 Description: The metadata the trigger applies to. 593 Type: List of PatternMatch 594 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 595 MUST be present and non-empty, and metadata.patterns MUST NOT 596 be present if the TriggerType is Preposition. 597 Property: content.patterns 598 Description: The content data the trigger applies to. 599 Type: List of PatternMatch 600 Mandatory: No, but at least one of 'metadata.*' or 'content.*' 601 MUST be present and non-empty, and content.patterns MUST NOT be 602 present if the TriggerType is Preposition. 604 5.1.1. Content URLs 606 To refer to content in dCDN, uCDN must present URLs in the same form 607 clients will use to access content in that dCDN, after transformation 608 to remove any surrogate-specific parts of a 302-redirect URL form. 609 By definition, it is always possible to locate content based on URLs 610 in this form. 612 If content URLs are transformed by an intermediate CDN in a cascade, 613 that intermediate CDN must transform URLs in trigger requests it 614 passes to its dCDN. 616 [Editor's note: Design for CDNI Metadata transformation, including 617 discussion of URL transformation, is being undertaken as part of the 618 work on the metadata interface. The intention is to align with that 619 document or make reference to it when it's complete.] 621 When processing trigger requests, CDNs may ignore the URL scheme 622 (http or https) in comparing URLs. For example, for an invalidate or 623 purge trigger, content may invalidated or purged regardless of the 624 protocol clients use to request it. 626 5.2. Properties of Trigger Status Resources 628 Property: trigger 629 Description: The properties of trigger request that created 630 this record. 631 Type: TriggerRequest 632 Mandatory: Yes 634 Property: ctime 635 Description: Time at which the request was received by dCDN. 636 Time is local to dCDN, there is no requirement to synchronise 637 clocks between interconnected CDNs. 638 Type: AbsoluteTime 639 Mandatory: Yes 641 Property: mtime 642 Description: Time at which the resource was last modified. 643 Time is local to dCDN, there is no requirement to synchronise 644 clocks between interconnected CDNs. 645 Type: AbsoluteTime 646 Mandatory: Yes 647 Property: etime 648 Description: Estimate of the time at which dCDN expects to 649 complete the activity. Time is local to dCDN, there is no 650 requirement to synchronise clocks between interconnected CDNs. 651 Type: AbsoluteTime 652 Mandatory: No 654 Property: status 655 Description: Current status of the triggered activity. 656 Type: TriggerStatus 657 Mandatory: Yes 659 Property: errors 660 Description: List of ErrorDesc. 661 Mandatory: No. 663 5.3. Properties of ErrorDesc 665 An ErrorDesc object is used to report failure for URLs and patterns 666 in a trigger request. 667 Property: error 668 Type: ErrorCode. 669 Mandatory: Yes. 670 Description: List of metadata.urls, content.urls, 671 metadata.patterns, content.patterns 673 Description: Metadata and content references copied from the 674 trigger request. Only those URLs and patterns to which the 675 error applies shall be included in each property, but those 676 URLs and patterns shall be exactly as they appear in the 677 request, dCDN must not generalise the URLs. (For example, if 678 uCDN requests prepositioning of URLs 679 "http://ucdn.example.com/a" and "http://ucdn.example.com/b", 680 dCDN may not generalise its error report to Pattern 681 "http://ucdn.example.com/*"). 683 Mandatory: At least one of these properties is mandatory in 684 each ErrorDesc. 685 Property: description 686 Description: A String containing a human-readable description 687 of the error. 688 Mandatory: No. 690 5.4. Properties of Trigger Collections 692 Property: links 693 Description: References to Trigger Status Resources in the 694 collection. 695 Type: List of Relationships. 696 Mandatory: Yes 697 Property: staleresourcetime 698 Description: The length of time for which dCDN guarantees to 699 keep a completed Trigger Status Resource. After this time, 700 dCDN MAY delete the resource and all references to it from 701 collections. 702 Type: Integer, time in seconds. 703 Mandatory: Yes, in the collection of all Trigger Status 704 Resources if dCDN deletes stale entries. If the property is 705 present in the filtered collections, it MUST have the same 706 value as in the collection of all Trigger Status Resources. 708 5.5. Trigger Resource Simple Data Type Descriptions 710 This section describes the simpler data types that are used for 711 properties of Trigger Status resources. 713 5.5.1. TriggerType 715 This type defines the type of action being triggered, permitted 716 actions are: 717 o Preposition - a request for dCDN to acquire metadata or content. 718 o Invalidate - a request for dCDN to invalidate metadata or content. 719 After servicing this request the dCDN will not use the specified 720 data without first re-validating it using, for example, an "If- 721 None-Match" HTTP request. The dCDN need not erase the associated 722 data. 723 o Purge - a request for dCDN to erase metadata or content. After 724 servicing the request, the specified data must not be held on 725 dCDN. 727 5.5.2. TriggerStatus 729 This type describes the current status of a Trigger, possible values 730 are: 732 o Pending - the trigger has not yet been acted upon. 733 o Active - the trigger is currently being acted upon. 734 o Complete - the triggered activity completed successfully, or the 735 trigger has been accepted and no further status update will be 736 made. 737 o Failed - the triggered activity could not be completed. 739 5.5.3. URLs 741 This type describes a set of references to metadata or content, it is 742 simply a list of absolute URLs. 744 5.5.4. AbsoluteTime 746 Times are expressed in seconds since the UNIX epoch. 748 5.5.5. ErrorCode 750 This type is used by dCDN to report failures in trigger processing. 752 o EMETA - dCDN was unable to acquire metadata required to fulfil the 753 request. 754 o ECONTENT - dCDN was unable to acquire content (preposition 755 triggers only). 756 o EPERM - uCDN does not have permission to trigger the requested 757 activity (for example, the data is owned by another CDN). 758 o EREJECT - dCDN is not willing to fulfil the request (for example, 759 a preposition request for content at a time when dCDN would not 760 accept Request Routing requests from uCDN). 761 o ECDN - An internal error in dCDN or one of its downstream CDNs. 763 6. JSON Encoding of Objects 765 This encoding is based on that described in [I-D.ietf-cdni-metadata], 766 but has been reproduced here while metadata work is in progress. 767 Once that work is complete, the authors would look to align with the 768 structure of the metadata draft and make reference to common 769 definitions as appropriate. 771 The encoding for a CI/T object is a JSON object containing a 772 dictionary of (key,value) pairs where the keys are the property 773 names, and the values are the associated property values. 775 The keys of the dictionary are the names of the properties associated 776 with the object and are therefore dependent on the specific object 777 being encoded (i.e. dependent on the MIME Media Type of the returned 778 resource). Likewise, the values associated with each key are 779 dependent on the specific object being encoded (i.e. dependent on the 780 MIME Media Type of the returned resource). 782 The "trigger" property of the top level JSON object lists the 783 requested action. 785 Key: trigger 786 Description: An object specifying the trigger type and a set of 787 data to act upon. 788 Type: A JSON object. 789 Mandatory: Yes. 791 Object keys in JSON are case sensitive and therefore any dictionary 792 key defined by this document (for example the names of CI/T object 793 properties) MUST always be represented in lowercase. 795 In addition to the properties of an object, the following additional 796 keys may be present. 798 Key: base 799 Description: Provides a prefix for any relative URLs in the 800 object. This is similar to the XML base tag [XML-BASE]. If 801 absent, all URLs in the remainder of the document must be 802 absolute URLs. 803 Type: URI 804 Mandatory: No 806 Key: links 807 Description: The relationships of this object to other 808 addressable objects. 809 Type: Array of Relationships. 810 Mandatory: Yes 812 6.1. JSON Encoding of Embedded Types 814 6.1.1. TriggerType 816 Key: type 817 Description: One of "preposition", "invalidate" or "purge". 818 Type: string 820 6.1.2. TriggerStatus 822 Key: status 823 Description: One of "pending", "active", "failed", "complete" 824 Type: string 826 6.1.3. PatternMatch 828 A PatternMatch is encoded as a JSON Object containing a string to 829 match and flags describing the type of match. 831 Key: pattern 832 Description: A pattern for string matching. The pattern may 833 contain the wildcards * and ?, where * matches any sequence of 834 characters (including the empty string) and ? matches exactly 835 one character. The three literals \ , * and ? should be 836 escaped as \\, \* and \? 837 Type: String 838 Mandatory: Yes 839 Key: case-sensitive 840 Description: Flag indicating whether or not case-sensitive 841 matching should be used. 842 Type: Boolean 843 Mandatory: No, default is case-insensitive match. 844 Key: match-query-string 845 Description: Flag indicating whether or not the query string 846 should be included in the pattern match. 847 Type: Boolean 848 Mandatory: No, default is not to include query. 849 Example of case-sensitive prefix match against 850 "http://www.example.com/trailers/": 851 { 852 "pattern": "http://www.example.com/trailers/*", 853 "case-sensitive": true 854 } 856 6.1.4. ErrorDesc 858 ErrorDesc shall be encoded as a JSON object with the following keys: 860 Key: error 861 Type: ErrorCode 862 Mandatory: Yes 863 Keys: metadata.urls, content.urls 864 Type: Array of strings 865 Mandatory: At least one of metadata.* or content.* must be 866 present. 867 Keys: metadata.patterns, content.patterns 868 Type: Array of PatternMatch 869 Mandatory: At least one of metadata.* or content.* must be 870 present. 871 Key: description 872 Type: String 873 Mandatory: No. 875 6.1.5. ErrorCode 877 One of the strings "EMETA", "ECONTENT", "EPERM", "EREJECT" or "ECDN". 879 6.1.6. Relationship 881 JSON: A dictionary with the following keys: 883 o href - The URI of the of the addressable object being referenced. 884 o rel - The Relationship between the referring object and the object 885 it is referencing. 886 o type - The MIME Media Type of the referenced object. See 887 Section 6.2 for the MIME Media Types of objects specified in this 888 document. 889 o title - An optional title for the Relationship/link. 891 Note: The above structure follows the pattern of atom:link in 892 [RFC4287]. 894 Example Relationship to a CI/T Resource within a CI/T Collection: 895 { 896 "href": "http://triggers.cdni.example.com/trigger/12345", 897 "rel": "Trigger", 898 "type": "application/vnd.cdni.control.trigger.status+json" 899 } 901 The format of relationship values is expected to align with other 902 CDNI interfaces. For example, rather than use simple names (like 903 "Trigger" in this case), there may be a namespace that allows well- 904 known and proprietary values to co-exist. 906 6.2. MIME Media Types 908 Table 1 lists the MIME Media Type for each trigger object (resource) 909 that is retrievable through the CI/T interface. 911 Note: A prefix of "vnd.cdni" is used, however it is expected that a 912 more appropriate prefix will be used if the CDNI WG accepts this 913 document. 915 +-------------------+-----------------------------------------------+ 916 | Data Object | MIME Media Type | 917 +-------------------+-----------------------------------------------+ 918 | TriggerStatus | application/ | 919 | | vnd.cdni.control.trigger.status+json | 920 | TriggerCollection | application/ | 921 | | vnd.cdni.control.trigger.collection+json | 922 +-------------------+-----------------------------------------------+ 924 Table 1: MIME Media Types for CDNI Trigger resources 926 7. Examples 928 The following sections provide examples of different CI/T objects 929 encoded as JSON. 931 No authentication is shown in the following illustrative examples, it 932 is anticipated that authentication mechanisms will be aligned with 933 other CDNI Interfaces as and when those mechanisms are defined. 935 Discovery of the triggers interface is out of scope of this document. 936 In an implementation, all URLs are under control of dCDN and the uCDN 937 must not attempt to ascribe any meaning to individual elements of the 938 path. In examples in this section, the following URLs are used as 939 the location of the collections of triggers: 941 o Collection of all Triggers belonging to one uCDN: 942 http://dcdn.example.com/triggers 943 o Filtered collections: 944 Pending: http://dcdn.example.com/triggers/pending 945 Active: http://dcdn.example.com/triggers/active 946 Complete: http://dcdn.example.com/triggers/complete 947 Failed: http://dcdn.example.com/triggers/failed 949 7.1. Creating Triggers 951 Examples of uCDN triggering activity in dCDN: 953 7.1.1. Preposition 955 An example of a preposition request, a POST to the "AllTriggers" 956 collection. 958 Note that "metadata.patterns" and "content.patterns" are not allowed 959 in a preposition trigger request. 960 REQUEST: 962 POST /triggers HTTP/1.1 963 User-Agent: example-user-agent/0.1 964 Host: dcdn.example.com 965 Accept: */* 966 Content-Type: application/vnd.cdni.control.trigger.request+json 967 Content-Length: 315 969 { 970 "trigger" : { 971 "type": "preposition", 973 "metadata.urls" : [ "http://metadata.example.com/a/b/c" ], 974 "content.urls" : [ 975 "http://www.example.com/a/b/c/1", 976 "http://www.example.com/a/b/c/2", 977 "http://www.example.com/a/b/c/3", 978 "http://www.example.com/a/b/c/4" 979 ] 980 } 981 } 983 RESPONSE: 985 HTTP/1.1 201 Created 986 Date: Sat, 23 Feb 2013 14:20:06 GMT 987 Content-Length: 472 988 Content-Type: application/vnd.cdni.control.trigger.status+json 989 Location: http://dcdn.example.com/triggers/0 990 Server: example-server/0.1 992 { 993 "ctime": 1361629206, 994 "etime": 1361629214, 995 "mtime": 1361629206, 996 "status": "pending", 997 "trigger": { 998 "content.urls": [ 999 "http://www.example.com/a/b/c/1", 1000 "http://www.example.com/a/b/c/2", 1001 "http://www.example.com/a/b/c/3", 1002 "http://www.example.com/a/b/c/4" 1003 ], 1004 "metadata.urls": [ 1005 "http://metadata.example.com/a/b/c" 1006 ], 1007 "type": "preposition" 1008 } 1009 } 1011 7.1.2. Invalidate 1013 An example of an invalidate request, another POST to the 1014 "AllTriggers" collection. This instructs dCDN to re-validate the 1015 content at "http://www.example.com/a/index.html", as well as any 1016 metadata and content whose URLs are prefixed by 1017 "http://metadata.example.com/a/b/" and "http://www.example.com/a/b/" 1018 respectively, using case-insensitive matching. 1019 REQUEST: 1021 POST /triggers HTTP/1.1 1022 User-Agent: example-user-agent/0.1 1023 Host: dcdn.example.com 1024 Accept: */* 1025 Content-Type: application/vnd.cdni.control.trigger.request+json 1026 Content-Length: 352 1028 { 1029 "trigger" : { 1030 "type": "invalidate", 1032 "metadata.patterns" : [ 1033 { "pattern" : "http://metadata.example.com/a/b/*" } 1034 ], 1036 "content.urls" : [ "http://www.example.com/a/index.html" ], 1037 "content.patterns" : [ 1038 { "pattern" : "http://www.example.com/a/b/*", 1039 "case-sensitive" : true 1040 } 1041 ] 1042 } 1043 } 1045 RESPONSE: 1047 HTTP/1.1 201 Created 1048 Date: Sat, 23 Feb 2013 14:20:08 GMT 1049 Content-Length: 551 1050 Content-Type: application/vnd.cdni.control.trigger.status+json 1051 Location: http://dcdn.example.com/triggers/1 1052 Server: example-server/0.1 1054 { 1055 "ctime": 1361629208, 1056 "etime": 1361629216, 1057 "mtime": 1361629208, 1058 "status": "pending", 1059 "trigger": { 1060 "content.patterns": [ 1061 { 1062 "case-sensitive": true, 1063 "pattern": "http://www.example.com/a/b/*" 1064 } 1065 ], 1066 "content.urls": [ 1067 "http://www.example.com/a/index.html" 1068 ], 1069 "metadata.patterns": [ 1070 { 1071 "pattern": "http://metadata.example.com/a/b/*" 1072 } 1073 ], 1074 "type": "invalidate" 1075 } 1076 } 1078 7.2. Examining Trigger Status 1080 Once triggers have been created, uCDN can check their status as shown 1081 in these examples. 1083 7.2.1. Collection of All Triggers 1085 The uCDN can fetch the set of all the triggers it has created and 1086 which have not yet been deleted or removed as expired. After 1087 creation of the "preposition" and "invalidate" triggers shown above, 1088 this collection might look as follows: 1090 REQUEST: 1092 GET /triggers HTTP/1.1 1093 User-Agent: example-user-agent/0.1 1094 Host: dcdn.example.com 1095 Accept: */* 1097 RESPONSE: 1099 HTTP/1.1 200 OK 1100 Content-Length: 422 1101 Expires: Sat, 23 Feb 2013 14:21:08 GMT 1102 Server: example-server/0.1 1103 ETag: "1484827667515030767" 1104 Cache-Control: max-age=60 1105 Date: Sat, 23 Feb 2013 14:20:08 GMT 1106 Content-Type: application/vnd.cdni.control.trigger.collection+json 1108 { 1109 "links": [ 1110 { 1111 "href": "http://dcdn.example.com/triggers/0", 1112 "rel": "Trigger", 1113 "type": "application/vnd.cdni.control.trigger.status+json" 1114 }, 1115 { 1116 "href": "http://dcdn.example.com/triggers/1", 1117 "rel": "Trigger", 1118 "type": "application/vnd.cdni.control.trigger.status+json" 1119 } 1120 ], 1121 "staleresourcetime": 86400 1122 } 1124 7.2.2. Filtered Collections of Triggers 1126 The filtered collections are also available to uCDN. Before dCDN 1127 starts processing the two triggers shown above, both will appear in 1128 the collection of Pending Triggers, for example: 1130 REQUEST: 1132 GET /triggers/pending HTTP/1.1 1133 User-Agent: example-user-agent/0.1 1134 Host: dcdn.example.com 1135 Accept: */* 1137 RESPONSE: 1139 HTTP/1.1 200 OK 1140 Content-Length: 422 1141 Expires: Sat, 23 Feb 2013 14:21:09 GMT 1142 Server: example-server/0.1 1143 ETag: "-970375801048973013" 1144 Cache-Control: max-age=60 1145 Date: Sat, 23 Feb 2013 14:20:09 GMT 1146 Content-Type: application/vnd.cdni.control.trigger.collection+json 1148 { 1149 "links": [ 1150 { 1151 "href": "http://dcdn.example.com/triggers/0", 1152 "rel": "Trigger", 1153 "type": "application/vnd.cdni.control.trigger.status+json" 1154 }, 1155 { 1156 "href": "http://dcdn.example.com/triggers/1", 1157 "rel": "Trigger", 1158 "type": "application/vnd.cdni.control.trigger.status+json" 1159 } 1160 ], 1161 "staleresourcetime": 86400 1162 } 1164 At this point, if no other triggers had been created, the other 1165 filtered views of the triggers would be empty. For example: 1167 REQUEST: 1169 GET /triggers/complete HTTP/1.1 1170 User-Agent: example-user-agent/0.1 1171 Host: dcdn.example.com 1172 Accept: */* 1174 RESPONSE: 1176 HTTP/1.1 200 OK 1177 Content-Length: 53 1178 Expires: Sat, 23 Feb 2013 14:21:09 GMT 1179 Server: example-server/0.1 1180 ETag: "-654105208640281650" 1181 Cache-Control: max-age=60 1182 Date: Sat, 23 Feb 2013 14:20:09 GMT 1183 Content-Type: application/vnd.cdni.control.trigger.collection+json 1185 { 1186 "links": [], 1187 "staleresourcetime": 86400 1188 } 1190 7.2.3. Trigger Status Resources 1192 The Trigger Status Resources can also be examined for detail about 1193 individual triggers. For example, for the "preposition" and 1194 "invalidate" triggers from previous examples: 1196 REQUEST: 1198 GET /triggers/0 HTTP/1.1 1199 User-Agent: example-user-agent/0.1 1200 Host: dcdn.example.com 1201 Accept: */* 1203 RESPONSE: 1205 HTTP/1.1 200 OK 1206 Content-Length: 472 1207 Expires: Sat, 23 Feb 2013 14:21:08 GMT 1208 Server: example-server/0.1 1209 ETag: "-7651038857765989381" 1210 Cache-Control: max-age=60 1211 Date: Sat, 23 Feb 2013 14:20:08 GMT 1212 Content-Type: application/vnd.cdni.control.trigger.status+json 1214 { 1215 "ctime": 1361629206, 1216 "etime": 1361629214, 1217 "mtime": 1361629206, 1218 "status": "pending", 1219 "trigger": { 1220 "content.urls": [ 1221 "http://www.example.com/a/b/c/1", 1222 "http://www.example.com/a/b/c/2", 1223 "http://www.example.com/a/b/c/3", 1224 "http://www.example.com/a/b/c/4" 1225 ], 1226 "metadata.urls": [ 1227 "http://metadata.example.com/a/b/c" 1228 ], 1229 "type": "preposition" 1230 } 1231 } 1233 REQUEST: 1235 GET /triggers/1 HTTP/1.1 1236 User-Agent: example-user-agent/0.1 1237 Host: dcdn.example.com 1238 Accept: */* 1240 RESPONSE: 1242 HTTP/1.1 200 OK 1243 Content-Length: 551 1244 Expires: Sat, 23 Feb 2013 14:21:09 GMT 1245 Server: example-server/0.1 1246 ETag: "-1103964172288811711" 1247 Cache-Control: max-age=60 1248 Date: Sat, 23 Feb 2013 14:20:09 GMT 1249 Content-Type: application/vnd.cdni.control.trigger.status+json 1251 { 1252 "ctime": 1361629208, 1253 "etime": 1361629216, 1254 "mtime": 1361629208, 1255 "status": "pending", 1256 "trigger": { 1257 "content.patterns": [ 1258 { 1259 "case-sensitive": true, 1260 "pattern": "http://www.example.com/a/b/*" 1261 } 1262 ], 1263 "content.urls": [ 1264 "http://www.example.com/a/index.html" 1265 ], 1266 "metadata.patterns": [ 1267 { 1268 "pattern": "http://metadata.example.com/a/b/*" 1269 } 1270 ], 1271 "type": "invalidate" 1272 } 1273 } 1275 7.2.4. Polling for Change 1277 The uCDN may use the Entity Tags of collections or resources when 1278 polling for change in status, as shown in the following examples: 1280 REQUEST: 1282 GET /triggers/pending HTTP/1.1 1283 User-Agent: example-user-agent/0.1 1284 Host: dcdn.example.com 1285 Accept: */* 1286 If-None-Match: "-970375801048973013" 1288 RESPONSE: 1290 HTTP/1.1 304 Not Modified 1291 Content-Length: 0 1292 Expires: Sat, 23 Feb 2013 14:21:09 GMT 1293 Server: example-server/0.1 1294 ETag: "-970375801048973013" 1295 Cache-Control: max-age=60 1296 Date: Sat, 23 Feb 2013 14:20:09 GMT 1297 Content-Type: application/vnd.cdni.control.trigger.collection+json 1298 REQUEST: 1300 GET /triggers/0 HTTP/1.1 1301 User-Agent: example-user-agent/0.1 1302 Host: dcdn.example.com 1303 Accept: */* 1304 If-None-Match: "-7651038857765989381" 1306 RESPONSE: 1308 HTTP/1.1 304 Not Modified 1309 Content-Length: 0 1310 Expires: Sat, 23 Feb 2013 14:21:08 GMT 1311 Server: example-server/0.1 1312 ETag: "-7651038857765989381" 1313 Cache-Control: max-age=60 1314 Date: Sat, 23 Feb 2013 14:20:08 GMT 1315 Content-Type: application/vnd.cdni.control.trigger.status+json 1317 When the triggered activity is complete, the contents of the filtered 1318 collections will be updated, along with their Entity Tags. For 1319 example, when the two example triggers are complete, the collections 1320 of pending and complete triggers may look like: 1322 REQUEST: 1324 GET /triggers/pending HTTP/1.1 1325 User-Agent: example-user-agent/0.1 1326 Host: dcdn.example.com 1327 Accept: */* 1328 If-None-Match: "-970375801048973013" 1330 RESPONSE: 1332 HTTP/1.1 200 OK 1333 Content-Length: 53 1334 Expires: Sat, 23 Feb 2013 14:21:13 GMT 1335 Server: example-server/0.1 1336 ETag: "-7056231826368088123" 1337 Cache-Control: max-age=60 1338 Date: Sat, 23 Feb 2013 14:20:13 GMT 1339 Content-Type: application/vnd.cdni.control.trigger.collection+json 1341 { 1342 "links": [], 1343 "staleresourcetime": 86400 1344 } 1346 REQUEST: 1348 GET /triggers/complete HTTP/1.1 1349 User-Agent: example-user-agent/0.1 1350 Host: dcdn.example.com 1351 Accept: */* 1353 RESPONSE: 1355 HTTP/1.1 200 OK 1356 Content-Length: 422 1357 Expires: Sat, 23 Feb 2013 14:21:20 GMT 1358 Server: example-server/0.1 1359 ETag: "2013095476705515794" 1360 Cache-Control: max-age=60 1361 Date: Sat, 23 Feb 2013 14:20:20 GMT 1362 Content-Type: application/vnd.cdni.control.trigger.collection+json 1364 { 1365 "links": [ 1366 { 1367 "href": "http://dcdn.example.com/triggers/0", 1368 "rel": "Trigger", 1369 "type": "application/vnd.cdni.control.trigger.status+json" 1370 }, 1371 { 1372 "href": "http://dcdn.example.com/triggers/1", 1373 "rel": "Trigger", 1374 "type": "application/vnd.cdni.control.trigger.status+json" 1375 } 1376 ], 1377 "staleresourcetime": 86400 1378 } 1380 7.2.5. Cancelling or Removing a Trigger 1382 To request dCDN to cancel a Trigger, uCDN may delete the Trigger 1383 Resource. It may also delete completed and failed triggers to reduce 1384 the size of the collections. For example, to remove the 1385 "preposition" request from earlier examples: 1387 REQUEST: 1389 DELETE /triggers/0 HTTP/1.1 1390 User-Agent: example-user-agent/0.1 1391 Host: dcdn.example.com 1392 Accept: */* 1394 RESPONSE: 1396 HTTP/1.1 204 No Content 1397 Date: Sat, 23 Feb 2013 14:20:20 GMT 1398 Content-Length: 0 1399 Content-Type: text/html; charset=UTF-8 1400 Server: example-server/0.1 1402 This would, for example, cause the collection of completed triggers 1403 shown in the example above to be updated to: 1404 REQUEST: 1406 GET /triggers/complete HTTP/1.1 1407 User-Agent: example-user-agent/0.1 1408 Host: dcdn.example.com 1409 Accept: */* 1411 RESPONSE: 1413 HTTP/1.1 200 OK 1414 Content-Length: 239 1415 Expires: Sat, 23 Feb 2013 14:21:20 GMT 1416 Server: example-server/0.1 1417 ETag: "4257416552489354137" 1418 Cache-Control: max-age=60 1419 Date: Sat, 23 Feb 2013 14:20:20 GMT 1420 Content-Type: application/vnd.cdni.control.trigger.collection+json 1422 { 1423 "links": [ 1424 { 1425 "href": "http://dcdn.example.com/triggers/1", 1426 "rel": "Trigger", 1427 "type": "application/vnd.cdni.control.trigger.status+json" 1428 } 1429 ], 1430 "staleresourcetime": 86400 1431 } 1433 7.2.6. Error Reporting 1435 In this example uCDN has requested prepositioning of 1436 "http://newsite.example.com/index.html", but dCDN was unable to 1437 locate metadata for that site: 1438 REQUEST: 1440 GET /triggers/2 HTTP/1.1 1441 User-Agent: example-user-agent/0.1 1442 Host: dcdn.example.com 1443 Accept: */* 1445 RESPONSE: 1447 HTTP/1.1 200 OK 1448 Content-Length: 505 1449 Expires: Sat, 23 Feb 2013 14:21:28 GMT 1450 Server: example-server/0.1 1451 ETag: "2621489144226897896" 1452 Cache-Control: max-age=60 1453 Date: Sat, 23 Feb 2013 14:20:28 GMT 1454 Content-Type: application/vnd.cdni.control.trigger.status+json 1456 { 1457 "ctime": 1361629220, 1458 "errors": [ 1459 { 1460 "content.urls": [ 1461 "http://newsite.example.com/index.html" 1462 ], 1463 "description": 1464 "No HostIndex entry found for newsite.example.com", 1465 "error": "EMETA" 1466 } 1467 ], 1468 "etime": 1361629228, 1469 "mtime": 1361629224, 1470 "status": "active", 1471 "trigger": { 1472 "content.urls": [ 1473 "http://newsite.example.com/index.html" 1474 ], 1475 "type": "preposition" 1476 } 1477 } 1479 8. IANA Considerations 1481 TBD. 1483 9. Security Considerations 1485 The dCDN must ensure that each uCDN only has access to its own 1486 Trigger Status Resources. 1488 It is anticipated that a common authentication mechanism will be used 1489 by this and other CDNI Interconnect interfaces, the mechanism must 1490 exist but is not identified in this document. 1492 The dCDN must ensure that activity triggered by uCDN only affects 1493 metadata or content originating from that uCDN. 1495 10. Acknowledgements 1497 TBD. 1499 11. References 1501 11.1. Normative References 1503 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1504 Requirement Levels", BCP 14, RFC 2119, March 1997. 1506 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1507 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1508 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1510 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1511 Resource Identifier (URI): Generic Syntax", STD 66, 1512 RFC 3986, January 2005. 1514 11.2. Informative References 1516 [I-D.ietf-cdni-framework] 1517 Peterson, L. and B. Davie, "Framework for CDN 1518 Interconnection", draft-ietf-cdni-framework-03 (work in 1519 progress), February 2013. 1521 [I-D.ietf-cdni-metadata] 1522 Niven-Jenkins, B., Murray, R., Watson, G., Caulfield, M., 1523 Leung, K., and K. Ma, "CDN Interconnect Metadata", 1524 draft-ietf-cdni-metadata-01 (work in progress), 1525 February 2013. 1527 [I-D.ietf-cdni-requirements] 1528 Leung, K. and Y. Lee, "Content Distribution Network 1529 Interconnection (CDNI) Requirements", 1530 draft-ietf-cdni-requirements-05 (work in progress), 1531 February 2013. 1533 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1534 Syndication Format", RFC 4287, December 2005. 1536 [RFC6707] Niven-Jenkins, B., Le Faucheur, F., and N. Bitar, "Content 1537 Distribution Network Interconnection (CDNI) Problem 1538 Statement", RFC 6707, September 2012. 1540 [XML-BASE] 1541 Marsh, J., Ed. and R. Tobin, Ed., "XML Base (Second 1542 Edition) - http://www.w3.org/TR/xmlbase/", January 2009. 1544 Authors' Addresses 1546 Rob Murray 1547 Velocix (Alcatel-Lucent) 1548 3 Ely Road 1549 Milton, Cambridge CB24 6DD 1550 UK 1552 Email: rmurray@velocix.com 1554 Ben Niven-Jenkins 1555 Velocix (Alcatel-Lucent) 1556 3 Ely Road 1557 Milton, Cambridge CB24 6DD 1558 UK 1560 Email: ben@velocix.com