Add various documentation indices

[nncp.git] / doc / sp.texi

diff --git a/doc/sp.texi b/doc/sp.texi
index 919cca108c2104bc58a63f06bb70465685a114b1..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,36 +171,70 @@ just an unsigned integer telling what body structure follows.
 
 Typical peer's behaviour is following:
 
 
 Typical peer's behaviour is following:
 

+@verbatiminclude sp.plantuml.txt
+

 @enumerate
 @enumerate

-@item Perform Noise-IK handshake.
-@item When remote peer's identity is known (by definition for initiator
-and after receiving first packet for responser (however it is not
-authenticated yet)), then collect all @emph{tx}-related files
-information and prepare payload packets with all that @emph{INFO}s.
-@item Pad the very first payload packet (that is sent with first Noise
-handshake message) with @emph{HALT}s to the maximal size.
-@item Send all queued payload packets.
-@item When @emph{INFO} packet received, check that is has an acceptable
-niceness level (skip if not), check if file's @file{.part} exists and
-queue @emph{FREQ} outgoing packet (with corresponding offset if
-required).
-@item When @emph{FREQ} packet received, append it to current sending
-queue. Sending queue contains files with offsets that are needed to be
+@item Perform @emph{Noise-IK} handshake:
+
+    @table @strong
+    @item Initiator
+    Collects all @emph{tx}-related files information and prepares
+    payload filled with @emph{INFO}s for including in the @strong{first}
+    handshake message.
+    @item Responder
+    After receiving the first handshake message, it gains remote
+    identity knowledge and similarly prepares the payload for including
+    in the @strong{second} handshake message.
+    @end table
+
+    All payloads are padded to maximal message size with @emph{HALT}s.
+
+@item If queued @emph{INFO}s are not sent completely in handshake
+payloads, then send all of remaining in the transport stage.
+
+@item When @emph{INFO} packet received:
+
+    @itemize
+    @item Check that it has an acceptable niceness level.
+    Ignore it if it is too nice.
+    @item If already downloaded file 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 When @emph{FREQ} packet received, insert it to current sending
+queue with niceness level sort: higher priority packets will be sent
+first. Sending queue contains files with offsets that are needed to be

 sent.
 sent.

-@item While sending queue is not empty, send @emph{FILE} packet until
-queue's head is not fully sent. @emph{FREQ} can contain offset equal to
-size -- anyway sent @emph{FILE} packet with an empty payload.
-@item When @emph{FILE} packet received, check if it is not fully
-downloaded (comparing to @emph{INFO}'s packet information). If so, then
-run background integrity checker on it. If check is succeeded, then
+
+@item While sending queue is not empty, send @emph{FILE} packets.
+@emph{FREQ} could contain offset equal to size -- anyway sent
+@emph{FILE} packet with an empty payload. @emph{FILE} sending is
+performed only if no other outgoing packets are queued: @emph{INFO}s
+have higher priority.
+
+@item When @emph{FILE} packet received, check if it is completely
+downloaded (comparing to @emph{INFO}'s packet size information). If so,
+then run background integrity checker on it. If check succeeds, then

 delete @file{.part} suffix from file's name and send @emph{DONE} packet.
 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{DONE} packet received, delete corresponding file.

+

 @item When @emph{HALT} packet received, empty file sending queue.
 @item When @emph{HALT} packet received, empty file sending queue.

-@item @emph{FILE} sending is performed only if no other outgoing packets
-are queued.
+

 @item Each second, node checks: are there any new @emph{tx} packets
 appeared and queues corresponding @emph{INFO} packets.
 @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