Introducing explicit types for Number and Digest components
diff --git a/conf.py b/conf.py
index c00e100..77008f9 100644
--- a/conf.py
+++ b/conf.py
@@ -48,9 +48,9 @@
# built documents.
#
# The short X.Y version.
-version = '0.1'
+version = '0.2'
# The full version, including alpha/beta/rc tags.
-release = '0.1a2'
+release = '0.2'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/interest.rst b/interest.rst
index 7ebd49e..30b4706 100644
--- a/interest.rst
+++ b/interest.rst
@@ -7,7 +7,7 @@
::
- Interest ::= INTEREST-TYPE TLV-LENGTH
+ Interest ::= INTEREST-TYPE TLV-LENGTH
Name
Selectors?
Nonce
@@ -16,7 +16,7 @@
``Name`` and ``Nonce`` are the only two two required elements in an Interest packet.
Selectors are optional elements that further qualify Data that may match the Interest.
-They are used for discovering and selecting the Data that matches best to what the application wants. Selectors are placed right after the Name to facilitate implementations that may use continuous memory block of Name and Selectors TLVs together as the index for PIT lookup. By using a TLV to group all the Selectors, an implementation can easily skip them to find Nonce, which is used together with Name to identify looping Interests.
+They are used for discovering and selecting the Data that matches best to what the application wants. Selectors are placed right after the Name to facilitate implementations that may use continuous memory block of Name and Selectors TLVs together as the index for PIT lookup. By using a TLV to group all the Selectors, an implementation can easily skip them to find Nonce, which is used together with Name to identify looping Interests.
If Selectors TLV is present in the Interest, it MUST contain at least one selector.
The two other optional elements, Scope and InterestLifetime, are referred to as *Guiders*.
@@ -36,7 +36,7 @@
::
- Selectors ::= SELECTORS-TYPE TLV-LENGTH
+ Selectors ::= SELECTORS-TYPE TLV-LENGTH
MinSuffixComponents?
MaxSuffixComponents?
PublisherPublicKeyLocator?
@@ -55,11 +55,11 @@
MaxSuffixComponents ::= MAX-SUFFIX-COMPONENTS-TYPE TLV-LENGTH
nonNegativeInteger
-When needed, ``MinSuffixComponents`` and ``MaxSuffixComponents`` allow a data consumer to indicate whether the Name in the Interest is the full name including the digest, or the full name except for the digest, or the content it is seeking has a known range of legitimate component counts.
-These two parameters refer to the number of name components beyond those in the prefix, and counting the implicit digest, that may occur in the matching Data.
+When needed, ``MinSuffixComponents`` and ``MaxSuffixComponents`` allow a data consumer to indicate whether the Name in the Interest is the full name including the digest, or the full name except for the digest, or the content it is seeking has a known range of legitimate component counts.
+These two parameters refer to the number of name components beyond those in the prefix, and counting the implicit digest, that may occur in the matching Data.
The default for ``MinSuffixComponents`` is 0 and for ``MaxSuffixComponents`` is effectively infinite, meaning that any Data whose name starts with the prefix is a match. Often only one of these will be needed to get the desired effect.
-
+
PublisherPublicKeyLocator
+++++++++++++++++++++++++
@@ -104,7 +104,7 @@
::
- ChildSelector ::= CHILD-SELECTOR-TYPE TLV-LENGTH
+ ChildSelector ::= CHILD-SELECTOR-TYPE TLV-LENGTH
nonNegativeInteger
Often a given Interest can match more than one Data within a given content store.
@@ -114,9 +114,12 @@
Here leftmost and rightmost refer to the least and greatest components according to the canonical NDN name component ordering (:ref:`Name Section<name>`).
This ordering is only done at the level of the name hierarchy one past the name prefix.
-For example, assuming in the name hierarchy the component immediately after the name prefix is the version number, whose next level is the segment number, then setting ChildSelector to be 1 will retrieve the rightmost version number (i.e., the latest version) and the leftmost segment number (i.e., the first segment). However, this selection is only done with respect to a single content store, not globally. Additional rounds that exclude the earlier versions may be used to explore other content stores for newer versions.
+For example, assuming in the name hierarchy the component immediately after the name prefix is the version number, whose next level is the segment number, then setting ChildSelector to be 1 will retrieve the rightmost version number (i.e., the latest version) and the leftmost segment number (i.e., the first segment). However, this selection is only done with respect to a single content store, not globally. Additional rounds that exclude the earlier versions may be used to explore other content stores for newer versions.
In this case, the use of ChildSelector does not change the multi-round outcome, but it decreases the number of rounds needed to converge to an answer.
-
+
+.. One exception from the above rule is for ``ImplicitSha256Digest`` component.
+
+
MustBeFresh
+++++++++++
@@ -125,7 +128,7 @@
MustBeFresh ::= MUST-BE-FRESH-TYPE TLV-LENGTH(=0)
This selector is encoded with Type and Length but no Value part.
-When it is absent from an Interest packet, the router can respond with a Data packet from its content store whose FreshnessPeriod is either still valid or expired.
+When it is absent from an Interest packet, the router can respond with a Data packet from its content store whose FreshnessPeriod is either still valid or expired.
When it is present in an Interest packet, the router should not return Data packet from its content store whose FreshnessPeriod has expired.
The FreshnessPeriod carried in each Data packet (:ref:`Data Section<data>`) is set by the original producer. It starts counting down when the Data packet arrives at a node. Consequently if a node is N hops away from the original producer, it may not consider the Data stale until N *X* FreshnessPeriod after the Data is produced.
@@ -159,11 +162,11 @@
This value limits how far the Interest may propagate.
Scope 0 prevents propagation beyond the local NDN daemon (even to other applications on the same host). Scope 1 limits propagation to the applications on the originating host.
-Scope 2 limits propagation to no further than the next node.
+Scope 2 limits propagation to no further than the next node.
Other values are not defined at this time, and will cause the Interest packet to be dropped.
Note that Scope is not a hop count---the value is not decremented as the Interest is forwarded.
-
+
InterestLifetime
++++++++++++++++
@@ -171,7 +174,7 @@
InterestLifetime ::= INTEREST-LIFETIME-TYPE TLV-LENGTH nonNegativeInteger
-``InterestLifetime`` indicates the (approximate) time remaining before the Interest times out.
+``InterestLifetime`` indicates the (approximate) time remaining before the Interest times out.
The value is the number of milliseconds. The timeout is relative to the arrival time of the Interest at the current node.
Nodes that forward Interests may decrease the lifetime to account for the time spent in the node before forwarding, but are not required to do so. It is recommended that these adjustments be done only for relatively large delays (measured in seconds).
@@ -197,7 +200,7 @@
- Changed default semantics of staleness.
- Specifically, NDN-TLV Interest without any selectors will bring any data that matches the name, and only when ``MustBeFresh`` selector is enabled it will try to honor freshness, specified in Data packets.
+ Specifically, NDN-TLV Interest without any selectors will bring any data that matches the name, and only when ``MustBeFresh`` selector is enabled it will try to honor freshness, specified in Data packets.
With Binary XML encoded Interests, the default behavior was to bring "fresh" data and return "stale" data only when ``AnswerOriginKind`` was set to 3.
Application developers must be aware of this change, reexamine the Interest expression code, and enable ``MustBeFresh`` selector when necessary.
diff --git a/name.rst b/name.rst
index 5658653..922bb1c 100644
--- a/name.rst
+++ b/name.rst
@@ -3,7 +3,7 @@
Name
----
-An NDN Name is a hierarchical name for NDN content, which contains a sequence of name components.
+An NDN Name is a hierarchical name for NDN content, which contains a sequence of name components.
NDN Name Format
~~~~~~~~~~~~~~~
@@ -15,59 +15,101 @@
::
- Name ::= NAME-TYPE TLV-LENGTH NameComponent*
+ Name ::= NAME-TYPE TLV-LENGTH
+ (NameComponent | NumberComponent | ImplicitSha256DigestComponent)*
+
NameComponent ::= NAME-COMPONENT-TYPE TLV-LENGTH BYTE+
+ NumberComponent ::= NUMBER-COMPONENT-TYPE TLV-LENGTH
+ nonNegativeInteger
+
+ ImplicitSha256DigestComponent ::= IMPLICIT-SHA256-DIGEST-COMPONENT TLV-LENGTH(=32)
+ BYTE{32}
+
.. % 0 or many name components in name
.. % 0 or many bytes in name component
+``NameComponent`` is a generic name component, containing any application defined data.
+
+``NumberComponent`` is a component that carries non-negative integer.
+
+``ImplicitSha256DigestComponent`` is an implicit SHA256 digest component.
+
+
NDN URI Scheme
~~~~~~~~~~~~~~
For textual representation, it is often convenient to use URI to represent NDN names.
Please refer to RFC 3986 (URI Generic Syntax) for background.
-- The scheme identifier is ``ndn``.
+- The scheme identifier is ``ndn``.
-- When producing a URI from an NDN Name, only the generic URI unreserved characters are left unescaped.
- These are the US-ASCII upper and lower case letters (A-Z, a-z), digits (0-9), and the four specials PLUS (+), PERIOD (.), UNDERSCORE (\_), and HYPHEN (-).
- All other characters are escaped using either the percent-encoding method of the URI Generic Syntax or a ``ndn`` scheme specific hexadecimal string escape starting with the EQUALS (=) and an even number of characters from the set of hex digits.
- Once an EQUALS has been encountered in a component the hexadecimal encoding persists until the end of the component.
- The hex digits in these escaped encodings should always use upper-case letters, i.e., A-Z.
+- Component types have the following URI representations:
-- To unambiguously represent name components that would collide with the use of . and .. for relative URIs, any component that consists solely of zero or more periods is encoded using three additional periods.
+ * ``NameComponent``
+
+ When producing a URI from an NDN Name, only the generic URI unreserved characters are left unescaped.
+ These are the US-ASCII upper and lower case letters (A-Z, a-z), digits (0-9), and the four specials PLUS (+), PERIOD (.), UNDERSCORE (\_), and HYPHEN (-).
+ All other characters are escaped using either the percent-encoding method of the URI Generic Syntax or a ``ndn`` scheme specific hexadecimal string escape starting with the EQUALS (=) and an even number of characters from the set of hex digits.
+ Once an EQUALS has been encountered in a component the hexadecimal encoding persists until the end of the component.
+ The hex digits in these escaped encodings should always use upper-case letters, i.e., A-Z.
+
+ To unambiguously represent name components that would collide with the use of . and .. for relative URIs, any component that consists solely of zero or more periods is encoded using three additional periods.
+
+ * ``NumberComponent``
+
+ Number components start with ``number=`` prefix, following with textual representation of the number.
+ For example, ``number=10`` represents a NumberComponent with encoded value of 10.
+
+ * ``ImplicitSha256DigestComponent``
+
+ Implicit SHA256 digest component starts with ``sha256digest=`` prefix, following the digest represented as a sequence of 32 hexadecimal numbers.
+ For example, ``sha256digest=893259d98aca58c451453f29ec7dc38688e690dd0b59ef4f3b9d33738bff0b8d``
- The authority component (the part after the initial ``//`` in the familiar http and ftp URI schemes) is not relevant to NDN.
- It should not be present, and it is ignored if it is present.
+ It should not be present, and it is ignored if it is present.
Implicit Digest Component
~~~~~~~~~~~~~~~~~~~~~~~~~
The Name of every piece of content includes as its final component a derived digest that ultimately makes the name unique.
-This digest may occur in an Interest Name as an ordinary Component (the last one in the name).
+This digest may occur in an Interest Name as an ``ImplicitSha256DigestComponent`` and MUST appear as the last component in the name.
This final component in the name is never included explicitly in the Data packet when it is transmitted on the wire.
It can be computed by any node based on the Data packet content.
The **implicit digest component** consists of the SHA-256 digest of the entire Data packet without the signature component. Having this digest as the last name component enables us to achieve the following two goals:
-- Identify one specific Data packet and no other.
+- Identify one specific Data packet and no other.
- Exclude a specific Data packet in an Interest (independent from whether it has a valid signature).
Canonical Order
~~~~~~~~~~~~~~~
-In several contexts in NDN packet processing, it is useful to have a consistent ordering of names and name components. NDN names consist of a sequence of NameComponents, and each NameComponent is a sequence of zero or more 8-bit bytes. The ordering for components is such that:
+In several contexts in NDN packet processing, it is useful to have a consistent ordering of names and name components.
-- If *a* is shorter than *b* (i.e., has fewer bytes), then *a* comes before *b*.
+The order between individual name components is defined as follows:
-- If *a* and *b* have the same length, then they are compared in ASCII lexicographic order (e.g., ordering based on memcmp() operation.)
+- Any ``ImplicitSha256DigestComponent`` less than any ``NumberComponent``, which is less than any ``NameComponent``
+::
+
+ ImplicitSha256DigestComponent < NumberComponent < NameComponent
+
+- The order for the same type components is such that:
+
+ * If *a* is shorter than *b* (i.e., has fewer bytes), then *a* comes before *b*.
+
+ * If *a* and *b* have the same length, then they are compared in ASCII lexicographic order (e.g., ordering based on memcmp() operation.)
For Names, the ordering is just based on the ordering of the first component where they differ.
If one name is a proper prefix of the other, then it comes first.
+..
+ While the above defines generic order of any NDN names, :ref:`Interest selector <Selectors>` ``ChildSelector`` does not take into account the implicit digest componen, unless all other components are equal.
+
+
Changes from CCNx
~~~~~~~~~~~~~~~~~
@@ -78,3 +120,5 @@
.. (\cite{NamingConvention}).
- Deprecated zero-length name component.
+
+- Number and implicit digest use dedicate TLV types