docs: Add sphinx doc

Change-Id: Id709fdf3675a6057da75591e246112682a58d760

docs/ChronoChat.rst

@@ -0,0 +1,14 @@
+ChronoChat - A Serverless Chat Application in NDN
+=================================================
+
+ChatRoom
+--------
+
+The sync prefix of a chatroom is defined as: ``/ndn/broadcast/ChronoChat/[chatroom]``.
+
+
+..
+   Invitation
+   ----------
+
+   Every application listen to a invitation prefix: ``/<routing_hint>/<user_prefix>/CHRONOCHAT-INVITATION``

docs/DesignDoc.rst

@@ -0,0 +1,187 @@
+Design Document
+===============
+
+
+Leaves
+------
+
+Leaf Node
+~~~~~~~~~
+
+``Leaf`` is the base class which contains NameInfo and SeqNo.
+
+NameInfo
+++++++++
+
+``NameInfo`` is an abstract class and has only one implementation class ``StdNameInfo``.
+Name is managed as a string in ``StdNameInfo``.
+
+``StdNameInfo`` also maintains an internal table of all created ``StdNameInfo`` objects.
+(**NOT CLEAR WHY**)
+
+SeqNo
++++++
+
+``SeqNo`` contains two pieces of information ``m_session`` and ``m_seq``.
+
+``m_session`` (uint64) is Session ID (e.g., after crash, application will choose new session ID.
+Session IDs for the same name should always increase.
+
+``m_seq`` (uint64) is Sequence Number for a session.
+It always starts with 0 and goes to max value.
+(**For now, wrapping sequence number after max to zero is not supported**)
+
+``SeqNo`` also contains a member ``m_valid``.
+It seems that ``SeqNo`` is "invalid" if ``m_seq`` is zero.
+
+Full Leaf Node
+~~~~~~~~~~~~~~
+
+``FullLeaf`` inherits from ``Leaf``.
+Compared to ``Leaf``, ``FullLeaf`` can calculate digest of a leaf.
+
+Digest is calculated as ``H(H(name)|H(session|seq))``.
+
+Diff Leaf Node
+~~~~~~~~~~~~~~
+
+``DiffLeaf`` inherits from ``Leaf``.
+Compared to ``Leaf``, ``DiffLeaf`` contains information about operation: Update & Remove.
+
+
+State (Tree)
+------------
+
+State
+~~~~~
+
+``State`` is an abstract class of digest tree.
+This class defines two methods ``update`` and ``remove``.
+It has only one implementation class ``FullState``.
+
+FullState
+~~~~~~~~~
+
+``FullState`` implements the interface defined by ``State`` and also support digest calculation.
+Digest is calculated as:
+
+0. If the tree is empty, the digest is directly set to ``00``.
+1. Sort all leaves according to names (in std::string order, see std::string::compare).
+2. ``H(H(l1)|H(l2)|...|H(ln))``
+
+
+
+``FullState`` also records the timestamp of the last update.
+
+DiffState
+~~~~~~~~~
+
+``DiffState`` can be considered as a "commitment", which includes a set of ``DiffLeaves``.
+``DiffState`` is maintained as a list.
+Each ``DiffState`` object has a pointer to the next diff.
+Each ``DiffState`` object also has a digest which corresponds to its full state.
+
+
+SyncLogic
+---------
+
+``SyncLogic`` is the core class of ChronoSync.
+
+Initialization
+~~~~~~~~~~~~~~
+
+``SyncLogic`` requires a ``m_syncPrefix``, a callback ``m_onUpdate`` to handle notification of state update, and a callback ``m_onRemove`` to handle notification of leaf removal.
+
+When created, ``SyncLogic`` will listen to ``m_syncPrefix`` to receive sync interest.
+A ``m_syncInterestTable`` is created to hold incoming sync interest with the same state digest as the receiving instance.
+
+``SyncLogic`` also has a ``m_perBranch`` boolean member and a ``m_onUpdateBranch`` callback member.
+(**NOT CLEAR ABOUT THE USAGE**. It seems that if ``m_perBranch`` is set, ``m_onUpdateBranch`` will be called, but ``m_onRemove`` and ``m_onUpdate`` will not be called.)
+
+Working Flow (onData)
+~~~~~~~~~~~~~~~~~~~~~
+
+``SyncLogic`` periodically expresses sync interest which contains its own state digest.
+Sync interest is constructed by concatenating the ``m_syncPrefix`` with the hex-encoded state digest.
+The ``MustBeFresh`` field of the sync interest must be set.
+When a sync interest is sent out, a timer is set up to re-express sync interest.
+The value of timer is set to ``4,000,000 + rand(100, 500)`` milliseconds.
+
+Sync interest is associated with two callbacks: ``onSyncData`` and ``onSyncTimeout``.
+``onSyncTimeout`` does nothing, because interest re-expressing is handled by a scheculer.
+``onSyncData`` validates the data. Invalid data will be dropped.
+If data can be validated, the packet will go through following process:
+
+1. ``SyncLogic`` deletes interests in ``m_syncInterestTable`` which can be satisfied by the sync data, because these interests
+in ``m_syncInterestTable`` must have been satisfied before the data packet is received.
+
+2. ``SyncLogic`` decodes the sync data into a ``DiffState`` object. ``DiffLeaves`` in ``DiffState`` is sorted according to name.
+``SyncLogic`` applies each ``DiffLeaf`` in the sorted order. If the operation in ``DiffLeaf`` changes the status, ``SyncLogic``
+will generate its own diff log which is also a ``DiffState`` object. If ``SyncLogic`` detect that the received sync data has some
+information that it is missing, it will prepare a ``MissingDataInfo`` which includes ``prefix`` (name), ``low`` (lowest missing SeqNo),
+and ``high`` (highest missing SeqNo), and call ``m_onUpdate`` on it.
+If the content of sync data cannot be parsed, the packet is dropped.
+
+3. ``SyncLogic`` compares the sync data name with ``m_outstandingInterestName`` which is the name of the outstanding sync interest
+sent by the instance. If so, ``SyncLogic`` expresses new sync interest after sync data processing is done, otherwise does nothing
+
+Working Flow (onInterest)
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``SyncLogic`` also expects to receive sync interest from others.
+If a sync interest is received, the packet will be processed as following:
+
+1. ``SyncLogic`` checks whether the interest is a normal interest or recovery interest (which will be described later).
+If data is a normal sync data packet, go to Step 2, otherwise go to Step 7.
+
+2. Receiving a normal sync interest, check if its digest is ``00``. If so, go to Step 3, otherwise go to Step 4.
+
+3. Receiving an initial sync interest (sending instance has an empty sync tree). If receiving ``SyncLogic`` 's sync tree is not empty,
+encode the whole sync tree into response (sync data), otherwise both sender and receiver are in the same status, put the interest into
+``m_syncInterestTable``.
+
+4. Receiving a sync interest which contains some state. Check if the sender and receiver are in the same status, if so, put the interest
+into ``m_syncInterestTable``. Otherwise check if sender's state exist in receiver's log, if so, merge all the difference into one
+``DiffState`` and encode it into response (sync data). If the receiver cannot recognize the sender's state, go to Step 5.
+
+5. Check if immediate recovery is needed (whether ``timedProcessing`` is set), if so, express recovery interest immediately (go to Step 6).
+Otherwise check if the interest exist in ``m_syncInterestTable``. If the interest has not been inserted into the table before,
+process the interest again after ``rand(200, 100)`` milliseconds but with ``timedProcessing set``. If the interest exist in the table,
+insert it again simply refreshes the table and defers the interest processing for another random period. It is guaranteed that a recovery
+interest will be sent out when the interest is processed again.
+
+6. Send recovery interest. A recovery interest is constructed by inserting a name component ``recovery`` between the ``m_syncPrefix`` and
+the received digest. Default recovery interest re-expressing timer is 200 milliseconds with a jitter ``rand(100, 500)`` milliseconds.
+Every time when recovery interest times out, the timer will be doubled until is longer than 100 seconds.
+
+7. Receiving a recovery sync interest, check if its digest is recongized. If not, drop the interest, otherwise, encode the sync tree in the
+response.
+
+Name Publishing
+~~~~~~~~~~~~~~~
+
+``addLocalName`` method is used to update leaf nodes.
+Caller needs to supply prefix (name), session, and seq.
+The 3-tuple will trigger state changes and sync interest/data exchange.
+
+Data Validation (in paper, not implemented)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each leaf as a sibling for endorsement.
+The name of the sibling is constructed by concatenating the original leaf's name with a name component ``ENDORSE``.
+``SyncLogic``, when parsing the returned data, will automatically fetch & process ``ENDORSE`` data.
+
+Unresolved Issue
+~~~~~~~~~~~~~~~~
+
+1. Remove leaf
+
+2. SeqNo wrapp-up
+
+SyncSocket
+----------
+
+``SyncSocket`` is a wrapper of ``SyncLogic``. It can be viewed as an interface to a leaf node.
+Through SyncSocket, user only needs to publish its data.
+``SyncSocket`` will maitain corresponding sequence number, and trigger synchronization throug ``SyncLogic::addLocalName`` method.
+``SyncSocket`` is also responsible for actual data publishing.

docs/FAQ.rst

@@ -0,0 +1,2 @@
+FAQ
+===

docs/index.rst

@@ -0,0 +1,46 @@
+ChronoSync - A synchronization Protocol in NDN
+==============================================
+
+..
+   NFD is a network forwarder that implements and evolves together with the Named Data
+   Networking (NDN) `protocol <http://named-data.net/doc/ndn-tlv/>`__. After the initial
+   release, NFD will become a core component of the `NDN Platform
+   <http://named-data.net/codebase/platform/>`__ and will follow the same release cycle.
+
+ChronoSync Documentation
+------------------------
+
+.. toctree::
+   :hidden:
+   :maxdepth: 3
+
+   DesignDoc
+   FAQ
+   ChronoChat
+
+..
+   INSTALL
+
+* :doc:`DesignDoc`
+
+* :doc:`FAQ`
+
+* :doc:`ChronoChat`
+
+**Additional documentation**
+
+* `API documentation (doxygen) <doxygen/annotated.html>`_
+
+Downloading
+-----------
+
+* `Source code GitHub git repository <https://github.com/named-data/ChronoSync>`_.
+
+License
+-------
+
+..
+   NFD is an open and free software package licensed under GPL 3.0 license and is the
+   centerpiece of our committement to making NDN's core technology open and free to all
+   Internet users and developers. For more information about the licensing details and
+   limitation, refer to `COPYING.md <https://github.com/named-data/NFD/blob/master/COPYING.md>`_.