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 keywords "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 the HTTP/1.1 protocol [RFC9112] and follows the principles of the Representational State Transfer (REST) architectural style. The uCDN, in its capacity as a CI/T interface client, requests the dCDN to carry out an action ("trigger") related to metadata or content stored by the dCDN on behalf of the uCDN.¶

The 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 the uCDN. Each such trigger is identified by a unique Uniform Resource Identifier (URI) as defined in Section 4.2 of [RFC9110].¶

Once a trigger is created, the uCDN can retrieve its representation from the dCDN or request the trigger to be modified by transferring an updated representation of it to the dCDN. The CI/T interface supports the 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 the uCDN passed commands to the dCDN using "ci-trigger-command" objects, and the 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 were used instead. The HEAD method can be used to verify that the target resource exists on the server.¶

2.3. Trigger

The uCDN requests creation of a trigger resource to instruct the dCDN to perform an action. If the dCDN accepts the request, it creates a new trigger resource and returns its unique URI to the uCDN. The uCDN MUST use this URI for all requests associated with the created trigger resource.¶

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

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

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

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

• purge - used to instruct the 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. The dCDN creates new triggers in the "pending" state. Once the dCDN starts processing a pending trigger, the trigger state is set to "active". The uCDN MAY explicitly request the trigger to be created in the "active" state. If accepted by the dCDN, it may create the new trigger in the "active" state and start its processing immediately upon creation. Once the trigger processing is complete, the state is set to either "complete" or "failed", depending on the processing outcome.¶

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

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

2.4. Trigger Access Control and Multi-Tenancy

The dCDN MUST only allow the uCDN access to the trigger resources it created.¶

The dCDN MUST ensure that triggers created in response to a uCDN request apply only to content and metadata objects associated with that uCDN.¶

In case of content prepositioning, the dCDN MUST be able to associate content objects referenced in a trigger created by the uCDN with delivery CDNI metadata objects in its possession that are associated with the same uCDN. These CDNI metadata objects include HostIndex, HostMatch, HostMetadata, PathMatch, PatternMatch, and PathMetadata, as described in Section 3.1 of [RFC8006]. For example, if the dCDN has no MI metadata objects that enable the dCDN to respond to requests for video.example.com, it MUST NOT allow prepositioning of content objects with this hostname in the object URL.¶

In case of metadata prepositioning, the prepositioned metadata objects MUST be consistent with pre-existing metadata, e.g., prepositioning of the MI HostMatch object in the absence of MI HostIndex would be rejected.¶

If such association between a trigger and pre-existing delivery metadata cannot be established, the dCDN MUST reject it.¶

Furthermore, the dCDN SHOULD reject a trigger from the uCDN A that seeks to preposition delivery metadata objects that are in conflict with the pre-existing metadata objects belonging to another uCDN B, e.g., if it could cause the dCDN to match a content request with metadata objects from multiple uCDNs.¶

2.5. Trigger Index and Trigger Collections

The Trigger Index is the top-level resource that references all trigger resources belonging to a particular uCDN. The dCDN maintains one Trigger Index resource for each uCDN, and each uCDN has access only to its own Trigger Index. The Trigger Index contains references to Trigger Collection resources. Each collection contains triggers that are optionally filtered by parameters - for example, all triggers in the "pending" state or all triggers labeled "video". The same trigger resource can be present in more than one collection. The supported trigger collection representations are listed in Section 4.3 and include filtering of triggers by state and label. Note that additional trigger collection representations can be defined in the future.¶

2.6. 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 the dCDN and for the uCDN to discover the status of that activity. Only successful triggering is shown. Please note that the example below uses simplified trigger identifiers for brevity. It is recommended that the actual implementation uses unique UUID identifiers as specified in [RFC9562]. Examples of the messages are shown in Section 6.¶

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

The steps in Figure 1 are as follows:¶

1. The uCDN requests creation of a new trigger resource by POSTing its representation to the trigger index resource with a well-known URI "https://dcdn.example/cit/uCDN".¶

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

3. The dCDN responds to the uCDN with an HTTP 201 ("Created") response status and the location of the trigger resource.¶

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

5. The 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", "processed", "failed" or "cancelled"), the uCDN MAY request deletion of the trigger resource.¶

7. The 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. The dCDN responds to the deletion request with a 200 ("OK") status code.¶

This section provides an overview of a regular session. For detailed discussions of trigger modification, cancellation, and deletion, see Section 3.2, Section 3.3, and Section 3.5.¶

2.7. Trigger Processing

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

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

A transit CDN is a dCDN that passes on CDNI Metadata and content to the dCDNs located further downstream.¶

The dCDN that creates trigger resources at the request of such transit CDN MUST associate the triggers with the transit CDN from which it receives the request, regardless of where the trigger request may have originated.¶

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

The "diamond" configuration may cause configuration consistency problems, where the dCDN may end up in possession of multiple, potentially conflicting metadata objects belonging to the multiple uCDNs that match the same content request. The conflict may arise due to the differences in trigger processing by the transit CDNs and/or variances in trigger propagation time across different paths in the "diamond" topology.¶

Because of this, the "diamond" configuration is considered a configuration error. A dCDN that receives identical trigger creation requests from different uCDNs SHOULD reject duplicate trigger requests, as described in Section 2.4.¶

Security considerations are discussed further in Section 8.¶

If the dCDN is also acting as the 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 a transit CDN until it is "complete" in all of its dCDNs and in the transit CDN itself. If a trigger is reported as "processed" in the transit CDN or any one of its dCDNs, transit CDNs MUST report the trigger as "processed" as well. If a trigger is reported as "failed" by the transit CDN or any one of its dCDNs, the transit 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 cascaded dCDNs.¶

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

When such CDN topologies become possible, it is RECOMMENDED that CDNs participating in it utilize a CDN Provider ID (PID) (Section 4.4.3) to detect and prevent loops as follows:¶

• The uCDNs that originate a new trigger request SHOULD specify their CDN provider ID using the trigger "cdn-path" attribute (see Section 4.1 for details).¶

• A dCDN that receives a trigger creation request that contains a "cdn-path" attribute SHOULD check it for its own CDN PID. If the dCDN's PID is already present, and the dCDN is not the CDN initiating the trigger, this condition likely indicates a loop. In such case, the dCDN MUST reject the trigger, which would result in a trigger rejection being returned to the originating uCDN. If the dCDN receives a trigger that it itself originated, the dCDN MAY process the trigger as required.¶

• A dCDN that cascades trigger requests to additional dCDNs (so-called "transit CDN") SHOULD NOT reject triggers that have CDN PID of its downstream CDNs in their CDN path, allowing each CDN to do their own loop detection.¶

• Transit CDNs MUST append their CDN PID to the CDN path of a trigger before sending it to its downstream CDNs.¶

• The dCDNs SHOULD advertise their CDN provider ID to the uCDNs using the "cdn-id" attribute of the trigger index (Section 4.2) resource.¶

3.1. Creating Triggers

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

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

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

The new trigger resource is created in a "pending" state. If successful, The HTTP response to the uCDN trigger creation request MUST have status code 201 ("Created") 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 the dCDN processed the trigger immediately.¶

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

The dCDN SHOULD provide continuous updates of the trigger processing progress by responding with updated trigger resource representations to the subsequent uCDN requests sent to the created trigger URI. 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 if it were a request in the "complete" state. In this case, the dCDN SHOULD also provide an estimated completion time for the request by using the trigger "etime" property.¶

The uCDN MAY request the new trigger to be created in the "active" state so that its processing begins immediately. If agreed to by the dCDN, the dCDN MUST start the new trigger processing immediately.¶

Otherwise, the 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 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 the uCDN, subject to the constraints described below.¶

3.2. Modifying Triggers

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

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

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

The 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 the dCDN receives the request¶

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

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

The 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 the dCDN or an appropriate 4xx HTTP error code in case of a malformed request.¶

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

3.3. Cancelling Triggers

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

The dCDN MUST respond to the trigger cancellation request with an appropriate HTTP response status code as documented in Section 3.2¶

If cancellation of a "pending" trigger is accepted by the dCDN, the 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 the uCDN cannot control the timing of that activity. Processing could, for example, start after the POST is sent by the uCDN but before that request is processed by the dCDN.¶

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

If the dCDN cannot stop the trigger processing immediately after receiving the request from the 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 the dCDN. Its state MUST NOT be changed.¶

3.4. Checking Status

The 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 enable the uCDN to use client-side caching of the trigger index resource, as well as all trigger and trigger collection resources, each resource representation sent by the dCDN SHOULD include at least one of the following HTTP response headers: "ETag" or "Last-Modified". The dCDN should respond with the HTTP 304 ("Not Modified") status code and no response body for conditional resource requests using the 'If-None-Match' and/or 'If-Modified-Since' headers, as specified in Section 13 of [RFC9110], if it does not have a more recent resource representation.¶

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

3.5. Deleting Triggers

The uCDN MAY request the deletion of 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 trigger collections. Subsequent requests to the trigger resource URI MUST be rejected by the 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, the uCDN SHOULD cancel triggers rather than delete them when it needs to access the trigger status after processing has terminated.¶

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

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

Deletion of a "complete", "cancelled", "cancelling", or "failed" trigger MUST result in no further processing by the dCDN.¶

The dCDN MUST respond to the trigger deletion request appropriately. The dCDN MUST respond with 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 yet been deleted, 404 (Not Found) if the trigger resource does not exist, or 501 (Not Implemented) if deletion is not supported by the dCDN.¶

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

3.6. Expiry of Triggers

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

If the dCDN does remove triggers in a terminal state automatically, it MUST report the expiry timeout period, using an attribute "staleresourcetime" of the trigger index resource (see Section 4.2 for details.¶

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

3.7. Error Handling

The dCDN MAY reject CI/T interface requests by responding with 4xx or 5xx HTTP status codes. For example, the 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 the 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 the dCDN is unable to pass a trigger on to any of its cascaded dCDNs:¶

• If the trigger is abandoned by the dCDN, the 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, the dCDN SHOULD keep the trigger "pending" or "active" state until either the trigger is acted upon or the uCDN chooses to cancel it.¶

uCDN-A                         dCDN-B                         dCDN-C
 |                              |                              |
 | (1) POST                     |                              |
 | https://dcdn-b.com           |                              |
 | /cit/uCDN-A                  |                              |
[ ]--------------------------->[ ]--+                          |
 |                             [ ]  | (2)                      |
 |                             [ ]<-+                          |
 | (3) HTTP 201 Response.      [ ]                             |
 |<----------------------------[ ]                             |
 | Loc:                        [ ]                             |
 | https://dcdn-b.com          [ ] (4) POST                    |
 | /cit/ucdn-a/123             [ ] https://dcdn-c.com          |
 |                             [ ] /cit/dcdn-b                 | (5)
 |                             [ ]--------------------------->[ ]--+
 |                              |                             [ ]  |
 |                              |                             [ ]<-+
 |                              | (6) HTTP 201 Response.      [ ]
 |                             [ ]<---------------------------[ ]
 |                              |  Loc:                        |
 |                              |  https://dcdn-c.com          |
 |                              |  /cit/dcdn-b/456             |
 |                              |                              |
 |                             [ ]--+                          |
 |                             [ ]  | (7.1)                    |
 |                             [ ]<-+                         [ ]--+
 |                              |                       (7.2) [ ]  |
 |                              |                             [ ]<-+
 |                              |                              |
 .                              .                              .
 .                              .                              .
 .                              .                              .
 |                              | (8) GET                      |
 |                              | https://dcdn-c.com           |
 |                              | /cit/dcdn-b/456              |
 |                             [ ]--------------------------->[ ]
 |                              |                             [ ]
 |                              | (9) HTTP 200                [ ]
 |                              | Trigger resource            [ ]
 |                             [ ]<---------------------------[ ]
 |                              |                              |
 .                              .                              .
 .                              .                              .
 .                              .                              .
 | (10) GET                     |                              |
 | https://dcdn-b.com           |                              |
 | /cit/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". Please note that the dCDN MUST include all existing trigger attributes in the trigger resource representation when requested by the uCDN. The trigger 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-to-Specify: It is optional for trigger updates, otherwise mandatory.¶

  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-to-Specify: It is optional for trigger updates, otherwise mandatory. Furthermore, when mandatory, 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-to-Specify: No. The default is no extensions.¶

  Name: labels

  Description: Array of trigger labels, as described in Section 4.1.4.¶

  Value: Array of trigger labels. Each label is a key-value pair, encoded as a JSON string, with "=" separator. The label key and value parts MUST contain up to 63 characters each, MUST begin with a letter or a number, and MAY contain letters, numbers, hyphens, dots, and underscores.¶

  Mandatory-to-Specify: 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.4.3.¶

  Mandatory-to-Specify: 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 the dCDN; there is no requirement to synchronize clocks between interconnected CDNs.¶

  Value: Time, as defined in Section 4.3.4 of [RFC8006].¶

  Mandatory-to-Specify: The dCDN MUST specify in trigger status representations. It is ignored when included in trigger representations sent by the uCDN.¶

  Name: mtime

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

  Value: Time, as defined in Section 4.3.4 of [RFC8006].¶

  Mandatory-to-Specify: The dCDN MUST specify in trigger status representations. It is ignored when included in trigger representations sent by the uCDN.¶

  Name: etime

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

  Value: Time, as defined in Section 4.3.4 of [RFC8006].¶

  Mandatory-to-Specify: The dCDN MAY specify in trigger status representations. It is ignored when included in trigger representations sent by the uCDN.¶

  Name: state

  Description: The current trigger state.¶

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

  Mandatory-to-Specify: The dCDN MUST include trigger state in the trigger resource representations it sends. The trigger state defaults to "pending" when a trigger is created and is optional in trigger updates sent by the uCDN.¶

  Name: state-reason

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

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

  Mandatory-to-Specify: No. The dCDN MAY include the trigger reason in the trigger resource representations it sends.¶

  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.6.1. An empty array is allowed and is equivalent to omitting the "errors" attribute from the object.¶

  Mandatory-to-Specify: No. The dCDN SHOULD include this attribute in the trigger resource representations it sends when the trigger is in a "failed" state.¶

  Name: total-objects-count

  Description: Total aggregate number of objects affected by the trigger, e.g., number of objects purged, invalidated or prepositioned as a result of trigger processing. It is RECOMMENDED that the dCDN maintains this attribute as a cumulative counter across all of its nodes, without de-duplicating the same objects processed in multiple nodes. The primary purpose of this attribute is to help the uCDN identify abnormal trigger processing results, e.g., a purge or preposition trigger that impacted a lower number of objects than expected. The dCDN MAY provide an updated object count as the trigger processing progresses in an "active" trigger state.¶

  Value: Integer.¶

  Mandatory-to-Specify: No. This attribute is "optional-to-implement". When supported, the dCDN SHOULD include this attribute in the trigger resource representations requested by the uCDN.¶

  Name: total-nodes-count

  Description: The total number of unique dCDN nodes affected by the trigger. The primary purpose of this attribute is to help the uCDN validate trigger processing results in combination with the cumulative counters "total-objects-count" and "total-objects-size". The dCDN MAY provide an updated nodes count as the trigger processing progresses in an "active" trigger state.¶

  Value: Integer.¶

  Mandatory-to-Specify: No. This attribute is "optional-to-implement". When supported, the dCDN SHOULD include this attribute in the trigger resource representations requested by the uCDN.¶

  Name: total-objects-size

  Description: Total aggregate size of objects affected by the trigger, in bytes. It is RECOMMENDED that the dCDN maintains this attribute as a cumulative counter across all of its nodes, without de-duplicating the same objects processed in multiple nodes. As with "total-objects-count" attribute above, the primary purpose of this attribute is to help the uCDN identify abnormal trigger processing results. The dCDN MAY provide an updated object size as the trigger processing progresses in "active" trigger state.¶

  Value: Integer.¶

  Mandatory-to-Specify: No. This attribute is "optional-to-implement". When supported, the dCDN SHOULD include this attribute in the trigger resource representations requested by the uCDN.¶

  Name: objects

  Description: List of objects derived by the dCDN when processing the trigger. When the "content-objectlist" trigger specification is used, the trigger MAY include one or more manifest files that form a hierarchical structure (e.g., media HLS playlists referenced by master HLS playlists, or JSON object lists referenced by other JSON object lists). The purpose of this optional attribute is to provide a single, flattened list of content objects derived from the input trigger.¶

  Value: An array of ObjectList (Section 4.4.2) objects. The dCDN SHOULD provide the list of objects it used as input for processing the trigger with Section 4.1.2.8, provided that the 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-to-Specify: No. The dCDN MAY send this attribute in its trigger resource representation when available and the capability is advertised via FCI as described above.¶

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

}

{
  "trigger-subject": "metadata",
  "cit-spec-type": "urls",
  "cit-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
}

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

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

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

{
  "cit-extension-type": "location-policy",
  "cit-extension-value": {
    "locations": [
      {
        "action": "allow",
        "footprints": [{
          "footprint-type": "countrycode",
          "footprint-value": [ "us" ]
        }]
      },
      {
        "action": "deny",
        "footprints": [{
          "footprint-type": "subdivisioncode",
          "footprint-value": [ "us-ma" ]
        }]
      }
    ]
  }
}

{
   "cit-extension-type": "time-policy",
   "cit-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"
}

{
  "cit-extension-type": "execution-policy",
  "cit-extension-value":
  {
    "priority": 100,
    "depends": [
     "https://dcdn.example/cit/b1467469-3cf3-4613-8629-814cd938f30b",
     "https://dcdn.example/cit/c73a9911-298b-4ee3-bbab-03bce07b7d5c"
    ]
  }
}

{
  "error": "econtent",
  "description": "Failed to parse HLS object list",
  "specs": [{
    "trigger-subject": "content",
    "cit-spec-type": "content-objectlist",
    "cit-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 location-policy",
    "specs": [{
      "trigger-subject": "content",
      "cit-spec-type": "urls",
      "cit-spec-value": {
        "urls": [
          "https://www.example.com/a/b/c/1",
          "https://www.example.com/a/b/c/2"
        ]
      }
    }],
    "extensions": [{
      "cit-extension-type": "location-policy",
      "cit-extension-value": {
        "locations": [{
          "action": "deny",
          "footprints": [{
              "footprint-type": "countrycode",
              "footprint-value": [ "ca" ]
            }]
          }]
        }
    }],
    "cdn": "AS64500:0"
  }]
}

4.2. Trigger Index Resource

As described in Section 2.1, the dCDN maintains RESTful trigger resources that represent actions ("triggers") requested by the uCDN for execution by the dCDN.¶

The trigger index resource maintains references to all trigger collection resources that can be used to retrieve triggers. The dCDN MUST create the trigger index resource when it first instantiates the CI/T interface for a uCDN, before any trigger resources are created. The dCDN MUST also create the unfiltered trigger collection containing all triggers, as well as trigger collections for each trigger state, and include references to these collections in the top-level trigger index resource. The dCDN MUST NOT remove the trigger index resource, the unfiltered trigger collection, or the state-based trigger collections once they have been created, as long as it continues to offer CI/T services to the uCDN.¶

The dCDN MUST update both the unfiltered trigger collection and the state-based trigger collections when triggers are created, deleted, or their state changes.¶

If triggers include labels, the dCDN MUST create and maintain a trigger collection resource for each label value used in any trigger resources, and update the trigger index to keep references to label-based trigger collections current. The dCDN MUST remove a label-based trigger collection when no triggers remain that use the corresponding label value.¶

As a top-level resource, the trigger index also includes global dCDN attributes, such as the "staleresourcetime" attribute, which regulates the expiration of completed triggers, and the "cdn-id" attribute, which indicates the CDN PID of the dCDN.¶

The trigger index resource representation MUST use a MIME media type of "application/cdni; ptype=ci-trigger-index.v2".¶

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

• Name: collections

  Description: Array of Trigger Collection View (Section 4.3.1) objects.¶

  Value: An array of JSON-encoded Trigger Collection View objects, one for each existing trigger collection resource. This includes the unfiltered trigger collection, per-state trigger collections (one for each trigger state as specified in Section 4.1.5), and any per-label trigger collections, if they exist.¶

  Mandatory-to-Specify: Yes.¶

  Name: staleresourcetime

  Description: The length of time for which the dCDN guarantees to keep a completed trigger resource. After this time, the 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-to-Specify: Yes.¶

  Name: cdn-id

  Description: The dCDN PID.¶

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

  Mandatory-to-Specify: No.¶

4.3. Trigger Collection Resource

The collection of trigger resources represents triggers created by the dCDN, optionally filtered by a parameter.¶

Trigger resources in a collection are usually 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 resource 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.¶

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

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

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

• Name: trigger-urls

  Description: Links to trigger resources in the collection.¶

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

  Mandatory-to-Specify: Yes.¶

  Name: trigger-objects

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

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

  Name: filter-type

  Description: Indicates the type of filter applied to select the triggers in the collection.¶

  Value: One of "state" or "label".¶

  Mandatory-to-Specify: No. The "filter-type" attribute MUST be used only in per-state and per-label trigger collections. If omitted or empty, the trigger collection MUST include all existing triggers.¶

  Name: filter-value

  Description: Specifies the filter value used to select the triggers in the collection.¶

  Value: For per-label trigger collections, this attribute MUST contain the corresponding label value. For per-state trigger collections, it MUST contain the trigger state shared by all triggers in the collection.¶

  Mandatory-to-Specify: No. The "filter-value" attribute MUST be used only in per-state and per-label trigger collections. If omitted or empty, the trigger collection MUST include all existing triggers.¶

4.4. Other CI/T Objects and Properties

This section describes common CI/T objects, which are used as part of the specification of several other 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-to-Specify: Yes.¶

  Name: trigger-versions

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

  Value: An array of JSON strings. Valid values include "v2", corresponding to this version of the interface, and "v1", corresponding to [RFC8007].¶

  Mandatory-to-Specify: Yes.¶

  Name: trigger-subjects

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

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

  Mandatory-to-Specify: No. A missing or empty "trigger-subjects" list means that all trigger subjects are supported by the endpoint. The 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), the 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/configuration/",
        "trigger-versions": [ "v1" ],
        "trigger-subjects": "metadata"
      },
      "footprints": {
        "footprint-type": "countrycode",
        "footprint-value": [ "us", "br" ]
      }
    },
    {
      "capability-type": "FCI.CITEndpoints",
      "capability-value": {
        "trigger-endpoint-uri":
          "https://dcdn.example/cache-management-us/",
        "trigger-versions": [ "v2" ],
        "trigger-subjects": "content"
      },
      "footprints": {
        "footprint-type": "countrycode",
        "footprint-value": [ "us" ]
      }
    },
    {
      "capability-type": "FCI.CITEndpoints",
      "capability-value": {
        "trigger-endpoint-uri":
          "https://dcdn.example/cache-management-br/",
        "trigger-versions": [ "v2" ],
        "trigger-subjects": "content"
      },
      "footprints": {
        "footprint-type": "countrycode",
        "footprint-value": [ "br" ]
      }
    }
  ]
}

5.2. CI/T Trigger Scope Capability Object

The CI/T supports several trigger actions for different trigger subjects as defined in Section 4.1.1 and Section 4.1.2.2. Additional actions, as well as subjects, may be defined in the future. The trigger scope capability object is used to indicate support for a trigger action for a subject. It further specifies the trigger generic spec types that may be used for selecting the targets to which the triggers apply, along with the supported trigger generic extension types.¶

All supported combinations of trigger actions and trigger subjects MUST be explicitly advertised, with one FCI.CITScope object provided for each combination.¶

The "trigger-scope-capability" object matches the "FCI.CITScope" capability type and is encoded as a JSON object containing the following name/value pairs:¶

• Name: trigger-action

  Description: The supported CDNI CI/T trigger action.¶

  Value: A string corresponding to an entry from the "CDNI CI/T Trigger Types" registry Section 7.2, which corresponds to a CDNI CI/T trigger action.¶

  Mandatory-to-Specify: Yes.¶

  Name: trigger-subject

  Description: The supported CDNI CI/T trigger subject.¶

  Value: A string corresponding to an entry from the "CDNI CI/T Trigger Subjects" registry Section 7.4, which corresponds to a CDNI CI/T trigger subject.¶

  Mandatory-to-Specify: Yes.¶

  Name: trigger-specs

  Description: A list of supported CDNI CI/T GenericSpecObject types for trigger action and subject.¶

  Value: List of JSON strings corresponding to entries from the "CDNI CI/T Trigger Specs" registry Section 7.3, which correspond to CDNI CI/T GenericSpecObject objects.¶

  Mandatory-to-Specify: No. The default in case of a missing or an empty list MUST be interpreted as "no GenericSpecObject types supported". A non-empty list MUST be interpreted as containing "the only GenericSpecObject types that are supported".¶

  Name: trigger-extensions

  Description: A list of supported CDNI CI/T GenericExtensionObject types for trigger action and subject.¶

  Value: List of JSON strings corresponding to entries from the "CDNI CI/T Trigger Extension" registry Section 7.6, which corresponds to a CDNI CI/T GenericExtensionObject object.¶

  Mandatory-to-Specify: No. The default in case of a missing or an empty list MUST be interpreted as "no GenericExtensionObject types are supported". A non-empty list MUST be interpreted as containing "the only GenericExtensionObject types that are supported".¶

{
     "capabilities": [
        {
          "capability-type": "FCI.CITScope",
          "capability-value": {
             "trigger-action": "preposition",
             "trigger-subject": "content",
             "trigger-specs": [ "urls", "ccids" ],
             "trigger-extensions": [ "time-policy" ]
          },
          "footprints": {
            "footprint-type": "countrycode",
            "footprint-value": [ "us" ]
         }
       },
       {
          "capability-type": "FCI.CITScope",
          "capability-value": {
             "trigger-action": "invalidate",
             "trigger-subject": "content",
             "trigger-specs": [ "urls", "ccids" ]
          },
          "footprints": {
            "footprint-type": "countrycode",
            "footprint-value": [ "us" ]
          }
       }
    ]
}
}

5.3. CI/T Object List Type Capability Object

Given an object list being supported by the 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 JSON strings representing ObjectListTypes (Section 4.4.2.1).¶

  Mandatory-to-Specify: No. 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.4.1 for details). The capability type is "FCI.CITPrivateUrlType".¶

• Name: private-url-type-support

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

  Value: Boolean.¶

  Mandatory-to-Specify: No. A 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

The CI/T extended trigger status capability object is used to indicate support for extended trigger status. The extended trigger status is returned upon the uCDN request and includes:¶

• "objects" attribute in the trigger object¶

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

• "trigger-objects" attribute in the trigger collection 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-to-Specify: 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

REQUEST:

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

{
  "action": "preposition",
  "specs": [
    {
      "trigger-subject": "metadata",
      "cit-spec-type": "urls",
      "cit-spec-value": {
      "urls": [ "https://metadata.example.com/a/b/c" ]
           }
    },
    {
      "trigger-subject": "content",
      "cit-spec-type": "urls",
      "cit-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: Sun, 27 Oct 2024 08:48:10 GMT
Content-Length: 710
Content-Type: application/cdni; ptype=ci-trigger.v2
Location: https://dcdn.example/cit/3f2d259d-a980-4742-beeb-9392a58129f5
Server: example-server/0.1

{
  "ctime": 1730119690,
  "etime": 1730119750,
  "mtime": 1730119690,
  "state": "pending",
  "action": "preposition",
  "specs": [
    {
      "trigger-subject": "metadata",
      "cit-spec-type": "urls",
      "cit-spec-value": {
        "urls": [ "https://metadata.example.com/a/b/c" ]
      }
    },
    {
      "trigger-subject": "content",
      "cit-spec-type": "urls",
      "cit-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 /cit HTTP/1.1
User-Agent: example-user-agent/0.1
Host: dcdn.example
Accept: */*
Content-Type: application/cdni; ptype=ci-trigger.v2
Content-Length: 783

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

RESPONSE:

HTTP/1.1 201 Created
Date: Sun, 27 Oct 2024 08:48:11 GMT
Content-Length: 807
Content-Type: application/cdni; ptype=ci-trigger.v2
Location: https://dcdn.example/cit/327df5b8-1df8-4cff-92f8-fda27774c171
Server: example-server/0.1

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

REQUEST:

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

{
  "action": "invalidate",
  "specs": [{
    "trigger-subject": "content",
    "cit-spec-type": "uri-regex-match",
    "cit-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: Sun, 27 Oct 2024 08:48:12 GMT
Content-Length: 960
Content-Type: application/cdni; ptype=ci-trigger.v2
Location: https://dcdn.example/cit/991b9fb9-d0be-4d05-be06-64c0e5c5a5f9
Server: example-server/0.1

{
  "errors": [{
    "specs": [{
      "trigger-subject": "content",
      "cit-spec-type": "uri-regex-match",
      "cit-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": "The dCDN rejected a regex due to complexity",
    "error": "ereject",
    "cdn": "AS64500:0"
  }],
  "ctime": 1730119692,
  "etime": 1730119692,
  "mtime": 1730119692,
  "state": "failed",
  "action": "invalidate",
  "specs": [{
    "trigger-subject": "content",
    "cit-spec-type": "uri-regex-match",
    "cit-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 /cit HTTP/1.1
User-Agent: example-user-agent/0.1
Host: dcdn.example
Accept: */*
Content-Type: application/cdni; ptype=ci-trigger.v2
Content-Length: 328

{
  "action": "preposition",
  "specs": [{
    "trigger-subject": "content",
    "cit-spec-type": "content-objectlist",
    "cit-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: Sun, 27 Oct 2024 08:48:13 GMT
Content-Length: 829
Content-Type: application/cdni; ptype=ci-trigger.v2
Location: https://dcdn.example/cit/86633e6e-d2da-4185-a285-b3d087a5d711
Server: example-server/0.1

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

6.2. Changing, Cancelling and Deleting Triggers

REQUEST:

POST /cit/3f2d259d-a980-4742-beeb-9392a58129f5 HTTP/1.1
User-Agent: example-user-agent/0.1
Host: dcdn.example
Accept: */*
Content-Type: application/cdni; ptype=ci-trigger.v2
Content-Length: 401

{
  "specs": [
    {
      "trigger-subject": "content",
      "cit-spec-type": "urls",
      "cit-spec-value": {
        "urls": [
          "https://www.example.com/d/e/f/1",
          "https://www.example.com/d/e/f/2",
          "https://www.example.com/d/e/f/3",
          "https://www.example.com/d/e/f/4"
        ]
      }
    }
  ],
  "labels": [
    "type=video"
  ]
}

RESPONSE:

HTTP/1.1 200 OK
Date: Sun, 27 Oct 2024 08:48:14 GMT
Content-Length: 520
Content-Type: application/cdni; ptype=ci-trigger.v2
Server: example-server/0.1

{
  "ctime": 1730119694,
  "etime": 1730119754,
  "mtime": 1730119694,
  "state": "pending",
  "action": "preposition",

  "specs": [
    {
      "trigger-subject": "content",
      "cit-spec-type": "urls",
      "cit-spec-value": {
        "urls": [
          "https://www.example.com/d/e/f/1",
          "https://www.example.com/d/e/f/2",
          "https://www.example.com/d/e/f/3",
          "https://www.example.com/d/e/f/4"
        ]
      }
    }
  ],
  "labels": [
    "type=video"
  ]
}

REQUEST:

POST /cit/3f2d259d-a980-4742-beeb-9392a58129f5 HTTP/1.1
User-Agent: example-user-agent/0.1
Host: dcdn.example
Accept: */*
Content-Type: application/cdni; ptype=ci-trigger.v2
Content-Length: 27

{
  "state": "cancelled"
}

RESPONSE:

HTTP/1.1 200 OK
Date: Sun, 27 Oct 2024 08:48:15 GMT
Content-Length: 523
Content-Type: application/cdni; ptype=ci-trigger.v2
Server: example-server/0.1

{
  "ctime": 1730119695,
  "etime": 1730119755,
  "mtime": 1730119695,
  "state": "cancelling",
  "action": "preposition",

  "specs": [
    {
      "trigger-subject": "content",
      "cit-spec-type": "urls",
      "cit-spec-value": {
        "urls": [
          "https://www.example.com/d/e/f/1",
          "https://www.example.com/d/e/f/2",
          "https://www.example.com/d/e/f/3",
          "https://www.example.com/d/e/f/4"
        ]
      }
    }
  ],
  "labels": [
    "type=video"
  ]
}

REQUEST:

DELETE /cit/3f2d259d-a980-4742-beeb-9392a58129f5 HTTP/1.1
User-Agent: example-user-agent/0.1
Host: dcdn.example
Accept: */*

RESPONSE:

HTTP/1.1 204 No Content
Date: Sun, 27 Oct 2024 08:48:16 GMT
Content-Length: 0
Content-Type: text/html; charset=UTF-8
Server: example-server/0.1

6.3. Examining Trigger Status

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

REQUEST:

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

RESPONSE:

HTTP/1.1 200 OK
Content-Length: 341
Expires: Sun, 27 Oct 2024 08:49:18 GMT
Server: example-server/0.1
ETag: "936094426920308378"
Last-Modified: Sun, 27 Oct 2024 08:40:17 GMT
Cache-Control: max-age=60
Date: Sun, 27 Oct 2024 08:48:18 GMT
Content-Type: application/cdni; ptype=ci-trigger-index.v2

{
  "cdn-id": "AS64496:0",
  "staleresourcetime": 86400,
  "collections": [
    {
      "uri": "/cit/all"
    },
    {
      "filter-type": "state",
      "filter-value": "pending",
      "uri": "/cit/state/pending"
    },
    {
      "filter-type": "state",
      "filter-value": "active",
      "uri": "/cit/state/active"
    },
    {
      "filter-type": "state",
      "filter-value": "complete",
      "uri": "/cit/state/complete"
    },
    {
      "filter-type": "state",
      "filter-value": "processed",
      "uri": "/cit/state/processed"
    },
    {
      "filter-type": "state",
      "filter-value": "failed",
      "uri": "/cit/state/failed"
    },
    {
      "filter-type": "state",
      "filter-value": "cancelling",
      "uri": "/cit/state/cancelling"
    },
    {
      "filter-type": "state",
      "filter-value": "cancelled",
      "uri": "/cit/state/cancelled"
    },
    {
      "filter-type": "label",
      "filter-value": "type=video",
      "uri": "/cit/labels/type=video"
    }
  ]
}

REQUEST:

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

RESPONSE:

HTTP/1.1 200 OK
Content-Length: 123
Expires: Sun, 27 Oct 2024 08:49:19 GMT
Server: example-server/0.1
ETag: "4331492443626270781"
Last-Modified: Sun, 27 Oct 2024 08:40:17 GMT
Cache-Control: max-age=60
Date: Sun, 27 Oct 2024 08:48:19 GMT
Content-Type: application/cdni; ptype=ci-trigger-collection.v2
327df5b8-1df8-4cff-92f8-fda27774c171
{
  "trigger-urls": [
    "https://dcdn.example/cit/327df5b8-1df8-4cff-92f8-fda27774c171"
  ]
}

REQUEST:

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

RESPONSE:

HTTP/1.1 200 OK
Content-Length: 51
Expires: Sun, 27 Oct 2024 08:49:20 GMT
Server: example-server/0.1
ETag: "7958041393922269003"
Last-Modified: Sun, 27 Oct 2024 08:48:17 GMT
Cache-Control: max-age=60
Date: Sun, 27 Oct 2024 08:48:20 GMT
Content-Type: application/cdni; ptype=ci-trigger-collection.v2

{
  "trigger-urls": []
}

REQUEST:

GET /cit/state/failed HTTP/1.1
User-Agent: example-user-agent/0.1
Host: dcdn.example
Accept: */*

RESPONSE:

HTTP/1.1 200 OK
Content-Length: 191
Expires: Sun, 27 Oct 2024 08:49:21 GMT
Server: example-server/0.1
ETag: "4331492443626270781"
Last-Modified: Sun, 27 Oct 2024 08:48:13 GMT
Cache-Control: max-age=60
Date: Sun, 27 Oct 2024 08:48:19 GMT
Content-Type: application/cdni; ptype=ci-trigger-collection.v2

{
  "trigger-urls": [
    "https://dcdn.example/cit/991b9fb9-d0be-4d05-be06-64c0e5c5a5f9"
    "https://dcdn.example/cit/86633e6e-d2da-4185-a285-b3d087a5d711"
  ]
}

REQUEST:

GET /cit/327df5b8-1df8-4cff-92f8-fda27774c171 HTTP/1.1
User-Agent: example-user-agent/0.1
Host: dcdn.example
Accept: */*

RESPONSE:

HTTP/1.1 200 OK
Content-Length: 545
Expires: Sun, 27 Oct 2024 08:49:22 GMT
Server: example-server/0.1
ETag: "554385204989405469"
Last-Modified: Sun, 27 Oct 2024 08:48:17 GMT
Cache-Control: max-age=60
Date: Sun, 27 Oct 2024 08:48:22 GMT
Content-Type: application/cdni; ptype=ci-trigger.v2

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

REQUEST:

GET /cit/state/pending HTTP/1.1
User-Agent: example-user-agent/0.1
Host: dcdn.example
Accept: */*
If-None-Match: "4331492443626270781"
If-Modified-Since: Sun, 27 Oct 2024 08:40:23 GMT

RESPONSE:
HTTP/1.1 304 Not Modified
Content-Length: 0
Expires: Sun, 27 Oct 2024 08:49:21 GMT
Server: example-server/0.1
ETag: "4331492443626270781"
Last-Modified: Sun, 27 Oct 2024 08:48:17 GMT
Cache-Control: max-age=60
Date: Sun, 27 Oct 2024 08:48:23 GMT
Content-Type: application/cdni; ptype=ci-trigger-collection.v2

REQUEST:

GET /cit/327df5b8-1df8-4cff-92f8-fda27774c171 HTTP/1.1
User-Agent: example-user-agent/0.1
Host: dcdn.example
Accept: */*
If-None-Match: "6990548174277557683"
If-Modified-Since: Sun, 27 Oct 2024 08:49:10 GMT

RESPONSE:

HTTP/1.1 304 Not Modified
Content-Length: 0
Expires: Sun, 27 Oct 2024 08:49:24 GMT
Server: example-server/0.1
ETag: "554385204989405469"
Last-Modified: Sun, 27 Oct 2024 08:48:17 GMT
Cache-Control: max-age=60
Date: Sun, 27 Oct 2024 08:48:24 GMT
Content-Type: application/cdni; ptype=ci-trigger.v2

REQUEST:

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

RESPONSE:

HTTP/1.1 200 OK
Content-Length: 51
Expires: Sun, 27 Oct 2024 08:49:25 GMT
Server: example-server/0.1
ETag: "1337503181677633762"
Last-Modified: Sun, 27 Oct 2024 08:48:17 GMT
Cache-Control: max-age=60
Date: Sun, 27 Oct 2024 08:48:25 GMT
Content-Type: application/cdni; ptype=ci-trigger-collection.v2

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

REQUEST:

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

RESPONSE:

HTTP/1.1 200 OK
Content-Length: 193
Expires: Sun, 27 Oct 2024 08:49:26 GMT
Server: example-server/0.1
ETag: "4481489539378529796"
Last-Modified: Sun, 27 Oct 2024 08:48:17 GMT
Cache-Control: max-age=60
Date: Sun, 27 Oct 2024 08:48:26 GMT
Content-Type: application/cdni; ptype=ci-trigger-collection.v2

{
  "staleresourcetime": 86400,
  "triggers": [
    "https://dcdn.example/cit/327df5b8-1df8-4cff-92f8-fda27774c171"
  ]
}

6.4. Extensions

REQUEST:

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

{
  "action": "purge",
  "specs": [{
    "trigger-subject": "content",
    "cit-spec-type": "content-objectlist",
    "cit-spec-value": {
      "objects": [{
        "href": "https://www.example.com/hls/1a910c8e/index.m3u8",
        "type": "hls"
      }]
     }
  }]
}

RESPONSE:

HTTP/1.1 201 Created
Date: Sun, 27 Oct 2024 08:48:27 GMT
Content-Length: 385
Content-Type: application/cdni; ptype=ci-trigger.v2
Location: https://dcdn.example/cit/564cc45e-9099-4a37-b95e-60342f2647ba
Server: example-server/0.1

{
  "ctime": 1730119707,
  "etime": 1730119767,
  "mtime": 1730119707,
  "state": "pending",
  "action": "purge",
  "specs": [{
    "trigger-subject": "content",
    "cit-spec-type": "content-objectlist",
    "cit-spec-value": {
      "objects": [{
        "href": "https://www.example.com/hls/1a910c8e/index.m3u8",
        "type": "hls"
      }]
     }
  }]
}


REQUEST:

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

{
  "action": "preposition",
  "specs": [{
    "trigger-subject": "content",
    "cit-spec-type": "content-objectlist",
    "cit-spec-value": {
      "objects": [{
        "href": "https://www.example.com/hls/09000b67/index.m3u8",
        "type": "hls"
      }]
     }
  }],
  "extensions": [
    "cit-extension-type": "execution-policy",
    "cit-extension-value": {
      "depends": [
        "https://dcdn.example/cit/564cc45e-9099-4a37-b95e-60342f2647ba"
      ]
    }
  ]
}


RESPONSE:

HTTP/1.1 201 Created
Date: Sun, 27 Oct 2024 08:48:28 GMT
Content-Length: 467
Content-Type: application/cdni; ptype=ci-trigger.v2
Location: https://dcdn.example/cit/f6dde35f-703f-49e9-bb80-4964dff3bca5
Server: example-server/0.1

{
  "ctime": 1730119708,
  "etime": 1730119768,
  "mtime": 1730119708,
  "state": "pending",
  "action": "preposition",
  "specs": [{
    "trigger-subject": "content",
    "cit-spec-type": "content-objectlist",
    "cit-spec-value": {
      "objects": [{
        "href": "https://www.example.com/hls/09000b67/index.m3u8",
        "type": "hls"
      }]
     }
  }],
  "extensions": [
    "cit-extension-type": "execution-policy",
    "cit-extension-value": {
      "depends": [
        "https://dcdn.example/cit/564cc45e-9099-4a37-b95e-60342f2647ba"
      ]
    }
  ]
}

REQUEST:

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

{
  "action": "preposition",
  "specs": [{
    "trigger-subject": "content",
    "cit-spec-type": "content-objectlist",
    "cit-spec-value": {
      "objects": [{
        "href": "https://www.example.com/hls/b89d49df/index.m3u8",
        "type": "hls"
      }]
     }
  }],
  "extensions": [
    "cit-extension-type": "execution-policy",
    "cit-extension-value": { "priority": 100 }
   ]
}

RESPONSE:

HTTP/1.1 201 Created
Date: Sun, 27 Oct 2024 08:48:30 GMT
Content-Length: 526
Content-Type: application/cdni; ptype=ci-trigger.v2
Location: https://dcdn.example/cit/e5483c4a-7c8e-4820-91c8-3c0a9f2edba8
Server: example-server/0.1

{
  "ctime": 1730119710,
  "etime": 1730119770,
  "mtime": 1730119710,
  "state": "pending",
  "action": "preposition",
  "specs": [{
    "trigger-subject": "content",
    "cit-spec-type": "content-objectlist",
    "cit-spec-value": {
      "objects": [{
        "href": "https://www.example.com/hls/b89d49df/index.m3u8",
        "type": "hls"
      }]
     }
  }],
  "extensions": [
    "cit-extension-type": "execution-policy",
    "cit-extension-value": { "priority": 100 }
   ]
}

REQUEST:

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

{
  "action": "preposition",
  "specs": [{
    "trigger-subject": "content",
    "cit-spec-type": "content-objectlist",
    "cit-spec-value": {
      "objects": [{
        "href": "https://www.example.com/hls/title/index.m3u8",
        "type": "hls"
      }]
    }
  }],
  "extensions": [
    {
      "cit-extension-type": "location-policy",
      "cit-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
    },
    {
      "cit-extension-type": "time-policy",
      "cit-extension-value": {
        "unix-time-window": {
          "start": 1730174400,
          "end": 1730260800
        }
      },
      "mandatory-to-enforce": true,
      "safe-to-redistribute": true
    }
  ],
  "cdn-path": [ "AS64496:0" ]
}

RESPONSE:

HTTP/1.1 201 Created
Date: Sun, 27 Oct 2024 08:48:31 GMT
Content-Length: 2595
Content-Type: application/cdni; ptype=ci-trigger.v2
Location: https://dcdn.example/cit/bcca1cde-ddf0-47db-b859-6a2c043baaa9
Server: example-server/0.1

{
  "errors": [
    {
      "extensions": [{
        "cit-extension-type": "location-policy",
        "cit-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": [{
        "cit-extension-type": "time-policy",
        "cit-extension-value": {
          "unix-time-window": {
            "start": 1730174400,
            "end": 1730260800
          }
        },
        "mandatory-to-enforce": true,
        "safe-to-redistribute": true
      }],
      "description": "unrecognized extension type",
      "error": "eextension",
      "cdn": "AS64501:0"
    }
  ],
  "ctime": 1730119691,
  "etime": 1730119691,
  "mtime": 1730119691,
  "state": "failed",
  "action": "preposition",
  "specs": [{
    "trigger-subject": "content",
    "cit-spec-type": "content-objectlist",
    "cit-spec-value": {
      "objects": [{
        "href": "https://www.example.com/hls/title/index.m3u8",
        "type": "hls"
      }]
    }
  }],
  "extensions": [
    {
      "cit-extension-type": "location-policy",
      "cit-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
    },
    {
      "cit-extension-type": "time-policy",
      "cit-extension-value": {
        "unix-time-window": {
          "start": 1730174400,
          "end": 1730260800
        }
      },
      "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 consist of the names and descriptions listed in Section 4.1.2, with this document serving as their 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 consist of the names and descriptions listed in Section 4.1.2.2, with this document serving as their 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.4.2.1, used by the Object List object.¶

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

The initial contents of the "CDNI CI/T Object List Types" registry consist of the names and descriptions listed in Section 4.4.2.1, with this document serving as their 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.8, used by the trigger spec object.¶

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

The initial contents of the "CDNI CI/T Trigger Extensions" registry consist of the names and descriptions listed in Section 2.8, with this document serving as their 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, the definitions of the Error Codes from [RFC8007] are without change. Additionally, the IANA is requested to register three additional error codes, "espec", "esubject", and "eextension", with the specification as defined in Section 4.1.6.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.4.1, used by Section 4.1.2.4, Section 4.1.2.6, Section 4.1.2.7, and Section 4.1.2.8.¶

The initial contents of the "CDNI CI/T Trigger Extensions" registry consist of the names and descriptions listed in Section 4.4.1, with this document serving as their 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 the dCDN and the uCDN to authenticate each other using TLS client authentication and TLS server authentication.¶

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

• The dCDN and the 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 the dCDNs or the 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.9 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 the dCDN. A malicious or faulty uCDN could use this to generate unnecessary load in the dCDN. The 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. The dCDN MUST ensure that it only exposes CI/T data related to the uCDN to clients it has authenticated as belonging to that uCDN.¶