idnits 2.17.1 draft-jenkins-cdni-metadata-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 : ---------------------------------------------------------------------------- == There are 11 instances of lines with non-RFC2606-compliant FQDNs in the document. -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 12, 2011) is 4603 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) == Outdated reference: A later version (-01) exists of draft-davie-cdni-framework-00 == Outdated reference: A later version (-04) exists of draft-zyp-json-schema-03 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Niven-Jenkins 3 Internet-Draft D. Ferguson 4 Intended status: Standards Track Velocix (Alcatel-Lucent) 5 Expires: March 15, 2012 G. Watson 6 BT 7 September 12, 2011 9 CDN Interconnect Metadata 10 draft-jenkins-cdni-metadata-00 12 Abstract 14 This document focuses on the CDNI Metadata interface, which enables 15 the CDNI Metadata function in a Downstream CDN to obtain CDNI 16 Metadata from an Upstream CDN so that the Downstream CDN can properly 17 process and respond to Redirection Requests received over the CDNI 18 Request Routing protocol and Request Routing and Content Requests 19 received directly from User Agents. 21 Requirements Language 23 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 24 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 25 document are to be interpreted as described in RFC 2119 [RFC2119]. 27 Status of this Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on March 15, 2012. 44 Copyright Notice 46 Copyright (c) 2011 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 63 2. CDNI Metadata Data Model . . . . . . . . . . . . . . . . . . . 5 64 3. CDNI Metadata Addressable Data Object Descriptions . . . . . . 6 65 3.1. SiteFeed . . . . . . . . . . . . . . . . . . . . . . . . . 7 66 3.2. Site . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 67 3.3. SelectionACL . . . . . . . . . . . . . . . . . . . . . . . 9 68 3.4. DeliveryACL . . . . . . . . . . . . . . . . . . . . . . . 9 69 3.5. Location . . . . . . . . . . . . . . . . . . . . . . . . . 10 70 4. CDNI Metadata Embedded Data Objects Descriptions . . . . . . . 10 71 4.1. DeliveryGlob . . . . . . . . . . . . . . . . . . . . . . . 11 72 5. CDNI Metadata Simple Data Type Descriptions . . . . . . . . . 11 73 5.1. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . 11 74 5.2. Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . 12 75 5.3. IPRange . . . . . . . . . . . . . . . . . . . . . . . . . 12 76 5.4. Pattern . . . . . . . . . . . . . . . . . . . . . . . . . 12 77 5.5. PatternFlags . . . . . . . . . . . . . . . . . . . . . . . 13 78 5.6. URI . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 79 6. CDNI Metadata interface . . . . . . . . . . . . . . . . . . . 13 80 6.1. MIME Media Types . . . . . . . . . . . . . . . . . . . . . 14 81 6.2. JSON Encoding of Objects . . . . . . . . . . . . . . . . . 15 82 6.3. JSON Encoding of Embedded Types . . . . . . . . . . . . . 16 83 6.3.1. PatternFlags . . . . . . . . . . . . . . . . . . . . . 16 84 6.3.2. Protocol . . . . . . . . . . . . . . . . . . . . . . . 17 85 6.3.3. Relationship / Link . . . . . . . . . . . . . . . . . 17 86 6.4. Retrieval of CDNI Metadata resources . . . . . . . . . . . 17 87 6.4.1. Bulk Retrieval of CDNI Metadata resources . . . . . . 18 88 6.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 19 89 6.5.1. SiteFeed . . . . . . . . . . . . . . . . . . . . . . . 20 90 6.5.2. Site . . . . . . . . . . . . . . . . . . . . . . . . . 20 91 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 92 8. Security Considerations . . . . . . . . . . . . . . . . . . . 22 93 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 22 94 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 95 10.1. Normative References . . . . . . . . . . . . . . . . . . . 22 96 10.2. Informative References . . . . . . . . . . . . . . . . . . 23 97 Appendix A. Relationship to the CDNI Requirements . . . . . . . . 24 98 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 24 100 1. Introduction 102 [I-D.jenkins-cdni-problem-statement] introduces the Problem scope for 103 CDN Interconnection (CDNI) and lists the four categories of 104 interfaces that may be used to compose a CDNI solution (Control, 105 Metadata, Request Routing, Logging). [I-D.davie-cdni-framework] 106 expands on the information provided in 107 [I-D.jenkins-cdni-problem-statement] and describes each of the 108 interfaces and the relationships between them in more detail. 110 This document focuses on the CDNI Metadata interface, which enables 111 the CDNI Metadata function in a Downstream CDN to obtain CDNI 112 Metadata from an Upstream CDN so that the Downstream CDN can properly 113 process and respond to: 115 o Redirection Requests received over the CDNI Request Routing 116 protocol. 117 o Request Routing and Content Requests received directly from User 118 Agents. 120 Specifically this document proposes: 122 o A set of data objects that are used to describe the different 123 aspects of CDNI Metadata along with a Data Model for CDNI Metadata 124 that expresses the relationships between the CDNI Metadata objects 125 (Section 2). 126 o An initial set of properties for the data objects in the CDNI 127 Metadata data model (Section 3 through Section 5). 128 o A RESTful web service for the transfer of CDNI Metadata data 129 objects (i.e. the CDNI Metadata interface) (Section 6). 131 Note: In order to make this document more accessible, it does not 132 attempt to articulate all the CDNI Metadata that would be required to 133 satisfy all CDNI use cases. Rather, a smaller set of properties are 134 proposed. These should be sufficient to implement a minimal 135 interconnect of basic HTTP delivery. Readers are encouraged to focus 136 on the overall structure of the protocol rather than on the details 137 or omission of particular properties. Additional properties may be 138 added in future drafts or may be better placed in separate documents 139 that focus on the CDNI Metadata required to interconnect delivery of 140 individual end-user protocols. 142 1.1. Terminology 144 This document reuses the terminology defined in 145 [I-D.jenkins-cdni-problem-statement]. 147 2. CDNI Metadata Data Model 149 The CDNI Metadata interface specified in this document utilizes two 150 types of Data Object: 152 o Addressable Data Objects, which are resources that may be 153 retrieved via their own URIs. 154 o Embedded Data Objects, which are contained within a property of an 155 Addressable Data Object. 157 Table 1 below defines the addressable data objects used by the CDNI 158 Metadata interface. 160 +--------------+----------------------------------------------------+ 161 | Data Object | Description | 162 +--------------+----------------------------------------------------+ 163 | SiteFeed | A SiteFeed object lists the Sites that may be | 164 | | delegated to the Downstream CDN. | 165 | Site | A Site object represents a customer-facing | 166 | | hostname that is used to serve content through | 167 | | including the rules for serving that content. | 168 | SelectionACL | A SelectionACL object restricts the Surrogates | 169 | | that can provide service for the associated Site | 170 | | to Surrogates in thre listed Locations. | 171 | DeliveryACL | A DeliveryACL object restricts the User Agent IP | 172 | | addresses that can access the associated Site or a | 173 | | URI pattern with the associated Site to User | 174 | | Agents in the listed Locations. | 175 | Location | A Location object represents a set of IP Address | 176 | | ranges. | 177 +--------------+----------------------------------------------------+ 179 Table 1: Content Distribution Metadata Data Objects 181 The only embedded data object defined is the DeliveryGlob object 182 within a Site object, which describes the rules to apply for 183 particular pattern based path matches within a Site. 185 The relationships between the different addressable CDNI Content 186 Distribution Metadata objects are described in Figure 1 and Table 2 187 below and the properties of each object are described in Section 3. 189 +------------+ 190 |SelectionACL+----------+ 191 +------------+ | 192 ^ | 193 | | 194 | v 195 +--------+ +--+-+ +--------+ 196 |SiteFeed+--------->|Site| |Location| 197 +--------+ +--+-+ +--------+ 198 | ^ 199 | | 200 v | 201 +-----------+ | 202 |DeliveryACL+----------+ 203 +-----------+ 204 Key: ----> = References 206 Figure 1: Relationships between CDNI Metadata Objects 208 +--------------+----------------------------------------------------+ 209 | Data Object | Objects it References | 210 +--------------+----------------------------------------------------+ 211 | SiteFeed | 0 or more Site objects. | 212 | Site | 0 or 1 SelectionACL objects. 0 or 1 DeliveryACL | 213 | | objects. | 214 | SelectionACL | 1 or more Location objects. | 215 | DeliveryACL | 1 or more Location objects. | 216 | Location | None. | 217 +--------------+----------------------------------------------------+ 219 Table 2: Relationships between CDNI Metadata Objects 221 3. CDNI Metadata Addressable Data Object Descriptions 223 Each of the sub-sections below describes the properties associated 224 with the data objects defined in Table 1. 226 The definition of each object is split into an ordered list of 227 relationships and an unordered set of properties. Relationships are 228 to other addressable data objects that are retrievable via the CDNI 229 Metadata interface. The only exception is the DeliveryProtocol 230 relationship which is to an 'opaque' URI representing the particular 231 feature set of a delivery protocol defined in a specification and 232 implemented in code. 234 Note: The names used for relationships (for example DeliveryProtocol) 235 are illustrative and selected for readability and intuitive 236 understanding of their meaning. If retained, a future version of 237 this document should list them out in the IANA considerations section 238 and request they are registered in the Link registry. 240 3.1. SiteFeed 242 Relationship: Lists 243 Description: A Site that the Upstream CDN may delegate the 244 delivery of to a Downstream CDN. 245 Allowed Target Types: Site 246 Cardinality: 0..* 248 Properties: None 250 3.2. Site 252 Relationship: DeliveryProtocol 253 Description: The Protocol to use for delivering this Site's 254 content. 255 Allowed Target Types: Protocol 256 Cardinality: 1 258 Relationship: RestrictsDelivery 259 Description: The DeliveryACL is used to restrict which End User 260 IP addresses are allowed access to the content of this Site. 261 If not present, there are no restrictions on which End Users 262 may receive the associated content (i.e. any End User IP 263 address can access the content). 264 Allowed Target Types: DeliveryACL 265 Cardinality: 0..1 267 Relationship: RestrictsSelection 268 Description: The SelectionACL is used to restrict which 269 Surrogates are allowed to serve the content of this Site. If 270 not present, there are no restrictions on which Surrogates may 271 deliver the associated content (i.e. any server can serve the 272 content). 273 Allowed Target Types: SelectionACL 274 Cardinality: 0..1 276 Property: active 277 Description: Whether delivery should be enabled for this Site. 278 Type: Boolean 279 Mandatory: No (default True) 281 Property: delivery.globs 282 Description: Path specific rules. First match applies. 283 Type: List of DeliveryGlob 284 Mandatory: No (default apply the properties defined in the Site 285 object to all paths) 287 Property: delivery.hostname 288 Description: The customer facing hostname for this site. 289 Type: Hostname 290 Mandatory: Yes 292 Property: delivery.query.remove 293 Description: A list of query parameter names. The listed query 294 parameters must be removed before checking for presence in the 295 cache or forwarding the request to the origin 296 Type: List of Strings 297 Mandatory: No (default pass full URI through) 299 Property: origin.basic.active 300 Description: Whether to use HTTP Basic authentication to the 301 Origin. 302 Type: Boolean 303 Mandatory: No (default False) 305 Property: origin.basic.password 306 Description: HTTP Basic auth password. Required if 307 origin.basic.active is true. 308 Type: String 309 Mandatory: No (default no password) 311 Property: origin.basic.username 312 Description: HTTP Basic auth username. Required if 313 origin.basic.active is true. 314 Type: String 315 Mandatory: No (default no username) 317 Property: origin.cookie.active 318 Description: Whether to use cookie-based authentication when 319 contacting the Origin server. 320 Type: Boolean 321 Mandatory: No (default False) 323 Property: origin.cookie.value 324 Description: Cookie value to be returned to origin for cookie- 325 based authentication. Required if origin.cookie.active is 326 True. 327 Type: String 328 Mandatory: No (default no cookie value) 330 Property: origin.endpoints 331 Description: Origins from which the Downstream CDN can acquire 332 content. These are not necessarily the actual origin servers 333 operated by the CSP but might be a set of Surrogates/servers in 334 the Upstream CDN. 335 Type: Set of Endpoints 336 Mandatory: Yes 338 3.3. SelectionACL 340 Relationship: SelectionAllow 341 Description: Surrogates in the referenced Location are allowed 342 to serve the content of this Site. 343 Allowed Target Types: Location 344 Cardinality: 0..* 346 Relationship: SelectionDeny 347 Description: Surrogates in the referenced Location are not 348 allowed to serve the content of this Site. 349 Allowed Target Types: Location 350 Cardinality: 0..* 352 Properties: None 354 Note: The order of Relationships within a SelectionACL is the order 355 in which the ACL MUST be processed. If a SelectionACL object does 356 not contain any of the above relationships (i.e. the object is empty) 357 the result is the equivalent of matching against a SelectionDeny 358 entry (i.e. any server is allowed to serve the associated content). 359 If the end of a SelectionACL is reached without matching any of its 360 entries the result is the equivalent of matching against a 361 SelectionDeny entry (i.e. no Surrogates are allowed to serve the 362 content of the Site). 364 3.4. DeliveryACL 366 Relationship: DeliveryAllow 367 Description: User Agents in the referenced Location are allowed 368 to receive the content of this Site/DeliveryGlob. 369 Allowed Target Types: Location 370 Cardinality: 0..* 372 Relationship: DeliveryDeny 373 Description: User Agents in the referenced Location are not 374 allowed to receive the content of this Site/DeliveryGlob. 376 Allowed Target Types: Location 377 Cardinality: 0..* 379 Relationship: DeliveryAuth 380 Description: The referenced URI represents an Authorisation 381 Server that must be queried to determine whether or not to 382 allow clients to receive the content of this Site/DeliveryGlob. 383 Allowed Target Types: URI 384 Cardinality: 0..1 386 Properties: None 388 Note: The order of Relationships within a DeliveryACL is the order in 389 which the ACL MUST be processed. If a DeliveryACL object does not 390 contain any of the above relationships (i.e. the object is empty) the 391 result is the equivalent of matching against a DeliveryDeny entry 392 (i.e. any User Agent IP address is allowed to receive the associated 393 content). If the end of an DeliveryACL is reached with matching any 394 of its entries the result is the equivalent of matching against a 395 DeliveryDeny entry (i.e. Delivery to the User Agent is not allowed). 397 3.5. Location 399 Relationships: None 401 Property: location.ip 402 Description: A set of IP Addresses. 403 Type: List of IPRange. 404 Mandatory: Yes 406 [Editor's Note: Location as specified above only supports the Class 407 1a names described in [I-D.jenkins-cdni-names]. Need to add support 408 for Class 1b names to a later version.] 410 4. CDNI Metadata Embedded Data Objects Descriptions 412 Each of the sub-sections below describes the data objects that are 413 embedded within one or more of the data objects described in 414 Section 3. 416 As in the previous section, the definition of each object is split 417 into its properties and its relationships. Relationships may be to 418 other objects that are retrievable via the CDNI Metadata interface. 420 4.1. DeliveryGlob 422 Relationship: RestrictsDelivery 423 Description: The DeliveryACL is used to restrict which End User 424 IP addresses are allowed access to the content matched by this 425 DeliveryGlob. If not present, there are no restrictions on 426 which End Users may receive the associated content (i.e. any 427 End User IP address can access the content). 428 Allowed Target Types: DeliveryACL 429 Cardinality: 0..1 431 Property: pattern.string 432 Description: String to match against the requested path, i.e. a 433 [RFC3986] path-absolute. 434 Type: Pattern. 435 Mandatory: Yes 437 Property: pattern.flags 438 Description: Flags to control the pattern match. 439 Type: PatternFlags. 440 Mandatory: No (default Case-sensitive infix matching) 442 Property: delivery.proxy 443 Description: If set to True then this pattern should be proxied 444 and not cached. 445 Type: Boolean. 446 Mandatory: No (default False) 448 5. CDNI Metadata Simple Data Type Descriptions 450 This section describes the simpler data types that are used for 451 properties of Addressable Data Objects and Embedded Data Objects. 453 5.1. Protocol 455 This type only appears in links. Links with this type are not 456 machine readable but rather represent particular feature sets of a 457 protocol defined in a specification and implemented in code. The URI 458 contained in the link needs to be defined for each delivery protocol 459 with an associated interoperable feature set. 461 The following examples are illustrative: 463 o http://url.cdni.ietf.example/protocol/delivery/http/rfcABCD 464 o http://url.cdni.ietf.example/protocol/delivery/rtmp/rfcEFGH 465 o http://url.vendorY.ietf.example/protocol/delivery/rtmp/releaseP.Q 467 [Editor's Note: It may be more appropriate to use the 'tag' URI 468 scheme [RFC4151] for these URIs.] 470 5.2. Endpoint 472 A hostname (with optional port) or an IP address (with optional 473 port). 475 Note: Client implementations MUST support IPv4 addresses encoded as 476 specified by the 'IPv4address' rule in Section 3.2.2 of [RFC3986] and 477 MUST support all IPv6 address formats specified in [RFC4291]. Server 478 implementations SHOULD use IPv6 address formats specified in 479 [RFC5952]. 481 5.3. IPRange 483 One of: 485 o A range of consecutive IP addresses (IPv4 or IPv6) expressed as 486 Address1-Address2 which does not have to be to power of two 487 aligned, for example the range 192.0.2.1-192.0.2.10 is valid. The 488 first Address in the range MUST be 'lower' than the final address 489 in the range. 490 o A valid IP subnet (IPv4 or IPv6) expressed using CIDR notation. 491 o A single IP address (IPv4 or IPv6). 493 Note: Client implementations MUST support IPv4 addresses encoded as 494 specified by the 'IPv4address' rule in Section 3.2.2 of [RFC3986] and 495 MUST support all IPv6 address formats specified in [RFC4291]. Server 496 implementations SHOULD use IPv6 address formats specified in 497 [RFC5952]. 499 5.4. Pattern 501 A pattern for string matching. The string may contain the wildcards 502 * and ?: 504 o * matches any sequence of characters (including the empty string). 505 o ? matches exactly one character. 507 Escaping: The three literals \ , * and ? should be escaped as \\, \* 508 and \? 510 5.5. PatternFlags 512 A set of flags indicating how a pattern match is made. The flags 513 are: 515 o Case-insensitive - Perform a case insensitive match (absence 516 indicates case-sensitive match). 517 o Prefix - Match against the start of the string (absence indicates 518 that a match may start anywhere in the string). 519 o Suffix - Match against the end of the string (absence indicates 520 that a match may end anywhere in the string). 522 Absence of both Prefix and Suffix results in a match against any part 523 of the string (infix). 525 5.6. URI 527 A URI as specified in [RFC3986]. 529 6. CDNI Metadata interface 531 This section specifies an interface to enable a Downstream CDN to 532 retrieve CDNI Metadata objects from an Upstream CDN. 534 The CDNI Metadata interface is built on the principles of RESTful web 535 services, in particular the use of hypermedia as the engine of 536 application state, and follows patterns established in The Atom 537 Syndication Format [RFC4287]. This means that requests and responses 538 over the interface are built around the transfer of representations 539 of hyperlinked resources. A resource in the context of the CDNI 540 Metadata interface is an Addressable Object in the Data Model (as 541 described in Section 2 through Section 3). 543 Requests are made over HTTP. The HTTP Method defines the operation 544 the request would like to perform. Servers implementing the CDNI 545 Metadata interface MUST support the HTTP GET and HEAD methods. The 546 corresponding HTTP Response returns the status of the operation in 547 the HTTP Status Code and returns the current representation of the 548 resource (if appropriate) in the Response Body. HTTP Responses from 549 servers implementing the CDNI Metadata interface that contain a 550 response body SHOULD include an ETag to enable validation of cached 551 versions of returned resources. 553 The CDNI Metadata interface specified in this document is a read-only 554 interface. Therefore support for other HTTP methods such as PUT, 555 POST and DELETE etc. is not specified. Server implementations of 556 this interface SHOULD reject all methods other than GET and HEAD. 558 The only representation specified in this document is JSON. 560 The interface can be used by a Downstream CDN to retrieve CDNI 561 Metadata objects either dynamically as required by the Downstream CDN 562 to process received requests (for example in response to receiving a 563 CDNI Request Routing request from an Upstream CDN or in response to 564 receiving a request for content from a User Agent) or in advance of 565 being required. 567 In the general case a CDNI Metadata server makes each instance of an 568 addressable CDNI Metadata object available via a unique URI that 569 returns a representation of that instance of that CDNI Metadata 570 object. When an object needs to reference another addressable CDNI 571 Metadata object (for example a Site object referencing a DeliveryACL 572 object) it does so by including a link to the referenced object. 574 The URI for the SiteFeed object needs to be either discovered by or 575 configured in the downstream CDN. All other objects/resources are 576 then discoverable from the SiteFeed object by following the links in 577 the SiteFeed object and the referenced Site objects. CDNI Metadata 578 servers are therefore free to assign whatever structure they desire 579 to the URIs for CDNI Metadata objects and CDNI Metadata clients MUST 580 NOT make any assumptions regarding the structure of CDNI Metadata 581 URIs or the mapping between CDNI Metadata objects and their 582 associated URIs. Therefore any URIs present in the examples below 583 are purely illustrative and are not intended impose a definitive 584 structure on CDNI Metadata interface implementations. 586 As the CDNI Metadata interface builds on top of HTTP, CDNI Metadata 587 servers may make use of any HTTP feature when implementing the CDNI 588 Metadata interface, for example a CDNI Metadata server may make use 589 of HTTP's caching mechanisms to indicate that the returned response/ 590 representation can be reused without re-contacting the CDNI Metadata 591 server. 593 6.1. MIME Media Types 595 Table 3 lists the MIME Media Type for each object (resource) that is 596 retrievable through the CDNI Metadata interface as well as the MIME 597 Media Type for the DeliveryProtocol relationship. 599 Note: A prefix of "vnd.cdni" is used, however it is expected that a 600 more appropriate prefix will be used if this document is accepted by 601 the CDNI WG. 603 +------------------+------------------------------------------------+ 604 | Data Object | MIME Media Type | 605 +------------------+------------------------------------------------+ 606 | SiteFeed | application/vnd.cdni.metadata.site.feed+json | 607 | Site | application/vnd.cdni.metadata.site+json | 608 | SelectionACL | application/ | 609 | | vnd.cdni.metadata.acl.selection+json | 610 | DeliveryACL | application/ | 611 | | vnd.cdni.metadata.acl.delivery+json | 612 | Location | application/vnd.cdni.metadata.location+json | 613 | DeliveryProtocol | application/vnd.cdni.metadata.protocol+json | 614 +------------------+------------------------------------------------+ 616 Table 3: MIME Media Types for CDNI Metadata resources 618 6.2. JSON Encoding of Objects 620 The "base" encoding for a CDNI Metadata object is a JSON object 621 containing a dictionary of (key,value) pairs where the keys are the 622 property names and the values are the associated property values. 624 The keys of the dictionary are the names of the properties associated 625 with the object and are therefore dependent on the specific object 626 being encoded (i.e. dependent on the MIME Media Type of the returned 627 resource). Likewise, the values associated with each key are 628 dependent on the specific object being encoded (i.e. dependent on the 629 MIME Media Type of the returned resource). 631 Dictionary keys in JSON are case sensitive and therefore any 632 dictionary key defined by this document (for example the names of 633 CDNI Metadata object properties) MUST always be represented in 634 lowercase. 636 In addition to the properties of the object, the following three 637 additional keys defined below may be present. 639 Key: base 640 Description: Provides a prefix for any relative URLs in the 641 object. This is similar to the XML base tag [XML-BASE]. If 642 absent, all URLs in the remainder of the document must be 643 absolute URLs. 644 Type: URI 645 Mandatory: No 647 Key: links 648 Description: The relationships of this object to other 649 addressable objects. 651 Type: List of Relationships. 652 Mandatory: Yes 653 Key: inline 654 Description: Dictionary containing additional objects that are 655 inlined within this object. The keys in the dictionary are 656 then then used to generate URI fragments which are used to 657 refer to inlined objects and the value is the Object itself. 658 Type: Dictionary of Objects. 659 Mandatory: No 661 Example SiteFeed Object: 663 { 664 "base": "http://metadata.cdni.example.com/sites/", 665 "links": [ 666 { 667 "title": "videos.example.net", 668 "href": "example1", 669 "rel": "Lists", 670 "type": "application/vnd.cdni.metadata.site+json" 671 }, 672 { 673 "title": "trailers.example.net", 674 "href": "http://metadata2.cdni.example.com/sites/example2", 675 "rel": "Lists", 676 "type": "application/vnd.cdni.metadata.site+json" 677 } 678 ], 679 } 681 6.3. JSON Encoding of Embedded Types 683 6.3.1. PatternFlags 685 JSON: A number calculated by adding together the values associated 686 with each flag that is set: 688 o 1 - Case-insensitive 689 o 2 - Prefix 690 o 4 - Suffix 692 Example of case-insensitive prefix match: 694 "pattern.flags": 3 696 6.3.2. Protocol 698 TBD 700 6.3.3. Relationship / Link 702 JSON: A dictionary with the following keys: 704 o href - The URI of the of the addressable object being referenced. 705 o rel - The Relationship between the referring object and the object 706 it is referencing. 707 o type - The MIME Media Type of the referenced object. See 708 Section 6.1 for the MIME Media Types of objects specified in this 709 document. 710 o title - An title for the for the Relationship/link. For the 711 "Lists" Relationships contained in a SiteFeed object the title key 712 MUST be present and MUST be the value of delivery.hostname for the 713 referenced Site object. For all other Relationships/links the 714 title key is optional. 716 Note: The above structure follows the pattern of atom:link in 717 [RFC4287]. 719 Example Relationship to a CDNI Metadata location within a 720 SelectionACL object: 722 { 723 "href": "http://metadata.cdni.example.com/locations/everywhere", 724 "rel": "SelectionAllow", 725 "type": "application/vnd.cdni.metadata.location+json" 726 } 728 6.4. Retrieval of CDNI Metadata resources 730 In the general case a CDNI Metadata server makes each instance of an 731 addressable CDNI Metadata object available via a unique URI and 732 therefore in order to retrieve CDNI Metadata, a CDNI Metadata client 733 first makes a HTTP GET request for the URI of the SiteFeed which 734 provides the CDNI Metadata client with a list of Sites (along with 735 their public facing hostnames) that the upstream CDN may delegate to 736 the downstream CDN. 738 In order to retrieve the CDNI Metadata for a particular Site the CDNI 739 Metadata client processes the received SiteFeed object and finds the 740 corresponding entry (using the title key to match against the 741 required public facing hostname if required) in the SiteFeed for the 742 Site it requires and can then can make a GET request for the URI 743 specified in the href key of that Site's entry in the SiteFeed. 745 In order to retrieve the SelectionACLs and DeliveryACLs associated 746 with that Site the CDNI Metadata client processes the received Site 747 object (as well as any DeliveryGlob objects embedded in the Site's 748 delivery.globs key) and can then can make a GET request for the URIs 749 specified in the href key of links within that Site or its 750 DeliveryGlobs that have a Relationship of RestrictsSelection and 751 RestrictsDelivery respectively. 753 Finally in order to retrieve the Locations associated with each ACL 754 the CDNI Metadata client processes the received ACL object(s) and can 755 then can make a GET request for the URIs specified in the href key of 756 links within that ACL that have a Relationship of Location. 758 6.4.1. Bulk Retrieval of CDNI Metadata resources 760 In addition to the general case where a CDNI Metadata server makes 761 each instance of an addressable CDNI Metadata object available via a 762 unique URI, in response to a request for a CDNI Metadata object a 763 CDNI Metadata Servers MAY include one or more of the addressable 764 objects referenced by the requested object inside the inline 765 dictionary of the referenced objects. 767 Inlined objects are referenced using a link in the normal way with 768 the exception that the href component of the link begins with # and 769 follows the fragment resolution protocol defined in 770 [I-D.zyp-json-schema]. 772 Use of the inline dictionary to include multiple addressable objects 773 has the advantage of reducing the number of requests a CDNI Metadata 774 client needs to make (and therefore reduces the additional latency 775 introduced by making multiple requests) in order to retrieve all the 776 CDNI Metadata it requires to process CDNI Request Routing requests 777 and User Agent requests for content. 779 However use of the inline dictionary has the disadvantage that the 780 cacheability of any inlined objects are tied to the cacheability of 781 the object they are inlined in. Some objects (for example Locations) 782 may not change very often and therefore could be cached for a longer 783 period of time than the objects that reference them. Or an object 784 (for example a SelectionACL) may be referenced by multiple other 785 objects and benefit from being cached separately in order to reduce 786 the size of the responses to requests for objects that reference it. 788 Example of an inline dictionary containing a DeliveryACL object: 790 "inline": { 791 "deliveryeverywhereacl": { 792 "links": [ 793 { 794 "href": 795 "http://metadata.cdni.example.com/locations/everywhere", 796 "rel": "DeliveryAllow", 797 "type": "application/vnd.cdni.metadata.location+json" 798 } 799 ] 800 } 801 } 803 Example of an inline dictionary containing a DeliveryACL object where 804 the Location referenced by the DeliveryACL is also inlined: 806 "inline": { 807 "deliveryeverywhereacl": { 808 "links": [ 809 { 810 "href": "#/inline/everywhere", 811 "rel": "DeliveryAllow", 812 "type": "application/vnd.cdni.metadata.location+json" 813 } 814 ] 815 }, 816 "everywhere": { 817 "location.ip": ["0.0.0.0", "::/0"] 818 } 819 } 821 Note: An alternative to using an inline key as described above would 822 be for the CDNI Metadata server to return a multipart/mixed response. 823 Using a multipart/mixed response would have the advantage that 824 inlined objects would not have to be tied to the cacheability of the 825 object they are inlined in (as they could have their own Cache- 826 Control headers) and could be cached separately from the object they 827 are inlined with (as they could have their own Location header). 828 However, using a multipart/mixed response would have the disadvantage 829 of requiring more complex processing by the CDNI Metadata client. 831 6.5. Examples 833 The following sections provide examples of different CDNI Metadata 834 objects encoded as JSON. 836 6.5.1. SiteFeed 838 Example SiteFeed: 840 { 841 "base": "http://metadata.cdni.example.com/sites/", 842 "links": [ 843 { 844 "title": "videos.example.net", 845 "href": "example1", 846 "rel": "Lists", 847 "type": "application/vnd.cdni.metadata.site+json" 848 }, 849 { 850 "title": "trailers.example.net", 851 "href": "http://metadata2.cdni.example.com/sites/example2", 852 "rel": "Lists", 853 "type": "application/vnd.cdni.metadata.site+json" 854 } 855 ], 856 } 858 6.5.2. Site 860 Example Site with inlined objects: 862 { 863 "base": "http://metadata.cdni.example.com/", 864 "links": [ 865 { 866 "href": "http://url.cdni.ietf.org/protocol/delivery/http/1.1", 867 "rel": "DeliveryProtocol", 868 "type": "application/vnd.cdni.metadata.protocol+json" 869 }, 870 { 871 "href": "#/inline/delivereverywhereacl", 872 "rel": "RestrictsDelivery", 873 "type": "application/vnd.cdni.acl.delivery+json" 874 }, 875 { 876 "href": "#/inline/servefromanywhereacl", 877 "rel": "RestrictsSelection", 878 "type": "application/vnd.cdni.acl.selection+json" 879 } 880 ], 881 "active": "true", 882 "delivery.hostname": "videos.example.net" 883 "origin.hostnames": ["origin.videos.example.net.cdni.example.com", 884 "origin.example.net"], 885 "delivery.globs": [ 886 { 887 "links": [ 888 { 889 "href": "#/inline/qaonlyacl", 890 "rel": "RestrictsDelivery", 891 "type": "application/vnd.cdni.acl.delivery+json" 892 } 893 ], 894 "pattern.string": "*/test_files/*", 895 "pattern.flags": 1, 896 "delivery.proxy": false 897 } 898 ], 899 "inline": { 900 "deliveryeverywhereacl": { 901 "links": [ 902 { 903 "href": "#/inline/everywhere", 904 "rel": "DeliveryAllow", 905 "type": "application/vnd.cdni.metadata.location+json" 906 } 907 ] 908 }, 909 "servefromanywhereacl": { 910 "links": [ 911 { 912 "href": "#/inline/everywhere", 913 "rel": "SelectionAllow", 914 "type": "application/vnd.cdni.metadata.location+json" 915 } 916 ] 917 }, 918 "qaonlyacl": { 919 "links": [ 920 { 921 "href": "#/inline/qa1", 922 "rel": "DeliveryAllow", 923 "type": "application/vnd.cdni.metadata.location+json" 924 }, 925 { 926 "href": "#/inline/qa2", 927 "rel": "DeliveryAllow", 928 "type": "application/vnd.cdni.metadata.location+json" 929 }, 930 { 931 "href": "#/inline/everywhere", 932 "rel": "DeliveryDeny", 933 "type": "application/vnd.cdni.metadata.location+json" 934 } 935 ] 936 }, 937 "everywhere": { 938 "location.ip": ["0.0.0.0", "::/0"] 939 }, 940 "qa1": { 941 "location.ip": ["192.0.2.1-192.0.2.10"] 942 }, 943 "qa2": { 944 "location.ip": ["198.51.100.1-198.51.100.15", 945 "198.51.100.200-198.51.100.254"] 946 } 947 } 948 } 950 7. IANA Considerations 952 TBD. 954 8. Security Considerations 956 TBD. 958 9. Acknowledgements 960 TBD. 962 10. References 964 10.1. Normative References 966 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 967 Requirement Levels", BCP 14, RFC 2119, March 1997. 969 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 970 Architecture", RFC 4291, February 2006. 972 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 973 Address Text Representation", RFC 5952, August 2010. 975 10.2. Informative References 977 [I-D.davie-cdni-framework] 978 Davie, B. and L. Peterson, "Framework for CDN 979 Interconnection", draft-davie-cdni-framework-00 (work in 980 progress), July 2011. 982 [I-D.jenkins-cdni-names] 983 Niven-Jenkins, B., "Thoughts on Naming and Referencing of 984 Data Objects within Content Distribution Network 985 Interconnection (CDNI) solutions", 986 draft-jenkins-cdni-names-00 (work in progress), 987 February 2011. 989 [I-D.jenkins-cdni-problem-statement] 990 Niven-Jenkins, B., Faucheur, F., and N. Bitar, "Content 991 Distribution Network Interconnection (CDNI) Problem 992 Statement", draft-jenkins-cdni-problem-statement-02 (work 993 in progress), March 2011. 995 [I-D.lefaucheur-cdni-requirements] 996 Leung, K., Lee, Y., Faucheur, F., Viveganandhan, M., and 997 G. Watson, "Content Distribution Network Interconnection 998 (CDNI) Requirements", 999 draft-lefaucheur-cdni-requirements-02 (work in progress), 1000 July 2011. 1002 [I-D.zyp-json-schema] 1003 Zyp, K. and G. Court, "A JSON Media Type for Describing 1004 the Structure and Meaning of JSON Documents", 1005 draft-zyp-json-schema-03 (work in progress), 1006 November 2010. 1008 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1009 Resource Identifier (URI): Generic Syntax", STD 66, 1010 RFC 3986, January 2005. 1012 [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", 1013 RFC 4151, October 2005. 1015 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1016 Syndication Format", RFC 4287, December 2005. 1018 [XML-BASE] 1019 Marsh, J., Ed. and R. Tobin, Ed., "XML Base (Second 1020 Edition) - http://www.w3.org/TR/xmlbase/", January 2009. 1022 Appendix A. Relationship to the CDNI Requirements 1024 Section 6 of [I-D.lefaucheur-cdni-requirements] lists the 1025 requirements for the CDNI Metadata Distribution interface. This 1026 section outlines which of those requirements are met by the CDNI 1027 Metadata interface specified in this document. 1029 Requirements R49 through R57 (inclusive) and R61 through R63 1030 (inclusive) are directly met by the interface specified in this 1031 document. 1033 Requirements R59 and R60 can be trivally met by defining additional 1034 properties for the CDNI Metadata objects defined in this document. 1036 It is the opinion of the authors that requirement R58 is better 1037 handled at Request Routing time by the CDNI Request Routing 1038 interface, rather than directly being met by the CDNI Metadata 1039 interface. 1041 Authors' Addresses 1043 Ben Niven-Jenkins 1044 Velocix (Alcatel-Lucent) 1045 326 Cambridge Science Park 1046 Milton Road, Cambridge CB4 0WG 1047 UK 1049 Email: ben@velocix.com 1051 David Ferguson 1052 Velocix (Alcatel-Lucent) 1053 326 Cambridge Science Park 1054 Milton Road, Cambridge CB4 0WG 1055 UK 1057 Email: david@velocix.com 1059 Grant Watson 1060 BT 1061 pp GDC 1 PP14, Orion Building, Adastral Park 1062 Martlesham, Ipswich IP5 3RE 1063 UK 1065 Email: grant.watson@bt.com