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 XDR envelope:
+are sent inside @url{https://tools.ietf.org/html/rfc4506, XDR} envelope:
@verbatim
+-----------------+
@headitem @tab XDR type @tab Value
@item Magic number @tab
8-byte, fixed length opaque data @tab
- @code{NNCPS0x10x00x00}
+ @verb{|N N C P S 0x00 0x00 0x01|}
@item Payload @tab
variable length opaque data @tab
Noise packet itself
@end multitable
-Peers static keys are specified as @ref{Configuration, @code{noisepub}}
+Peers static keys are specified as @ref{Configuration, @emph{noisepub}}
configuration entry.
-Payload inside Noise packets has maximum size of @code{65 KiB - 256 B =
+Payload inside Noise packets has maximum size of @emph{64 KiB - 256 B =
65280 B}. It is sent immediately in the first message by each side. The
very first payload (that is carried inside handshake messages) is always
-padded to the maximum size with @code{HALT} packets (read below), for
-hiding actual number of @code{INFO} packets (number of files available
+padded to the maximum size with @emph{HALT} packets (read below), for
+hiding actual number of @emph{INFO} packets (number of files available
for transmission).
Each SP payload is a concatenation of SP packets. Each packet has
XDR-encoded header and then corresponding XDR-encoded body. Header is
just an unsigned integer telling what body structure follows.
-@table @code
+@table @emph
@item HALT
Stop file transmission, empty sending queue on the remote side.
- Actually @code{HALT} packet does not have any body, only the header
+ 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
@item INFO
Information about the file we have for transmission.
@verbatim
-+--------------------+
-| NICE | SIZE | HASH |
-+--------------------+
++------+--------------------+
+| INFO | NICE | SIZE | HASH |
++------+--------------------+
@end verbatim
@multitable @columnfractions 0.2 0.3 0.5
@headitem @tab XDR type @tab Value
File transmission request. Ask remote side to queue the file for
transmission.
@verbatim
-+---------------+
-| HASH | OFFSET |
-+---------------+
++------+---------------+
+| FREQ | HASH | OFFSET |
++------+---------------+
@end verbatim
@multitable @columnfractions 0.2 0.3 0.5
@headitem @tab XDR type @tab Value
@item FILE
Chunk of file.
@verbatim
-+-------------------------+
-| HASH | OFFSET | PAYLOAD |
-+-------------------------+
++------+-------------------------+
+| FILE | HASH | OFFSET | PAYLOAD |
++------+-------------------------+
@end verbatim
@multitable @columnfractions 0.2 0.3 0.5
@headitem @tab XDR type @tab Value
@item DONE
Signal remote side that we have successfully downloaded the file.
@verbatim
-+------+
-| HASH |
-+------+
++------+------+
+| DONE | HASH |
++------+------+
@end verbatim
@multitable @columnfractions 0.2 0.3 0.5
@headitem @tab XDR type @tab Value
@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{CfgOnlineDeadline,
+onlinedeadline} duration, then close the connection. There is no
+explicit indication that session is over.
+@end enumerate