Internet DRAFT - draft-chaudhari-source-access-control-metadata

draft-chaudhari-source-access-control-metadata







Content Delivery Networks Interconnection                   P. Chaudhari
Internet-Draft                                                    Disney
Intended status: Standards Track                            G. Goldstein
Expires: 5 September 2024                                       W. Power
                                                      Lumen Technologies
                                                           A. Warshavsky
                                                                   Qwilt
                                                            4 March 2024


                  CDNI Source Access Control Metadata
           draft-chaudhari-source-access-control-metadata-00

Abstract

   This specification provides an alternative to the MI.SourceMetadata
   objects defined in RFC8006, providing greatly extended capabilities
   with regards to defining multiple sources, load balancing, and
   failover rules across those sources, as well as a mechanism for a
   content delivery network (CDN) to monitor source health and pull
   unhealthy sources out of rotation.  Additionally, new methods are
   defined for authentication access to an upstream source/origin.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 5 September 2024.

Copyright Notice

   Copyright (c) 2024 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.



Chaudhari, et al.       Expires 5 September 2024                [Page 1]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Requirements  . . . . . . . . . . . . . . . . . . . . . . . .   3
   3.  MI.SourceMetadataExtended . . . . . . . . . . . . . . . . . .   3
     3.1.  MI.SourceExtended . . . . . . . . . . . . . . . . . . . .   6
       3.1.1.  MI.SourceConnectionControl  . . . . . . . . . . . . .  10
         3.1.1.1.  MI.SourceByteReadTimeoutActions . . . . . . . . .  14
         3.1.1.2.  MI.SourceTimeoutActions . . . . . . . . . . . . .  15
         3.1.1.3.  MI.SourceConnectionRetries  . . . . . . . . . . .  15
       3.1.2.  MI.HTTPCodeFailover . . . . . . . . . . . . . . . . .  18
         3.1.2.1.  MI.HTTPCodeFailoverActions  . . . . . . . . . . .  21
         3.1.2.2.  MI.HTTPCodeReforwards . . . . . . . . . . . . . .  22
       3.1.3.  MI.EndpointDetention  . . . . . . . . . . . . . . . .  23
         3.1.3.1.  MI.HTTPErrorCodeTrigger . . . . . . . . . . . . .  24
         3.1.3.2.  MI.EndpointDetentionTrigger . . . . . . . . . . .  24
         3.1.3.3.  MI.EndpointRepeatingFailures  . . . . . . . . . .  25
     3.2.  MI.SourceDetention  . . . . . . . . . . . . . . . . . . .  27
       3.2.1.  MI.DetentionFullBehavior  . . . . . . . . . . . . . .  28
       3.2.2.  MI.DetentionResetBehavior . . . . . . . . . . . . . .  28
     3.3.  MI.LoadBalanceMetadata  . . . . . . . . . . . . . . . . .  31
   4.  New Authentication Types  . . . . . . . . . . . . . . . . . .  33
     4.1.  MI.HeaderAuth . . . . . . . . . . . . . . . . . . . . . .  33
     4.2.  MI.AWSv4Auth  . . . . . . . . . . . . . . . . . . . . . .  34
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .  37
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  37
     6.1.  CDNI Payload Types  . . . . . . . . . . . . . . . . . . .  37
   7.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  39
   8.  Normative References  . . . . . . . . . . . . . . . . . . . .  39
   9.  Informative References  . . . . . . . . . . . . . . . . . . .  40
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  40

1.  Introduction

   The [RFC8006] MI.SourceMetadata and Source objects provide the dCDN
   with information about content acquisition, i.e., how to contact an
   upstream content delivery network (uCDN) or an origin server to
   obtain the content to be served.  This specification details
   alternatives to these objects (using MI.SourceMetadataExtended and
   MI.SourceExtended), that provide a rich set of additional
   capabilities for managing the connection and access to upstream
   sources, such as:



Chaudhari, et al.       Expires 5 September 2024                [Page 2]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   *  Designation as to whether a source requires Hypertext Transfer
      Protocol Secure (HTTPS) access.

   *  Specification of the source's Transmission Control Protocol (TCP)
      port number.

   *  Web root path specification for the source.

   *  Indication as to whether redirects should be followed.

   *  Support for additional forms of origin authentication.

   *  Multi-origin failover - The ability to specify a list of origins
      that can act as fallbacks to the primary origin.  Failure rules
      can specify types of errors and timeout values that trigger
      failover.

   *  Multi-origin load balancing - The ability to specify a list of
      origins that can be selected by one of several balancing rules
      (random, content hash, or IP hash).

   *  Specification of connection control parameters for origin access,
      with detailed options for specifying error handling, timeouts, and
      retries.

   *  Mechanisms to track the health of upstream sources and place
      unhealthy sources in detention (an unusable state) until they
      return to good health.

2.  Requirements

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

3.  MI.SourceMetadataExtended

   MI.SourceMetadataExtended is an alternative to the CDN
   Interconnection (CDNI) standard MI.SourceMetadata object, which adds
   a property to specify load balancing across multiple sources, a
   MI.SourceExtended subobject with additional attributes to the CDNI
   standard Source object and a MI.SourceDetention subobject to manage
   unavailable sources.








Chaudhari, et al.       Expires 5 September 2024                [Page 3]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   While both MI.SourceMetadataExtended and MI.SourceMetadata can be
   provided for backward compatibility, a dCDN that advertises
   capability for MI.SourceMetadataExtended will ignore
   MI.SourceMetadata if both are provided for a given host or path
   match.

   The following diagram shows MI.SourceMetadataExtended and its group
   of subobjects:

   CDNi Metadata Object Model
   +-----------------+
   |SourceMetadata   |
   --------|----------
   |sources|MI.Source|----|
   +-------|---------+    |
                          v
   +-------------------------------+
   |Source                         |
   ---------------------------------
   |acquisition-auth|MI.Auth       |
   ---------------------------------
   |endpoints       |MI.Endpoint []|
   ---------------------------------
   |protocol        |MI.Protocol   |
   +----------------|--------------+


   Service Configuration Object Model
   +-----------------------------------+
   |SourceMetadataExtended             |
   -----------------|-------------------
   |sources         |MI.SourceExtended |----|
   -----------------|-------------------    |
   |source-detention|MI.SourceDetention|    |
   -----------------|-------------------    |
   |load-balance    |MI.LoadBalance    |    |
   +----------------|------------------+    |
                                            v
   +---------------------------------------------+
   |SourceExtended                               |
   -------------------|---------------------------
   |acquisition-auth  |MI.Auth                   |
   -------------------|---------------------------
   |endpoints         |MI.Endpoint []            |
   -------------------|---------------------------
   |protocol          |MI.Protocol               |
   -------------------|---------------------------
   |origin-host       |String                    |



Chaudhari, et al.       Expires 5 September 2024                [Page 4]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   -------------------|---------------------------
   |webroot           |String                    |
   -------------------|---------------------------
   |follow-redirects  |Boolean                   |
   -------------------|---------------------------
   |failover-errors   |String []                 |
   -------------------|---------------------------
   |timeout-ms        |Integer                   |
   -------------------|---------------------------
   |connection-control|MI.SourceConnectionControl|
   -------------------|---------------------------
   |http-code-failover|MI.HTTPCodeFailover       |
   -------------------|---------------------------
   |endpoint-detention|MI.EndpointDetention      |
   +------------------|--------------------------+

              Figure 1: MI.SourceMetadataExtended Object Model

   Property: sources

   *  Description: The sources from which the dCDN can acquire content,
      listed in order of preference.

   *  Type: Array of MI.SourceExtended objects

   *  Mandatory-to-Specify: No.  The default is to use a static
      configuration, out-of-band from the CDNI metadata interface.

   Property: source-detention

   *  Description: Specifies rules for handling detention at the set of
      sources.

   *  Type: SourceDetention object

   *  Mandatory-to-Specify: No.  If not specified, the dCDN-specific
      behavior gets used.

   Property: load-balance

   *  Description: Specifies load balancing rules for the set of
      sources.

   *  Type: LoadBalanceMetadata object

   *  Mandatory-to-Specify: No





Chaudhari, et al.       Expires 5 September 2024                [Page 5]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   The following is an example of an MI.SourceMetadataExtended object
   with the associated MI.LoadBalanceMetadata configuration object:


   {
     "generic-metadata-type": "MI.SourceMetadataExtended",
     "generic-metadata-value": {
       "sources": [
         {
           "endpoints": [
             "a.service123.ucdn.example",
             "b.service123.ucdn.example"
           ],
           "protocol": "http/1.1"
         },
         {
           "endpoints": [
             "origin.service123.example"
           ],
           "protocol": "http/1.1"
         }
       ],
       "load-balance": {
         "balance-algorithm": "content-hash",
         "balance-path-pattern": "^/prod/(.*)/.*\\.ts$"
       }
     }
   }

                                  Figure 2

3.1.  MI.SourceExtended

   MI.SourceExtended is an alternative to the CDNI standard Source
   object with additional metadata.  It contains all the attributes of
   the [RFC8006] Source object (acquisition-auth, endpoints, and
   protocol), with additions specified below.

   Property: acquisition-auth

   *  Description: The authentication method to use when requesting
      content from this source.  Same as [RFC8006]

   *  Type: Auth (see [RFC8006] Section 4.2.7 and the new MI.Auth types
      in this specification)

   *  Mandatory-to-Specify: No.  The default is no authentication
      required.



Chaudhari, et al.       Expires 5 September 2024                [Page 6]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   Property: endpoints

   *  Description: The origins from which the dCDN can acquire content.
      If multiple endpoints are specified, they are all equal, i.e., the
      list is not ordered by preference.  Same as [RFC8006]

   *  Type: Array of endpoint objects (see [RFC8006] Section 4.3.3)

   *  Mandatory-to-Specify: Yes

   Property: protocol

   *  Description: The network retrieval protocol to use when requesting
      content from this source.  Same as [RFC8006]

   *  Type: Protocol (see [RFC8006] Section 4.3.2)

   *  Mandatory-to-Specify: Yes

   Property: origin-host

   *  Description: The Hypertext Transfer Protocol (HTTP) host header to
      pass to the endpoints when retrieving content from a uCDN.  The
      host MUST conform to the Domain Name System (DNS) syntax defined
      in [RFC1034] and [RFC1123]

   *  Type: String

   *  Mandatory-to-Specify: No.  The default is to use the host name
      passed by the dCDN.

   Property: webroot

   *  Description: The path element that is prepended to a resource's
      Uniform Resource Identifier (URI) before retrieving content from a
      uCDN.

   *  Type: String, typically starting with a "/"

   *  Mandatory-to-Specify: No.  The default is to use the original URI.

   Property: follow-redirects

   *  Description: If the follow-redirects property is set to "True",
      HTTP redirect responses returned from a uCDN will be followed when
      retrieving content.  Otherwise, the HTTP redirect response is
      returned to the client.




Chaudhari, et al.       Expires 5 September 2024                [Page 7]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   *  Type: Boolean

   *  Mandatory-to-Specify: No.  The default is "True" (i.e., follow
      redirect responses from the uCDN).

   Property: failover-errors

   *  Description: An array of HTTP response error status codes (see
      Sections 15.5 and 15.6 of [RFC9110]), that if returned from the
      uCDN, will trigger a failover to the next source in the
      MI.SourceMetadataExtended source array.  If the uCDN returns an
      HTTP error code that is not in the failover-errors array, that
      error code is returned to the client of the dCDN.  Note that use
      of the http-code-failover property overrides this setting.

   *  Type: Array of HTTP response status codes encoded as strings.  Any
      HTTP status code from 100 to 599, or any of the special values,
      "2xx", "3xx", "4xx" or "5xx", where "xx" implies everything from
      00 to 99.  While repeated and redundant values in the array are
      allowed, they SHOULD be avoided for efficiency (no reason to
      specify both 5xx and 503, for example).

   *  Mandatory-to-Specify: No.  The default is to revert to [RFC8006]
      behavior.

   Property: timeout-ms

   *  Description: A timeout, in milliseconds, to apply when connecting
      to a uCDN.  If the connection is not established within timeout-
      ms, this source is abandoned and the next source in the
      MI.SourceMetadataExtended source array is tried.  Once a
      connection is established, timeout-ms is used on subsequent reads
      of data from the uCDN.  Note that use of the connection-control
      property overrides this setting.

   *  Type: Integer

   *  Mandatory-to-Specify: No.  The default is to revert to [RFC8006]
      behavior if neither this property or connection-control are
      specified.

   Property: connection-control

   *  Description: Specifies how connection-related errors and timeouts
      are handled.  When specified, it overrides the timeout-ms
      property.

   *  Type: SourceConnectionControl object



Chaudhari, et al.       Expires 5 September 2024                [Page 8]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   *  Mandatory-to-Specify: No.  If not specified, the timeout-ms
      property is used to configure simple connection control timeouts.

   Property: http-code-failover

   *  Description: Specifies how HTTP response error codes are handled.
      When specified, it overrides the failover-errors property.

   *  Type: HTTPCodeFailover object

   *  Mandatory-to-Specify: No.  If not specified, the failover-errors
      property is used to configure error handling behavior for HTTP
      response error codes.

   Property: endpoint-detention

   *  Description: Defines error-based triggers for which an endpoint is
      put in detention (excluded from future use) for a given duration
      of time.

   *  Type: EndpointDetention object

   *  Mandatory-to-Specify: No.  If not specified, no health check and
      detention is done on an unhealthy endpoint.


   The following is an example of an MI.SourceExtended object that
   describes a pair of endpoints (servers) that the dCDN can use to
   acquire content for the applicable host and/or URI path:






















Chaudhari, et al.       Expires 5 September 2024                [Page 9]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   {
     "generic-metadata-type": "MI.SourceMetadataExtended",
     "generic-metadata-value": {
       "sources": [
         {
           "endpoints": [
             "a.service123.ucdn.example",
             "b.service123.ucdn.example:8443"
           ],
           "protocol": "https/1.1",
           "origin-host": "internal.example.com",
           "webroot": "/prod",
           "follow-redirects": false,
           "timeout-ms": 4000,
           "failover-errors": [ "502", "503", "504" ]
         },
         {
           "endpoints": [ "origin.service123.example" ],
           "protocol": "http/1.1",
           "webroot": "/prod",
           "follow-redirects": true,
           "timeout-ms": 8000
         }
       ]
     }
   }

                                  Figure 3

3.1.1.  MI.SourceConnectionControl

   MI.SourceConnectionControl is a subobject of MI.SourceExtended and
   allows for the dCDN to specify how it will handle connection timeouts
   and errors against an origin/uCDN.  The use of this object overrides
   the timeout-ms property of MI.SourceExtended, even if any timeout
   properties of this object are not configured.

   The following diagram illustrates the model for a CDN source load
   balancer failing over between multiple sources based on different
   types of timeout errors.











Chaudhari, et al.       Expires 5 September 2024               [Page 10]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


                                                    +----------+
                                            1*|---->|EndPoint-1|
                           Source-1           |     +----------+
               1*         +-----------------------+       |
             ------------>|SourceConnectionControl|       |
             |            +-----------------------+       |
             |                                |     +----------+
             |                       |      2*|---->|EndPoint-n|
   +--------------------+            |              +----------+
   |Source Load Balancer|            |
   +--------------------+            |              +----------+
             |                       |      1*|---->|EndPoint-1|
             |             Source-n           |     +----------+
             |            +-----------------------+       |
             |----------->|SourceConnectionControl|       |
               3*         +-----------------------+       |
                                              |     +----------+
                                            2*|---->|EndPoint-n|
     Legend                                         +----------+
       1* - primary flow
       2* - failover across Endpoints due to timeouts
       3* - failover across Sources after exhausting Endpoints

                   Figure 4: Failover Model for timeouts

   Property: connection-setup-timeout-ms

   *  Description: The time, in milliseconds, within which a connection
      MUST be established against an endpoint of an MI.SourceExtended
      object.

   *  Type: Integer.  A value greater than 0 to define a timeout, in
      milliseconds, for establishing a new network connection.

   *  Mandatory-to-Specify: No.  If not specified, internal dCDN values
      are used.

   Property: connection-setup-timeout-ms-actions

   *  Description: Specifies error handling actions to take when the
      connection could not be established within a given timeout, as
      specified by the connection-setup-timeout-ms property.  It is an
      error to specify this property without the corresponding
      connection-setup-timeout-ms property.

   *  Type: SourceTimeoutActions object





Chaudhari, et al.       Expires 5 September 2024               [Page 11]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   *  Mandatory-to-Specify: No.  If not specified, and a timeout occurs
      when establishing a new network connection, the next
      MI.SourceExtended will be used as a failover action.

   Property: first-byte-read-timeout-ms

   *  Description: The time, in milliseconds, within which the first
      byte MUST be received/read on a new network connection.

   *  Type: Integer.  A value greater than 0 to define a timeout, in
      milliseconds, for reading the first byte on a new network
      connection.

   *  Mandatory-to-Specify: No.  If not specified, internal dCDN values
      are used.

   Property: first-byte-read-timeout-ms-actions

   *  Description: Specifies the error handling actions to take when the
      first byte on a new connection could not be read within a given
      timeout, as specified by the first-byte-read-timeout-ms property.
      It is an error to specify this property without the corresponding
      first-byte-read-timeout-ms property.

   *  Type: SourceTimeoutActions object

   *  Mandatory-to-Specify: No.  If not specified, and a timeout occurs
      when reading the first byte on a new network connection, the next
      MI.SourceExtended will be used as a failover action.

   Property: byte-read-timeout-ms

   *  Description: The time, in milliseconds, within which the next byte
      MUST be received/read on a connection.

   *  Type: Integer.  A value greater than 0 to define a timeout, in
      milliseconds, for reading the next byte on an established network
      connection.

   *  Mandatory-to-Specify: No.  If not specified, internal dCDN values
      are used.

   Property: byte-read-timeout-ms-actions








Chaudhari, et al.       Expires 5 September 2024               [Page 12]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   *  Description: Specifies error handling actions to take when the
      next byte on a connection could not be read within a given
      timeout, as specified by the byte-read-timeout-ms property.  It is
      an error to specify this property without the corresponding byte-
      read-timeout-ms property.

   *  Type: SourceByteReadTimeoutActions object

   *  Mandatory-to-Specify: No.  If not specified, and a timeout occurs
      when reading bytes from an existing network connection, the next
      MI.SourceExtended will be used as a failover action.

   Property: connection-keep-alive-time-ms

   *  Description: Specifies the time, in milliseconds, to keep an idle
      connection open.

   *  Type: Integer.  A value greater than 0 defines the amount of time
      for which a connection SHOULD be kept alive.

   *  Mandatory-to-Specify: No.  If not specified, any dCDN defined
      internal values are used.

   Property: max-connection-retries-per-source

   *  Description: Specifies the upper bound of retries allowed across
      all endpoints of an MI.SourceExtended object for all timeout
      errors.

   *  Type: Integer.  A value greater than or equal to 0 indicates the
      maximum number of retries against all endpoints of the current
      MI.SourceExtended object for connection establishment, first-byte-
      read, and byte-read timeout errors.  A value of 0 indicates that
      no retries are to be performed against this source.

   *  Mandatory-to-Specify: No.  If not specified, any retry values
      defined in the properties of connection-setup-timeout-ms-actions,
      first-byte-read-timeout-ms-actions, and byte-read-timeout-ms-
      actions for their respective error types are used.

   Property: resume-from-last-byte-of-previous-source

   *  Description: Upon establishing a new connection to an origin/uCDN,
      this specifies whether the next byte to read will start from the
      last byte read from a previous MI.SourceExtended object.  This is
      only applicable when the content length of the object being
      downloaded is known.




Chaudhari, et al.       Expires 5 September 2024               [Page 13]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   *  Type: Boolean.  If "True", the next byte read will resume from the
      last successful byte downloaded from a previous MI.SourceExtended
      object.  The default is "False".

   *  Mandatory-to-Specify: No.

   Property: resume-from-last-byte-of-previous-endpoint

   *  Description: Upon establishing a new connection to an origin/uCDN,
      this specifies whether the next byte read will start from the last
      byte read from a previous endpoint of the current
      MI.SourceExtended.  This is only applicable when the content
      length of the object being downloaded is known.

   *  Type: Boolean.  If "True", the next byte read will resume from the
      last successful byte downloaded from a previous endpoint of the
      current MI.SourceExtended object.  The default is "False".

   *  Mandatory-to-Specify: No.

3.1.1.1.  MI.SourceByteReadTimeoutActions

   MI.SourceByteReadTimeoutActions is a subobject of
   MI.SourceConnectionControl and allows for the specification of
   actions to be taken when a timeout occurs when reading the next byte
   on an existing network connection against an endpoint of an origin/
   uCDN.

   Property: retries

   *  Description: Specifies the number of retries that MUST occur
      against a given endpoint when an error occurs.

   *  Type: SourceConnectionRetries object

   *  Mandatory-to-Specify: No.  If not specified, no retries are done.

   Property: error-state

   *  Description: Specifies whether to capture any error message for
      the current error condition.

   *  Type: SetVariable object specifying a user-defined variable.  See
      the Metadata Expression Language Specification [SVTA2031]

   *  Mandatory-to-Specify: No.  If not specified, a dCDN will not
      capture the error condition for which this object is used.




Chaudhari, et al.       Expires 5 September 2024               [Page 14]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   Property: resume-from-last-byte

   *  Description: Specifies whether to resume reading from the last
      byte of the current endpoint only if the content length of the
      object being downloaded is known.

   *  Type: Boolean.  If set to "True", when a byte read timeout occurs
      against an endpoint and if a retry action is performed against the
      same endpoint, the byte read will resume from the last byte
      downloaded.  The default value is "False".

   *  Mandatory-to-Specify: No.  If not specified, a retry against the
      current endpoint will download the requested object from the first
      byte.

3.1.1.2.  MI.SourceTimeoutActions

   MI.SourceTimeoutActions is a subobject of MI.SourceConnectionControl
   and allows for the specification of actions to be taken when a
   timeout occurs against an endpoint of an origin/uCDN.

   Property: retries

   *  Description: Specifies the number of retries that MUST occur
      against a given endpoint when an error occurs.

   *  Type: SourceConnectionRetries object

   *  Mandatory-to-Specify: No.  If not specified, no retries are made.

   Property: error-state

   *  Description: Specifies whether to capture any error message for
      the current error condition.

      -  Type: SetVariable object specifying a user-defined variable.
         See the Metadata Expression Language Specification [SVTA2031]

   *  Mandatory-to-Specify: No.  If not specified, a dCDN will not
      capture the error condition for which this object is used.

3.1.1.3.  MI.SourceConnectionRetries

   MI.SourceConnectionRetries is a subobject that allows for the
   specification of retries to be performed against endpoints of an
   MI.SourceExtended object.

   Property: max-retries-per-source



Chaudhari, et al.       Expires 5 September 2024               [Page 15]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   *  Description: Specifies the maximum number of retries against all
      endpoints of the MI.SourceExtended object for a given class of
      error.

   *  Type: Integer.  A value of greater than or equal to 0 indicates
      the number of retries.  Example: If the value of max-retries-per-
      source of the retries property of connection-setup-timeout-ms-
      actions is set to 5, a maximum of 5 retries are allowed for
      connection setup timeout errors across all endpoints of the
      current MI.SourceExtended object.  If this value is set to 0, no
      retries will be done.

   *  Mandatory-to-Specify: No.  If not specified, the individual
      endpoint-specific retries are honored.

   Property: retries-per-endpoint

   *  Description: Specifies the number of retries against the current
      endpoint of the MI.SourceExtended object for a given class of
      error.

   *  Type: Integer.  A value of greater than or equal to 0 indicates
      the number of retries.  Example: If the value of retries-per-
      endpoint of the retries property of connection-setup-timeout-ms-
      actions is set to 5, 5 retries will be done for connection-setup
      timeout errors on the current endpoint of the current
      MI.SourceExtended object.  If this value is set to 0, no retries
      will be done.

   *  Mandatory-to-Specify: No.  If not specified, the value of 0 is
      assumed and no retries will be done for the given class of error.

   The following is an example showing how different connection errors
   against an origin/uCDN can be handled and a custom response sent to
   the player/client.  This example illustrates use of the Processing
   Stages Model [SVTA2032] to apply metadata at the clientResponse
   Stage:

   [
     {
       "generic-metadata-type": "MI.SourceConnectionControl",
       "generic-metadata-value": {
         "connection-setup-timeout-ms": 10,
         "connection-setup-timeout-ms-actions": {
           "retries": {
             "max-retries-per-source": 3,
             "retries-per-endpoint": 1
           },



Chaudhari, et al.       Expires 5 September 2024               [Page 16]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


           "error-state": {
             "variable-name": "connection-setup-timeout",
             "variable-value": "true"
           }
         },
         "first-byte-read-timeout-ms": 1,
         "first-byte-read-timeout-ms-actions": {
           "retries": {
             "max-retries-per-source": 3,
             "retries-per-endpoint": 1
           },
           "error-state": {
             "variable-name": "first-byte-read-timeout",
             "variable-value": "true"
           }
         },
         "byte-read-timeout-ms": 1,
         "byte-read-timeout-ms-actions": {
           "resume-from-last-byte": true,
           "retries": {
             "max-retries-per-source": 3,
             "retries-per-endpoint": 1
           },
           "error-state": {}
         },
         "connection-keep-alive-time-ms": 3,
         "max-connection-retries-per-source": 3,
         "resume-from-last-byte-of-previous-source": true,
         "resume-from-last-byte-of-previous-endpoint": true
       }
     },
     {
       "generic-metadata-type": "MI.ProcessingStages",
       "generic-metadata-value": {
         "client-response": [
           {
             "match": "var.connection-setup-timeout-ms == 'true'",
             "stage-metadata": {
               "response-transform": {
                 "header-transform": {
                   "add": [
                     {
                       "name": "x-failure-handling",
                       "value": "connection setup timeout",
                       "value-is-expression": false
                     }
                   ]
                 },



Chaudhari, et al.       Expires 5 September 2024               [Page 17]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


                 "response-status": "404",
                 "status-is-expression": false
               }
             }
           }
         ]
       }
     }
   ]

                                  Figure 5

3.1.2.  MI.HTTPCodeFailover

   MI.HTTPCodeFailover is a new GenericMetadata subobject of
   MI.SourceExtended that allows the dCDN to specify how it will handle
   HTTP error codes against an origin/uCDN.

   The following diagram illustrates the model for a CDN source load
   balancer failing over between multiple sources based on HTTP error
   code status:

                                                    +----------+
                                            1*|---->|EndPoint-1|
                           Source-1           |     +----------+
               1*         +-----------------------+       |
             ------------>|HTTPCodeFailover       |       |
             |            +-----------------------+       |
             |                                |     +----------+
             |                       |      2*|---->|EndPoint-n|
   +--------------------+            |              +----------+
   |Source Load Balancer|            |
   +--------------------+            |              +----------+
             |                       |      1*|---->|EndPoint-1|
             |             Source-n           |     +----------+
             |            +-----------------------+       |
             |----------->|HTTPCodeFailover       |       |
               3*         +-----------------------+       |
                                              |     +----------+
                                            2*|---->|EndPoint-n|
     Legend                                         +----------+
       1* - primary flow
       2* - failover across Endpoints due to HTTP Error codes
       3* - failover across Sources after exhausting Endpoints

               Figure 6: Failover Model for HTTP status codes

   Property: max-reforwards-per-source



Chaudhari, et al.       Expires 5 September 2024               [Page 18]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   *  Description: Specifies the upper bound of reforwards allowed
      across all endpoints of an MI.SourceExtended object for all
      configured HTTP error codes.

   *  Type: Integer.  A value greater than or equal to 0 indicates the
      maximum number of retries against all endpoints of the current
      MI.SourceExtended object for all configured HTTP error codes.

   *  Mandatory-to-Specify: No.  If not specified, any reforward values
      defined within the http-code-failover-actions property are used.

   Property: http-code-failover-actions

   *  Description: Specifies the different HTTP codes for which failover
      actions against an origin/uCDN MUST be done.

   *  Type: Array of MI.HTTPCodeFailoverActions object

   *  Mandatory-to-Specify: Yes.

   Following is an example of MI.HTTPCodeFailover illustrating how
   different HTTP error codes from an origin/uCDN can be handled and a
   custom response sent to the player/client.  In this example, a CDNI
   metadata expression user-defined variable named "forward-http-code-
   failover" is set with the string value "404-failure".


























Chaudhari, et al.       Expires 5 September 2024               [Page 19]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   {
     "generic-metadata-type": "MI.HTTPCodeFailover",
     "generic-metadata-value": {
       "max-reforwards-per-source": 2,
       "http-code-failover-actions": [
         {
           "http-codes": [
             "404"
           ],
           "reforwards": {
             "max-reforwards-per-source": 1,
             "reforwards-per-endpoint": 2
           },
           "error-state": {
             "variable-name": "forward-http-code-failover",
             "variable-value": "404-failure"
           }
         },
         {
           "http-codes": [
             "512"
           ],
           "reforwards": {
             "max-reforwards-per-source": 1,
             "reforwards-per-endpoint": 2
           },
           "error-state": {
             "variable-name": "forward-http-code-failover",
             "variable-value": "404-failure"
           }
         }
       ]
     }
   }

                                  Figure 7

   Continuing with the example, the "forward-http-code-failover" user-
   defined variable is tested in a subsequent match expression in the
   context of the Processing Stages Model [SVTA2032] to trigger an HTTP
   response transformation (in this case, the addition of a custom
   header).









Chaudhari, et al.       Expires 5 September 2024               [Page 20]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   {
     "generic-metadata-type": "MI.ProcessingStages",
     "generic-metadata-value": {
       "client-response": [
         {
           "match": "var.forward-http-code-failover == '404-failure'",
           "stage-metadata": {
             "response-transform": {
               "header-transform": {
                 "add": [
                   {
                     "name": "x-failure-handling",
                     "value": "forward side 404",
                     "value-is-expression": false
                   }
                 ]
               },
               "response-status": "404",
               "status-is-expression": false
             }
           }
         }
       ]
     }
   }

                                  Figure 8

3.1.2.1.  MI.HTTPCodeFailoverActions

   MI.HTTPCodeFailoverActions is a subobject of MI.HTTPCodeFailover.  It
   defines one or more HTTP error codes against which some failover
   action MUST be performed.

   Property: http-codes

   *  Description: An array of HTTP response error status codes (see
      Sections 15.5 and 15.6 of [RFC9110]) received from an origin/uCDN
      for which a failover MUST be performed.

   *  Type: Array of HTTP response status codes encoded as strings.  Any
      HTTP status code from 100 to 599, or any of the special values,
      "2xx", "3xx", "4xx" or "5xx", where "xx" implies everything from
      00 to 99.  While repeated and redundant values in the array are
      allowed, they SHOULD be avoided for efficiency (no reason to
      specify both 5xx and 503, for example).

   *  Mandatory-to-Specify: Yes



Chaudhari, et al.       Expires 5 September 2024               [Page 21]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   Property: reforwards

   *  Description: Specifies how the reforwards MUST be done.

   *  Type: MI.HTTPCodeReforwards object

   *  Mandatory-to-Specify: Yes

   Property: error-state

   *  Description: Specifies whether to capture any error message for
      the current error condition.

   *  Type: SetVariable object specifying a user-defined variable.  See
      the Metadata Expression Language (MEL) specification [SVTA2031]

   *  Mandatory-to-Specify: No.  If not specified, a dCDN will not
      capture any information about the specific HTTP error code.

3.1.2.2.  MI.HTTPCodeReforwards

   MI.HTTPCodeReforwards is a subobject of MI.HTTPtpCodeFailoverActions
   and allows for the specification of reforwards that MUST occur
   against endpoints of an MI.SourceExtended object.

   Property: max-reforwards-per-source

   *  Description: Specifies the maximum number of reforwards that can
      be performed across all endpoints of the MI.SourceExtended object
      for a given set of HTTP error codes.

   *  Type: Integer.  A value greater than or equal to 0 indicates the
      maximum number of reforwards against an MI.SourceExtended object.
      A value of 0 indicates that no reforwards will be done against
      this source for the given set of HTTP error codes.

   *  Mandatory-to-Specify: No.  If not specified, any reforward values
      defined in the reforwards-per-endpoint property are honored
      without any caps.

   Property: reforwards-per-endpoint

   *  Description: Specifies the number of reforwards to be performed
      across the current endpoint of the MI.SourceExtended object for a
      given set of HTTP error codes.






Chaudhari, et al.       Expires 5 September 2024               [Page 22]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   *  Type: Integer.  A value of greater than or equal to 0 indicates
      the number of reforwards against the current endpoint.  A value of
      0 indicates that no reforwards will be performed against the
      current endpoint for the given set of HTTP error codes.

   *  Mandatory-to-Specify: No.  If not specified, the default value is
      0.

3.1.3.  MI.EndpointDetention

   MI.EndpointDetention is a subobject of MI.SourceExtended and is used
   to track the health of an endpoint (see [RFC8006] section 4.3.3) and
   place it in detention, if deemed unhealthy.  Unhealthy endpoints are
   not used for future HTTP requests until a set cool-off time is met.
   Error-based triggers are defined for which an endpoint can be put in
   detention for a given duration of time.

   Property: connection-setup-fail-trigger

   *  Description: A trigger for the connection setup error, including
      timeouts for connection establishment, that is fired for a given
      threshold of such errors.

   *  Type: EndpointDetentionTrigger object

   *  Mandatory-to-Specify: No.  If not specified, no health check and
      detention is done for connection errors or connection timeouts.

   Property: read-timeout-trigger

   *  Description: A trigger for the byte read timeout error that is
      fired for a given threshold of such errors.

   *  Type: EndpointDetentionTrigger object

   *  Mandatory-to-Specify: No.  If not specified, no health check and
      detention is done for both first byte and byte read timeout
      errors.

   Property: http-error-code-trigger

   *  Description: A list of HTTP error codes for which a trigger is
      fired for a given threshold of such error codes received from an
      endpoint.

   *  Type: HTTPErrorCodeTrigger object





Chaudhari, et al.       Expires 5 September 2024               [Page 23]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   *  Mandatory-to-Specify: No.  If not specified, no health check and
      detention is done upon receiving HTTP error codes.

   Property: detention-seconds

   *  Description: The time, in seconds, for which an endpoint is put in
      detention (not used) after any error-based trigger fires.

   *  Type: Integer.  A value greater than 0 defines a time, in seconds,
      for which an endpoint is put in detention (not used).

   *  Mandatory-to-Specify: Yes

3.1.3.1.  MI.HTTPErrorCodeTrigger

   MI.HTTPErrorCodeTrigger is a subobject of MI.EndpointDetention and
   defines a trigger for detention based on HTTP error codes.  Any HTTP
   code received from an endpoint that matches against the list of
   defined HTTP error codes counts against a single EndPointTrigger for
   detention.

   Property: trigger

   *  Description: A trigger for HTTP error codes that is fired for a
      given threshold of such error codes received in HTTP responses.

   *  Type: EndpointDetentionTrigger object

   *  Mandatory-to-Specify: Yes

   Property: error-codes

   *  Description: An array of HTTP error response codes that, when
      returned from an endpoint, can cause the endpoint to be triggered
      into an unhealthy state.

   *  Type: Array of HTTP response codes.  The error codes are from 400
      to 599, or one of the special values "4xx" or "5xx", where "xx"
      implies everything from 00 to 99.

   *  Mandatory-to-Specify: Yes

3.1.3.2.  MI.EndpointDetentionTrigger

   MI.EndpointDetentionTrigger is a subobject of MI.EndpointDetention
   and defines a trigger for a specific kind of error against an
   endpoint.




Chaudhari, et al.       Expires 5 September 2024               [Page 24]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   Property: trigger-value

   *  Description: The threshold at which an endpoint is triggered to
      unhealthy state and put in detention.

   *  Type: EndpointRepeatingFailures object

   *  Mandatory-to-Specify: Yes

3.1.3.3.  MI.EndpointRepeatingFailures

   MI.EndpointRepeatingFailures is a subobject of
   MI.EndpointDetentionTrigger and triggers an endpoint to a failure
   state if "event-count" of errors takes place during "time-window-
   millisec", while accounting for at least "fail-event-percent-
   threshold"% of the transactions to this endpoint during this period.

   Property: event-count

   *  Description: The number of errors against an endpoint within a
      duration of time-window-millsec.

   *  Type: Integer.  A value greater than 0.

   *  Mandatory-to-Specify: Yes

   Property: time-window-millsec

   *  Description: The duration, in milliseconds, for which error
      statistics of event-count and fail-event-percent-threshold are
      tracked against an endpoint.

   *  Type: Integer.  A value greater than 0.

   *  Mandatory-to-Specify: Yes

   Property: fail-event-percent-threshold

   *  Description: The minimum percentage of errors against an endpoint
      within a duration of time-window-millsec.

   *  Type: Integer.  A value greater than or equal to 0.

   *  Mandatory-to-Specify: No.  If not specified, an endpoint is
      triggered to an unhealthy state after encountering event-count
      errors without regards to the overall percentage of such errors.





Chaudhari, et al.       Expires 5 September 2024               [Page 25]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   The following example shows the first MI.SourceExtended object
   (sources property) with an EndpointDetention object (endpoint-
   detention property) for the three error conditions of connection
   setup, read timeout, and HTTP error codes.

   The trigger for connection setup errors will put the endpoint in an
   unhealthy state when there are three such errors within 1000
   milliseconds, as long as 10% of attempts to establish a connection
   (and not HTTP requests) against the endpoint have failed within that
   time duration.

   The trigger for read timeout errors is configured to fire for three
   such errors within 1000 milliseconds without any condition for error
   percentage.

   The trigger for HTTP error codes is configured to fire for 404 and
   5xx response codes with at least one such HTTP code received from the
   endpoint within 1000 milliseconds.

   {
     "generic-metadata-type": "MI.SourceMetadataExtended",
     "generic-metadata-value": {
       "sources": [
         {
           "endpoints": [
             "a.origin-tier1.com",
             "b.origin-tier1.com",
             "c.origin-tier1.com"
           ],
           "protocol": "http/1.1",
           "timeout-ms": "4000",
           "failover-errors": [
             "502",
             "503",
             "504",
             "500"
           ],
           "endpoint-detention": {
             "connection-setup-fail-trigger": {
               "trigger-type": "MI.EndpointRepeatingFailures",
               "trigger-value": {
                 "event-count": 3,
                 "time-window-millisec": 1000,
                 "fail-event-percent-threshold": 10
               }
             },
             "read-timeout-trigger": {
               "trigger-type": "MI.EndpointRepeatingFailures",



Chaudhari, et al.       Expires 5 September 2024               [Page 26]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


               "trigger-value": {
                 "event-count": 3,
                 "time-window-millisec": 1000
               }
             },
             "http-error-code-trigger": {
               "error-codes": [
                 "404, 5xx"
               ],
               "trigger": {
                 "trigger-type": "MI.EndpointRepeatingFailures",
                 "trigger-value": {
                   "event-count": 1,
                   "time-window-millisec": 1000
                 }
               }
             },
             "detention-seconds": 60
           }
         },
         {
           "endpoints": [
             "origin-tier2.com"
           ],
           "protocol": "http/1.1"
         }
       ]
     }
   }

                                  Figure 9

3.2.  MI.SourceDetention

   MI.SourceDetention is a subobject of MI.SourceMetadataExtended and
   defines detention rules at the set of sources.

   Property: detention-full-behavior

   *  Description: Defines how a response is constructed when every
      endpoint of each MI.SourceMetadata has been put in detention.

   *  Type: DetentionFullBehavior object

   *  Mandatory-to-Specify: No.  If not specified, the dCDN-specific
      behavior is used.

   Property: detention-reset-behavior



Chaudhari, et al.       Expires 5 September 2024               [Page 27]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   *  Description: After every endpoint of each MI.SourceMetadata is put
      in detention, it defines early removal of an endpoint from
      detention without having served the full duration of detention.

   *  Type: DetentionResetBehavior object

   *  Mandatory-to-Specify: No.  If not specified, an endpoint is
      removed from detention only upon the completion of the detention
      duration.

3.2.1.  MI.DetentionFullBehavior

   A uCDN can configure how a response is constructed when all endpoints
   are in detention.

   Property: serve-if-stale-available

   *  Description: A stale version of the requested object is served
      back to the client.  If no stale objects exist, other properties
      of MI.DetentionFullBehavior apply.

   *  Type: Boolean

   *  Mandatory-to-Specify: No.  The default value is "False", in which
      case other properties of MI.DetentionFullBehavior apply.

   Property: synthetic-response

   *  Description: The synthetic response to return back to the client.

   *  Type: MI.SyntheticResponse object.  See the Processing Stages
      Metadata Specification [SVTA2032]

   *  Mandatory-to-Specify: No.  If not specified, the dCDN-specific
      error response is used.

3.2.2.  MI.DetentionResetBehavior

   When all endpoints of an MI.SourceMetadata are put in detention, this
   object allows a uCDN to define the early removal of an endpoint from
   detention.  All endpoints removed from detention through this
   behavior are available for immediate use for all subsequent client
   requests.

   Property: reset-endpoints






Chaudhari, et al.       Expires 5 September 2024               [Page 28]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   *  Description: The list of endpoints to be removed from detention
      after no healthy endpoints are available across all
      MI.SourceExtended objects.

   *  Type: Array of endpoint objects.

   *  Mandatory-to-Specify: No.  The default value is an empty array,
      indicating that no endpoints can be removed early from detention.

   Property: reset-all-endpoints

   *  Description: All endpoints are removed from detention after no
      healthy endpoints are available across all MI.SourceExtended
      objects.

   *  Type: Boolean

   *  Mandatory-to-Specify: No.  The default value is "False",
      indicating that no endpoints can be removed early from detention.

   The following example shows two MI.SourceExtended objects, each with
   two endpoints.  A detention trigger of type HTTPErrorCodeTrigger for
   the first source and connection setup failure for the second source
   are also defined, with each endpoint set to be put in detention for
   60 seconds.  For the case when all endpoints are put in detention,
   the defined MI.SourceDetention object allows for the return of a
   stale version of the object and fallback to return a 502 if no stale
   object is found.  Additionally, the "a2.origin-tier2.com" endpoint is
   set for early removal from detention.

   {
     "generic-metadata-type": "MI.SourceMetadataExtended",
     "generic-metadata-value": {
       "sources": [
         {
           "endpoints": [
             "a1.origin-tier1.com",
             "b1.origin-tier1.com",
             "c.origin-tier1.com"
           ],
           "failover-errors": [
             "502",
             "503",
             "504",
             "500"
           ],
           "endpoint-detention": {
             "http-error-code-trigger": {



Chaudhari, et al.       Expires 5 September 2024               [Page 29]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


               "error-codes": [
                 "404, 5xx"
               ],
               "trigger": {
                 "trigger-type": "MI.EndpointRepeatingFailures",
                 "trigger-value": {
                   "event-count": 1,
                   "time-window-millisec": 1000
                 }
               }
             },
             "detention-seconds": 60
           }
         },
         {
           "endpoints": [
             "a2.origin-tier2.com",
             "b2.origin-tier2.com"
           ],
           "timeout-ms": 4000,
           "endpoint-detention": {
             "connection-setup-fail-trigger": {
               "trigger-type": "MI.EndpointRepeatingFailures",
               "trigger-value": {
                 "event-count": 3,
                 "time-window-millisec": 1000,
                 "fail-event-percent-threshold": 10
               }
             },
             "detention-seconds": 60
           }
         }
       ],
       "source-detention": {
         "detention-full-behavior": {
           "serve-if-stale-available": true,
           "synthetic-response": {
             "headers": [
               {
                 "name": "x-error-reason",
                 "value": "all sources in detention"
               }
             ],
             "response-status": 502,
             "response-body":
               "req.uri . 'is unavailable due to origin errors'",
             "body-is-expression": true
           }



Chaudhari, et al.       Expires 5 September 2024               [Page 30]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


         },
         "detention-reset-behavior": {
           "reset-endpoints": [
             "a2.origin-tier2.com"
           ],
           "reset-all-endpoints": true
         }
       }
     }
   }

                                 Figure 10

3.3.  MI.LoadBalanceMetadata

   The MI.LoadBalanceMetadata object is a subobject of
   MI.SourceMetadataExtended,defining how content acquisition requests
   are distributed over the MI.SourceExtended objects listed in the
   MI.SourceMetadataExtended object.

   Property: balance-algorithm

   *  Description: Specifies the algorithm to be used when distributing
      content acquisition requests over the sources in an
      MI.SourceMetadataExtended object.  The available algorithms are:

   o random: Requests are distributed over the sources in proportion to
   their associated weights.

   o content-hash: Requests are distributed over the sources in a
   consistent fashion, based on the balance-path-pattern property.

   o ip-hash: Requests are distributed over the sources in a consistent
   fashion based on the IP address of the client requestor.


   *  Type: String, one of the following: random | content-hash | ip-
      hash

   *  Mandatory-to-Specify: No.  The default is to use sources in
      preference order as defined in the MI.SourceMetadataExtended
      object.

   Property: balance-weights

   *  Description: Specifies the relative frequency that a source is
      used when distributing requests.  For example, if there are three
      MI.SourceExtended objects in a MI.SourceMetadataExtended object



Chaudhari, et al.       Expires 5 September 2024               [Page 31]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


      with balance-weights [1, 2, 1], source 1 will receive 1/4 of the
      requests, source 2 will receive 2/4 of the requests, and source 3
      will receive 1/4 of the requests.

   *  Type: Array of integers

   *  Mandatory-to-Specify: No.  The default is to use sources in
      preference order as defined in the MI.SourceMetadataExtended
      object.

   Property: balance-path-pattern

   *  Description: This property specifies a regular expression pattern
      to apply to the URI when calculating the content hash used by the
      balance-algorithm.  For example, "balance-path-pattern":
      "^/prod/(.*)/.*\.ts$" would distribute requests based on the URI
      but exclude the /prod prefix and the .ts segment file.

   *  Type: String (regular expression)

   *  Mandatory-to-Specify: No.  The default is to use the original URI.

   In example 1, the MI.LoadBalanceMetadata object distributes content
   acquisition requests over sources using a content-hash algorithm:

   {
     "generic-metadata-type": "MI.LoadBalanceMetadata",
     "generic-metadata-value": {
       "balance-algorithm": "content-hash",
       "balance-path-pattern": "^/prod/(.*)/.*\\.ts$"
     }
   }

                                 Figure 11


   In example 2, the MI.LoadBalanceMetadata object distributes content
   acquisition requests over sources using the random algorithm:

   {
     "generic-metadata-type": "MI.LoadBalanceMetadata",
     "generic-metadata-value": {
       "balance-algorithm": "random",
       "balance-weights": [
         1,2, 1
       ]
     }
   }



Chaudhari, et al.       Expires 5 September 2024               [Page 32]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


                                 Figure 12

4.  New Authentication Types

   To meet the typical industry requirements for authenticating CDNs to
   external origins, two new authentication types are defined
   (MI.HeaderAuth and MI.AWSv4Auth) to be used within the MI.Auth object
   defined in [RFC8006], section 4.2.7 These authentication types are
   designed to leverage the SVTA/CDNI Protected Secrets Metadata
   standard, allowing for sensitive values to be protected by
   referencing them from an external keystore as an alternative to
   embedding them in the clear in the configuration metadata.

4.1.  MI.HeaderAuth

   The MI.HeaderAuth metadata object is used in the auth-value property
   of the

   MI.Auth object, as defined in [RFC8006] section 4.2.7, and MAY be
   applied to any

   source by including or referencing it under its authentication
   property.  This method of authentication provides a simple capability
   for a mutually agreed upon header to be added by the CDN to all
   requests sent to a specific source/origin.  Note that if a
   dynamically generated header value is required, the RequestTransform
   capabilities within StageProcessing can be used as an alternative to
   synthesize a value.


   Property: header-name

   *  Description: The name of the authentication header.

   *  Type: String

   *  Mandatory-to-Specify: Yes

   Property: header-value

   *  Description: The value of the authentication header (typically a
      pre-shared key).

   *  Type: MI.SecretValue object that can either contain the header
      value in the clear (not recommended) or as a reference to the
      header value in an external key store.  See the Protected Secrets
      Metadata standard [SVTA2039] for more details.




Chaudhari, et al.       Expires 5 September 2024               [Page 33]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   *  Mandatory-to-Specify: Yes

   In the following example the Auth object is used for header
   authentication, referencing an external key vault for the protected
   header value:

   {
     "generic-metadata-type": "MI.SourceMetadataExtended",
     "generic-metadata-value": {
       "sources": [
         {
           "endpoints": [
             "origin.example.com"
           ],
           "protocol": "http/1.1",
           "acquisition-auth": {
             "generic-metadata-type": "MI.Auth",
             "generic-metadata-value": {
               "auth-type": "MI.HeaderAuth",
               "auth-value": {
                 "header-name": "X-Origin-Auth",
                 "header-value": {
                   "secret-store-id": "my-key-vault",
                   "secret-path":
                     "/source/keys/origin.example.com_header"
                 }
               }
             }
           }
         }
       ]
     }
   }

                                 Figure 13

4.2.  MI.AWSv4Auth

   The MI.AWSv4Auth metadata object is used in the auth-value property
   of the MI.Auth object as defined in [RFC8006] section 4.2.7, and MAY
   be applied to any source by including or referencing it under its
   authentication property.









Chaudhari, et al.       Expires 5 September 2024               [Page 34]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   AWSv4 authentication causes upstream requests to have a signature
   applied, following the method described in [AWSv4].  A hash-based
   signature is calculated over the request URI and specified headers,
   and is provided in an Authorization: header on the upstream request.
   The signature is tied to a pre-shared secret key specific to an AWS
   service, region, and key ID.

   Property: access-key-id

   *  Description: The preconfigured ID of the pre-shared authorization
      secret.

   *  Type: String

   *  Mandatory-to-Specify: Yes

   Property: secret-access-key

   *  Description: The pre-shared authorization secret, which is the
      basis of building the signature.

   *  Type: MI.SecretValue object that can either contain the access key
      in the clear (not recommended) or as a reference to the access key
      in an external key store.  See [SVTA2039] for more details.

   *  Mandatory-to-Specify: Yes

   Property: aws-region

   *  Description: The AWS region name that is hosting the service and
      shares the key ID and corresponding pre-shared secret.

   *  Type: String

   *  Mandatory-to-Specify: Yes

   Property: aws-service

   *  Description: The AWS service name that is serving the upstream
      requests.

   *  Type: String

   *  Mandatory-to-Specify: No.  The default is "s3" if not specified.

   Property: host-name





Chaudhari, et al.       Expires 5 September 2024               [Page 35]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   *  Description: The host name to use as part of the signature
      calculation.

   *  Type: String

   *  Mandatory-to-Specify: No.  The default is to use the value of the
      Host: header of the upstream request.  This property is available
      in case the application needs to override the default behavior.

   In the following example, the Auth object is used for AWSv4
   authentication, referencing an external key vault for the protected
   access key:

   {
     "generic-metadata-type": "MI.SourceMetadataExtended",
     "generic-metadata-value": {
       "sources": [
         {
           "endpoints": [
             "origin.example.com"
           ],
           "protocol": "http/1.1",
           "acquisition-auth": {
             "generic-metadata-type": "MI.Auth",
             "generic-metadata-value": {
               "auth-type": "MI.AWSv4Auth",
               "auth-value": {
                 "access-key-id": "MYACCESSKEYID",
                 "secret-access-key": {
                   "secret-store-id": "my-key-vault",
                   "secret-path": "/source/keys/aws/s3-key1"
                 },
                 "aws-region": "us-west-1",
                 "aws-service": "s3"
               }
             }
           }
         }
       ]
     }
   }

                                 Figure 14








Chaudhari, et al.       Expires 5 September 2024               [Page 36]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


5.  Security Considerations

   The FCI and MI objects defined in the present document are
   transferred via the interfaces defined in CDNI [RFC8006] which
   describes how to secure these interfaces protecting integrity and
   confidentiality while ensuring the authenticity of the dCDN and uCDN.

6.  IANA Considerations

6.1.  CDNI Payload Types

   This document requests the registration of the following entries
   under the "CDNI Payload Types" registry hosted by IANA:






































Chaudhari, et al.       Expires 5 September 2024               [Page 37]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


            +---------------------------------+---------------+
            | Payload Type                    | Specification |
            +---------------------------------+---------------+
            | MI.SourceMetadataExtended       | RFCthis       |
            +---------------------------------+---------------+
            | MI.SourceExtended               | RFCthis       |
            +---------------------------------+---------------+
            | MI.SourceConnectionControl      | RFCthis       |
            +---------------------------------+---------------+
            | MI.SourceByteReadTimeoutActions | RFCthis       |
            +---------------------------------+---------------+
            | MI.SourceTimeoutActions         | RFCthis       |
            +---------------------------------+---------------+
            | MI.SourceConnectionRetries      | RFCthis       |
            +---------------------------------+---------------+
            | MI.HTTPCodeFailover             | RFCthis       |
            +---------------------------------+---------------+
            | MI.HTTPCodeFailoverActions      | RFCthis       |
            +---------------------------------+---------------+
            | MI.HTTPCodeReforwards           | RFCthis       |
            +---------------------------------+---------------+
            | MI.EndpointDetention            | RFCthis       |
            +---------------------------------+---------------+
            | MI.HTTPErrorCodeTrigger         | RFCthis       |
            +---------------------------------+---------------+
            | MI.EndpointDetentionTrigger     | RFCthis       |
            +---------------------------------+---------------+
            | MI.EndpointRepeatingFailures    | RFCthis       |
            +---------------------------------+---------------+
            | MI.SourceDetention              | RFCthis       |
            +---------------------------------+---------------+
            | MI.DetentionFullBehavior        | RFCthis       |
            +---------------------------------+---------------+
            | MI.DetentionResetBehavior       | RFCthis       |
            +---------------------------------+---------------+
            | MI.LoadBalanceMetadata          | RFCthis       |
            +---------------------------------+---------------+
            | MI.HeaderAuth                   | RFCthis       |
            +---------------------------------+---------------+
            | MI.AWSv4Auth                    | RFCthis       |
            +---------------------------------+---------------+

                        Table 1: CDNI Payload Types








Chaudhari, et al.       Expires 5 September 2024               [Page 38]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


7.  Acknowledgements

   The authors would like to express their gratitude to the members of
   the Streaming Video Technology Alliance [SVTA] Open Caching Working
   Group for their guidance / contribution / reviews ...)

   Particulary the following people contribute in one or other way to
   the content of this draft:

   *  Guillaume Bichot - Broadpeak

   *  Christoph Neumann - Broadpeak

   *  Chris Lemmons - Comcast

   *  Rajeev RK - picoNETS

   *  Shmuel Asafi - Qwilt

   *  Yoav Gressel - Qwilt

   *  Nir Sopher - Qwilt

   *  Eric Klein - Sirius XM

   *  Andrew Ryan - Sirius XM

   *  Alfonso Siloniz - Telefonica

   *  Ben Rosenblum - Vecima

   *  Sanjay Mishra - Verizon

8.  Normative References

   [RFC1034]  Mockapetris, P., "Domain names - concepts and facilities",
              STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987,
              <https://www.rfc-editor.org/info/rfc1034>.

   [RFC1123]  Braden, R., Ed., "Requirements for Internet Hosts -
              Application and Support", STD 3, RFC 1123,
              DOI 10.17487/RFC1123, October 1989,
              <https://www.rfc-editor.org/info/rfc1123>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.



Chaudhari, et al.       Expires 5 September 2024               [Page 39]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   [RFC8006]  Niven-Jenkins, B., Murray, R., Caulfield, M., and K. Ma,
              "Content Delivery Network Interconnection (CDNI)
              Metadata", RFC 8006, DOI 10.17487/RFC8006, December 2016,
              <https://www.rfc-editor.org/info/rfc8006>.

   [RFC9110]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP Semantics", STD 97, RFC 9110,
              DOI 10.17487/RFC9110, June 2022,
              <https://www.rfc-editor.org/info/rfc9110>.

9.  Informative References

   [AWSv4]    AWS, "Authenticating Requests (AWS Signature Version 4)",
              <https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-
              authenticating-requests.html>.

   [SVTA]     SVTA, "Streaming Video Technology Alliance Home Page",
              <https://www.svta.org>.

   [SVTA2031] SVTA, "Metadata Expression Language (MEL)",
              <https://svta.org/documents/SVTA2031>.

   [SVTA2032] SVTA, "Processing Stages Metadata",
              <https://svta.org/documents/SVTA2032>.

   [SVTA2039] SVTA, "Protected Secrets Metadata",
              <https://svta.org/documents/SVTA2039>.

Authors' Addresses

   Pankaj Chaudhari
   Disney
   United States of America
   Email: pankaj.chaudhari.pub@gmail.com


   Glenn Goldstein
   Lumen Technologies
   United States of America
   Email: glenng1215@gmail.com


   Will Power
   Lumen Technologies
   United States of America
   Email: wrpower@gmail.com





Chaudhari, et al.       Expires 5 September 2024               [Page 40]

Internet-Draft     CDNI Source Access Control Metadata        March 2024


   Arnon Warshavsky
   Qwilt
   Israel
   Email: arnon@qwilt.com















































Chaudhari, et al.       Expires 5 September 2024               [Page 41]