Subject: Re: [CDNi] Review of draft-ietf-cdni-control-triggers-02

From: Rob Murray <[email-masked]>
Date: Thu, 3 Jul 2014 18:38:21 +0000

Hi all,

Kevin, thank you for the review. All very good comments, sorry it took me so long to get to them.

Responses inline below, and I've posted an "03" version of the draft...

   http://datatracker.ietf.org/doc/draft-ietf-cdni-control-triggers/
   http://tools.ietf.org/html/draft-ietf-cdni-control-triggers-03 (eventually)

Most comments have been addressed, including a couple of earlier ones from Francois about broken formatting.

What I've not dealt with is the idea to separate trigger deletion and cancellation - in order to make it possible to check the status of a deleted trigger. It'd make the interface a little more complicated, and I'm not sure what status the dCDN could usefully report. (Also, I ran out of time for making edits!) Let's discuss further in Toronto.

Cheers,
Rob.

On 6 May 2014, at 23:15, Kevin Ma J <[email-masked]> wrote:

> Hi All,
> 
>  Per the chairs' request for a detailed review of the triggers draft,
>  I've compiled a list of comments below.
> 
> thanx.
> 
> --  Kevin J. Ma
> 
> comments:
> 
> - General: imo, an article in front of uCDN/dCDN (i.e., the uCDN/dCDN)
>           makes for easier reading.

Done.

> - General: There are quite a few lower case "must"s (17), "shall"s (14),
>           "should"s (7), and "may"s (36) in the document.  Are they all
>           intentionally non-normative? 

Hopefully sorted now, though I MAY have gone too far!

> - section 2: Should cancelling a trigger and removing a trigger status
>             be separated in some way?  Using DELETE for both means
>             that if I wanted to cancel a trigger, I would have no way
>             to get status on the cancelled trigger, since the status
>             resource would be removed at the same time, and delete
>             does not return a status, per the example in section 7.2.5

See above, it could be a good idea but it'd be good to talk it through a bit further (sorry I left this update too late to do it on the list before the deadline).

> - section 2/4.1: In step 2 of figure 1, it mentions authentication as
>                 does section 4.1, but section 7 and 9 provide no
>                 guidance on either the authentication mechanism or
>                 what precisely is being authenticated.  Presumably we
>                 are authenticating that it is a known uCDN making the
>                 request for metadata/content that is known to be owned
>                 by that uCDN?  Should we state that?
> 
>                 Do we have a suggestion (e.g., SSL client auth, HTTP
>                 basic/digest auth, etc.) for authentication method?

I've rewritten the Security Considerations section now (based on what's in the Logging draft, as agreed in London).

> - section 2.1: I found the wording of this sentance a little confusing.
> 
>    "If uCDN wishes to invalidate or purge content, then immediately
>     preposition replacement content at the same URLs, it must ensure the
>     dCDN has completed the invalidate/purge before initiating the
>     prepositioning.  If it fails to do that and the requests overlap, and
>     dCDN passes the triggers on to a further dCDN in a cascade, that CDN
>     may preposition content that has not yet been invalidated/purged in
>     its uCDN."
> 
>    Perhaps something like:
> 
>    "If uCDN wishes to invalidate or purge content, then immediately
>     preposition replacement content at the same URLs, it must ensure the
>     dCDN and all cascaded dCDNs have completed the invalidate/purge
>     before initiating the prepositioning, otherwise, a cascaded dCDN may
>     attempt to preposition content that has not yet been invalidated/purged
>     in its uCDN."

Done.

> 
> - section 3: I would break this into two sentances:
> 
>    "The dCDN must present a different set of Trigger Status Resources to
>     each interconnected uCDN, only Trigger Status Resources belonging to
>     a uCDN shall be visible to it."
> 
>    i.e.:
> 
>    "The dCDN must present a different set of Trigger Status Resources to
>     each interconnected uCDN.  Only Trigger Status Resources belonging to
>     a uCDN shall be visible to it."

Done (and reworded a bit).

> - section 3: This is the first mention of expiry.  Perhaps a reference
>             to Section 4.4?
> 
>    "This collection lists all
>     uCDN triggers that have been accepted by dCDN, and have not yet been
>     deleted by uCDN or expired and removed by dCDN."

Done.

> - section 4.1: These are the first mention of etime and mtime, perhaps
>               there should be a reference to Section 5.2, or some
>               type of explaination on what etime > mtime means.
> 
>               I am not sure about using of etime > mtime as an indicator.
>               If mtime < now and etime < now, but still etime > mtime,
>               it would seem to imply that the activity may be complete,
>               but I don't think that is the intent?
> 
>               Should there be some normative language stating that if
>               etime > mtime, the uCDN must update the status, and the
>               dCDN must update mtime = now and etime > mtime?
> 
>    "If dCDN is not able to track triggered activity, it MAY indicate that
>     it has undertaken to complete the activity but will not report
>     completion or any further errors.  To do this, it must set the
>     trigger status to "complete", with an estimated completion time in
>     the future ("etime" greater than "mtime")."

I got rid of that and added an extra state, "processed" - it's like "complete", but means the dCDN can't provide a success/fail result. (With a recommendation that an estimated completion time should be provided in that case.)

> - section 4.4: Why 24 hours?  Seems fast?
> 
>    "It
>     is recommended that Trigger Status Resources are automatically
>     deleted 24 hours after they become completed or failed."

I made it "not less than 24 hours".

> - section 4.4: comma after:
> 
>    "If any part of the trigger request fails, "
> 
>               comma before:
> 
>    ", if the trigger is still running for some URLs
>     or Patterns in the trigger request."
> 
>               perhaps clarify "cascaded" dCDNs:
> 
>    "pass a trigger request on to any of its affected cascaded dCDNs"

Done.

> - section 5.2: AbsoluteTime is a Unix Epoch, so should be UTC.
>               I found the phrase "Time is local to dCDN" confusing as
>               I first assumed "local" was referencing timezone, but I
>               think "local" is just related to unsynchronized clocks?
>               Perhaps: "Time is determined by the dCDN"?

Done.

> - section 5.4: links is a "List of Relationships".  Why not just URLs?
>               If the trigger collection can only reference trigger
>               statuses, then why does it need typed relationships?
>               The use of a relationship here seems overly complex?
> 
>               Is relationship standard JSON terminology?  Should there
>               be a reference to the acknowledged work of Mike Kelly?

Yes, you're right. It had all got too complicated and bloated. So it's just a list of URLs now, I got rid of all that JSON relationship stuff.

> - section 6: There is a note about MI dependency.
>             Is it just for PatternMatch?

It was, but the dependency wasn't necessary so I've got rid of it.

> - section 6.1.6: "ralationship" -> "relationship"

Fixed.

> - section 6.1.6/6.1.7: I think it would be helpful to define the
>                       Relationship and Link objects the same way as
>                       all the other JSON objects, e.g.:
> 
>                       How are the keys in the _links dictionary
>                       determined?  And how is their meaning known?
>                       The key "self" seems to have a specific meaning?
>                       It is essentially a reserved keyword?  Are there
>                       other reserved keywords (e.g., "Trigger"), and
>                       do they have to be registered somewhere?
> 
>    Relationship:
>      Key: _links
>      Description: List of related objects?
>      Type: Array of LinkUnions
>      Mandatory: Yes
> 
>    LinkUnion:
>      Key: ???
>      Description: List of related objects?
>      Type: Array of LinkUnions
>      Mandatory: No.
> 
>      Key: ???
>      Description: related objects?
>      Type: Link
>      Mandatory: No.
> 
>    Link:
>      Key: href
>      Description: URI of the addressable object being referenced
>      Type: URL
>      Mandatory: Yes
> 
>      Key: type
>      Description: Type of the referenced object
>      Type: MIME Media Type
>      Mandatory: No

I did that - then decided to get rid of it all, as above. It was only used in the collections, and they're now just lists of links.

> - section 7: There are no examples with "base" or "links".  I have an
>             idea of how "base" might be used, but I don't know what
>             the purpoes of "links" is.  Can we add an example?
> 
>             "URLs are under control" -> "URLs are under the control"

"links" has gone.

> - section 7.2.1/7.2.2: I don't know where the key "Trigger" came from?
>                       Is it derived from some known object, or is it
>                       randomly selected (and somehow registered)?

In the "01" draft it was the "relationship type", and I'd not documented the change properly. But it's gone now, just a list of URLs.

> - section 7.2.5: Would there be value in returning the status on delete?

Probably a good idea. Let's wrap it up with discussion on the delete/cancel question.

> - section 9: In the first sentance below, I interpret "access" as the
>             ability to read (GET) a status object or collection.  It
>             does not necessarily imply to me who can issue a new
>             trigger request?  In the second sentance, it says it can
>             only "affect" it's own content, which I guess implies
>             that only it can affect it's own content, as another uCDN
>             affecting it's content would violate this rule?  Should
>             we make that more explicit?
> 
>    "The dCDN must ensure that each uCDN only has access to its own
>     Trigger Status Resources."
> 
>    "The dCDN must ensure that activity triggered by uCDN only affects
>     metadata or content originating from that uCDN."
> 
>             e.g., update the second sentance to something like:
> 
>    "The dCDN must ensure that activity triggered by uCDN only affects
>     metadata or content originating from that uCDN, and that no other
>     uCDN may trigger activity that affects another uCDN's metadata or
>     content."

Hopefully the re-written section 9 is clearer.

> - random: The mention of only affecting a uCDN's own content made me
>          think of the DNS diamond scenario.  Do we believe that the
>          Content URLs described in section 5.1.1 are sufficient to
>          ensure this, or is there a caveat for the diamond case?
> 
>    "The dCDN must ensure that activity triggered by uCDN only affects
>     metadata or content originating from that uCDN."

Done.

> 
> _______________________________________________
> CDNi mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/cdni

---

From: "Francois Le Faucheur (flefauch)" <[email-masked]>
Date: Fri, 4 Jul 2014 15:41:52 +0000

Hi Rob,

I read the new version till end of section 4. Below are some comments.

Cheers

Francois

*** in section 1: 
	* remove the reproduction of actual requirements  (for consistency with other documents).
	* reader of the present document may not be familiar with meaning of “Medium” and “High”, so I’d suggest:
OLD:
"
Requirements for CI/T
are the "High" and "Medium" priority requirements for the CI identified in section 4 of [I-D.ietf-cdni-requirements],, reproduced here for convenience:

      CI-1 [HIGH] The CDNI Control interface shall allow the Upstream
...    
"
NEW:
"
Section 4 of [I-D.ietf-cdni-requirements] identifies the requirements specific to the CI interface. The subset of these requirements applicable to the CI/T interafce are CI-1 to CI-6.
"

*** Section 2:
"Requests to invalidate and purge metadata or content apply to all
   variants of that data with a given URI.”
What do you mean by “variants” here?

*** RFC2119 statements:
I think you need to walk through the doc and ensures there are MUST/SHOULD/MAY for all necessary element of behaviour.
For example, I see:
	* "To trigger activity in the dCDN, the uCDN will POST to the collection of Trigger Status Resources.” and
	* "To trigger activity in the dCDN, the uCDN creates a new Trigger Status Resource by posting to the dCDN's collection of uCDN's Trigger Status Resources.”
but I don’t see any “MUST POST”.
Can you plan a review and make sure you add MUST/SHOULD/MAY wherever it is needed?

As another example, section 2 primarily uses descriptive text (“dCDN does this”, "it will do that”) but has a few RFC2119 statements ("uCDN MAY GET”. "uCDN MAY DELETE”). Sincxe section 2 is an overview, I woudl suggest using only descriptive text and makingh sure all RFC2119 statements are moved to the more detailed sections.

*** section 2.1:
s/Timing of triggered activity is under the dCDN's control/Timing of the execution of the triggered activity is under the dCDN's control/

*** section 2.1:
"Invalidate and purge triggers MUST be applied to all data acquired
   before the trigger was created in the dCDN.  The dCDN may apply the
   triggers to data acquired after trigger creation.”
why do we have a “MUST” and then a “may” (instead of a “MAY”)?
This seems like another example of a needed RFC2119 cleanup.

*** section 2.1:
s/Otherwise, the dCDN may pre-position/Otherwise, there is a risk that the dCDN pre-positions/

*** section 3:
“
 o  Complete - Trigger Status Resources representing activity that
      completed successfully, or for which no further status updates
      will be made by the dCDN.
“
I think "for which no further status updates will be made by the dCDN” means that is in the “processed” status defined in section 4, right?
If yes, it may be worth mentioning the word “processed” here to help reconciliate this list of collection with the various status defined in section 4. e.g.:
“
 o  Complete - Trigger Status Resources representing activity that
      completed successfully, or for which no further status updates
      will be made by the dCDN (.i.e that is already processed).
"

*** section 4:
"The interface is
   intended to be independent of the set of activities defined now, or
   that may be defined in future.”
I had to re-read this a couple of times to understand what you meant. I think it can be phrased better, perhaps indicating it is independent of the “types of triggers” (as opposed to "set of activities) and replacing “now” by “specified in the present document”. 

*** section 4:
the terms “client” and “server” are used out of teh blue and need to be related to uCDN and dCDN. Perhaps you could do something similar to what we did in cdni-logging i.e. we specified teh “Server-side” and “client-side” behavior and stated that a dCDN implementation of the interface MUST support the server-side and an uCDN  implementation of the interface MUST support the client-side and an uCDN. 

*** section 4:
“Since only one CDN
   can be authoritative for a given item of metadata or content, this
   requirement means there cannot be any "loops" in trigger requests
   between CDNs."
This may deserve some more explanations.
When you say “there cannot be” does it mean “it will not happen because it is prevented by the law of physics so you don’t have to worry about it”? or does it mean “you need to make sure it does not happen”? 

*** section 4.1:
"if it is malformed
   or the uCDN does not have sufficient access rights it MAY reject the
   request immediately.”
shoudl this be just a “MAY”? what else can it do with a malformed request?

*** section 4.1:
s/If the dCDN is not able to track triggered activity/If the dCDN is not able to track the execution of triggered activity/

*** section 4.1:
s/If the dCDN is able to track triggered activity/If the dCDN is able to track the execution of triggered activity/

*** section 4.2:
s/described in the following sections/described in section 4.2.1 and 4.2.2/

*** section 4.3:
"If an "active" Trigger Status Resource is deleted, the dCDN MAY stop
   processing the triggered activity. “
MAY or SHOULD?

*** section 4.3:
OLD:
“
 it is recommended that the uCDN's polling interval is half
   the time after which records for completed activity will be
   considered stale.
“
NEW:
“
 the uCDN SHOULD set its polling interval to a value that is at most half
   the time after which records for completed activity will be
   considered stale.
“

*** Section 4.5:
“
If a surrogate affected by a trigger is offline in the dCDN, or the
   dCDN is unable to pass a trigger request on to any of its cascaded
   dCDNs; the dCDN SHOULD report an error if the request is abandoned.
   Otherwise, it SHOULD keep the trigger in state "pending" or "active"
   until it's acted upon or the uCDN chooses to cancel it.
“
It is not obvious if “Otherwise” refers to “if a surrogate…” or “if the request is abandoned”. I think it is teh latter. In which case, you may want to structure the text with bullets like:
“
If a surrogate affected by a trigger is offline in the dCDN, or the
   dCDN is unable to pass a trigger request on to any of its cascaded
   dCDNs:
	*  if the request is abandoned by the dCDN, the dCDN SHOULD report an error
	* Otherwise, it SHOULD keep the trigger in state "pending" or "active"
   until it's acted upon or the uCDN chooses to cancel it.
"

=====================

Editorial Nits:

*** Abstract:
s/CDN Interconnect/CDN Interconnection/
s/re-validate or purge/re-validates or purges/

*** section 1:
s/Problem scope/problem scope/

*** section 2:
s/a request for dCDN/a request for the dCDN/

*** Sometimes you use “the uCDN” and sometimes “uCDN” (e.g. ", uCDN has access”). I suggest always using “the uCDN”. 

*** I thought the aprostrophe for the possessive case only applied to humans and not things, so that one should say “dCDN control” and not “dCDN’s control”. 

*** section 4.1:
s/it MUST indicate that indicate/it MUST indicate/

---

From: Rob Murray <[email-masked]>
Date: Mon, 7 Jul 2014 07:46:07 +0000

Thanks Francois - I'll get these fixed for an update soon after Toronto (along with anything else that comes up).

Cheers,
Rob.