[Nfd-dev] comments for the nfd doc

[Burke, Jeff]

Hi,

Below are some comments based on a pretty quick read of the document.  I hope this is helpful.  It's really exciting to have this as a starting point for understanding NFD, and I am looking forward to the NFD team's updates over time...

Thanks,
Jeff



Big picture comments:


1.     I think the document could be re-organized in a simple way to provide a clearer high-level view of how the forwarder functions first, and then dive into the details. While starting with Faces makes sense from a bottom-up perspective, a critical thing to understand first may be how NFD processes packets, and what the various modules/abstractions are.  This might be accomplished by moving the pipelines section earlier or by expanding the introduction to talk about packet processing, the relationship between NRD / NFD, etc.



2.     More generally, it would be nice if the document was re-organized to reduce the number of forward references needed to understand something in detail, and grouped discussion of functionality together.  (E.g., Strategy, Strategy Choice Table, Strategy Manager could all be in a strategy section, rather than spread out, if the notion of managers and the Name Tree are introduced beforehand.)


a.     For example, the strategy choice table structure section is hard to read / understand without reading about strategy first. While a forward pointer works, it would be better if the strategy section came first.



b.     Similarly, high-level abstractions used repeatedly that are relevant to the way the code is organized, e.g,. the notion of “managers”, should be introduced briefly at the beginning, rather than relying on forward references.   Then, you could group the description of each manager with what it manages… the FIB manager description could go in the section about the FIB, the strategy manager in the section about strategy, etc.  I think this would make these various things easier to grasp quickly.


3.     I would highly recommend increasing the terseness / consistency of terminology.  E.g., the terms callbacks and triggers are used in the early part of the document, but there is a whole section on the “event system” – what is the difference between a trigger, event, timer, signal (p7), and callback?  Can the number of terms be reduced?  It’s not that the relationship is particularly complicated, but it creates noise for the reader unnecessarily. If the terminology does not reflect functional differences, it should be collapsed; if it does, it should be explained more clearly.    Other examples are distinguishing between Internal and Local (Internal doesn’t show up in the table in 2.1); non-local vs. remote and peer, etc.  Similarly, there is a “face system” but a “tables module”… What is a system vs. a module?   Namespace vs. a prefix?   Operator vs. user vs. administrator (p40) vs. application vs. developer?  Streamlining terminology may greatly improve readability for the first-time reader.



4.     Consider also putting security earlier, and working more security information into the other sections over time.   Also, the notion of /localhost and /localhop are worked with throughout as a key concept, but not discussed in the security section


5.     A future work / open issues section would be helpful.


6.     Utilities (6.2) should likely be last in the document, and probably integrated with Section 9.


7.     As with any early draft, the document probably needs a single editor to do a pass to make the language more consistent and simpler.  “The purpose of the channel abstraction is to encapsulate the functionalities needed to accept incoming connections or tostart outgoing connections, and to create a face when the connection attempt is successful.”  (p7) => “Channels start outgoing connections and accept incoming connections.  They create Faces for successful connections.”


8.     Diagrams could be made more consistent, and you may want to allocate space based on their complexity.


a.     E.g., Figure 2 is really useful and has a lot of information, but is only given the same space a Figure 7.



b.     In fact, having more diagrams like Figure 2 per section would be very helpful.


c.     The visual overview of all pipelines (Figure 10) is critical and probably needs to be redrawn to be clearer (fewer colors, stronger lines, etc), have a key (what are yellow boxes) and perhaps give more detailed information.


d.     There are too many visual styles of diagrams, but this could be fixed later.


9.     Things that are usually not NDN-like, in particular channels and hosts, should have some bit of explanation that explains why these abstractions or terms are used.



10.  There are a few places where there is discussion of a use condition (e.g., “The FIB is expected to be relatively stable” p10) that are problematic, as they do not 1) provide evidence, explanation, or citation for the statement, 2) explain what it actually means in technical terms, or 3) explain why it’s relevant to what’s being read or what was designed. In the FIB example, would a vehicle’s FIB in a highly dynamic environment be considered “relatively stable” or not?  Etc.  These types of statements should be removed or explained in terms of the three aspects above, if possible.  They a little distracting because they seem to beg the question rather than clarify the design strategy as intended.


11.  When describing specific relationships, “Management calls Cs::setLimit”, perhaps it is better to say which manager(s) specifically?  Management is used generally several times


12.  Summary figures like Fig 18 could perhaps come earlier


13.  Should there be timing diagrams (p36) for other components besides the RIB manager?


More low-level details:


1.     “Listen only” should be defined (p6)

2.     Guiders and selectors are undefined but used occasionally

3.     Tables should have numbers and captions

4.     Colloquialisms should be avoided in technical definitions:  “starting point” and "understands" (p6)

5.     The configuration file mentioned on p8 is not explained until much later, so the intro of section 2.4 is a little confusing.

6.     The title of Section 3 should include all tables it discusses or no tables.

7.     The “unsatisfy timer” is a little confusing, as “unsatisfy” is not a typical English word, and on p13 the explanation makes it a little unclear whether it refers to a PIT entry or the whole PIT.

8.     Sections 3.4 and 3.5 really should come after or in the strategy section.

9.     What it means to “install a strategy” should be explained.

10.  It’s unclear why the word “choice” is in the strategy table name; perhaps this could be briefly explained.

11.  The notion of an “operator” is used several times but undefined. (And “local operator” is used on p14.)  This is actually a big-picture note, I guess. If the assumption is that NFD implements a stack on end-user devices, this word should be used sparingly or not at all.   Footnote 3 is another example.  I think the notion of an “NFD operator” should be explained earlier or dropped.

12.  What makes a strategy effective? Who is expected to write / override findEffectiveStrategy?  (p14)  Integrating the strategy table and strategy sections might help answer this easily.

13.  The example of an anti-DDOS strategy begs the question of whether strategies can be composed together / more than one can operate on a packet.

14.  Early in the document, performance optimizations are stated as a non-goal (for now) but on p16, it is used to motivate a custom hash table implementation.

15.  A lot of detail is given on the NameTree (p17, etc.) – perhaps an explanation of when it is expected that a developer would need to know the details / extend it would be helpful.

16.  What’s the purpose of introducing “Host” relative to Strategy Info?  It’s the only non-TCP/IP mention of host in the document except for the notion of “localhost”, which probably needs to be defined as well... why in the non-host-based world of NDN, is this so central (p26)

17.   In 5.2.4, the NCC acronym needs to be written out, and probably a short explanation should be given so one does not have to go back to the CCNx doc.

18.  What is a LocalControlHeader and a NextHopFaceId?  Is this documented in the protocol specification? – perhaps should have a citation, as it will be new for most people.

19.  Section 5.3.1 is very useful, and there should be more like it.  (However, the first sentence seems to overstate our knowledge at this time.)

20.  The notion of an “authorized user” is introduced on p29/p30 without explanation.

21.  As with “operator” I would recommend either explaining “user” (p29-30) or eliminating it.  What does user mean in the context of NFD-as-future-stack vs. NFD-as-standalone-forwarder? Similarly, “administrator” is used only once on p40.

22.  The configuration section of 6.1.2 is helpful – perhaps somewhere there should be a section that explains what happens when you start NFD, and how it relates to all of these modules?

23.  “protect NFD from errors” may need rephrasing. Why would NFD need protecting? (p31)

24.  URIs are introduced on p31, what is a FaceUri?

25.  The bullet list on p31 seems focused on unicast faces; perhaps should cover all kinds?

26.  What is dataset?  (p32) Does this new term need to be introduced?  May want to explain why  measurement data is only available locally.

27.  What are status codes and how are they used? (Introduced without much fanfare in section 6 – perhaps just need a few more references to the management protocol doc?)

28.  Consider providing the RFC reference for the websocket implementation being used.

29.  The details of the command interest format don’t seem in the right place at the beginning of the trust model section, as it's something of an implementation / protocol detail — in most other cases in the document, protocols are defined elsewhere.  The security section seems somewhat sparse in general – e.g., the seemingly critical term “NDN identity certificate” is introduced without much fanfare, as are NDN Regular Expressions, which seem to be a significant and important topic.





-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.lists.cs.ucla.edu/pipermail/nfd-dev/attachments/20140620/1d03fbd8/attachment.html>