Content Delivery Network Interconnection (CDNI) Control Interface / Triggers 2nd Edition

1.1. Terminology

This document reuses the terminology defined in [RFC6707] and uses "uCDN" and "dCDN" as shorthand for "upstream CDN" and "downstream CDN", respectively.¶

Additionally, the following terms are used throughout this document and are defined as follows:¶

• HLS - HTTP Live Streaming¶

• DASH - Dynamic Adaptive Streaming Over HTTP¶

• MSS - Microsoft Smooth Streaming¶

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

2.1. REST Architecture

The CI/T interface utilizes HTTP/1.1 protocol [RFC9112] and follows the principles of the Representational State Transfer (REST) architectural style. uCDN, in its capacity of a CI/T interface client, makes a request to dCDN to carry out an action ("trigger") related to metadata or content stored by dCDN on behalf of uCDN.¶

dCDN, as a CI/T interface server, governs the triggers as a set of resources, which can be dynamically created and deleted, and whose state can be retrieved and/or modified by uCDN. Each such trigger is identified by a unique Uniform Resource Identifier (URI) is defined in Section 4.2 of [RFC9110].¶

Once a trigger is created, uCDN can retrieve its trigger state from dCDN or request its state to be modified by transferring an updated representation of the trigger state to dCDN. The CI/T interface supports representation of trigger resources using JSON [RFC8259].¶

This RESTful data model built around a common "trigger" resource replaces the command-oriented model of [RFC8007], wherein uCDN passed commands to dCDN using "ci-trigger-command" objects, and dCDN generated "ci-trigger-status" objects in response.¶

2.2. HTTP Methods

Section 9.3 of [RFC9110] defines the set of methods in HTTP. The CI/T interface uses some of these methods for resource creation, retrieval of resource state, modification of resources and deletion of resources. The HTTP methods not listed here are not supported by the CI/T interface.¶

• GET - used to retrieve the current state of a resource. The GET method doesn't cause any state change on the server side.¶

• POST - used to request that the target resource process the representation enclosed in the request. If a resource has been created on the server as a result of successfully processing a POST request, the server sends a 201 (Created) response containing a Location header field that contains an identifier for the newly created resource.¶

• DELETE - used to request the server remove the target resource.¶

• HEAD - used to request metadata associated with the target resource, in the form of HTTP response headers that would have been sent if the GET method was used instead. The HEAD method can be used to verify that the target resource exists at the server.¶

2.3. Trigger

To request that an action be carried by dCDN, uCDN requests to create a trigger resource. If dCDN accepts the request, it creates a new Trigger resource and returns its unique URI to uCDN. uCDN MUST use this URI for all requests associated with the created Trigger resource.¶

uCDN can only access Trigger resources it created.¶

Note that the version of the Trigger resources that uCDN requests to create MUST match the version of CI/T Trigger objects reported as supported by dCDN.¶

The CI/T interface supports the following types of trigger action::¶

• preposition - used to instruct dCDN to fetch metadata from the uCDN or content from any origin including uCDN.¶

• invalidate - used to instruct dCDN to revalidate specific metadata or content before reusing it.¶

• purge - used to instruct dCDN to delete specific metadata or content.¶

Note that additional action types can be defined and registered in the future.¶

The trigger resource has a state attribute. dCDN creates new triggers in "pending" state. Once dCDN starts processing a trigger, the trigger state is set to "active". Once the the trigger processing is complete, the state is set to either "complete" or "failed", depending on the processing outcome.¶

uCDN MAY request dCDN to cancel a trigger. If such request is accepted, the trigger state is changed to "cancelling", and when the cancellation is complete, the trigger state changes to "cancelled".¶

For full description of the Trigger resource, please refer to Section 4.1.¶

2.4. Trigger Collection

Trigger Collection is a resource that represents one or more trigger resources, belonging to particular uCDN. dCDN maintains one Trigger Collection resource for each uCDN. Each uCDN only has access to its own collection resource. dCDN supports retrieval of multiple representations of the trigger collection resource. The supported trigger collection representations are listed in Section 4.2, and include filtering of Trigger resources by Trigger State and Trigger Label attributes. Note that additional trigger collection representations can be defined and registered in the future.¶

2.5. Session Overview

Figure 1 is an example showing the basic message flow in a CI/T interface session used by the uCDN to trigger activity in dCDN and for uCDN to discover the status of that activity. Only successful triggering is shown. Examples of the messages are shown in Section 6.¶

   uCDN                                                   dCDN
    |  (1) POST https://dcdn.example.com/triggers/uCDN      |
   [ ] --------------------------------------------------> [ ]--+
    |                                                      [ ]  | (2)
    |  (3) HTTP 201 Response                               [ ]<-+
   [ ] <-------------------------------------------------- [ ]
    |     Loc: https://dcdn.example.com/triggers/uCDN/123   |
    |                                                       |
    .                           .                           .
    .                           .                           .
    .                           .                           .
    |                                                       |
    | (4) GET https://dcdn.example.com/triggers/uCDN/123    |
   [ ] --------------------------------------------------> [ ]
    |                                                      [ ]
    | (5) HTTP 200 Trigger resource representation         [ ]
   [ ] <-------------------------------------------------- [ ]
    |                                                       |
    |                                                       |
    | (6) DELETE https://dcdn.example.com/triggers/uCDN/123 |
   [ ] --------------------------------------------------> [ ]--+
    |                                                      [ ]  | (7)
    | (8) HTTP 200 OK                                      [ ]<--
   [ ] <-------------------------------------------------- [ ]
    |                                                       |

The steps in Figure 1 are as follows:¶

1. uCDN requests to create a new Trigger resource by POSTing its representation to the trigger collection resource with a well-known URI "https://dcdn.example.com/triggers/uCDN".¶

2. dCDN authenticates the request, validates the Trigger resource in it, and if the request is accepted, creates a new Trigger resource.¶

3. dCDN responds to uCDN with an HTTP 201 response status and the location of the Trigger resource.¶

4. uCDN MAY query, possibly repeatedly, the Trigger resource in dCDN.¶

5. dCDN responds to each query with the current Trigger resource representation, including the trigger state, that reflects the progress of the uCDN request.¶

6. Once the trigger reaches a terminal state ("complete", "failed" or "cancelled"), uCDN MAY request to delete Trigger resource.¶

7. dCDN validates the request and the trigger resource state. If successful, the trigger resource is removed by the server, and subsequent requests for this resource MUST result in 404 (Not Found).¶

8. dCDN responds to the deletion request with 200 (OK) status code.¶

2.6. Trigger Processing

2.7. Trigger Extensibility

The CDNI Control Interface / Triggers 1st edition [RFC8007] defines a set of properties and objects used by the trigger commands. This 2nd edition defines an extension mechanism to the triggers interface that enables applications to add instructions for finer control over the trigger execution, for example indicating a time window in which to execute the trigger. This document specifies a generic trigger extension object wrapper for managing individual CDNI trigger extensions in an opaque manner.¶

All trigger extensions are optional, and it is thus the responsibility of the extension specification to define a consistent default behavior for the case the extension is not present.¶

All trigger extensions MUST be registered in the IANA "CDNI CI/T Trigger Extensions" registry (see Section 7.6).¶

This document also defines an initial set of trigger extension objects and registers them in the IANA "CDNI CI/T Trigger Extensions" registry:¶

Example use cases¶

• Preposition with cache location policy¶

• Purge content with cache location policy¶

• Preposition at a specific time¶

• Purge by content acquisition time (e.g., purge all content acquired in the past X hours)¶

2.8. Multiple Interconnected CDNs

In a network of interconnected CDNs, a single uCDN will originate a given item of metadata and associated content. It MAY distribute that metadata and content to one or more dCDNs, which in turn distributes that metadata and content to additional dCDNs located further downstream.¶

An intermediate CDN is dCDN that passes on CDNI Metadata and content to dCDNs located further downstream.¶

A "diamond" configuration is one where dCDN can acquire metadata and content originated in one uCDN from that uCDN itself and an intermediate CDN, or via more than one intermediate CDN.¶

Triggers originating in the single source uCDN affect metadata and content in all dCDNs; however, in a diamond configuration, it may not be possible for dCDN to determine from which uCDN it acquired content. In this case, dCDN MUST allow each uCDN from which it may have acquired the content to act upon that content using triggers.¶

In all other cases, dCDN MUST reject triggers from uCDN that attempts to act on another uCDN's content by responding, for example, with an HTTP 403 ("Forbidden").¶

Security considerations are discussed further in Section 8.¶

The diamond configuration may lead to inefficient interactions, but the interactions are otherwise harmless. For example:¶

• When uCDN requests to create an "invalidate" trigger, dCDN will receive that request from multiple directly connected uCDNs. The dCDN may schedule multiple such triggers separately, and the last scheduled trigger may affect content already revalidated following execution of the "invalidate" trigger that was scheduled first.¶

• If one of dCDN's directly connected uCDNs loses its rights to distribute content, it may issue a "purge" trigger. That purge may affect content dCDN could retain because it's distributed by another directly connected uCDN. But, that content can be reacquired by dCDN from the remaining uCDN.¶

• When uCDN originating an item of content issues a purge followed by a preposition, two directly connected uCDNs will pass those triggers to a dCDN. That dCDN implementation need not merge those operations or notice the repetition, in which case the purge issued by one uCDN will be completed before the other. The first uCDN to finish its purge may then forward the "preposition" trigger, and content prepositioned as a result might be affected by the still-running purge issued by the other uCDN. However, dCDN will reacquire that content as needed, or when it's asked to preposition the content by the second uCDN. dCDN implementation could avoid this interaction by knowing which uCDN it acquired the content from, or it could minimize the consequences by recording the time at which the "invalidate"/"purge" trigger was received and not applying it to content acquired after that time.¶

If dCDN is also acting as uCDN in a cascade, it MUST forward trigger requests to any dCDNs that may be affected. The trigger state MUST NOT be reported as "complete" by an intermediate CDN until it is "complete" in all of its dCDNs and in the intermediate CDN itself. If a trigger is reported as "processed" in the intermediate CDN or any one of its dCDNs, intermediate CDNs MUST report trigger as "processed" as well. If a trigger is reported as "failed" by the intermediate CDN or any one of its dCDNs, the intermediate CDN must report the trigger as "failed" only after its processing is finished in it and all of its dCDNs. A cancelled trigger MUST be reported as "cancelling" until it has been reported as "cancelled", "complete", or "failed" by all dCDNs in a cascade.¶

3.1. Creating Triggers

To create a new trigger, uCDN makes an HTTP POST request with the trigger representation to the root interface URL. The trigger representation MUST include the mandatory attributes of trigger resource (Section 4.1).¶

uCDN MAY also optionally specify optional trigger v2 specification attributes, namely trigger labels and trigger extensions, as well as the optional "cdn-path" attribute of the trigger resource.¶

dCDN validates the trigger resource representation sent by uCDN. If the representation is malformed or uCDN does not have sufficient access rights, dCDN MUST either respond with an appropriate 4xx HTTP error code and not create a trigger resource or create a trigger resource with "failed" state and an appropriate Error.v2 Description (Section 4.1.5.1).¶

The new trigger resource is created in "pending" state. If successful, The HTTP response to the uCDN trigger creation request MUST have status code 201 (Accepted) and MUST convey the URI of the newly created trigger resources in the Location response header field [RFC9110]. The HTTP response SHOULD include the updated representation of the trigger resource. This is particularly important in cases where dCDN processed the trigger immediately.¶

Once a trigger resource has been created, dCDN MUST NOT reuse its URI, even after the trigger resource has been fully removed. It is therefore recommended that dCDN utilize unique UUID identifiers as specififed in [RFC9562].¶

dCDN SHOULD provide continuous updates of the trigger processing progress, by responding with updated trigger resource representations to subsequent uCDN requests sent to the created trigger URL. If the dCDN is unable to do that, it MUST indicate that it has accepted the request but will not be providing further status updates. To do this, it MUST set the trigger state to "processed" at creation time. In this case, CI/T processing should continue as it were a request in the "complete" state. In this case dCDN SHOULD also provide an estimated completion time for the request by using the trigger "etime" property.¶

Otherwise dCDN MUST set the state of the new trigger to "pending". Once trigger processing has started, the status MUST be changed to "active". Finally, once the the trigger processing is complete, the trigger state MUST be set to "complete" or "failed".¶

Once created, trigger resources can be cancelled, modified or deleted by uCDN, subject to constraints described below.¶

3.2. Modifying Triggers

Modification of existing triggers is useful for uCDN to correct an error in trigger specification or trigger extension(s) that may govern when the trigger is to be processed.¶

uCDN can request modification of an existing trigger resource by sending an updated trigger representation to the trigger URI using HTTP POST command.¶

dCDN MAY accept modifications of the trigger specifications, trigger extensions and trigger labels, when the trigger is in "pending" state, i.e. dCDN didn't start its processing yet.¶

dCDN MAY also accept a request to change the trigger state subject to the following constraints:¶

• the requested state is "cancelled", and the trigger was in either "pending" or "active" state when dCDN receives the request¶

• the requested state is "active", and the trigger was in "pending" state when dCDN received the request¶

The Section 3.3 describes processing of the trigger cancellation requests in detail. uCDN MAY request to set the trigger state to "active" to prompt dCDN to re-examine the trigger resource and start its processing immediately.¶

dCDN MUST respond to the trigger modification request appropriately. Thus, the HTTP status code 200 ("OK") should be returned if the modification has been processed, 202 ("Accepted") if the command has been accepted but the modification is not fully complete yet, 404 ("Not Found") when the trigger resource does not exist, 409 ("Conflict") when the trigger resource is in a state that doesn't allow the requested modification, 501 ("Not Implemented") if the modification is not supported by dCDN or an appropriate 4xx HTTP error code in case of a malformed request.¶

In case of successful 2xx response, dCDN MUST provide the updated trigger resource representation in the response body.¶

3.3. Cancelling Triggers

uCDN MAY request cancellation of a trigger by requesting its state to be set to "cancelled", as described in Section 3.2. dCDN MUST respond to such request, however the actual cancellation of a trigger resource is optional to implement.¶

dCDN MUST respond to the trigger cancellation request appropriately. dCDN MUST respond with the HTTP status code 200 ("OK") if the trigger processing has been cancelled and the trigger state has been set to "cancelled", 202 ("Accepted") if the command has been accepted but the trigger processing has not been cancelled yet, 404 ("Not Found") when the trigger resource does not exist, or 501 ("Not Implemented") if cancellation is not supported by dCDN.¶

If cancellation of a "pending" trigger is accepted by dCDN, dCDN SHOULD NOT start the processing of that activity. Requesting a cancellation of a "pending" trigger does not, however, guarantee that the corresponding activity will not be started, because uCDN cannot control the timing of that activity. Processing could, for example, start after the POST is sent by uCDN but before that request is processed by dCDN.¶

If cancellation of an "active" or "processed" trigger is accepted by dCDN, dCDN SHOULD stop processing the trigger. However, as with the cancellation of a "pending" trigger, dCDN does not guarantee that the trigger processing doesn't run to completion in the meantime.¶

If uCDN cannot stop the trigger processing immediately after receiving the request from uCDN to do so, it MUST set the trigger state to "cancelling" and provide this state in the trigger representation in its response. If the trigger processing is stopped before its normal completion, the trigger state MUST be set to "cancelled".¶

Cancellation of a "complete", "failed" or "cancelled" trigger requires no processing in dCDN. Its state MUST NOT be changed.¶

3.4. Checking Status

uCDN has two ways to check the progress of its triggers' processing, as described in Section 3.4.1 and Section 3.4.2.¶

To allow uCDN to use client-side caching of all triggers and trigger collections, dCDN SHOULD include an ETag response header with every resource representation it sends. dCDN SHOULD also respond with the HTTP code 304 ("Not Modified") without a response body in response to conditional resource requests that use "If-None-Match" and/or "If-Modified-Since" request headers as described in Section 13 of [RFC9110] , in case dCDN doesn't have a more recent resource representation.¶

dCDN SHOULD use the cache control headers for responses to GET requests for its resources to indicate the frequency at which it recommends that uCDN and/or intermediate proxies should poll for change. If provided, uCDN should match the frequency of polling to the cache control information provided by dCDN.¶

3.5. Deleting Triggers

uCDN MAY request delete trigger resources at any time using the HTTP DELETE method. As defined in the CDNI Control Interface / Triggers 1st edition [RFC8007],¶

Once deleted, the deleted trigger MUST be removed from all representations of the trigger collection. Subsequent requests to the trigger resource URI MUST be rejected by dCDN with HTTP error 404 ("Not Found").¶

the effect of deletion is similar to cancellation, except that the trigger resource becomes unavailable after the deletion is complete. For this reason, uCDN SHOULD cancel triggers rather than delete them when it is important for uCDN to access the trigger status after the trigger processing is stopped.¶

If a "pending" trigger is deleted, dCDN SHOULD NOT start the processing of that activity. Deleting a "pending" trigger does not, however, guarantee that its processing has not started, because uCDN cannot control the timing of that activity. Processing may, for example, start after the DELETE is sent by uCDN but before that request is processed by dCDN.¶

When an "active" or "processed" trigger is deleted, the dCDN SHOULD stop processing it. However, as with deletion of a "pending" trigger, dCDN does not guarantee this.¶

Deletion of a "complete", "cancelled" or "failed" trigger no processing in dCDN.¶

dCDN MUST respond to the trigger deletion request appropriately. dCDN MUST respond with the HTTP status code 200 ("OK") without a response body if the trigger has been deleted immediately. 202 ("Accepted") if the command has been accepted but the trigger has not been deleted yet. 404 ("Not Found") when the trigger resource does not exist, or 501 ("Not Implemented") if deletion is not supported by dCDN.¶

The trigger state MUST be set to "cancelling" while dCDN is processing a deletion request asynchronously.¶

3.6. Expiry of Triggers

dCDN MAY automatically delete trigger resources sometime after they reach a terminate state (one of "complete", "processed", "failed", or "cancelled"). In this case, after dCDN removed such trigger, it MUST respond to subsequent requests for it with the HTTP error 404 ("Not Found") and remove it from the trigger collection resource.¶

If dCDN does remove triggers in a terminal state automatically, it MUST report the expiry timeout period, using an attribute of the trigger collection resource.¶

It is RECOMMENDED that dCDN sets its expiry timeout to at least 24 hours. It is further RECOMMENDED that uCDN sets its trigger polling period to less than the expiry period, so it doesn't miss trigger status updates before the "complete" or "failed" triggers are expired by dCDN.¶

3.7. Loop Detection and Prevention

Given three CDNs, A, B, and C, if CDNs B and C delegate delivery of CDN A's content to each other, CDN A's trigger creation requests could be passed between CDNs B and C in a loop. More complex networks of CDNs could contain similar loops involving more hops.¶

To prevent and detect such CI/T loops, each CDN uses a CDN Provider ID (PID) (Section 4.3.3). to uniquely identify itself. In every trigger resource it creates or cascades, each CDN MUST append an array element containing its CDN PID to a JSON array under an entry named "cdn-path". When receiving a trigger creation request, dCDN MUST check the cdn-path and reject any trigger that already contains its own CDN PID in the cdn-path. Transit CDNs MUST check the "cdn-path" and not cascade the trigger creation request to dCDNs that are already listed in the cdn-path.¶

3.8. Error Handling

dCDN MAY reject CI/T interface requests, by responding to those requests with 4xx or 5xx HTTP status codes. For example, uCDN MAY respond with 400 ("Bad Request") if the request is malformed, or 403 ("Forbidden") or 404 ("Not Found") if the request could not be properly authenticated or if uCDN is trying to act on another CDN's resources.¶

If any part of the trigger processing fails, the trigger SHOULD be reported as "failed" once its activity is complete or if no further errors will be reported. The "errors" property in the trigger will be used to enumerate which actions failed and the reasons for failure, and can be present while the trigger is still "pending" or "active" if the trigger processing is still running for some URLs or patterns in the trigger specs.¶

Once a request has been accepted, processing errors are reported in the trigger using a list of Error.v2 Descriptions. Each Error.v2 Description is used to report errors against one or more of the URLs or patterns in the Trigger Specification.¶

If a Surrogate affected by a trigger is offline in the dCDN or dCDN is unable to pass a trigger on to any of its cascaded dCDNs:¶

• If the trigger is abandoned by dCDN, dCDN SHOULD report an error.¶

• A CI/T "invalidate" command may be reported as "complete" when Surrogates that may have the data are offline. In this case, Surrogates MUST NOT use the affected data without first revalidating it when they are back online.¶

• CI/T "preposition" and "purge" commands can be reported as "processed" if affected caches are offline and the activity will complete when they return to service.¶

• Otherwise, dCDN SHOULD keep the trigger "pending" or "active" state until either the trigger is acted upon or uCDN chooses to cancel it.¶

uCDN-A                         dCDN-B                         dCDN-C
 |                              |                              |
 | (1) POST                     |                              |
 | https://dcdn-b.example.com   |                              |
 | /triggers/uCDN-A             |                              |
[ ]--------------------------->[ ]--+                          |
 |                             [ ]  | (2)                      |
 |                             [ ]<-+                          |
 | (3) HTTP 201 Response.      [ ]                             |
 |<----------------------------[ ]                             |
 | Loc:                        [ ]                             |
 | https://dcdn-b.example.com  [ ] (4) POST                    |
 | /triggers/uCDN-A/123        [ ] https://dcdn-c.example.com  |
 |                             [ ] /triggers/dCDN-B            | (5)
 |                             [ ]--------------------------->[ ]--+
 |                              |                             [ ]  |
 |                              |                             [ ]<-+
 |                              | (6) HTTP 201 Response.      [ ]
 |                             [ ]<---------------------------[ ]
 |                              |  Loc:                        |
 |                              |  https://dcdn-c.example.com  |
 |                              |  /triggers/dCDN-B/456        |
 |                              |                              |
 |                             [ ]--+                          |
 |                             [ ]  | (7.1)                    |
 |                             [ ]<-+                         [ ]--+
 |                              |                       (7.2) [ ]  |
 |                              |                             [ ]<-+
 |                              |                              |
 .                              .                              .
 .                              .                              .
 .                              .                              .
 |                              | (8) GET                      |
 |                              | https://dcdn-c.example.com   |
 |                              | /triggers/dCDN-B/456         |
 |                             [ ]--------------------------->[ ]
 |                              |                             [ ]
 |                              | (9) HTTP 200                [ ]
 |                              | Trigger resource            [ ]
 |                             [ ]<---------------------------[ ]
 |                              |                              |
 .                              .                              .
 .                              .                              .
 .                              .                              .
 | (10) GET                     |                              |
 | https://dcdn-b.example.com   |                              |
 | /triggers/uCDN-A/123         |                              |
[ ]--------------------------->[ ]                             |
 |                             [ ]                             |
 | (11) HTTP 200               [ ]                             |
 | Trigger resource            [ ]                             |
[ ]<---------------------------[ ]                             |

4.1. Trigger Resource

Trigger resource is encoded as a JSON object and MUST use a MIME media type of "application/cdni; ptype=ci-trigger.v2". The rigger resource contains the following name/value pairs:¶

• Name: action

  Description: Defines the type of the CI/T Trigger Action.¶

  Value: Trigger Action Type, as defined in Section 4.1.1.¶

  Mandatory: Yes.¶

  Name: specs

  Description: Array of trigger specs representing the trigger's targets, as described in Section 4.1.2.¶

  Value: Array of GenericTriggerSpec objects (see Section 4.1.2.1).¶

  Mandatory: Yes. Furthermore, the list MUST NOT be empty.¶

  Name: extensions

  Description: Array of trigger extensions, as described in Section 4.1.3.¶

  Value: Array of GenericTriggerExtension objects (see Section 4.1.3.2).¶

  Mandatory: No. The default is no extensions.¶

  Name: labels

  Description: Array of trigger labels.¶

  Value: Array of Trigger labels, Each label is encoded as a JSON string and SHOULD be unique per trigger.¶

  Mandatory: No. The default is no labels.¶

  Name: cdn-path

  Description: The chain of CDN PIDs of CDNs that have already created this trigger resource.¶

  Value: Non-empty array of JSON strings, where each string is a CDN PID as defined in Section 4.3.3.¶

  Mandatory: No. The default is no CDN path.¶

  Name: ctime

  Description: The time at which the trigger resource was received by the dCDN. The time is determined by dCDN; there is no requirement to synchronize clocks between interconnected CDNs.¶

  Value: A JSON number, seconds since the UNIX epoch (00:00:00 UTC on 1 January 1970).¶

  Mandatory: Yes.¶

  Name: mtime

  Description: The time at which the trigger resource was last modified. The time is determined by dCDN; there is no requirement to synchronize clocks between interconnected CDNs.¶

  Value: A JSON number, seconds since the UNIX epoch (00:00:00 UTC on 1 January 1970).¶

  Mandatory: Yes.¶

  Name: etime

  Description: The estimate of the time at which dCDN expects to complete the trigger processing. Time is determined by dCDN; there is no requirement to synchronize clocks between interconnected CDNs.¶

  Value: A JSON number, seconds since the UNIX epoch (00:00:00 UTC on 1 January 1970).¶

  Mandatory: No.¶

  Name: state

  Description: The current trigger state.¶

  Value: Trigger state, as defined in Section 4.1.4.¶

  Mandatory: No.¶

  Name: state-reason

  Description: A human-readable explanation for the object state.¶

  Value: A JSON string, the human-readable reason.¶

  Mandatory: No.¶

  Name: errors

  Description: Descriptions of errors that have occurred while processing the trigger.¶

  Value: An array of Error.v2 Descriptions, as defined in Section 4.1.5.1. An empty array is allowed and is equivalent to omitting "errors" from the object.¶

  Mandatory: No.¶

  Name: objects

  Description: List of objects derived by dCDN when processing the trigger.¶

  Value: An array of ObjectList (Section 4.3.2) objects. dCDN SHOULD provide the list of objects it used as input for processing the trigger with Section 4.1.2.7, provided that dCDN advertised support for extended status (Section 5.5). An empty array is allowed and is equivalent to omitting "objects" from the trigger representation. This field is intended to provide the list of all objects used in processing. The objects that failed to process SHOULD be specified using the Error.v2 Description resource.¶

  Mandatory: No.¶

{
  "generic-trigger-spec-type":
     <Type of this trigger spec>,
  "generic-trigger-spec-value":
      {
        <properties of this trigger spec object>
      },
   "generic-trigger-spec-subject":
     <Category of this trigger spec subject>

}

{
  "trigger-subject": "metadata",
  "generic-trigger-spec-type": "urls",
  "generic-trigger-spec-value": {
    "urls": [ "https://metadata.example.com/a/b/c" ],
    "url-type": "published"
  }
}

{
  "pattern": "https://www.example.com/trailers/*",
  "case-sensitive": true
}

"^(https:\/\/video\.example\.com)\/([a-z])\/
 movie1\/([1-7])\/*(index.m3u8|\d{3}.ts)$"

{
  "regex": "^(https:\\/\\/video\\.example\\.com)\\/([a-z])\\/
           movie1\\/([1-7])\\/*(index.m3u8|\\d{3}.ts)$",
  "case-sensitive": true,
  "match-query-string": false
}

 https://video.example.com/d/movie1/5/index.m3u8

 https://video.example.com/k/movie1/4/013.ts

{
  "generic-trigger-extension-type":
     <Type of this trigger extension object>,
  "generic-trigger-extension-value":
      {
        <properties of this trigger extension object>
      },
  "mandatory-to-enforce": <bool>,
  "safe-to-redistribute": <bool>,
  "incomprehensible": <bool>
}

{
  "generic-trigger-extension-type": "location-policy",
  "generic-trigger-extension-value": {
    "locations": [
      {
        "action": "allow",
        "footprints": [{
          "footprint-type": "countrycode",
          "footprint-value": [ "us" ]
        }]
      },
      {
        "action": "deny",
        "footprints": [{
          "footprint-type": "countrycode",
          "footprint-value": [ "ca" ]
        }]
      }
    ]
  },
  "mandatory-to-enforce": true,
  "safe-to-redistribute": true,
  "incomprehensible": false
}

{
   "generic-trigger-extension-type": "time-policy",
   "generic-trigger-extension-value":
    {
      "unix-time-window": {
         "start": 946717200,
         "end": 946746000
      }
    },
   "mandatory-to-enforce": true,
   "safe-to-redistribute": true,
   "incomprehensible": false
}

{
  "start": "2000-01-01T02:30:00.00Z",
  "end": "2000-01-01T04:30:00.00Z"
}

{
  "start": "2000-01-01T02:30:00.00-05:00",
  "end": "2000-01-01T04:30:00.00-05:00"
}

{
  "generic-trigger-extension-type": "execution-policy",
  "generic-trigger-extension-value":
  {
    "priority": 100,
    "depends":  [
      "https://dcdn.example.com/triggers/100",
      "https://dcdn.example.com/triggers/101"
    ],
    "urgent": true
  }
}

{
  "error": "econtent",
  "description": "Failed to parse HLS object list",
  "specs": [{
    "trigger-subject": "content",
    "generic-trigger-spec-type": "content-objectlist",
    "generic-trigger-spec-value": {
      "objects": [{
        "href": "https://www.example.com/hls/title/index.m3u8",
        "type": "hls"
      }]
   }}
  ],
  "objects": [{
    "href": "https://www.example.com/hls/title/index.m3u8",
    "type": "hls"
  }],
  "cdn": "AS64500:0"
}

{
  "errors": [{
    "error": "eextension",
    "description": "unrecognized extension <type>",
    "specs": [{
      "trigger-subject": "content",
      "generic-trigger-spec-type": "urls",
      "generic-trigger-spec-value": {
        "urls": [
          "https://www.example.com/a/b/c/1",
          "https://www.example.com/a/b/c/2"
        ]
      }
    }],
    "extensions": [{
      "generic-trigger-extension-type": "location-policy",
      "generic-trigger-extension-value": {
        "locations": [{
          "action": "deny",
          "footprints": [{
              "footprint-type": "countrycode",
              "footprint-value": [ "ca" ]
            }]
          }]
        }
    }],
    "cdn": "AS64500:0"
  }]
}

4.2. Trigger Collection Resource

As described in Section 2, trigger resources exist in dCDN to represent a specific activity that uCDN requests dCDN to carry out.¶

A collection of trigger resources is a resource that represents all triggers in it. By default trigger resources in a collection are represented using their unique URIs. Note that the collection may refer to CI/T Resources from several versions of CI/T objects, i.e., a subsequent call for the retrieval of the relevant trigger status may provide objects of various MIME media types: ci-trigger-status as defined in [RFC8007], ci-trigger.v2 defined in this document, or objects of future CI/T objects versions, based on the version of the JSON object used to create the trigger.¶

dCDN MUST make a collection of uCDN's trigger resources available to that uCDN. This collection includes all triggers that have been created by uCDN and have not yet been deleted by uCDN (see Section 3.5) or expired and removed by dCDN (see Section 3.6). Trigger resources belonging to uCDN MUST NOT be visible to any other CDN. dCDN could, for example, achieve this by offering different collection URLs to each uCDN and by filtering the response based on uCDN with which the HTTP client is associated.¶

To trigger an activity in dCDN or to cancel a triggered activity, the uCDN POSTs a trigger representation to dCDN's collection of uCDN's triggers.¶

To allow uCDN to check the status of multiple triggers in a single request, dCDN MAY maintain optional representations of the trigger collection, that contain a subset of all triggers, filtered based on a parameter These filtered collection representations are "optional-to-implement", but if they are implemented, dCDN MUST include links to them in the trigger collection.¶

dCDN MAY provide filtered collections per trigger state (Section 4.1.4). If implemented, dCDN SHOULD provide a separate filtered collection for every trigger state, and advertise these collections in the trigger collection.¶

dCDN MAY provide filtered collections per trigger label, as specified by uCDN when creating a trigger resource (Section 4.1). If implemented, dCDN SHOULD provide a separate filtered collection for every unique trigger label, and advertise these collections in the collection of all Trigger resources.¶

Trigger Collections MUST use a MIME media type of "application/cdni; ptype=ci-trigger-collection".¶

A Trigger Collection is encoded as a JSON object containing the following name/value pairs:¶

• Name: triggers

  Description: Links to triggers in the collection.¶

  Value: A JSON array of zero or more URLs, represented as JSON strings.¶

  Mandatory: Yes.¶

  Name: staleresourcetime

  Description: The length of time for which dCDN guarantees to keep a completed trigger resource. After this time, dCDN SHOULD delete the trigger resource and all references to it from the collection.¶

  Value: A JSON number, which must be a positive integer, representing time in seconds.¶

  Mandatory: Yes, in the collection of all triggers if dCDN deletes stale entries. If the property is present in the filtered collection representation, it MUST have the same value as in the collection of all triggers.¶

  Name: coll-state

  Description: Array of all Section 4.2.2 objects.¶

  Value: An array of JSON-encoded FilteredCollectionStatusLink objects.¶

  Mandatory: Mandatory in the collection of all triggers, if dCDN implements the filtered collections. Otherwise, optional.¶

  Name: coll-label

  Description: Array of all Section 4.2.1 objects.¶

  Value: An array of JSON-encoded FilteredCollectionLabelLink objects.¶

  Mandatory: Mandatory in the collection of all triggers, if dCDN implements the filtered collections. Otherwise, optional.¶

  Name: all-triggers

  Description: Array of all triggers in the collection. Should be returned only when an extended trigger collection view is requested as described in Section 3.4.1.1.¶

  Value: An array of JSON-encoded triggers.¶

  Mandatory: No. The "all-triggers" SHOULD only be used by dCDN that supports and advertises the appropriate extended status for trigger collections (see Section 5.5 for details).¶

  Name: cdn-id

  Description: The CDN PID of dCDN.¶

  Value: A JSON string, dCDN's CDN PID, as defined in Section 3.7.¶

  Mandatory: Only in the collection of all triggers, if dCDN implements the filtered collections. Optional in the filtered collections (uCDN can always find dCDN's cdn-id in the collection of all triggers, but dCDN can choose to repeat that information in its implementation of filtered collections).¶

4.3. Other CI/T Objects

This section describes common CI/T objects and their encodings.¶

[
  {
    "href": "https://example.com/hls/a36f764e/index.m3u8",
    "type": "hls"
  }
]

[
  {
    "href": "https://example.com/hls/35cdc008/assets",
    "type": "text"
  }
]

[
  {
    "href": "https://example.com/hls/35cdc008/index.m3u8",
    "type": "hls"
  },
  {
    "href": "https://example.com/dash/35cdc008/main.mpd",
    "type": "dash"
  },
  {
    "href": "https://example.com/dash/35cdc008/files.json",
    "type": "json"
  }
]

[
  {
    "data": [
      {
        "href": "https://example.com/hls/35cdc008/index.m3u8",
        "type": "hls"
      },
      {
        "href": "https://example.com/dash/35cdc008/main.mpd",
        "type": "dash"
      },
      {
        "href": "https://example.com/img/35cdc008/thumb-l.jpg",
        "size": 10260
      },
      {
        "href": "https://example.com/img/35cdc008/thumb-s.jpg",
        "size": 1453
      }
    ],
    "type": "json"
  }
]

[
  {
  "data": "#EXTM3U\n
  #EXT-X-STREAM-INF:BANDWIDTH=150000,RESOLUTION=416x234,
            CODECS=\"avc1.42e00a,mp4a.40.2\"\n
  http://example.com/low/index.m3u8\n
  #EXT-X-STREAM-INF:BANDWIDTH=240000,RESOLUTION=416x234,
            CODECS=\"avc1.42e00a,mp4a.40.2\"\n
  http://example.com/lo_mid/index.m3u8\n
  #EXT-X-STREAM-INF:BANDWIDTH=440000,RESOLUTION=416x234,
            CODECS=\"avc1.42e00a,mp4a.40.2\"\n
  http://example.com/hi_mid/index.m3u8\n
  #EXT-X-STREAM-INF:BANDWIDTH=640000,RESOLUTION=640x360,
            CODECS=\"avc1.42e00a,mp4a.40.2\"\n
  http://example.com/high/index.m3u8\n
  #EXT-X-STREAM-INF:BANDWIDTH=64000,
            CODECS=\"mp4a.40.5\"\n
  http://example.com/high/index.m3u8\n",
  "type": "hls"
  }
]

[
  {
    "href": "https://example.com/hls/35cdc008/index.m3u8",
    "type": "hls"
  },
  {
    "href": "https://example.com/dash/35cdc008/main.mpd",
    "type": "dash"
  },
  {
    "href": "https://example.com/img/35cdc008/thumb-l.jpg",
    "size": 102600
  },
  {
    "href": "https://example.com/img/35cdc008/thumb-s.jpg",
    "size": 14535
  }
]

5.1. CI/T Endpoint Capability Object

The CI/T trigger endpoint capability object is used to advertise one or more CI/T interface endpoints along with CI/T interface versions supported by these endpoints. The capability type is "FCI.CITEndpoints". Version 1, as originally defined in [RFC8007], is the default if this capability is not explicitly declared.¶

A CI/T Endpoints capability object is encoded as an array of JSON objects containing the following name/value pairs:¶

• Name: trigger-endpoint-uri

  Description: CI/T endpoint URI¶

  Value: A URL represented as a JSON string.¶

  Mandatory: Yes.¶

  Name: trigger-versions

  Description: A list of CI/T versions supported by the trigger endpoint.¶

  Value: An array of JSON strings.¶

  Mandatory: Yes.¶

  Name: trigger-subject

  Description: Array of trigger subjects supported by the trigger endpoint.¶

  Value: An array of Strings containing the type of the subject matching the generic-trigger-spec-value property, such as "content" or "metadata" as defined in Section 4.1.2.2.¶

  Mandatory: No. A missing or empty "trigger-subject" list means that all trigger subjects are supported by the endpoint. dCDN SHOULD advertise only one endpoint for every trigger subject and CI/T interface version pair. If more than one interface endpoint supports the same trigger subject and CI/T interface version (e.g. CI/T version 2 interface for content objects), uCDN SHOULD be able to use any of the advertised CI/T interface endpoints interchangeably.¶

{
  "capabilities": [
    {
      "capability-type": "FCI.CITEndpoints",
      "capability-value": {
        "trigger-endpoint-uri":
          "https://dcdn.example.com/configuration/",
        "trigger-versions": [ "1" ],
        "trigger-subjects": "metadata"
      },
      "footprints": {
        "footprint-type": "countrycode",
        "footprint-value": [ "us" ]
      }
    },
    {
      "capability-type": "FCI.CITEndpoints",
      "capability-value": {
        "trigger-endpoint-uri":
          "https://dcdn.example.com/cache-management/",
        "trigger-versions": [ "2", "2.1" ],
        "trigger-subjects": "content"
      },
      "footprints": {
        "footprint-type": "countrycode",
        "footprint-value": [ "us" ]
      }
    }
  ]
}

5.3. CI/T Object List Type Capability Object

Given an object list being supported by dCDN, the CI/T Object List Type capability object is used to indicate support for one or more Object List types listed in Section 7.5 by the type property of the "ObjectList" object. The capability type is "FCI.CITObjectListType".¶

• Name: object-list-types

  Description: A list of supported ObjectList types.¶

  Value: An array of Section 4.3.2.1.¶

  Mandatory: No. In case of a missing or an empty list, MUST be interpreted as no ObjectList types are supported.¶

{
  "capabilities": [{
    "capability-type": "FCI.CITObjectListType",
    "capability-value": {
      "object-list-types": [ "hls", "dash", "json" ]
    },
    "footprints": {
      "footprint-type": "countrycode",
      "footprint-value": [ "us" ]
    }
  }]
}

5.4. CI/T Private URL Capability Object

The CI/T Private URL capability object is used to indicate support for operations on private URLs (see Section 4.3.1 for details). The capability type is "FCI.CITPrivateUrlType".¶

• Name: private-url-type-support

  Description: Indicate whether private URL type is supported by dCDN.¶

  Value: Boolean.¶

  Mandatory: No. In case of missing or an empty attribute, MUST be interpreted as no support for private URLs.¶

{
  "capabilities": [{
    "capability-type": "FCI.CITPrivateUrlType",
    "capability-value": { "private-url-type-support": true },
    "footprints": {
      "footprint-type": "countrycode",
      "footprint-value": [ "us" ]
    }
  }]
}

5.5. CI/T Extended Status Capability Object

CI/T Extended Trigger Status Capability object is used to indicate support for extended trigger status. The extended trigger status is returned upon uCDN request and includes:¶

• "objects" attribute in top-level Trigger object¶

• "objects" attribute in Error.v2 Description object¶

• "all-triggers" attribute in top-level Trigger Collections object¶

The capability type is "FCI.CITExtendedStatus".¶

• Name: extended-status-objects

  Description: List of CI/T objects that support extended attributes.¶

  Value: An array of JSON strings listing CI/T objects.¶

  Mandatory: No. By default, in case of a missing or an empty list, no extended attribute objects are supported.¶

{
  "capabilities": [{
    "capability-type": "FCI.CITExtendedStatus",
    "capability-value": {
      "extended-status-objects": [
        "trigger-state"      ,
        "error-v2-description",
        "trigger-collection"
      ]
    },
    "footprints": {
      "footprint-type": "countrycode",
      "footprint-value": [ "us" ]
    }
  }]
}

6.1. Creating Triggers

Examples of uCDN triggering activity in dCDN:¶

REQUEST:

  POST /triggers HTTP/1.1
  User-Agent: example-user-agent/0.1
  Host: dcdn.example.com
  Accept: */*
  Content-Type: application/cdni; ptype=ci-trigger.v2
  Content-Length: 352

  {
    "action": "preposition",
    "specs": [
      {
        "trigger-subject": "metadata",
        "generic-trigger-spec-type": "urls",
        "generic-trigger-spec-value": {
        "urls": [ "https://metadata.example.com/a/b/c" ]
           }
      },
      {
        "trigger-subject": "content",
        "generic-trigger-spec-type": "urls",
        "generic-trigger-spec-value": {
          "urls": [
            "https://www.example.com/a/b/c/1",
            "https://www.example.com/a/b/c/2",
            "https://www.example.com/a/b/c/3",
            "https://www.example.com/a/b/c/4"
          ]
        }
      }
    ],
    "cdn-path": [ "AS64496:1" ]
  }


RESPONSE:

  HTTP/1.1 201 Created
  Date: Wed, 04 May 2016 08:48:10 GMT
  Content-Length: 467
  Content-Type: application/cdni; ptype=ci-trigger.v2
  Location: https://dcdn.example.com/triggers/0
  Server: example-server/0.1

  {
    "ctime": 1462351690,
    "etime": 1462351698,
    "mtime": 1462351690,
    "state": "pending",
    "action": "preposition",
    "specs": [
      {
        "trigger-subject": "metadata",
        "generic-trigger-spec-type": "urls",
        "generic-trigger-spec-value": {
          "urls": [ "https://metadata.example.com/a/b/c" ]
        }
      },
      {
        "trigger-subject": "content",
        "generic-trigger-spec-type": "urls",
        "generic-trigger-spec-value": {
          "urls": [
            "https://www.example.com/a/b/c/1",
            "https://www.example.com/a/b/c/2",
            "https://www.example.com/a/b/c/3",
            "https://www.example.com/a/b/c/4"
          ]
        }
      }
    ],
    "cdn-path": [ "AS64496:1" ]
  }

REQUEST:

  POST /triggers HTTP/1.1
  User-Agent: example-user-agent/0.1
  Host: dcdn.example.com
  Accept: */*
  Content-Type: application/cdni; ptype=ci-trigger.v2
  Content-Length: 387

  {
    "action": "invalidate",
    "specs": [
       {
          "trigger-subject": "metadata",
          "generic-trigger-spec-type": "uri-pattern-match",
          "generic-trigger-spec-value": {
             "pattern": "https://metadata.example.com/a/b/*"
          }
       },
       {
          "trigger-subject": "content",
          "generic-trigger-spec-type": "urls",
          "generic-trigger-spec-value": {
             "urls": [
                "https://www.example.com/a/index.html"
             ]
          }
       },
       {
          "trigger-subject": "content",
          "generic-trigger-spec-type": "uri-pattern-match",
          "generic-trigger-spec-value": {
             "pattern": "https://www.example.com/a/b/*",
             "case-sensitive": true
          }
       }
    ],
    "cdn-path": [ "AS64496:1" ]
  }

RESPONSE:

  HTTP/1.1 201 Created
  Date: Wed, 04 May 2016 08:48:11 GMT
  Content-Length: 545
  Content-Type: application/cdni; ptype=ci-trigger.v2
  Location: https://dcdn.example.com/triggers/1
  Server: example-server/0.1

  {
    "ctime": 1462351691,
    "etime": 1462351699,
    "mtime": 1462351691,
    "state": "pending",
    "action": "invalidate",
    "specs": [
      {
        "trigger-subject": "metadata",
        "generic-trigger-spec-type": "uri-pattern-match",
        "generic-trigger-spec-value": {
          "pattern": "https://metadata.example.com/a/b/*"
        }
      },
      {
        "trigger-subject": "content",
        "generic-trigger-spec-type": "urls",
        "generic-trigger-spec-value": {
          "urls": [ "https://www.example.com/a/index.html" ]
        }
      },
      {
        "trigger-subject": "content",
        "generic-trigger-spec-type": "uri-pattern-match",
        "generic-trigger-spec-value": {
          "pattern": "https://www.example.com/a/b/*",
          "case-sensitive": true
        }
      }
    ],
    "cdn-path": [ "AS64496:1" ]
  }

REQUEST:

  POST /triggers HTTP/1.1
  User-Agent: example-user-agent/0.1
  Host: triggers.dcdn.example.com
  Accept: */*
  Content-Type: application/cdni; ptype=ci-trigger.v2

  {
    "action": "invalidate",
    "specs": [{
      "trigger-subject": "content",
      "generic-trigger-spec-type": "uri-regex-match",
      "generic-trigger-spec-value": {
        "regex": "^(https:\\/\\/video\\.example\\.com)\\/
          ([a-z])\\/movie1\\/([1-7])\\/*(index.m3u8|\\d{3}.ts)$",
        "case-sensitive": true,
        "match-query-string": false
      }
    }],
    "cdn-path": [ "AS64496:0" ]
  }

RESPONSE:

  HTTP/1.1 201 Created
  Date: Wed, 04 May 2016 08:48:10 GMT
  Content-Length: 467
  Content-Type: application/cdni; ptype=ci-trigger.v2
  Location: https://triggers.dcdn.example.com/triggers/2
  Server: example-server/0.1

  {
    "errors": [{
      "specs": [{
        "trigger-subject": "content",
        "generic-trigger-spec-type": "uri-regex-match",
        "generic-trigger-spec-value": {
        "regex": "^(https:\\/\\/video\\.example\\.com)\\/([a-z])\
          \/movie1\\/([1-7])\\/*(index.m3u8|\\d{3}.ts)$",
          "case-sensitive": true,
          "match-query-string": false
        }
      }],
      "description": "dCDN rejected a regex due to complexity",
      "error": "ereject",
      "cdn": "AS64500:0"
    }],
    "ctime": 1462351690,
    "etime": 1462351698,
    "mtime": 1462351690,
    "state": "failed",
    "action": "invalidate",
    "specs": [{
      "trigger-subject": "content",
      "generic-trigger-spec-type": "uri-regex-match",
      "generic-trigger-spec-value": {
        "regex": "^(https:\\/\\/video\\.example\\.com)\\/([a-z])\
          \/movie1\\/([1-7])\\/*(index.m3u8|\\d{3}.ts)$",
        "case-sensitive": true,
        "match-query-string": false
      }
    }],
    "cdn-path": [ "AS64496:0" ]
  }

REQUEST:

  POST /triggers HTTP/1.1
  User-Agent: example-user-agent/0.1
  Host: triggers.dcdn.example.com
  Accept: */*
  Content-Type: application/cdni; ptype=ci-trigger.v2

  {
    "action": "preposition",
    "specs": [{
      "trigger-subject": "content",
      "generic-trigger-spec-type": "content-objectlist",
      "generic-trigger-spec-value": {
        "objects": [{
          "href": "https://www.example.com/hls/title/index.m3u8",
          "type": "hls"
        }]
       }
    }],
    "cdn-path": [ "AS64496:0" ]
  }

RESPONSE:

  HTTP/1.1 201 Created
  Date: Wed, 04 May 2016 08:48:10 GMT
  Content-Length: 467
  Content-Type: application/cdni; ptype=ci-trigger.v2
  Location: https://triggers.dcdn.example.com/triggers/3
  Server: example-server/0.1

  {
    "errors": [{
      "specs": [{
        "trigger-subject": "content",
        "generic-trigger-spec-type": "content-objectlist",
        "generic-trigger-spec-value": {
          "objects": [{
            "href": "https://www.example.com/hls/title/index.m3u8",
            "type": "hls"
          }}
      }],
      "description": "dCDN was not able to parse the object list",
      "error": "econtent",
      "cdn": "AS64500:0"
    }],
    "ctime": 1462351690,
    "etime": 1462351698,
    "mtime": 1462351690,
    "state": "failed",
    "action": "preposition",
    "specs": [{
      "trigger-subject": "content",
      "generic-trigger-spec-type": "content-objectlist",
      "generic-trigger-spec-value": {
        "objects": [{
          "href": "https://www.example.com/hls/title/index.m3u8",
          "type": "hls"
        }]
      }
    }],
    "cdn-path": [ "AS64496:0" ]
  }

6.2. Examining Trigger Status

Once triggers have been created, uCDN can check their status as shown in the following examples.¶

REQUEST:

  GET /triggers HTTP/1.1
  User-Agent: example-user-agent/0.1
  Host: dcdn.example.com
  Accept: */*

RESPONSE:

  HTTP/1.1 200 OK
  Content-Length: 341
  Expires: Wed, 04 May 2016 08:49:11 GMT
  Server: example-server/0.1
  ETag: "-936094426920308378"
  Cache-Control: max-age=60
  Date: Wed, 04 May 2016 08:48:11 GMT
  Content-Type: application/cdni; ptype=ci-trigger-collection

{
  "cdn-id": "AS64496:0",
  "coll-status": [
    {
      "status"    : "pending",
      "collection": "/triggers/pending"
    },
    {
      "status"    : "active",
      "collection": "/triggers/active"
    },
    {
      "status"    : "complete",
      "collection": "/triggers/complete"
    },
    {
      "status"    : "processed",
      "collection": "/triggers/processed"
    },
    {
      "status"    : "failed",
      "collection": "/triggers/failed"
    },
    {
      "status"    : "cancelling",
      "collection": "/triggers/cancelling"
    },
    {
      "status"    : "cancelled",
      "collection": "/triggers/cancelled"
    }
  ],
  "coll-label": [
    {
      "label"     : "1b1bad0c",
      "collection": "/triggers/1b1bad0c"
    },
    {
      "label"     : "fafa9a97",
      "collection": "/triggers/fafa9a97"
    }
  ],
  "staleresourcetime": 86400,
  "triggers": [
    "https://dcdn.example.com/triggers/0",
    "https://dcdn.example.com/triggers/1"
  ]
}

REQUEST:

  GET /triggers/pending HTTP/1.1
  User-Agent: example-user-agent/0.1
  Host: dcdn.example.com
  Accept: */*

RESPONSE:

  HTTP/1.1 200 OK
  Content-Length: 152
  Expires: Wed, 04 May 2016 08:49:11 GMT
  Server: example-server/0.1
  ETag: "4331492443626270781"
  Cache-Control: max-age=60
  Date: Wed, 04 May 2016 08:48:11 GMT
  Content-Type: application/cdni; ptype=ci-trigger-collection

  {
    "staleresourcetime": 86400,
    "triggers": [
      "https://dcdn.example.com/triggers/0",
      "https://dcdn.example.com/triggers/1"
    ]
  }

REQUEST:

  GET /triggers/complete HTTP/1.1
  User-Agent: example-user-agent/0.1
  Host: dcdn.example.com
  Accept: */*

RESPONSE:

  HTTP/1.1 200 OK
  Content-Length: 54
  Expires: Wed, 04 May 2016 08:49:11 GMT
  Server: example-server/0.1
  ETag: "7958041393922269003"
  Cache-Control: max-age=60
  Date: Wed, 04 May 2016 08:48:11 GMT
  Content-Type: application/cdni; ptype=ci-trigger-collection

  {
    "staleresourcetime": 86400,
    "triggers": []
  }

REQUEST:

  GET /triggers/0 HTTP/1.1
  User-Agent: example-user-agent/0.1
  Host: dcdn.example.com
  Accept: */*

RESPONSE:

  HTTP/1.1 200 OK
  Content-Length: 467
  Expires: Wed, 04 May 2016 08:49:10 GMT
  Server: example-server/0.1
  ETag: "6990548174277557683"
  Cache-Control: max-age=60
  Date: Wed, 04 May 2016 08:48:10 GMT
  Content-Type: application/cdni; ptype=ci-trigger.v2

  {
    "ctime": 1462351690,
    "etime": 1462351698,
    "mtime": 1462351690,
    "status": "pending",
    "action": "preposition",
    "specs": [
      {
        "trigger-subject": "metadata",
        "generic-trigger-spec-type": "urls",
        "generic-trigger-spec-value": {
          "urls": [ "https://metadata.example.com/a/b/c" ]
        }
      },
      {
        "trigger-subject": "content",
        "generic-trigger-spec-type": "urls",
        "generic-trigger-spec-value": {
          "urls": [
            "https://www.example.com/a/b/c/1",
            "https://www.example.com/a/b/c/2",
            "https://www.example.com/a/b/c/3",
            "https://www.example.com/a/b/c/4"
          ]
        }
      }
    ]
  }

REQUEST:

  GET /triggers/1 HTTP/1.1
  User-Agent: example-user-agent/0.1
  Host: dcdn.example.com
  Accept: */*

RESPONSE:

  HTTP/1.1 200 OK
  Content-Length: 545
  Expires: Wed, 04 May 2016 08:49:11 GMT
  Server: example-server/0.1
  ETag: "-554385204989405469"
  Cache-Control: max-age=60
  Date: Wed, 04 May 2016 08:48:11 GMT
  Content-Type: application/cdni; ptype=ci-trigger.v2

  {
    "ctime": 1462351691,
    "etime": 1462351699,
    "mtime": 1462351691,
    "status": "pending",
    "action": "invalidate",
    "specs": [
      {
        "trigger-subject": "metadata",
        "generic-trigger-spec-type": "uri-pattern-match",
        "generic-trigger-spec-value": {
          "pattern": "https://metadata.example.com/a/b/*"
        }
      },
      {
        "trigger-subject": "content",
        "generic-trigger-spec-type": "urls",
        "generic-trigger-spec-value": {
          "urls": [ "https://www.example.com/a/index.html" ]
        }
      },
      {
        "trigger-subject": "content",
        "generic-trigger-spec-type": "uri-pattern-match",
        "generic-trigger-spec-value": {
          "pattern": "https://www.example.com/a/b/*",
          "case-sensitive": true
        }
      }
    ]
  }

REQUEST:

  GET /triggers/pending HTTP/1.1
  User-Agent: example-user-agent/0.1
  Host: dcdn.example.com
  Accept: */*
  If-None-Match: "4331492443626270781"

RESPONSE:
  HTTP/1.1 304 Not Modified
  Content-Length: 0
  Expires: Wed, 04 May 2016 08:49:11 GMT
  Server: example-server/0.1
  ETag: "4331492443626270781"
  Cache-Control: max-age=60
  Date: Wed, 04 May 2016 08:48:11 GMT
  Content-Type: application/cdni; ptype=ci-trigger-collection

REQUEST:

  GET /triggers/0 HTTP/1.1
  User-Agent: example-user-agent/0.1
  Host: dcdn.example.com
  Accept: */*
  If-None-Match: "6990548174277557683"

RESPONSE:

  HTTP/1.1 304 Not Modified
  Content-Length: 0
  Expires: Wed, 04 May 2016 08:49:10 GMT
  Server: example-server/0.1
  ETag: "6990548174277557683"
  Cache-Control: max-age=60
  Date: Wed, 04 May 2016 08:48:10 GMT
  Content-Type: application/cdni; ptype=ci-trigger.v2

REQUEST:

  GET /triggers/pending HTTP/1.1
  User-Agent: example-user-agent/0.1
  Host: dcdn.example.com
  Accept: */*

RESPONSE:

  HTTP/1.1 200 OK
  Content-Length: 54
  Expires: Wed, 04 May 2016 08:49:15 GMT
  Server: example-server/0.1
  ETag: "1337503181677633762"
  Cache-Control: max-age=60
  Date: Wed, 04 May 2016 08:48:15 GMT
  Content-Type: application/cdni; ptype=ci-trigger-collection

  {
    "staleresourcetime": 86400,
    "triggers": []
  }

REQUEST:

  GET /triggers/complete HTTP/1.1
  User-Agent: example-user-agent/0.1
  Host: dcdn.example.com
  Accept: */*

RESPONSE:

  HTTP/1.1 200 OK
  Content-Length: 152
  Expires: Wed, 04 May 2016 08:49:22 GMT
  Server: example-server/0.1
  ETag: "4481489539378529796"
  Cache-Control: max-age=60
  Date: Wed, 04 May 2016 08:48:22 GMT
  Content-Type: application/cdni; ptype=ci-trigger-collection

  {
    "staleresourcetime": 86400,
    "triggers": [
       "https://dcdn.example.com/triggers/0",
       "https://dcdn.example.com/triggers/1"
    ]
  }

REQUEST:

  DELETE /triggers/0 HTTP/1.1
  User-Agent: example-user-agent/0.1
  Host: dcdn.example.com
  Accept: */*

RESPONSE:

  HTTP/1.1 204 No Content
  Date: Wed, 04 May 2016 08:48:22 GMT
  Content-Length: 0
  Content-Type: text/html; charset=UTF-8
  Server: example-server/0.1

REQUEST:

  GET /triggers/complete HTTP/1.1
  User-Agent: example-user-agent/0.1
  Host: dcdn.example.com
  Accept: */*

RESPONSE:

  HTTP/1.1 200 OK
  Content-Length: 105
  Expires: Wed, 04 May 2016 08:49:22 GMT
  Server: example-server/0.1
  ETag: "-6938620031669085677"
  Cache-Control: max-age=60
  Date: Wed, 04 May 2016 08:48:22 GMT
  Content-Type: application/cdni; ptype=ci-trigger-collection

  {
    "staleresourcetime": 86400,
    "triggers": [ "https://dcdn.example.com/triggers/1" ]
  }

REQUEST:

  POST /triggers HTTP/1.1
  User-Agent: example-user-agent/0.1
  Host: triggers.dcdn.example.com
  Accept: */*
  Content-Type: application/cdni; ptype=ci-trigger.v2

  {
    "action": "preposition",
    "specs": [{
      "trigger-subject": "content",
      "generic-trigger-spec-type": "content-objectlist",
      "generic-trigger-spec-value": {
        "objects": [{
          "href": "https://www.example.com/hls/title/index.m3u8",
          "type": "hls"
        }]
      }
    }],
    "extensions": [
      {
        "generic-trigger-extension-type": "location-policy",
        "generic-trigger-extension-value": {
          "locations": [
            {
              "action": "allow",
              "footprints": [{
                  "footprint-type": "countrycode",
                  "footprint-value": [ "us" ]
              }]
            },
            {
              "action": "deny",
              "footprints": [{
                 "footprint-type": "countrycode",
                 "footprint-value": [ "ca" ]
              }]
            }
          ]
        },
        "mandatory-to-enforce": true,
        "safe-to-redistribute": true
      },
      {
        "generic-trigger-extension-type": "time-policy",
        "generic-trigger-extension-value": {
          "unix-time-window": {
            "start": 946717200,
            "end": 946746000
          }
        },
        "mandatory-to-enforce": true,
        "safe-to-redistribute": true
      }
    ],
    "cdn-path": [ "AS64496:0" ]
  }

RESPONSE:

  HTTP/1.1 201 Created
  Date: Wed, 04 May 2016 08:48:10 GMT
  Content-Length: 467
  Content-Type: application/cdni; ptype=ci-trigger.v2
  Location: https://triggers.dcdn.example.com/triggers/0
  Server: example-server/0.1

  {
    "errors": [
      {
        "extensions": [{
          "generic-trigger-extension-type": "location-policy",
          "generic-trigger-extension-value": {
            "locations": [
              {
                "action": "allow",
                "footprints": [{
                    "footprint-type": "countrycode",
                    "footprint-value": [ "us" ]
                  }]
              },
              {
                "action": "deny",
                "footprints": [{
                    "footprint-type": "countrycode",
                    "footprint-value": [ "ca" ]
                  }]
              }
            ]
          },
          "mandatory-to-enforce": true,
          "safe-to-redistribute": true
        }],
        "description": "unrecognized extension type",
        "error": "eextension",
        "cdn": "AS64500:0"
      },
      {
        "extensions": [{
          "generic-trigger-extension-type": "time-policy",
          "generic-trigger-extension-value": {
            "unix-time-window": {
              "start": 946717200,
              "end": 946746000
            }
          },
          "mandatory-to-enforce": true,
          "safe-to-redistribute": true
        }],
        "description": "unrecognized extension type",
        "error": "eextension",
        "cdn": "AS64501:0"
      }
    ],
    "ctime": 1462351690,
    "etime": 1462351698,
    "mtime": 1462351690,
    "status": "failed",
    "action": "preposition",
    "specs": [{
      "trigger-subject": "content",
      "generic-trigger-spec-type": "content-objectlist",
      "generic-trigger-spec-value": {
        "objects": [{
          "href": "https://www.example.com/hls/title/index.m3u8",
          "type": "hls"
        }]
      }
    }],
    "extensions": [
      {
        "generic-trigger-extension-type": "location-policy",
        "generic-trigger-extension-value": {
          "locations": [
            {
              "action": "allow",
              "footprints": [{
                "footprint-type": "countrycode",
                "footprint-value": [ "us" ]
              }]
            },
            {
              "action": "deny",
              "footprints": [{
                "footprint-type": "countrycode",
                "footprint-value": [ "ca" ]
              }]
            }
          ]
        },
        "mandatory-to-enforce": true,
        "safe-to-redistribute": true
      },
      {
        "generic-trigger-extension-type": "time-policy",
        "generic-trigger-extension-value": {
          "unix-time-window": {
            "start": 946717200,
            "end": 946746000
          }
        },
        "mandatory-to-enforce": true,
        "safe-to-redistribute": true
      }
    ],
    "cdn-path": [ "AS64496:0" ]
  }

7.1. CDNI Payload Type Parameter Registrations

All references to RFC 8007 in the IANA registries should be replaced with references to this document, apart from references associated with the following registrations:¶

The IANA is requested to register the following new Payload Types in the "CDNI Payload Types" registry defined by [RFC7736], for use with the "application/cdni" MIME media type.¶

[RFC Editor: Please replace RFCthis with the published RFC number for this document.]¶

7.2. "CDNI CI/T Trigger Types" Registry For Trigger Actions

In [RFC8007] the IANA was requested to create a new "CDNI CI/T Trigger Types" registry under the "Content Delivery Network Interconnection (CDNI) Parameters" registry group.¶

Additions to the "CDNI CI/T Trigger Types" registry are made via the RFC Required policy as defined in [RFC8126].¶

In this second edition of the interface, trigger types are referred to as "trigger actions". The "Trigger Types" registry is used for action definitions. Furthermore, this document, and specifically Section 4.1.1, reuses the definition of "trigger types" as defined in [RFC8007] as trigger actions, and provide their specifications, with no modification compared to [RFC8007].¶

7.3. "CDNI CI/T Trigger Specs" Registry

The IANA is requested to create a new "CDNI CI/T Trigger Specs" registry in the "Content Delivery Networks Interconnection (CDNI) Parameters" registry group. The "CDNI CI/T Trigger Specs" namespace defines the valid trigger targets' spec values in Section 4.1.2, used by the Trigger Spec object.¶

Additions to the "CDNI CI/T Trigger Specs" registry are made via the RFC Required policy as defined in [RFC8126].¶

The initial contents of the "CDNI CI/T Trigger Specs" registry comprise the names and descriptions listed in Section 4.1.2, with this document acting as the specification.¶

7.4. "CDNI CI/T Trigger Subjects" Registry

The IANA is requested to create a new "CDNI CI/T Trigger Subjects" registry in the "Content Delivery Networks Interconnection (CDNI) Parameters" registry group. The "CDNI CI/T Trigger Subjects" namespace defines the valid trigger targets' subject values in Section 4.1.2.2, used by the Trigger Spec object.¶

Additions to the "CDNI CI/T Trigger Subjects" registry are made via the RFC Required policy as defined in [RFC8126].¶

The initial contents of the "CDNI CI/T Trigger Subjects" registry comprise the names and descriptions listed in Section 4.1.2.2, with this document acting as the specification.¶

7.5. "CDNI CI/T Object List Types" Registry

The IANA is requested to create a new "CDNI CI/T Object List Types" registry in the "Content Delivery Networks Interconnection (CDNI) Parameters" registry group. The "CDNI CI/T Object List Types" namespace defines the valid object list type values in Section 4.3.2.1, used by the Object List object.¶

Additions to the "CDNI CI/T Object List Types" registry are made via the RFC Required policy as defined in [RFC8126].¶

The initial contents of the "CDNI CI/T Object List Types" registry comprise the names and descriptions listed in Section 4.3.2.1, with this document acting as the specification.¶

7.6. "CDNI CI/T Trigger Extensions" Registry

The IANA is requested to create a new "CDNI CI/T Trigger Extensions" registry in the "Content Delivery Networks Interconnection (CDNI) Parameters" registry group. The "CDNI CI/T Trigger Extensions" namespace defines the valid trigger targets' extension values in Section 2.7, used by the Trigger Spec object.¶

Additions to the "CDNI CI/T Trigger Extensions" registry are made via the RFC Required policy as defined in [RFC8126].¶

The initial contents of the "CDNI CI/T Trigger Extensions" registry comprise the names and descriptions listed in Section 2.7, with this document acting as the specification.¶

7.7. "CDNI CI/T Error Codes" Registry

In [RFC8007] the IANA was requested to create a new "CDNI CI/T Error Codes" registry under the "Content Delivery Network Interconnection (CDNI) Parameters" registry group.¶

Additions to the "CDNI CI/T Error Codes" registry are made via the Specification Required policy as defined in [RFC8126]. The Designated Expert will verify that new Error Code registrations do not duplicate existing Error Code definitions (in name or functionality), prevent gratuitous additions to the namespace, and prevent any additions to the namespace that would impair the interoperability of CDNI implementations.¶

In this second edition of the interface, we list and repeat the definition of the Error Codes from [RFC8007] - acting as the entities specification with no modification compared to [RFC8007]. Additionally, the IANA is requested to register three additional error codes, "espec", "esubject" and "eextension", with specification as defined in Section 4.1.5.2.¶

7.8. "CDNI CI/T URL Types" Registry

The IANA is requested to create a new "CDNI CI/T URL types" registry in the "Content Delivery Networks Interconnection (CDNI) Parameters" registry group. The "CDNI CI/T URL Types" namespace defines the valid URL type values in Section 4.3.1, used by Section 4.1.2.3, Section 4.1.2.5, Section 4.1.2.6 and Section 4.1.2.7.¶

The initial contents of the "CDNI CI/T Trigger Extensions" registry comprise the names and descriptions listed in Section 4.3.1, with this document acting as the specification.¶

8.1. Authentication, Authorization, Confidentiality, Integrity Protection

A CI/T implementation MUST support Transport Layer Security (TLS) transport for HTTP (HTTPS) as per [RFC9110].¶

TLS MUST be used by the server side (dCDN) and the client side (uCDN) of the CI/T interface, including the authentication of the remote end, unless alternate methods are used to ensure the security of the information in the CI/T interface requests and responses (such as setting up an IPsec tunnel between the two CDNs or using a physically secured internal network between two CDNs that are owned by the same corporate entity).¶

The use of TLS for transport of the CI/T interface allows dCDN and uCDN to authenticate each other using the TLS client authentication and TLS server authentication.¶

Once dCDN and uCDN have mutually authenticated each other, TLS allows:¶

• dCDN and uCDN to authorize each other (to ensure that they are receiving trigger requests from, or responding to, an authorized CDN).¶

• CDNI commands and responses to be transmitted with confidentiality.¶

• Protection of the integrity of CDNI commands and responses.¶

When TLS is used, the general TLS usage guidance in [RFC9325] MUST be followed.¶

The mechanisms for access control are dCDN-specific and are not standardized as part of this CI/T specification.¶

HTTP requests that attempt to access or operate on CI/T data belonging to another CDN MUST be rejected using, for example, HTTP 403 ("Forbidden") or 404 ("Not Found"). This is intended to prevent unauthorized users from generating unnecessary load in dCDNs or uCDNs due to revalidation, reacquisition, or unnecessary acquisition.¶

When deploying a network of interconnected CDNs, the possible inefficiencies related to the diamond configuration discussed in Section 2.8 should be considered.¶

8.2. Denial of Service

This document does not define a specific mechanism to protect against Denial-of-Service (DoS) attacks on the CI/T interface. However, CI/T endpoints can be protected against DoS attacks through the use of TLS transport and/or via mechanisms outside the scope of the CI/T interface, such as firewalling or the use of Virtual Private Networks (VPNs).¶

Depending on the implementation, triggered activity may consume significant processing and bandwidth in dCDN. A malicious or faulty uCDN could use this to generate unnecessary load in dCDN. dCDN should consider mechanisms to avoid overload -- for example, by rate-limiting acceptance or processing of triggers, or by performing batch processing.¶

8.3. Privacy

The CI/T protocol does not carry any information about individual end users of a CDN; there are no privacy concerns for end users.¶

The CI/T protocol does carry information that could be considered commercially sensitive by CDN operators and content owners. The use of mutually authenticated TLS to establish a secure session for the transport of CI/T data, as discussed in Section 8.1, provides confidentiality while the CI/T data is in transit and prevents parties other than the authorized dCDN from gaining access to that data. dCDN MUST ensure that it only exposes CI/T data related to uCDN to clients it has authenticated as belonging to that uCDN.¶