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