idnits 2.17.1 draft-sopher-cdni-triggers-extensions-rfc8007bis-00.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 (April 28, 2021) is 1092 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) == Unused Reference: 'RFC8007' is defined on line 1912, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group O. Finkelman 3 Internet-Draft Qwilt 4 Obsoletes: 8007 (if approved) S. Mishra 5 Intended status: Standards Track Verizon 6 Expires: October 30, 2021 N. Sopher 7 Qwilt 8 April 28, 2021 10 Content Delivery Network Interconnection (CDNI) Control Interface / 11 Triggers 2nd Edition 12 draft-sopher-cdni-triggers-extensions-rfc8007bis-00 14 Abstract 16 This document obsoletes RFC8007. This document describes the part of 17 the Content Delivery Network Interconnection (CDNI) Control interface 18 that allows a CDN to trigger activity in an interconnected CDN that 19 is configured to deliver content on its behalf. The upstream CDN can 20 use this mechanism to request that the downstream CDN pre-position 21 metadata or content or to request that it invalidate or purge 22 metadata or content. The upstream CDN can monitor the status of 23 activity that it has triggered in the downstream CDN. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on October 30, 2021. 42 Copyright Notice 44 Copyright (c) 2021 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 61 2. Model for CDNI Triggers . . . . . . . . . . . . . . . . . . . 4 62 2.1. Timing of Triggered Activity . . . . . . . . . . . . . . 6 63 2.2. Scope of Triggered Activity . . . . . . . . . . . . . . . 6 64 2.2.1. Multiple Interconnected CDNs . . . . . . . . . . . . 7 65 2.3. Trigger Results . . . . . . . . . . . . . . . . . . . . . 8 66 3. Collections of Trigger Status Resources . . . . . . . . . . . 8 67 4. CDNI Trigger Interface . . . . . . . . . . . . . . . . . . . 9 68 4.1. Creating Triggers . . . . . . . . . . . . . . . . . . . . 10 69 4.2. Checking Status . . . . . . . . . . . . . . . . . . . . . 11 70 4.2.1. Polling Trigger Status Resource Collections . . . . . 12 71 4.2.2. Polling Trigger Status Resources . . . . . . . . . . 12 72 4.3. Canceling Triggers . . . . . . . . . . . . . . . . . . . 12 73 4.4. Deleting Triggers . . . . . . . . . . . . . . . . . . . . 13 74 4.5. Expiry of Trigger Status Resources . . . . . . . . . . . 14 75 4.6. Loop Detection and Prevention . . . . . . . . . . . . . . 14 76 4.7. Error Handling . . . . . . . . . . . . . . . . . . . . . 15 77 4.8. Content URLs . . . . . . . . . . . . . . . . . . . . . . 16 78 5. CI/T Object Properties and Encoding . . . . . . . . . . . . . 16 79 5.1. CI/T Objects . . . . . . . . . . . . . . . . . . . . . . 16 80 5.1.1. CI/T Commands . . . . . . . . . . . . . . . . . . . . 16 81 5.1.2. Trigger Status Resources . . . . . . . . . . . . . . 17 82 5.1.3. Trigger Collections . . . . . . . . . . . . . . . . . 19 83 5.2. Properties of CI/T Objects . . . . . . . . . . . . . . . 20 84 5.2.1. Trigger Specification . . . . . . . . . . . . . . . . 20 85 5.2.2. Trigger Type . . . . . . . . . . . . . . . . . . . . 22 86 5.2.3. Trigger Status . . . . . . . . . . . . . . . . . . . 22 87 5.2.4. PatternMatch . . . . . . . . . . . . . . . . . . . . 23 88 5.2.5. Absolute Time . . . . . . . . . . . . . . . . . . . . 24 89 5.2.6. Error Description . . . . . . . . . . . . . . . . . . 24 90 5.2.7. Error Code . . . . . . . . . . . . . . . . . . . . . 25 91 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 26 92 6.1. Creating Triggers . . . . . . . . . . . . . . . . . . . . 26 93 6.1.1. Preposition . . . . . . . . . . . . . . . . . . . . . 26 94 6.1.2. Invalidate . . . . . . . . . . . . . . . . . . . . . 28 95 6.2. Examining Trigger Status . . . . . . . . . . . . . . . . 29 96 6.2.1. Collection of All Triggers . . . . . . . . . . . . . 29 97 6.2.2. Filtered Collections of Trigger Status Resources . . 30 98 6.2.3. Individual Trigger Status Resources . . . . . . . . . 32 99 6.2.4. Polling for Changes in Status . . . . . . . . . . . . 34 100 6.2.5. Deleting Trigger Status Resources . . . . . . . . . . 37 101 6.2.6. Error Reporting . . . . . . . . . . . . . . . . . . . 38 102 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 103 7.1. CDNI Payload Type Parameter Registrations . . . . . . . . 39 104 7.2. "CDNI CI/T Trigger Types" Registry . . . . . . . . . . . 39 105 7.3. "CDNI CI/T Error Codes" Registry . . . . . . . . . . . . 39 106 8. Security Considerations . . . . . . . . . . . . . . . . . . . 40 107 8.1. Authentication, Authorization, Confidentiality, Integrity 108 Protection . . . . . . . . . . . . . . . . . . . . . . . 40 109 8.2. Denial of Service . . . . . . . . . . . . . . . . . . . . 41 110 8.3. Privacy . . . . . . . . . . . . . . . . . . . . . . . . . 42 111 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 42 112 9.1. Normative References . . . . . . . . . . . . . . . . . . 42 113 9.2. Informative References . . . . . . . . . . . . . . . . . 43 114 Appendix A. Formalization of the JSON Data . . . . . . . . . . . 44 115 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 46 116 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 46 118 1. Introduction 120 [RFC6707] introduces the problem scope for Content Delivery Network 121 Interconnection (CDNI) and lists the four categories of interfaces 122 that may be used to compose a CDNI solution (Control, Metadata, 123 Request Routing, and Logging). 125 [RFC7336] expands on the information provided in [RFC6707] and 126 describes each of the interfaces and the relationships between them 127 in more detail. 129 This document describes the "CI/T" interface -- "CDNI Control 130 interface / Triggers". It does not consider those parts of the 131 Control interface that relate to configuration, bootstrapping, or 132 authentication of CDN Interconnect interfaces. Section 4 of 133 [RFC7337] identifies the requirements specific to the CI/T interface; 134 requirements applicable to the CI/T interface are CI-1 to CI-6. 136 o Section 2 outlines the model for the CI/T interface at a high 137 level. 139 o Section 3 describes collections of Trigger Status Resources. 141 o Section 4 defines the web service provided by the downstream CDN. 143 o Section 5 lists properties of CI/T Commands and Status Resources. 145 o Section 6 contains example messages. 147 1.1. Terminology 149 This document reuses the terminology defined in [RFC6707] and uses 150 "uCDN" and "dCDN" as shorthand for "upstream CDN" and "downstream 151 CDN", respectively. 153 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 154 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 155 document are to be interpreted as described in RFC 2119 [RFC2119]. 157 2. Model for CDNI Triggers 159 A CI/T Command, sent from the uCDN to the dCDN, is a request for the 160 dCDN to do some work relating to data associated with content 161 requests originating from the uCDN. 163 There are two types of CI/T Commands: CI/T Trigger Commands and CI/T 164 Cancel Commands. The CI/T Cancel Command can be used to request 165 cancellation of an earlier CI/T Trigger Command. A CI/T Trigger 166 Command is of one of the following types: 168 o preposition - used to instruct the dCDN to fetch metadata from the 169 uCDN, or content from any origin including the uCDN. 171 o invalidate - used to instruct the dCDN to revalidate specific 172 metadata or content before reusing it. 174 o purge - used to instruct the dCDN to delete specific metadata or 175 content. 177 The CI/T interface is a web service offered by the dCDN. It allows 178 CI/T Commands to be issued and allows triggered activity to be 179 tracked. The CI/T interface builds on top of HTTP/1.1 [RFC7230]. 180 References to URL in this document relate to HTTP/HTTPS URIs, as 181 defined in Section 2.7 of [RFC7230]. 183 When the dCDN accepts a CI/T Command, it creates a resource 184 describing the status of the triggered activity -- a Trigger Status 185 Resource. The uCDN can poll Trigger Status Resources to monitor 186 progress. 188 The dCDN maintains at least one collection of Trigger Status 189 Resources for each uCDN. Each uCDN only has access to its own 190 collections, the locations of which are shared when CDNI is 191 established. 193 To trigger activity in the dCDN, the uCDN POSTs a CI/T Command to the 194 collection of Trigger Status Resources. If the dCDN accepts the CI/T 195 Command, it creates a new Trigger Status Resource and returns its 196 location to the uCDN. To monitor progress, the uCDN can GET the 197 Trigger Status Resource. To request cancellation of a CI/T Trigger 198 Command, the uCDN can POST to the collection of Trigger Status 199 Resources or simply delete the Trigger Status Resource. 201 In addition to the collection of all Trigger Status Resources for the 202 uCDN, the dCDN can maintain filtered views of that collection. These 203 filtered views are defined in Section 3 and include collections of 204 Trigger Status Resources corresponding to active and completed CI/T 205 Trigger Commands. These collections provide a mechanism for polling 206 the status of multiple jobs. 208 Figure 1 is an example showing the basic message flow used by the 209 uCDN to trigger activity in the dCDN and for the uCDN to discover the 210 status of that activity. Only successful triggering is shown. 211 Examples of the messages are given in Section 6. 213 uCDN dCDN 214 | (1) POST https://dcdn.example.com/triggers/uCDN | 215 [ ] --------------------------------------------------> [ ]--+ 216 | [ ] | (2) 217 | (3) HTTP 201 Response [ ]<-+ 218 [ ] <-------------------------------------------------- [ ] 219 | Loc: https://dcdn.example.com/triggers/uCDN/123 | 220 | | 221 . . . 222 . . . 223 . . . 224 | | 225 | (4) GET https://dcdn.example.com/triggers/uCDN/123 | 226 [ ] --------------------------------------------------> [ ] 227 | [ ] 228 | (5) HTTP 200 Trigger Status Resource [ ] 229 [ ] <-------------------------------------------------- [ ] 230 | | 231 | | 233 Figure 1: Basic CDNI Message Flow for Triggers 235 The steps in Figure 1 are as follows: 237 1. The uCDN triggers action in the dCDN by POSTing a CI/T Command to 238 a collection of Trigger Status Resources -- 239 "https://dcdn.example.com/triggers/uCDN". This URL was given to 240 the uCDN when the CI/T interface was established. 242 2. The dCDN authenticates the request, validates the CI/T Command, 243 and, if it accepts the request, creates a new Trigger Status 244 Resource. 246 3. The dCDN responds to the uCDN with an HTTP 201 response status 247 and the location of the Trigger Status Resource. 249 4. The uCDN can poll, possibly repeatedly, the Trigger Status 250 Resource in the dCDN. 252 5. The dCDN responds with the Trigger Status Resource, describing 253 the progress or results of the CI/T Trigger Command. 255 The remainder of this document describes the messages, Trigger Status 256 Resources, and collections of Trigger Status Resources in more 257 detail. 259 2.1. Timing of Triggered Activity 261 Timing of the execution of CI/T Commands is under the dCDN's control, 262 including its start time and pacing of the activity in the network. 264 CI/T "invalidate" and "purge" commands MUST be applied to all data 265 acquired before the command was accepted by the dCDN. The dCDN 266 SHOULD NOT apply CI/T "invalidate" and "purge" commands to data 267 acquired after the CI/T Command was accepted, but this may not always 268 be achievable, so the uCDN cannot count on that. 270 If the uCDN wishes to invalidate or purge content and then 271 immediately pre-position replacement content at the same URLs, it 272 SHOULD ensure that the dCDN has completed the invalidate/purge before 273 initiating the pre-positioning. Otherwise, there is a risk that the 274 dCDN pre-positions the new content, then immediately invalidates or 275 purges it (as a result of the two uCDN requests running in parallel). 277 Because the CI/T Command timing is under the dCDN's control, the dCDN 278 implementation can choose whether to apply CI/T "invalidate" and 279 "purge" commands to content acquisition that has already started when 280 the command is received. 282 2.2. Scope of Triggered Activity 284 Each CI/T Command can operate on multiple metadata and content URLs. 286 Multiple representations of an HTTP resource may share the same URL. 287 CI/T Trigger Commands that invalidate or purge metadata or content 288 apply to all resource representations with matching URLs. 290 2.2.1. Multiple Interconnected CDNs 292 In a network of interconnected CDNs, a single uCDN will originate a 293 given item of metadata and associated content. It may distribute 294 that metadata and content to more than one dCDN, which may in turn 295 distribute that metadata and content to CDNs located further 296 downstream. 298 An intermediate CDN is a dCDN that passes on CDNI Metadata and 299 content to dCDNs located further downstream. 301 A "diamond" configuration is one where a dCDN can acquire metadata 302 and content originated in one uCDN from that uCDN itself and an 303 intermediate CDN, or via more than one intermediate CDN. 305 CI/T Commands originating in the single source uCDN affect metadata 306 and content in all dCDNs; however, in a diamond configuration, it may 307 not be possible for the dCDN to determine which uCDN it acquired 308 content from. In this case, a dCDN MUST allow each uCDN from which 309 it may have acquired the content to act upon that content using CI/T 310 Commands. 312 In all other cases, a dCDN MUST reject CI/T Commands from a uCDN that 313 attempts to act on another uCDN's content by using, for example, HTTP 314 403 ("Forbidden"). 316 Security considerations are discussed further in Section 8. 318 The diamond configuration may lead to inefficient interactions, but 319 the interactions are otherwise harmless. For example: 321 o When the uCDN issues an "invalidate" CI/T Command, a dCDN will 322 receive that command from multiple directly connected uCDNs. The 323 dCDN may schedule multiple such commands separately, and the last 324 scheduled command may affect content already revalidated following 325 execution of the "invalidate" command that was scheduled first. 327 o If one of a dCDN's directly connected uCDNs loses its rights to 328 distribute content, it may issue a CI/T "purge" command. That 329 purge may affect content the dCDN could retain because it's 330 distributed by another directly connected uCDN. But, that content 331 can be reacquired by the dCDN from the remaining uCDN. 333 o When the uCDN originating an item of content issues a CI/T purge 334 followed by a pre-position, two directly connected uCDNs will pass 335 those commands to a dCDN. That dCDN implementation need not merge 336 those operations or notice the repetition, in which case the purge 337 issued by one uCDN will complete before the other. The first uCDN 338 to finish its purge may then forward the "preposition" trigger, 339 and content pre-positioned as a result might be affected by the 340 still-running purge issued by the other uCDN. However, the dCDN 341 will reacquire that content as needed, or when it's asked to pre- 342 position the content by the second uCDN. A dCDN implementation 343 could avoid this interaction by knowing which uCDN it acquired the 344 content from, or it could minimize the consequences by recording 345 the time at which the "invalidate"/"purge" command was received 346 and not applying it to content acquired after that time. 348 2.3. Trigger Results 350 Possible states for a Trigger Status Resource are defined in 351 Section 5.2.3. 353 The CI/T Trigger Command MUST NOT be reported as "complete" until all 354 actions have been completed successfully. The reasons for failure, 355 and URLs or patterns affected, SHOULD be enumerated in the Trigger 356 Status Resource. For more details, see Section 4.7. 358 If a dCDN is also acting as a uCDN in a cascade, it MUST forward CI/T 359 Commands to any dCDNs that may be affected. The CI/T Trigger Command 360 MUST NOT be reported as "complete" in a CDN until it is "complete" in 361 all of its dCDNs. If a CI/T Trigger Command is reported as 362 "processed" in any dCDN, intermediate CDNs MUST NOT report 363 "complete"; instead, they MUST also report "processed". A CI/T 364 Command MAY be reported as "failed" as soon as it fails in a CDN or 365 in any of its dCDNs. A canceled CI/T Trigger Command MUST be 366 reported as "cancelling" until it has been reported as "cancelled", 367 "complete", or "failed" by all dCDNs in a cascade. 369 3. Collections of Trigger Status Resources 371 As described in Section 2, Trigger Status Resources exist in the dCDN 372 to report the status of activity triggered by each uCDN. 374 A collection of Trigger Status Resources is a resource that contains 375 a reference to each Trigger Status Resource in that collection. 377 The dCDN MUST make a collection of a uCDN's Trigger Status Resources 378 available to that uCDN. This collection includes all of the Trigger 379 Status Resources created for CI/T Commands from the uCDN that have 380 been accepted by the dCDN, and have not yet been deleted by the uCDN, 381 or expired and removed by the dCDN (as described in Section 4.4). 382 Trigger Status Resources belonging to a uCDN MUST NOT be visible to 383 any other CDN. The dCDN could, for example, achieve this by offering 384 different collection URLs to each uCDN and by filtering the response 385 based on the uCDN with which the HTTP client is associated. 387 To trigger activity in a dCDN or to cancel triggered activity, the 388 uCDN POSTs a CI/T Command to the dCDN's collection of the uCDN's 389 Trigger Status Resources. 391 In order to allow the uCDN to check the status of multiple jobs in a 392 single request, the dCDN MAY also maintain collections representing 393 filtered views of the collection of all Trigger Status Resources. 394 These filtered collections are "optional-to-implement", but if they 395 are implemented, the dCDN MUST include links to them in the 396 collection of all Trigger Status Resources. The filtered collections 397 are: 399 o Pending - Trigger Status Resources for CI/T Trigger Commands that 400 have been accepted but not yet acted upon. 402 o Active - Trigger Status Resources for CI/T Trigger Commands that 403 are currently being processed in the dCDN. 405 o Complete - Trigger Status Resources representing activity that 406 completed successfully, and "processed" CI/T Trigger Commands for 407 which no further status updates will be made by the dCDN. 409 o Failed - Trigger Status Resources representing CI/T Commands that 410 failed or were canceled by the uCDN. 412 4. CDNI Trigger Interface 414 This section describes an interface to enable a uCDN to trigger 415 activity in a dCDN. 417 The CI/T interface builds on top of HTTP, so dCDNs may make use of 418 any HTTP feature when implementing the CI/T interface. For example, 419 a dCDN SHOULD make use of HTTP's caching mechanisms to indicate that 420 a requested response/representation has not been modified, reducing 421 the uCDN's processing needed to determine whether the status of 422 triggered activity has changed. 424 All dCDNs implementing CI/T MUST support the HTTP GET, HEAD, POST, 425 and DELETE methods as defined in [RFC7231]. 427 The only representation specified in this document is JSON [RFC8259]. 428 It MUST be supported by the uCDN and by the dCDN. 430 The URL of the dCDN's collection of all Trigger Status Resources 431 needs to be either discovered by or configured in the uCDN. The 432 mechanism for discovery of that URL is outside the scope of this 433 document. 435 CI/T Commands are POSTed to the dCDN's collection of all Trigger 436 Status Resources. If a CI/T Trigger Command is accepted by the dCDN, 437 the dCDN creates a new Trigger Status Resource and returns its URI to 438 the uCDN in an HTTP 201 response. The triggered activity can then be 439 monitored by the uCDN using that resource and the collections 440 described in Section 3. 442 The URI of each Trigger Status Resource is returned to the uCDN when 443 it is created, and URIs of all Trigger Status Resources are listed in 444 the dCDN's collection of all Trigger Status Resources. This means 445 all Trigger Status Resources can be discovered by the uCDN, so dCDNs 446 are free to assign whatever structure they desire to the URIs for CI/ 447 T resources. Therefore, uCDNs MUST NOT make any assumptions 448 regarding the structure of CI/T URIs or the mapping between CI/T 449 objects and their associated URIs. URIs present in the examples in 450 this document are purely illustrative and are not intended to impose 451 a definitive structure on CI/T interface implementations. 453 4.1. Creating Triggers 455 To issue a CI/T Command, the uCDN makes an HTTP POST to the dCDN's 456 collection of all of the uCDN's Trigger Status Resources. The 457 request body of that POST is a CI/T Command, as described in 458 Section 5.1.1. 460 The dCDN validates the CI/T Command. If the command is malformed or 461 the uCDN does not have sufficient access rights, the dCDN MUST either 462 respond with an appropriate 4xx HTTP error code and not create a 463 Trigger Status Resource or create a "failed" Trigger Status Resource 464 containing an appropriate Error Description. 466 When a CI/T Trigger Command is accepted, the uCDN MUST create a new 467 Trigger Status Resource that will convey a specification of the CI/T 468 Command and its current status. The HTTP response to the dCDN MUST 469 have status code 201 and MUST convey the URI of the Trigger Status 470 Resource in the Location header field [RFC7231]. The HTTP response 471 SHOULD include the content of the newly created Trigger Status 472 Resource. This is particularly important in cases where the CI/T 473 Trigger Command has completed immediately. 475 Once a Trigger Status Resource has been created, the dCDN MUST NOT 476 reuse its URI, even after that Trigger Status Resource has been 477 removed. 479 The dCDN SHOULD track and report on the progress of CI/T Trigger 480 Commands using a Trigger Status Resource (Section 5.1.2). If the 481 dCDN is not able to do that, it MUST indicate that it has accepted 482 the request but will not be providing further status updates. To do 483 this, it sets the status of the Trigger Status Resource to 484 "processed". In this case, CI/T processing should continue as for a 485 "complete" request, so the Trigger Status Resource MUST be added to 486 the dCDN's collection of complete Trigger Status Resources. The dCDN 487 SHOULD also provide an estimated completion time for the request by 488 using the "etime" property of the Trigger Status Resource. This will 489 allow the uCDN to schedule pre-positioning after an earlier delete of 490 the same URLs is expected to have finished. 492 If the dCDN is able to track the execution of CI/T Commands and a CI/ 493 T Command is queued by the dCDN for later action, the "status" 494 property of the Trigger Status Resource MUST be "pending". Once 495 processing has started, the status MUST be "active". Finally, once 496 the CI/T Command is complete, the status MUST be set to "complete" or 497 "failed". 499 A CI/T Trigger Command may result in no activity in the dCDN if, for 500 example, it is an "invalidate" or "purge" request for data the dCDN 501 has not yet acquired, or a "preposition" request for data that it has 502 already acquired and that is still valid. In this case, the status 503 of the Trigger Status Resource MUST be "processed" or "complete", and 504 the Trigger Status Resource MUST be added to the dCDN's collection of 505 complete Trigger Status Resources. 507 Once created, Trigger Status Resources can be canceled or deleted by 508 the uCDN, but not modified. The dCDN MUST reject PUT and POST 509 requests from the uCDN to Trigger Status Resources by responding with 510 an appropriate HTTP status code -- for example, 405 ("Method Not 511 Allowed"). 513 4.2. Checking Status 515 The uCDN has two ways to check the progress of CI/T Commands it has 516 issued to the dCDN, as described in Sections 4.2.1 and 4.2.2. 518 To allow the uCDN to check for changes in the status of a Trigger 519 Status Resource or collection of Trigger Status Resources without 520 refetching the whole resource or collection, the dCDN SHOULD include 521 entity-tags (ETags) for the uCDN to use as cache validators, as 522 defined in [RFC7232]. 524 The dCDN SHOULD use the cache control headers for responses to GETs 525 for Trigger Status Resources and Collections to indicate the 526 frequency at which it recommends that the uCDN should poll for 527 change. 529 4.2.1. Polling Trigger Status Resource Collections 531 The uCDN can fetch the collection of its Trigger Status Resources or 532 filtered views of that collection. 534 This makes it possible to poll the status of all CI/T Trigger 535 Commands in a single request. If the dCDN moves a Trigger Status 536 Resource from the active to the completed collection, the uCDN can 537 fetch the result of that activity. 539 When polling in this way, the uCDN SHOULD use HTTP ETags to monitor 540 for change, rather than repeatedly fetching the whole collection. An 541 example of this is given in Section 6.2.4. 543 4.2.2. Polling Trigger Status Resources 545 The uCDN has a URI provided by the dCDN for each Trigger Status 546 Resource it has created. It may fetch that Trigger Status Resource 547 at any time. 549 This can be used to retrieve progress information and to fetch the 550 result of the CI/T Command. 552 When polling in this way, the uCDN SHOULD use HTTP ETags to monitor 553 for change, rather than repeatedly fetching the Trigger Status 554 Resource. 556 4.3. Canceling Triggers 558 The uCDN can request cancellation of a CI/T Trigger Command by 559 POSTing a CI/T Cancel Command to the collection of all Trigger Status 560 Resources. 562 The dCDN is required to accept and respond to the CI/T Cancel 563 Command, but the actual cancellation of a CI/T Trigger Command is 564 optional-to-implement. 566 The dCDN MUST respond to the CI/T Cancel Command appropriately -- for 567 example, with HTTP status code 200 ("OK") if the cancellation has 568 been processed and the CI/T Command is inactive, 202 ("Accepted") if 569 the command has been accepted but the CI/T Command remains active, or 570 501 ("Not Implemented") if cancellation is not supported by the dCDN. 572 If cancellation of a "pending" Trigger Status Resource is accepted by 573 the dCDN, the dCDN SHOULD NOT start the processing of that activity. 574 Issuing a CI/T Cancel Command for a "pending" Trigger Status Resource 575 does not, however, guarantee that the corresponding activity will not 576 be started, because the uCDN cannot control the timing of that 577 activity. Processing could, for example, start after the POST is 578 sent by the uCDN but before that request is processed by the dCDN. 580 If cancellation of an "active" or "processed" Trigger Status Resource 581 is accepted by the dCDN, the dCDN SHOULD stop processing the CI/T 582 Command. However, as with cancellation of a "pending" CI/T Command, 583 the dCDN does not guarantee this. 585 If the CI/T Command cannot be stopped immediately, the status in the 586 corresponding Trigger Status Resource MUST be set to "cancelling", 587 and the Trigger Status Resource MUST remain in the collection of 588 Trigger Status Resources for active CI/T Commands. If processing is 589 stopped before normal completion, the status value in the Trigger 590 Status Resource MUST be set to "cancelled", and the Trigger Status 591 Resource MUST be included in the collection of failed CI/T Trigger 592 Commands. 594 Cancellation of a "complete" or "failed" Trigger Status Resource 595 requires no processing in the dCDN. Its status MUST NOT be changed 596 to "cancelled". 598 4.4. Deleting Triggers 600 The uCDN can delete Trigger Status Resources at any time, using the 601 HTTP DELETE method. The effect is similar to cancellation, but no 602 Trigger Status Resource remains afterwards. 604 Once deleted, the references to a Trigger Status Resource MUST be 605 removed from all Trigger Status Resource collections. Subsequent 606 requests to GET the deleted Trigger Status Resource SHOULD be 607 rejected by the dCDN with an HTTP error. 609 If a "pending" Trigger Status Resource is deleted, the dCDN SHOULD 610 NOT start the processing of that activity. Deleting a "pending" 611 Trigger Status Resource does not, however, guarantee that it has not 612 started, because the uCDN cannot control the timing of that activity. 613 Processing may, for example, start after the DELETE is sent by the 614 uCDN but before that request is processed by the dCDN. 616 If an "active" or "processed" Trigger Status Resource is deleted, the 617 dCDN SHOULD stop processing the CI/T Command. However, as with 618 deletion of a "pending" Trigger Status Resource, the dCDN does not 619 guarantee this. 621 Deletion of a "complete" or "failed" Trigger Status Resource requires 622 no processing in the dCDN other than deletion of the Trigger Status 623 Resource. 625 4.5. Expiry of Trigger Status Resources 627 The dCDN can choose to automatically delete Trigger Status Resources 628 some time after they become "complete", "processed", "failed", or 629 "cancelled". In this case, the dCDN will remove the Trigger Status 630 Resource and respond to subsequent requests for it with an HTTP 631 error. 633 If the dCDN does remove Trigger Status Resources automatically, it 634 MUST report the length of time after which it will do so, using a 635 property of the collection of all Trigger Status Resources. It is 637 RECOMMENDED that Trigger Status Resources are not automatically 638 deleted by the dCDN for at least 24 hours after they become 639 "complete", "processed", "failed", or "cancelled". 641 To ensure that it is able to get the status of its Trigger Status 642 Resources for completed and failed CI/T Commands, it is RECOMMENDED 643 that the uCDN polling interval is less than the time after which 644 records for completed activity will be deleted. 646 4.6. Loop Detection and Prevention 648 Given three CDNs, A, B, and C, if CDNs B and C delegate delivery of 649 CDN A's content to each other, CDN A's CI/T Commands could be passed 650 between CDNs B and C in a loop. More complex networks of CDNs could 651 contain similar loops involving more hops. 653 In order to prevent and detect such CI/T loops, each CDN uses a CDN 654 Provider ID (PID) to uniquely identify itself. In every CI/T Command 655 it originates or cascades, each CDN MUST append an array element 656 containing its CDN PID to a JSON array under an entry named "cdn- 657 path". When receiving CI/T Commands, a dCDN MUST check the cdn-path 658 and reject any CI/T Command that already contains its own CDN PID in 659 the cdn-path. Transit CDNs MUST check the cdn-path and not cascade 660 the CI/T Command to dCDNs that are already listed in the cdn-path. 662 The CDN PID consists of the two characters "AS" followed by the CDN 663 provider's Autonomous System number [RFC1930], then a colon (":") and 664 an additional qualifier that is used to guarantee uniqueness in case 665 a particular AS has multiple independent CDNs deployed -- for 666 example, "AS64496:0". 668 If the CDN provider has multiple ASes, the same AS number SHOULD be 669 used in all messages from that CDN provider, unless there are 670 multiple distinct CDNs. 672 If the CDNI Request Routing Redirection interface (RI) described in 673 [RFC7975] is implemented by the dCDN, the CI/T interface and the RI 674 SHOULD use the same CDN PID. 676 4.7. Error Handling 678 A dCDN can signal rejection of a CI/T Command using HTTP status codes 679 -- for example, 400 ("Bad Request") if the request is malformed, or 680 403 ("Forbidden") or 404 ("Not Found") if the uCDN does not have 681 permission to issue CI/T Commands or it is trying to act on another 682 CDN's data. 684 If any part of the CI/T Trigger Command fails, the trigger SHOULD be 685 reported as "failed" once its activity is complete or if no further 686 errors will be reported. The "errors" property in the Trigger Status 687 Resource will be used to enumerate which actions failed and the 688 reasons for failure, and can be present while the Trigger Status 689 Resource is still "pending" or "active", if the CI/T Trigger Command 690 is still running for some URLs or patterns in the Trigger 691 Specification. 693 Once a request has been accepted, processing errors are reported in 694 the Trigger Status Resource using a list of Error Descriptions. Each 695 Error Description is used to report errors against one or more of the 696 URLs or patterns in the Trigger Specification. 698 If a Surrogate affected by a CI/T Trigger Command is offline in the 699 dCDN or the dCDN is unable to pass a CI/T Command on to any of its 700 cascaded dCDNs: 702 o If the CI/T Command is abandoned by the dCDN, the dCDN SHOULD 703 report an error. 705 o A CI/T "invalidate" command may be reported as "complete" when 706 Surrogates that may have the data are offline. In this case, 707 Surrogates MUST NOT use the affected data without first 708 revalidating it when they are back online. 710 o CI/T "preposition" and "purge" commands can be reported as 711 "processed" if affected caches are offline and the activity will 712 complete when they return to service. 714 o Otherwise, the dCDN SHOULD keep the Trigger Status Resource in 715 state "pending" or "active" until either the CI/T Command is acted 716 upon or the uCDN chooses to cancel it. 718 4.8. Content URLs 720 If content URLs are transformed by an intermediate CDN in a cascade, 721 that intermediate CDN MUST similarly transform URLs in CI/T Commands 722 it passes to its dCDN. 724 When processing Trigger Specifications, CDNs MUST ignore the URL 725 scheme (HTTP or HTTPS) in comparing URLs. For example, for a CI/T 726 "invalidate" or "purge" command, content MUST be invalidated or 727 purged regardless of the protocol clients used to request it. 729 5. CI/T Object Properties and Encoding 731 The CI/T Commands, Trigger Status Resources, and Trigger Collections, 732 as well as their properties, are encoded using JSON, as defined in 733 Sections 5.1.1, 5.1.2, and 5.1.3. They MUST use the MIME media type 734 "application/cdni", with parameter "ptype" values as defined below 735 and in Section 7.1. 737 Names in JSON are case sensitive. The names and literal values 738 specified in the present document MUST always use lowercase. 740 JSON types, including "object", "array", "number", and "string", are 741 defined in [RFC8259]. 743 Unrecognized name/value pairs in JSON objects SHOULD NOT be treated 744 as an error by either the uCDN or dCDN. They SHOULD be ignored 745 during processing and passed on by the dCDN to any further dCDNs in a 746 cascade. 748 5.1. CI/T Objects 750 The top-level objects defined by the CI/T interface are described in 751 this section. 753 The encoding of values used by these objects is described in 754 Section 5.2. 756 5.1.1. CI/T Commands 758 CI/T Commands MUST use a MIME media type of "application/cdni; 759 ptype=ci-trigger-command". 761 A CI/T Command is encoded as a JSON object containing the following 762 name/value pairs. 764 Name: trigger 766 Description: A specification of the trigger type and a set of 767 data to act upon. 769 Value: A Trigger Specification, as defined in Section 5.2.1. 771 Mandatory: No, but exactly one of "trigger" or "cancel" MUST be 772 present in a CI/T Command. 774 Name: cancel 776 Description: The URLs of Trigger Status Resources for CI/T 777 Trigger Commands that the uCDN wants to cancel. 779 Value: A non-empty JSON array of URLs represented as JSON 780 strings. 782 Mandatory: No, but exactly one of "trigger" or "cancel" MUST be 783 present in a CI/T Command. 785 Name: cdn-path 787 Description: The CDN PIDs of CDNs that have already issued the 788 CI/T Command to their dCDNs. 790 Value: A non-empty JSON array of JSON strings, where each 791 string is a CDN PID as defined in Section 4.6. 793 Mandatory: Yes. 795 5.1.2. Trigger Status Resources 797 Trigger Status Resources MUST use a MIME media type of "application/ 798 cdni; ptype=ci-trigger-status". 800 A Trigger Status Resource is encoded as a JSON object containing the 801 following name/value pairs. 803 Name: trigger 805 Description: The Trigger Specification POSTed in the body of 806 the CI/T Command. Note that this need not be a byte-for-byte 807 copy. For example, in the JSON representation the dCDN may re- 808 serialize the information differently. 810 Value: A Trigger Specification, as defined in Section 5.2.1. 812 Mandatory: Yes. 814 Name: ctime 816 Description: Time at which the CI/T Command was received by the 817 dCDN. Time is determined by the dCDN; there is no requirement 818 to synchronize clocks between interconnected CDNs. 820 Value: Absolute Time, as defined in Section 5.2.5. 822 Mandatory: Yes. 824 Name: mtime 826 Description: Time at which the Trigger Status Resource was last 827 modified. Time is determined by the dCDN; there is no 828 requirement to synchronize clocks between interconnected CDNs. 830 Value: Absolute Time, as defined in Section 5.2.5. 832 Mandatory: Yes. 834 Name: etime 836 Description: Estimate of the time at which the dCDN expects to 837 complete the activity. Time is determined by the dCDN; there 838 is no requirement to synchronize clocks between interconnected 839 CDNs. 841 Value: Absolute Time, as defined in Section 5.2.5. 843 Mandatory: No. 845 Name: status 847 Description: Current status of the triggered activity. 849 Value: Trigger Status, as defined in Section 5.2.3. 851 Mandatory: Yes. 853 Name: errors 855 Description: Descriptions of errors that have occurred while 856 processing a Trigger Command. 858 Value: An array of Error Descriptions, as defined in 859 Section 5.2.6. An empty array is allowed and is equivalent to 860 omitting "errors" from the object. 862 Mandatory: No. 864 5.1.3. Trigger Collections 866 Trigger Collections MUST use a MIME media type of "application/cdni; 867 ptype=ci-trigger-collection". 869 A Trigger Collection is encoded as a JSON object containing the 870 following name/value pairs. 872 Name: triggers 874 Description: Links to Trigger Status Resources in the 875 collection. 877 Value: A JSON array of zero or more URLs, represented as JSON 878 strings. 880 Mandatory: Yes. 882 Name: staleresourcetime 884 Description: The length of time for which the dCDN guarantees 885 to keep a completed Trigger Status Resource. After this time, 886 the dCDN SHOULD delete the Trigger Status Resource and all 887 references to it from collections. 889 Value: A JSON number, which must be a positive integer, 890 representing time in seconds. 892 Mandatory: Yes, in the collection of all Trigger Status 893 Resources if the dCDN deletes stale entries. If the property 894 is present in the filtered collections, it MUST have the same 895 value as in the collection of all Trigger Status Resources. 897 Names: coll-all, coll-pending, coll-active, coll-complete, coll- 898 failed 900 Description: Link to a Trigger Collection. 902 Value: A URL represented as a JSON string. 904 Mandatory: Links to all of the filtered collections are 905 mandatory in the collection of all Trigger Status Resources, if 906 the dCDN implements the filtered collections. Otherwise, 907 optional. 909 Name: cdn-id 911 Description: The CDN PID of the dCDN. 913 Value: A JSON string, the dCDN's CDN PID, as defined in 914 Section 4.6. 916 Mandatory: Only in the collection of all Trigger Status 917 Resources, if the dCDN implements the filtered collections. 918 Optional in the filtered collections (the uCDN can always find 919 the dCDN's cdn-id in the collection of all Trigger Status 920 Resources, but the dCDN can choose to repeat that information 921 in its implementation of filtered collections). 923 5.2. Properties of CI/T Objects 925 This section defines the values that can appear in the top-level 926 objects described in Section 5.1, and their encodings. 928 5.2.1. Trigger Specification 930 A Trigger Collection is encoded as a JSON object containing the 931 following name/value pairs. 933 An unrecognized name/value pair in the Trigger Specification object 934 contained in a CI/T Command SHOULD be preserved in the Trigger 935 Specification of any Trigger Status Resource it creates. 937 Name: type 939 Description: Defines the type of the CI/T Trigger Command. 941 Value: Trigger Type, as defined in Section 5.2.2. 943 Mandatory: Yes. 945 Name: metadata.urls 946 Description: The uCDN URLs of the metadata the CI/T Trigger 947 Command applies to. 949 Value: A JSON array of URLs represented as JSON strings. 951 Mandatory: No, but at least one of "metadata.*" or "content.*" 952 MUST be present and non-empty. 954 Name: content.urls 956 Description: URLs of content the CI/T Trigger Command applies 957 to. See Section 4.8. 959 Value: A JSON array of URLs represented as JSON strings. 961 Mandatory: No, but at least one of "metadata.*" or "content.*" 962 MUST be present and non-empty. 964 Name: content.ccid 966 Description: The Content Collection IDentifier of content the 967 trigger applies to. The "ccid" is a grouping of content, as 968 defined by [RFC8006]. 970 Value: A JSON array of strings, where each string is a Content 971 Collection IDentifier. 973 Mandatory: No, but at least one of "metadata.*" or "content.*" 974 MUST be present and non-empty. 976 Name: metadata.patterns 978 Description: The metadata the trigger applies to. 980 Value: A JSON array of PatternMatch objects, as defined in 981 Section 5.2.4. 983 Mandatory: No, but at least one of "metadata.*" or "content.*" 984 MUST be present and non-empty, and metadata.patterns MUST NOT 985 be present if the Trigger Type is "preposition". 987 Name: content.patterns 989 Description: The content data the trigger applies to. 991 Value: A JSON array of PatternMatch objects, as defined in 992 Section 5.2.4. 994 Mandatory: No, but at least one of "metadata.*" or "content.*" 995 MUST be present and non-empty, and content.patterns MUST NOT be 996 present if the Trigger Type is "preposition". 998 5.2.2. Trigger Type 1000 Trigger Type is used in a Trigger Specification to describe trigger 1001 action. 1003 All trigger types MUST be registered in the IANA "CDNI CI/T Trigger 1004 Types" registry (see Section 7.2). 1006 A dCDN receiving a request containing a trigger type it does not 1007 recognize or does not support MUST reject the request by creating a 1008 Trigger Status Resource with a status of "failed" and the "errors" 1009 array containing an Error Description with error "eunsupported". 1011 The following trigger types are defined by this document: 1013 +--------------+----------------------------------------------------+ 1014 | JSON String | Description | 1015 +--------------+----------------------------------------------------+ 1016 | preposition | A request for the dCDN to acquire metadata or | 1017 | | content. | 1018 | invalidate | A request for the dCDN to invalidate metadata or | 1019 | | content. After servicing this request, the dCDN | 1020 | | will not use the specified data without first | 1021 | | revalidating it using, for example, an | 1022 | | "If-None-Match" HTTP request. The dCDN need not | 1023 | | erase the associated data. | 1024 | purge | A request for the dCDN to erase metadata or | 1025 | | content. After servicing the request, the | 1026 | | specified data MUST NOT be held on the dCDN (the | 1027 | | dCDN should reacquire the metadata or content from | 1028 | | the uCDN if it needs it). | 1029 +--------------+----------------------------------------------------+ 1031 5.2.3. Trigger Status 1033 Trigger Status describes the current status of the triggered 1034 activity. It MUST be one of the JSON strings in the following table: 1036 +--------------+----------------------------------------------------+ 1037 | JSON String | Description | 1038 +--------------+----------------------------------------------------+ 1039 | pending | The CI/T Trigger Command has not yet been acted | 1040 | | upon. | 1041 | active | The CI/T Trigger Command is currently being acted | 1042 | | upon. | 1043 | complete | The CI/T Trigger Command completed successfully. | 1044 | processed | The CI/T Trigger Command has been accepted, and no | 1045 | | further status update will be made (can be used in | 1046 | | cases where completion cannot be confirmed). | 1047 | failed | The CI/T Trigger Command could not be completed. | 1048 | canceling | Processing of the CI/T Trigger Command is still in | 1049 | | progress, but the CI/T Trigger Command has been | 1050 | | canceled by the uCDN. | 1051 | canceled | The CI/T Trigger Command was canceled by the uCDN. | 1052 +--------------+----------------------------------------------------+ 1054 5.2.4. PatternMatch 1056 A PatternMatch consists of a string pattern to match against a URI, 1057 and flags describing the type of match. 1059 It is encoded as a JSON object with the following name/value pairs: 1061 Name: pattern 1063 Description: A pattern for URI matching. 1065 Value: A JSON string representing the pattern. The pattern can 1066 contain the wildcards * and ?, where * matches any sequence of 1067 [RFC3986] pchar or "/" characters (including the empty string) and 1068 ? matches exactly one [RFC3986] pchar character. The three 1069 literals $, * and ? MUST be escaped as $$, $* and $? (where $ is 1070 the designated escape character). All other characters are 1071 treated as literals. 1073 Mandatory: Yes. 1075 Name: case-sensitive 1077 Description: Flag indicating whether or not case-sensitive 1078 matching should be used. 1080 Value: One of the JSON values "true" (the matching is case 1081 sensitive) or "false" (the matching is case insensitive). 1083 Mandatory: No; default is case-insensitive match. 1085 Name: match-query-string 1087 Description: Flag indicating whether to include the query part 1088 of the URI when comparing against the pattern. 1090 Value: One of the JSON values "true" (the full URI, including 1091 the query part, should be compared against the given pattern) 1092 or "false" (the query part of the URI should be dropped before 1093 comparison with the given pattern). 1095 Mandatory: No; default is "false". The query part of the URI 1096 should be dropped before comparison with the given pattern. 1098 Example of case-sensitive prefix match against 1099 "https://www.example.com/trailers/": 1101 { 1102 "pattern": "https://www.example.com/trailers/*", 1103 "case-sensitive": true 1104 } 1106 5.2.5. Absolute Time 1108 A JSON number, seconds since the UNIX epoch (00:00:00 UTC on 1 1109 January 1970). 1111 5.2.6. Error Description 1113 An Error Description is used to report the failure of a CI/T Command 1114 or failure in the activity it triggered. It is encoded as a JSON 1115 object with the following name/value pairs: 1117 Name: error 1119 Value: Error Code, as defined in Section 5.2.7. 1121 Mandatory: Yes. 1123 Names: metadata.urls, content.urls, metadata.patterns, 1124 content.patterns 1126 Description: Metadata and content references copied from the 1127 Trigger Specification. Only those URLs and patterns to which 1128 the error applies are included in each property, but those URLs 1129 and patterns MUST be exactly as they appear in the request; the 1130 dCDN MUST NOT generalize the URLs. (For example, if the uCDN 1131 requests pre-positioning of URLs "https://content.example.com/ 1132 a" and "https://content.example.com/b", the dCDN must not 1133 generalize its error report to the pattern 1134 "https://content.example.com/*".) 1136 Value: A JSON array of JSON strings, where each string is 1137 copied from a "content.*" or "metadata.*" value in the 1138 corresponding Trigger Specification. 1140 Mandatory: At least one of these name/value pairs is mandatory 1141 in each Error Description object. 1143 Name: description 1145 Description: A human-readable description of the error. 1147 Value: A JSON string, the human-readable description. 1149 Mandatory: No. 1151 5.2.7. Error Code 1153 This type is used by the dCDN to report failures in trigger 1154 processing. All Error Codes MUST be registered in the IANA "CDNI CI/ 1155 T Error Codes" registry (see Section 7.3). Unknown Error Codes MUST 1156 be treated as fatal errors, and the request MUST NOT be automatically 1157 retried without modification. 1159 The following Error Codes are defined by this document and MUST be 1160 supported by an implementation of the CI/T interface. 1162 +--------------+----------------------------------------------------+ 1163 | Error Code | Description | 1164 +--------------+----------------------------------------------------+ 1165 | emeta | The dCDN was unable to acquire metadata required | 1166 | | to fulfill the request. | 1167 | econtent | The dCDN was unable to acquire content (CI/T | 1168 | | "preposition" commands only). | 1169 | eperm | The uCDN does not have permission to issue the | 1170 | | CI/T Command (for example, the data is owned by | 1171 | | another CDN). | 1172 | ereject | The dCDN is not willing to fulfill the CI/T | 1173 | | Command (for example, a "preposition" request for | 1174 | | content at a time when the dCDN would not accept | 1175 | | Request Routing requests from the uCDN). | 1176 | ecdn | An internal error in the dCDN or one of its dCDNs. | 1177 | ecanceled | The uCDN canceled the request. | 1178 | eunsupported | The Trigger Specification contained a "type" that | 1179 | | is not supported by the dCDN. No action was taken | 1180 | | by the dCDN other than to create a Trigger Status | 1181 | | Resource in state "failed". | 1182 +--------------+----------------------------------------------------+ 1184 6. Examples 1186 The following subsections provide examples of different CI/T objects 1187 encoded as JSON. 1189 Discovery of the CI/T interface is out of scope for this document. 1190 In an implementation, all CI/T URLs are under the control of the 1191 dCDN. The uCDN MUST NOT attempt to ascribe any meaning to individual 1192 elements of the path. 1194 In examples in this section, the URL "https://dcdn.example.com/ 1195 triggers" is used as the location of the collection of all Trigger 1196 Status Resources, and the CDN PID of the uCDN is "AS64496:1". 1198 6.1. Creating Triggers 1200 Examples of the uCDN triggering activity in the dCDN: 1202 6.1.1. Preposition 1204 Below is an example of a CI/T "preposition" command -- a POST to the 1205 collection of all Trigger Status Resources. 1207 Note that "metadata.patterns" and "content.patterns" are not allowed 1208 in a pre-position Trigger Specification. 1210 REQUEST: 1212 POST /triggers HTTP/1.1 1213 User-Agent: example-user-agent/0.1 1214 Host: dcdn.example.com 1215 Accept: */* 1216 Content-Type: application/cdni; ptype=ci-trigger-command 1217 Content-Length: 352 1219 { 1220 "trigger": { 1221 "type": "preposition", 1223 "metadata.urls": [ "https://metadata.example.com/a/b/c" ], 1224 "content.urls": [ 1225 "https://www.example.com/a/b/c/1", 1226 "https://www.example.com/a/b/c/2", 1227 "https://www.example.com/a/b/c/3", 1228 "https://www.example.com/a/b/c/4" 1229 ] 1230 }, 1231 "cdn-path": [ "AS64496:1" ] 1232 } 1234 RESPONSE: 1236 HTTP/1.1 201 Created 1237 Date: Wed, 04 May 2016 08:48:10 GMT 1238 Content-Length: 467 1239 Content-Type: application/cdni; ptype=ci-trigger-status 1240 Location: https://dcdn.example.com/triggers/0 1241 Server: example-server/0.1 1243 { 1244 "ctime": 1462351690, 1245 "etime": 1462351698, 1246 "mtime": 1462351690, 1247 "status": "pending", 1248 "trigger": { 1249 "content.urls": [ 1250 "https://www.example.com/a/b/c/1", 1251 "https://www.example.com/a/b/c/2", 1252 "https://www.example.com/a/b/c/3", 1253 "https://www.example.com/a/b/c/4" 1254 ], 1255 "metadata.urls": [ 1256 "https://metadata.example.com/a/b/c" 1257 ], 1258 "type": "preposition" 1259 } 1260 } 1262 6.1.2. Invalidate 1264 Below is an example of a CI/T "invalidate" command -- another POST to 1265 the collection of all Trigger Status Resources. This instructs the 1266 dCDN to revalidate the content at "https://www.example.com/a/ 1267 index.html", as well as any metadata and content whose URLs are 1268 prefixed by "https://metadata.example.com/a/b/" using case- 1269 insensitive matching, and "https://www.example.com/a/b/" using case- 1270 sensitive matching, respectively. 1272 REQUEST: 1274 POST /triggers HTTP/1.1 1275 User-Agent: example-user-agent/0.1 1276 Host: dcdn.example.com 1277 Accept: */* 1278 Content-Type: application/cdni; ptype=ci-trigger-command 1279 Content-Length: 387 1281 { 1282 "trigger": { 1283 "type": "invalidate", 1285 "metadata.patterns": [ 1286 { "pattern": "https://metadata.example.com/a/b/*" } 1287 ], 1289 "content.urls": [ "https://www.example.com/a/index.html" ], 1290 "content.patterns": [ 1291 { "pattern": "https://www.example.com/a/b/*", 1292 "case-sensitive": true 1293 } 1294 ] 1295 }, 1296 "cdn-path": [ "AS64496:1" ] 1297 } 1299 RESPONSE: 1301 HTTP/1.1 201 Created 1302 Date: Wed, 04 May 2016 08:48:11 GMT 1303 Content-Length: 545 1304 Content-Type: application/cdni; ptype=ci-trigger-status 1305 Location: https://dcdn.example.com/triggers/1 1306 Server: example-server/0.1 1308 { 1309 "ctime": 1462351691, 1310 "etime": 1462351699, 1311 "mtime": 1462351691, 1312 "status": "pending", 1313 "trigger": { 1314 "content.patterns": [ 1315 { 1316 "case-sensitive": true, 1317 "pattern": "https://www.example.com/a/b/*" 1318 } 1319 ], 1320 "content.urls": [ 1321 "https://www.example.com/a/index.html" 1322 ], 1323 "metadata.patterns": [ 1324 { 1325 "pattern": "https://metadata.example.com/a/b/*" 1326 } 1327 ], 1328 "type": "invalidate" 1329 } 1330 } 1332 6.2. Examining Trigger Status 1334 Once Trigger Status Resources have been created, the uCDN can check 1335 their status as shown in the following examples. 1337 6.2.1. Collection of All Triggers 1339 The uCDN can fetch the collection of all Trigger Status Resources it 1340 has created that have not yet been deleted or removed as expired. 1341 After creation of the "preposition" and "invalidate" triggers shown 1342 above, this collection might look as follows: 1344 REQUEST: 1346 GET /triggers HTTP/1.1 1347 User-Agent: example-user-agent/0.1 1348 Host: dcdn.example.com 1349 Accept: */* 1351 RESPONSE: 1353 HTTP/1.1 200 OK 1354 Content-Length: 341 1355 Expires: Wed, 04 May 2016 08:49:11 GMT 1356 Server: example-server/0.1 1357 ETag: "-936094426920308378" 1358 Cache-Control: max-age=60 1359 Date: Wed, 04 May 2016 08:48:11 GMT 1360 Content-Type: application/cdni; ptype=ci-trigger-collection 1362 { 1363 "cdn-id": "AS64496:0", 1364 "coll-active": "/triggers/active", 1365 "coll-complete": "/triggers/complete", 1366 "coll-failed": "/triggers/failed", 1367 "coll-pending": "/triggers/pending", 1368 "staleresourcetime": 86400, 1369 "triggers": [ 1370 "https://dcdn.example.com/triggers/0", 1371 "https://dcdn.example.com/triggers/1" 1372 ] 1373 } 1375 6.2.2. Filtered Collections of Trigger Status Resources 1377 The filtered collections are also available to the uCDN. Before the 1378 dCDN starts processing the two CI/T Trigger Commands shown above, 1379 both will appear in the collection of pending triggers. For example: 1381 REQUEST: 1383 GET /triggers/pending HTTP/1.1 1384 User-Agent: example-user-agent/0.1 1385 Host: dcdn.example.com 1386 Accept: */* 1388 RESPONSE: 1390 HTTP/1.1 200 OK 1391 Content-Length: 152 1392 Expires: Wed, 04 May 2016 08:49:11 GMT 1393 Server: example-server/0.1 1394 ETag: "4331492443626270781" 1395 Cache-Control: max-age=60 1396 Date: Wed, 04 May 2016 08:48:11 GMT 1397 Content-Type: application/cdni; ptype=ci-trigger-collection 1399 { 1400 "staleresourcetime": 86400, 1401 "triggers": [ 1402 "https://dcdn.example.com/triggers/0", 1403 "https://dcdn.example.com/triggers/1" 1404 ] 1405 } 1407 At this point, if no other Trigger Status Resources had been created, 1408 the other filtered views would be empty. For example: 1410 REQUEST: 1412 GET /triggers/complete HTTP/1.1 1413 User-Agent: example-user-agent/0.1 1414 Host: dcdn.example.com 1415 Accept: */* 1417 RESPONSE: 1419 HTTP/1.1 200 OK 1420 Content-Length: 54 1421 Expires: Wed, 04 May 2016 08:49:11 GMT 1422 Server: example-server/0.1 1423 ETag: "7958041393922269003" 1424 Cache-Control: max-age=60 1425 Date: Wed, 04 May 2016 08:48:11 GMT 1426 Content-Type: application/cdni; ptype=ci-trigger-collection 1428 { 1429 "staleresourcetime": 86400, 1430 "triggers": [] 1431 } 1433 6.2.3. Individual Trigger Status Resources 1435 The Trigger Status Resources can also be examined for details about 1436 individual CI/T Trigger Commands. For example, for the CI/T 1437 "preposition" and "invalidate" commands from previous examples: 1439 REQUEST: 1441 GET /triggers/0 HTTP/1.1 1442 User-Agent: example-user-agent/0.1 1443 Host: dcdn.example.com 1444 Accept: */* 1446 RESPONSE: 1448 HTTP/1.1 200 OK 1449 Content-Length: 467 1450 Expires: Wed, 04 May 2016 08:49:10 GMT 1451 Server: example-server/0.1 1452 ETag: "6990548174277557683" 1453 Cache-Control: max-age=60 1454 Date: Wed, 04 May 2016 08:48:10 GMT 1455 Content-Type: application/cdni; ptype=ci-trigger-status 1457 { 1458 "ctime": 1462351690, 1459 "etime": 1462351698, 1460 "mtime": 1462351690, 1461 "status": "pending", 1462 "trigger": { 1463 "content.urls": [ 1464 "https://www.example.com/a/b/c/1", 1465 "https://www.example.com/a/b/c/2", 1466 "https://www.example.com/a/b/c/3", 1467 "https://www.example.com/a/b/c/4" 1468 ], 1469 "metadata.urls": [ 1470 "https://metadata.example.com/a/b/c" 1471 ], 1472 "type": "preposition" 1473 } 1474 } 1476 REQUEST: 1478 GET /triggers/1 HTTP/1.1 1479 User-Agent: example-user-agent/0.1 1480 Host: dcdn.example.com 1481 Accept: */* 1483 RESPONSE: 1485 HTTP/1.1 200 OK 1486 Content-Length: 545 1487 Expires: Wed, 04 May 2016 08:49:11 GMT 1488 Server: example-server/0.1 1489 ETag: "-554385204989405469" 1490 Cache-Control: max-age=60 1491 Date: Wed, 04 May 2016 08:48:11 GMT 1492 Content-Type: application/cdni; ptype=ci-trigger-status 1493 { 1494 "ctime": 1462351691, 1495 "etime": 1462351699, 1496 "mtime": 1462351691, 1497 "status": "pending", 1498 "trigger": { 1499 "content.patterns": [ 1500 { 1501 "case-sensitive": true, 1502 "pattern": "https://www.example.com/a/b/*" 1503 } 1504 ], 1505 "content.urls": [ 1506 "https://www.example.com/a/index.html" 1507 ], 1508 "metadata.patterns": [ 1509 { 1510 "pattern": "https://metadata.example.com/a/b/*" 1511 } 1512 ], 1513 "type": "invalidate" 1514 } 1515 } 1517 6.2.4. Polling for Changes in Status 1519 The uCDN SHOULD use the ETags of collections or Trigger Status 1520 Resources when polling for changes in status, as shown in the 1521 following examples: 1523 REQUEST: 1525 GET /triggers/pending HTTP/1.1 1526 User-Agent: example-user-agent/0.1 1527 Host: dcdn.example.com 1528 Accept: */* 1529 If-None-Match: "4331492443626270781" 1531 RESPONSE: 1533 HTTP/1.1 304 Not Modified Content-Length: 0 Expires: Wed, 04 May 1534 2016 08:49:11 GMT Server: example-server/0.1 ETag: 1535 "4331492443626270781" Cache-Control: max-age=60 Date: Wed, 04 May 2016 1536 08:48:11 GMT Content-Type: application/cdni; ptype=ci-trigger- 1537 collection 1539 REQUEST: 1541 GET /triggers/0 HTTP/1.1 1542 User-Agent: example-user-agent/0.1 1543 Host: dcdn.example.com 1544 Accept: */* 1545 If-None-Match: "6990548174277557683" 1547 RESPONSE: 1549 HTTP/1.1 304 Not Modified 1550 Content-Length: 0 1551 Expires: Wed, 04 May 2016 08:49:10 GMT 1552 Server: example-server/0.1 1553 ETag: "6990548174277557683" 1554 Cache-Control: max-age=60 1555 Date: Wed, 04 May 2016 08:48:10 GMT 1556 Content-Type: application/cdni; ptype=ci-trigger-status 1558 When the CI/T Trigger Command is complete, the contents of the 1559 filtered collections will be updated along with their ETags. For 1560 example, when the two example CI/T Trigger Commands are complete, the 1561 collections of pending and complete Trigger Status Resources might 1562 look like: 1564 REQUEST: 1566 GET /triggers/pending HTTP/1.1 1567 User-Agent: example-user-agent/0.1 1568 Host: dcdn.example.com 1569 Accept: */* 1571 RESPONSE: 1573 HTTP/1.1 200 OK 1574 Content-Length: 54 1575 Expires: Wed, 04 May 2016 08:49:15 GMT 1576 Server: example-server/0.1 1577 ETag: "1337503181677633762" 1578 Cache-Control: max-age=60 1579 Date: Wed, 04 May 2016 08:48:15 GMT 1580 Content-Type: application/cdni; ptype=ci-trigger-collection 1582 { 1583 "staleresourcetime": 86400, 1584 "triggers": [] 1585 } 1587 REQUEST: 1589 GET /triggers/complete HTTP/1.1 1590 User-Agent: example-user-agent/0.1 1591 Host: dcdn.example.com 1592 Accept: */* 1594 RESPONSE: 1596 HTTP/1.1 200 OK 1597 Content-Length: 152 1598 Expires: Wed, 04 May 2016 08:49:22 GMT 1599 Server: example-server/0.1 1600 ETag: "4481489539378529796" 1601 Cache-Control: max-age=60 1602 Date: Wed, 04 May 2016 08:48:22 GMT 1603 Content-Type: application/cdni; ptype=ci-trigger-collection 1605 { 1606 "staleresourcetime": 86400, 1607 "triggers": [ 1608 "https://dcdn.example.com/triggers/0", 1609 "https://dcdn.example.com/triggers/1" 1610 ] 1611 } 1613 6.2.5. Deleting Trigger Status Resources 1615 The uCDN can delete completed and failed Trigger Status Resources to 1616 reduce the size of the collections, as described in Section 4.4. For 1617 example, to delete the "preposition" request from earlier examples: 1619 REQUEST: 1621 DELETE /triggers/0 HTTP/1.1 1622 User-Agent: example-user-agent/0.1 1623 Host: dcdn.example.com 1624 Accept: */* 1626 RESPONSE: 1628 HTTP/1.1 204 No Content 1629 Date: Wed, 04 May 2016 08:48:22 GMT 1630 Content-Length: 0 1631 Content-Type: text/html; charset=UTF-8 1632 Server: example-server/0.1 1634 This would, for example, cause the collection of completed Trigger 1635 Status Resources shown in the example above to be updated to: 1637 REQUEST: 1639 GET /triggers/complete HTTP/1.1 1640 User-Agent: example-user-agent/0.1 1641 Host: dcdn.example.com 1642 Accept: */* 1644 RESPONSE: 1646 HTTP/1.1 200 OK 1647 Content-Length: 105 1648 Expires: Wed, 04 May 2016 08:49:22 GMT 1649 Server: example-server/0.1 1650 ETag: "-6938620031669085677" 1651 Cache-Control: max-age=60 1652 Date: Wed, 04 May 2016 08:48:22 GMT 1653 Content-Type: application/cdni; ptype=ci-trigger-collection 1655 { 1656 "staleresourcetime": 86400, 1657 "triggers": [ 1658 "https://dcdn.example.com/triggers/1" 1659 ] 1660 } 1662 6.2.6. Error Reporting 1664 In this example, the uCDN has requested pre-positioning of 1665 "https://newsite.example.com/index.html", but the dCDN was unable to 1666 locate metadata for that site: 1668 REQUEST: 1670 GET /triggers/2 HTTP/1.1 1671 User-Agent: example-user-agent/0.1 1672 Host: dcdn.example.com 1673 Accept: */* 1675 RESPONSE: 1677 HTTP/1.1 200 OK 1678 Content-Length: 486 1679 Expires: Wed, 04 May 2016 08:49:26 GMT 1680 Server: example-server/0.1 1681 ETag: "5182824839919043757" 1682 Cache-Control: max-age=60 1683 Date: Wed, 04 May 2016 08:48:26 GMT 1684 Content-Type: application/cdni; ptype=ci-trigger-status 1686 { 1687 "ctime": 1462351702, 1688 "errors": [ 1689 { 1690 "content.urls": [ 1691 "https://newsite.example.com/index.html" 1692 ], 1693 "description": "newsite.example.com not in HostIndex", 1694 "error": "emeta" 1695 } 1696 ], 1697 "etime": 1462351710, 1698 "mtime": 1462351706, 1699 "status": "active", 1700 "trigger": { 1701 "content.urls": [ 1702 "https://newsite.example.com/index.html" 1703 ], 1704 "type": "preposition" 1705 } 1706 } 1708 7. IANA Considerations 1710 7.1. CDNI Payload Type Parameter Registrations 1712 The IANA is requested to register the following new Payload Types in 1713 the "CDNI Payload Types" registry defined by [RFC7736], for use with 1714 the "application/cdni" MIME media type. 1716 +-----------------------+----------------+ 1717 | Payload Type | Specification | 1718 +-----------------------+----------------+ 1719 | ci-trigger-command | RFC 8007 | 1720 | ci-trigger-status | RFC 8007 | 1721 | ci-trigger-collection | RFC 8007 | 1722 +-----------------------+----------------+ 1724 7.2. "CDNI CI/T Trigger Types" Registry 1726 The IANA is requested to create a new "CDNI CI/T Trigger Types" 1727 subregistry under the "Content Delivery Network Interconnection 1728 (CDNI) Parameters" registry. 1730 Additions to the "CDNI CI/T Trigger Types" registry will be made via 1731 the RFC Required policy as defined in [RFC8126]. 1733 The initial contents of the "CDNI CI/T Trigger Types" registry 1734 comprise the names and descriptions listed in Section 5.2.2 of this 1735 document, with this document acting as the specification. 1737 7.3. "CDNI CI/T Error Codes" Registry 1739 The IANA is requested to create a new "CDNI CI/T Error Codes" 1740 subregistry under the "Content Delivery Network Interconnection 1741 (CDNI) Parameters" registry. 1743 Additions to the "CDNI CI/T Error Codes" registry will be made via 1744 the Specification Required policy as defined in [RFC8126]. The 1745 Designated Expert will verify that new Error Code registrations do 1746 not duplicate existing Error Code definitions (in name or 1747 functionality), prevent gratuitous additions to the namespace, and 1748 prevent any additions to the namespace that would impair the 1749 interoperability of CDNI implementations. 1751 The initial contents of the "CDNI CI/T Error Codes" registry comprise 1752 the names and descriptions of the Error Codes listed in Section 5.2.7 1753 of this document, with this document acting as the specification. 1755 8. Security Considerations 1757 The CI/T interface provides a mechanism to allow a uCDN to generate 1758 requests into the dCDN and to inspect its own CI/T requests and their 1759 current states. The CI/T interface does not allow access to, or 1760 modification of, the uCDN or dCDN metadata relating to content 1761 delivery or to the content itself. It can only control the presence 1762 of that metadata in the dCDN, and the processing work and network 1763 utilization involved in ensuring that presence. 1765 By examining "preposition" requests to a dCDN, and correctly 1766 interpreting content and metadata URLs, an attacker could learn the 1767 uCDN's or content owner's predictions for future content popularity. 1768 By examining "invalidate" or "purge" requests, an attacker could 1769 learn about changes in the content owner's catalog. 1771 By injecting CI/T Commands, an attacker or a misbehaving uCDN would 1772 generate work in the dCDN and uCDN as they process those requests. 1773 So would a man-in-the-middle attacker modifying valid CI/T Commands 1774 generated by the uCDN. In both cases, that would decrease the dCDN's 1775 caching efficiency by causing it to unnecessarily acquire or 1776 reacquire content metadata and/or content. 1778 A dCDN implementation of CI/T MUST restrict the actions of a uCDN to 1779 the data corresponding to that uCDN. Failure to do so would allow 1780 uCDNs to detrimentally affect each other's efficiency by generating 1781 unnecessary acquisition or reacquisition load. 1783 An origin that chooses to delegate its delivery to a CDN is trusting 1784 that CDN to deliver content on its behalf; the interconnection of 1785 CDNs is an extension of that trust to dCDNs. That trust relationship 1786 is a commercial arrangement, outside the scope of the CDNI protocols. 1787 So, while a malicious CDN could deliberately generate load on a dCDN 1788 using the CI/T interface, the protocol does not otherwise attempt to 1789 address malicious behavior between interconnected CDNs. 1791 8.1. Authentication, Authorization, Confidentiality, Integrity 1792 Protection 1794 A CI/T implementation MUST support Transport Layer Security (TLS) 1795 transport for HTTP (HTTPS) as per [RFC2818] and [RFC7230]. 1797 TLS MUST be used by the server side (dCDN) and the client side (uCDN) 1798 of the CI/T interface, including authentication of the remote end, 1799 unless alternate methods are used for ensuring the security of the 1800 information in the CI/T interface requests and responses (such as 1801 setting up an IPsec tunnel between the two CDNs or using a physically 1802 secured internal network between two CDNs that are owned by the same 1803 corporate entity). 1805 The use of TLS for transport of the CI/T interface allows the dCDN 1806 and the uCDN to authenticate each other using TLS client 1807 authentication and TLS server authentication. 1809 Once the dCDN and the uCDN have mutually authenticated each other, 1810 TLS allows: 1812 o The dCDN and the uCDN to authorize each other (to ensure that they 1813 are receiving CI/T Commands from, or reporting status to, an 1814 authorized CDN). 1816 o CDNI commands and responses to be transmitted with 1817 confidentiality. 1819 o Protection of the integrity of CDNI commands and responses. 1821 When TLS is used, the general TLS usage guidance in [RFC7525] MUST be 1822 followed. 1824 The mechanisms for access control are dCDN-specific and are not 1825 standardized as part of this CI/T specification. 1827 HTTP requests that attempt to access or operate on CI/T data 1828 belonging to another CDN MUST be rejected using, for example, HTTP 1829 403 ("Forbidden") or 404 ("Not Found"). This is intended to prevent 1830 unauthorized users from generating unnecessary load in dCDNs or uCDNs 1831 due to revalidation, reacquisition, or unnecessary acquisition. 1833 When deploying a network of interconnected CDNs, the possible 1834 inefficiencies related to the diamond configuration discussed in 1835 Section 2.2.1 should be considered. 1837 8.2. Denial of Service 1839 This document does not define a specific mechanism to protect against 1840 Denial-of-Service (DoS) attacks on the CI/T interface. However, CI/T 1841 endpoints can be protected against DoS attacks through the use of TLS 1842 transport and/or via mechanisms outside the scope of the CI/T 1843 interface, such as firewalling or the use of Virtual Private Networks 1844 (VPNs). 1846 Depending on the implementation, triggered activity may consume 1847 significant processing and bandwidth in the dCDN. A malicious or 1848 faulty uCDN could use this to generate unnecessary load in the dCDN. 1849 The dCDN should consider mechanisms to avoid overload -- for example, 1850 by rate-limiting acceptance or processing of CI/T Commands, or by 1851 performing batch processing. 1853 8.3. Privacy 1855 The CI/T protocol does not carry any information about individual end 1856 users of a CDN; there are no privacy concerns for end users. 1858 The CI/T protocol does carry information that could be considered 1859 commercially sensitive by CDN operators and content owners. The use 1860 of mutually authenticated TLS to establish a secure session for the 1861 transport of CI/T data, as discussed in Section 8.1, provides 1862 confidentiality while the CI/T data is in transit and prevents 1863 parties other than the authorized dCDN from gaining access to that 1864 data. The dCDN MUST ensure that it only exposes CI/T data related to 1865 a uCDN to clients it has authenticated as belonging to that uCDN. 1867 9. References 1869 9.1. Normative References 1871 [RFC1930] Hawkinson, J. and T. Bates, "Guidelines for creation, 1872 selection, and registration of an Autonomous System (AS)", 1873 BCP 6, RFC 1930, DOI 10.17487/RFC1930, March 1996, 1874 . 1876 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1877 Requirement Levels", BCP 14, RFC 2119, 1878 DOI 10.17487/RFC2119, March 1997, 1879 . 1881 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1882 Resource Identifier (URI): Generic Syntax", STD 66, 1883 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1884 . 1886 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1887 Protocol (HTTP/1.1): Message Syntax and Routing", 1888 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1889 . 1891 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1892 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1893 DOI 10.17487/RFC7231, June 2014, 1894 . 1896 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1897 Protocol (HTTP/1.1): Conditional Requests", RFC 7232, 1898 DOI 10.17487/RFC7232, June 2014, 1899 . 1901 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 1902 "Recommendations for Secure Use of Transport Layer 1903 Security (TLS) and Datagram Transport Layer Security 1904 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 1905 2015, . 1907 [RFC8006] Niven-Jenkins, B., Murray, R., Caulfield, M., and K. Ma, 1908 "Content Delivery Network Interconnection (CDNI) 1909 Metadata", RFC 8006, DOI 10.17487/RFC8006, December 2016, 1910 . 1912 [RFC8007] Murray, R. and B. Niven-Jenkins, "Content Delivery Network 1913 Interconnection (CDNI) Control Interface / Triggers", 1914 RFC 8007, DOI 10.17487/RFC8007, December 2016, 1915 . 1917 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1918 Writing an IANA Considerations Section in RFCs", BCP 26, 1919 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1920 . 1922 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1923 Interchange Format", STD 90, RFC 8259, 1924 DOI 10.17487/RFC8259, December 2017, 1925 . 1927 9.2. Informative References 1929 [I-D.greevenbosch-appsawg-cbor-cddl] 1930 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 1931 definition language (CDDL): a notational convention to 1932 express CBOR data structures", draft-greevenbosch-appsawg- 1933 cbor-cddl-11 (work in progress), July 2017. 1935 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 1936 DOI 10.17487/RFC2818, May 2000, 1937 . 1939 [RFC6707] Niven-Jenkins, B., Le Faucheur, F., and N. Bitar, "Content 1940 Distribution Network Interconnection (CDNI) Problem 1941 Statement", RFC 6707, DOI 10.17487/RFC6707, September 1942 2012, . 1944 [RFC7336] Peterson, L., Davie, B., and R. van Brandenburg, Ed., 1945 "Framework for Content Distribution Network 1946 Interconnection (CDNI)", RFC 7336, DOI 10.17487/RFC7336, 1947 August 2014, . 1949 [RFC7337] Leung, K., Ed. and Y. Lee, Ed., "Content Distribution 1950 Network Interconnection (CDNI) Requirements", RFC 7337, 1951 DOI 10.17487/RFC7337, August 2014, 1952 . 1954 [RFC7736] Ma, K., "Content Delivery Network Interconnection (CDNI) 1955 Media Type Registration", RFC 7736, DOI 10.17487/RFC7736, 1956 December 2015, . 1958 [RFC7975] Niven-Jenkins, B., Ed. and R. van Brandenburg, Ed., 1959 "Request Routing Redirection Interface for Content 1960 Delivery Network (CDN) Interconnection", RFC 7975, 1961 DOI 10.17487/RFC7975, October 2016, 1962 . 1964 Appendix A. Formalization of the JSON Data 1966 This appendix is non-normative. 1968 The JSON data described in this document has been formalized using 1969 the CBOR Data Definition Language (CDDL) 1970 [I-D.greevenbosch-appsawg-cbor-cddl] (where "CBOR" means "Concise 1971 Binary Object Representation"), as follows: 1973 CIT-object = CIT-command / Trigger-Status-Resource / Trigger-Collection 1975 CIT-command ; use media type application/cdni; ptype=ci-trigger-command 1976 = { 1977 ? trigger: Triggerspec 1978 ? cancel: [* URI] 1979 cdn-path: [* Cdn-PID] 1980 } 1982 Trigger-Status-Resource ; application/cdni; ptype=ci-trigger-status 1983 = { 1984 trigger: Triggerspec 1985 ctime: Absolute-Time 1986 mtime: Absolute-Time 1987 ? etime: Absolute-Time 1988 status: Trigger-Status 1989 ? errors: [* Error-Description] 1990 } 1991 Trigger-Collection ; application/cdni; ptype=ci-trigger-collection 1992 = { 1993 triggers: [* URI] 1994 ? staleresourcetime: int ; time in seconds 1995 ? coll-all: URI 1996 ? coll-pending: URI 1997 ? coll-active: URI 1998 ? coll-complete: URI 1999 ? coll-failed: URI 2000 ? cdn-id: Cdn-PID 2001 } 2003 Triggerspec = { ; see Section 5.2.1 2004 type: Trigger-Type 2005 ? metadata.urls: [* URI] 2006 ? content.urls: [* URI] 2007 ? content.ccid: [* Ccid] 2008 ? metadata.patterns: [* Pattern-Match] 2009 ? content.patterns: [* Pattern-Match] 2010 } 2012 Trigger-Type = "preposition" / "invalidate" 2013 / "purge" ; see Section 5.2.2 2015 Trigger-Status = "pending" / "active" / "complete" / "processed" 2016 / "failed" / "cancelling" / "cancelled" ; see Section 5.2.3 2018 Pattern-Match = { ; see Section 5.2.4 2019 pattern: tstr 2020 ? case-sensitive: bool 2021 ? match-query-string: bool 2022 } 2024 Absolute-Time = number ; seconds since UNIX epoch (Section 5.2.5) 2026 Error-Description = { ; see Section 5.2.6 2027 error: Error-Code 2028 ? metadata.urls: [* URI] 2029 ? content.urls: [* URI] 2030 ? metadata.patterns: [* Pattern-Match] 2031 ? content.patterns: [* Pattern-Match] 2032 ? description: tstr 2033 } 2035 Error-Code = "emeta" / "econtent" / "eperm" / "ereject" 2036 / "ecdn" / "ecanceled" ; see Section 5.2.7 2038 Ccid = tstr ; see RFC 8006 2039 Cdn-PID = tstr .regexp "AS[0-9]+:[0-9]+" 2041 URI = tstr 2043 Acknowledgments 2045 The authors thank Kevin Ma for his input, and Carsten Bormann for his 2046 review and formalization of the JSON data. 2048 Authors' Addresses 2050 Ori Finkelman 2051 Qwilt 2052 6, Ha'harash 2053 Hod HaSharon 4524079 2054 Israel 2056 Email: ori.finkelman.ietf@gmail.com 2058 Sanjay Mishra 2059 Verizon 2060 13100 Columbia Pike 2061 Silver Spring, MD 20904 2062 USA 2064 Email: sanjay.mishra@verizon.com 2066 Nir B. Sopher 2067 Qwilt 2068 6, Ha'harash 2069 Hod HaSharon 4524079 2070 Israel 2072 Email: nir@apache.org