X-Git-Url: http://www.git.cypherpunks.ru/?p=nncp.git;a=blobdiff_plain;f=doc%2Fsp.texi;h=36f5cc794d32ced78508a4e99c718fa45cfea69a;hp=f57a489958105e7a16623380438f6262e84b8a9c;hb=203dfe36da7adf2b3089e4fa4017a67409cbad70;hpb=71fef454f38565b87e8697f86b071a57b3a3c379

diff --git a/doc/sp.texi b/doc/sp.texi
index f57a489..36f5cc7 100644
--- 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,10 +16,17 @@ 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
-are sent inside @url{https://tools.ietf.org/html/rfc4506, XDR} envelope:
+is sent inside an @url{https://tools.ietf.org/html/rfc4506, XDR} envelope:
 
 @verbatim
 +-----------------+
@@ -24,7 +35,7 @@ are sent inside @url{https://tools.ietf.org/html/rfc4506, XDR} envelope:
 @end verbatim
 
 @multitable @columnfractions 0.2 0.3 0.5
-@headitem  @tab XDR type @tab Value
+@headitem @tab XDR type @tab Value
 @item Magic number @tab
     8-byte, fixed length opaque data @tab
     @verb{|N N C P S 0x00 0x00 0x01|}
@@ -49,26 +60,41 @@ 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
     with the type. It is also used in the first payload for padding to
     the maximum size.
+
 @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.
+
 @verbatim
 +------+--------------------+
 | INFO | NICE | SIZE | HASH |
 +------+--------------------+
 @end verbatim
+
     @multitable @columnfractions 0.2 0.3 0.5
-    @headitem  @tab XDR type @tab Value
+    @headitem @tab XDR type @tab Value
     @item Niceness @tab
         unsigned integer @tab
         1-255, file niceness level
@@ -80,16 +106,19 @@ 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.
+
 @verbatim
 +------+---------------+
 | FREQ | HASH | OFFSET |
 +------+---------------+
 @end verbatim
+
     @multitable @columnfractions 0.2 0.3 0.5
-    @headitem  @tab XDR type @tab Value
+    @headitem @tab XDR type @tab Value
     @item Hash @tab
         32-byte, fixed length opaque data @tab
         Unique file identifier, its checksum
@@ -98,15 +127,18 @@ 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.
+
 @verbatim
 +------+-------------------------+
 | FILE | HASH | OFFSET | PAYLOAD |
 +------+-------------------------+
 @end verbatim
+
     @multitable @columnfractions 0.2 0.3 0.5
-    @headitem  @tab XDR type @tab Value
+    @headitem @tab XDR type @tab Value
     @item Hash @tab
         32-byte, fixed length opaque data @tab
         Unique file identifier, its checksum
@@ -118,15 +150,18 @@ 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.
+
 @verbatim
 +------+------+
 | DONE | HASH |
 +------+------+
 @end verbatim
+
     @multitable @columnfractions 0.2 0.3 0.5
-    @headitem  @tab XDR type @tab Value
+    @headitem @tab XDR type @tab Value
     @item Hash @tab
         32-byte, fixed length opaque data @tab
         Unique file identifier, its checksum
@@ -134,38 +169,72 @@ just an unsigned integer telling what body structure follows.
 
 @end table
 
-Typical peers behaviour is following:
+Typical peer's behaviour is following:
+
+@verbatiminclude sp.plantuml.txt
 
 @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.
-@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.
+
 @item When @emph{DONE} packet received, delete corresponding file.
+
 @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 check are there any new @emph{tx} 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