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. Timing of Triggered Activity

Timing of the execution of CI/T Commands is under dCDN's control, including its start time and pacing of the activity in the network. Instructions regarding this timing may be included in the trigger using one of the Trigger Extension Objects defined in Section 8, such as Section 8.3 and Section 8.2.¶

CI/T "invalidate" and "purge" commands MUST be applied to all data acquired before the command was accepted by dCDN. dCDN SHOULD NOT apply CI/T "invalidate" and "purge" commands to data acquired after the CI/T Command was accepted, but this may not always be achievable, so uCDN cannot count on that.¶

If uCDN wishes to invalidate or purge content and then immediately pre-position replacement content at the same URLs, it SHOULD ensure that dCDN has completed the invalidate/purge before initiating the pre-positioning. Otherwise, there is a risk that the dCDN pre-positions the new content, then immediately invalidates or purges it (as a result of the two uCDN requests running in parallel).¶

Because the CI/T Command timing is under dCDN's control, dCDN implementation can choose whether to apply CI/T "invalidate" and "purge" commands to content acquisition that has already started when the command is received.¶

2.2. Scope of Triggered Activity

Each CI/T Command can operate on multiple metadata and content elements, usually referred to by their URLs. These elements are targeted by specifying both their subject (i.e., "metadata" or "content") as well as specification method (e.g., URL Regexes) and value.¶

Multiple representations of an HTTP resource may share the same URL. CI/T Trigger Commands that invalidate or purge metadata or content apply to all resource representations with matching URLs.¶

2.3. Trigger Results

Possible states for a Trigger Status Resource are defined in Section 6.2.6.¶

The CI/T Trigger Command MUST NOT be reported as "complete" until all operations have been completed successfully. The reasons for failure, and URLs or patterns affected, SHOULD be enumerated in the Trigger Status Resource. For more details, see Section 5.8.¶

If dCDN is also acting as uCDN in a cascade, it MUST forward CI/T Commands to any dCDNs that may be affected. The CI/T Trigger Command MUST NOT be reported as "complete" in a CDN until it is "complete" in all of its dCDNs. If a CI/T Trigger Command is reported as "processed" in any dCDN, intermediate CDNs MUST NOT report "complete"; instead, they MUST also report "processed". A CI/T Command MAY be reported as "failed" as soon as it fails in a CDN or any of its dCDNs. A cancelled CI/T Trigger Command MUST be reported as "cancelling" until it has been reported as "cancelled", "complete", or "failed" by all dCDNs in a cascade.¶

3.1. Trigger Action

Trigger Action is used in a Trigger Specification to describe trigger actions. It was initially referred to in [RFC8007] as "Trigger Type".¶

All trigger actions MUST be registered in the IANA "CDNI CI/T Trigger Types" registry (see Section 11.2).¶

dCDN receiving a request containing a trigger action that it does not recognize or does not support MUST reject the request by creating a Trigger Status Resource with "failed" status and the "errors" array containing an Error.v2 Description with error "eunsupported" (see Section 6.2.7).¶

The following trigger actions are defined by this document:¶

3.2. Trigger Spec

The CDNI Control Interface / Triggers 1st edition [RFC8007] defines a set of properties and objects used by the trigger commands in order to specify the targets upon which the trigger is applied. This document modifies the trigger interface objects so it has a list of trigger specs. Such structure improves the interface's extensibility and flexibility. Furthermore, the document defines a generic trigger spec object that acts as a wrapper for managing individual CDNI trigger specs in an opaque manner, allowing future extension of the interface.¶

All trigger specs MUST be registered in the IANA "CDNI CI/T Trigger Specs" registry (see Section 11.3).¶

dCDN receiving a request containing a trigger spec that it does not recognize or does not support MUST reject the request by creating a Trigger Status Resource with "failed" status and the "errors" array containing an Error.v2 Description with error "espec" (see Section 6.2.7).¶

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

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

• Pre-position with cache location policy¶

• Purge content with cache location policy¶

• Pre-position at a specific time¶

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

4.1. Filtered Collections by Trigger Status

dCDN MAY provide filtered collections per Trigger Status (Section 6.2.6). If implemented, dCDN SHOULD provide a separate filtered collection for every Trigger Status, and advertise these collections in the collection of all Trigger Resources.¶

4.2. Filtered Collections by Trigger Label

dCDN MAY provide filtered collections per Trigger Label (Section 6.2.10), as specified by uCDN in Section 6.2.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.¶

5.1. Creating Triggers

To issue a CI/T Command, uCDN makes an HTTP POST to dCDN's collection of all of uCDN's Trigger Status Resources. The request body of that POST is a CI/T Command, as described in Section 6.1.1.¶

dCDN validates the CI/T Command. If the command 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 Status Resource or create a "failed" Trigger Status Resource containing an appropriate Error.v2 Description.¶

When a CI/T Trigger Command is accepted, dCDN MUST create a new Trigger Status Resource that will convey a specification of the CI/T Command and its current status. The HTTP response to uCDN MUST have status code 201 and MUST convey the URI of the Trigger Status Resource in the Location header field [RFC9110]. The HTTP response SHOULD include the content of the newly created Trigger Status Resource. This is particularly important in cases where the CI/T Trigger Command has been completed immediately.¶

Once a Trigger Status Resource has been created, dCDN MUST NOT reuse its URI, even after that Trigger Status Resource has been removed.¶

dCDN SHOULD track and report on the progress of CI/T Trigger Commands using a Trigger Status Resource (Section 6.1.3). If the dCDN is not able to do that, it MUST indicate that it has accepted the request but will not be providing further status updates. To do this, it sets the status of the Trigger Status Resource to "processed". In this case, CI/T processing should continue as for a "complete" request, so the Trigger Status Resource MUST be added to dCDN's collection of complete Trigger Status Resources. dCDN SHOULD also provide an estimated completion time for the request by using the "etime" property of the Trigger Status Resource. This will allow uCDN to schedule pre-positioning after an earlier delete of the same URLs is expected to have finished.¶

If dCDN can track the execution of CI/T Commands and a CI/T Command is queued by dCDN for later action, the "status" property of the Trigger Status Resource MUST be "pending". Once processing has started, the status MUST be "active". Finally, once the CI/T Command is complete, the status MUST be set to "complete" or "failed".¶

A CI/T Trigger Command may result in no activity in dCDN if, for example, it is an "invalidate" or "purge" request for datdCDN has not yet acquired, or a "preposition" request for data that it has already acquired and that is still valid. In this case, the status of the Trigger Status Resource MUST be "processed" or "complete", and the Trigger Status Resource MUST be added to dCDN's collection of complete Trigger Status Resources.¶

Once created, Trigger Status Resources can be cancelled or deleted by uCDN, but not modified. dCDN MUST reject PUT and POST requests from uCDN to Trigger Status Resources by responding with an appropriate HTTP status code -- for example, 405 ("Method Not Allowed").¶

5.2. Modifying Triggers

uCDN can request modification of an existing Trigger Command by issuing CI/T Modify Trigger Command. Allowed modifications include an update of the Trigger Command specification and change of state.¶

dCDN MAY accept the request to update specification when the trigger has "pending" status, i.e. the trigger has not been acted upon yet.¶

dCDN MAY accept the trigger status change request as long as:¶

• the requested state is "cancelled"¶

• the trigger has either "pending" or "active" status before the request¶

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 Command is to be executed.¶

dCDN MUST respond to the CI/T Modify Trigger Command appropriately. For example, 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 Status Resource does not exist, 409 ("Conflict") when the Trigger Status Resource is in a state that doesn't allow the requested modification, 501 ("Not Implemented") if modification is not supported by dCDN or an appropriate 4xx HTTP error code in case of a malformed request.¶

5.3. Checking Status

uCDN has two ways to check the progress of CI/T Commands it has issued to dCDN, as described in Sections Section 5.3.1 and Section 5.3.2.¶

To allow uCDN to check for changes in the status of a Trigger Status Resource or collection of Trigger Status Resources without refetching the whole resource or collection, dCDN SHOULD include entity-tags (ETags) for uCDN to use as cache validators, as defined in [RFC9110].¶

dCDN SHOULD use the cache control headers for responses to GETs for Trigger Status Resources and Collections to indicate the frequency at which it recommends that uCDN should poll for change.¶

5.4. Cancelling Triggers

uCDN can request cancellation of a trigger by issuing CI/T Modify Trigger Command to the specific trigger's Trigger Status Resource URL and setting the "desired-status" field to "cancelled".¶

dCDN is required to accept and respond to the CI/T Modify Command, but the actual cancellation of a CI/T Trigger Command is optional-to-implement.¶

dCDN MUST respond to the CI/T Modify Command appropriately -- for example, with HTTP status code 200 ("OK") if the cancellation has been processed and the CI/T Command is inactive, 202 ("Accepted") if the command has been accepted but the CI/T Command remains active, 404 ("Not Found") when the Trigger Status Resource does not exist, or 501 ("Not Implemented") if cancellation is not supported by dCDN.¶

If cancellation of a "pending" Trigger Status Resource is accepted by dCDN, dCDN SHOULD NOT start the processing of that activity. Requesting a cancellation of a trigger using a CI/T Modify Command for a "pending" Trigger Status Resource 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 Status Resource is accepted by dCDN, dCDN SHOULD stop processing the CI/T Command. However, as with the cancellation of a "pending" CI/T Command, dCDN does not guarantee this.¶

If the CI/T Command cannot be stopped immediately, the status in the corresponding Trigger Status Resource MUST be set to "cancelling", and the Trigger Status Resource MUST remain in the collection of Trigger Status Resources for active CI/T Commands. If processing is stopped before normal completion, the status value in the Trigger Status Resource MUST be set to "cancelled", and the Trigger Status Resource MUST be included in the collection of failed CI/T Trigger Commands.¶

Cancellation of a "complete" or "failed" Trigger Status Resource requires no processing in dCDN. Its status MUST NOT be changed to "cancelled".¶

5.5. Deleting Triggers

uCDN can delete Trigger Status Resources at any time using the HTTP DELETE method. As defined in the CDNI Control Interface / Triggers 1st edition [RFC8007], the effect is similar to cancellation, but no Trigger Status Resource remains afterwards. Note that in cases where the trigger's status before the deletion is not a terminal status (i.e., "completed", "failed" or "cancelled"), uCDN would not have the ability to further monitor the cancellation process and the final status of the trigger. For this reason, it is recommended that the trigger is cancelled (see Section 5.4) before trigger deletion and deletion is only used on triggers with a terminal status.¶

Once deleted, the references to a Trigger Status Resource MUST be removed from all Trigger Status Resource collections. Subsequent requests to GET the deleted Trigger Status Resource SHOULD be rejected by dCDN with an HTTP error.¶

If a "pending" Trigger Status Resource is deleted, dCDN SHOULD NOT start the processing of that activity. Deleting a "pending" Trigger Status Resource does not, however, guarantee that it 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.¶

If an "active" or "processed" Trigger Status Resource is deleted, the dCDN SHOULD stop processing the CI/T Command. However, as with deletion of a "pending" Trigger Status Resource, dCDN does not guarantee this.¶

Deletion of a "complete" or "failed" Trigger Status Resource requires no processing in dCDN other than deletion of the Trigger Status Resource.¶

5.6. Expiry of Trigger Status Resources

dCDN can choose to automatically delete Trigger Status Resources sometime after they become "complete", "processed", "failed", or "cancelled". In this case, dCDN will remove the Trigger Status Resource and respond to subsequent requests for it with an HTTP error.¶

If dCDN does remove Trigger Status Resources automatically, it MUST report the length of time after which it will do so, using a property of the collection of all Trigger Status Resources. It is RECOMMENDED that Trigger Status Resources are not automatically deleted by dCDN for at least 24 hours after they become "complete", "processed", "failed", or "cancelled".¶

To ensure that it can get the status of its Trigger Status Resources for completed and failed CI/T Commands, it is RECOMMENDED that uCDN polling interval is less than the time after which records for completed activity will be deleted.¶

5.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 CI/T Commands 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) to uniquely identify itself. In every CI/T Command it originates 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 CI/T Commands, dCDN MUST check the cdn-path and reject any CI/T Command that already contains its own CDN PID in the cdn-path. Transit CDNs MUST check the cdn-path and not cascade the CI/T Command to dCDNs that are already listed in the cdn-path.¶

The CDN PID consists of the two characters "AS" followed by the CDN provider's Autonomous System number [RFC1930], then a colon (":") and an additional qualifier that is used to guarantee uniqueness in case a particular AS has multiple independent CDNs deployed -- for example, "AS64496:0".¶

If the CDN provider has multiple ASes, the same AS number SHOULD be used in all messages from that CDN provider, unless there are multiple distinct CDNs.¶

If the CDNI Request Routing Redirection interface (RI) described in [RFC7975] is implemented by dCDN, the CI/T interface and the RI SHOULD use the same CDN PID.¶

5.8. Error Handling

dCDN can signal rejection of a CI/T Command using HTTP status codes -- for example, 400 ("Bad Request") if the request is malformed, or 403 ("Forbidden") or 404 ("Not Found") if uCDN does not have permission to issue CI/T Commands or it is trying to act on another CDN's data.¶

If any part of the CI/T Trigger Command 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 Status Resource will be used to enumerate which actions failed and the reasons for failure, and can be present while the Trigger Status Resource is still "pending" or "active" if the CI/T Trigger Command is still running for some URLs or patterns in the Trigger Specification.¶

Once a request has been accepted, processing errors are reported in the Trigger Status Resource 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 CI/T Trigger Command is offline in the dCDN or dCDN is unable to pass a CI/T Command on to any of its cascaded dCDNs:¶

• If the CI/T Command 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 Status Resource in state "pending" or "active" until either the CI/T Command 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 Status Resource     [ ]
 |                             [ ]<---------------------------[ ]
 |                              |                              |
 .                              .                              .
 .                              .                              .
 .                              .                              .
 | (10) GET                     |                              |
 | https://dcdn-b.example.com   |                              |
 | /triggers/uCDN-A/123         |                              |
[ ]--------------------------->[ ]                             |
 |                             [ ]                             |
 | (11) HTTP 200               [ ]                             |
 | Trigger Status Resource     [ ]                             |
[ ]<---------------------------[ ]                             |

6.1. CI/T Objects

The top-level objects defined by the CI/T interface are described in this section.¶

The encoding of values used by these objects is described in Section 6.2.¶

6.2. Properties of CI/T Objects

This section defines the values that can appear in the top-level objects described in Section 6.1 and their encodings.¶

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

}

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

{
  "error": "econtent",
  "description": "Failed to parse HLS object list",
  "specs": [
    {
      "trigger-subject": "content",
      "generic-trigger-spec-type": "content-objectlist",
      "generic-trigger-spec-value": {
        "href": "https://www.example.com/hls/title/index.m3u8",
        "type": "hls"
      }
    }
   ],
  "objects": {
     "href": "https://dcdn.com/triggers/2a544cd9/objects",
     "type": "json"
  }
  "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":
            <type of this erroneous trigger extension object>,
          "generic-trigger-extension-value": {
            <properties of this erroneous trigger extension object>
          }
        }
      ],
      "cdn": "AS64500:0"
    }
  ]
}

[
  {
    "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\n
http://example.com/hls/35cdc008/low/index.m3u8\n
#EXT-X-STREAM-INF:BANDWIDTH=240000,RESOLUTION=416x234\n
http://example.com/hls/35cdc008/lo_mid/index.m3u8\n
#EXT-X-STREAM-INF:BANDWIDTH=440000,RESOLUTION=416x234\n
http://example.com/hls/35cdc008/hi_mid/index.m3u8\n
#EXT-X-STREAM-INF:BANDWIDTH=640000,RESOLUTION=640x360\n
http://example.com/hls/35cdc008/high/index.m3u8\n
#EXT-X-STREAM-INF:BANDWIDTH=64000\n
http://example.com/hls/35cdc008/audio/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
  },
]

7.1. URLs Spec

The "urls" spec type allows uCDN to manage uCDN content or metadata objects held by dCDN based on the objects' URLs.¶

The URLs spec is encoded as a JSON object containing the following name/value pairs:¶

• Name: urls

  Description: An array of URLs over which the trigger MUST be executed.¶

  Value: A JSON array of URLs represented as JSON strings.¶

  Mandatory: Yes.¶

  Name: url-type

  Description: Type of URL used.¶

  Value: URL Type as defined in Section 6.2.8.¶

  Mandatory: No. When omitted or empty, "published" URL type is assumed.¶

Below is an example of a JSON serialized URLs spec object, matching the metadata at metadata.example.com/a/b/c.¶

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

7.2. CCIDs Spec

The "ccids" spec type allows uCDN to specify the Content Collection IDentifier (CCID) of content to which the trigger applies. The CCID is a grouping of content as defined by [RFC8006]. The "ccids" spec type is valid only for the content spec subject (see Section 3.2.1).¶

CCIDs spec is encoded as a JSON object containing the following name/value pairs:¶

• Name: ccids

  Description: An array of Content Collection IDentifiers over which the trigger MUST be executed.¶

  Value: A JSON array of strings, where each string is a Content Collection IDentifier.¶

  Mandatory: Yes.¶

7.3. URI Pattern Match Spec

The "uri-pattern-match" spec type allows uCDN to manage uCDN content or metadata objects held by dCDN based on the objects' URI pattern. The value is a UriPatternMatch object, as defined in Section 7.3.1.¶

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

7.4. URI Regex Match Spec

The "uri-regex-match" spec type allows uCDN to manage content or metadata objects held by dCDN based on the objects' URI regex.¶

"^(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
or
https://video.example.com/k/movie1/4/013.ts

7.5. Object List Spec

The "objectlist" spec type allows uCDN to manage content held by dCDN based on structured object lists. The Object List spec type is valid only for the content spec subject (see Section 3.2.1).¶

An object list is encoded as an ObjectList (Section 6.2.9) object.¶

8.1. LocationPolicy Extension

A content operation may be relevant for a specific geographical region or need to be excluded from a specific region. In this case, the trigger should be applied only to parts of the network that are either "included" or "not excluded" by the location policy. Note that the restrictions here are on the cache location rather than the client location.¶

The LocationPolicy object defines which CDN or cache locations for which the trigger command is relevant.¶

Example use cases:¶

• Pre-position: Certain contracts allow for pre-positioning or availability of contracts in all regions except for certain excluded regions in the world, including caches. For example, some content cannot ever knowingly touch servers in a specific country, including cached content. Therefore, these regions MUST be excluded from a pre-positioning operation.¶

• Purge: In certain cases, content may have been located on servers in regions where the content must not reside. In such cases, a purge operation to remove content specifically from that region is required.¶

Object specification:¶

• Name: locations

  Description: An Access List that allows or denies (blocks) the trigger execution per cache location.¶

  Value: Array of LocationRule objects (see Section 4.2.2.1 of [RFC8006]).¶

  Mandatory: Yes.¶

  Name: url-type

  Description: Type of URL used in the ObjectList(s).¶

  Value: URL Type as defined in Section 6.2.8.¶

  Mandatory: No. When omitted or empty, the "published" URL type is assumed.¶

If a location policy object is not listed within the trigger command, the default behavior is to execute the trigger in all available caches and locations of dCDN.¶

The trigger command is allowed, or denied, for a specific cache location according to the action of the first location whose footprint matches that cache's location. If two or more footprints overlap, the first footprint that matches against the cache's location determines the action a CDN MUST take. If the "locations" property is an empty list or if none of the listed footprints match the location of a specific cache location, then the result is equivalent to a "deny" action.¶

The following is an example of a JSON serialized generic trigger extension object containing a location policy object that allows the trigger execution in the US but blocks its execution in Canada:¶

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

8.2. TimePolicy Extension

uCDN may wish to perform content management operations on dCDN on a specific schedule. The TimePolicy extension allows uCDN to instruct dCDN to execute the trigger command in a desired time window. For example, a content provider that wishes to pre-populate a new episode at off-peak time so that it would be ready on caches at prime time when the episode is released for viewing. A scheduled operation enables uCDN to direct dCDN in what time frame to execute the trigger.¶

uCDN may wish to schedule a trigger such that dCDN will execute it in local time, as it is measured in each region. For example, uCDN may wish dCDN to pull the content at off-peak hours, between 2AM-4AM, however, as a CDN is distributed across multiple time zones, the UTC definition of 2AM depends on the actual location.¶

We define two alternatives for localized scheduling:¶

• Regional schedule: When used in conjunction with the Location Policy defined in Section 8.1, uCDN can trigger separate commands for different geographical regions, for each region using a different schedule. This allows uCDN to control the execution time per region.¶

• Local Time schedule: We introduce a "local time" version for Internet timestamps that follows the notation for local time as defined in Section 4.2.2 of [ISO8601]. When local time is used, that dCDN SHOULD execute the triggers at different absolute times, according to the local time of each execution location.¶

Object specification:¶

• Name: unix-time-window

  Description: A UNIX epoch time window in which the trigger SHOULD be executed.¶

  Value: TimeWindow object using UNIX epoch timestamps (see Section 4.2.3.2 of [RFC8006]).¶

  Mandatory: No, but exactly one of "unixEpochWindow" or "utcWindow" MUST be present.¶

• Name: utc-window

  Description: A UTC time window in which the trigger SHOULD be executed.¶

  Value: UTCWindow object as defined in Section 8.2.1.¶

  Mandatory: No, but exactly one of "unixEpochWindow" or "utcWindow" MUST be present.¶

If a time policy object is not listed within the trigger command, the default behavior is to execute the trigger in a time frame most suitable to dCDN taking under consideration other constraints and / or obligations.¶

Example of a JSON serialized generic trigger extension object containing a time policy object that schedules the trigger execution to a window between 09:00 01/01/2000 UTC and 17:00 01/01/2000 UTC, using the "unix-time-window" property:¶

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

8.3. ExecutionPolicy Extension

Unless specified otherwise, dCDN is at liberty to decide how to choose trigger commands for execution from all pending commands, whether to process trigger commands sequentially or in parallel, immediately upon acceptance, or with a delay in batches. uCDN may wish to control trigger processing in more detail, including the order of execution, dependencies, and concurrency.¶

Example use cases:¶

• Priority: uCDN may have multiple trigger commands in "pending" and/or "active" mode. For example, trigger commands with policy constraints, a large number of content objects affected, or other dCDN business logic may take a long time to execute. uCDN may wish to prescribe the order in which dCDN picks up its trigger commands for execution from the "pending" queue, by indicating a relative priority of each trigger. The priority would affect the selection of trigger commands specific to the requesting uCDN. dCDN may separately prioritize triggers from multiple uCDNs subject to its business logic. Multiple priority-related use cases exist:¶

  • uCDN needs to introduce an urgent "purge" or "invalidate" trigger into an existing queue of trigger commands to correct wrong versions of content objects published by it¶

  • uCDN needs to indicate which content objects should be prepositioned, purged or invalidated first, for example prepositioning newer released content before prepositioning updates to an existing catalog¶

• Pre-requisite: In some cases, uCDN may wish to indicate what trigger commands should be processed and completed before another trigger command is processed. For example, uCDN may want to rectify incorrectly published content by purging content objects and then prepositioning them again. In this case, uCDN may want the preposition trigger command to be processed only after the purge trigger command has been processed because concurrent processing of these triggers may cause the new version of these content objects to be purged. Alternatively, uCDN may wish to condition the execution of purge or invalidation triggers upon the completion or cancellation of long-running preposition triggers to avoid race conditions that would result from processing these in parallel. The prerequisite requirement implies that a previous trigger reaches one of the following states:¶

  • "complete" or "processed" for successful completion¶

  • "failed" for failed processing¶

  • "cancelled" for completion of cancellation¶

• Urgency: uCDN may wish to indicate that dCDN should process a trigger command without delay. This requirement is separate and additional to priority, as priority indicates the order in which triggers should be processed, yet does not prescribe how soon each trigger should be executed. dCDN MAY reject such requests for urgent processing using "ereject" error code. This can happen due to dCDN internal business logic (e.g. batch-driven purge and invalidation), or due to dependencies on other triggers that could not be completed by dCDN immediately. In such a case uCDN should either modify the request by removing prerequisites or cancel such pending triggers before re-trying the request.¶

uCDN may combine multiple options in the same trigger command. dCDN should consider the following when processing such commands:¶

• dCDN MUST reject triggers that are dependent on other pending triggers with lower priority to prevent deadlocks.¶

• When introducing an urgent trigger uCDN SHOULD indicate a priority that is equal to or higher than the highest priority among the pending triggers that belong to the same uCDN. dCDN MUST reject urgent triggers that have lower priority than other pending triggers of the same uCDN.¶

• dCDN MUST reject an urgent trigger that has pending triggers as its prerequisite. dCDN MAY reject an urgent trigger that has triggers in an "active" or "cancelling" state as its prerequisite, such as when such triggers are deemed to take a long time to complete or cancel.¶

When combining ExtensionPolicy with Section 8.2, TimePolicy governs the time window when the trigger can execute, while ExecutionPolicy controls the order of trigger execution within their respective windows. The following error conditions should be considered by dCDN:¶

• When a trigger is marked urgent, but its TimePolicy extension doesn't allow immediate processing, it should be rejected by dCDN.¶

• When a trigger has a TimePolicy extension and is also dependent on another trigger with a TimePolicy extension, that specifies an execution window (directly or via a chain of dependency) that doesn't start until after the depending trigger's execution window ends, such a trigger should be rejected.¶

The ExtensionPolicy extension is encoded as a JSON object containing the following name/value pairs:¶

• Name: priority

  Description: Relative weight of the trigger. When picking a trigger for execution from all pending triggers posted by each uCDN, dCDN MUST choose the trigger with the highest priority first.¶

  Value: Integer from -100 to 100.¶

  Mandatory: No. The value defaults to zero if omitted.¶

  Name: depends

  Description: Links to Trigger Status Resources that the current Trigger Command depends on. Indicates which triggers should fully finish processing before starting execution of the current trigger. The triggers need to be in one of the following states to be considered finished: "complete", "processed", "failed" or "cancelled".¶

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

  Mandatory: No. In case of a missing or an empty list, no dependencies are assumed.¶

  Name: urgent

  Description: Indicates whether the trigger should be immediately moved to the "active" state upon acceptance. In the absence of this flag, dCDN is at liberty to choose the time for trigger execution, e.g., batch processing.¶

  Value: Boolean.¶

  Mandatory: No. The default is to handle the Trigger Command as not urgent.¶

The following is an example of a JSON serialized generic extension trigger object containing an execution policy object that specifies trigger priority of 100, marks Trigger Command as urgent and makes the Trigger Command execution dependent on the completion of the previous Trigger Commands:¶

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

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

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

9.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 11.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 6.2.9.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 objects> ]
   }
 ]
}

9.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 6.2.8 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 attribtue, MUST be interpreted as no support for private URLs.¶

{
 "capabilities": [
   {
     "capability-type": "FCI.CITPrivateUrlType",
     "capability-value": {
       "private-url-type-support": true
     },
     "footprints": [ <Footprint objects> ]
   }
 ]
}

9.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 Trigger Status object¶

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

• "all-triggers" attribute in 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-status",
         "error-v2-description",
         "trigger-collection"
       ]
     },
     "footprints": [ <Footprint objects> ]
   }
 ]
}

10.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-command.create.v2
  Content-Length: 352

  {
      "trigger": {
         "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-status.v2
  Location: https://dcdn.example.com/triggers/0
  Server: example-server/0.1

  {
      "ctime": 1462351690,
      "etime": 1462351698,
      "mtime": 1462351690,
      "status": "pending",
      "trigger": {
         "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:

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

  {
    "trigger": {
      "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-status.v2
  Location: https://dcdn.example.com/triggers/1
  Server: example-server/0.1

  {
      "ctime": 1462351691,
      "etime": 1462351699,
      "mtime": 1462351691,
      "status": "pending",
      "trigger": {
         "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:

  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-command.create.v2
  {
    "trigger": {
      "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-status.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,
    "status": "failed",
    "trigger": { <content of trigger.v2 object from the command> }
  }

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-command.create.v2
  {
    "trigger": {
      "action": "preposition",
      "specs": [
        {
          "trigger-subject": "content",
          "generic-trigger-spec-type": "content-objectlist",
          "generic-trigger-spec-value": {
            "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-status.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": {
              "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,
    "status": "failed",
    "trigger": { <content of trigger.v2 object from the command> }
  }

10.2. Examining Trigger Status

Once Trigger Status Resources 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-status.v2

  {
      "ctime": 1462351690,
      "etime": 1462351698,
      "mtime": 1462351690,
      "status": "pending",
      "trigger": {
          "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-status.v2
  {
      "ctime": 1462351691,
      "etime": 1462351699,
      "mtime": 1462351691,
      "status": "pending",
      "trigger": {
          "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-status.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-command.create.v2
  {
    "trigger": {
      "action": "preposition",
      "specs": [
        {
          "trigger-subject": "content",
          "generic-trigger-spec-type": "content-objectlist",
          "generic-trigger-spec-value": {
            "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-status.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",
    "trigger": { <content of trigger.v2 object from the command> }
  }

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

11.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 3.1, reuses the definition of "trigger types" as defined in [RFC8007] as trigger actions, and provide their specifications, with no modification compared to [RFC8007].¶

11.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 3.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 3.2, with this document acting as the specification.¶

11.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 3.2.1, 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 3.2.1, with this document acting as the specification.¶

11.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 6.2.9.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 6.2.9.1, with this document acting as the specification.¶

11.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 3.3, 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 3.3, with this document acting as the specification.¶

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

11.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 6.2.8, used by Section 7.1, Section 7.3, Section 7.4 and Section 7.5.¶

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

12.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 CI/T Commands from, or reporting status 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.2.1 should be considered.¶

12.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 CI/T Commands, or by performing batch processing.¶

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