Add various documentation indices

[nncp.git] / doc / sp.texi

diff --git a/doc/sp.texi b/doc/sp.texi
index d6be2d927f7977aca6b750a2c22b2152ea6b1179..36f5cc794d32ced78508a4e99c718fa45cfea69a 100644 (file)
--- a/doc/sp.texi
+++ b/doc/sp.texi
@@ -1,10 +1,14 @@
 @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.
 
+@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
@@ -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.
 
+@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
@@ -49,6 +60,7 @@ just an unsigned integer telling what body structure follows.
 
 @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
@@ -61,6 +73,17 @@ just an unsigned integer telling what body structure follows.
 +------+
 @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.
 
@@ -83,6 +106,7 @@ just an unsigned integer telling what body structure follows.
         Unique file identifier, its checksum
     @end multitable
 
+@cindex FREQ payload
 @item FREQ
     File transmission request. Ask remote side to queue the file for
     transmission.
@@ -103,6 +127,7 @@ just an unsigned integer telling what body structure follows.
         Offset from which remote side must transmit the file
     @end multitable
 
+@cindex FILE payload
 @item FILE
     Chunk of file.
 
@@ -125,6 +150,7 @@ just an unsigned integer telling what body structure follows.
         Chunk of file itself
     @end multitable
 
+@cindex DONE payload
 @item DONE
     Signal remote side that we have successfully downloaded the file.
 
@@ -145,7 +171,7 @@ just an unsigned integer telling what body structure follows.
 
 Typical peer's behaviour is following:
 
-@verbatiminclude sp.utxt
+@verbatiminclude sp.plantuml.txt
 
 @enumerate
 @item Perform @emph{Noise-IK} handshake:
@@ -173,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.
-    @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
@@ -195,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.
+
 @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