idnits 2.17.1 draft-goldstein-cdni-metadata-model-extensions-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 53 instances of too long lines in the document, the longest one being 16 characters in excess of 72. == There are 4 instances of lines with non-RFC2606-compliant FQDNs in the document. -- The draft header indicates that this document updates RFC8008, but the abstract doesn't seem to directly say this. It does mention RFC8008 though, so this could be OK. -- The draft header indicates that this document updates RFC8006, but the abstract doesn't seem to directly say this. It does mention RFC8006 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (7 March 2022) is 781 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'CDNI-MEL' is mentioned on line 2351, but not defined -- Looks like a reference, but probably isn't: '1' on line 963 -- Looks like a reference, but probably isn't: '2' on line 963 == Unused Reference: 'SVA' is defined on line 3534, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Possible downref: Non-RFC (?) normative reference: ref. 'W3C' -- Obsolete informational reference (is this intentional?): RFC 7694 (Obsoleted by RFC 9110) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group G. Goldstein 3 Internet-Draft W. Power 4 Updates: 8006, 8008 (if approved) Lumen Technologies 5 Intended status: Standards Track G. Bichot 6 Expires: 8 September 2022 Broadpeak 7 A. Siloniz 8 Telefonica 9 7 March 2022 11 CDNI Metadata Model Extensions 12 draft-goldstein-cdni-metadata-model-extensions-02 14 Abstract 16 The Content Delivery Network Interconnection (CDNI) Metadata 17 interface enables interconnected Content Delivery Networks (CDNs) to 18 exchange content distribution metadata in order to enable content 19 acquisition and delivery. To facilitate a wider set of use cases 20 such as Open Caching, this document describes extensions to the CDNI 21 Metadata object model and its associated Capabilities model as 22 documented in "CDNI Metadata" RFC8006 and "CDNI Request Routing: 23 Footprint and Capabilities Semantics" RFC8008 . 25 This document is a reflection of the content in the Streaming Video 26 Alliance specification titled "SVA Configuration Interface: Part 2 27 Extensions to CDNI Metadata Object Model". 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on 8 September 2022. 46 Copyright Notice 48 Copyright (c) 2022 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 53 license-info) in effect on the date of publication of this document. 54 Please review these documents carefully, as they describe your rights 55 and restrictions with respect to this document. Code Components 56 extracted from this document must include Revised BSD License text as 57 described in Section 4.e of the Trust Legal Provisions and are 58 provided without warranty as described in the Revised BSD License. 60 Table of Contents 62 1. Introduction and Scope . . . . . . . . . . . . . . . . . . . 4 63 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 64 1.2. Requirements Language . . . . . . . . . . . . . . . . . . 6 65 2. CDNI Metadata Model Extensions . . . . . . . . . . . . . . . 6 66 2.1. Cache Control Metadata . . . . . . . . . . . . . . . . . 8 67 2.1.1. MI.CachePolicy . . . . . . . . . . . . . . . . . . . 9 68 2.1.2. MI.NegativeCachePolicy . . . . . . . . . . . . . . . 11 69 2.1.3. MI.StaleContentCachePolicy . . . . . . . . . . . . . 12 70 2.1.4. MI.CacheBypassPolicy . . . . . . . . . . . . . . . . 14 71 2.1.5. MI.ComputedCacheKey . . . . . . . . . . . . . . . . . 16 72 2.2. Origin Access Metadata . . . . . . . . . . . . . . . . . 17 73 2.2.1. MI.SourceMetadataExtended . . . . . . . . . . . . . . 18 74 2.2.1.1. MI.SourceExtended . . . . . . . . . . . . . . . . 19 75 2.2.1.2. MI.LoadBalanceMetadata . . . . . . . . . . . . . 22 76 2.2.2. MI.Auth . . . . . . . . . . . . . . . . . . . . . . . 24 77 2.2.2.1. MI.HeaderAuth . . . . . . . . . . . . . . . . . . 24 78 2.2.2.2. MI.AWSv4Auth . . . . . . . . . . . . . . . . . . 26 79 2.3. Edge Control Metadata . . . . . . . . . . . . . . . . . . 28 80 2.3.1. MI.CrossOriginPolicy . . . . . . . . . . . . . . . . 28 81 2.3.1.1. MI.AccessControlAllowOrigin . . . . . . . . . . . 31 82 2.3.2. MI.AllowCompress . . . . . . . . . . . . . . . . . . 33 83 2.3.3. MI.TrafficType . . . . . . . . . . . . . . . . . . . 35 84 2.3.4. MI.OcnSelection . . . . . . . . . . . . . . . . . . . 36 85 2.3.4.1. MI.OcnDelivery . . . . . . . . . . . . . . . . . 37 86 2.4. Processing Stage Metadata . . . . . . . . . . . . . . . . 38 87 2.4.1. MI.ProcessingStages . . . . . . . . . . . . . . . . . 40 88 2.4.2. MI.StageRules . . . . . . . . . . . . . . . . . . . . 43 89 2.4.3. MI.ExpressionMatch . . . . . . . . . . . . . . . . . 45 90 2.4.4. MI.StageMetadata . . . . . . . . . . . . . . . . . . 46 91 2.4.5. MI.RequestTransform . . . . . . . . . . . . . . . . . 48 92 2.4.6. MI.ResponseTransform . . . . . . . . . . . . . . . . 49 93 2.4.7. MI.SyntheticResponse . . . . . . . . . . . . . . . . 50 94 2.4.8. MI.HeaderTransform . . . . . . . . . . . . . . . . . 52 95 2.4.9. MI.HTTPHeader . . . . . . . . . . . . . . . . . . . . 54 96 2.5. General Metadata . . . . . . . . . . . . . . . . . . . . 55 97 2.5.1. MI.ServiceIDs . . . . . . . . . . . . . . . . . . . . 55 98 2.5.2. MI.PrivateFeatureList . . . . . . . . . . . . . . . . 57 99 2.5.2.1. MI.PrivateFeature . . . . . . . . . . . . . . . . 58 100 2.5.3. MI.RequestRouting . . . . . . . . . . . . . . . . . . 59 101 3. Metadata Expression Language . . . . . . . . . . . . . . . . 60 102 3.1. Expression Variables . . . . . . . . . . . . . . . . . . 62 103 3.2. Expression Operators and keywords . . . . . . . . . . . . 63 104 3.3. Expression Built-in Functions . . . . . . . . . . . . . . 64 105 3.3.1. Basic Functions: Type Conversions . . . . . . . . . . 64 106 3.3.2. Basic Functions: String Conversions . . . . . . . . . 65 107 3.3.3. Convenience Functions . . . . . . . . . . . . . . . . 65 108 3.4. Error Handling . . . . . . . . . . . . . . . . . . . . . 66 109 3.4.1. Compile Time Errors . . . . . . . . . . . . . . . . . 66 110 3.4.2. Runtime Errors . . . . . . . . . . . . . . . . . . . 67 111 3.5. Expression Examples . . . . . . . . . . . . . . . . . . . 67 112 3.5.1. ComputedCacheKey . . . . . . . . . . . . . . . . . . 67 113 3.5.2. ExpressionMatch . . . . . . . . . . . . . . . . . . . 67 114 3.5.3. ResponseTransform . . . . . . . . . . . . . . . . . . 68 115 3.5.4. MI.ServiceIDs . . . . . . . . . . . . . . . . . . . . 68 116 4. CDNI Capabilities Extensions . . . . . . . . . . . . . . . . 69 117 4.1. FCI Metadata Object . . . . . . . . . . . . . . . . . . . 69 118 4.2. FCI Model Extensions . . . . . . . . . . . . . . . . . . 70 119 4.2.1. FCI.AuthTypes . . . . . . . . . . . . . . . . . . . . 70 120 4.2.2. FCI.ProcessingStages . . . . . . . . . . . . . . . . 72 121 4.2.3. FCI.SourceMetadataExtended . . . . . . . . . . . . . 73 122 4.2.4. FCI.RequestRouting . . . . . . . . . . . . . . . . . 74 123 4.2.5. FCI.PrivateFeatures . . . . . . . . . . . . . . . . . 75 124 4.2.5.1. FCI.PrivateFeature . . . . . . . . . . . . . . . 76 125 4.2.6. FCI.OcnSelection . . . . . . . . . . . . . . . . . . 76 126 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 77 127 5.1. CDNI Payload Types . . . . . . . . . . . . . . . . . . . 77 128 6. Security Considerations . . . . . . . . . . . . . . . . . . . 79 129 7. Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . 79 130 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 79 131 8.1. Normative References . . . . . . . . . . . . . . . . . . 79 132 8.2. Informative References . . . . . . . . . . . . . . . . . 80 133 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 81 135 1. Introduction and Scope 137 The Content Delivery Network Interconnection (CDNI) Metadata 138 interface enables interconnected Content Delivery Networks (CDNs) to 139 exchange content distribution metadata in order to enable content 140 acquisition and delivery. To facilitate a wider set of use cases 141 encountered in the commercial CDN and Open Caching ecosystems, this 142 document describes extensions to the CDNI Metadata object model and 143 its associated Capabilities model. 145 The objectives of this document are: 147 1. Identify the requirements for extending [RFC8006] and [RFC8008] 148 and specify a set of extensions that realize these requirements. 150 2. Maintain backward compatibility with [RFC8006] and [RFC8008] by 151 not altering the definitions or semantics of the original object 152 model. All extensions are defined as new GenericMetadata 153 Objects. 155 3. Define the metadata object model independently of the APIs used 156 to publish and retrieve metadata. 158 Scope this document ADDRESSES: 160 1. Define and register CDNI GenericMetadata objects, as defined in 161 section 4 of [RFC8006]. 163 2. Define and register CDNI Payload Types, as defined in section 7.1 164 of [RFC8006]. 166 3. Define Capabilities Objects that facilitate advertisement of a 167 dCDN's support of these new metadata features, extending 168 definitions in section 5 of [RFC8008]. 170 4. Specification of a Metadata Expression Language Section 3 used 171 within the metadata object model extensions. 173 5. Provide JSON examples illustrating real-world CDN and Open 174 Caching use cases. 176 Scope this document DOES NOT ADDRESS: 178 1. Metadata object model definitions already specified in [RFC8006]. 180 2. Interface API definitions for publishing and retrieving 181 configuration metadata. The Metadata Interface (MI) as defined 182 in [RFC8006] can be used to retrieve metadata. To enable more 183 sophisticated metadata configuration publishing workflows, the 184 Streaming Video Alliance (SVA) Open Caching API [OC-CI], as 185 documented in the SVA Configuration Interface Part 3 (Simple API) 186 and Part 4 (Advanced API) specifications can be used. 188 1.1. Terminology 190 For consistency with other CDNI documents this document follows the 191 CDNI convention of uCDN (upstream CDN) and dCDN (downstream CDN). It 192 should be noted, however, that uCDN and dCDN are roles that can be 193 played by a variety of entities in the distribution ecosystem. A 194 Content Provider, for example, can play the roles of a uCDN, while a 195 commercial CDN or Open Caching system can play either the roles of a 196 uCDN or dCDN. Additionally, this document reuses the terminology 197 defined in [RFC6707],[RFC7336], [RFC8006], [RFC8007] and [RFC8804]. 199 The following terms are used throughout this document: 201 * API - Application Programming Interface 203 * AWS - Amazon Web Services 205 * CDN - Content Delivery Network 207 * CDNi - CDN Interconnect 209 * CORS - Cross-Origin Resource Sharing 211 * CP - Content Provider 213 * dCDN - Downstream CDN 215 * DNS - Domain Name System 217 * FCI - Footprint and Capabilities Advertising Interface 219 * HREF - Hypertext Reference (link) 221 * HTTP - Hypertext Transfer Protocol 223 * IETF - Internet Engineering Task Force 225 * ISP - Internet Service Provider 227 * JSON - JavaScript Object Notation 229 * MEL - Metadata Expression Language 230 * Object - A collection of properties. 232 * OC - Open Caching 234 * OCN - Open Caching Node 236 * PatternMatch - An object which matches a string pattern 238 * UA - User Agent 240 * uCDN - Upstream CDN 242 * URI - Uniform Resource Identifier 244 * URN - Uniform Resource Name 246 * VOD - Video-on-Demand 248 * W3C - World Wide Web Consortium 250 1.2. Requirements Language 252 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 253 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 254 "OPTIONAL" in this document are to be interpreted as described in BCP 255 14 [RFC2119] [RFC8174] when, and only when, they appear in all 256 capitals, as shown here. 258 2. CDNI Metadata Model Extensions 260 This section details extensions to the CDNI Metadata model as defined 261 in Section 4 of [RFC8006], expressed as a set of new GenericMetadata 262 objects. To preserve backward compatibility with [RFC8006], no 263 changes are proposed to the original set of GenericMetadata. 265 +---------+ +---------+ +------------+ 266 |HostIndex++(*)+>+HostMatch++(1)+>+HostMetadata+------+(*)+-----+ 267 +---------+ +---------+ +------+-----+ | 268 + | 269 (*) + 270 + V 271 +-> Contains or references V ***************** 272 (1) One and only one +---------+ *GenericMetadata* 273 (*) Zero or more +--->+PathMatch| * Objects *<+ 274 | +----+---++ ***************** | 275 + + + ^ | 276 (*) (1) (1) +------------+ | | 277 + + +->+PatternMatch| | | 278 | V +------------+ | | 279 | +------------+ | | 280 +--+PathMetadata+------+(*)+-----+ | 281 +------------+ | 282 | 283 | 284 | 285 +---------------------------------------+ 286 | 287 + 288 New GenericMetadata Object by Categories (SVA) 289 +-------------------+ +-------------------+ +---------------------+ 290 | Cache Control | | Origin Access | |Client Access Control| 291 +-------------------+ +-------------------+ +---------------------+ 293 +-------------------+ +-------------------+ +---------------------+ 294 | Edge Control | | Processing Stages | | General Metadata | 295 +-------------------+ +-------------------+ +---------------------+ 297 Figure 1: CDNI Metadata Model with Extensions 299 The remainder of this section presents the extended set of 300 GenericMetadata objects organized by the categories in the above 301 diagram. 303 Note: In the following sections, the term "mandatory-to-specify" is 304 used to convey which properties MUST be included when serializing a 305 given capability object. When mandatory-to-specify is defined as 306 "Yes" for an individual property, it means that if the object 307 containing that property is included in a message, then the 308 mandatory-to-specify property MUST also be included. 310 2.1. Cache Control Metadata 312 In addition to the cache control policies currently specified by CDNI 313 metadata, content providers often need more fine-grained control over 314 CDN caching, including scenarios where it is desirable to override or 315 adjust cache-control headers from the origin. 317 The following additional capabilities are needed for general CDN and 318 open caching use cases: 320 1. Positive Cache Control - Allows the uCDN to specify internal 321 caching policies for the dCDN and external caching policies 322 advertised to clients of the dCDN, overriding any cache control 323 policy set in the response from the uCDN. 325 2. Negative Cache Control - Allows the specification of caching 326 policies based on error response codes received from the origin, 327 allowing for fine-grained control of the downstream caching of 328 error responses. For example, it may be desirable to cache error 329 responses at the dCDN for a short period of time to prevent an 330 overwhelmed origin service or uCDN from being flooded with 331 requests. 333 3. Cache Bypass Control - Allows content providers to bypass CDN 334 caching when needed (typically for testing or performance 335 benchmarking purposes). 337 4. Stale Content Policies - Allows control over how the dCDN should 338 process requests for stale content. For example, this policy 339 allows the content provider to specify that stale content be 340 served from cache for a specified time period while refreshes 341 from the origin occur asynchronously. 343 5. Dynamically Constructed Cache Keys - While the properties 344 provided by the standard CDNI metadata Cache object provide some 345 simple control over the construction of the cache key, it is 346 typical in advanced CDN configurations to generate cache keys 347 that are dynamically constructed via lightweight processing of 348 various properties of the HTTP request and/or response. As an 349 example, an origin may specify a cache key as a value returned in 350 a specific HTTP response header. A rich expression language is 351 provided to allow for such advanced cache key construction. 353 2.1.1. MI.CachePolicy 355 CachePolicy is a new GenericMetadata object that allows for the uCDN 356 to specify internal caching policies for the dCDN, as well as 357 external caching policies advertised to clients of the dCDN 358 (overriding any cache control policy set in the response from the 359 uCDN). 361 Property: internal 363 - Description: Specifies the internal cache control policy to be 364 used by the dCDN. 366 - Type: Number in seconds encoded as string (e.g. 5 is a five 367 second cache ) and/or a list of Enumeration [as-is|no-cache|no- 368 store] 370 - Mandatory-to-Specify: No. The default is to use the cache 371 control policy specified in the response from the uCDN. 373 Property: external 375 - Description: Specifies the external cache control policy to be 376 used by clients of this dCDN. 378 - Type: Number in seconds encoded as string (e.g. 5 is a five 379 second cache ) and/or a list of Enumeration [as-is|no-cache|no- 380 store] 382 - Mandatory-to-Specify: No. The default is to use the cache 383 control policy specified in the response from the uCDN. 385 Property: force 387 - Description: If set to True, the metadata interface cache 388 policy defined in the MI.CachePolicy will override any cache 389 control policy set in the response from the uCDN. If set to 390 False, the MI.CachePolicy is only used if there is no cache 391 control policy provided in the response from the uCDN. 393 - Type: Boolean 395 - Mandatory-to-Specify: No. The default is "False", which will 396 apply the MI.CachePolicy only if no policy is provided in the 397 response from the uCDN. 399 Example 1: An MI.CachePolicy that sets the internal cache control 400 policy to five seconds. The external cache policy is set to 'no- 401 cache': 403 { 404 "generic-metadata-type": "MI.CachePolicy", 405 "generic-metadata-value": { 406 "internal": "5", 407 "external": "no-cache", 408 "force": "true" 409 } 410 } 412 Example 2: An MI.CachePolicy that sets the internal cache control 413 policy to "as-is" (keep the policy set in the response from the 414 uCDN). The external cache policy is set to 'no-cache: 416 { 417 "generic-metadata-type": "MI.CachePolicy", 418 "generic-metadata-value": { 419 "internal": "as-is", 420 "external": "no-cache", 421 "force": "true" 422 } 423 } 425 Example 3: An MI.CachePolicy in the context of the processing stages 426 model that sets a caching policy only if the HTTP status code 427 received from the origin is a 200. In this example, the internal 428 cache control policy is set to five seconds. The external cache 429 policy is set to 'no-cache'. Force is set to 'False', indicating 430 that the MI.CachePolicy only applies if there is no cache policy in 431 the response from the uCDN. 433 { 434 "generic-metadata-type": "MI.ProcessingStages", 435 "generic-metadata-value": { 436 "origin-response": [ 437 { 438 "match": { 439 "expression": "resp.status == 200" 440 }, 441 "stage-metadata": { 442 "generic-metadata": [ 443 { 444 "generic-metadata-type": "MI.CachePolicy", 445 "generic-metadata-value": { 446 "internal": "5", 447 "external": "no-cache", 448 "force": "false" 449 } 450 } 451 ] 452 } 453 } 454 ] 455 } 456 } 458 2.1.2. MI.NegativeCachePolicy 460 NegativeCachePolicy is a new GenericMetadata object that allows for 461 the specification of caching policies based on error response codes 462 received from the origin. 464 Property: error-codes 466 - Description: Array of HTTP response error status codes (See 467 Sections 6.5 and 6.6 of [RFC7231] , that if returned from the 468 uCDN, will be cached using the cache policy defined by the 469 cache-policy property. 471 - Type: Array of HTTP response error status codes 473 - Values: ["404", "503", "504"] 475 - Mandatory-to-Specify: No. The default is to revert to 476 [RFC8006] behavior. 478 Property: cache-policy 479 - Description: MI.CachePolicy to apply to the HTTP response error 480 status codes returned by the uCDN. 482 - Mandatory-to-Specify: Yes 484 Example: A MI.NegativeCachePolicy that applies to HTTP error codes: 485 "404", "503", "504" and sets the internal cache control policy to 486 five seconds and external to 'no-cache'. 488 { 489 "generic-metadata-type": "MI.NegativeCachePolicy", 490 "generic-metadata-value": { 491 "error-codes": [ "404", "503", "504" ], 492 "cache-policy": { 493 "internal": "5", 494 "external": "no-cache", 495 "force": "true" 496 } 497 } 498 } 500 2.1.3. MI.StaleContentCachePolicy 502 MI.StaleContentCachePolicy is a new GenericMetadata object that 503 allows the uCDN to specify the policy to use by a dCDN when 504 responding with stale content. For example, this policy allows the 505 content provider to specify that stale content be served from cache 506 for a specified time period while refreshes from the origin occur 507 asynchronously. 509 Property: stale-while-revalidating 511 - Description: Instructs the dCDN to serve a stale version of a 512 resource while refreshing the resource with the uCDN. When set 513 to "True", the dCDN will return a previously cached version of 514 a resource while the resource is refreshed with the uCDN in the 515 background. 517 - Type: Boolean 519 - Mandatory-to-Specify: No. The default is False, which waits 520 for the uCDN to refresh a resource before responding to the 521 client. 523 Property: stale-if-error 524 - Description: Instructs the dCDN to serve a stale version of a 525 resource if an error was received when trying to refresh the 526 resource with the uCDN. When set, the dCDN will return a 527 previously cached version of a resource instead of caching the 528 error response. Per Section 4 of [RFC5861], an error is any 529 situation that would result in a 500, 502, 503, or 504 HTTP 530 response status code being returned 532 - Type: Array of HTTP response error status codes. Example: [ 533 "503", "504"] 535 - Mandatory-to-Specify: No. The default is to cache the error 536 response received from the uCDN. 538 Property: failed-refresh-ttl 540 - Description: Instructs the dCDN to serve a stale version of a 541 resource for the number of seconds specified in failed-refresh- 542 ttl before trying to revalidate the resource with the uCDN. 543 Use of failed-refresh-ttl allows the load to be reduced on the 544 uCDN during times of system stress. 546 - Type: Integer 548 - Mandatory-to-Specify: No 550 Example 1: A MI.StaleContentCachePolicy where stale-while- 551 revalidating is true, instructing the dCDN to respond with a stale 552 cached version of the resource while it refreshes the resource with 553 the uCDN in the background: 555 { 556 "generic-metadata-type": "MI.StaleContentCachePolicy", 557 "generic-metadata-value": { 558 "stale-while-revalidating": true 559 } 560 } 562 Example 2: A MI.StaleContentCachePolicy where stale-if-error 563 instructs the dCDN to use the stale cached resource if it receives an 564 error of type 503 or 504 when trying to refresh the resource with the 565 uCDN. 567 failed-refresh-ttl instructs the dCDN to use a five second cache TTL 568 on the resource that receives an error when refreshing from the uCDN. 569 That is, after five seconds, the dCDN will attempt to refresh the 570 resource with the uCDN. 572 { 573 "generic-metadata-type": "MI.StaleContentCachePolicy", 574 "generic-metadata-value": { 575 "stale-if-error": [ "503", "504" ], 576 "failed-refresh-ttl": "5" 577 } 578 } 580 Example 3: A MI.StaleContentCachePolicy where stale-while- 581 revalidating is true, instructing the dCDN to respond with a stale 582 cached version of the resource while it refreshes the resource with 583 the uCDN in the background. 585 stale-if-error instructs the dCDN to use the stale cached resource if 586 it receives an error of type 404, 503, or 504 when trying to refresh 587 the resource with the uCDN. 589 failed-refresh-ttl instructs the dCDN to use a five second cache TTL 590 on the resource that receives an error when refreshing from the uCDN. 591 That is, after five seconds, the dCDN will attempt to refresh the 592 resource with the uCDN. 594 { 595 "generic-metadata-type": "MI.StaleContentCachePolicy", 596 "generic-metadata-value": { 597 "stale-while-revalidating": "true", 598 "stale-if-error": [ "404", "503", "504" ], 599 "failed-refresh-ttl": "5" 600 } 601 } 603 2.1.4. MI.CacheBypassPolicy 605 CacheBypassPolicy is a new GenericMetadata object that allows a 606 client request to be set as non-cacheable. It is expected that this 607 feature will be used to allow clients to bypass cache when testing 608 the uCDN fill path. Note: CacheBypassPolicy is typically used in 609 conjunction with a path match or match expression on a header value 610 or query parameter. Any content previously cached (by client 611 requests that do not set CacheBypassPolicy) is not evicted. 613 Property: bypass-cache 615 - Description: A Boolean value that can activate the feature for 616 a given client request. It is expected that this feature will 617 be used within ProcessingStages to allow a client request to be 618 marked to bypass cache. 620 - Type: Boolean 622 - Mandatory-to-Specify: No. The default is False. 624 Example 1: A MI.CacheBypassPolicy with the client HTTP header of: 625 CDN-BYPASS: "True": 627 { 628 "generic-metadata-type": "MI.ProcessingStages", 629 "generic-metadata-value": { 630 "client-request": [ 631 { 632 "match": { 633 "expression": "req.h.cdn-bypass == 'true'" 634 }, 635 "stage-metadata": { 636 "generic-metadata": [ 637 { 638 "generic-metadata-type": "MI.CacheBypassPolicy", 639 "generic-metadata-value": { 640 "bypass-cache": "true" 641 } 642 } 643 ] 644 } 645 } 646 ] 647 } 648 } 650 Example 2: A MI.CacheBypassPolicy that applies to all requests where 651 the host header is bypass.example.com: 653 { 654 "generic-metadata-type": "MI.ProcessingStages", 655 "generic-metadata-value": { 656 "client-request": [ 657 { 658 "match": { 659 "expression": "req.h.host == 'bypass.example.com'" 660 }, 661 "stage-metadata": { 662 "generic-metadata": [ 663 { 664 "generic-metadata-type": "MI.CacheBypassPolicy", 665 "generic-metadata-value": { 666 "bypass-cache": "true" 667 } 668 } 669 ] 670 } 671 } 672 ] 673 } 674 } 676 2.1.5. MI.ComputedCacheKey 678 While the properties provided by the standard CDNi metadata Cache 679 object (See Section 4.2.6 of [RFC8006]) provide some simple control 680 over the construction of the cache key, it is typical in advanced CDN 681 configurations to generate cache keys that are dynamically 682 constructed via lightweight processing of various properties of the 683 HTTP request and/or response. As an example, an origin may specify a 684 cache key as a value returned in a specific HTTP response header. 686 ComputedCacheKey is a new GenericMetadata object that allows for the 687 specification of a cache key using the metadata expression language. 688 Typical use cases would involve the construction of a cache key from 689 one or more elements of the HTTP request. In cases where both the 690 ComputedCacheKey and the Cache object are applied, the 691 ComputedCacheKey will take precedence. 693 Property: expression 695 - Description: The expression that specifies how the cache key 696 shall be constructed. 698 - Type: String. An expression using [CDNI-MEL] to dynamically 699 construct the cache key from elements of the HTTP request and/ 700 or response. 702 - Mandatory-to-Specify: Yes 704 Example, using a custom request header as the cache key instead of 705 the URI path: 707 { 708 "generic-metadata-type": "MI.ComputedCacheKey", 709 "generic-metadata-value": { 710 "expression": "req.h.X-Cache-Key" 711 } 712 } 714 2.2. Origin Access Metadata 716 The CDNI metadata definitions for sources (also known as origins in 717 the CDN industry), are extended to provide the following capabilities 718 required: 720 1. Designation as to whether a source requires HTTPS access. 722 2. Specification of the source's TCP port number. 724 3. Web root path specification for the source. 726 4. Indication as to whether redirects should be followed. 728 5. Support for additional forms of origin authentication. 730 6. Multi-origin failover - The ability to specify a list of origins 731 that can act as fallbacks to the primary origin. Failure rules 732 can specify types of errors and timeout values that trigger 733 failover. 735 7. Multi-origin load balancing - The ability to specify a list of 736 origins that can be selected by one of several balancing rules 737 (round robin, content hash, IP hash). 739 8. Specification of SNI configurations required for origin access. 741 9. Specification of connection control parameters for origin access. 743 2.2.1. MI.SourceMetadataExtended 745 SourceMetadataExtended is an alternative to the CDNI standard 746 SourceMetadata object, which adds a property to specify load 747 balancing across multiple sources, as well as a SourceExtended sub- 748 object with additional attributes to the CDNI standard Source object. 749 While both SourceMetadataExtended and SourceMetadata can be provided 750 for backward compatibility, a dCDN that advertises capability for 751 SourceMetadataExtended will ignore SourceMetadata if both are 752 provided for a given host or path match. 754 Property: sources 756 - Description: Sources from which the dCDN can acquire content, 757 listed in order of preference. 759 - Type: Array of SourceExtended objects 761 - Mandatory-to-Specify: No. Default is to use static 762 configuration, out-of-band from the CDNI metadata interface. 764 Property: load-balance 766 - Description: Specifies load balancing rules for the set of 767 sources. 769 - Type: LoadBalanceMetadata object 771 - Mandatory-to-Specify: No 773 Example of a SourceMetadataExtended object with the associated 774 LoadBalanceMetadata configuration object: 776 { 777 "generic-metadata-type": "MI.SourceMetadataExtended", 778 "generic-metadata-value": { 779 "sources": [ 780 { 781 "endpoints": [ 782 "a.service123.ucdn.example", 783 "b.service123.ucdn.example" 784 ], 785 "protocol": "http/1.1" 786 }, 787 { 788 "endpoints": [ 789 "origin.service123.example" 790 ], 791 "protocol": "http/1.1" 792 } 793 ], 794 "load-balance": { 795 "balance-algorithm": "content-hash", 796 "balance-path-pattern": "^/prod/(.*)/.*\\.ts$" 797 } 798 } 799 } 801 2.2.1.1. MI.SourceExtended 803 SourceExtended is an alternative to the CDNI standard Source object 804 with additional metadata. It contains all the attributes of the 805 [RFC8006] Source object (acquisition-auth, endpoints, and protocol), 806 with additions specified below. 808 Property: acquisition-auth 810 - Description: Authentication method to use when requesting 811 content from this source. Same as [RFC8006]. 813 - Type: Auth (see [RFC8006] Section 4.2.7 and the new MI.Auth 814 types in this specification) 816 - Mandatory-to-Specify: No. Default is no authentication 817 required. 819 Property: endpoints 821 - Description: Origins from which the dCDN can acquire content. 822 If multiple endpoints are specified, they are all equal, i.e., 823 the list is not ordered by preference. Same as [RFC8006]. 825 - Type: Array of Endpoint objects (see [RFC8006] Section 4.3.3) 827 - Mandatory-to-Specify: Yes.. 829 Property: protocol 831 - Description: Network retrieval protocol to use when requesting 832 content from this source. Same as [RFC8006]. 834 - Type: Protocol (see [RFC8006] Section 4.3.2) 836 - Mandatory-to-Specify: Yes.. 838 Property: origin-host 840 - Description: HTTP host header to pass to the endpoints when 841 retrieving content from a uCDN. The host MUST conform to the 842 Domain Name System (DNS) syntax defined in [RFC1034] and 843 [RFC1123] 845 - Type: String 847 - Mandatory-to-Specify: No. The default is to use the host name 848 passed by the dCDN. 850 Property: webroot 852 - Description: The path element that is prepended to a resource's 853 URI before retrieving content from a uCDN. 855 - Type: String 857 - Mandatory-to-Specify: No. The default is to use the original 858 URI. 860 Property: follow-redirects 862 - Description: If the follow-redirects property is set to "True", 863 HTTP redirect responses returned from a uCDN will be followed 864 when retrieving content. Otherwise, the HTTP redirect response 865 is returned to the client. 867 - Type: Boolean 869 - Mandatory-to-Specify: No. The default is "True" (i.e., follow 870 redirect responses from the uCDN). 872 Property: timeout-ms 873 - Description: A timeout (in milliseconds) to apply when 874 connecting to a uCDN. If the connection is not established 875 within timeout-ms, this source is abandoned and the next source 876 in the MI.SourceMetadataExtended sources array is tried. Once 877 a connection is established, timeout-ms is used on subsequent 878 reads of data from the uCDN. 880 - Type: Integer 882 - Mandatory-to-Specify: No. The default is to revert to 883 [RFC8006] behavior. 885 Property: failover-errors 887 - Description: Array of HTTP response error status codes 888 (Section 6 of [RFC7231]), that if returned from the uCDN, will 889 trigger a failover to the next source in the 890 MI.SourceMetadataExtended sources array. If the uCDN returns 891 an HTTP error code that is not in the failover-errors array, 892 that error code is returned to the client of the dCDN. 894 - Type: Array of HTTP response error status codes. 896 - Mandatory-to-Specify: No. The default is to revert to 897 [RFC8006] behavior. 899 Example of a SourceExtended object that describes a pair of endpoints 900 (servers) that the dCDN can use to acquire content for the applicable 901 host and/or URI path: 903 { 904 "generic-metadata-type": "MI.SourceMetadataExtended", 905 "generic-metadata-value": { 906 "sources": [ 907 { 908 "endpoints": [ 909 "a.service123.ucdn.example", 910 "b.service123.ucdn.example:8443" 911 ], 912 "protocol": "https/1.1", 913 "origin-host": "internal.example.com", 914 "webroot": "/prod", 915 "follow-redirects": false, 916 "timeout-ms": 4000, 917 "failover-errors": [ "502", "503", "504" ] 918 }, 919 { 920 "endpoints": [ "origin.service123.example" ], 921 "protocol": "http/1.1", 922 "webroot": "/prod", 923 "follow-redirects": true, 924 "timeout-ms": 8000 925 } 926 ] 927 } 928 } 930 2.2.1.2. MI.LoadBalanceMetadata 932 The LoadBalanceMetadata object defines how content acquisition 933 requests are distributed over the SourceExtended objects listed in 934 the SourceMetadataExtended object. 936 Property: balance-algorithm 938 - Description: Specifies the algorithm to be used when 939 distributing content acquisition requests over the sources in a 940 SourceMetadataExtended object. The available algorithms are 941 random, content-hash, and ip-hash. 943 o random: Requests are distributed over the sources in proportion to 944 their associated weights. 946 o content-hash: Requests are distributed over the sources in a 947 consistent fashion, based on the balance-path-pattern property. 949 o ip-hash: Requests are distributed over the sources in a consistent 950 fashion based on the IP address of the client requestor. 952 1. Type: Enumeration [random|content-hash|ip-hash] encoded as a 953 lowercase string. 955 2. Mandatory-to-Specify: No. The default is to use sources in 956 preference order as defined in the SourceMetadataExtended object. 958 Property: balance-weights 960 - Description: This property specifies the relative frequency 961 that a source is used when distributing requests. For example, 962 if there are three SourceExtended objects in a 963 SourceMetadataExtended object with balance-weights [1, 2, 1], 964 source 1 will receive 1/4 of the requests; source 2 will 965 receive 2/4 of the requests; source 3 will receive 1/4 of the 966 requests. 968 - Type: Array of integers 970 - Mandatory-to-Specify: No. The default is to use sources in 971 preference order as defined in the SourceMetadataExtended 972 object. 974 Property: balance-path-pattern 976 - Description: This property specifies a regular expression 977 pattern to apply to the URI when calculating the content hash 978 used by the balance-algorithm. For example, "balance-path- 979 pattern": "^/prod/(.*)/.*\.ts$" would distribute requests based 980 on the URI but excluding the /prod prefix and the .ts segment 981 file. 983 - Type: String (regular expression) 985 - Mandatory-to-Specify: No. The default is to use the original 986 URI. 988 Example 1: The LoadBalanceMetadata object distributes content 989 acquisition requests over sources using a content-hash algorithm: 991 { 992 "generic-metadata-type": "MI.LoadBalanceMetadata", 993 "generic-metadata-value": { 994 "balance-algorithm": "content-hash", 995 "balance-path-pattern": "^/prod/(.*)/.*\\.ts$" 996 } 997 } 998 Example 2: The LoadBalanceMetadata object distributes content 999 acquisition requests over sources using the random algorithm: 1001 { 1002 "generic-metadata-type": "MI.LoadBalanceMetadata", 1003 "generic-metadata-value": { 1004 "balance-algorithm": "random", 1005 "balance-weights": [ 1, 2, 1 ] 1006 } 1007 } 1009 2.2.2. MI.Auth 1011 To meet the typical industry requirements for authenticating CDNs to 1012 external origins, two new authentication types are defined. 1014 auth-type: MI.HeaderAuth 1016 - Description: Header based authentication is used to pass an 1017 HTTP header (secret-name) and value (secret-value) to a uCDN 1018 when requesting content. The header name and value are agreed 1019 upon between parties out of band. 1021 - Note: We may want to add a way to encrypt or separately 1022 communicate the secret; this could be a general capability for 1023 CDNI. 1025 - auth-value: MI.HeaderAuth object specifying the header name and 1026 value (secret name, secret key) required for authenticated 1027 access to an origin. For more information, refer to the 1028 MI.HeaderAuth section below. 1030 auth-type: MI.AWSv4Auth 1032 - Description: Allows for the specification of a set of headers 1033 to be added to requests that are forwarded to an origin to 1034 enable Amazon Web Services (AWS) authentication, as documented 1035 by AWS (See Specifications & Standards References). 1037 - auth-value: MI.AWSv4Auth object specifying the access 1038 parameters. For more information, refer to the MI.AWSv4Auth 1039 section below. 1041 2.2.2.1. MI.HeaderAuth 1043 The HeaderAuth metadata object is used in the auth-value property of 1044 the 1045 Auth object, as defined in [RFC8006] section 4.2.7, and may be 1046 applied to any 1048 source by including or referencing it under its authentication 1049 property. This method of authentication provides a simple capability 1050 for a mutually agreed upon header to be added by the CDN to all 1051 requests sent to a specific origin. Note that if a dynamically 1052 generated header value is required, the RequestTransform capabilities 1053 within StageProcessing can be used. 1055 Property: header-name 1057 - Description: Name of the authentication header. 1059 - Type: String 1061 - Mandatory-to-Specify: Yes 1063 Property: header-value 1065 - Description: Value of the authentication header (typically a 1066 pre-shared key). Note that this value SHOULD NOT be disclosed; 1067 it SHOULD be protected by some mechanism such as a secret- 1068 sharing API, which is outside the scope of this specification. 1070 - Type: String 1072 - Mandatory-to-Specify: Yes 1074 Example Auth object for header authentication: 1076 { 1077 "generic-metadata-type": "MI.SourceMetadataExtended", 1078 "generic-metadata-value": { 1079 "sources": [ 1080 { 1081 "endpoints": [ "origin.example.com" ], 1082 "protocol": "http/1.1", 1083 "acquisition-auth": { 1084 "generic-metadata-type": "MI.Auth", 1085 "generic-metadata-value": { 1086 "auth-type": "MI.HeaderAuth", 1087 "auth-value": { 1088 "header-name": "X-Origin-Auth", 1089 "header-value": "SECRETKEYJKSDHFSIFUI4UFH78HW4NF7" 1090 } 1091 } 1092 } 1093 } 1094 ] 1095 } 1096 } 1098 2.2.2.2. MI.AWSv4Auth 1100 The AWSv4Auth metadata object is used in the auth-value property of 1101 the Auth object as defined in [RFC8006] section 4.2.7, and may be 1102 applied to any source by including or referencing it under its 1103 authentication property. 1105 AWSv4 authentication causes upstream requests to have a signature 1106 applied, following the method described in [AWSv4Method]. A hash- 1107 based signature is calculated over the request URI and specified 1108 headers, and provided in an Authorization: header on the upstream 1109 request. The signature is tied to a pre-shared secret key specific 1110 to an AWS service, region, and key ID. 1112 1. We may want to add a way to encrypt or separately communicate the 1113 secret; this could be a general capability for CDNI. 1115 2. We may want to add optional properties that allow overriding the 1116 default headers to sign. 1118 3. We may want to add optional properties that allow the signature 1119 to be sent in a way other than with the Authorization: header 1120 (e.g., query strings are also supported). 1122 Property: access-key-id 1123 - Description: The preconfigured ID of the pre-shared 1124 authorization secret. 1126 - Type: String 1128 - Mandatory-to-Specify: Yes 1130 Property: secret-access-key 1132 - Description: The pre-shared authorization secret, which is the 1133 basis of building the signature. This is a secret key that 1134 SHOULD NOT be disclosed; it SHOULD be protected by some 1135 mechanism such as a secret-sharing API, which is outside the 1136 scope of this specification. 1138 - Type: String 1140 - Mandatory-to-Specify: Yes 1142 Property: aws-region 1144 - Description: The AWS region name that is hosting the service 1145 and shares the key ID and corresponding pre-shared secret. 1147 - Type: String 1149 - Mandatory-to-Specify: Yes 1151 Property: aws-service 1153 - Description: The AWS service name that is serving the upstream 1154 requests. 1156 - Type: String 1158 - Mandatory-to-Specify: No. It defaults to "s3" if not 1159 specified. 1161 Property: host-name 1163 - Description: The host name to use as part of the signature 1164 calculation. 1166 - Type: String 1167 - Mandatory-to-Specify: No. It defaults to using the value of 1168 the Host: header of the upstream request. This property is 1169 available in case the application needs to override that 1170 behavior. 1172 Example Auth object for AWSv4 authentication: 1174 { 1175 "generic-metadata-type": "MI.SourceMetadataExtended", 1176 "generic-metadata-value": { 1177 "sources": [ 1178 { 1179 "endpoints": [ "origin.example.com" ], 1180 "protocol": "http/1.1", 1181 "acquisition-auth": { 1182 "generic-metadata-type": "MI.Auth", 1183 "generic-metadata-value": { 1184 "auth-type": "MI.AWSv4Auth", 1185 "auth-value": { 1186 "access-key-id": "MYACCESSKEYID", 1187 "secret-access-key": "SECRETKEYJKSDHFSIUHKWRGHHF", 1188 "aws-region": "us-west-1" 1189 } 1190 } 1191 } 1192 } 1193 ] 1194 } 1195 } 1197 2.3. Edge Control Metadata 1199 CDNs typically require a set of configuration metadata to inform 1200 processing of responses downstream (at the edge and in the user 1201 agent). This section specifies GenericMetadata objects to meet those 1202 requirements. 1204 2.3.1. MI.CrossOriginPolicy 1206 Delegation of traffic between a CDN over an open caching node based 1207 on HTTP redirection does change the domain name in the client 1208 requests. This represents a cross-origin request that must be 1209 managed appropriately using Cross-Origin Resource Sharing (CORS) 1210 headers in the responses. 1212 The dynamic generation of CORS headers is typical in modern HTTP 1213 request processing and avoids CORS validation forwarded to the CDN 1214 origin servers, particularly with the preflight OPTIONS requests. 1215 The CDNI metadata model requires extensions to specify how a CDN or 1216 open caching node should generate and evaluate these headers. 1218 Required capabilities: 1220 1. Set a default value for CORS response headers independent of the 1221 origin request header value. 1223 2. Match the origin request header with a list of valid values, 1224 including PatternMatch, to return or not return the CORS response 1225 headers. 1227 3. Set a list of custom headers that can be exposed to the client 1228 (expose headers). 1230 4. Support for preflight requests using the OPTIONS method, 1231 including custom header validation, expose headers, and methods. 1233 5. Support for credentials validation within CORS. 1235 Simple CORS requests are those where both HTTP method and headers in 1236 the request are included in the safe list defined by the World Wide 1237 Web Consortium [W3C]. The user agent (UA) request can include an 1238 origin header set to the URL domain of the webpage that the player 1239 runs. Depending on the metadata configuration, the logic to apply by 1240 the open caching node (OCN) is: 1242 1. Validation of the origin header - Metadata can include a list of 1243 valid domains to validate the request origin header. If it does 1244 not match, the CORS header must not be included in the response. 1246 2. WIldcard usage - Depending on the configuration, the resultant 1247 CORS header to include in the response will be the same as the 1248 request origin header, or a wildcard. 1250 3. If no validation of request is included in the origin header, set 1251 a default value for CORS response headers independent of the 1252 origin request header value. 1254 When a UA makes a request that includes a method or headers that are 1255 not included in the safe-list, the client will make a CORS preflight 1256 request using the OPTIONS method to the resource including the origin 1257 header. If CORS is enabled and the requests passes the origin 1258 validation, the OCN SHOULD respond with the set of headers that 1259 indicate what is permitted for that resource, including one or more 1260 of the following: 1262 1. Allowed methods 1264 2. Allowed credentials 1266 3. Allowed request headers 1268 4. Max age that the OPTIONS request is valid 1270 5. Headers that can be exposed to the client 1272 CrossoriginPolicy is a GenericMetadata object that allows for the 1273 specification of dynamically generated CORS headers. 1275 Property: allow-origin 1277 - Description: Validation of simple CORS requests. 1279 - Type: Object MI.AccessControlAllowOrigin 1281 - Values: One element for each of the following properties. 1283 - Mandatory-to-Specify: Yes 1285 Property: expose-headers 1287 - Description: A list of values the OCN will include in the 1288 Access-Control-Expose-Headers response header to a preflight 1289 request. 1291 - Type: Array of strings 1293 - Mandatory-to-Specify: No 1295 Property: allow-methods 1297 - Description: A list of values the OCN will include in the 1298 Access-Control-Allow-Methods response header to a preflight 1299 request. 1301 - Type: Array of strings 1302 - Mandatory-to-Specify: No 1304 Property: allow-headers 1306 - Description: A list of values the OCN will include in the 1307 Access-Control-Allow-Headers response header to a preflight 1308 request. 1310 - Type: Array of strings 1312 - Mandatory-to-Specify: No 1314 Property: allow-credentials 1316 - Description: The value the OCN will include in the Access- 1317 Control-Allow-Credentials response header to a preflight 1318 request. 1320 - Type: Boolean 1322 - Mandatory-to-Specify: No 1324 Property: max-age 1326 - Description: The value the OCN will include in the Access- 1327 Control-Max-Age response header to a preflight request. 1329 - Type: Integer 1331 - Mandatory-to-Specify: No 1333 2.3.1.1. MI.AccessControlAllowOrigin 1335 The MI.AccessControlAllowOrigin object has the following properties: 1337 Property: allow-list 1339 - Description: List of valid URLs that will be used to match the 1340 request origin header. The Origin header is a HTTP extension. 1341 Its value is a version of the Referer header in some specific 1342 requests, and used for Cross Origin requests. . Permitted 1343 values are schema://hostname[:port] 1345 - Type: Array of PatternMatch objects 1347 - Mandatory-to-Specify: Yes 1349 Property: wildcard-return 1350 - Description: If "True", the OCN will include a wildcard (*) in 1351 the Access-Control-Allow-Origin response header. If "False", 1352 the OCN will reflect the request origin header in the Access- 1353 Control-Allow-Origin response header. 1355 - Type: Boolean 1357 - Mandatory-to-Specify: Yes 1359 The examples below demonstrate how to configure response headers 1360 dynamically for CORS validation. 1362 Example 1: A simple CORS validation configuration: 1364 { 1365 "generic-metadata-type": "MI.CrossoriginPolicy", 1366 "generic-metadata-value": { 1367 "allow-origin": { 1368 "allow-list": [ 1369 { 1370 "pattern": "*" 1371 } 1372 ], 1373 "wildcard-return": true 1374 } 1375 } 1376 } 1378 Example 2: Validation of a preflight request when some of the headers 1379 included in the subsequent object request are not included in the 1380 CORS specification safelist: 1382 { 1383 "generic-metadata-type": "MI.CrossoriginPolicy", 1384 "generic-metadata-value": { 1385 "allow-origin": { 1386 "allow-list": [ 1387 { 1388 "pattern": "*://sourcepage.example.com" 1389 }, 1390 "wildcard-return": false 1391 }, 1392 "allow-methods": [ "GET", "POST" ], 1393 "allow-credentials": true, 1394 "allow-headers": [ "X-PINGOTHER", "Content-Type" ], 1395 "expose-headers": [ "X-User", "Authorization" ], 1396 "max-age": 3600 1397 } 1398 } 1399 } 1401 2.3.2. MI.AllowCompress 1403 Downstream CDNs often have the ability to compress HTTP response 1404 bodies in cases where the client has declared that it can accept 1405 compressed responses (via an Accept-Encoding header), but the source/ 1406 origin has returned an uncompressed response. 1408 The specific compression algorithm used by the dCDN is negotiated by 1409 the client's Accept-Encoding header according to [RFC7694] (including 1410 q= preferences) and the compression capabilities available on the 1411 dCDN. 1413 In addition, HeaderTransform allows the uCDN to normalize, or modify, 1414 the Accept-Encoding header to allow for fine-grain control over the 1415 selection of the compression algorithm (e.g., gzip, compress, 1416 deflate, br, etc.). 1418 AllowCompress is a new GenericMetadata object that allows the dCDN to 1419 compress content before sending to the client. 1421 Property: allow-compress 1423 - Description: If set to "True", then the dCDN will try to 1424 compress the response to the client based on the Accept- 1425 Encoding request header. 1427 - Type: Boolean 1429 - Values: True or False 1430 - Mandatory-to-Specify: No. The default is "False". 1432 Example 1: An MI.AllowCompress that allows manifests (*.m3u8) to be 1433 compressed by the dCDN: 1435 { 1436 "match": { 1437 "expression": "req.h.uri *= '*.m3u8'" 1438 }, 1439 "stage-metadata": { 1440 "generic-metadata": [ 1441 { 1442 "generic-metadata-type": "MI.AllowCompress", 1443 "generic-metadata-value": { 1444 "allow-compress": "true" 1445 } 1446 } 1447 ] 1448 } 1449 } 1451 Example 2: An MI.AllowCompress that allows manifests (*.m3u8) to be 1452 compressed by the dCDN but normalizing the client's Accept-Encoding 1453 header: 1455 { 1456 "match": { 1457 "expression": "req.h.accept-encoding *= '*gzip*'" 1458 }, 1459 "stage-metadata": { 1460 "generic-metadata": [ 1461 { 1462 "generic-metadata-type": "MI.AllowCompress", 1463 "generic-metadata-value": { 1464 "allow-compress": "true" 1465 } 1466 } 1467 ] 1468 } 1469 } 1471 2.3.3. MI.TrafficType 1473 Content delivery networks often apply different infrastructure, 1474 network routes, and internal metadata for different types of traffic. 1475 Delivery of large static objects (such as software downloads), may, 1476 for example, use different network routes than video stream delivery. 1477 In an HTTP adaptive bitrate video service, every video title 1478 corresponds to a set of video files and descriptors according to 1479 different video protocols, and this is independent of the type of 1480 service (Video-on-Demand, Live, Catch-up, etc.). 1482 The way the video service is consumed by the user agents can vary. 1483 For instance, a segment that belongs to a Video-on-Demand (VoD) title 1484 can be requested for every moment the content is available for the 1485 user agents to consume, while a segment of live content will be only 1486 requested as long as the time-shift duration is configured for that 1487 service. Knowing those differences, a CDN or OCN provider can 1488 implement specific strategies that will maximize performance and 1489 thereby provide more available capacity to the upstream provider. It 1490 should be noted that the dCDNs handling of the traffic types is 1491 implementation-specific and not prescribed here. 1493 TrafficType metadata defines a set of descriptors that characterize 1494 either the type or usage of the traffic, enabling CDNs and OCNs to 1495 apply any internal configuration rules without exposing an 1496 unnecessary number of internal details. Note that the interpretation 1497 of these traffic types and application of rules such as rate limiting 1498 or delivery pacing are implementation specific. 1500 Property: traffic-type 1502 - Description: A literal that defines the traffic type. uCDN will 1503 use the literal that is most representative of the traffic 1504 being delegated. 1506 - Type: Enumeration [vod, live, object-download] encoded as 1507 lowercase string 1509 - Mandatory-to-Specify: Yes 1511 Property: hints 1513 - Description: Other traffic characteristics that the uCDN can 1514 indicate to the dCDN as suggestions for service optimization. 1515 Accepts free-form unconstrained values. 1517 - Type: Array of strings 1518 - Mandatory-to-Specify: No 1520 A TrafficType definition example for HostMetadata: 1522 { 1523 "generic-metadata-type": "MI.TrafficType", 1524 "generic-metadata-value": { 1525 "traffic-type": "vod", 1526 "hints": [ "low-latency", "catch-up" ] 1527 } 1528 } 1530 2.3.4. MI.OcnSelection 1532 Configuration metadata is required to permit several levels of OCN 1533 selection policies. For example, in a mobile network, several 1534 physical locations are possible (i.e., candidates) for hosting the 1535 OCN that will take charge in the delegation for the uCDN. This is 1536 the case when the cache is virtualized and deployed dynamically. 1537 Depending on the OCN selection policy (which may be a cost driver), 1538 the dCDN may attempt to favor certain types of caches at the edge, 1539 for example. The default OCN selection policy might be "best- 1540 effort". Another one might be linked to the network characteristics 1541 like "Edge" or ("average latency< 10ms"). 1543 OcnSelection is a new GenericMetadata object that allows the uCDN to 1544 indicate to the dCDN a preference in terms of OCN selection. 1546 Property: ocn-delivery 1548 - Description: Instructs the dCDN to perform delegation operating 1549 a particular medium and/or a transport arrangement. 1551 - Type: Object MI.OcnDelivery 1553 - Mandatory-to-Specify: No. At least one of the two properties, 1554 ocn-type or ocn-delivery, must be present. 1556 Property: ocn-type 1558 - Description: Instructs the dCDN to perform delegation operating 1559 the type of open caching nodes. 1561 - Type: A string corresponding to one of the open caching node 1562 types announced by the dCDN through the FCI interface. 1564 - Mandatory-to-Specify: No. At least one of the two properties, 1565 ocn-type or ocn-delivery, must be present. 1567 Property: ocn-selection 1569 - Description: This property enforces the selection of OCNs, 1570 considering the ocn-type and/or the ocn-delivery properties. 1571 "False" means best-effort. 1573 - Type: string. "attempt-or-failed" and "attempt-or-besteffort" 1574 mean that the delegation must be attempted considering the ocn- 1575 type and/or the ocn-delivery properties. If not possible, it 1576 is considered as an error and either fails (configuration 1577 failure) or the dCDN continues with a best-effort procedure. 1578 Last, "best effort" means the dCDN tries its best to fulfil the 1579 requested ocn-selection policy. 1581 - Mandatory-to-Specify: No. Best-effort is the default OCN 1582 selection policy. 1584 2.3.4.1. MI.OcnDelivery 1586 An ocn-delivery object contains the following properties: 1588 Property: ocn-medium 1590 - Description: Instructs the dCDN to perform delegation operating 1591 a particular medium. The following values are specified: 1592 "SATELLITE". 1594 - Type: String 1596 - Mandatory-to-Specify: No. Either the ocn-medium property or 1597 the ocn-transport property must be present. 1599 Property: ocn-transport 1601 - Description: Instructs the dCDN to perform delegation operating 1602 a particular transport arrangement. The following values are 1603 specified: "MABR". 1605 - Type: String 1607 - Mandatory-to-Specify: No. At least one of the two properties 1608 (ocn-medium or ocn-transport) must be present. 1610 2.4. Processing Stage Metadata 1612 It is typical in CDN configurations to define matching rules and 1613 metadata that are to be applied at specific stages in the request 1614 processing pipeline. For example, it may be required to append a 1615 host header prior to forwarding a request to an origin, or modify the 1616 response returned from an origin prior to storing in the cache. 1618 +-------+ +---------------+ +--------+ 1619 | +--->|A B+--->| | 1620 | | | | | uCDN | 1621 | UA | | dCDN | | | 1622 | | | | | Source | 1623 | |<---+D C|<---+ | 1624 +-------+ +---------------+ +--------+ 1626 Figure 2: Processing stages 1628 Processing stages: 1630 1. clientRequest - Rules run on the client request prior to further 1631 processing. 1633 2. originRequest - Rules run prior to making a request to the 1634 origin. 1636 3. originResponse - Rules run after a response is received from the 1637 origin and before being placed in the cache. 1639 4. clientResponse - Rules run prior to sending the response to the 1640 client. If the response is from the cache, rules are applied to 1641 the response retrieved from the cache prior to sending to the 1642 client. 1644 Requirements: 1646 1. Header Matching - While CDNI metadata defines some basic 1647 matching rules for host names and pattern patching on paths, CDN 1648 and open caching use cases often require matching on specific 1649 fields in Hypertext Transfer Protocol (HTTP) request and 1650 response headers to set metadata. A typical example may be 1651 matching on a user agent string to set access controls or 1652 matching on a mime-type header to set caching rules. A rich 1653 expression matching syntax that allows matching on any 1654 combination of host, path, and header values covers most typical 1655 use cases. 1657 2. Expression Matching - Header matching alone is not always 1658 sufficient for identifying a set of requests or responses that 1659 require specific metadata. CDN and open caching systems often 1660 require a rich set of matching rules, with full regular 1661 expressions and Boolean combinations of matching parameters for 1662 host, path, and header elements of a request. In typical CDN 1663 implementations, this capability is provided by a rich 1664 expression language that can be embedded in the metadata 1665 configurations. 1667 3. URI Modifications - In processing HTTP requests, modifications 1668 to the request Uniform Resource Identifier (URI) are often 1669 required for uses such as collapsing multiple paths to a common 1670 cache key or normalizing file extension naming conventions 1671 before making a request to the origin. In cases where the 1672 modified URI needs to be constructed dynamically, an expression 1673 language is provided that allows elements of requests and 1674 responses to be concatenated with string literals. 1676 4. Header Modifications - In processing HTTP requests, it is often 1677 required to modify HTTP request or response headers at one of 1678 the processing stages, requiring CDNI metadata to have the 1679 capability to update any field in an HTTP request or response 1680 header. It should be noted that certain HTTP headers (such as 1681 Set-Cookie) have multiple occurrences in a request or response, 1682 thereby requiring that we allow for add and replace designations 1683 for header modification. In cases where a header value needs to 1684 be constructed dynamically, an expression language is provided 1685 that allows elements of requests and responses to be 1686 concatenated with string literals. All of the following 1687 capabilities are required at each processing stage: 1689 5. Add Request Header Field - Add a header name/value to the 1690 request, along with any headers of the same name that may 1691 already be present. 1693 6. Replace Request Header Field - Add a header name/value to the 1694 request, replacing any headers of the same name that may already 1695 be present. 1697 7. Delete Request Header Field - Delete all occurrences of the 1698 named header from the request. 1700 8. Add Response Header Field - Add a header name/value to the 1701 response, along with any headers of the same name that may 1702 already be present. 1704 9. Replace Response Header Field - Add a header name/value to the 1705 response, replacing any headers of the same name that may 1706 already be present. 1708 10. Delete Response Header Field - Delete all occurrences of the 1709 named header from the response. 1711 11. Synthetic Responses - It is quite common in CDN configurations 1712 to specify a synthetic response be generated based on inspection 1713 of aspects of the original request or the origin response. The 1714 synthetic response capability allows for the specification of a 1715 set of response headers, a status code, and a response body. In 1716 cases where a header value or the synthetic response body needs 1717 to be constructed dynamically, an expression language is 1718 provided that allows elements of requests and responses to be 1719 concatenated with string literals. 1721 2.4.1. MI.ProcessingStages 1723 A ProcessingStages object is a new GenericMetadata which describes 1724 the matching rules, metadata, and transformations to be applied at 1725 specific stages in the request processing pipeline. The processing 1726 rules and transformations are defined as a child data model 1727 referenced within a ProcessingStages object, as defined below. 1729 +----------------+ 1730 |ProcessingStages| 1731 +----------------+ 1732 (*) 1733 | 1734 +----------------+-------+---------+----------------+ 1735 | | | | 1736 v v v v 1737 +-------------+ +-------------+ +--------------+ +--------------+ 1738 |ClientRequest| |OriginRequest| |OriginResponse| |ClientResponse| 1739 +-------------+ +-------------+ +--------------+ +--------------+ 1740 (*) (*) (*) (*) 1741 | | | | 1742 +---------------+----------------+----------------+ 1743 | 1744 | +---------------+ 1745 | +-------->|ExpressionMatch| 1746 | | +---------------+ 1747 | | 1748 | | ***************** 1749 | (*) +--->*GenericMetadata* 1750 | +----------+ +-------------+ | * Objects * 1751 +--->+StageRules+--->|StageMetadata+(*)-+ ***************** 1752 +----------+ +-------------+ 1753 (*) (*) 1754 | | 1755 +-------+ +-----------+ 1756 | | 1757 v v 1758 +----------------+ +-----------------+ 1759 |RequestTransform|(*)-+ +-(*)|ResponseTransform| 1760 +----------------+ | | +-----------------+ 1761 (*) | | 1762 | | | 1763 | v v 1764 | +---------------+ 1765 | |HeaderTransform|(*)-+ 1766 | +---------------+ | 1767 | | 1768 v | 1769 +-----------------+ | 1770 |SyntheticResponse|(*)--+ v 1771 +-----------------+ | +----------+ 1772 +----->|HTTPHeader| 1773 +----------+ 1775 Figure 3: CDNi ProcessingStages metadata model with contained objects 1776 Each of the four processing stages is represented by an array of 1777 StageRules objects, with each StageRules object defining criteria 1778 along with metadata that MUST be applied if the match applies to 1779 "True". It should be noted that the StageRules objects in the array 1780 are evaluated and processed in order. A possible future extension to 1781 this processing model could allow for an if-else structure, where 1782 processing for a stage is halted upon the first match of a StageRules 1783 expression. 1785 Property: client-request 1787 - Description: Allows for the specification of conditional 1788 metadata to be applied at the client request processing stages, 1789 as defined in the Rule Processing Stages section. The 1790 StageRules in the array are evaluated in order. 1792 - Type: Array of StageRules objects 1794 - Mandatory-to-Specify: No 1796 Property: origin-request 1798 - Description: Allows for the specification of conditional 1799 metadata to be applied at origin request processing stages, as 1800 defined in the Rule Processing Stages section. The StageRules 1801 in the array are evaluated in order. 1803 - Type: Array of StageRules objects 1805 - Mandatory-to-Specify: No 1807 Property: origin-response 1809 - Description: Allows for the specification of conditional 1810 metadata to be applied at origin response processing stages, as 1811 defined in the Rule Processing Stages section. The StageRules 1812 in the array are evaluated in order. 1814 - Type: Array of StageRules objects 1816 - Mandatory-to-Specify: No 1818 Property: client-response 1820 - Description: Allows for the specification of conditional 1821 metadata to be applied at client response processing stages, as 1822 defined in the Rule Processing Stages section. The StageRules 1823 in the array are evaluated in order. 1825 - Type: Array of StageRules objects 1827 - Mandatory-to-Specify: No 1829 Example specifying all four processing stages. In this example, the 1830 client-request stage has two StageRules, appling one set of metadata 1831 if "ExpressionMatch1" evaluates to "True" and applying another set of 1832 metadata if "ExpressionMatch2" evaluates to "True". 1834 { 1835 "generic-metadata-type": "MI.ProcessingStages", 1836 "generic-metadata-value": { 1837 "client-request" : [ 1838 { 1839 "match" : < ExpressionMatch1 for conditional metadata > 1840 "stage-metadata" : , 1841 }, 1842 { 1843 "match" : 1844 "stage-metadata" : , 1845 } 1846 ], 1847 "origin-request" : [{ 1848 "match" : 1849 "stage-metadata" : , 1850 }], 1851 "origin-response" : [{ 1852 "match" : 1853 "stage-metadata" : , 1854 }], 1855 "client-response" : [{ 1856 "match" : 1857 "stage-metadata" : , 1858 }] 1859 } 1860 } 1862 2.4.2. MI.StageRules 1864 A StageRules object is used within the context of ProcessingStages to 1865 define elements in a list of match rules and stage-specific metadata 1866 and transformations that MUST be applied conditionally on a rich 1867 expression match. 1869 Property: match 1870 - Description: An ExpressionMatch object encapsulating a rich 1871 expression using the CDNI Metadata Expression Language [CDNI- 1872 MEL] to evaluate aspects of the HTTP request and/or response. 1873 The stage-metadata rules are only applied if the match 1874 evaluates to "True" or if no match expression is provided 1876 - Type: ExpressionMatch object 1878 - Mandatory-to-Specify: No. The stage-metadata rules are always 1879 applied if no match expression is provided. This would be the 1880 case when stage-metadata should be applied unconditionally 1881 within the context of the higher-level host and path matches. 1883 Property: stage-metadata 1885 - Description: Specifies the set of StageMetadata to be applied 1886 at the processing stage if the match expression evaluates to 1887 "True" or is not present. 1889 - Type: Array of StageMetadata objects, applied in order. 1891 - Mandatory-to-Specify: Yes 1893 An example of StageRules that are applied just after responses are 1894 received from the origin. In this example, receipt of a response 1895 status code of 304 from the origin indicates that CachePolicy 1896 metadata SHOULD be applied (as specified via an external HREF), and 1897 that response headers SHOULD be modified (X-custom-response-header 1898 added and ETag deleted). 1900 { 1901 "match": { 1902 "expression": "resp.status == 304" 1903 }, 1904 "stage-metadata": { 1905 "generic-metadata": [ 1906 { 1907 "type": "MI.CachePolicy", 1908 "href": "https://metadata.ucdn.example/origin_response_cache" 1909 } 1910 ], 1911 "response-transform": { 1912 "headers": { 1913 "add": [ 1914 { 1915 "name": "X-custom-response-header", 1916 "value": "header-value" 1917 } 1918 ], 1919 "delete": [ "ETag" ] 1920 } 1921 } 1922 } 1923 } 1925 2.4.3. MI.ExpressionMatch 1927 The ExpressionMatch object contains the rich expression that must 1928 evaluate to "True" for the StageMetadata to be applied for the 1929 specific StageRules. Defining expressions as stand-alone objects 1930 allows for sets of reusable match expressions to be reused via 1931 metadata reference linking. 1933 Property: expression 1935 - Description: A rich expression using CDNI-MEL to evaluate 1936 aspects of the HTTP request and/or response. See documentation 1937 on the Metadata Expression Language for details on the 1938 expression of matching variables and syntax. 1940 - Type: String, using CDNI-MEL syntax. See the METADATA 1941 EXPRESSION LANGUAGE (CDNI-MEL) section. 1943 - Mandatory-to-Specify: Yes 1945 Example of ExpressionMatch on the referrer and user agent request 1946 headers: 1948 { 1949 "expression" : "req.h.user-agent *= '*Safari*' and req.h.referrer == 'www.myhost.com'" 1950 } 1952 2.4.4. MI.StageMetadata 1954 The StageMetadata object contains GenericMetadata and HTTP request/ 1955 response transformations that MUST be applied for a StageRules match. 1956 The following table defines the processing stages where request and 1957 response transformations are possible: 1959 +================+===================+====================+ 1960 | Stage | request-transform | response-transform | 1961 +================+===================+====================+ 1962 | clientRequest | yes | yes | 1963 +----------------+-------------------+--------------------+ 1964 | originRequest | yes | yes | 1965 +----------------+-------------------+--------------------+ 1966 | originResponse | no | yes | 1967 +----------------+-------------------+--------------------+ 1968 | clientResponse | no | yes | 1969 +----------------+-------------------+--------------------+ 1971 Table 1: StageMetadata stages 1973 Note that for the stages where both request and response 1974 transformations are allowed, it is possible to specify both. This 1975 may be the case if, for example, the request URI needs alteration for 1976 cache-key generation and the response headers need to be manipulated. 1978 Property: generic-metadata 1980 - Description: Specifies the set of GenericMetadata to be applied 1981 for a StageRules match. A typical use case would be the 1982 application of a CachePolicy or TimeWindowACL conditionally on 1983 matching HTTP headers. Support for this capability is optional 1984 and can be advertised via feature-flags in the FCI interface. 1986 - Type: Array of GenericMetadata, applied in order. Note that 1987 not all GenericMetadata object types may be applicable at all 1988 processing stages. 1990 - Mandatory-to-Specify: No. The generic-metadata property would 1991 not be needed when StageMetadata is used to only specify 1992 request or response transformations, such as modifications of 1993 HTTP headers. 1995 Property: request-transform 1996 - Description: Specifies a transformation to be applied to the 1997 HTTP request for a StageRules match. The transformation can be 1998 the modification of any request header and/or the modification 1999 of the URI. Modifications are applied such that downstream 2000 processing stages receive the modified HTTP request as their 2001 input. Support for this capability is optional and can be 2002 advertised via feature-flags in the FCI interface. 2004 - Type: RequestTransform object 2006 - Mandatory-to-Specify: No 2008 Property: response-transform 2010 - Description: Specifies a transformation to be applied to the 2011 HTTP response for a StageRules match. The transformation can 2012 be the modification of any response header, HTTP response 2013 status code, or the generation of a synthetic response. 2014 Modifications are applied such that downstream processing 2015 stages receive the modified HTTP response as their input. 2016 Support for this capability is optional and can be advertised 2017 via feature-flags in the FCI interface. 2019 - Type: ResponseTransform object 2021 - Mandatory-to-Specify: No 2023 Example of a StageMetadata object: 2025 { 2026 "generic-metadata" : [{ 2027 < Optional list of generic metadata to apply at this stage > 2028 }], 2029 "request-transform" : { 2030 "headers" : { }, 2031 "uri" : < URI rewrite, either static or dynamically constructed> 2032 } 2033 "response-transform" : { 2034 "headers" : { }, 2035 "response-status" : 2036 } 2037 } 2038 2.4.5. MI.RequestTransform 2040 The RequestTransform object contains metadata for transforming the 2041 HTTP request for a specific StageRules object. The transformation 2042 can be the modification of any request header and/or the modification 2043 of the URI. Modifications are applied such that downstream 2044 processing stages receive the modified HTTP request as their input. 2046 Property: headers 2048 - Description: A HeaderTransform object specifying HTTP request 2049 headers to add, replace, or delete. 2051 - Type: HeaderTransform object 2053 - Mandatory-to-Specify: No 2055 Property: uri 2057 - Description: Replacement value for the HTTP request. 2059 - Type: String. Either a literal (static string) or an 2060 expression using CDNI-MEL to dynamically construct a URI value 2061 from elements of the HTTP request and/or response. 2063 - Mandatory-to-Specify: No 2065 Property: uri-is-expression 2067 - Description: Flag to signal whether the URI is a static string 2068 literal or a CDNI-MEL expression that needs to be dynamically 2069 evaluated. 2071 - Type: Boolean 2073 - Mandatory-to-Specify: No. The default is "False", indicating 2074 that the URI is a string literal and does not need to be 2075 evaluated. 2077 Example of a RequestTransform object illustrating a dynamically 2078 constructed URI rewrite: 2080 { 2081 "request-transform" : { 2082 "headers" : { }, 2083 "uri" : "req.uri.path", 2084 "uri-is-expression" : true 2085 } 2087 2.4.6. MI.ResponseTransform 2089 The ResponseTransform object contains metadata for transforming the 2090 HTTP response for a StageRules match. The transformation can be the 2091 modification of any response header, HTTP response status code, or 2092 the generation of a synthetic response. Modifications are applied 2093 such that downstream processing stages receive the modified HTTP 2094 response as their input. 2096 Property: headers 2098 - Description: A HeaderTransform object specifying HTTP response 2099 headers to add, replace, or delete. 2101 - Type: HeaderTransform object 2103 - Mandatory-to-Specify: No 2105 Property: response-status 2107 - Description: Replacement value for the HTTP response status 2108 code. 2110 - Type: Integer. Either a static integer or an expression using 2111 CDNI-MEL that evaluates to an integer to dynamically generate 2112 an HTTP status code based on elements of the HTTP request and/ 2113 or response. Expressions that do not evaluate to an integer 2114 shall be considered invalid and result in no override of 2115 origin-provided response status. 2117 - Mandatory-to-Specify: No 2119 Property: status-is-expression 2121 - Description: Flag to signal whether the response-status is a 2122 static integer or a CDNI-MEL expression that needs to be 2123 dynamically evaluated to generate an HTTP response status code. 2125 - Type: Boolean 2127 - Mandatory-to-Specify: No. The default is "False", indicating 2128 that the response-status is a static integer and does not need 2129 to be evaluated. 2131 Property: synthetic 2132 - Description: Specification of a complete replacement of any 2133 HTTP response that may have been generated in an earlier 2134 processing stage with a synthetic response. Use of this 2135 property to specify a synthetic response would override any 2136 response transformations or status codes specified by other 2137 properties. 2139 - Type: SyntheticResponse object 2141 - Mandatory-to-Specify: No 2143 Example of a ResponseTransform object, illustrating a dynamically 2144 constructed header value that uses the expression language to 2145 concatenate the user agent and host header, and forces a 403 HTTP 2146 response status code: 2148 { 2149 "response-transform": { 2150 "headers": { 2151 "add": [ 2152 { 2153 "name": "X-custom-response-header", 2154 "value": "req.h.user-agent . ‘-‘ . req.h.host", 2155 "value-is-expressions": true 2156 } 2157 ] 2158 }, 2159 "response-status": "403" 2160 } 2161 } 2163 2.4.7. MI.SyntheticResponse 2165 The SyntheticResponse object allows for the specification of a 2166 synthetic response to be generated in response to the HTTP request 2167 being processed. The synthetic response can contain a set of 2168 response headers, a status code, and a response body, and is a 2169 complete replacement for any HTTP response elements generated in an 2170 earlier processing stage. 2172 A dynamically generated Content-Length HTTP response header is 2173 generated based on the length of the generated response body. 2175 Property: headers 2177 - Description: An array of HTTP header objects that specify the 2178 full set of headers to be applied to the synthetic response. 2180 - Type: Array of HTTP header objects 2182 - Mandatory-to-Specify: No, although it would be unusual to not 2183 specify minimal standard response headers, such as Content- 2184 Type. 2186 Property: response-status 2188 - Description: HTTP response status code. 2190 - Type: Integer. Either a static integer or an expression using 2191 CDNI-MEL that evaluates to an integer to dynamically generate 2192 an HTTP status code based on elements of the upstream HTTP 2193 request and/or response. Expressions that do not evaluate to 2194 an integer shall be considered invalid and result in a 500 2195 status for the synthetic response. 2197 - Mandatory-to-Specify: Yes 2199 Property: status-is-expression 2201 - Description: Flag to signal whether the response-status is a 2202 static integer or a CDNI-MEL expression that needs to be 2203 dynamically evaluated to generate an HTTP response status code. 2205 - Type: Boolean 2207 - Mandatory-to-Specify: No. The default is "False", indicating 2208 that the response-status is a static integer and does not need 2209 to be evaluated. 2211 Property: body 2213 - Description: Body for the synthetic HTTP response. The 2214 response body can either be static or dynamically constructed 2215 from a rich expression. 2217 - Type: String. Either a literal (static string) or an 2218 expression using CDNI-MEL to dynamically construct a response 2219 body from elements of the HTTP request and/or response. 2221 - Mandatory-to-Specify: No. If absent, an empty HTTP response 2222 with a zero-value Content-Length header is generated. 2224 Property: body-is-expression 2225 - Description: Flag to signal whether the synthetic response body 2226 is a static string literal or a CDNI-MEL expression that needs 2227 to be dynamically evaluated. 2229 - Type: Boolean 2231 - Mandatory-to-Specify: No. The default is "False", indicating 2232 that the body is a string literal and does not need to be 2233 evaluated. 2235 Example of a SyntheticResponse object illustrating a dynamically 2236 constructed response body that uses the expression language to 2237 combine the request URI with static text and forces a 405 HTTP 2238 response status code: 2240 { 2241 "headers": [ 2242 { 2243 "name": "content-type", 2244 "value": "text/plain" 2245 }, 2246 { 2247 "name": "X-custom-response-header", 2248 "value": "some static value" 2249 } 2250 ], 2251 "response-status": "405", 2252 "response-body": "'Sorry, Access to resource '.req.uri.' not allowed'", 2253 "body-is-expression": false 2254 } 2256 2.4.8. MI.HeaderTransform 2258 The HeaderTransform object specifies how HTTP headers MUST be added, 2259 replaced, or deleted from HTTP requests and responses. 2261 Property: add 2263 - Description: List of HTTP headers (name/value pairs) that MUST 2264 be added to the HTTP request or response. Note that any 2265 existing headers in the request or response with the same names 2266 of those added are not affected, resulting in multiple headers 2267 with the same name. 2269 - Type: Array of HTTPHeader objects containing header name/value 2270 pairs 2272 - Mandatory-to-Specify: No 2273 Property: replace 2275 - Description: List of HTTP headers (name/value pairs) that MUST 2276 be added to the HTTP request or response, replacing any 2277 previous headers with the same name. 2279 - Type: Array of HTTPHeader objects containing header name/value 2280 pairs 2282 - Mandatory-to-Specify: No 2284 Property: delete 2286 - Description: List of names of HTTP headers that MUST be deleted 2287 from the 2289 - HTTP request or response. If a named header appears multiple 2290 times, all occurrences are deleted. 2292 - Type: Array of strings, with each string naming an HTTP header 2293 to delete 2295 - Mandatory-to-Specify: No 2297 Example of a HeaderTransform object illustrating the addition of two 2298 customer headers, the replacement of any previously provided Accept- 2299 Encoding header, and the removal of any previously provided 2300 Authorization or Accept-Language headers: 2302 { 2303 "add": [ 2304 { 2305 "name": "X-custom-header1", 2306 "value": "header-value 1" 2307 }, 2308 { 2309 "name": "X-custom-header2", 2310 "value": "header-value 2" 2311 } 2312 ], 2313 "replace": [ 2314 { 2315 "name": "Accept-Encoding", 2316 "value": "gzip,deflate,br" 2317 } 2318 ], 2319 "delete": [ 2320 "Authorization", 2321 "Accept-Language" 2322 ] 2323 } 2325 2.4.9. MI.HTTPHeader 2327 The HTTPHeader object contains a name/value pair for an HTTP header 2328 to add or replace in a request or response. The CDNI-MEL expression 2329 language can be used to dynamically generate response values. 2331 Property: name 2333 - Description: Name of the HTTP header. 2335 - Type: String 2337 - Mandatory-to-Specify: Yes 2339 Property: value 2341 - Description: New value of the named HTTP header. 2343 - Type: String. Either a static string or an expression using 2344 [CDNI-MEL] to dynamically construct a header value from 2345 elements of the HTTP request and/or response. 2347 - Mandatory-to-Specify: Yes 2349 Property: value-is-expression 2350 - Description: Flag to signal whether the value is a static 2351 string literal or a [CDNI-MEL] expression that needs to be 2352 dynamically evaluated. 2354 - Type: Boolean 2356 - Mandatory-to-Specify: No. The default is "False", indicating 2357 that the value is a string literal and does not need to be 2358 evaluated. 2360 Example of an HTTPHeader illustrating a dynamically constructed 2361 header value that equals the session parameter from the query string: 2363 { 2364 "name": "X-custom-response-header", 2365 "value": "req.uri.query.session", 2366 "value-is-expression": true 2367 } 2369 2.5. General Metadata 2371 This section documents a set of general purpose GenericMetadata 2372 objects whose use and interpretation may be specific to a CDN or Open 2373 Caching system's implementation, enabling extensibility and service 2374 differentiation for providers. 2376 2.5.1. MI.ServiceIDs 2378 CDN configurations typically have multiple tiers of identifiers that 2379 group configurations by customer account to facilitate logging, 2380 billing, and support operations. This structure supports two tiers 2381 of identifiers (a serviceID which typically identifies a high level 2382 customer's service, and a propertyID which typically represents a 2383 logical grouping of a set of hosts within a customers' service. It 2384 should be noted, however, that the interpretation of ServiceID and 2385 PropertyID are implementation-specific, and may not be used by all 2386 CDNs and Open Caching systems. 2388 This metadata model extension allows for the association service 2389 identifier metadata to a host or path match and to allow for these 2390 IDs to be dynamically generated via an expression language. For 2391 example, it may be necessary to extract a portion of the Request URI 2392 path to derive a service identifier (e.g.: /news/* maps to one 2393 propertyID and /movies/* maps to a different propertyID). When 2394 processing the MI.ServiceIDs metadata for a request, implementations 2395 SHOULD override any previously assigned service identifiers with 2396 those specified by this metadata. 2398 MI.ServiceIDs is a new GenericMetadata object that allows for the 2399 specification of the two tiers of CDN-specific service identifiers 2400 and service names. 2402 Property: service-id 2404 - Description: A provider-specific identifier for the service 2405 (typically a customer account identifier). 2407 - Type: String. Either a literal (static string) or an 2408 expression using CDNI-MEL to dynamically construct the ID from 2409 elements of the HTTP request and/or response. 2411 - Mandatory-to-Specify: No 2413 Property: service-id-is-expression 2415 - Description: Flag to signal whether the service-id is a static 2416 string literal or a CDNI-MEL expression that needs to be 2417 dynamically evaluated. 2419 - Type: Boolean 2421 - Mandatory-to-Specify: No. The default is "False", indicating 2422 that the service-id is a string literal and does not need to be 2423 evaluated. 2425 Property: service-name 2427 - Description: Human-readable name for the service-id. 2429 - Type: String 2431 - Mandatory-to-Specify: No 2433 Property: property-id 2435 - Description: A provider-specific identifier for the property 2436 (typically identifies a child configuration within the parent 2437 service-id). 2439 - Type: String. Either a literal (static string) or an 2440 expression using CDNI-MEL to dynamically construct the ID from 2441 elements of the HTTP request and/or response. 2443 - Mandatory-to-Specify: No 2445 Property: property-id-is-expression 2446 - Description: Flag to signal whether the property-id is a static 2447 string literal or a CDNI-MEL expression that needs to be 2448 dynamically evaluated. 2450 - Type: Boolean 2452 - Mandatory-to-Specify: No. The default is "False", indicating 2453 that the property-id is a string literal and does not need to 2454 be evaluated. 2456 Property: property-name 2458 - Description: Human-readable name for the property-id. 2460 - Type: String 2462 - Mandatory-to-Specify: No 2464 Example illustrating the assignment of a literal service-id along 2465 with a dynamically computed property-id that is extracted from the 2466 root element of the request URI path. 2468 { 2469 "generic-metadata-type": "MI.ServiceIDs", 2470 "generic-metadata-value": { 2471 "service-id": "12345", 2472 "service-name": "My Streaming Service", 2473 "property-id": "path_element(req.uri, 1)", 2474 "property-id-is-expression": true 2475 } 2476 } 2478 2.5.2. MI.PrivateFeatureList 2480 The dCDN may gather a certain number of private features (i.e., not 2481 [yet] adopted by SVA or considered marginal) that it may want to 2482 expose to the content provider and/or the uCDN. Although private, 2483 the announcement, selection, and configuration of this private 2484 feature could be done through the OC API. 2486 One example could be the support in OCNs of a new protocol that 2487 allows the ability to get additional insight about the user agent 2488 status (e.g., CTA Wave CMCD). 2490 As another example, Broadpeak has developed a feature called 2491 S4Streaming, and would like to give the opportunity to control that 2492 feature to the uCDN. 2494 PrivateFeatureListis a GenericMetadata configuration object as a base 2495 generic object that permits the control of private features. 2497 Property: features 2499 - Description: The list of feature configuration objects. 2501 - Type: List (array) of MI.PrivateFeature objects . 2503 - Mandatory-to-Specify: Yes 2505 2.5.2.1. MI.PrivateFeature 2507 MI.PrivateFeature object contains the following properties: 2509 Property: feature-oid 2511 - Description: The owner/organization that has specified that 2512 feature. 2514 - Type: String 2516 - Mandatory-to-Specify: Yes 2518 Property: feature-type 2520 - Description: Indicates the type/name of the private feature 2521 configuration object. 2523 - Type: String 2525 - Mandatory-to-Specify: Yes 2527 Property: feature-value 2529 - Description: Feature configuration object. 2531 - Type: Format/type is defined by the value of the feature-type 2532 property above. 2534 - Mandatory-to-Specify: Yes 2536 Note that the private features exposed by the dCDN can be advertised 2537 through a dedicated FCI object. 2539 Example, illustrating the Broadpeak S4 Streaming feature: 2541 { 2542 "generic-metadata-type": "MI.PrivateFeatureList", 2543 "generic-metadata-value": { 2544 "feature": { 2545 "feature-oid": "Broadpeak", 2546 "feature-type": "S4Streaming", 2547 "feature-value": { 2548 "footprint": { 2549 "footprint-type": "ipv4cidr", 2550 "footprint-value": [ 2551 "192.0.2.0/24", 2552 "198.51.100.0/24" 2553 ] 2554 }, 2555 "activation": "ON", 2556 "mode": "transparent", 2557 "policy": "bandwidth-max" 2558 } 2559 } 2560 } 2561 } 2563 2.5.3. MI.RequestRouting 2565 The uCDN requires the ability to indicate whether HTTP redirect, DNS 2566 redirect, and manifest rewrite are allowed, and indicate which is 2567 preferable. This is required in cases where the uCDN would like to 2568 delegate the traffic relying on the iterative method but knows the 2569 client will not support HTTP redirect. In that case, the uCDN needs 2570 a means to force the dCDN to perform request routing based on DNS 2571 redirect (or manifest rewrite). 2573 This configuration possibility is useful only if the dCDN can 2574 advertise the mode of redirection it supports. There is an ongoing 2575 discussion in the IETF CDNI group to understand the semantics behind 2576 the redirection modes currently in Footprint & Capabilities 2577 Advertising Interface (I-DNS and I-HTTP). It is not clear whether 2578 this indicates that the dCDN supports one or both delegation modes 2579 (the request routing performed by the uCDN can only be based on DNS 2580 redirect or HTTP redirect or both), or whether it indicates that the 2581 dCDN supports, as its own request routing mode, DNS redirect and/or 2582 HTTP redirect. The latter is required for this new configuration 2583 object to be valid. 2585 MI.RequestRouting is a new GenericMetadata object that allows the 2586 uCDN to force the dCDN request routing mode(s) to be applied when 2587 working in iterative redirection mode. The list of redirection modes 2588 supported by the dCDN is advertised through the FCI.RedirectionMode 2589 object. The list of request routing modes supported by the dCDN is 2590 advertised through the FCI.RequestRoutingMode object. 2592 Property: request-routing-modes 2594 - Description: Instructs the dCDN to perform request routing 2595 according to one or more preferred modes among those supported 2596 and advertised by the dCDN through the FCI.RequestRouting 2597 object. One must understand that forcing (instead of letting 2598 the dCDN request router select) one particular request routing 2599 mode may trigger some inefficiency in the request routing 2600 process. 2602 - Type: List (array) of iterative request routing modes 2604 - Values: "DNS", "HTTP", "MANIFEST_REWRITE" 2606 - Mandatory-to-Specify: No. By default, all request routing 2607 modes supported by the dCDN can be used by the dCDN as part of 2608 its request routing process. 2610 Example, illustrating the uCDN forcing the dCDN to use DNS or HTTP as 2611 the method for request routing in case the uCDN performs an iterative 2612 delegation (i.e., iterative redirection mode): 2614 { 2615 "generic-metadata-type": "MI.RequestRouting", 2616 "generic-metadata-value": { 2617 "request-routing-modes": [ "DNS", "HTTP" ] 2618 } 2619 } 2621 3. Metadata Expression Language 2623 The CDNI Metadata Expression Language provides a syntax with a rich 2624 set of variables, operators, and built-in functions to facilitate use 2625 cases within the extended CDNi metadata model. 2627 Enables expression matching to dynamically determine if 2628 StageMetadata (Section 2.4) should be applied at a StageRules 2629 match. 2631 Enables the dynamic construction of a value to be used in 2632 scenarios such as constructing a service identifier or cache key, 2633 setting an HTTP header, rewriting a request URI, setting a 2634 response status code, or dynamically generating a response body 2635 for a SyntheticResponse. 2637 Expressions can evaluate to a Boolean, string, or integer, depending 2638 on the use case: 2640 +=============================+=================+==================+ 2641 | Usage | Description | Evaluation | 2642 | | | Results | 2643 +=============================+=================+==================+ 2644 | ExpressionMatch.expression | Dynamically | Boolean. | 2645 | | determines if | Expressions that | 2646 | | StageMetadata | do not evaluate | 2647 | | should be | to True or False | 2648 | | applied at a | shall be | 2649 | | specific | considered as | 2650 | | StageRules. | False. | 2651 +-----------------------------+-----------------+------------------+ 2652 | RequestTransform.uri | Rewrites | String | 2653 | | request URI | | 2654 | | that will be | | 2655 | | presented to | | 2656 | | all downstream | | 2657 | | stages. | | 2658 +-----------------------------+-----------------+------------------+ 2659 | ResponseTransform.response- | Dynamically | Integer (HTTP | 2660 | status | sets a response | status code) | 2661 | | status code to | | 2662 | | replace the | | 2663 | | status-code | | 2664 | | returned by the | | 2665 | | origin. | | 2666 +-----------------------------+-----------------+------------------+ 2667 | SyntheticResponse.response- | Dynamically | Integer (HTTP | 2668 | status | sets a response | status code) | 2669 | | status code for | | 2670 | | a synthetically | | 2671 | | constructed | | 2672 | | response. | | 2673 +-----------------------------+-----------------+------------------+ 2674 | SyntheticResponse.body | Dynamically | String | 2675 | | constructs a | | 2676 | | response body. | | 2677 +-----------------------------+-----------------+------------------+ 2678 | HTTPHeader.value | Dynamically | String | 2679 | | constructs a | | 2680 | | header value. | | 2681 +-----------------------------+-----------------+------------------+ 2682 | ComputedCacheKey.expression | Dynamically | String | 2683 | | constructs a | | 2684 | | cache key. | | 2685 +-----------------------------+-----------------+------------------+ 2686 | ServiceIDs.properry- | Dynamically | String | 2687 | id,ServiceIDs.service-id | constructs | | 2688 | | service and | | 2689 | | property | | 2690 | | identifiers. | | 2691 +-----------------------------+-----------------+------------------+ 2693 Table 2: CDNI MEL expressions 2695 3.1. Expression Variables 2697 +=====================+====================================+ 2698 | Variable | Meaning | 2699 +=====================+====================================+ 2700 | req.h. | Request header | 2701 +---------------------+------------------------------------+ 2702 | req.uri | Request URI (includes query string | 2703 | | and fragment identifier, if any) | 2704 +---------------------+------------------------------------+ 2705 | req.uri.path | Request URI path | 2706 +---------------------+------------------------------------+ 2707 | req.uri.pathquery | Request path and query string | 2708 +---------------------+------------------------------------+ 2709 | req.uri.query | Request query string | 2710 +---------------------+------------------------------------+ 2711 | req.uri.query. | Request query string value | 2712 | | associated with | 2713 +---------------------+------------------------------------+ 2714 | req.method | Request HTTP method (GET, POST, | 2715 | | others) | 2716 +---------------------+------------------------------------+ 2717 | resp.h. | Response header | 2718 +---------------------+------------------------------------+ 2719 | resp.status | Response status code | 2720 +---------------------+------------------------------------+ 2722 Table 3: CDNI MEL variables 2724 3.2. Expression Operators and keywords 2726 +==========+==========+==========+=================================+ 2727 | Operator | Type | Result | Meaning | 2728 | | | Type | | 2729 +==========+==========+==========+=================================+ 2730 | == | infix | Boolean | Equality test | 2731 +----------+----------+----------+---------------------------------+ 2732 | != | infix | Boolean | Inequality test | 2733 +----------+----------+----------+---------------------------------+ 2734 | ! | infix | Boolean | Logical NOT operator | 2735 +----------+----------+----------+---------------------------------+ 2736 | > | infix | Boolean | Greater than test | 2737 +----------+----------+----------+---------------------------------+ 2738 | < | infix | Boolean | Less than test | 2739 +----------+----------+----------+---------------------------------+ 2740 | >= | infix | Boolean | Greater than or equal test | 2741 +----------+----------+----------+---------------------------------+ 2742 | <= | infix | Boolean | Less than or equal | 2743 +----------+----------+----------+---------------------------------+ 2744 | *= | infix | Boolean | Glob style match | 2745 +----------+----------+----------+---------------------------------+ 2746 | ~= | infix | Boolean | Regular expression match (see | 2747 | | | | https://www.pcre.org/ for | 2748 | | | | details on PCRE RegEx matching) | 2749 +----------+----------+----------+---------------------------------+ 2750 | ipmatch | infix | Boolean | Match against IP address or | 2751 | | | | CIDR (IPv4 and IPv6) | 2752 +----------+----------+----------+---------------------------------+ 2753 | + | infix | Numeric | Addition | 2754 +----------+----------+----------+---------------------------------+ 2755 | - | infix | Numeric | Subtraction | 2756 +----------+----------+----------+---------------------------------+ 2757 | * | infix | Numeric | Multiplication | 2758 +----------+----------+----------+---------------------------------+ 2759 | / | infix | Numeric | Division | 2760 +----------+----------+----------+---------------------------------+ 2761 | % | infix | Unsigned | Modulus | 2762 | | | or | | 2763 | | | Integer | | 2764 +----------+----------+----------+---------------------------------+ 2765 | . | infix | String | Concatenation | 2766 +----------+----------+----------+---------------------------------+ 2767 | ? : | ternary | * | Conditional operator: ? | 2768 | | | | : Evaluates if | 2769 | | | | is true, otherwise. | 2770 +----------+----------+----------+---------------------------------+ 2771 | ( ) | grouping | | Used to override precedence and | 2772 | | | | for function calls. | 2773 +----------+----------+----------+---------------------------------+ 2775 Table 4: CDNI MEL expression operators 2777 +=========+=======================================+ 2778 | Keyword | Meaning | 2779 +=========+=======================================+ 2780 | and | Logical AND | 2781 +---------+---------------------------------------+ 2782 | or | Logical OR | 2783 +---------+---------------------------------------+ 2784 | not | Logical NOT (see also the ! operator) | 2785 +---------+---------------------------------------+ 2786 | nil | No value (distinct from empty value) | 2787 +---------+---------------------------------------+ 2788 | true | Boolean constant: true | 2789 +---------+---------------------------------------+ 2790 | false | Boolean constant: false | 2791 +---------+---------------------------------------+ 2793 Table 5: CDNI MEL expression keywords 2795 3.3. Expression Built-in Functions 2797 3.3.1. Basic Functions: Type Conversions 2799 +============+=====================+=============+=========+ 2800 | Function | Action | Argument(s) | Returns | 2801 +============+=====================+=============+=========+ 2802 | integer(e) | Converts expression | 1 | integer | 2803 | | to integer. | | | 2804 +------------+---------------------+-------------+---------+ 2805 | real(e) | Converts expression | 1 | real | 2806 | | to real. | | | 2807 +------------+---------------------+-------------+---------+ 2808 | string(e) | Converts expression | 1 | string | 2809 | | to string. | | | 2810 +------------+---------------------+-------------+---------+ 2811 | boolean(e) | Converts expression | 1 | Boolean | 2812 | | to Boolean. | | | 2813 +------------+---------------------+-------------+---------+ 2815 Table 6: CDNI MEL type conversions 2817 3.3.2. Basic Functions: String Conversions 2819 +==========+==============================+=============+=========+ 2820 | Function | Action | Argument(s) | Returns | 2821 +==========+==============================+=============+=========+ 2822 | upper(e) | Converts a string to | 1 | string | 2823 | | uppercase. Useful for case- | | | 2824 | | insensitive comparisons. | | | 2825 +----------+------------------------------+-------------+---------+ 2826 | lower(e) | Converts a string to | 1 | string | 2827 | | lowercase. Useful for case- | | | 2828 | | insensitive comparisons. | | | 2829 +----------+------------------------------+-------------+---------+ 2831 Table 7: CDNI MEL string conversions 2833 3.3.3. Convenience Functions 2835 +====================+======================================+===========+=======+ 2836 |Function |Action |Argument(s)|Returns| 2837 +====================+======================================+===========+=======+ 2838 |match(string Input, |Regular expression Match is applied to|2 |string | 2839 |string Match) |Input and the matching element (if | | | 2840 | |any) is returned. Empty string is | | | 2841 | |returned if there is no match. See | | | 2842 | |https://www.pcre.org/ for details on | | | 2843 | |PCRE RegEx matching. | | | 2844 +--------------------+--------------------------------------+-----------+-------+ 2845 |match_replace(string|Regular expression Match is applied to|3 |string | 2846 |Input, string Match,|Input arg and replaced with the | | | 2847 |string Replace) |Replace arg upon successful match. | | | 2848 | |Returns updated (replaced) version of | | | 2849 | |Input. | | | 2850 +--------------------+--------------------------------------+-----------+-------+ 2851 |add_query(string |Add query string element q with value |2 |string | 2852 |Input, string q, |v to the Input string. If v is nil, | | | 2853 |string v) |then just add the query string element| | | 2854 | |q. The query element q and value v | | | 2855 | |must conform to the format defined in:| | | 2856 | |https://datatracker.ietf.org/doc/html/| | | 2857 | |rfc3986 | | | 2858 +--------------------+--------------------------------------+-----------+-------+ 2859 |remove_query(string |Remove (all occurrences of) query |2 |string | 2860 |Input, string q) |string element q from the Input | | | 2861 | |string. | | | 2862 +--------------------+--------------------------------------+-----------+-------+ 2863 |path_element(string |Return the path element n from Input. |2 |string | 2864 |Input, integer n) |-1 returns the last element. | | | 2865 +--------------------+--------------------------------------+-----------+-------+ 2866 |path_element(string |Return the path elements from position|3 |string | 2867 |Input, integer n, |n to m. | | | 2868 |integer m) | | | | 2869 +--------------------+--------------------------------------+-----------+-------+ 2871 Table 8: CDNI MEL convenience functions 2873 3.4. Error Handling 2875 3.4.1. Compile Time Errors 2877 To ensure reliable service, all CDNI Metadata configurations MUST be 2878 validated for syntax errors before they are ingested into a dCDN. 2879 That is, existing configurations should be kept as the live running 2880 configuration until the new configuration has passed validation. If 2881 errors are detected in a new configuration, the configuration MUST be 2882 rejected. A HTTP 500 Internal Server Error should be returned with a 2883 message that indicates the source of the error (line number, and 2884 configuration element that caused the error). 2886 Examples of compile-time errors: 2888 1. Configuration does not parse relative to the CDNI Metadata JSON 2889 schema 2891 2. Unknown CDNI Metadata object referenced in the configuration 2893 3. CDNI Metadata object parse error 2895 a. Missing mandatory CDNI Metadata property 2897 b. Unknown CDNI Metadata property 2899 c. Incorrect type for a CDNI Metadata property value 2901 4. CDNI-MEL 2903 a. Unknown CDNI-MEL variable name referenced in an expression 2905 b. Unknown CDNI-MEL operator, key-word, or functions referenced 2906 in an expression 2908 c. Incorrect number of arguments used in a CDNI-MEL expression 2909 operator or function 2911 d. Incorrect type of argument used in a CDNI-MEL expression 2912 operator or function 2914 3.4.2. Runtime Errors 2916 If a runtime error is detected when processing a request, the request 2917 should be terminated, and a HTTP 500 'Internal Server Error' returned 2918 to the caller. To avoid security leaks, sensitive information MUST 2919 be removed from the error message before it is returned to an 2920 external client. In addition to returning the HTTP 500 error, the 2921 dCDN SHOULD log additional diagnostics information to assist in 2922 troubleshooting. 2924 Examples of runtime errors: 2926 1. Failure to allocate memory (or other server resources) when 2927 evaluating a CDNI-MEL expression 2929 2. Incorrect runtime argument type in a CDNI-MEL expression. E.g., 2930 trying to convert a non-numeric string to a number 2932 3.5. Expression Examples 2934 3.5.1. ComputedCacheKey 2936 Sets the MI.ComputedCacheKey to the value of the X-Cache-Key header 2937 from the client request. 2939 { 2940 "generic-metadata-type": "MI.ComputedCacheKey", 2941 "generic-metadata-value": { 2942 "expression": "req.h.x-cache-key" 2943 } 2944 } 2946 Sets the MI.ComputedCacheKey to the lowercase version of the URI. 2948 { 2949 "generic-metadata-type": "MI.ComputedCacheKey", 2950 "generic-metadata-value": { 2951 "expression": "lower(req.uri)" 2952 } 2953 } 2955 3.5.2. ExpressionMatch 2957 ExpressionMatch where the expression is true if the user-agent (glob) 2958 matches *Safari* and the referrer equals www.example.com. 2960 { 2961 "expression": "req.h.user-agent *= '*Safari*' 2962 and req.h.referrer == 'www.example.com'" 2963 } 2965 3.5.3. ResponseTransform 2967 Adds X-custom-response-header with a value equal to the value of 2968 user-agent - host header. 2970 { 2971 "response-transform": { 2972 "headers": { 2973 "add": [ 2974 { 2975 "name": "X-custom-response-header", 2976 "value": "req.h.user-agent . ' - ' . req.h.host", 2977 "value-is-expression": true 2978 } 2979 ], 2980 "response-status": "403" 2981 } 2982 } 2983 } 2985 Adds a Set-Cookie header with a dynamically computed cookie value 2986 (concatenating user agent and host name) and forces a 403 response. 2988 { 2989 "response-transform":{ 2990 "headers":{ 2991 "add":[ 2992 { 2993 "name":"Set-Cookie", 2994 "value":"req.h.user-agent . ' - ' . req.h.host", 2995 "value-is-expression":true 2996 } 2997 ] 2998 } 2999 } 3000 } 3002 3.5.4. MI.ServiceIDs 3004 Extracts the first path element from the URI. For example, if the 3005 URI = /789/second/third/test.txt, property-id is set to the first- 3006 path (789). 3008 { 3009 "generic-metadata-type":"MI.ServiceIDs", 3010 "generic-metadata-value":{ 3011 "service-id":"12345", 3012 "service-name":"My Streaming Service", 3013 "property-id":"path_element(req.uri, 1)", 3014 "property-id-is-expression":true 3015 } 3016 } 3018 4. CDNI Capabilities Extensions 3020 Since not all dCDNs will be capable of supporting all the extensions 3021 proposed in this document, they need the ability to inform uCDNs 3022 about their capabilities. [RFC8008] (the CDNI Footprint & 3023 Capabilities Interface) was designed for this purpose and is extended 3024 here to express these new capabilities. 3026 4.1. FCI Metadata Object 3028 Whenever a capability is represented as a top-level GenericMetadata 3029 object, a dCDN will be able to declare its support simply by 3030 including that object name in the capability-value list of the 3031 standard FCI.Metadata object. 3033 For each of the new GenericMetadata objects documented within the SVA 3034 Configuration Interface, the default assumption should be that the 3035 capability is not supported by the dCDN unless named within the FCI 3036 metadata object. 3038 Example: A capabilities object declaring support for several of the 3039 newly defined GenericMetadata types: 3041 { 3042 "capabilities": [ 3043 { 3044 "capability-type": "FCI.Metadata", 3045 "capability-value": { 3046 "metadata": [ 3047 "MI.SourceMetadataExtended", 3048 "MI.ProcessingStages", 3049 "MI.CrossoriginPolicy", 3050 "MI.CachePolicy", 3051 "MI.NegativeCachePolicy", 3052 "MI.PrivateFeatureList", 3053 "MI.RequestRouting" 3054 ] 3055 }, 3056 "footprints": [ 3057 < Footprint Objects > 3058 ] 3059 } 3060 ] 3061 } 3063 4.2. FCI Model Extensions 3065 In most cases, the presence or absence of a GenericMetadata object 3066 name in FCI.Metadata (as described above), is sufficient to convey 3067 support for a capability. There are cases, however, where more fine- 3068 grained capabilities declarations are required. Specifically, a dCDN 3069 may support some, but not all, of the capabilities specified by one 3070 of the new GenericMetadata objects. In these cases, new FCI objects 3071 will be created to allow a dCDN to express these fine-grained 3072 capabilities. 3074 4.2.1. FCI.AuthTypes 3076 The AuthTypes object is used to indicate the support of 3077 authentication methods to be used for content acquisition (while 3078 interacting with an origin server) and authorization methods to be 3079 used for content delivery. 3081 This specification document defines two new authentication methods 3082 (see MI.Auth) while there is one authorization method currently under 3083 specification in CDNI called [URI.signing] 3085 Property: stage-metadata 3086 - Description: Specifies the set of StageMetadata to be applied 3087 at the processing stage if the match expression evaluates to 3088 "True" or is not present. 3090 - Type: Array of StageMetadata objects, applied in order. 3092 - Mandatory-to-Specify: Yes 3094 Property: authe-types 3096 - Description: List of supported authentication methods (possibly 3097 required for content acquisition) 3099 - Type: Array of strings 3101 - Values: "AWSv4Auth", "HeaderAuth" 3103 - Mandatory-to-Specify: No. No authentication method is 3104 supported in this case. 3106 Property: autho-types 3108 - Description: List of supported authorization methods (possibly 3109 required for content delivery) 3111 - Type: Array of strings 3113 - Values: "UriSigning" 3115 - Mandatory-to-Specify: No. No authorization method is supported 3116 in this case. 3118 FCI.AuthTypes example: 3120 { 3121 "capabilities": [ 3122 { 3123 "capability-type": "FCI.AuthTypes", 3124 "capability-value": { 3125 "authe-types": [ 3126 "AWSv4Auth", 3127 "HeaderAuth" 3128 ], 3129 "autho-types": [ 3130 "UriSigning" 3131 ] 3132 } 3133 } 3134 ] 3135 } 3137 4.2.2. FCI.ProcessingStages 3139 This object is used to signal the set of features that are supported 3140 in relation to the ProcessingStages configuration object (see 3141 MI.ProcessingStages). Those optional features depend on the CDNI-MEL 3142 language support. 3144 Property: features 3146 - Description: List of supported optional processing stages 3147 features. Note that these features all have some dependencies 3148 on support of the CDNI MEL expression language. 3150 - Type: Array of strings 3152 - Values: "ExpressionMatch", "RequestTransform", 3153 "ResponseTransform" 3155 - Mandatory-to-Specify: No. None of these optional features are 3156 supported in this case. 3158 Example: 3160 { 3161 "capabilities": [ 3162 { 3163 "capability-type": "FCI.ProcessingStages", 3164 "capability-value": { 3165 "features": [ 3166 "ExpressionMatch", 3167 "RequestTransform", 3168 "ResponseTransform" 3169 ] 3170 } 3171 } 3172 ] 3173 } 3175 4.2.3. FCI.SourceMetadataExtended 3177 This object is used to signal the supported features related to the 3178 SourceMetadataExtended configuration object. 3180 Property: load-balance 3182 - Description: List of supported load balancing algorithms in 3183 relation to the SourceMetadataExtended configuration object 3184 (see MI.SourceMetadataExtended) 3186 - Type: Array of strings 3188 - Values: "random", "content-hash", "ip-hash 3190 - Mandatory-to-Specify: No. load balancing is not supported among 3191 sources. 3193 If the FCI.SourceMetadtaExtended object is not exposed/advertised or 3194 if the "load-balance" array is empty, the dCDN does not support the 3195 usage of the load-balance property attached to the 3196 SourceMetadataExtended configuration object (see 3197 MI.SourceMetadataExtended). 3199 Example: 3201 { 3202 "capabilities": [ 3203 { 3204 "capability-type": "FCI.SourceMetadataExtended", 3205 "capability-value": { 3206 "load-balance": [ 3207 "random", 3208 "content-hash", 3209 "ip-hash" 3210 ] 3211 } 3212 } 3213 ] 3214 } 3216 4.2.4. FCI.RequestRouting 3218 This object is used by the dCDN to signal/announce the supported 3219 request routing modes. This can be optionally used by the uCDN to 3220 further select a subset of those modes when operating one of the 3221 iterative delegation modes. See the section on the GenericMetadata 3222 RequestRouting object.. 3224 Property: request-routing-modes 3226 - Description: List of supported request routing modes by the 3227 dCDN. This information is useful when the uCDN decides to 3228 perform a delegation in iterative mode. 3230 - Type: Array of strings 3232 - Values: "DNS", "HTTP-R", "MANIFEST_REWRITE" 3234 - Mandatory-to-Specify: No. If the dCDN does not advertise the 3235 supported request routing modes, they are all supported by 3236 default. 3238 Example: 3240 { 3241 "capabilities": [ 3242 { 3243 "capability-type": "FCI.RequestRouting", 3244 "capability-value": { 3245 "request-routing-modes": [ 3246 "DNS", 3247 "HTTP", 3248 "MANIFEST_REWRITE" 3249 ] 3250 } 3251 } 3252 ] 3253 } 3255 4.2.5. FCI.PrivateFeatures 3257 This object is used by the dCDN to signal/announce the list of 3258 supported private features. See the section on the GenericMetadata 3259 PrivateFeatureList object. 3261 Property: features 3263 - Description: The list of supported private feature 3265 - Type: List nested objects of FCI.PrivateFeature 3267 Example: 3269 { 3270 "capabilities": [ 3271 { 3272 "capability-type": "FCI.PrivateFeatures", 3273 "capability-value": { 3274 "features": [ 3275 { 3276 "feature-oid": "Broadpeak", 3277 "feature-type": "S4Streaming" 3278 } 3279 ] 3280 } 3281 } 3282 ] 3283 } 3285 4.2.5.1. FCI.PrivateFeature 3287 This object contains the following properties: 3289 Property: feature-oid 3291 - Description: The owner/organization that has specified the 3292 feature. 3294 - Type: String 3296 - Mandatory-to-Specify: Yes 3298 Property: feature-type 3300 - Description: Indicates the type/name of the private feature 3301 configuration object. 3303 - Type: String 3305 - Mandatory-to-Specify: Yes 3307 4.2.6. FCI.OcnSelection 3309 This object is used by the dCDN to signal/announce the supported OCN 3310 types and/or their transport arrangement and/or medium supported by 3311 OCNs. 3313 Property ocn-delivery-list 3315 1. Description: List of supported medium and/or transport 3316 arrangements. 3318 2. Type: Array of nested objects, each containing the following 3319 properties: 3321 o Property: ocn-medium 3323 - Description: This property lists the supported mediums. 3325 - Type: Array of strings. The following values are specified: 3326 "SATELLITE" 3328 - Mandatory-to-Specify: No 3330 o Property: ocn-transport 3331 - Description: Instructs the dCDN to perform delegation operating 3332 a particular transport arrangement. The following values are 3333 specified: "MABR". 3335 - Type: Array of strings 3337 - Mandatory-to-Specify: No 3339 .....Property: ocn-type-list 3341 o Description: List of supported OCN types. Examples include: "HOME" 3342 or "EDGE". 3344 o Type: Array of strings 3346 o Mandatory-to-Specify: No 3348 5. IANA Considerations 3350 5.1. CDNI Payload Types 3352 This document requests the registration of the following entries 3353 under the "CDNI Payload Types" registry hosted by IANA 3355 +==============================+===============+ 3356 | Payload type | Specification | 3357 +==============================+===============+ 3358 | MI.CachePolicy | RFCthis | 3359 +------------------------------+---------------+ 3360 | MI.NegativeCachePolicy | RFCthis | 3361 +------------------------------+---------------+ 3362 | MI.StaleContentCachePolicy | RFCthis | 3363 +------------------------------+---------------+ 3364 | MI.CacheBypassPolicy | RFCthis | 3365 +------------------------------+---------------+ 3366 | MI.ComputedCacheKey | RFCthis | 3367 +------------------------------+---------------+ 3368 | MI.AllowCompress | RFCthis | 3369 +------------------------------+---------------+ 3370 | MI.SourceMetadataExtended | RFCthis | 3371 +------------------------------+---------------+ 3372 | MI.SourceExtended | RFCthis | 3373 +------------------------------+---------------+ 3374 | MI.LoadBalanceMetadata | RFCthis | 3375 +------------------------------+---------------+ 3376 | MI.HeaderAuth | RFCthis | 3377 +------------------------------+---------------+ 3378 | MI.AWSv4Auth | RFCthis | 3379 +------------------------------+---------------+ 3380 | MI.CrossOriginPolicy | RFCthis | 3381 +------------------------------+---------------+ 3382 | MI.AuthTokenMetadata (TBD) | RFCthis | 3383 +------------------------------+---------------+ 3384 | MI.CertificateMetadata (TBD) | RFCthis | 3385 +------------------------------+---------------+ 3386 | MI.OcnSelection | RFCthis | 3387 +------------------------------+---------------+ 3388 | MI.RequestRouting | RFCthis | 3389 +------------------------------+---------------+ 3390 | MI.ProcessingStages | RFCthis | 3391 +------------------------------+---------------+ 3392 | MI.StageRules | RFCthis | 3393 +------------------------------+---------------+ 3394 | MI.ExpressionMatch | RFCthis | 3395 +------------------------------+---------------+ 3396 | MI.StageMetadata | RFCthis | 3397 +------------------------------+---------------+ 3398 | MI.RequestTransform | RFCthis | 3399 +------------------------------+---------------+ 3400 | MI.ResponseTransform | RFCthis | 3401 +------------------------------+---------------+ 3402 | MI.SyntheticResponse | RFCthis | 3403 +------------------------------+---------------+ 3404 | MI.HeaderTransform | RFCthis | 3405 +------------------------------+---------------+ 3406 | MI.HTTPHeader | RFCthis | 3407 +------------------------------+---------------+ 3408 | MI.ServiceIDs | RFCthis | 3409 +------------------------------+---------------+ 3410 | MI.TrafficType | RFCthis | 3411 +------------------------------+---------------+ 3412 | MI.LoggingMetadata (TBD) | RFCthis | 3413 +------------------------------+---------------+ 3414 | MI.PrivateFeatureList | RFCthis | 3415 +------------------------------+---------------+ 3416 | FCI.AuthTypes | RFCthis | 3417 +------------------------------+---------------+ 3418 | FCI.ProcessingStages | RFCthis | 3419 +------------------------------+---------------+ 3420 | FCI.SourceMetadataExtended | RFCthis | 3421 +------------------------------+---------------+ 3422 | FCI.RequestRouting | RFCthis | 3423 +------------------------------+---------------+ 3424 | FCI.PrivateFeatures | RFCthis | 3425 +------------------------------+---------------+ 3426 | FCI.OcnSelection | RFCthis | 3427 +------------------------------+---------------+ 3429 Table 9: Payload Types 3431 6. Security Considerations 3433 This specification is in accordance with the CDNI Request Routing: 3434 Footprint and Capabilities Semantics. As such, it is subject to the 3435 security and privacy considerations as defined in Section 8 of 3436 [RFC8006] and in Section 7 of [RFC8008] respectively. 3438 7. Conclusion 3440 This document presents requirements and extensions to the CDNI 3441 metadata model to cover typical use cases found in the commercial CDN 3442 and Open Caching ecosystems. By limiting the scope of these 3443 extensions to new GenericMetadata objects, backward compatibility can 3444 be maintained with any existing CDNI Metadata Interface 3445 implementations. 3447 8. References 3449 8.1. Normative References 3451 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 3452 STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, 3453 . 3455 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 3456 Application and Support", STD 3, RFC 1123, 3457 DOI 10.17487/RFC1123, October 1989, 3458 . 3460 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3461 Requirement Levels", BCP 14, RFC 2119, 3462 DOI 10.17487/RFC2119, March 1997, 3463 . 3465 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3466 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 3467 DOI 10.17487/RFC7231, June 2014, 3468 . 3470 [RFC8006] Niven-Jenkins, B., Murray, R., Caulfield, M., and K. Ma, 3471 "Content Delivery Network Interconnection (CDNI) 3472 Metadata", RFC 8006, DOI 10.17487/RFC8006, December 2016, 3473 . 3475 [RFC8007] Murray, R. and B. Niven-Jenkins, "Content Delivery Network 3476 Interconnection (CDNI) Control Interface / Triggers", 3477 RFC 8007, DOI 10.17487/RFC8007, December 2016, 3478 . 3480 [RFC8008] Seedorf, J., Peterson, J., Previdi, S., van Brandenburg, 3481 R., and K. Ma, "Content Delivery Network Interconnection 3482 (CDNI) Request Routing: Footprint and Capabilities 3483 Semantics", RFC 8008, DOI 10.17487/RFC8008, December 2016, 3484 . 3486 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3487 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3488 May 2017, . 3490 [RFC8804] Finkelman, O. and S. Mishra, "Content Delivery Network 3491 Interconnection (CDNI) Request Routing Extensions", 3492 RFC 8804, DOI 10.17487/RFC8804, September 2020, 3493 . 3495 [URI.signing] 3496 van Brandenburg, R., Leung, K., and P. Sorber, "URI 3497 Signing for CDN Interconnection (CDNI)", 8 October 2019, 3498 . 3501 [W3C] "Cross-Origin Resource Sharing", 3502 . 3504 8.2. Informative References 3506 [AWSv4Method] 3507 "Authenticating Requests (AWS Signature Version 4)", 3508 . 3511 [OC-CI] Goldstein, G., Ed., Power, W., Bichot, G., and A. Siloniz, 3512 "Open Caching - Configuration Interface Functional 3513 Specification (Parts 1,2,3)", Version 0.1, 2 July 2021. 3515 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 3516 Content", RFC 5861, DOI 10.17487/RFC5861, May 2010, 3517 . 3519 [RFC6707] Niven-Jenkins, B., Le Faucheur, F., and N. Bitar, "Content 3520 Distribution Network Interconnection (CDNI) Problem 3521 Statement", RFC 6707, DOI 10.17487/RFC6707, September 3522 2012, . 3524 [RFC7336] Peterson, L., Davie, B., and R. van Brandenburg, Ed., 3525 "Framework for Content Distribution Network 3526 Interconnection (CDNI)", RFC 7336, DOI 10.17487/RFC7336, 3527 August 2014, . 3529 [RFC7694] Reschke, J., "Hypertext Transfer Protocol (HTTP) Client- 3530 Initiated Content-Encoding", RFC 7694, 3531 DOI 10.17487/RFC7694, November 2015, 3532 . 3534 [SVA] "Streaming Video Alliance Home Page", 3535 . 3537 Authors' Addresses 3539 Glenn Goldstein 3540 Lumen Technologies 3541 United States of America 3542 Email: glenng1215@gmail.com 3544 Will Power 3545 Lumen Technologies 3546 United States of America 3547 Email: wrpower@gmail.com 3549 Guillaume Bichot 3550 Broadpeak 3551 France 3552 Email: guillaume.bichot@gmail.com 3554 Alfonso Siloniz 3555 Telefonica 3556 Spain 3557 Email: alfonsosiloniz@gmail.com