From c6bc491ffaf8c730d3f815d489c7a50894cd3507 Mon Sep 17 00:00:00 2001
From: Sergey Matveev <stargrave@stargrave.org>
Date: Sun, 15 Jan 2017 11:51:56 +0300
Subject: [PATCH] Document onlinedeadline

---
 doc/cfg.texi  | 13 +++++++++++++
 doc/cmds.texi |  5 ++++-
 doc/sp.texi   | 38 +++++++++++++++++++++++++++++++++++++-
 3 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/doc/cfg.texi b/doc/cfg.texi
index 036d5d4..e930e27 100644
--- a/doc/cfg.texi
+++ b/doc/cfg.texi
@@ -35,6 +35,7 @@ neigh:
     noisepub: UBM5K...VI42A
     sendmail: ["/bin/sh", "-c", "false"]
     incoming: /home/alice/incoming
+    onlinedeadline: 3600
     addrs:
       lan: "[fe80::1234%igb0]:5400"
       internet: alice.com:3389
@@ -72,6 +73,7 @@ Except for @emph{id}, @emph{exchpub} and @emph{signpub} each neighbour
 node has the following fields:
 
 @table @strong
+
 @item noisepub
 If present, then node can be online called using @ref{Sync,
 synchronization protocol}. Contains authentication public key.
@@ -100,4 +102,15 @@ human-readable name of the link/address. Values are @verb{|addr:port|}
 pairs pointing to @ref{nncp-daemon}'s listening instance. May be omitted
 if either no direct connection exists, or @ref{nncp-call} is used with
 forced address specifying.
+
+@anchor{Onlinedeadline}
+@item onlinedeadline
+Online connection deadline of node inactivity in seconds. It is the time
+connection considered dead after not receiving/sending any packets and
+node must disconnect. By default it is set to 10 seconds -- that means
+that disconnecting after 10 seconds when no packets received and
+transmitted. This can be set to rather high values to keep connection
+alive (to reduce handshake overhead and delays), wait for appearing
+packets ready to send and notifying remote side about their appearance.
+
 @end table
diff --git a/doc/cmds.texi b/doc/cmds.texi
index 51944ac..c5191f3 100644
--- a/doc/cmds.texi
+++ b/doc/cmds.texi
@@ -34,7 +34,7 @@ Nearly all commands have the following common options:
 @section nncp-call
 
 @verbatim
-% nncp-call [options] [-rx|-tx] NODE[:ADDR] [FORCEADDR]
+% nncp-call [options] [-onlinedeadline INT] [-rx|-tx] NODE[:ADDR] [FORCEADDR]
 @end verbatim
 
 Call (connect to) specified @option{NODE} and run @ref{Sync,
@@ -48,6 +48,9 @@ If @option{-rx} option is specified then only inbound packets transmission
 is performed. If @option{-tx} option is specified, then only outbound
 transmission is performed.
 
+@option{-onlinedeadline} overrides @ref{Onlinedeadline,
+@emph{onlinedeadline}} configuration option.
+
 Each @option{NODE} can contain several uniquely identified
 @option{ADDR}esses in @ref{Configuration, configuration} file. If you do
 not specify the exact one, then all will be tried until the first
diff --git a/doc/sp.texi b/doc/sp.texi
index ab8390e..21e7b9e 100644
--- a/doc/sp.texi
+++ b/doc/sp.texi
@@ -14,7 +14,7 @@ unacceptable performance degradation.
 
 SP works on top of
 @url{http://noiseprotocol.org/noise.html#interactive-patterns,
-@verb{|Noise_IK_25519_ChaChaPoly_BLAKE2b|}} protocol. Each Noise packet
+@code{Noise_IK_25519_ChaChaPoly_BLAKE2b}} protocol. Each Noise packet
 are sent inside XDR envelope:
 
 @verbatim
@@ -133,3 +133,39 @@ just an unsigned integer telling what body structure follows.
     @end multitable
 
 @end table
+
+Typical peers behaviour is following:
+
+@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
+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
+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
+appeared and queues corresponding @emph{INFO} packets.
+@item If no packets are sent and received during @ref{Onlinedeadline,
+onlinedeadline} duration, then close the connection. There is no
+explicit indication that session is over.
+@end enumerate
-- 
2.44.0