doc/sp.texi

   1 @node Sync
   2 @unnumbered Synchronization protocol
   3
   4 So-called synchronization protocol (SP) is used in current TCP daemon's
   5 implementation. It is used for synchronizing @ref{Spool, spool}
   6 directory contents between two nodes.
   7
   8 It is aimed to be very simple and effective. It uses reliable transport
   9 like TCP connections. It must be effective both on single-duplex and
  10 full-duplex links: for example satellites have very high throughput but
  11 high-delay links, so acknowledging of each received packet, like
  12 @url{https://en.wikipedia.org/wiki/XMODEM, XMODEM} does, causes
  13 unacceptable performance degradation.
  14
  15 Internally it uses various timeouts and deadlines. One of them used
  16 extensively is 10 seconds default deadline timeout. You can override it
  17 with @env{$NNCPDEADLINE} environment variable, that could be useful with
  18 very high delay links.
  19
  20 SP works on top of
  21 @url{http://noiseprotocol.org/noise.html#interactive-patterns,
  22 @code{Noise_IK_25519_ChaChaPoly_BLAKE2b}} protocol. Each Noise packet
  23 is sent inside an @url{https://tools.ietf.org/html/rfc4506, XDR} envelope:
  24
  25 @verbatim
  26 +-----------------+
  27 | MAGIC | PAYLOAD |
  28 +-----------------+
  29 @end verbatim
  30
  31 @multitable @columnfractions 0.2 0.3 0.5
  32 @headitem @tab XDR type @tab Value
  33 @item Magic number @tab
  34     8-byte, fixed length opaque data @tab
  35     @verb{|N N C P S 0x00 0x00 0x01|}
  36 @item Payload @tab
  37     variable length opaque data @tab
  38     Noise packet itself
  39 @end multitable
  40
  41 Peers static keys are specified as @ref{Configuration, @emph{noisepub}}
  42 configuration entry.
  43
  44 Payload inside Noise packets has maximum size of @emph{64 KiB - 256 B =
  45 65280 B}. It is sent immediately in the first message by each side. The
  46 very first payload (that is carried inside handshake messages) is always
  47 padded to the maximum size with @emph{HALT} packets (read below), for
  48 hiding actual number of @emph{INFO} packets (number of files available
  49 for transmission).
  50
  51 Each SP payload is a concatenation of SP packets. Each packet has
  52 XDR-encoded header and then corresponding XDR-encoded body. Header is
  53 just an unsigned integer telling what body structure follows.
  54
  55 @table @emph
  56
  57 @item HALT
  58     Stop file transmission, empty sending queue on the remote side.
  59     Actually @emph{HALT} packet does not have any body, only the header
  60     with the type. It is also used in the first payload for padding to
  61     the maximum size.
  62
  63 @verbatim
  64 +------+
  65 | HALT |
  66 +------+
  67 @end verbatim
  68
  69 @item PING
  70     Dummy packet only used for determining workability of the connection.
  71
  72 @verbatim
  73 +------+
  74 | PING |
  75 +------+
  76 @end verbatim
  77
  78 @item INFO
  79     Information about the file we have for transmission.
  80
  81 @verbatim
  82 +------+--------------------+
  83 | INFO | NICE | SIZE | HASH |
  84 +------+--------------------+
  85 @end verbatim
  86
  87     @multitable @columnfractions 0.2 0.3 0.5
  88     @headitem @tab XDR type @tab Value
  89     @item Niceness @tab
  90         unsigned integer @tab
  91         1-255, file niceness level
  92     @item Size @tab
  93         unsigned hyper integer @tab
  94         File size
  95     @item Hash @tab
  96         32-byte, fixed length opaque data @tab
  97         Unique file identifier, its checksum
  98     @end multitable
  99
 100 @item FREQ
 101     File transmission request. Ask remote side to queue the file for
 102     transmission.
 103
 104 @verbatim
 105 +------+---------------+
 106 | FREQ | HASH | OFFSET |
 107 +------+---------------+
 108 @end verbatim
 109
 110     @multitable @columnfractions 0.2 0.3 0.5
 111     @headitem @tab XDR type @tab Value
 112     @item Hash @tab
 113         32-byte, fixed length opaque data @tab
 114         Unique file identifier, its checksum
 115     @item Offset @tab
 116         unsigned hyper integer @tab
 117         Offset from which remote side must transmit the file
 118     @end multitable
 119
 120 @item FILE
 121     Chunk of file.
 122
 123 @verbatim
 124 +------+-------------------------+
 125 | FILE | HASH | OFFSET | PAYLOAD |
 126 +------+-------------------------+
 127 @end verbatim
 128
 129     @multitable @columnfractions 0.2 0.3 0.5
 130     @headitem @tab XDR type @tab Value
 131     @item Hash @tab
 132         32-byte, fixed length opaque data @tab
 133         Unique file identifier, its checksum
 134     @item Offset @tab
 135         unsigned hyper integer @tab
 136         Offset from which transmission goes
 137     @item Payload @tab
 138         variable length opaque data @tab
 139         Chunk of file itself
 140     @end multitable
 141
 142 @item DONE
 143     Signal remote side that we have successfully downloaded the file.
 144
 145 @verbatim
 146 +------+------+
 147 | DONE | HASH |
 148 +------+------+
 149 @end verbatim
 150
 151     @multitable @columnfractions 0.2 0.3 0.5
 152     @headitem @tab XDR type @tab Value
 153     @item Hash @tab
 154         32-byte, fixed length opaque data @tab
 155         Unique file identifier, its checksum
 156     @end multitable
 157
 158 @end table
 159
 160 Typical peer's behaviour is following:
 161
 162 @verbatiminclude sp.plantuml.txt
 163
 164 @enumerate
 165 @item Perform @emph{Noise-IK} handshake:
 166
 167     @table @strong
 168     @item Initiator
 169     Collects all @emph{tx}-related files information and prepares
 170     payload filled with @emph{INFO}s for including in the @strong{first}
 171     handshake message.
 172     @item Responder
 173     After receiving the first handshake message, it gains remote
 174     identity knowledge and similarly prepares the payload for including
 175     in the @strong{second} handshake message.
 176     @end table
 177
 178     All payloads are padded to maximal message size with @emph{HALT}s.
 179
 180 @item If queued @emph{INFO}s are not sent completely in handshake
 181 payloads, then send all of remaining in the transport stage.
 182
 183 @item When @emph{INFO} packet received:
 184
 185     @itemize
 186     @item Check that it has an acceptable niceness level.
 187     Ignore it if it is too nice.
 188     @item If already downloaded file exists, then queue @emph{DONE}
 189     sending.
 190     @item If @file{seen/XXX} exists, then queue @emph{DONE} sending.
 191     @item If @file{.part} exists, then queue @emph{FREQ} sending with
 192     corresponding offset.
 193     @end itemize
 194
 195 @item When @emph{FREQ} packet received, insert it to current sending
 196 queue with niceness level sort: higher priority packets will be sent
 197 first. Sending queue contains files with offsets that are needed to be
 198 sent.
 199
 200 @item While sending queue is not empty, send @emph{FILE} packets.
 201 @emph{FREQ} could contain offset equal to size -- anyway sent
 202 @emph{FILE} packet with an empty payload. @emph{FILE} sending is
 203 performed only if no other outgoing packets are queued: @emph{INFO}s
 204 have higher priority.
 205
 206 @item When @emph{FILE} packet received, check if it is completely
 207 downloaded (comparing to @emph{INFO}'s packet size information). If so,
 208 then run background integrity checker on it. If check succeeds, then
 209 delete @file{.part} suffix from file's name and send @emph{DONE} packet.
 210
 211 @item When @emph{DONE} packet received, delete corresponding file.
 212
 213 @item When @emph{HALT} packet received, empty file sending queue.
 214
 215 @item Each second, node checks: are there any new @emph{tx} packets
 216 appeared and queues corresponding @emph{INFO} packets.
 217
 218 @item Each minute, if no packets were sent, node sends @emph{PING}
 219 packet.
 220
 221 @item If no non-PING packets are sent and received during
 222 @ref{CfgOnlineDeadline, onlinedeadline} duration, then close the
 223 connection. There is no explicit indication that session is over.
 224
 225 @item If no packets are received during two minutes (two PING timeouts),
 226 then close the connection.
 227
 228 @end enumerate