Add various documentation indices

[nncp.git] / doc / sp.texi

diff --git a/doc/sp.texi b/doc/sp.texi
index 239b87f1eb6c0d995caa606a88f196a8114e15a6..36f5cc794d32ced78508a4e99c718fa45cfea69a 100644 (file)
--- a/doc/sp.texi
+++ b/doc/sp.texi
@@ -1,10 +1,14 @@
 @node Sync
 @node Sync

+@cindex sync protocol
+@cindex online protocol
+@cindex synchronization

 @unnumbered Synchronization protocol
 
 So-called synchronization protocol (SP) is used in current TCP daemon's
 implementation. It is used for synchronizing @ref{Spool, spool}
 directory contents between two nodes.
 
 @unnumbered Synchronization protocol
 
 So-called synchronization protocol (SP) is used in current TCP daemon's
 implementation. It is used for synchronizing @ref{Spool, spool}
 directory contents between two nodes.
 

+@cindex XMODEM

 It is aimed to be very simple and effective. It uses reliable transport
 like TCP connections. It must be effective both on single-duplex and
 full-duplex links: for example satellites have very high throughput but
 It is aimed to be very simple and effective. It uses reliable transport
 like TCP connections. It must be effective both on single-duplex and
 full-duplex links: for example satellites have very high throughput but


@@ -12,6 +16,13 @@ high-delay links, so acknowledging of each received packet, like
 @url{https://en.wikipedia.org/wiki/XMODEM, XMODEM} does, causes
 unacceptable performance degradation.
 
 @url{https://en.wikipedia.org/wiki/XMODEM, XMODEM} does, causes
 unacceptable performance degradation.
 

+@vindex NNCPDEADLINE
+Internally it uses various timeouts and deadlines. One of them used
+extensively is 10 seconds default deadline timeout. You can override it
+with @env{$NNCPDEADLINE} environment variable, that could be useful with
+very high delay links.
+
+@cindex Noise-IK

 SP works on top of
 @url{http://noiseprotocol.org/noise.html#interactive-patterns,
 @code{Noise_IK_25519_ChaChaPoly_BLAKE2b}} protocol. Each Noise packet
 SP works on top of
 @url{http://noiseprotocol.org/noise.html#interactive-patterns,
 @code{Noise_IK_25519_ChaChaPoly_BLAKE2b}} protocol. Each Noise packet


@@ -49,24 +60,39 @@ just an unsigned integer telling what body structure follows.
 
 @table @emph
 
 
 @table @emph
 

+@cindex HALT payload

 @item HALT
     Stop file transmission, empty sending queue on the remote side.
     Actually @emph{HALT} packet does not have any body, only the header
     with the type. It is also used in the first payload for padding to
     the maximum size.
 @item HALT
     Stop file transmission, empty sending queue on the remote side.
     Actually @emph{HALT} packet does not have any body, only the header
     with the type. It is also used in the first payload for padding to
     the maximum size.

+

 @verbatim
 +------+
 | HALT |
 +------+
 @end verbatim
 
 @verbatim
 +------+
 | HALT |
 +------+
 @end verbatim
 

+@cindex PING payload
+@item PING
+    Dummy packet only used for determining workability of the connection.
+
+@verbatim
++------+
+| PING |
++------+
+@end verbatim
+
+@cindex INFO payload

 @item INFO
     Information about the file we have for transmission.
 @item INFO
     Information about the file we have for transmission.

+

 @verbatim
 +------+--------------------+
 | INFO | NICE | SIZE | HASH |
 +------+--------------------+
 @end verbatim
 @verbatim
 +------+--------------------+
 | INFO | NICE | SIZE | HASH |
 +------+--------------------+
 @end verbatim

+

     @multitable @columnfractions 0.2 0.3 0.5
     @headitem @tab XDR type @tab Value
     @item Niceness @tab
     @multitable @columnfractions 0.2 0.3 0.5
     @headitem @tab XDR type @tab Value
     @item Niceness @tab


@@ -80,14 +106,17 @@ just an unsigned integer telling what body structure follows.
         Unique file identifier, its checksum
     @end multitable
 
         Unique file identifier, its checksum
     @end multitable
 

+@cindex FREQ payload

 @item FREQ
     File transmission request. Ask remote side to queue the file for
     transmission.
 @item FREQ
     File transmission request. Ask remote side to queue the file for
     transmission.

+

 @verbatim
 +------+---------------+
 | FREQ | HASH | OFFSET |
 +------+---------------+
 @end verbatim
 @verbatim
 +------+---------------+
 | FREQ | HASH | OFFSET |
 +------+---------------+
 @end verbatim

+

     @multitable @columnfractions 0.2 0.3 0.5
     @headitem @tab XDR type @tab Value
     @item Hash @tab
     @multitable @columnfractions 0.2 0.3 0.5
     @headitem @tab XDR type @tab Value
     @item Hash @tab


@@ -98,13 +127,16 @@ just an unsigned integer telling what body structure follows.
         Offset from which remote side must transmit the file
     @end multitable
 
         Offset from which remote side must transmit the file
     @end multitable
 

+@cindex FILE payload

 @item FILE
     Chunk of file.
 @item FILE
     Chunk of file.

+

 @verbatim
 +------+-------------------------+
 | FILE | HASH | OFFSET | PAYLOAD |
 +------+-------------------------+
 @end verbatim
 @verbatim
 +------+-------------------------+
 | FILE | HASH | OFFSET | PAYLOAD |
 +------+-------------------------+
 @end verbatim

+

     @multitable @columnfractions 0.2 0.3 0.5
     @headitem @tab XDR type @tab Value
     @item Hash @tab
     @multitable @columnfractions 0.2 0.3 0.5
     @headitem @tab XDR type @tab Value
     @item Hash @tab


@@ -118,13 +150,16 @@ just an unsigned integer telling what body structure follows.
         Chunk of file itself
     @end multitable
 
         Chunk of file itself
     @end multitable
 

+@cindex DONE payload

 @item DONE
     Signal remote side that we have successfully downloaded the file.
 @item DONE
     Signal remote side that we have successfully downloaded the file.

+

 @verbatim
 +------+------+
 | DONE | HASH |
 +------+------+
 @end verbatim
 @verbatim
 +------+------+
 | DONE | HASH |
 +------+------+
 @end verbatim

+

     @multitable @columnfractions 0.2 0.3 0.5
     @headitem @tab XDR type @tab Value
     @item Hash @tab
     @multitable @columnfractions 0.2 0.3 0.5
     @headitem @tab XDR type @tab Value
     @item Hash @tab


@@ -136,7 +171,7 @@ just an unsigned integer telling what body structure follows.
 
 Typical peer's behaviour is following:
 
 
 Typical peer's behaviour is following:
 

-@verbatiminclude sp.utxt
+@verbatiminclude sp.plantuml.txt

 
 @enumerate
 @item Perform @emph{Noise-IK} handshake:
 
 @enumerate
 @item Perform @emph{Noise-IK} handshake:


@@ -164,7 +199,7 @@ payloads, then send all of remaining in the transport stage.
     Ignore it if it is too nice.
     @item If already downloaded file exists, then queue @emph{DONE}
     sending.
     Ignore it if it is too nice.
     @item If already downloaded file exists, then queue @emph{DONE}
     sending.

-    @item If @file{.seen} exists, then queue @emph{DONE} sending.
+    @item If @file{seen/XXX} exists, then queue @emph{DONE} sending.

     @item If @file{.part} exists, then queue @emph{FREQ} sending with
     corresponding offset.
     @end itemize
     @item If @file{.part} exists, then queue @emph{FREQ} sending with
     corresponding offset.
     @end itemize


@@ -186,13 +221,20 @@ then run background integrity checker on it. If check succeeds, then
 delete @file{.part} suffix from file's name and send @emph{DONE} packet.
 
 @item When @emph{DONE} packet received, delete corresponding file.
 delete @file{.part} suffix from file's name and send @emph{DONE} packet.
 
 @item When @emph{DONE} packet received, delete corresponding file.

+

 @item When @emph{HALT} packet received, empty file sending queue.
 
 @item Each second, node checks: are there any new @emph{tx} packets
 appeared and queues corresponding @emph{INFO} packets.
 
 @item When @emph{HALT} packet received, empty file sending queue.
 
 @item Each second, node checks: are there any new @emph{tx} packets
 appeared and queues corresponding @emph{INFO} packets.
 

-@item If no packets are sent and received during @ref{CfgOnlineDeadline,
-onlinedeadline} duration, then close the connection. There is no
-explicit indication that session is over.
+@item Each minute, if no packets were sent, node sends @emph{PING}
+packet.
+
+@item If no non-PING packets are sent and received during
+@ref{CfgOnlineDeadline, onlinedeadline} duration, then close the
+connection. There is no explicit indication that session is over.
+
+@item If no packets are received during two minutes (two PING timeouts),
+then close the connection.

 
 @end enumerate
 
 @end enumerate