Subject: [CDNi] WG Chair review of draft-ietf-cdni-metadata-06.txt [Batch 6]

From: "Francois Le Faucheur (flefauch)" <[email-masked]>
Date: Mon, 24 Mar 2014 18:57:21 +0000

Below is the last batch.

Overall, I think the document is in good shape.
There are a whole slew of comments that are intended to improve the doc and its readability.
But, embedded in there, there are also a number of more important comments and questions that require some work and some discussions before the doc can move forward (in my opinion). Since I did my review over separate times, I might have lost track of a few things and perhaps some of the issues I bring up are more or less already addressed, don’t hesitate to say so.

I hope this review helps.

Francois

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

*** section 6.3:
s/either discovered by or configured in the downstream CDN./either configured in, or discovered by, the downstream CDN./

*** section 6.4:
"Embedded, where the object is contained (or inlined) within a
      property of an addressable object.”
What is the difference between “inlined” and “contained”?

*** section 6.4:
OLD:
“
to mean either Y is directly embedded in X or that Y is linked to by X.
"
NEW:
OLD:
“
to mean that Y is either directly embedded in X or is linked to by X.
“

*** section 6.4:
s/and which are separately addressable./and which are made separately addressable./

*** section 6.4.1:
s/All MIME types are prefixed./All MIME types for CDNI Metadata objects are prefixed/

*** section 6.4.1:
OLD:
"
The MIME type for each object matches
“
NEW:
"
The MIME type for each object then contains
“

*** Section 6.4.1:
"the type name of that object as defined by this document.”
The phrase “type name” was not clear to me. Should it not just be the "object name”?
For example, HostIndex is not defined as a type, it is just used as the object name. 

*** Section 6.4.1:
OLD:
"
Table 3 lists a few examples of
   the MIME Media Type for each object (resource) that is retrievable
   through the CDNI Metadata interface.
“
NEW:
“
Table 3 lists a few examples of
   the MIME Media Type for some object (resource) that are retrievable
   through the CDNI Metadata interface.
“

*** section 6.4.1:
"See http://www.iana.org/assignments/media-types/index.html for reference."
I was not quite sure what to do with that reference at this point in the document.
Perhaps you coudl remove that sentence and just include teh reference in brackets in the first sentence of section 6.4.1 like 
“All MIME types ([IANA-MIME-TYPES]) for CDNI Metadata objects …"

*** section 6.4.2:
"CDNI Metadata objects are encoded as JSON objects”
This sentence leaves it ambiguous as to whether one CDNI metadat data object can be encoded as only a single JSON object or as multiple JSON objects. I think it is only the former. If this is true then, I suggest “A CDNI Metadata objects is encoded as a JSON object”

*** section 6.4.2:
OLD:
“
Dictionary keys in JSON are case sensitive and therefore by
   convention any dictionary key defined by this document (for example
   the names of CDNI Metadata object properties) MUST be represented in
   lowercase.
“
NEW:
“
Dictionary keys in JSON are case sensitive. By
   convention any dictionary key defined by this document (for example
   the names of CDNI Metadata object properties) MUST be represented in
   lowercase.
“
[Rationale: the 2nd part is not a consequence of the first.]

*** section 6.4.2:
“If absent, all URLs in the remainder of the document must be absolute URLs.”
I don’t think “document” is the right word here. please calrify the scope of “base” (eg single object, until there is another “base” something else)?

*** section 6.4.2:
s/The links of this object to/The links from this object to/

*** section 6.4.2:
"In addition to the properties specific to each object type, the keys
   defined below may be present in any object.”
Wrt the _links key, I think it can appear “instead” of the property and not “in addition to” the properties. Is that right?
For example:
     "host": "video.example.com",
         "_links": {
           "host-metadata" : {
             "type": "application/cdni.HostMetadata.v1+json",
             "href": "http://metadata.example.ucdn.com/video"
we have _links” appear instead of “host-metadata” (and then it happens that _links contains “host-metadata” ).
Can you tweak the text accordingly (not that for “base” it may be in addition, I am not sure).

*** section 6.4.2.1.
“metadata.example.ucdn.com” 
I think we want example domain names that finish with “.example.com” or “.example”. The framework uses “.example” for the cdn hostnames so how about “metadata.ucn.example” ?
(note that I think “video.example.com” is good because it shows the content hostnames and the cdn hostnames in completely different domains).
Obviously this needs to be reflected everywhere.

I understand that URI structure is completely arbitrary but I think:
	* using "http://metadata.example.ucdn.com/host1234” instead of "http://metadata.example.ucdn.com/video” and
	* using "http://metadata.example.ucdn.com/host6789” instead of "http://metadata.example.ucdn.com/images”
woudl be more illustrative (ie it avoids using teh same patterns in request hostnames and metadata URIs, which might be confusing for the reader). And it is in line with the ""http://metadata.ucdn.example.com/auth1234” example you have below.

*** section 6.4.2.1.
"
         "locations": [
             {
               "locations": [
                 { "iprange": "192.168.0.0/16" }
               ],
               "action": "deny"
“
Should the 2nd “locations” occurence above not read “footprints"?
Then why do we not see the “type” and “value” properties defined under footprints?

“iprange” is not one of the footprint types defined in 7.1.1.1, which defines IPv4range and IPv6range.

*** section 6.4.2.1
"
           "protocols": [
             {
               "protocols": [
                 "ftp"
               ],
               "action": "deny"
“
This makes me realise that it woudl be wise to rename the ProtocolACL object property into something like “protocol-acl” or whatever but something different to “protocols”. So the example above would read:
"
           “protocol-acl": [
             {
               "protocols": [
                 "ftp"
               ],
               "action": "deny"
“
This would avoid having two properties (embedded in each other) share the same name, which is bound to create confusion.
This goes bcak to a comment I made in different places about using more explicit and unique property names throughout the document. 

*** section 6.4.2.1 
OLD:
"
"pattern": "/videos/trailers/*”
"
NEW:
“
"pattern": "/video/trailers/*"
"

*** section 6.4.2.1 
OLD:
"
"pattern": "/videos/movies/*”
"
NEW:
“
"pattern": "/video/movies/*"
"

*** section 6.4.2.1
 "href": "http://metadata.ucdn.example.com/videos/trailers” and "href": "http://metadata.ucdn.example.com/videos/movies"
same comment as before, I’d suggest something like  "http://metadata.ucdn.example.com/host1234/path9876" and "http://metadata.ucdn.example.com/host1234/path7654”

same for              "href": "http://metadata.ucdn.example.com/videos/movies/hd”, I’d suggest something like "http://metadata.ucdn.example.com/host1234/path5432”  (I don’t think we need to illustrate the hierarchy of path match into teh path metadata uris)

*** section 6.4.2.1
"
           "times": [
             "times": [
“
same comment as above for “protocols”: the top property should be renamed (eg to something like "times-acl”).

*** section 6.4.2.1
"
             "type": “allow"
“
I think this should read :
“
             “action": “allow”
“

*** section 6.5:
"proprietary and/or custom property Metadata”
What is the difference between proprietary and custom? Perhaps we should just talk about vendor specific?

*** section 6.5:
OLD:
“
   Note: Identification of the property Metadata defining organization
   in the property Metadata type decreases the possibility of property
   Metadata type collision.  
“
NEW:
“
   Note: Identification inside the property Metadata type of the organization that defined the proprietary property Metadata decreases the possibility of property
   Metadata type collision.  
“
Are we really talking about “property Metadata type”? or should this read “Metadata property name”?

*** section 6.5.1
"property Metadata” same as above: is this not more “Metadata property” (or “Metadata properties”)?

*** section 6.5.1
"The uCDN may or may not know which property Metadata the dCDN
   supports. “
I think this statement is intended to apply to vendor-specific properties, so you should be explicit about that in the text of 6.5.1 (as opposed to just imply it from teh discussion in section 6.5) and always talk about “vendor specific properties” .

*** section 6.5.1 
OLD:
“
In cases where the uCDN supports Metadata that the dCDN
   does not, the dCDN MUST be aware of any Metadata marked as
   "mandatory-to-enforce".  If a CDN does not understand or is unable to
   perform the functions associated with any "mandatory-to-enforce"
   Metadata, the CDN MUST NOT service any requests for the corresponding
   content.
“
NEW:
“
In the cases where the uCDN supports vendor-specific Metadata that the dCDN
   does not, the dCDN MUST enforce the semantics of the "mandatory-to-enforce”: If a dCDN does not understand or is unable to
   perform the functions associated with any "mandatory-to-enforce” vendor-specific
   Metadata, the dCDN MUST NOT service any requests for the corresponding
   content.
“

*** section 6.5.1 
"Any standard which defines a new GenericMetadata Type MUST also
   define whether or not the new metadata is mandatory-to-enforce."
Should it not also define whether it is "safe-to-redistribute”?
I don’t think it is appropriate to talk about “standard”. I suggest rephrasing into something like “Any document specifying new GenericMetadata ….”.

*** section 6.5.1 
s/Thus, the dCDN MUST evaluate/Thus, the dCDN MUST always evaluate/

*** section 6.5.2:
I would suggest changing the title of that section (and the text accordingly) to something like “Metadata conflicts”. Because the concept of metadata “overide" is defined in section 3,3 and is something different (ie same metadata but applying at different “host path" levels).

With this change of terminology (ie conflict vs override), I think the Note could be summarised as saying that potentially conflicting metadata may be used as long as they are structured in way that ensures that Metadata ovveride rules avoid any actual conflict (by ensuring that potentially conflicting metadata apply to different sets of requests). Do you agree? to me this is easier to read than the current statement.

*** section 6.6:
“
The version of CDNI Metadata Structural objects is specified by the
   HTTP Content-Type header.  Upon responding to a request for an
   object, a metadata server MUST include a Content-Type header with the
   MIME-type and version number of the object.
“ 
I think the wording needs to be changed because the version is part of the MIME-type whiel the text above suggests it is conveyed in addition to the MIME-type.
Perhaps change to:
“
The version of CDNI Metadata Structural objects is conveyed inside the MIME-Type that is included in the HTTP Content-Type header.  Upon responding to a request for an
   object, a metadata server MUST include a Content-Type header with the
   MIME-type containing the version number of the object.
“

*** section 6.6:
"
Unless stated otherwise, the
   version of each object defined by this document is version 1.
“
I don’t think any objects is defined here with a version different to v1, so how about just saying:
“the version of each object defined by this document is version 1.”

*** section 6.6:
"HTTP requests sent to a metadata server SHOULD include an Accept header with the MIME-type
   and version of the expected object.“
Can a metadata client indicate it it is happy to receive wither of two versions eg "application/cdni.HostIndex.v1+json” or "application/cdni.HostIndex.v2+json? I assme yes. Can you state that and give some description or example?

*** section 6.6:
"
Any document which defines a new type of
   GenericMetadata should specify the version number which it describes."
should—>MUST or SHOULD?

*** section 7:
I don't think the proposed MIME Type allocation approach works. 
I think you propose:
	* to have IANA allocate only the MIME-Type prefix ("application/cdni”)
	* then assume that the CDNI Metadata spec implicitely allocates de-facto the complete MIME-Types through a “rule” which says add the name of a metadata object + v1 + jason. 
I think you want to explicitely request IANA to allocate each and every individual MIME-Type (eg all teh ones mentioned in Table 3  + the other ones needed).
As an analogy, note that ALTO has an allocation in the MIME-TYPE registry for each ALTO type (alto-costmap+json	, alto-costmapfilter+jso, alto-directory+json, etc.).
Also, for information, in teh cdni-logging spec we are requsting allocation of the "application/cdni.LoggingFile” MIME-Type.

*** Section 7:
Why is there not a registry for the Structural metadata objects (like there is for the generic metadata)?
Would this not make it more future-proof and extensible in case there is a need in the future to extend the structural metadata objects?

*** section 7.1
s/a new IANA registry is requested for "CDNI GenericMetadata Types" namespace./a new IANA registry is requested for the "CDNI GenericMetadata Types" namespace./

*** section 7.1:
"
       | Auth           | RFCthis       | 1       | true | true |
“
I think what should appear here is “Authorization” (currently in section 4.2.5) and not “Auth” (currently in section 4.2.6 ). This relates to an earlier comment that section 4.2.6 should probably be turned into 4.2.5.1 (since Authorization contains a List of Auth).

*** section 7.1:
"the version number of the GenericMetadata set to which the
   standard capability applies,”
I can’t parse that. I am not sure what is this version as compared to the versions that appear in MIME-Type.

I am also a bit confused now as to the need to register those object names, beause the Metadata Object names registered here actually never appear in the encoded Metadata (which only lists the corresponding set of properties)..

Actually, this raises a serious high level question in my mind on the way the metadata objects are defined.
So you define objects by names (eg HostIndex). But these object names never appear in the actually encoding. What appears are the properties comprised under the object name (e.g. “hosts” for HostIndex). So it is the first property name appearing (eg “hosts”) that needs to be parsed to actually identify what objects this is (and therefore what other properties follow).
Now if you want to keep that approach, then you need to make sure that a new object allocated in the GenericMetadata Type registry never allocates the same first  “property name”, right? otherwise you can’t parse teh encoding and know which object it is. I don’t think any such restrictions is currently identified in the document.
Would it not be simpler to first list the object name in the encoding (and then it does not matter if different objects reuse the same property name)?

[I am not doing a complete review of the IANA section as I think we need to close on teh previous question first].

While I am on this, I don’t think I have seen in the document exact rules about which metadata object can appear and in which order, and  how many times (as I have already commented).  For example, in Generic metadata , is the object order completely unrestricted? what happens if you have multiple instances of objects, etc.. We want to have exact rules (on sending side and receiving side) about all this.

*** section 7.1:
“MUST”" as discussed before I assume you will be removing any RFC2119 terminology from the IANA section.

*** section 8:
I think the security discussion needs some work.
Some suggestions:
	* The text first indicates that the interface is to be secured via transport security, and then it talks about bad things that can  happens with malicious server/client. This suggests that these bad things happen even when the interface is secured. I recommend you explain the security concern first, and then explain that these can be protected against via transport security mechanisms.
	* regarding security mechanisms, please look at the latest approach decided for cdni-logging and align approach and wording (ie you SHOULD use TLS except in such and such situations, you need to do this re cipher suites,..).
	* when discussing security risks, I recommend you distinguish those that relate to authentication (ie someone spoofing the other end), to confidentiality protection (e.g. someone being able to see metadata), to integrity protection (someone being able to modify metadata). 

*** Appendix A: 
Like we did for cdni-logging, this appendix tracking compliance to requirements is historical and should be removed at publication time. So please add a note for RFC Editor stating that this whole appendix is to be removed at publication.