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 are sent inside 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{|NNCPS0x00x00x01|}
  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{65 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 @verbatim
  58 +------+
  59 | HALT |
  60 +------+
  61 @end verbatim
  62
  63 @item INFO
  64     Information about the file we have for transmission.
  65 @verbatim
  66 +------+--------------------+
  67 | INFO | NICE | SIZE | HASH |
  68 +------+--------------------+
  69 @end verbatim
  70     @multitable @columnfractions 0.2 0.3 0.5
  71     @headitem  @tab XDR type @tab Value
  72     @item Niceness @tab
  73         unsigned integer @tab
  74         1-255, file niceness level
  75     @item Size @tab
  76         unsigned hyper integer @tab
  77         File size
  78     @item Hash @tab
  79         32-byte, fixed length opaque data @tab
  80         Unique file identifier, its checksum
  81     @end multitable
  82
  83 @item FREQ
  84     File transmission request. Ask remote side to queue the file for
  85     transmission.
  86 @verbatim
  87 +------+---------------+
  88 | FREQ | HASH | OFFSET |
  89 +------+---------------+
  90 @end verbatim
  91     @multitable @columnfractions 0.2 0.3 0.5
  92     @headitem  @tab XDR type @tab Value
  93     @item Hash @tab
  94         32-byte, fixed length opaque data @tab
  95         Unique file identifier, its checksum
  96     @item Offset @tab
  97         unsigned hyper integer @tab
  98         Offset from which remote side must transmit the file
  99     @end multitable
 100
 101 @item FILE
 102     Chunk of file.
 103 @verbatim
 104 +------+-------------------------+
 105 | FILE | HASH | OFFSET | PAYLOAD |
 106 +------+-------------------------+
 107 @end verbatim
 108     @multitable @columnfractions 0.2 0.3 0.5
 109     @headitem  @tab XDR type @tab Value
 110     @item Hash @tab
 111         32-byte, fixed length opaque data @tab
 112         Unique file identifier, its checksum
 113     @item Offset @tab
 114         unsigned hyper integer @tab
 115         Offset from which transmission goes
 116     @item Payload @tab
 117         variable length opaque data @tab
 118         Chunk of file itself
 119     @end multitable
 120
 121 @item DONE
 122     Signal remote side that we have successfully downloaded the file.
 123 @verbatim
 124 +------+------+
 125 | DONE | HASH |
 126 +------+------+
 127 @end verbatim
 128     @multitable @columnfractions 0.2 0.3 0.5
 129     @headitem  @tab XDR type @tab Value
 130     @item Hash @tab
 131         32-byte, fixed length opaque data @tab
 132         Unique file identifier, its checksum
 133     @end multitable
 134
 135 @end table
 136
 137 Typical peers behaviour is following:
 138
 139 @enumerate
 140 @item Perform Noise-IK handshake.
 141 @item When remote peer's identity is known (by definition for initiator
 142 and after receiving first packet for responser (however it is not
 143 authenticated yet)), then collect all @emph{tx}-related files
 144 information and prepare payload packets with all that @emph{INFO}s.
 145 @item Pad the very first payload packet (that is sent with first Noise
 146 handshake message) with @emph{HALT}s to the maximal size.
 147 @item Send all queued payload packets.
 148 @item When @emph{INFO} packet received, check that is has an acceptable
 149 niceness level (skip if not), check if file's @file{.part} exists and
 150 queue @emph{FREQ} outgoing packet (with corresponding offset if
 151 required).
 152 @item When @emph{FREQ} packet received, append it to current sending
 153 queue. Sending queue contains files with offsets that are needed to be
 154 sent.
 155 @item While sending queue is not empty, send @emph{FILE} packet until
 156 queue's head is not fully sent. @emph{FREQ} can contain offset equal to
 157 size -- anyway sent @emph{FILE} packet with an empty payload.
 158 @item When @emph{FILE} packet received, check if it is not fully
 159 downloaded (comparing to @emph{INFO}'s packet information). If so, then
 160 run background integrity checker on it. If check is succeeded, then
 161 delete @file{.part} suffix from file's name and send @emph{DONE} packet.
 162 @item When @emph{DONE} packet received, delete corresponding file.
 163 @item When @emph{HALT} packet received, empty file sending queue.
 164 @item @emph{FILE} sending is performed only if no other outgoing packets
 165 are queued.
 166 @item Each second node check are there any new @emph{tx} packets
 167 appeared and queues corresponding @emph{INFO} packets.
 168 @item If no packets are sent and received during @ref{Onlinedeadline,
 169 onlinedeadline} duration, then close the connection. There is no
 170 explicit indication that session is over.
 171 @end enumerate