CDNI Source Access Control Metadata

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.¶

                                                 +----------+
                                         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

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¶

• 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¶

• 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.¶

• 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.¶

[
  {
    "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
        },
        "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
                  }
                ]
              },
              "response-status": "404",
              "status-is-expression": false
            }
          }
        }
      ]
    }
  }
]

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

Property: max-reforwards-per-source¶

• 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".¶

{
  "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"
        }
      }
    ]
  }
}

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).¶

{
  "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
          }
        }
      }
    ]
  }
}

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¶

• 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¶

{
  "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",
            "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"
      }
    ]
  }
}

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¶

• 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": {
            "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
        }
      },
      "detention-reset-behavior": {
        "reset-endpoints": [
          "a2.origin-tier2.com"
        ],
        "reset-all-endpoints": true
      }
    }
  }
}